refactor(plugin): independent per-load registration with marker-based bootstrap idempotency (#352)

* refactor(plugin): independent per-load registration with marker-based bootstrap idempotency

Each call to SystematicPlugin now runs initializePlugin independently and
returns its own hooks surface. With multiple OpenCode plugin sources
configured (project + user config), each source gets its own systematic_skill
tool, its own config handler, and its own chat.system.transform closure.
hasLoggedInit moves into per-init closure state, so the process emits N init
log lines for N registrations — honest signal that init ran N times.

Bootstrap content idempotency is now enforced at injection time, not init
time. applyBootstrapContent walks output.system for any prior
<SYSTEMATIC_WORKFLOWS>...</SYSTEMATIC_WORKFLOWS> block (non-greedy regex) and
replaces it in-place; missing-block falls through to append. Under OpenCode's
verified FIFO hook iteration, the last transform to run owns the final block
— most-recently-registered plugin wins, which matches the project-after-user
load order developers expect.

This reverts the plugInOnce singleton from PR #335, which turned out to be
over-correction. OpenCode registers tools per-source even with a shared hooks
reference, so the singleton's init-dedup had no visible effect on the TUI
tool catalog — what it did do in dev setups was silently collapse all loads
onto whichever ran first, shadowing later sources.

Also removes _resetPluginSingleton from the integration test setup; the
singleton itself is deleted in a follow-up commit.

12 new behavior tests cover marker-replacement in every slot, non-greedy
boundary, multi-block edge cases, per-invocation distinct references, and
the cross-registration integration scenario.

* refactor(plugin): delete plugin-singleton module after factory revert

The plugInOnce abstraction and its test file are no longer reachable —
src/index.ts stopped importing them in the prior commit, and the consumer
test files (plugin.test.ts and opencode.test.ts) dropped the
_resetPluginSingleton reset calls.

Deletes 227 lines of now-dead infrastructure: the singleton helper, its
five test cases, and the module-level exports. The architectural rationale
lives in docs/brainstorms/2026-05-10-multi-load-plugin-registration-requirements.md
and the implementation plan at docs/plans/2026-05-10-002-refactor-multi-load-plugin-registration-plan.md.

* docs: sync AGENTS hierarchy and PR #335 solution after singleton removal

Updates module count in AGENTS.md and src/lib/AGENTS.md from 16/14 to 15
(post-deletion of plugin-singleton.ts). Appends a 2026-05-10 follow-up
section to the PR #335 solution doc noting the singleton was removed and
documenting marker-based idempotency as the current correctness contract.

Also commits the implementation plan with all four units marked complete.
The plan was untracked locally during execution per project convention;
landing it here gives the architectural inversion a visible paper trail.

* fix(plugin): replace bootstrap marker regex with linear scan to close ReDoS

The non-greedy regex /<SYSTEMATIC_WORKFLOWS>[\s\S]*?<\/SYSTEMATIC_WORKFLOWS>/
was flagged by CodeQL as polynomial-time on uncontrolled input — when the
opening tag repeats and the closing tag is absent, the engine backtracks
through every prefix. With per-load registration now letting any plugin
source contribute system prompt fragments, this regex sees content the
plugin itself didn't author.

Replaces the regex with a small indexOf/slice helper. Fixed literal
delimiters never needed regex; the linear scan is provably immune to ReDoS
and unchanged in behavior for the existing seven marker-replacement tests.
Adds a regression test that runs the helper against 10000 repeated opening
markers with no closing tag and asserts completion in well under 1s.

Closes CodeQL alerts #42 and #43.

Author: marcusrbrown

AGENTS.md

@@ -46,7 +46,7 @@ systematic/
 ├── src/
 │   ├── index.ts          # Plugin entry (default export)
 │   ├── cli.ts            # CLI entry (list/convert/config commands)
-│   └── lib/              # 16 core modules (see src/lib/AGENTS.md)
+│   └── lib/              # 15 core modules (see src/lib/AGENTS.md)
 ├── skills/               # 45 bundled skills (SKILL.md format)
 ├── agents/               # 51 bundled agents (6 categories: design/docs/document-review/research/review/workflow)
 ├── docs/                 # Starlight docs workspace (see docs/AGENTS.md)

docs/plans/2026-05-10-002-refactor-multi-load-plugin-registration-plan.md

@@ -142,3 +142,9 @@ const SystematicPlugin: Plugin = async (input) => {
 - Plan document: `docs/plans/2026-05-01-001-fix-idempotent-plugin-registration-plan.md`
 - Adjacent upstream pattern (idempotence under cache-busting hook injection): <https://github.com/alvinunreal/oh-my-opencode-slim/issues/415>
 - Precedent that initially appeared transferable but used the insufficient whole-hooks pattern: `opencode-copilot-delegate/src/runtime/plugin-singleton.ts`
+
+## 2026-05-10 follow-up: singleton removed
+
+The `plugInOnce` singleton introduced in PR #335 was reverted in a later PR. The duplicate-tool-entry concern that motivated the singleton turned out to be a non-issue — OpenCode registers tools per-source regardless of whether the hooks reference is shared, so the singleton's deduplication of the init work had no visible effect on the TUI tool catalog. What it DID do in dev setups with multiple plugin sources was collapse all loads onto whichever ran first, silently shadowing later sources.
+
+The real correctness contract is now marker-based idempotency in `applyBootstrapContent`: each registration applies its bootstrap content by walking `output.system` for any prior `<SYSTEMATIC_WORKFLOWS>...</SYSTEMATIC_WORKFLOWS>` block and replacing it in-place. Under OpenCode's FIFO hook iteration, the last transform to run owns the final block — most-recently-registered plugin wins. The architectural rationale is captured in `docs/brainstorms/2026-05-10-multi-load-plugin-registration-requirements.md` and the implementation plan at `docs/plans/2026-05-10-002-refactor-multi-load-plugin-registration-plan.md`.

docs/solutions/integration-issues/opencode-plugin-factory-duplicate-registration-2026-05-04.md

@@ -8,7 +8,6 @@ import {
 } from './lib/bootstrap.js'
 import { loadConfig } from './lib/config.js'
 import { createConfigHandler } from './lib/config-handler.js'
-import { plugInOnce } from './lib/plugin-singleton.js'
 import { createSkillTool } from './lib/skill-tool.js'
 
 const __dirname = path.dirname(fileURLToPath(import.meta.url))
@@ -18,12 +17,36 @@ const bundledSkillsDir = path.join(packageRoot, 'skills')
 const bundledAgentsDir = path.join(packageRoot, 'agents')
 const bundledCommandsDir = path.join(packageRoot, 'commands')
 const packageJsonPath = path.join(packageRoot, 'package.json')
-let hasLoggedInit = false
 
-const applyBootstrapContent = (
+const BOOTSTRAP_MARKER_OPEN = '<SYSTEMATIC_WORKFLOWS>'
+const BOOTSTRAP_MARKER_CLOSE = '</SYSTEMATIC_WORKFLOWS>'
+
+const findBootstrapMarkerBlock = (
+  entry: string,
+): { start: number; end: number } | null => {
+  const start = entry.indexOf(BOOTSTRAP_MARKER_OPEN)
+  if (start === -1) return null
+  const closeStart = entry.indexOf(
+    BOOTSTRAP_MARKER_CLOSE,
+    start + BOOTSTRAP_MARKER_OPEN.length,
+  )
+  if (closeStart === -1) return null
+  return { start, end: closeStart + BOOTSTRAP_MARKER_CLOSE.length }
+}
+
+export const applyBootstrapContent = (
   output: { system: string[] },
   content: string,
 ): void => {
+  for (let i = 0; i < output.system.length; i++) {
+    const entry = output.system[i]
+    const block = findBootstrapMarkerBlock(entry)
+    if (block !== null) {
+      output.system[i] =
+        entry.slice(0, block.start) + content + entry.slice(block.end)
+      return
+    }
+  }
   if (output.system.length > 0) {
     output.system[output.system.length - 1] += `\n\n${content}`
   } else {
@@ -42,15 +65,8 @@ const getPackageVersion = (): string => {
   }
 }
 
-/**
- * Build the plugin hook surface for a single OpenCode plugin invocation.
- *
- * Extracted into a named initializer so the default export can wrap it through
- * `plugInOnce(...)`, making duplicate factory calls in the same process
- * converge on the same hooks promise. See `src/lib/plugin-singleton.ts` for
- * the duplicate-load justification.
- */
 const initializePlugin = async ({ client, directory }: PluginInput) => {
+  let hasLoggedInit = false
   const config = loadConfig(directory)
   // Snapshot bootstrap once per plugin init so the cached system prefix stays
   // stable across requests. Custom bootstrap file edits take effect on restart.
@@ -129,13 +145,7 @@ const initializePlugin = async ({ client, directory }: PluginInput) => {
 }
 
 const SystematicPlugin: Plugin = async (input) => {
-  const { hooks } = await plugInOnce({
-    doInit: () => initializePlugin(input),
-  })
-  // hooks is the real plugin hook surface on every invocation — first and
-  // duplicate alike. Returning it unconditionally keeps every configured
-  // plugin source functional instead of suppressing duplicates with `{}`.
-  return hooks
+  return initializePlugin(input)
 }
 
 export default SystematicPlugin

src/index.ts

@@ -1,6 +1,6 @@
 # src/lib — Core Implementation
 
-14 modules implementing plugin logic: discovery, conversion, config, schema validation, and tool registration.
+15 modules implementing plugin logic: discovery, conversion, config, schema validation, and tool registration.
 
 ## Data Flow
 

src/lib/AGENTS.md

@@ -4,7 +4,6 @@ import os from 'node:os'
 import path from 'node:path'
 import type { Config, PluginInput } from '@opencode-ai/plugin'
 import SystematicPlugin from '../../src/index.js'
-import { _resetPluginSingleton } from '../../src/lib/plugin-singleton.js'
 
 const OPENCODE_AVAILABLE = (() => {
   const result = Bun.spawnSync(['which', 'opencode'])
@@ -109,7 +108,6 @@ describe('SystematicPlugin config hook integration', () => {
   let originalHomedir: typeof os.homedir
 
   beforeEach(() => {
-    _resetPluginSingleton()
     originalHomedir = os.homedir
     tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'systematic-plugin-'))
 
@@ -126,7 +124,6 @@ describe('SystematicPlugin config hook integration', () => {
   afterEach(() => {
     // Restore os.homedir before cleanup so nothing snags on a deleted dir.
     os.homedir = originalHomedir
-    _resetPluginSingleton()
     delete process.env.OPENCODE_CONFIG_DIR
     delete process.env.XDG_DATA_HOME
     fs.rmSync(tempDir, { recursive: true, force: true })