@fro.bot/systematic 3.32.1 → 3.32.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/HARNESSES.md CHANGED
@@ -29,13 +29,15 @@ The citations above (OC-1 to OC-8) describe the v1 adapter. The v2 adapter is th
29
29
 
30
30
  ## OpenCode v2 — Tier 1 shipped adapter
31
31
 
32
- One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.0 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. The floors are a support decision, not a loader limit: the loader probe found that 1.18.28 and v2 2.1.4 load the object default exactly as the floor versions do, and that v2 2.1.4 silently drops a function default while 2.2.0 logs a warning [OC2-LOADER]. v2 2.2.0 is the oldest v2 release the adapter is tested on; whether earlier releases provide every API it uses was not probed.
32
+ One package serves both OpenCode lines. v1 (1.18.29 and later) reads the `plugin` key and calls `server`; v2 (2.2.5 and later) reads `plugins` and calls `setup(ctx)`. Versions below those floors are unsupported, with no shim. Both floors are held in `scripts/opencode-host-pins.json` (`v1Floor`, `v2Floor`), and the `@opencode-ai/plugin` and `@opencode/plugin` peer ranges start at them. The v2 floor is 2.2.5, the version CI runs; no CI job runs an older v2 release, and the `execute.before` hook that the `ce:connect` tool guard relies on has only been observed there.
33
+
34
+ History of the earlier v2 floor: the first v2 floor was 2.2.0, chosen on 2026-10-27 as a support decision rather than a loader limit. The loader probe found that 1.18.28 and v2 2.1.4 load the object default exactly as the floor versions do, and that v2 2.1.4 silently drops a function default while 2.2.0 logs a warning [OC2-LOADER]. 2.2.0 was then the oldest v2 release the adapter was tested on; whether earlier releases provide every API it uses was not probed. The floor moved to 2.2.5 because that is the only v2 release CI runs.
33
35
 
34
36
  Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. The table records which mechanism won and what covers it. "CI" names the job that runs the test; every v2 test below runs in `Host Contract v2 shard N/4` (the `v2` profile in `scripts/host-contract-guard.ts`) against the pinned v2 CLI in `scripts/opencode-host-pins.json`, and the `Host Contract` check aggregates it. Behaviors that no CI test reaches are labeled "local probe, OpenCode 2.2.0, 2026-10-27": they were observed once on a real host, are not re-checked by CI, and the scratch logs behind them are not published.
35
37
 
36
38
  | Probe | Outcome | Mechanism the adapter uses | Evidence |
37
39
  |---|---|---|---|
38
- | Agent creation | Passed | `ctx.agent.transform` with `editor.update(id, fn)` creates a missing agent from a default skeleton. Unknown fields are stripped, so there is no ownership marker; user config applies after every plugin transform and overlays a same-named agent | [OC2-AGENT] |
40
+ | Agent creation | Passed | `ctx.agent.transform` with `editor.update(id, fn)` creates a missing agent from a default skeleton. Unknown fields are stripped, so there is no ownership marker; user config applies after every plugin transform and overlays a same-named agent. `editor.get` returns the live record of an agent an earlier transform defined, `update` mutates it in place and `remove` deletes it; a transform replay starts from an empty state, so a transform never sees its own earlier output. For a read-only agent another plugin defined, the adapter removes the entry and creates it again from the plan, keeping only that entry's `model` | [OC2-AGENT] |
39
41
  | Instruction entries | Passed, with a different trigger | One keyed entry (`systematic.bootstrap`) per session, put from `ctx.session.hook('prompt')`. `session.created` is not used, because the first session after a service start never sees it | [OC2-INSTR] |
40
42
  | Per-kind request hooks | Not needed | The `context` hook is used only to restore truncated skill output; the bootstrap does not use it | [OC2-CTX] |
41
43
  | Permissions | Passed | Ordered `{action, resource, effect}` lists, last match wins; `bash` becomes `shell`, `task` becomes `subagent`, `doom_loop` and `lsp` have no v2 action; a session-level allow overrides an agent's own deny, so see the CN-2 and CN-3 entries for the tool guard | [OC2-PERM] |
@@ -96,7 +98,7 @@ Systematic ships its own search over four kinds of durable output: `docs/solutio
96
98
 
97
99
  Evidence tiers differ by host, and this file does not claim more than the tests do:
98
100
  - **Host-free contract evidence:** one parity test drives each adapter's real entry over one fixture corpus and compares the rendered text; a second runs the built bin under real Node from a directory with no `node_modules` [SR-1].
99
- - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current (1.19.4) lanes, and OpenCode v2 (2.2.0), each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
101
+ - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current (1.19.4) lanes, and OpenCode v2 (the pinned 2.2.5), each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
100
102
  - **Delegated-reach tests:** on OpenCode v1 (floor and current), OpenCode v2 and Pi, a dispatched learnings-researcher child calls `systematic_search` and its result reaches the parent. The child's next model request must carry a tool message that starts `Search "` and names both planted documents, and the parent's final request must carry both paths [SR-5]. These prove reach and plumbing. A scripted model makes the call, so they do not show that a live model chooses to search.
101
103
  - **External search, host-free:** one parity test drives v1, v2, Pi, the CLI, the bin in process and the built bin under Node over one fixture project with a project source and a user source, and compares the rendered `external` text byte for byte. It also covers the not-allowed reply, an allow-list edit between two calls with nothing restarted, and `search.enabled: false` [SR-6].
102
104
  - **External search, delegated:** on OpenCode v2 only, a dispatched learnings-researcher child searches `kind: external` and the planted external path reaches the parent's final answer, with a negative control that withholds the allow entry [SR-6]. Delegated external proofs on OpenCode v1, Pi and Claude Code have not been run, and a scripted model makes the call, so this shows reach and plumbing, not that a live model chooses `external`. The researcher's side of the call is pinned by the wiring contract test [SR-6].
@@ -108,8 +110,8 @@ The `ce:connect` skill dispatches `connections-researcher`, an agent that must n
108
110
 
109
111
  | Host | Version | Mechanism | Support evidence |
110
112
  |---|---|---|---|
111
- | OpenCode v1 | 1.19.5 | `permission:` denies `bash`, `edit`, `webfetch`, `websearch` and `task`, plus `external_directory: allow` so a headless run can read allowed projects outside the working directory. A string `tools:` is dropped by the host's converter and is not relied on. | Observed [CN-1] |
112
- | OpenCode v2 | 2.2.5 | The same denies, plus Systematic's `execute.before` tool guard, which refuses every call from `connections-researcher` outside `read`, `grep`, `glob`, `skill`, `systematic_search` and `systematic_skill`, direct or from inside Code Mode. A session-level allow overrides an agent's own deny on v2, so the guard does the enforcing. | Observed [CN-2][CN-3] |
113
+ | OpenCode v1 | 1.19.5 | `permission:` denies `bash`, `edit`, `webfetch`, `websearch` and `task`, plus `external_directory: allow` so a headless run can read allowed projects outside the working directory. Another config entry of the same agent name keeps only its `model` and `variant`; the denies and prompt are Systematic's. A string `tools:` is dropped by the host's converter and is not relied on. | Observed [CN-1] |
114
+ | OpenCode v2 | 2.2.5 | The same denies, plus Systematic's `execute.before` tool guard, which refuses every call from `connections-researcher` outside `read`, `grep`, `glob`, `skill`, `systematic_search` and `systematic_skill`, direct or from inside Code Mode. A session-level allow overrides an agent's own deny on v2, so the guard does the enforcing. Another plugin's definition of the same agent name is replaced by Systematic's, keeping only its `model`; a definition in the user's own config applies after the plugin transforms and is not replaced. | Observed [CN-2][CN-3] |
113
115
  | Pi | 1.5.0 | The agent's `tools: Read, Grep, Glob` reach the delegate session as read, grep and find. The agent is not one of the curated pi-subagents personas, which carry no tool allowlist. | Observed [CN-4] |
114
116
  | Claude Code | 2.1.319 | The agent declares `tools: Read, Grep, Glob` and `disallowedTools`. The positive `tools` allowlist is what the host enforced in the manual run: the session's tools were Read, Grep and Glob. Upstream reports describe `disallowedTools` not being enforced for plugin subagents, so the allowlist leads. | Observed once, by hand, with a live model [CN-5]. Any other version is unlisted: headless mode refuses it and interactive mode warns and asks consent. |
115
117
 
@@ -233,20 +235,20 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
233
235
  - **OC-6** — `ARCHITECTURE.md:217-223` (invariant 2) and `agents/`.
234
236
  - **OC-7** — `src/lib/asset-plan.ts:274-380` (a model reaches an agent only through `applyAgentOverlays`, `applyAgentOverlayPass` and `applyRoutingModel`, all driven by user-owned overlays); `tests/unit/config-handler.test.ts:1173-1330` (overlay model emitted, `model: null` restores inheritance, native same-name replacement stays model-free).
235
237
  - **OC-8** — `src/lib/opencode-v1.ts:73-79` (v1: the loaded config and `composeBootstrapContent`; the rule is always supplied and the gate lives in `getBootstrapContent`); `src/lib/bootstrap.ts:144-160` (`readWorktreePlacementRule`), `:244-253` (`bootstrap.enabled` and `bootstrap.file` return before the rule is composed), `:265-269` (the rule is omitted when `disabled_skills` contains `git-worktree`), `:279` (placement after the usage template and before the profile), `:291-314` (`composeBootstrapContent`, shared by v1 and v2); `tests/unit/bootstrap.test.ts:1025-1227` (real `loadConfig`: default, `git-worktree` disabled, another skill disabled, qualified name rejected, `bootstrap.enabled: false`, existing and missing `bootstrap.file`); `tests/unit/plugin.test.ts:1473-1610` (real v1 plugin init).
236
- - **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
237
- - **OC2-LOADER** — OpenCode v1 1.18.28, 1.18.29, 1.19.4 and v2 2.1.4, 2.2.0, 2026-10-27. The object default `{id, setup, server}` loads on all five. A v1 host calls `server(input)` and then `setup(ctx)` in the same process, with a reduced context of 9 keys and no `location` or `session`; a v2 host never calls `server`. v2 2.1.4 drops a function default with no log line, and 2.2.0 logs a warning. Tarball config forms fail on v1, so installs go through `npm install <tarball>` and load the installed directory. Local probe for the version comparison. CI covers the 2.2.0 load: CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected"; the v1 loads: CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, `tests/integration/opencode-v1.test.ts` › "packaged plugin loads, warns on a removed disabled_skills name, and exposes a compliant catalog"; the bridge no-op: `tests/unit/opencode-v2.test.ts` › "default export wiring" › "setup does nothing for the reduced context a v1 host passes".
238
- - **OC2-HOST** — Local probe, OpenCode 2.2.0, 2026-10-27. Isolation takes `HOME`, the four `XDG_*` variables, `OPENCODE_CONFIG_DIR` and `TMPDIR`; a managed config under `/Library` on macOS is read and cannot be isolated. One-shot runs use `run --standalone`; the default `run` starts a detached shared service on port 49374. The remote client is `@opencode/client` (`OpenCode.make`), not `@opencode/sdk`, which has only the embedded `create`. The plugin runs in the service process under a compiled Bun 1.4.4, with the home directory as its working directory. The CLI install needs `npm install --dangerously-allow-all-scripts` on npm 12. CI uses this recipe: the host install step and `tests/integration/fixtures/opencode-host.ts` in CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0).
239
- - **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
240
- - **OC2-INSTR** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the first request of a new session carries the bootstrap with the v2 profile, once", "the title request does not carry the bootstrap", "a subagent request carries the bootstrap once, and so does the parent request that follows it", "a second turn does not duplicate the bootstrap or announce a change", "git-worktree in disabled_skills leaves the worktree rule out of the bootstrap" and "bootstrap.enabled false puts no entry and nothing reaches the model". Local probe, OpenCode 2.2.0, 2026-10-27: the entry lands in the first system message as `<context key="...">`; compaction and later requests carry it once; entries persist across a host restart, even with the plugin removed; a changed value freezes the system block at the old text and adds a `<system-update>` message; a value is capped at 256 KiB; a `session.created` subscription misses the first session after a service start, so the `prompt` hook is the trigger. The composed bootstrap is about 9.2 KB.
241
- - **OC2-CTX** — Local probe, OpenCode 2.2.0, 2026-10-27. Per-kind hooks `prompt`, `title`, `context`, `compaction` and `generate`; pushing to `event.system` in a hook reaches the model once per request. Not used for the bootstrap. The `context` hook is used for skill output restoration, which CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0), `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" covers.
242
- - **OC2-PERM** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "an agent with a managed skills list is refused a skill outside it, and an unmanaged agent is not" and "systematic_skill refuses a skill a managed agent may not load while a sibling agent loads it"; `tests/unit/opencode-v2-permissions.test.ts` (the v1 golden corpus replayed through the translator, including the integer-like skill names that v1 hoists and v2 keeps in order). Local probe, OpenCode 2.2.0, 2026-10-27: last match wins, `*` and `?` match whole values, `deny *` then one allow per skill works, any deny blocks a compound shell command, and the action names are `shell` and `subagent`. The tool asserts the bare skill id, so a rule written for `systematic:<id>` (the v1 spelling) is translated to the bare id; CI: `tests/integration/opencode-v2.test.ts` › "a skill deny written with the systematic: prefix refuses the skill, as it does on v1".
243
- - **OC2-SKILL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the native skill tool sees the registered bundled skills, and not a disabled one" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic". Local probe, OpenCode 2.2.0, 2026-10-27: the native tool refuses denied skills per agent, including in subagents; `<available_skills>` lists only the skills the agent may load; the permission resource is the skill id; an inline skill's base directory is `dirname(path)`; the tool takes only `{id}`, so `$ARGUMENTS` stays literal.
244
- - **OC2-TOOL** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "systematic_skill is offered to the model and loads an enabled skill by bare and prefixed name", "arguments are substituted into the skill the model receives" and "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin tool takes a JSON Schema input; the default registration is reachable only through Code Mode, and `options: {codemode: false}` makes it a direct tool (`pinned: true` did not).
245
- - **OC2-TRUNC** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" and "a discovered project skill above the host output limit reaches the model whole as a command, with its arguments". Local probe, OpenCode 2.2.0, 2026-10-27: tool output over 2000 lines or 51200 bytes is cut after the plugin's `execute.after` hook has seen the full text, with a trailing `[showing lines a-b of N; full output saved to <path>]` part; the bundled `ce-review`, `ce-plan` and `ce-compound-refresh` skills are over the limit. Restoration matches the tool result by call id and does not read the marker. v2 has no runtime prune placeholder: `[Old tool result content cleared]` exists only in the v1-to-v2 migration converter, so v1's compacted-result restore has no v2 counterpart.
246
- - **OC2-CMD** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a command with $ARGUMENTS reaches the model expanded, on the invoking session as it is", "a command that declares agent is refused with a message and nothing is prompted" (and the same for `model` and `subtask`), "a !-backtick block in a command stays literal text in the prompt", "the command names and descriptions match the v1 set" and "a discovered skill named like a built-in command is skipped and the built-in stays". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin command receives `{sessionID, prompt: {text, files, agents, skills}, delivery}` with the raw typed text; `prompt` takes no agent or model; `switchAgent` to an unregistered agent succeeds and the next turn fails; a plugin command named like a built-in replaces it; the command editor has only `add`; a throwing `execute` makes `session.command` reject with `CommandExecutionError` and leaves the plugin loaded. A session created with no agent or model reports neither from `session.get`, even after a turn; it runs on the host's default agent (`build` here) and the model `model.default` returns. `switchAgent` and `switchModel` make a session's choice explicit and persistent, and no call clears it; the host also reads a session's agent and model for every model request, so a switch made during a running turn changes that turn's later requests. Because of those three facts a plugin command cannot route without leaving the user's session changed or racing a running turn, so Systematic does not route: a command whose plan declares `agent`, `model` or `subtask` is refused with a message that points to an OpenCode command in Markdown or JSON. Only bundled skills can reach that refusal, and no bundled skill declares those fields. A discovered skill is never refused: its fields are dropped with one note per skill (`tests/unit/opencode-v2-commands.test.ts` › "a discovered skill that declares routing"; `tests/integration/opencode-v2.test.ts` › "a discovered skill that declares routing is not refused"). On OpenCode v1 the same skill's `subtask` passes through, `agent` passes only for a subtask that names a known agent, and `model` passes only as `provider/model`; anything else is dropped with a warning (`tests/unit/config-handler.test.ts` › "routing fields").
247
- - **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "a user agent with the same id in config keeps the user system prompt" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic" (user config and disk sources win over plugin transforms); `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set" (replay on a fresh editor). Local probe, OpenCode 2.2.0, 2026-10-27: plugins apply in config order and see earlier plugins' edits; `reload()` replays transforms and does not re-run `setup`.
248
- - **OC2-ERR** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "invalid systematic.json fails the plugin load, is logged, and the session still answers" and "a command that declares %s is refused with a message and nothing is prompted" (a `systematic:` diagnostic reaches the server's standard error); `tests/unit/opencode-v2.test.ts` › "createSafeGuard". Local probe, OpenCode 2.2.0, 2026-10-27: a rejected `setup` leaves the plugin unloaded with one `WARN failed to load plugin` and the host and other plugins unaffected; a throwing transform disables the whole plugin; a throwing `prompt` hook returns HTTP 500; a throwing `context` hook fails the turn; a throwing `execute.before` or `execute.after` turns the tool result into an error; `console.error` reaches only the server's standard error.
249
- - **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (OpenCode 2.2.0): `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected" and every test that writes a project `.opencode/systematic.json`, such as "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: `ctx.location.directory` is the project directory and `ctx.location.project` has `id`, `directory` and `canonical`; one shared service creates one plugin instance per location, with a fresh module instance and its own `setup`; project config plugins load with no trust prompt.
238
+ - **OC2-PROFILE** — [OpenCode v2 profile](skills/using-systematic/references/opencode-v2-profile.md#L5-L11). Tool names and arguments: Local probe, OpenCode 2.2.0, 2026-10-27, from the tool list of a real request (`edit`, `glob`, `grep`, `question`, `read`, `shell`, `skill`, `subagent`, `webfetch`, `websearch`, `write`, `execute`): `subagent` takes `agent`, `description`, `prompt`, `model`, `sessionID` and `background`; `question` takes `questions` with `question`, `header`, `options` and `multiple`. CI covers the `subagent` call: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a subagent request carries the bootstrap once, and so does the parent request that follows it". `question` has no CI test.
239
+ - **OC2-LOADER** — OpenCode v1 1.18.28, 1.18.29, 1.19.4 and v2 2.1.4, 2.2.0, 2026-10-27. The object default `{id, setup, server}` loads on all five. A v1 host calls `server(input)` and then `setup(ctx)` in the same process, with a reduced context of 9 keys and no `location` or `session`; a v2 host never calls `server`. v2 2.1.4 drops a function default with no log line, and 2.2.0 logs a warning. Tarball config forms fail on v1, so installs go through `npm install <tarball>` and load the installed directory. Local probe for the version comparison. CI covers the load: CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected"; the v1 loads: CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, `tests/integration/opencode-v1.test.ts` › "packaged plugin loads, warns on a removed disabled_skills name, and exposes a compliant catalog"; the bridge no-op: `tests/unit/opencode-v2.test.ts` › "default export wiring" › "setup does nothing for the reduced context a v1 host passes".
240
+ - **OC2-HOST** — Local probe, OpenCode 2.2.0, 2026-10-27. Isolation takes `HOME`, the four `XDG_*` variables, `OPENCODE_CONFIG_DIR` and `TMPDIR`; a managed config under `/Library` on macOS is read and cannot be isolated. One-shot runs use `run --standalone`; the default `run` starts a detached shared service on port 49374. The remote client is `@opencode/client` (`OpenCode.make`), not `@opencode/sdk`, which has only the embedded `create`. The plugin runs in the service process under a compiled Bun 1.4.4, with the home directory as its working directory. The CLI install needs `npm install --dangerously-allow-all-scripts` on npm 12. CI uses this recipe: the host install step and `tests/integration/fixtures/opencode-host.ts` in CI job `Host Contract v2 shard N/4` (the pinned v2 CLI).
241
+ - **OC2-AGENT** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the bundled agents appear in the agent list with their v1 description and prompt" and "a user agent with the same id in config keeps the user system prompt"; `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set"; `tests/unit/opencode-v2.test.ts` › "a read-only agent another plugin already defined" and `tests/integration/opencode-v2.test.ts` › "a researcher an earlier plugin defined with no denies is replaced by the shipped one: Systematic prompt, shell and write refused". Local probe, OpenCode 2.2.0, 2026-10-27: an extra property set in a transform is visible to later plugins in the same replay and gone from `agent.list`, so no ownership marker survives; an agent's `model` applies only when the session names no model; a session whose agent is later unregistered fails its next turn with `Session.AgentNotFoundError`.
242
+ - **OC2-INSTR** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the first request of a new session carries the bootstrap with the v2 profile, once", "the title request does not carry the bootstrap", "a subagent request carries the bootstrap once, and so does the parent request that follows it", "a second turn does not duplicate the bootstrap or announce a change", "git-worktree in disabled_skills leaves the worktree rule out of the bootstrap" and "bootstrap.enabled false puts no entry and nothing reaches the model". Local probe, OpenCode 2.2.0, 2026-10-27: the entry lands in the first system message as `<context key="...">`; compaction and later requests carry it once; entries persist across a host restart, even with the plugin removed; a changed value freezes the system block at the old text and adds a `<system-update>` message; a value is capped at 256 KiB; a `session.created` subscription misses the first session after a service start, so the `prompt` hook is the trigger. The composed bootstrap is about 9.2 KB.
243
+ - **OC2-CTX** — Local probe, OpenCode 2.2.0, 2026-10-27. Per-kind hooks `prompt`, `title`, `context`, `compaction` and `generate`; pushing to `event.system` in a hook reaches the model once per request. Not used for the bootstrap. The `context` hook is used for skill output restoration, which CI job `Host Contract v2 shard N/4` (the pinned v2 CLI), `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" covers.
244
+ - **OC2-PERM** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "an agent with a managed skills list is refused a skill outside it, and an unmanaged agent is not" and "systematic_skill refuses a skill a managed agent may not load while a sibling agent loads it"; `tests/unit/opencode-v2-permissions.test.ts` (the v1 golden corpus replayed through the translator, including the integer-like skill names that v1 hoists and v2 keeps in order). Local probe, OpenCode 2.2.0, 2026-10-27: last match wins, `*` and `?` match whole values, `deny *` then one allow per skill works, any deny blocks a compound shell command, and the action names are `shell` and `subagent`. The tool asserts the bare skill id, so a rule written for `systematic:<id>` (the v1 spelling) is translated to the bare id; CI: `tests/integration/opencode-v2.test.ts` › "a skill deny written with the systematic: prefix refuses the skill, as it does on v1".
245
+ - **OC2-SKILL** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the native skill tool sees the registered bundled skills, and not a disabled one" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic". Local probe, OpenCode 2.2.0, 2026-10-27: the native tool refuses denied skills per agent, including in subagents; `<available_skills>` lists only the skills the agent may load; the permission resource is the skill id; an inline skill's base directory is `dirname(path)`; the tool takes only `{id}`, so `$ARGUMENTS` stays literal.
246
+ - **OC2-TOOL** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "systematic_skill is offered to the model and loads an enabled skill by bare and prefixed name", "arguments are substituted into the skill the model receives" and "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin tool takes a JSON Schema input; the default registration is reachable only through Code Mode, and `options: {codemode: false}` makes it a direct tool (`pinned: true` did not).
247
+ - **OC2-TRUNC** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "a skill above the host output limit reaches the model in full on the continuation request and later turns" and "a discovered project skill above the host output limit reaches the model whole as a command, with its arguments". Local probe, OpenCode 2.2.0, 2026-10-27: tool output over 2000 lines or 51200 bytes is cut after the plugin's `execute.after` hook has seen the full text, with a trailing `[showing lines a-b of N; full output saved to <path>]` part; the bundled `ce-review`, `ce-plan` and `ce-compound-refresh` skills are over the limit. Restoration matches the tool result by call id and does not read the marker. v2 has no runtime prune placeholder: `[Old tool result content cleared]` exists only in the v1-to-v2 migration converter, so v1's compacted-result restore has no v2 counterpart.
248
+ - **OC2-CMD** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "a command with $ARGUMENTS reaches the model expanded, on the invoking session as it is", "a command that declares agent is refused with a message and nothing is prompted" (and the same for `model` and `subtask`), "a !-backtick block in a command stays literal text in the prompt", "the command names and descriptions match the v1 set" and "a discovered skill named like a built-in command is skipped and the built-in stays". Local probe, OpenCode 2.2.0, 2026-10-27: a plugin command receives `{sessionID, prompt: {text, files, agents, skills}, delivery}` with the raw typed text; `prompt` takes no agent or model; `switchAgent` to an unregistered agent succeeds and the next turn fails; a plugin command named like a built-in replaces it; the command editor has only `add`; a throwing `execute` makes `session.command` reject with `CommandExecutionError` and leaves the plugin loaded. A session created with no agent or model reports neither from `session.get`, even after a turn; it runs on the host's default agent (`build` here) and the model `model.default` returns. `switchAgent` and `switchModel` make a session's choice explicit and persistent, and no call clears it; the host also reads a session's agent and model for every model request, so a switch made during a running turn changes that turn's later requests. Because of those three facts a plugin command cannot route without leaving the user's session changed or racing a running turn, so Systematic does not route: a command whose plan declares `agent`, `model` or `subtask` is refused with a message that points to an OpenCode command in Markdown or JSON. Only bundled skills can reach that refusal, and no bundled skill declares those fields. A discovered skill is never refused: its fields are dropped with one note per skill (`tests/unit/opencode-v2-commands.test.ts` › "a discovered skill that declares routing"; `tests/integration/opencode-v2.test.ts` › "a discovered skill that declares routing is not refused"). On OpenCode v1 the same skill's `subtask` passes through, `agent` passes only for a subtask that names a known agent, and `model` passes only as `provider/model`; anything else is dropped with a warning (`tests/unit/config-handler.test.ts` › "routing fields").
249
+ - **OC2-ORDER** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "a user agent with the same id in config keeps the user system prompt" and "an on-disk skill with the same id replaces the registered one in the native tool, with no diagnostic" (user config and disk sources win over plugin transforms); `tests/unit/opencode-v2.test.ts` › "agents installer" › "replaying the transform on a fresh editor yields the same single agent set" (replay on a fresh editor). Local probe, OpenCode 2.2.0, 2026-10-27: plugins apply in config order and see earlier plugins' edits; `reload()` replays transforms and does not re-run `setup`.
250
+ - **OC2-ERR** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "invalid systematic.json fails the plugin load, is logged, and the session still answers" and "a command that declares %s is refused with a message and nothing is prompted" (a `systematic:` diagnostic reaches the server's standard error); `tests/unit/opencode-v2.test.ts` › "createSafeGuard". Local probe, OpenCode 2.2.0, 2026-10-27: a rejected `setup` leaves the plugin unloaded with one `WARN failed to load plugin` and the host and other plugins unaffected; a throwing transform disables the whole plugin; a throwing `prompt` hook returns HTTP 500; a throwing `context` hook fails the turn; a throwing `execute.before` or `execute.after` turns the tool result into an error; `console.error` reaches only the server's standard error.
251
+ - **OC2-TRUST** — CI job `Host Contract v2 shard N/4` (the pinned v2 CLI): `tests/integration/opencode-v2.test.ts` › "the packed plugin loads, setup runs once and stderr carries nothing unexpected" and every test that writes a project `.opencode/systematic.json`, such as "a skill in disabled_skills is refused by systematic_skill". Local probe, OpenCode 2.2.0, 2026-10-27: `ctx.location.directory` is the project directory and `ctx.location.project` has `id`, `directory` and `canonical`; one shared service creates one plugin instance per location, with a fresh module instance and its own `setup`; project config plugins load with no trust prompt.
250
252
  - **OC2-TODO** — Binary strings only: no live request showed the tool, and no CI test covers it. Local probe, OpenCode 2.2.0, 2026-10-27, reading strings in the 2.2.0 CLI binary: a `todowrite` tool with input `todos: [{content, status}]` (`status` is `pending`, `in_progress`, `completed` or `cancelled`) and an experimental config option `todo` described as "Enable the experimental todowrite tool. Defaults to false". The tool list of the probe requests had no todo tool, so whether the tool appears with the option on was not observed. The v2 profile therefore marks task tracking conditional.
251
253
  - **PI-P** — [Pi profile](skills/using-systematic/references/pi-profile.md#L5-L11).
252
254
  - **PI-1** — `src/lib/pi-delegate-tool.ts:14-18,245-249,279-291`.
@@ -289,11 +291,11 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
289
291
  - **WT-1** — `skills/using-systematic/references/worktree-placement.md` (the rule text); `tests/unit/bootstrap.test.ts:1043-1092` (exact text, at most 350 bytes, names `git-worktree` and `.worktrees/<branch>`, keeps the raw-add ban and the carve-out sentence, no harness identifiers, no `CLAUDE.md` literal).
290
292
  - **WT-2** — `skills/git-worktree/scripts/worktree-manager.sh` (the script); `tests/unit/git-worktree-manager.test.ts` and `tests/unit/git-worktree-cleanup.test.ts` (placement from the root, a subdirectory and a linked worktree, refused layouts, ignore policy, base resolution, `--no-track`, `list`, `switch`, `copy-env`, `cleanup`; real git in throwaway repositories with a bare `origin`, `TEST_BASH=/bin/bash` runs them under bash 3.2); `tests/unit/git-worktree-skills-contract.test.ts` (the safety and routing terms in `skills/git-worktree/SKILL.md` and the pointers in `ce-review`, `orchestrating-subagents` and `git-clean-gone-branches`). Package probe: the plugin-init, Pi-init and built-output-style tests cited by WT-1, OC-8, PI-8 and CC-13. No live session has run.
291
293
  - **SR-1** — `src/lib/search-core.ts` (`runSearch`, the tool name and argument constants, the lifecycle constants and resolver); `src/lib/search-tool.ts` (the v1, v2 and Pi adapters); `tests/unit/search-adapters-parity.test.ts` (every adapter's real entry over one corpus: byte-identical text, fixed validation errors, no permission request, registration shapes); `tests/unit/search-lifecycle.test.ts` (the resolver over a lifecycle fixture corpus); `tests/unit/search-determinism.test.ts` (Bun and Node produce the same bits).
292
- - **SR-2** — `tests/integration/opencode-v1.test.ts` › "systematic_search finds a document under the host project, and limit 0 and 21 reach the core" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`); `tests/integration/opencode-v2.test.ts` › "systematic_search is offered to the model, finds a document under the project, and limit 0 and 21 reach the core" (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set).
294
+ - **SR-2** — `tests/integration/opencode-v1.test.ts` › "systematic_search finds a document under the host project, and limit 0 and 21 reach the core" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`); `tests/integration/opencode-v2.test.ts` › "systematic_search is offered to the model, finds a document under the project, and limit 0 and 21 reach the core" (CI job `Host Contract v2 shard N/4`, the pinned v2 CLI, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set).
293
295
  - **SR-3** — `src/claude-code-search.ts` (the bin entry); `tests/unit/claude-code-search.test.ts` (the bundle run from a foreign directory); `tests/unit/harness-profiles-search.test.ts` and `tests/integration/claude-code.test.ts` (the output style names `systematic-search` and `command -v systematic-search`, and still ships no `systematic_skill` tool). From project config the bin reads only the `sources` a project proposes, from the repository-root file, and only for `--kind external` (SR-6). `tests/unit/claude-code-search.test.ts` has 26 tests, one of which starts in a subfolder of a repository and reads the repo-root project file, its excludes and a user.local allow entry. No CI job runs the bin inside a live Claude Code session; see SR-4.
294
296
  - **SR-4** — Manual evidence, not a CI check. Recorded 2026-10-31 with Claude Code 2.1.312 and model claude-sonnet-5-5. The plugin bundle was built from 9ed5a336 with `bun run claude-code:build` and loaded with `--plugin-dir`. The fixture project held one solution and one `status: abandoned` brainstorm. `claude -p --output-format stream-json --verbose --forward-subagent-text` was given a prompt to dispatch `systematic:learnings-researcher` with `scope: past-work`. Outcome: the subagent ran `systematic-search --kind all --limit 12 -- '<query>'` through Bash. The Bash `tool_use` carried `parent_tool_use_id` set to the `Agent` dispatch's id. The `tool_result` began `Search "` and named both the solution and the brainstorm. In that bundle the researcher still used the `all` call. The per-kind calls that replaced it run through the same bin. Scope limit: this run predates `kind: external`, and no live Claude Code session has run `--kind external`.
295
- - **SR-5** — `tests/helpers/delegated-search-proof.ts` (the planted fixture, the scripted four-turn model and the proof assertion with its failure diagnostics); `tests/unit/delegated-search-proof.test.ts` (the assertion over recorded request lists, including each failure code); `tests/integration/opencode-v1.test.ts` › "a dispatched learnings-researcher child calls systematic_search and its result reaches the parent" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, OpenCode 1.18.29 and the current v1 pin); `tests/integration/opencode-v2.test.ts` › the same test name (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set); `tests/integration/pi.test.ts` › "a delegated learnings-researcher child calls systematic_search and its result reaches the parent" (the real Pi runtime, run in the v2 host-contract profile). Each file also has a negative control: with `search.enabled` false the child is not offered the tool and the proof fails saying so. Scope limit: a scripted model makes the call, so these show reach and plumbing only.
296
- - **SR-6** — External search reach (`kind: "external"`). Code: `src/lib/search-external-sources.ts` (the per-call reader every surface shares), `src/lib/search-project-identity.ts` (main-root identity from filesystem reads), `src/lib/search-external.ts` and `src/lib/search-external-deciduous.ts` (the Markdown and Deciduous loaders), `src/lib/search-user-config.ts` (the field and entry validators, the user-level and project file selection, and the 1 MB bin-safe project reader), `src/lib/search-exclude.ts` (the `exclude` pattern validators and matcher), `src/lib/search-render.ts` (the external renderer). Host-free tests: `tests/unit/search-project-identity.test.ts` (real git repositories and `git worktree add`: a worktree maps to its main root, forged and inconsistent `.git` files, a bare repository, `core.worktree` and a symlinked `.git` never resolve); `tests/unit/search-external-sources.test.ts` (resolution order, worktrees, shadowing, the 8-source cap, user and custom config directories, nothing cached between calls, the module graph); `tests/unit/search-external.test.ts` and `tests/unit/search-external-deciduous.test.ts` (records, caps, the shared read budget, states, symlinks and read-only behavior); `tests/unit/search-adapters-parity.test.ts` › \"search adapters parity: kind external\" (v1, v2, Pi, CLI, the bin in process and the built bin under Node give byte-identical text; not-allowed replies; an allow-list edit between calls; `search.enabled` false); `tests/unit/claude-code-search.test.ts` (`--kind external` in process and from a foreign directory under Node, the stderr warning for a broken project file, and a bundle that contains neither `config.ts` nor `config-schema.ts`); `tests/unit/opencode-v2-search.test.ts` › \"setupOpenCodeV2 with a project search.sources problem\" (a project file that parses never fails v2 setup, and one that cannot be parsed still does); `tests/unit/past-work-wiring-contract.test.ts` › \"the external call in past-work scope\" and the External records group (the researcher prompt side); `tests/unit/delegated-search-proof.test.ts` › \"external mode\" and `tests/helpers/delegated-search-proof.ts` (the external fixture, script and assertion). Real host: `tests/integration/opencode-v2.test.ts` › \"a dispatched learnings-researcher child searches kind external and the planted external record reaches the parent\" and its negative control \"with the allow entry absent the child receives the not-allowed reply, the parent never sees the external path and the proof names the failure\" (CI job `Host Contract v2 shard N/4`, OpenCode 2.2.0, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set). Config locations, local overlays and excludes (host-free; the per-file counts are the tests in each file today, not only the ones added): `tests/unit/search-exclude.test.ts` (77 tests: pattern validation, the matcher on slash, `**` and `?` patterns, adversarial inputs, and a module that imports nothing); `tests/unit/search-user-config.test.ts` (192 tests: file selection by existence, the four user-level layers, an aliased custom directory read once, project file selection, `exclude` validation); `tests/unit/search-corpus.test.ts` › "lookupSearchRoot" and "discoverSourceFiles: excludes" (109 tests); `tests/unit/search-external.test.ts` › "loadExternalSources: excludes" (58 tests) and `tests/unit/search-external-deciduous.test.ts` › "Deciduous loader: excludes" (54 tests); `tests/unit/search-external-sources.test.ts` › "resolveExternalSources: locations, local overlays and diagnostics" and "inspectSearch" (66 tests); `tests/unit/search-adapters-parity.test.ts` › "search adapters parity: repo-root project file, local overlays and excludes" and "search adapters parity: an invalid local file" (43 tests: one fixture started in a subfolder gives byte-identical external text on v1, v2, Pi, the CLI, the bin in process and the built bin, with every layer and the excludes applied; v1 and Pi throw at init and v2 setup rejects naming an invalid local file; a project file over 1 MB fails v1, v2 and Pi while the CLI and the bin carry on); `tests/unit/config.test.ts` › "layered config files" (374 tests); `tests/unit/pi.test.ts` › "src/pi.ts config resolved from the repository root" (72 tests); `tests/unit/opencode-v2.test.ts` (44 tests: a project directory below the repository root applies the root file, the home fallback applies no project file, an invalid user.local rejects setup naming it); `tests/unit/cli.test.ts` › "cli config show: locations and search" and the `loadSearchSettingsForCli` cases (132 tests). Scope limits: a scripted model makes the call, so the real-host proof shows reach and plumbing only; it covers OpenCode v2 alone. No real-host external proof exists for OpenCode v1, Pi or Claude Code.
297
+ - **SR-5** — `tests/helpers/delegated-search-proof.ts` (the planted fixture, the scripted four-turn model and the proof assertion with its failure diagnostics); `tests/unit/delegated-search-proof.test.ts` (the assertion over recorded request lists, including each failure code); `tests/integration/opencode-v1.test.ts` › "a dispatched learnings-researcher child calls systematic_search and its result reaches the parent" (CI jobs `Host Contract v1 floor` and `Host Contract v1 current`, OpenCode 1.18.29 and the current v1 pin); `tests/integration/opencode-v2.test.ts` › the same test name (CI job `Host Contract v2 shard N/4`, the pinned v2 CLI, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set); `tests/integration/pi.test.ts` › "a delegated learnings-researcher child calls systematic_search and its result reaches the parent" (the real Pi runtime, run in the v2 host-contract profile). Each file also has a negative control: with `search.enabled` false the child is not offered the tool and the proof fails saying so. Scope limit: a scripted model makes the call, so these show reach and plumbing only.
298
+ - **SR-6** — External search reach (`kind: "external"`). Code: `src/lib/search-external-sources.ts` (the per-call reader every surface shares), `src/lib/search-project-identity.ts` (main-root identity from filesystem reads), `src/lib/search-external.ts` and `src/lib/search-external-deciduous.ts` (the Markdown and Deciduous loaders), `src/lib/search-user-config.ts` (the field and entry validators, the user-level and project file selection, and the 1 MB bin-safe project reader), `src/lib/search-exclude.ts` (the `exclude` pattern validators and matcher), `src/lib/search-render.ts` (the external renderer). Host-free tests: `tests/unit/search-project-identity.test.ts` (real git repositories and `git worktree add`: a worktree maps to its main root, forged and inconsistent `.git` files, a bare repository, `core.worktree` and a symlinked `.git` never resolve); `tests/unit/search-external-sources.test.ts` (resolution order, worktrees, shadowing, the 8-source cap, user and custom config directories, nothing cached between calls, the module graph); `tests/unit/search-external.test.ts` and `tests/unit/search-external-deciduous.test.ts` (records, caps, the shared read budget, states, symlinks and read-only behavior); `tests/unit/search-adapters-parity.test.ts` › \"search adapters parity: kind external\" (v1, v2, Pi, CLI, the bin in process and the built bin under Node give byte-identical text; not-allowed replies; an allow-list edit between calls; `search.enabled` false); `tests/unit/claude-code-search.test.ts` (`--kind external` in process and from a foreign directory under Node, the stderr warning for a broken project file, and a bundle that contains neither `config.ts` nor `config-schema.ts`); `tests/unit/opencode-v2-search.test.ts` › \"setupOpenCodeV2 with a project search.sources problem\" (a project file that parses never fails v2 setup, and one that cannot be parsed still does); `tests/unit/past-work-wiring-contract.test.ts` › \"the external call in past-work scope\" and the External records group (the researcher prompt side); `tests/unit/delegated-search-proof.test.ts` › \"external mode\" and `tests/helpers/delegated-search-proof.ts` (the external fixture, script and assertion). Real host: `tests/integration/opencode-v2.test.ts` › \"a dispatched learnings-researcher child searches kind external and the planted external record reaches the parent\" and its negative control \"with the allow entry absent the child receives the not-allowed reply, the parent never sees the external path and the proof names the failure\" (CI job `Host Contract v2 shard N/4`, the pinned v2 CLI, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set). Config locations, local overlays and excludes (host-free; the per-file counts are the tests in each file today, not only the ones added): `tests/unit/search-exclude.test.ts` (77 tests: pattern validation, the matcher on slash, `**` and `?` patterns, adversarial inputs, and a module that imports nothing); `tests/unit/search-user-config.test.ts` (192 tests: file selection by existence, the four user-level layers, an aliased custom directory read once, project file selection, `exclude` validation); `tests/unit/search-corpus.test.ts` › "lookupSearchRoot" and "discoverSourceFiles: excludes" (109 tests); `tests/unit/search-external.test.ts` › "loadExternalSources: excludes" (58 tests) and `tests/unit/search-external-deciduous.test.ts` › "Deciduous loader: excludes" (54 tests); `tests/unit/search-external-sources.test.ts` › "resolveExternalSources: locations, local overlays and diagnostics" and "inspectSearch" (66 tests); `tests/unit/search-adapters-parity.test.ts` › "search adapters parity: repo-root project file, local overlays and excludes" and "search adapters parity: an invalid local file" (43 tests: one fixture started in a subfolder gives byte-identical external text on v1, v2, Pi, the CLI, the bin in process and the built bin, with every layer and the excludes applied; v1 and Pi throw at init and v2 setup rejects naming an invalid local file; a project file over 1 MB fails v1, v2 and Pi while the CLI and the bin carry on); `tests/unit/config.test.ts` › "layered config files" (374 tests); `tests/unit/pi.test.ts` › "src/pi.ts config resolved from the repository root" (72 tests); `tests/unit/opencode-v2.test.ts` (44 tests: a project directory below the repository root applies the root file, the home fallback applies no project file, an invalid user.local rejects setup naming it); `tests/unit/cli.test.ts` › "cli config show: locations and search" and the `loadSearchSettingsForCli` cases (132 tests). Scope limits: a scripted model makes the call, so the real-host proof shows reach and plumbing only; it covers OpenCode v2 alone. No real-host external proof exists for OpenCode v1, Pi or Claude Code.
297
299
  - **CN-1** — OpenCode v1 1.19.5 (CI job `Host Contract v1 current`): `tests/integration/opencode-v1-isolation.test.ts` › "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent" (the `HOST_SUPPORT_TABLE` `observedBy` for this row); "with the deny entries removed the same script writes a file and the proof names an isolation breach" (negative control); "a blanket allow in the host's own permission block does not lift the shipped researcher's deny"; "a headless run reads a git checkout outside the project and the marker reaches the parent, with every denied tool still refused" and "without external_directory: allow the same read is auto-rejected, which pins what the entry does". The file runs on the `v1-current` profile only (`scripts/host-contract-guard.ts`, `V1_CURRENT_ONLY_FILES`). Local observation on 1.19.5: a headless run whose work file lay in the state directory was refused as an `external_directory` request, which ended the session before any final line. A host-config `permission.external_directory` allow for `<state directory>/*` let the whole pipeline run and end `Connect complete`. Scope limit: other v1 versions, including the 1.18.29 floor, are unobserved and unsupported.
298
300
  - **CN-2** — OpenCode v2 2.2.5 (CI job `Host Contract v2 shard N/4`, run only when `SYSTEMATIC_OPENCODE_V2_BIN` is set): `tests/integration/opencode-v2.test.ts` › "a session-level allow does not lift the guarded researcher when a parent with that rule dispatches it" (the `observedBy` for this row), "a session-level allow does not lift the guarded researcher when it runs directly", "the shipped researcher, dispatched from the packed plugin, is refused shell, write, edit and web fetch and its read reaches the parent", and the negative control "the shipped definition alone, under a name the guard does not know, is refused each denied tool and its read reaches the parent". Scope limit: a scripted model makes the calls.
299
301
  - **CN-3** — The v2 tool guard. Code: `src/lib/opencode-v2-tool-guard.ts` (`decideToolCall`, the `execute.before` registration, `READ_ONLY_AGENT_NAMES`, `READ_ONLY_TOOL_ALLOWLIST`). Tests: `tests/unit/opencode-v2-tool-guard.test.ts` (the allowlist is exactly read, grep, glob, skill and the two Systematic tools; exact-name matching; every other agent left alone; a refused call throws so the host fails that call alone; a failed hook registration is reported and never thrown into the host); `tests/integration/opencode-v2.test.ts` › "the execute.before hook sees each call with the session agent, including Code Mode calls, and a throw fails that call alone" (a plugin hook that throws fails the call without any Systematic guard in play). The reason for the guard, observed on 2.2.5: a session-level allow rule overrides an agent's own deny, and Code Mode `execute` reaches host-native `opencode_*` tools that no frontmatter key can name.
package/README.md CHANGED
@@ -41,7 +41,7 @@ The workflow runs on three harnesses from one source: [OpenCode](https://opencod
41
41
  { "plugin": ["@fro.bot/systematic@latest"] }
42
42
  ```
43
43
 
44
- OpenCode v2 (2.2.0 or later) reads the `plugins` key:
44
+ OpenCode v2 (2.2.5 or later) reads the `plugins` key:
45
45
 
46
46
  ```json
47
47
  { "plugins": ["@fro.bot/systematic@latest"] }
@@ -52,7 +52,9 @@ Work in the fewest turns you can. Make independent searches and reads in one tur
52
52
  6. Take every fingerprint from the files index or the rules file. Search the files index for the path and use its `sha256` and `project root` as they are. Never compute, invent or guess a fingerprint or a path.
53
53
  7. Copy every excerpt from a read of that file, character for character, 20 to 1500 characters. A target-evidence excerpt must lie inside the line span you cite and contain the symbol you name. Never paraphrase inside an excerpt.
54
54
 
55
- If you are short of turns, stop searching, answer at once, and set `"complete": false`. Do not guess to finish.
55
+ A search result that is truncated or very long is a reason to narrow the search, never a reason to stop. Search again with a more specific pattern, in one project or directory at a time, or use the files index to pick paths, and go on. Before you conclude that a rule has no candidate, read at least the most relevant file a search pointed to. Judge from what you read, not from search output alone.
56
+
57
+ If you are short of turns, stop searching, answer at once, and set `"complete": false`. Do not guess to finish. That is the only case for `"complete": false`. When the searches are done and nothing holds up, set `"complete": true` with no candidates.
56
58
 
57
59
  ## What you return
58
60
 
@@ -81,10 +83,10 @@ The types matter, because the helper rejects the whole answer on a wrong one:
81
83
  "kind": "contradiction | transferable-lesson",
82
84
  "ruleId": "<a rule id from your family that one source belongs to>",
83
85
  "target": "<main root of the project that should change>",
84
- "title": "<one line>",
85
- "summary": "<one paragraph: what the excerpts together show>",
86
+ "title": "<one line, at most 160 characters; aim for under about 120>",
87
+ "summary": "<one paragraph, at most 800 characters; aim for about 4 short sentences, about 600 characters: what the excerpts together show>",
86
88
  "nextStep": "refresh-learning | compound-learning | investigate",
87
- "overlapCheck": { "queries": ["<what you searched in the target>"], "result": "none-found | found", "note": "<optional one paragraph>" },
89
+ "overlapCheck": { "queries": ["<what you searched in the target, at most 200 characters each>"], "result": "none-found | found", "note": "<optional one paragraph, at most 400 characters>" },
88
90
  "sources": [{ "project": "<root>", "path": "<learning path>", "fingerprint": "<sha256>", "excerpt": "<verbatim>" }],
89
91
  "targetEvidence": [{ "path": "<tracked path in the target>", "start": 1, "end": 1, "symbol": "<identifier in the span>", "fingerprint": "<sha256>", "excerpt": "<verbatim, inside the span, contains the symbol>" }],
90
92
  "counterevidence": [{ "project": "<root>", "path": "<path>", "fingerprint": "<sha256>", "excerpt": "<verbatim>" }]
@@ -98,4 +100,6 @@ The types matter, because the helper rejects the whole answer on a wrong one:
98
100
  - A `transferable-lesson` has `sources` outside the `target` project, at least one `targetEvidence` item, and its `nextStep` is `compound-learning` or `investigate`.
99
101
  - `sources` are learnings. `counterevidence` may be any tracked file.
100
102
  - Free text (`title`, `summary`, `note`, each query) is one paragraph within these caps: title 160 characters, summary 800, note 400, query 200. Put nothing in it that you copied from a file other than in an excerpt.
103
+ - Send at most one candidate for each rule and target. When one rule shows several gaps in the same target, put them in that one candidate, each gap as its own `targetEvidence` entry, and keep the summary within its cap: the helper drops a second candidate for the same rule, sources and target as a duplicate, and the finding is lost.
101
104
  - Propose only the two kinds above. Send at most `max candidates`. An empty `candidates` list with `complete` true is the right answer when nothing holds up.
105
+ - Last check, before you answer: measure each title, summary and note you wrote. If one is over its cap, cut it, and drop detail that is already in the excerpts. Never answer with an over-length field: the helper drops the whole candidate for it, and the finding is lost.
package/dist/cli.js CHANGED
@@ -3267,7 +3267,7 @@ function setupOpenCode(cwd, ops) {
3267
3267
  throw createSetupError(`Invalid OpenCode config in ${targetPath}: root must be an object`);
3268
3268
  }
3269
3269
  if (Object.hasOwn(parsed, "plugins")) {
3270
- throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugins\` (plural) is the OpenCode v2 key. Setup writes only the OpenCode v1 \`plugin\` key and left this file unchanged. For OpenCode v2 (2.2.0 or later), add "${SYSTEMATIC_PACKAGE_NAME}" to \`plugins\` by hand`);
3270
+ throw createSetupError(`Invalid OpenCode config in ${targetPath}: \`plugins\` (plural) is the OpenCode v2 key. Setup writes only the OpenCode v1 \`plugin\` key and left this file unchanged. For OpenCode v2 (2.2.5 or later), add "${SYSTEMATIC_PACKAGE_NAME}" to \`plugins\` by hand`);
3271
3271
  }
3272
3272
  if (!Object.hasOwn(parsed, "plugin")) {
3273
3273
  const edits = modify(rawText, ["plugin"], [SYSTEMATIC_PACKAGE_NAME], {});
package/dist/index.js CHANGED
@@ -748,16 +748,53 @@ function buildAssetPlan(input) {
748
748
  };
749
749
  }
750
750
 
751
+ // src/lib/opencode-v2-tool-guard.ts
752
+ var READ_ONLY_AGENT_NAMES = [
753
+ "connections-researcher"
754
+ ];
755
+ var READ_ONLY_TOOL_ALLOWLIST = [
756
+ "read",
757
+ "grep",
758
+ "glob",
759
+ "skill",
760
+ "systematic_search",
761
+ "systematic_skill"
762
+ ];
763
+ var ALLOWED = { allowed: true };
764
+ function decideToolCall(agent, tool) {
765
+ if (typeof agent !== "string" || !READ_ONLY_AGENT_NAMES.includes(agent)) {
766
+ return ALLOWED;
767
+ }
768
+ if (typeof tool === "string" && READ_ONLY_TOOL_ALLOWLIST.includes(tool)) {
769
+ return ALLOWED;
770
+ }
771
+ const name = typeof tool === "string" ? tool : "unknown";
772
+ return {
773
+ allowed: false,
774
+ message: `The tool "${name}" is not available to the read-only ${agent} agent. It may call only: ${READ_ONLY_TOOL_ALLOWLIST.join(", ")}.`
775
+ };
776
+ }
777
+ function refuseOutsideAllowlist(event) {
778
+ const verdict = decideToolCall(event.agent, event.tool);
779
+ if (!verdict.allowed)
780
+ throw new Error(verdict.message);
781
+ }
782
+ var installToolGuard = async ({ ctx }) => {
783
+ await ctx.tool.hook("execute.before", refuseOutsideAllowlist);
784
+ };
785
+
751
786
  // src/lib/config-handler.ts
752
787
  function isSystematicAgentConfig(agent) {
753
788
  const description = agent?.description;
754
789
  return typeof description === "string" && /\(.* - Systematic\)$/.test(description);
755
790
  }
791
+ var reportedSecuritySensitiveAgents = new Set;
792
+ var foreignRoutingByConfig = new WeakMap;
756
793
  function isSystematicCommandConfig(command) {
757
794
  const description = command?.description;
758
795
  return typeof description === "string" && description.startsWith("(Systematic) ");
759
796
  }
760
- function mergeSystematicEntries(existing, emitted, shouldDropExisting) {
797
+ function mergeSystematicEntries(existing, emitted, shouldDropExisting, enforceOver) {
761
798
  const merged = { ...existing ?? {} };
762
799
  for (const [key, value] of Object.entries(existing ?? {})) {
763
800
  if (shouldDropExisting(key, value)) {
@@ -765,12 +802,54 @@ function mergeSystematicEntries(existing, emitted, shouldDropExisting) {
765
802
  }
766
803
  }
767
804
  for (const [key, value] of Object.entries(emitted)) {
768
- if (Object.hasOwn(merged, key))
805
+ if (Object.hasOwn(merged, key)) {
806
+ if (enforceOver !== undefined) {
807
+ merged[key] = enforceOver(key, merged[key], value);
808
+ }
769
809
  continue;
810
+ }
770
811
  merged[key] = value;
771
812
  }
772
813
  return merged;
773
814
  }
815
+ function isSecuritySensitiveAgent(name) {
816
+ return READ_ONLY_AGENT_NAMES.includes(name);
817
+ }
818
+ function readForeignRouting(entry) {
819
+ if (!isRecord(entry))
820
+ return {};
821
+ const { model, variant } = entry;
822
+ return {
823
+ ...typeof model === "string" ? { model } : {},
824
+ ...typeof variant === "string" ? { variant } : {}
825
+ };
826
+ }
827
+ function reportForeignDefinition(name) {
828
+ if (reportedSecuritySensitiveAgents.has(name))
829
+ return;
830
+ reportedSecuritySensitiveAgents.add(name);
831
+ console.warn(`[systematic] agent "${name}" is also defined by another config entry; applied Systematic's read-only definition and kept only that entry's model and variant.`);
832
+ }
833
+ function enforceSecuritySensitiveAgent(config, name, present, emitted) {
834
+ if (!isSecuritySensitiveAgent(name))
835
+ return present ?? emitted;
836
+ const captured = foreignRoutingByConfig.get(config) ?? new Map;
837
+ foreignRoutingByConfig.set(config, captured);
838
+ let foreign;
839
+ if (isSystematicAgentConfig(present)) {
840
+ foreign = captured.get(name);
841
+ } else {
842
+ foreign = readForeignRouting(present);
843
+ captured.set(name, foreign);
844
+ reportForeignDefinition(name);
845
+ }
846
+ const result = { ...emitted };
847
+ if (foreign?.model !== undefined)
848
+ result.model = foreign.model;
849
+ if (foreign?.variant !== undefined)
850
+ result.variant = foreign.variant;
851
+ return result;
852
+ }
774
853
  function foldPermissionRulesToV1Map(rules) {
775
854
  const explicitSkillSettings = new Map;
776
855
  for (const rule of rules) {
@@ -884,7 +963,7 @@ function createConfigHandler(deps) {
884
963
  const { config: systematicConfig, overlays } = loadConfigWithSources(directory);
885
964
  const existingAgents = { ...config.agent ?? {} };
886
965
  const existingCommands = { ...config.command ?? {} };
887
- const nativeAgentNames = Object.entries(existingAgents).filter(([, agent]) => !isSystematicAgentConfig(agent)).map(([name]) => name);
966
+ const nativeAgentNames = Object.entries(existingAgents).filter(([name, agent]) => !isSystematicAgentConfig(agent) && !isSecuritySensitiveAgent(name)).map(([name]) => name);
888
967
  const plan = buildAssetPlan({
889
968
  config: systematicConfig,
890
969
  overlays,
@@ -902,7 +981,7 @@ function createConfigHandler(deps) {
902
981
  toV1AgentConfig(planned)
903
982
  ]));
904
983
  const bundledAgentKeys = new Set(Object.keys(bundledAgents));
905
- config.agent = mergeSystematicEntries(existingAgents, bundledAgents, (key, agent) => bundledAgentKeys.has(key) && isSystematicAgentConfig(agent));
984
+ config.agent = mergeSystematicEntries(existingAgents, bundledAgents, (key, agent) => bundledAgentKeys.has(key) && isSystematicAgentConfig(agent) && !isSecuritySensitiveAgent(key), (key, present, emitted) => enforceSecuritySensitiveAgent(config, key, present, emitted));
906
985
  config.command = mergeSystematicEntries(existingCommands, plan.commands, (_key, command) => isSystematicCommandConfig(command));
907
986
  applyDiscoveredRouting(config, plan, reportedRouting);
908
987
  registerSkillsPaths(config, plan.skillsDir);
@@ -1863,41 +1942,6 @@ var installSkills = async ({
1863
1942
  await guard.async("skill output restore registration", () => ctx.session.hook("context", restore))();
1864
1943
  };
1865
1944
 
1866
- // src/lib/opencode-v2-tool-guard.ts
1867
- var READ_ONLY_AGENT_NAMES = [
1868
- "connections-researcher"
1869
- ];
1870
- var READ_ONLY_TOOL_ALLOWLIST = [
1871
- "read",
1872
- "grep",
1873
- "glob",
1874
- "skill",
1875
- "systematic_search",
1876
- "systematic_skill"
1877
- ];
1878
- var ALLOWED = { allowed: true };
1879
- function decideToolCall(agent, tool) {
1880
- if (typeof agent !== "string" || !READ_ONLY_AGENT_NAMES.includes(agent)) {
1881
- return ALLOWED;
1882
- }
1883
- if (typeof tool === "string" && READ_ONLY_TOOL_ALLOWLIST.includes(tool)) {
1884
- return ALLOWED;
1885
- }
1886
- const name = typeof tool === "string" ? tool : "unknown";
1887
- return {
1888
- allowed: false,
1889
- message: `The tool "${name}" is not available to the read-only ${agent} agent. It may call only: ${READ_ONLY_TOOL_ALLOWLIST.join(", ")}.`
1890
- };
1891
- }
1892
- function refuseOutsideAllowlist(event) {
1893
- const verdict = decideToolCall(event.agent, event.tool);
1894
- if (!verdict.allowed)
1895
- throw new Error(verdict.message);
1896
- }
1897
- var installToolGuard = async ({ ctx }) => {
1898
- await ctx.tool.hook("execute.before", refuseOutsideAllowlist);
1899
- };
1900
-
1901
1945
  // src/lib/opencode-v2.ts
1902
1946
  var DIAGNOSTIC_PREFIX = "systematic:";
1903
1947
  function describeFailure(error) {
@@ -1979,10 +2023,37 @@ function writeAgentFields(agent, planned, reported) {
1979
2023
  writeAgentModel(agent, planned, reported);
1980
2024
  agent.permissions.push(...agentPermissionRules(planned));
1981
2025
  }
2026
+ function readForeignModel(entry) {
2027
+ if (!isRecord(entry) || !isRecord(entry.model))
2028
+ return;
2029
+ const { providerID, id, variant } = entry.model;
2030
+ if (typeof providerID !== "string" || typeof id !== "string")
2031
+ return;
2032
+ return typeof variant === "string" ? { providerID, id, variant } : { providerID, id };
2033
+ }
2034
+ function replaceReadOnlyAgent(editor, planned, existing, reported) {
2035
+ const foreignModel = readForeignModel(existing);
2036
+ const key = `replaced:${planned.name}`;
2037
+ if (!reported.has(key)) {
2038
+ reported.add(key);
2039
+ console.error(`${DIAGNOSTIC_PREFIX} agent "${planned.name}" is also defined by the host or another plugin; applied Systematic's read-only definition and kept only that entry's model`);
2040
+ }
2041
+ editor.remove(planned.name);
2042
+ editor.update(planned.name, (agent) => {
2043
+ writeAgentFields(agent, planned, reported);
2044
+ if (foreignModel !== undefined)
2045
+ agent.model = foreignModel;
2046
+ });
2047
+ }
1982
2048
  function applyPlannedAgent(editor, planned, reported = new Set) {
1983
2049
  if (planned.config.disable === true)
1984
2050
  return;
1985
- if (editor.get(planned.name) !== undefined) {
2051
+ const existing = editor.get(planned.name);
2052
+ if (existing !== undefined) {
2053
+ if (READ_ONLY_AGENT_NAMES.includes(planned.name)) {
2054
+ replaceReadOnlyAgent(editor, planned, existing, reported);
2055
+ return;
2056
+ }
1986
2057
  const key = `clash:${planned.name}`;
1987
2058
  if (reported.has(key))
1988
2059
  return;
@@ -13,6 +13,8 @@ export interface ConfigHandlerDeps {
13
13
  /** OpenCode global config directory override for discovered-skill lookups. Defaults to `<homeDir>/.config/opencode`. */
14
14
  opencodeConfigDir?: string;
15
15
  }
16
+ /** Clear the once-per-process notice record and captured routing. For tests. */
17
+ export declare function resetSecuritySensitiveAgentNotices(): void;
16
18
  /**
17
19
  * Per-tool permission rule map as actually emitted by {@link foldPermissionRulesToV1Map}:
18
20
  * each key is a match pattern (`'*'` or an exact name) mapped to a setting.
@@ -86,7 +88,10 @@ export declare function toV1AgentConfig(planned: PlannedAgent): AgentConfig;
86
88
  *
87
89
  * Bundled content is loaded and then tuned with Systematic agent overlays.
88
90
  * Existing native OpenCode agents with the same emitted key are preserved as
89
- * replacements for bundled agents.
91
+ * replacements for bundled agents. The exception is a security-sensitive agent
92
+ * (see {@link isSecuritySensitiveAgent}): its Systematic definition is applied
93
+ * over any other entry of the same name, keeping only that entry's model and
94
+ * variant.
90
95
  */
91
96
  export declare function createConfigHandler(deps: ConfigHandlerDeps): (config: Config) => Promise<void>;
92
97
  /** Register a directory for OpenCode's native skill discovery (`skill` tool). */
@@ -349,6 +349,8 @@ export interface DigestModel {
349
349
  }>;
350
350
  readonly unread: readonly string[];
351
351
  readonly dropped: Readonly<Record<string, number>>;
352
+ /** Which candidates the counts in `dropped` lost, bounded by the run's candidate maximum. */
353
+ readonly droppedCandidates: readonly DroppedCandidate[];
352
354
  readonly discardedIncomplete: number;
353
355
  readonly candidates: readonly DigestCandidate[];
354
356
  readonly recorded: readonly RecordedConnection[];
@@ -362,6 +364,21 @@ export interface DigestModel {
362
364
  }
363
365
  /** Strip control and format characters. Line breaks stay; tabs become a space. */
364
366
  export declare function sanitizeText(text: string): string;
367
+ /**
368
+ * A candidate the checks refused, named so a person can tell whether a real
369
+ * finding was lost. It holds no model text except the title, which is display
370
+ * safe and capped like an accepted title.
371
+ */
372
+ export interface DroppedCandidate {
373
+ readonly family: string;
374
+ readonly kind: CandidateKind | 'unknown';
375
+ readonly title: string;
376
+ readonly reason: string;
377
+ }
378
+ /** What a dropped candidate shows as its title when it has none. */
379
+ export declare const NO_TITLE = "(no title)";
380
+ /** Name a dropped candidate from its raw form, which may be anything. */
381
+ export declare function nameDropped(family: string, raw: unknown, reason: string): DroppedCandidate;
365
382
  /**
366
383
  * Render the digest. All free text in it came from documents or from the
367
384
  * researcher, so it appears only as block quotes and fenced excerpts with
@@ -61,12 +61,14 @@ export interface V2AgentRecord {
61
61
  export interface V2AgentEditor {
62
62
  get(id: string): unknown;
63
63
  update(id: string, update: (agent: V2AgentRecord) => void): void;
64
+ remove(id: string): void;
64
65
  }
65
66
  /**
66
67
  * Create one planned agent on a transform editor. An id that already exists
67
- * belongs to the host or another plugin and is left alone. A same-named user
68
- * agent needs no check: user config applies after every plugin transform and
69
- * overlays what is created here.
68
+ * belongs to the host or another plugin and is left alone, except for an agent
69
+ * in `READ_ONLY_AGENT_NAMES`: that definition is replaced by ours. A same-named
70
+ * user agent needs no check for an ordinary agent: user config applies after
71
+ * every plugin transform and overlays what is created here.
70
72
  */
71
73
  export declare function applyPlannedAgent(editor: V2AgentEditor, planned: PlannedAgent, reported?: Set<string>): void;
72
74
  /**
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@fro.bot/systematic",
3
- "version": "3.32.1",
3
+ "version": "3.32.3",
4
4
  "description": "Compound-engineering loops for OpenCode, Pi, and Claude Code",
5
5
  "type": "module",
6
6
  "homepage": "https://fro.bot/systematic",
@@ -99,7 +99,7 @@
99
99
  },
100
100
  "peerDependencies": {
101
101
  "@opencode-ai/plugin": ">=1.18.29",
102
- "@opencode/plugin": ">=2.2.0",
102
+ "@opencode/plugin": ">=2.2.5",
103
103
  "@earendil-works/pi-coding-agent": "^1.0.0",
104
104
  "typebox": "^1.1.38"
105
105
  },
@@ -122,14 +122,14 @@
122
122
  "@earendil-works/pi-coding-agent": "1.5.0",
123
123
  "@opencode-ai/plugin": "1.19.5",
124
124
  "@opencode-ai/sdk": "1.19.5",
125
- "@opencode/client": "2.2.5",
126
- "@opencode/plugin": "2.2.5",
127
- "@opencode/sdk": "2.2.5",
125
+ "@opencode/client": "2.2.6",
126
+ "@opencode/plugin": "2.2.6",
127
+ "@opencode/sdk": "2.2.6",
128
128
  "@semantic-release/exec": "7.1.0",
129
129
  "@tintinweb/pi-subagents": "0.22.1",
130
130
  "@types/bun": "latest",
131
131
  "@types/js-yaml": "4.0.9",
132
- "@types/node": "26.6.6",
132
+ "@types/node": "24.19.2",
133
133
  "agent-browser": "0.39.4",
134
134
  "ajv": "8.20.0",
135
135
  "ajv-formats": "3.0.1",
@@ -152,10 +152,10 @@ JSON
152
152
 
153
153
  Copy `runId` and `lock` from the `begin` answer. List every batch file, in order; `"batches": []` when there were none.
154
154
 
155
- - `validated`: read `pendingOutcome`, `degradeReasons`, `accepted`, `recorded`, `suppressed`, `dropped`, `droppedTotal`, `coverage` and `sweep`. Go on to Step 7.
155
+ - `validated`: read `pendingOutcome`, `degradeReasons`, `accepted`, `recorded`, `suppressed`, `dropped`, `droppedTotal`, `droppedCandidates`, `coverage` and `sweep`. Go on to Step 7.
156
156
  - Any `failed` outcome, such as `malformed-batch`, `batch-version` or `invalid-request`: every failed `validate` reply has a `lockReleased` field. When it is `true`, the helper has released the lock and removed the work files. When it is not `true` (the reply says the lock was not released, or has no such field), run `ledger unlock` for this run before you stop, the way `references/headless-and-outcomes.md` shows; the lock is the one you took in Step 2, and this is the only case where the skill runs `ledger unlock` itself. Print the `reason`, then `Connect failed`. Do not publish.
157
157
 
158
- A dropped candidate never changes the outcome: it is counted by reason in the digest.
158
+ A dropped candidate never changes the outcome: it is counted by reason in the digest, which also names it by family, kind, reason and title.
159
159
 
160
160
  ## Step 7: Publish
161
161
 
@@ -62,7 +62,7 @@ The next step also decides the handoff the summary prints. A `compound-learning`
62
62
 
63
63
  ## What the helper checks
64
64
 
65
- Each candidate, in order. The first failure drops that candidate and counts it by reason; the outcome does not change.
65
+ Each candidate, in order. The first failure drops that candidate and counts it by reason; the outcome does not change. The reply, the digest and the run record also name each dropped candidate by family, kind, reason and its title (sanitized, capped at the title limit, `(no title)` when it has none), so a person can see whether a real finding was lost. The list holds no other candidate text and is bounded by the run's candidate maximum.
66
66
 
67
67
  - Every path is a tracked, contained file in an allowed project: not absolute, no `..`, not a symlink, not untracked.
68
68
  - Every fingerprint equals the hash the helper took at `begin`, and the file still has it.
@@ -42,7 +42,7 @@ Every run ends with exactly one of these lines as its last line. The reason and
42
42
  | Final line | When |
43
43
  |---|---|
44
44
  | `Connect complete` | `publish` answered `complete`: every project read, every offered rule covered by a complete family, nothing failed, and the run committed. Rules the run was not offered are not a degrade reason, and neither is the stale-citation check reaching its cap: the digest notes it under "Not read or not covered" and the run record keeps the counts, and the outcome is unchanged. Nothing found is still `complete`, labeled "no candidate in searched scope". |
45
- | `Connect degraded` | `publish` answered `degraded`: something was not read, an offered rule was not covered, a file a candidate cited changed or vanished during the run (`evidence-changed`, `unresolved-source`; the rule of that candidate is then not counted as covered), or a bound on the file inventory, a family or a batch was reached. The digest names what. A degraded run is never proof that nothing is there. |
45
+ | `Connect degraded` | `publish` answered `degraded`: something was not read, an offered rule was not covered, a file a candidate cited changed or vanished during the run (`evidence-changed`, `unresolved-source`; the rule of that candidate is then not counted as covered), or a bound on the file inventory, a family or a batch was reached. The digest names what. A degraded run is never proof that nothing is there. A dropped candidate never changes the outcome; the digest lists each one under "Dropped candidates" with its reason and quoted title, and the run record keeps the same list. |
46
46
  | `Connect busy` | `begin` answered `busy`: another run holds the lock, or the holder cannot be verified. Nothing was written and nothing was dispatched. |
47
47
  | `Connect failed` | Any other stop: a bad mode token, the helper missing, an unsupported host in headless mode, consent declined, no allowed projects, a malformed batch, or a helper error. Nothing was published. |
48
48
 
@@ -2,7 +2,7 @@
2
2
  // biome-ignore-all assist/source/organizeImports: generated bundle
3
3
  // Generated by scripts/generate-ce-connect-helper.ts; do not edit by hand.
4
4
  // Run `bun run ce-connect-helper:build` to regenerate.
5
- // source-digest: 07be8564b8fc91ee115aea440890933f5c2be97ffcfc4e34adb75525879f684b
5
+ // source-digest: 9b652bc13739937297f63e9284e288f7e230df862d2c573fa399e9f69e3cae21
6
6
  // src/ce-connect-helper.ts
7
7
  import { spawnSync as spawnSync3 } from 'node:child_process'
8
8
  import fs8 from 'node:fs'
@@ -1410,7 +1410,7 @@ var HOST_SUPPORT_TABLE = [
1410
1410
  },
1411
1411
  {
1412
1412
  host: 'opencode-v2',
1413
- version: '2.2.5',
1413
+ version: '2.2.6',
1414
1414
  observedBy:
1415
1415
  'tests/integration/opencode-v2.test.ts > a session-level allow does not lift the guarded researcher when a parent with that rule dispatches it',
1416
1416
  },
@@ -6566,6 +6566,28 @@ function sanitizeText(text) {
6566
6566
  : '',
6567
6567
  )
6568
6568
  }
6569
+ var NO_TITLE = '(no title)'
6570
+ function displayTitle(title) {
6571
+ if (typeof title !== 'string') return NO_TITLE
6572
+ const line = sanitizeText(title)
6573
+ .replaceAll(
6574
+ `
6575
+ `,
6576
+ ' ',
6577
+ )
6578
+ .trim()
6579
+ if (line === '') return NO_TITLE
6580
+ return Array.from(line).slice(0, CANDIDATE_LIMITS.title).join('').trimEnd()
6581
+ }
6582
+ function nameDropped(family, raw, reason) {
6583
+ const fields = isRecord2(raw) ? raw : {}
6584
+ return {
6585
+ family,
6586
+ kind: isKind(fields.kind) ? fields.kind : 'unknown',
6587
+ title: displayTitle(fields.title),
6588
+ reason,
6589
+ }
6590
+ }
6569
6591
  function quote(text) {
6570
6592
  return sanitizeText(text)
6571
6593
  .split(`
@@ -6747,6 +6769,25 @@ function renderHeader(model) {
6747
6769
  return out
6748
6770
  }
6749
6771
  var MAX_STALE_LISTED = 50
6772
+ function renderDroppedCandidates(model) {
6773
+ if (model.droppedCandidates.length === 0) return []
6774
+ const out = ['## Dropped candidates', '']
6775
+ for (const item of model.droppedCandidates) {
6776
+ out.push(
6777
+ `- ${item.reason}: ${item.kind} from ${inline(item.family)}`,
6778
+ ` ${quote(item.title)}`,
6779
+ )
6780
+ }
6781
+ const total = Object.values(model.dropped).reduce((a, b) => a + b, 0)
6782
+ const unlisted = total - model.droppedCandidates.length
6783
+ if (unlisted > 0) {
6784
+ out.push(
6785
+ `- ${unlisted} more dropped candidates are counted above but not listed.`,
6786
+ )
6787
+ }
6788
+ out.push('')
6789
+ return out
6790
+ }
6750
6791
  function renderStale(model) {
6751
6792
  const out = ['## Stale citations', '']
6752
6793
  if (model.staleCitations.length === 0) {
@@ -6807,7 +6848,7 @@ function renderDigest(model) {
6807
6848
  '',
6808
6849
  )
6809
6850
  }
6810
- out.push(...renderStale(model))
6851
+ out.push(...renderDroppedCandidates(model), ...renderStale(model))
6811
6852
  return `${out
6812
6853
  .join(`
6813
6854
  `)
@@ -8297,6 +8338,7 @@ function isValidated(value) {
8297
8338
  typeof value.runId === 'string' &&
8298
8339
  Array.isArray(value.accepted) &&
8299
8340
  Array.isArray(value.recorded) &&
8341
+ Array.isArray(value.droppedCandidates) &&
8300
8342
  Array.isArray(value.coveredRuleIds) &&
8301
8343
  isRecord4(value.sweep) &&
8302
8344
  Array.isArray(value.degradeReasons)
@@ -8864,6 +8906,14 @@ function contextFrom(snapshot) {
8864
8906
  function count(table, key, by = 1) {
8865
8907
  table[key] = (table[key] ?? 0) + by
8866
8908
  }
8909
+ function recordDrop(result, family, raw, reason) {
8910
+ count(result.dropped, reason)
8911
+ noteDropped(result, family, raw, reason)
8912
+ }
8913
+ function noteDropped(result, family, raw, reason) {
8914
+ if (result.droppedCandidates.length >= result.droppedListLimit) return
8915
+ result.droppedCandidates.push(nameDropped(family, raw, reason))
8916
+ }
8867
8917
  function standingOf(outcome) {
8868
8918
  if (outcome.standing === 'new') {
8869
8919
  return { standing: 'new', possible: [...outcome.possibleMatches] }
@@ -8916,10 +8966,10 @@ function holdBack(raw, input, result) {
8916
8966
  result.heldBackRuleIds.add(ruleId)
8917
8967
  }
8918
8968
  }
8919
- function classifyOne(raw, input, seen, result) {
8969
+ function classifyOne(raw, family, input, seen, result) {
8920
8970
  const check = checkCandidate(raw, input.ctx)
8921
8971
  if (check.status === 'dropped') {
8922
- count(result.dropped, check.reason)
8972
+ recordDrop(result, family, raw, check.reason)
8923
8973
  if (check.reason === 'changed-since-begin') {
8924
8974
  addUnique(result.degrade, 'evidence-changed')
8925
8975
  holdBack(raw, input, result)
@@ -8934,7 +8984,7 @@ function classifyOne(raw, input, seen, result) {
8934
8984
  const record = toCandidateRecord(check.candidate)
8935
8985
  const identity = candidateIdentity(record)
8936
8986
  if (seen.has(identity)) {
8937
- count(result.dropped, 'duplicate-candidate')
8987
+ recordDrop(result, family, raw, 'duplicate-candidate')
8938
8988
  return
8939
8989
  }
8940
8990
  seen.add(identity)
@@ -8953,6 +9003,8 @@ function classifyBatches(batches, input, limits) {
8953
9003
  accepted: [],
8954
9004
  recorded: [],
8955
9005
  dropped: {},
9006
+ droppedCandidates: [],
9007
+ droppedListLimit: limits.maxFamiliesPerRun * limits.maxCandidatesPerBatch,
8956
9008
  suppressed: 0,
8957
9009
  unresolved: 0,
8958
9010
  discardedIncomplete: 0,
@@ -8960,6 +9012,7 @@ function classifyBatches(batches, input, limits) {
8960
9012
  heldBackRuleIds: new Set(),
8961
9013
  }
8962
9014
  const seen = new Set()
9015
+ const overflow = []
8963
9016
  for (const batch of batches) {
8964
9017
  if (batch.ruleIds.length > limits.maxRulesPerFamily) {
8965
9018
  addUnique(result.degrade, 'family-bound')
@@ -8974,7 +9027,15 @@ function classifyBatches(batches, input, limits) {
8974
9027
  count(result.dropped, 'over-batch-cap', over)
8975
9028
  addUnique(result.degrade, 'candidate-bound')
8976
9029
  }
8977
- for (const raw of considered) classifyOne(raw, input, seen, result)
9030
+ for (const raw of considered) {
9031
+ classifyOne(raw, batch.family, input, seen, result)
9032
+ }
9033
+ for (const raw of batch.candidates.slice(considered.length)) {
9034
+ overflow.push({ family: batch.family, raw })
9035
+ }
9036
+ }
9037
+ for (const item of overflow) {
9038
+ noteDropped(result, item.family, item.raw, 'over-batch-cap')
8978
9039
  }
8979
9040
  return result
8980
9041
  }
@@ -9041,6 +9102,7 @@ function validateResponse(runId, state, classified) {
9041
9102
  unresolved: classified.unresolved,
9042
9103
  dropped: classified.dropped,
9043
9104
  droppedTotal,
9105
+ droppedCandidates: classified.droppedCandidates,
9044
9106
  discardedIncomplete: classified.discardedIncomplete,
9045
9107
  coverage: state.coverage,
9046
9108
  offered:
@@ -9111,6 +9173,7 @@ function runValidation(snapshot, workDir, batchesRead, ledger, deps) {
9111
9173
  ),
9112
9174
  ],
9113
9175
  dropped: classified.dropped,
9176
+ droppedCandidates: classified.droppedCandidates,
9114
9177
  discardedIncomplete: classified.discardedIncomplete,
9115
9178
  suppressed: classified.suppressed,
9116
9179
  unresolved: classified.unresolved,
@@ -9238,6 +9301,7 @@ function digestModel(snapshot, state, outcome, degradeReasons) {
9238
9301
  unmatched: snapshot.unmatched,
9239
9302
  unread: state.unread,
9240
9303
  dropped: state.dropped,
9304
+ droppedCandidates: state.droppedCandidates,
9241
9305
  discardedIncomplete: state.discardedIncomplete,
9242
9306
  candidates: digestCandidates,
9243
9307
  recorded: state.recorded,
@@ -9285,6 +9349,7 @@ function runRecord(snapshot, state, outcome, degradeReasons) {
9285
9349
  droppedTotal,
9286
9350
  discardedIncomplete: state.discardedIncomplete,
9287
9351
  },
9352
+ droppedCandidates: state.droppedCandidates,
9288
9353
  coverage: state.coverage,
9289
9354
  batches: state.batches,
9290
9355
  candidateBlock: buildCandidateBlock(state.accepted),