@fro.bot/systematic 3.32.3 → 3.33.0

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,7 +29,7 @@ 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.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.
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. CI runs the v2 pin, not the floor; no CI job runs a v2 release older than the floor, and the `execute.before` hook that the `ce:connect` tool guard relies on has been observed only on the floor and later pins.
33
33
 
34
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.
35
35
 
@@ -46,7 +46,7 @@ Each v2 mechanism was chosen by a probe against OpenCode 2.2.0 on 2026-10-27. Th
46
46
  | Output truncation | Truncates | The host cuts tool output at 2000 lines or 51200 bytes after the plugin's `execute.after` hook sees the full text. The full text is kept by call id and put back in the `context` hook; nothing depends on the marker text | [OC2-TRUNC] |
47
47
  | Commands | Passed, with constraints | `ctx.command.transform`; a plugin command receives only the typed text and does its own expansion; routing is not offered to plugin commands, so a bundled command that declares `agent`, `model` or `subtask` is refused, while a discovered skill's fields are dropped with a note; a name that matches a built-in replaces it | [OC2-CMD] |
48
48
  | Apply order | Documented | Plugin transforms run first, then user config and discovered sources; `reload()` replays transforms on a fresh editor and does not re-run `setup` | [OC2-ORDER] |
49
- | Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Every callback is guarded, except the read-only tool guard, whose installer runs outside the never-throw wrapper so a failed registration holds its agents back and whose hook throws on purpose, and invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
49
+ | Error handling | Documented | A rejected `setup` leaves the plugin unloaded and the host running; a throwing transform disables the whole plugin; a throwing hook breaks the turn. Ordinary installers and the callbacks they register are guarded and never throw. The read-only tool guard is the exception and fails closed: its installer runs first and outside the never-throw wrapper, so a failed registration reports once and withholds its agents, and its hook throws on purpose. Invalid config rejects `setup` as it throws on v1 | [OC2-ERR] |
50
50
  | Project directory | Documented | `ctx.location.directory` is the project directory (the service's working directory is not); each location gets a fresh module instance and its own `setup` | [OC2-TRUST] |
51
51
  | Task tracking tool | Conditional, unobserved | Binary strings name a `todowrite` tool behind the experimental `todo` option; no live request showed it | [OC2-TODO] |
52
52
 
@@ -98,7 +98,7 @@ Systematic ships its own search over four kinds of durable output: `docs/solutio
98
98
 
99
99
  Evidence tiers differ by host, and this file does not claim more than the tests do:
100
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].
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.
101
+ - **Real-host tests:** OpenCode v1 on the floor (1.18.29) and current lanes, and OpenCode v2 at the pinned version, each call the tool through a real host [SR-2]. CI runs them in the host-contract jobs.
102
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.
103
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].
104
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,12 +108,12 @@ Evidence tiers differ by host, and this file does not claim more than the tests
108
108
 
109
109
  The `ce:connect` skill dispatches `connections-researcher`, an agent that must not run shell commands, write, edit or fetch. Each host enforces that differently, so a host and version counts as supported only after a deny was observed on that host: the shipped researcher is dispatched, a scripted model calls shell, write, edit and web fetch, each is refused, a read succeeds and reaches the parent, and the planted marker file is never written. A negative control removes the limits and the proof fails under its own name. The supported pairs are in `HOST_SUPPORT_TABLE` in `src/lib/connect-config.ts`; each row names the test that observed it in `observedBy`. A definition test is a regression pin and is never counted as proof.
110
110
 
111
- | Host | Version | Mechanism | Support evidence |
112
- |---|---|---|---|
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] |
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] |
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. |
111
+ | Host | Mechanism | Support evidence |
112
+ |---|---|---|
113
+ | OpenCode v1 | `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 | 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] |
115
+ | Pi | 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] |
116
+ | Claude Code | 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. |
117
117
 
118
118
  What the evidence does not show: a scripted model makes the calls, so these proofs show enforcement plumbing, not live model choice. Read tools are not path-scoped on any host and session MCP tools are not denied; the guide documents both as limits. The v1 floor (1.18.29) has no row and is not run against this proof.
119
119
 
@@ -232,7 +232,7 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
232
232
  - **OC-3** — cloned OpenCode source, `.slim/clonedeps/repos/anomalyco__opencode/packages/core/src/tool/todowrite.ts:1-10`.
233
233
  - **OC-4** — `src/lib/asset-plan.ts:223-234` (`loadSkillAsCommand`), `:532-551` (bundled skills as `systematic:<name>` commands), `:553-618` (discovered skills as commands); `src/lib/config-handler.ts:367-377` (`registerSkillsPaths`, the v1 skill path); `src/lib/config-handler.ts:188-274` (the v1 config hook that writes the plan into the host config); `src/lib/config-handler.ts:112-170` (`foldPermissionRulesToV1Map`, which writes each managed skill allow under both the bare and the `systematic:` name unless the user wrote a rule for the prefixed name, because v1's native `skill` tool asks with the bare name and `systematic_skill` with the prefixed one); `src/lib/config-handler.ts:276-360` (`denyDisabledSkills`, the top-level `permission.skill` deny in both name forms for each disabled skill, because the registered skills folder is not filtered). Real v1 host, 1.19.4: `tests/integration/opencode-v1.test.ts` (a managed `skills` list loads through `systematic_skill`; the native `skill` tool refuses a disabled skill).
234
234
  - **OC-5** — `src/lib/skill-tool.ts:146-230` (`createSkillTool`, the v1 tool with the `context.ask` permission check at `:198-203`).
235
- - **OC-6** — `ARCHITECTURE.md:217-223` (invariant 2) and `agents/`.
235
+ - **OC-6** — `ARCHITECTURE.md:255-261` (invariant 2) and `agents/`.
236
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).
237
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).
238
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.
@@ -298,6 +298,6 @@ Migrated-skill discipline is enforced by the [content-integrity gate](scripts/co
298
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.
299
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.
300
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.
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.
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 rejects, so `setupOpenCodeV2` can catch it and withhold the guarded agents); `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.
302
302
  - **CN-4** — Pi 1.5.0: `tests/unit/pi-delegate-session.test.ts` › "the shipped researcher reaches createAgentSession with read, grep and find and none of bash, write, edit or systematic_delegate" (the `observedBy` for this row; the real session builder runs against a fake runtime and the test asserts the `tools` that reach `createAgentSession`, not the mock); `tests/integration/pi.test.ts` › "a family completes inside the delegate turn cap with read, search and find tools only, and its batch validates" and "a child that never answers stops at the turn cap and the family is degraded, not empty" (the real Pi runtime, run in the v2 host-contract profile). Scope limit: the delegate is capped at 20 turns, and a scripted model drives the integration tests.
303
303
  - **CN-5** — Manual evidence, not a CI check. Recorded 2026-11-08 with Claude Code 2.1.319 (`claude --version` prints `2.1.319 (Claude Code)`), run by hand with the plugin bundle built from the rebased branch head and a live model. Verdict PASS. Run A dispatched `systematic:connections-researcher` through the `Agent` tool: the subagent reported its tools as Read, Grep and Glob, read a planted file and returned its marker, skipped Bash, Write, Edit and WebFetch as unavailable, and never called any of them (the checker found no call to Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit). Run B started a session with `claude --agent systematic:connections-researcher`: the session's init message listed Read, Grep and Glob as its tools, none of Bash, Write, Edit, WebFetch, WebSearch or NotebookEdit, and no MCP tools; the read worked and its marker reached the answer. The `HOST_SUPPORT_TABLE` row names this entry as its `observedBy`. Limits: one live model on one Claude Code version; in run A the denial is the subagent's own report, because it never called the tools, and the host's own statement comes from run B's session tool list; the read tools are not path-scoped; whether a dispatched subagent can reach its parent session's MCP tools was not tested. `tests/unit/connect-host-isolation.test.ts` › "claude plugin validate accepts the definition and rejects one that does not parse" remains a parse check only, because an agent whose frontmatter fails to parse loads without its limits. Upstream issue reports 58645 and 94202 (cited from the research behind this feature, not re-checked) describe `disallowedTools` not being enforced for plugin and subagent Bash, so the agent leads with the positive `tools` allowlist.
@@ -1,6 +1,6 @@
1
1
  import { type ConnectConfigOptions, type HostSupportRow } from './lib/connect-config.js';
2
2
  import { type ConnectBounds } from './lib/connect-evidence.js';
3
- import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
3
+ import { type InvocationWriteOptions, type ProcessTable, type PublishOptions } from './lib/connect-state.js';
4
4
  /**
5
5
  * Entry point for the generated, self-contained `ce:connect` helper
6
6
  * (`skills/ce-connect/scripts/connect.mjs`).
@@ -17,7 +17,7 @@ import { type ProcessTable, type PublishOptions } from './lib/connect-state.js';
17
17
  * file the skill writes in the run's work directory, read here through the
18
18
  * bounded reader as a regular file.
19
19
  */
20
- export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|ledger show [--offset N]|ledger clear|ledger unlock>";
20
+ export declare const CE_CONNECT_USAGE = "Usage: node connect.mjs <begin|validate|publish|decide|import|apply-ticks|render-report|ledger show [--offset N]|ledger clear|ledger unlock>";
21
21
  export interface HelperDeps {
22
22
  /** Environment for `XDG_STATE_HOME`. Defaults to `process.env`. */
23
23
  readonly env?: Readonly<Record<string, string | undefined>>;
@@ -34,6 +34,8 @@ export interface HelperDeps {
34
34
  readonly inspector?: ProcessInspector;
35
35
  /** Seams in the middle of a publish, for tests of a crash or a failed write. */
36
36
  readonly publishHooks?: NonNullable<PublishOptions['hooks']>;
37
+ /** Seams in the write of the invocation record, for tests of a failed write. */
38
+ readonly invocationHooks?: InvocationWriteOptions;
37
39
  }
38
40
  export interface HelperResult {
39
41
  readonly ok: boolean;
package/dist/cli.js CHANGED
@@ -48,7 +48,7 @@ import {
48
48
  SEARCH_NOTICES,
49
49
  SEARCH_CONFIG_UNREADABLE_NOTE,
50
50
  runSearch
51
- } from "./index-nrbdgp4m.js";
51
+ } from "./index-1cj1mrpb.js";
52
52
  var __defProp = Object.defineProperty;
53
53
  var __returnValue = (v) => v;
54
54
  function __exportSetter(name, newValue) {
@@ -7621,6 +7621,8 @@ function isAllowedProject(identity, allowList, options = {}) {
7621
7621
  var MAX_ALLOW_PROJECTS = 64;
7622
7622
  var MAX_ALLOW_PROJECT_LENGTH = 4096;
7623
7623
  var MAX_CONNECT_CONFIG_BYTES = 1024 * 1024;
7624
+ var MAX_CONNECT_GROUPS = 32;
7625
+ var CONNECT_GROUP_NAME_PATTERN = /^[a-z0-9][a-z0-9-]{0,63}$/;
7624
7626
 
7625
7627
  // src/lib/removed-names.ts
7626
7628
  var REMOVED_BUNDLED_SKILL_NAMES = [
@@ -8752,11 +8754,30 @@ var ConnectSettingsSchema = trustProtected(object({
8752
8754
  allow_projects: array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).max(MAX_ALLOW_PROJECTS).optional().meta({
8753
8755
  description: `Main repository roots that \`ce:connect\` may read for contradictions and transferable lessons. Each entry is an absolute or \`~\`-prefixed path to the root of a repository checkout, not a subdirectory and not a linked worktree. At most ${MAX_ALLOW_PROJECTS} entries; an entry that matches no repository is reported by the run and does not widen the list. The lists in user, user.local, custom and custom.local config are merged as a union. Omitted or empty, it allows no project.`,
8754
8756
  examples: [["~/src/github.com/me/app", "/srv/checkouts/shared-lib"]]
8757
+ }),
8758
+ groups: record(string().regex(CONNECT_GROUP_NAME_PATTERN), array(string().min(1).max(MAX_ALLOW_PROJECT_LENGTH)).min(1).max(MAX_ALLOW_PROJECTS)).refine((groups) => Object.keys(groups).length <= MAX_CONNECT_GROUPS).optional().meta({
8759
+ description: `Named subsets of the allow list that \`ce:connect\` can be narrowed to with \`group:<name>\`. A group name is 1 to 64 characters of lowercase letters, digits and hyphens, led by a letter or digit (\`${CONNECT_GROUP_NAME_PATTERN.source}\`). Each group lists at least one and at most ${MAX_ALLOW_PROJECTS} members in the same form as an \`allow_projects\` entry. At most ${MAX_CONNECT_GROUPS} groups per file. A group never adds a project: a member that is not on the allow list stops the run that selects the group. Groups merge by name across user, user.local, custom and custom.local config, and a later file replaces a same-named group whole.`,
8760
+ examples: [
8761
+ {
8762
+ "harness-tools": [
8763
+ "~/src/github.com/me/app",
8764
+ "/srv/checkouts/shared-lib"
8765
+ ]
8766
+ }
8767
+ ],
8768
+ maxProperties: MAX_CONNECT_GROUPS
8755
8769
  })
8756
8770
  }).strict().meta({
8757
- description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list.",
8771
+ description: "Cross-project connections. User-owned only: valid in user config or OPENCODE_CONFIG_DIR config, and a project config setting it has the whole block ignored with a warning, because a repository cannot grant itself access to other projects. A block with an unknown key or a bad value is unreadable and counts as an empty allow list and no groups.",
8758
8772
  examples: [
8759
8773
  { allow_projects: ["~/src/github.com/me/app"] },
8774
+ {
8775
+ allow_projects: [
8776
+ "~/src/github.com/me/app",
8777
+ "~/src/github.com/me/lib"
8778
+ ],
8779
+ groups: { "harness-tools": ["~/src/github.com/me/app"] }
8780
+ },
8760
8781
  { allow_projects: [] }
8761
8782
  ]
8762
8783
  }));
@@ -10515,9 +10536,20 @@ function mergeConnect(sources) {
10515
10536
  const blocks = sources.flatMap((source) => source.config.connect === undefined ? [] : [source.config.connect]);
10516
10537
  if (blocks.length === 0)
10517
10538
  return {};
10539
+ const groups = {};
10540
+ let hasGroups = false;
10541
+ for (const block of blocks) {
10542
+ if (block.groups === undefined)
10543
+ continue;
10544
+ hasGroups = true;
10545
+ for (const [name, members] of Object.entries(block.groups)) {
10546
+ groups[name] = [...members];
10547
+ }
10548
+ }
10518
10549
  return {
10519
10550
  connect: {
10520
- allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), [])
10551
+ allow_projects: blocks.reduce((merged, block) => mergeArraysUnique(merged, block.allow_projects), []),
10552
+ ...hasGroups && { groups }
10521
10553
  }
10522
10554
  };
10523
10555
  }
package/dist/index.js CHANGED
@@ -26,7 +26,7 @@ import {
26
26
  SEARCH_NOTICES,
27
27
  SEARCH_CONFIG_UNREADABLE_NOTE,
28
28
  runSearch
29
- } from "./index-nrbdgp4m.js";
29
+ } from "./index-1cj1mrpb.js";
30
30
 
31
31
  // src/index.ts
32
32
  import path8 from "path";
@@ -401,6 +401,7 @@ export declare function createSystematicConfigSchema(opts: SystematicConfigSchem
401
401
  }, z.core.$strict>>;
402
402
  connect: z.ZodOptional<z.ZodObject<{
403
403
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
404
+ groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
404
405
  }, z.core.$strict>>;
405
406
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
406
407
  [x: string]: string;
@@ -613,6 +614,7 @@ export declare const SystematicConfigSchema: z.ZodObject<{
613
614
  }, z.core.$strict>>;
614
615
  connect: z.ZodOptional<z.ZodObject<{
615
616
  allow_projects: z.ZodOptional<z.ZodArray<z.ZodString>>;
617
+ groups: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodArray<z.ZodString>>>;
616
618
  }, z.core.$strict>>;
617
619
  disabled_skills: z.ZodDefault<z.ZodArray<z.ZodEnum<{
618
620
  [x: string]: string;
@@ -201,8 +201,9 @@ export interface SystematicConfig {
201
201
  searchUnreadable?: boolean;
202
202
  /**
203
203
  * Merged `connect` settings from user and custom config only: the
204
- * `allow_projects` lists of every layer that sets one, as a union. Absent
205
- * when no layer sets the block, which allows no project. A project
204
+ * `allow_projects` lists of every layer that sets one, as a union, and the
205
+ * `groups` by name with a later layer replacing a same-named group whole.
206
+ * Absent when no layer sets the block, which allows no project. A project
206
207
  * config's `connect` is stripped at load with a warning and never appears
207
208
  * here. The `ce:connect` helper reads the same files itself
208
209
  * (`loadConnectAllowList`) and never consults this value.
@@ -0,0 +1,189 @@
1
+ /**
2
+ * The CI side of `ce:connect`: the report a scheduled run posts, and the ticks
3
+ * an operator leaves on it. One module defines the report format, so what
4
+ * `render-report` writes is exactly what `apply-ticks` reads.
5
+ *
6
+ * Trust: every file read here is untrusted input, including the state the CI
7
+ * run itself wrote. The run record, the invocation record, the candidate
8
+ * payload store, the manifest store and the report body each get bounded
9
+ * reads, typed fields and named keys only. Model text reaches the report in
10
+ * fences only, with mentions, issue references and comment delimiters broken
11
+ * so nothing in it can notify, link or write a marker.
12
+ *
13
+ * A decision comes from one place: a checkbox line the renderer generated,
14
+ * inside the single delimited section, outside any code fence, whose id is in
15
+ * the manifest of the report that was read and whose candidate is still open.
16
+ * The manifest of a report is stored under the hash its body carries, so a
17
+ * report that was posted keeps its own manifest even when a later render
18
+ * failed to post or posted something else.
19
+ *
20
+ * Import rule: node builtins and the `connect-*` modules. The `ce:connect`
21
+ * helper bundles this module, so it must never import zod, `config.ts` or
22
+ * `config-schema.ts`.
23
+ *
24
+ * Layout in the state root, next to the ledger:
25
+ *
26
+ * ci-payloads.json the text of each open candidate (the ledger holds none)
27
+ * ci-manifests.json the candidate ids of the last fourteen reports
28
+ * report.md the report body the last render wrote
29
+ *
30
+ * Neither operation reads the network or the clock: the date and the GitHub
31
+ * run come from the caller.
32
+ */
33
+ import { type LockBusyReason, type ProcessTable } from './connect-state.js';
34
+ /** A report body is never longer than this many characters. */
35
+ export declare const REPORT_MAX_CHARS = 60000;
36
+ /** The manifests kept: the newest reports a person can still be looking at. */
37
+ export declare const MANIFESTS_KEPT = 14;
38
+ export declare const REPORT_FILE = "report.md";
39
+ export declare const PAYLOAD_FILE = "ci-payloads.json";
40
+ export declare const MANIFEST_FILE = "ci-manifests.json";
41
+ export declare const DECISIONS_BEGIN = "<!-- connect-decisions:begin -->";
42
+ export declare const DECISIONS_END = "<!-- connect-decisions:end -->";
43
+ export type DecisionStatus = 'promoted' | 'rejected';
44
+ /** `<!-- connect-manifest:<hash> -->`: which stored manifest this body was rendered with. */
45
+ export declare function manifestMarker(hash: string): string;
46
+ /** One generated checkbox line. The marker carries the id; nothing else on the line is read. */
47
+ export declare function decisionLine(id: string, status: DecisionStatus, ticked: boolean): string;
48
+ export interface CiOptions {
49
+ readonly processes?: ProcessTable;
50
+ readonly now?: () => number;
51
+ }
52
+ /**
53
+ * Make model text inert in a GitHub issue. Control and format characters go,
54
+ * and a zero-width space breaks each thing the page would act on: `@` (a
55
+ * mention), `#` before a digit and `GH-` before a digit (an issue reference,
56
+ * alone or after `owner/repo`), and the delimiters of an HTML comment, so
57
+ * text cannot write a marker. Removing the zero-width spaces gives back the
58
+ * original text.
59
+ */
60
+ export declare function neutraliseText(text: string): string;
61
+ /** Neutralised text in a fenced block whose fence is longer than any backtick run inside it. */
62
+ export declare function fenceText(text: string): string;
63
+ export type BodySection = 'ok' | 'missing' | 'malformed';
64
+ export interface ParsedBox {
65
+ readonly id: string;
66
+ readonly status: DecisionStatus;
67
+ readonly ticked: boolean;
68
+ }
69
+ export interface ParsedBody {
70
+ /** The hash in the manifest marker, when the body has exactly one. */
71
+ readonly manifest: string | undefined;
72
+ readonly section: BodySection;
73
+ /** The generated checkbox lines inside the section, in document order. */
74
+ readonly boxes: readonly ParsedBox[];
75
+ }
76
+ /**
77
+ * Read a report body. Only exact generated lines count, only inside the one
78
+ * delimited section, and never inside a code fence. A body with a delimiter
79
+ * missing, repeated or out of order has no section, and a body with no marker
80
+ * or more than one marker has no manifest.
81
+ */
82
+ export declare function parseReportBody(body: string): ParsedBody;
83
+ export type BodyRead = {
84
+ readonly status: 'ok';
85
+ readonly body: string;
86
+ } | {
87
+ readonly status: 'failed';
88
+ readonly reason: 'body-missing' | 'body-symlink' | 'body-not-regular' | 'body-too-large' | 'body-unreadable';
89
+ };
90
+ /** Read a report body from a file: one bounded regular file, never a symlink. */
91
+ export declare function readReportBody(file: string): BodyRead;
92
+ export type ReportOutcome = 'complete' | 'degraded' | 'busy' | 'failed' | 'no-final-line';
93
+ export interface RenderRequest {
94
+ /** The UTC date of the report, `YYYY-MM-DD`. */
95
+ readonly date: string;
96
+ /** The GitHub run id and attempt of this workflow run. */
97
+ readonly runId: string;
98
+ readonly attempt: string;
99
+ /** Whether an Actions cache was restored for this run. */
100
+ readonly cacheRestored: boolean;
101
+ }
102
+ export type RenderResult = {
103
+ readonly status: 'rendered';
104
+ readonly body: string;
105
+ readonly bodyFile: string;
106
+ /** The hash in the body's manifest marker. */
107
+ readonly manifest: string;
108
+ readonly open: number;
109
+ readonly shown: number;
110
+ readonly hidden: number;
111
+ /** Candidates listed for the first time on this date. */
112
+ readonly fresh: number;
113
+ /** The GitHub runs the listed candidates came from, in the order they appear. */
114
+ readonly runs: readonly string[];
115
+ readonly outcome: ReportOutcome;
116
+ /** The workflow job turns red after posting. */
117
+ readonly red: boolean;
118
+ /** False when the report was rendered without the lock and recorded no payload or manifest. */
119
+ readonly stateUpdated: boolean;
120
+ } | {
121
+ readonly status: 'busy';
122
+ readonly reason: LockBusyReason;
123
+ } | {
124
+ readonly status: 'failed';
125
+ readonly reason: 'invalid-request' | 'lock-failed' | 'ledger-unreadable' | 'no-invocation' | 'payload-store-unreadable' | 'payload-store-too-large' | 'manifest-store-unreadable' | 'write-failed';
126
+ };
127
+ /**
128
+ * Render the report body for the state in `root`: the open candidates of the
129
+ * ledger, oldest first, as many as fit under the cap, each with its two
130
+ * boxes. Updates the payload store and the manifest store and writes the body
131
+ * to `report.md`. It needs this workflow run's invocation record (the marker
132
+ * `<run>-<attempt>`); without one it writes nothing. A run that ended `busy`
133
+ * is still reported when a live holder keeps the lock: the ledger is read
134
+ * without it, only `report.md` is written, and the body says the state was
135
+ * not updated.
136
+ */
137
+ export declare function renderReport(root: string, request: RenderRequest, options?: CiOptions): RenderResult;
138
+ export interface TickOptions extends CiOptions {
139
+ readonly hooks?: {
140
+ /** Runs after the ticks are sorted and before the first one is recorded. */
141
+ readonly afterTriage?: () => void;
142
+ };
143
+ }
144
+ export interface TickRequest {
145
+ /** The report body as the issue holds it now. */
146
+ readonly body: string;
147
+ /** The report's issue number; it goes into the reason a decision records. */
148
+ readonly issue: number;
149
+ }
150
+ export interface AcceptedTick {
151
+ readonly id: string;
152
+ readonly status: DecisionStatus;
153
+ }
154
+ export type SkipReason = 'conflict' | 'not-in-manifest' | 'not-open' | 'already-recorded';
155
+ export interface SkippedTick {
156
+ readonly id: string;
157
+ readonly status?: DecisionStatus;
158
+ readonly reason: SkipReason;
159
+ }
160
+ export type UnresolvedReason = 'manifest-missing' | 'unknown-candidate';
161
+ export interface UnresolvedTick {
162
+ readonly id: string;
163
+ readonly status: DecisionStatus;
164
+ readonly reason: UnresolvedReason;
165
+ }
166
+ export type TickResult = {
167
+ readonly status: 'applied';
168
+ readonly section: BodySection;
169
+ readonly accepted: readonly AcceptedTick[];
170
+ readonly skipped: readonly SkippedTick[];
171
+ readonly unresolved: readonly UnresolvedTick[];
172
+ } | {
173
+ readonly status: 'busy';
174
+ readonly reason: LockBusyReason;
175
+ readonly accepted: readonly AcceptedTick[];
176
+ } | {
177
+ readonly status: 'failed';
178
+ readonly reason: 'invalid-request' | 'ledger-unreadable' | 'lock-failed' | 'write-failed';
179
+ readonly accepted: readonly AcceptedTick[];
180
+ };
181
+ /**
182
+ * Record the ticks of a report body. A tick counts when its box is a generated
183
+ * line in the section of the body, its id is in the manifest the body names,
184
+ * and the candidate is open; a decision already recorded with the same reason
185
+ * is left as it is, so a second pass changes nothing. Each decision is made
186
+ * only if the candidate is still open under the lock, so one recorded since
187
+ * the ledger was read is skipped as `not-open`, never overwritten.
188
+ */
189
+ export declare function applyTicks(root: string, request: TickRequest, options?: TickOptions): TickResult;
@@ -12,6 +12,11 @@
12
12
  * imports the limits from here and tags the same block `trust:
13
13
  * 'project-or-higher'`; the dependency runs one way.
14
14
  *
15
+ * The block also holds named `groups` of allow-list-form entries. A group
16
+ * narrows a run to part of the allow list and never adds a project: nothing
17
+ * here checks that a member is on the allow list; the selection step does,
18
+ * on resolved main roots.
19
+ *
15
20
  * Trust: `connect` is user-only. User config, `OPENCODE_CONFIG_DIR` config and
16
21
  * the `systematic.local` file beside each may set it. `config.ts` strips it
17
22
  * from project config with a warning, and this reader never opens a project
@@ -21,8 +26,9 @@
21
26
  * a list over its limit makes that layer's block unreadable, and an
22
27
  * unreadable block contributes no entries. A missing, unparseable, oversize
23
28
  * or non-regular file contributes none either. No failure can add an entry
24
- * the user did not write. The four layers merge by union, so a layer that
25
- * fails drops only its own entries.
29
+ * the user did not write. The four layers merge, the allow lists by union and
30
+ * the groups by name (a later layer replaces a same-named group whole), so a
31
+ * layer that fails drops only its own entries and groups.
26
32
  *
27
33
  * Warnings name config files and reasons, never an allow-list entry: an entry
28
34
  * is a project the user chose to expose, and a warning can reach logs and
@@ -34,21 +40,30 @@ export declare const MAX_ALLOW_PROJECTS = 64;
34
40
  export declare const MAX_ALLOW_PROJECT_LENGTH = 4096;
35
41
  /** Largest config file the reader accepts. A larger file is unreadable. */
36
42
  export declare const MAX_CONNECT_CONFIG_BYTES: number;
43
+ /** One config layer holds at most this many groups. */
44
+ export declare const MAX_CONNECT_GROUPS = 32;
45
+ /** A group name: lowercase letters, digits and hyphens, one to 64 characters, led by a letter or digit. */
46
+ export declare const CONNECT_GROUP_NAME_PATTERN: RegExp;
47
+ /** Group name to member list. A member has the form of an allow-list entry. */
48
+ export type ConnectGroups = Record<string, string[]>;
37
49
  export interface ConnectSettings {
38
50
  allow_projects: string[];
51
+ groups?: ConnectGroups;
39
52
  }
40
53
  export type ConnectBlockValidation = {
41
54
  readonly ok: true;
42
55
  readonly allowProjects: string[];
56
+ readonly groups: ConnectGroups;
43
57
  } | {
44
58
  readonly ok: false;
45
59
  };
46
60
  /**
47
61
  * Validate a `connect` block with plain guards. The block is valid when it is
48
- * an object whose only key, if any, is `allow_projects`, holding at most
49
- * `MAX_ALLOW_PROJECTS` non-empty strings of at most `MAX_ALLOW_PROJECT_LENGTH`
50
- * characters. The zod schema in `config-schema.ts` accepts and rejects the
51
- * same values; a test pins the two together.
62
+ * an object whose only keys, if any, are `allow_projects` and `groups`.
63
+ * `allow_projects` holds at most `MAX_ALLOW_PROJECTS` non-empty strings of at
64
+ * most `MAX_ALLOW_PROJECT_LENGTH` characters. `groups` maps names to member
65
+ * lists as `readGroups` describes. The zod schema in `config-schema.ts`
66
+ * accepts and rejects the same values; a test pins the two together.
52
67
  */
53
68
  export declare function validateConnectBlock(value: unknown): ConnectBlockValidation;
54
69
  export interface ConnectConfigOptions {
@@ -78,8 +93,8 @@ export type ContainerRefusal = 'checkout' | 'allowed-root';
78
93
  /**
79
94
  * Why `dir` may not hold configuration or state, or `undefined` when it may.
80
95
  * A directory is refused when it is, or sits inside, an allowed root
81
- * (`allowed-root`), or when it or any ancestor holds a `.git` entry
82
- * (`checkout`). A repository is untrusted input, so what it holds must not
96
+ * (`allowed-root`), or when it or any ancestor holds a `.git` file, a `.git`
97
+ * symlink or a `.git` directory with a `HEAD` (`checkout`). A repository is untrusted input, so what it holds must not
83
98
  * steer what the helper reads or where it writes. Both sides are compared as
84
99
  * realpaths when they exist.
85
100
  */
@@ -87,6 +102,11 @@ export declare function containerRefusal(dir: string, allowedRoots: readonly str
87
102
  export interface ConnectAllowListLoad {
88
103
  /** The union of the readable layers' entries, in layer order, duplicates removed. */
89
104
  readonly allowProjects: readonly string[];
105
+ /**
106
+ * The readable layers' groups by name. A later layer replaces a same-named
107
+ * group whole. A member is not checked against the allow list here.
108
+ */
109
+ readonly groups: Readonly<Record<string, readonly string[]>>;
90
110
  /** Some layer's file or block could not be read and contributed nothing. */
91
111
  readonly unreadable: boolean;
92
112
  /** One line per problem. They name files and reasons, never an allow-list entry. */