@skanl/brambo-adapter-cli 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 SKANL
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,183 @@
+# @skanl/brambo-adapter-cli
+
+Every shipped `ExecutorAdapter` (`@skanl/brambo-contracts`) that drives an out-of-process coding CLI.
+One generic engine spawns the binary headlessly inside a workspace's root path and maps its
+output to a typed `ResultEnvelope`; each executor is a trait RECORD over that engine, never a
+class of its own.
+
+## Trait table
+
+`ExecutorTraits` = `{executorId, command, args, promptDelivery, promptArgSeparator?, output}`.
+The two real structural axes are prompt delivery and payload shape — everything else is shared
+machinery. The factory validates the record and rejects the shapes that would fail silently
+(empty `command`, empty `resultPath`, empty `errorStatusPrefix`, `usagePaths` that is empty or
+names an empty path, `usagePaths` without the `usageWhen` that bounds it, a `metadata` key colliding with
+an engine-owned `data` key) with a coded error.
+
+| Executor | Invocation | Prompt | Payload | Result |
+|---|---|---|---|---|
+| `claude-code` | `claude --print --output-format stream-json --verbose --no-session-persistence --dangerously-skip-permissions` | stdin | JSONL events | `result` where `type == "result"` |
+| `codex` | `codex exec --json --skip-git-repo-check` | stdin (positional omitted) | JSONL events | `item.text` where `item.type == "agent_message"` |
+| `opencode` | `opencode run --format json -- <prompt>` | final argv entry | JSONL events | `part.text` where `part.type == "text"` |
+
+Adding a fourth executor means adding a record — `test/trait-stub.test.ts` proves it by passing
+the whole clause suite with a trait record the engine has never seen.
+
+All three are reachable from `brambo run --executor <id>` and from
+`.brambo/config.json`'s `executor` key (Story 2.7c). This package owns the catalogue that maps an
+id to its adapter — `EXECUTOR_CATALOGUE`, `DEFAULT_EXECUTOR_ID`, `createExecutorAdapter` — because
+the kernel plugin below has to perform that lookup for itself.
+
+### As a kernel plugin
+
+`createExecutorPlugin()` mounts an adapter on a `@skanl/brambo-kernel` container. It reads WHICH executor
+from the kernel's composed configuration (its own `executor` key, the same one `.brambo/config.json`
+spells), rejects activation when that key names nothing this package ships, and provides the
+`executor` service.
+
+That service is a **runner**, not an adapter: `{ executorId, run(actionId, request) }`. The adapter
+is closed over and never handed out, so every run registers an action on the KERNEL's interception
+waterfall and a cap refuses before a process is spawned. What that closes is the container's
+surface — anyone who imports `createClaudeCodeAdapter` from here can still drive one directly, and
+`deferred-work.md` keeps that open rather than claiming otherwise.
+
+### Finding the result in a JSONL stream
+
+The engine reads the stream once and keeps two records: the first one that reports a failure, and
+the last one carrying a usable result. Codex's `ThreadEvent` variants and OpenCode's event types
+are their own evolving vocabularies, so matching on event NAMES would break brambo on their next
+release; the engine only matches the paths a trait record names, which costs nothing when the
+stream ends in trailing noise.
+
+Failure detection is deliberately non-positional. OpenCode emits recoverable `error` events and
+keeps going, so "last qualifying line wins" would silently drop a reported failure whenever any
+output followed it.
+
+A result path alone is not enough to identify the answer: codex `reasoning` items and opencode
+`reasoning` parts both carry a `text` field, so both records add a discriminator. Without one the
+adapter would confidently return chain-of-thought as the result.
+
+### Working directory
+
+All three CLIs accept a cwd flag (`-C`, `--dir`), and none of them is passed: the spawn seam
+starts the child in `workspace.rootPath`. Codex additionally needs `--skip-git-repo-check`
+because a brambo workspace is not necessarily a git repository.
+
+The cwd is **not** the only mechanism, and believing it was is what M4.A found. `opencode`
+resolves its file tools against `$PWD` rather than against `process.cwd()`, so with brambo's own
+`PWD` inherited it wrote into the directory brambo was launched from — twice, reproducibly. The
+spawner therefore hands every child a `PWD` equal to the cwd it is given. Two mechanisms, and for
+opencode the second one is the load-bearing one.
+
+### What the workspace is, and what it is not
+
+Measured per executor against the real binaries (`test/confinement-live.test.ts`):
+
+| Executor | A workspace-relative write | Notes |
+|---|---|---|
+| `claude-code` | lands in the workspace | resolves against its cwd; ignores a lying `PWD` |
+| `codex` | never happens | `codex exec` defaults to the `read-only` sandbox, so **as brambo ships it codex cannot create or edit a file at all** |
+| `opencode` | lands in the workspace | resolves against `$PWD`, which brambo sets to the cwd |
+
+**brambo makes the workspace true; it does not enforce it.** Told to write to an ABSOLUTE path
+outside the workspace, `claude` did so without hesitating — brambo runs it with
+`--dangerously-skip-permissions` and spawns an ordinary child with the user's own privileges, and
+nothing sits between the two. (`codex` refused, but that is codex's own sandbox, not brambo's.)
+OS-level sandboxing is a deliberate non-goal here.
+
+And `HOME` is passed through untouched, because scrubbing it would break all three: per-user
+executor state is therefore SHARED across concurrent sessions — `opencode` keeps a single SQLite
+database under `~/.local/share/opencode/`, `claude` a per-project directory under `~/.claude/`.
+Two isolated workspaces do not imply two isolated executors.
+
+### Argument delivery is a trust boundary
+
+Putting the prompt in argv means the OS — and on win32 possibly a shell — parses caller-supplied
+text, so that path is guarded:
+
+- A `--` separator (trait data) keeps a prompt starting with `-` out of flag position.
+- A prompt beyond the platform's conservative argv bound is refused with a coded envelope naming
+  the limit, rather than surfacing as an unattributable spawn error.
+- A win32 `.cmd`/`.bat` command can only start by rerouting through `cmd.exe`, which interprets
+  `&`, `|`, `>`, `^` and `%VAR%` no matter how the argument is quoted. The run fails closed with
+  a coded `executorUnavailable` naming the way out (point `command` at the real executable).
+  Escaping for `cmd.exe` is not a winnable game and is not attempted.
+
+## Envelope guarantees
+
+Identical for every adapter: coded `executorUnavailable` when the binary cannot spawn,
+`executorRunFailed` on pipe/stream errors, non-zero exits, unparseable output and
+executor-reported failures (even at exit code 0), and a `cancelled` envelope with a non-empty
+`errors` array on abort. Completion is observed before an abort can claim cancellation, so an
+abort landing after a successful exit yields the real `ok` envelope. Cancellation kills the whole
+process tree (`taskkill /T /F` on win32, process-group SIGKILL on posix) and never signals a pid
+that has already exited.
+
+A structured payload survives a non-zero exit: codex and opencode exit non-zero exactly when they
+have printed their error event, so the envelope is built from that payload rather than from
+stderr noise. A capture that hit the stream cap is reported as a coded failure naming the
+truncation — an `ok` built from the last event that happened to survive the cut would be a
+confident wrong answer.
+
+## Child-process seam
+
+All spawning goes through `ChildProcessSpawner` (`spawn-seam.ts`). Production uses
+`createNodeChildSpawner()`; every adapter suite injects a fake, so no executor is ever really
+started by a test. The spawner is also the orphan-detection surface: after cancellation, and
+after a broken stdin pipe, no child may remain unsettled-and-unkilled.
+
+Two suites do spawn real processes, and neither runs an executor: `test/overhead.test.ts` and
+`test/tree-kill.test.ts` spawn `process.execPath` (part of `pnpm check`, no network, no auth).
+Four suites run a real coding CLI, and each one spends account credit:
+`test/live-smoke.test.ts`, `test/usage-live.test.ts`, `test/confinement-live.test.ts` and
+`test/stream-mode-live.test.ts`. The authoritative roster is
+`packages/contracts/test/live-suite-naming.test.ts`, which reddens when a live suite
+escapes the exclusion glob — this sentence used to say "three", and the fourth was
+the one the glob had already learned to catch twice.
+
+The spawner also decides the child's ENVIRONMENT, which is otherwise inherited whole. Exactly one
+variable is changed: `PWD` is set to the cwd the child is given, because it is the only inherited
+variable that claims to name the working directory and a stale one redirects `opencode`'s writes.
+Nothing is removed — `INIT_CWD` was the suspect M3.C named and was ruled out by measurement, and
+deleting a variable measured not to matter is a scrub, not a fix.
+
+## Spawn-overhead instrumentation
+
+Pass `onTiming` to receive `{ spawnSetupMs, runMs }` per run. NFR-9 budgets adapter-added overhead
+at ≤150ms above raw CLI startup; the deterministic measurement lives in `test/overhead.test.ts`
+(adapter vs direct spawn of the same trivial command — no network, no auth, no flake).
+
+## Live smoke
+
+`test/live-smoke.test.ts` runs one tiny real task end-to-end when the `claude` binary is detected
+and authenticated; otherwise it skips with an explicit reason (never silently passes).
+Set `BRAMBO_LIVE_SMOKE=0` to disable it explicitly. It is env-gated by design and is never part of
+what `pnpm check` guarantees.
+
+## Confinement
+
+`test/confinement-live.test.ts` measures, per executor, where a file the executor was told to
+create actually lands. The same rule applies: a missing or non-answering binary skips with its
+reason, an authenticated-but-logged-out one skips, and `BRAMBO_LIVE_CONFINEMENT=0` disables it.
+Because that means CI — where none of the three binaries exists — runs it green while measuring
+nothing, its last case PRINTS which executors were measured; read that line before trusting a
+green run. Its deterministic half (what environment the spawner hands a child) runs everywhere and
+needs no binary.
+
+## Token usage
+
+A trait record may declare where its vendor reports what a run spent:
+
+- `usageWhen` — the records that carry usage (`{"type": "turn.completed"}` for codex,
+  `{"type": "step_finish"}` for opencode, `{"type": "result"}` for claude-code).
+- `usagePaths` — the numeric fields inside such a record. They are summed within a record
+  **and across every matching record**, because a vendor that works in steps bills each step.
+
+The total lands on `envelope.data.usage` as a NUMBER — the one non-string value there, and the
+reason `usage` is an engine-owned key a `metadata` key may not collide with. Absent means the
+vendor reported nothing; the figure is never faked, never estimated and never tokenized by brambo.
+It fails closed as a whole: if any billed record cannot be read, the run reports no figure rather
+than a sum missing a term.
+
+Every shipped figure is verified against the real binary by `test/usage-live.test.ts`, which is
+also what keeps a fourth adapter from shipping a `usagePaths` nobody ever exercised.

package/dist/catalogue.d.ts

@@ -0,0 +1,57 @@
+import { BramboError } from '@skanl/brambo-contracts';
+import type { CliExecutorAdapter, CliExecutorAdapterOptions, ExecutorTraits } from './traits.ts';
+/**
+ * One shipped adapter: its OWN trait record, and the factory that builds it.
+ *
+ * The pair is what the catalogue stores, and the trait record is what supplies
+ * the key. There is deliberately no `id` field here to write beside it — a
+ * second spelling of the name is the thing this file exists to prevent.
+ */
+export interface ShippedExecutor {
+    readonly traits: ExecutorTraits;
+    readonly create: (options?: CliExecutorAdapterOptions) => CliExecutorAdapter;
+}
+/**
+ * Every adapter brambo ships, keyed by each adapter's own `executorId` TRAIT.
+ *
+ * Keyed from the traits, never from a list of string literals written beside
+ * them: Story 2.7a shipped an executor that was never once exercised because a
+ * parallel name list drifted from the thing it named. A name that exists here is
+ * a name whose trait record supplied it, so a fourth adapter appears by being
+ * shipped rather than by being listed twice.
+ *
+ * The key alone does not close the whole hole — a mis-paired factory would key
+ * codex's traits to opencode's constructor — so `packages/session/test/executors.test.ts`
+ * builds every entry and asserts the ADAPTER answers with the key it was found under.
+ *
+ * It lives HERE rather than in `@skanl/brambo-session` since M3.B: the executor plugin
+ * turns a configured id into an adapter, and a plugin whose package could not
+ * perform its own lookup would have to be handed a constructor by whoever
+ * mounted it — which is the direct construction this story exists to remove.
+ * `@skanl/brambo-session` re-exports the whole set, so its callers see no move.
+ */
+export declare const EXECUTOR_CATALOGUE: ReadonlyMap<string, ShippedExecutor>;
+/**
+ * What brambo runs when nothing selects otherwise. Taken from the trait record,
+ * so it is one of the catalogue's own keys by construction, and used as the
+ * `defaults` LAYER rather than as a constructor fallback — the difference being
+ * that a layer can be overridden and reported on, and a constructor cannot.
+ */
+export declare const DEFAULT_EXECUTOR_ID: string;
+/** Every id a selection may name, in catalogue order. */
+export declare function availableExecutorIds(): readonly string[];
+/** Brambo ships no adapter under the name that was asked for. */
+export declare function unknownExecutor(executorId: string): BramboError;
+/**
+ * The adapter for one catalogue id, or brambo's default when none is named.
+ *
+ * The default flows from `DEFAULT_EXECUTOR_ID` through the same catalogue lookup
+ * every other id takes, so there is no path on which a hardcoded constructor
+ * runs. An id the catalogue does not hold is a coded failure, never a fallback.
+ *
+ * `options` is the adapter's OWN seam — a child-process spawner, or a binary
+ * path that overrides the trait's command. `SessionOptions.adapterOptions`
+ * threads it through from `runSession` and from `brambo run`, so it is a live
+ * seam rather than flexibility no caller could reach.
+ */
+export declare function createExecutorAdapter(executorId?: string, options?: CliExecutorAdapterOptions): CliExecutorAdapter;

package/dist/catalogue.js

@@ -0,0 +1,62 @@
+import { BRAMBO_ERROR_CODES, BramboError } from '@skanl/brambo-contracts';
+import { CLAUDE_CODE_TRAITS, createClaudeCodeAdapter } from './executors/claude-code.js';
+import { CODEX_TRAITS, createCodexAdapter } from './executors/codex.js';
+import { OPENCODE_TRAITS, createOpenCodeAdapter } from './executors/opencode.js';
+const SHIPPED = [
+    { traits: CLAUDE_CODE_TRAITS, create: createClaudeCodeAdapter },
+    { traits: CODEX_TRAITS, create: createCodexAdapter },
+    { traits: OPENCODE_TRAITS, create: createOpenCodeAdapter },
+];
+/**
+ * Every adapter brambo ships, keyed by each adapter's own `executorId` TRAIT.
+ *
+ * Keyed from the traits, never from a list of string literals written beside
+ * them: Story 2.7a shipped an executor that was never once exercised because a
+ * parallel name list drifted from the thing it named. A name that exists here is
+ * a name whose trait record supplied it, so a fourth adapter appears by being
+ * shipped rather than by being listed twice.
+ *
+ * The key alone does not close the whole hole — a mis-paired factory would key
+ * codex's traits to opencode's constructor — so `packages/session/test/executors.test.ts`
+ * builds every entry and asserts the ADAPTER answers with the key it was found under.
+ *
+ * It lives HERE rather than in `@skanl/brambo-session` since M3.B: the executor plugin
+ * turns a configured id into an adapter, and a plugin whose package could not
+ * perform its own lookup would have to be handed a constructor by whoever
+ * mounted it — which is the direct construction this story exists to remove.
+ * `@skanl/brambo-session` re-exports the whole set, so its callers see no move.
+ */
+export const EXECUTOR_CATALOGUE = new Map(SHIPPED.map((executor) => [executor.traits.executorId, executor]));
+/**
+ * What brambo runs when nothing selects otherwise. Taken from the trait record,
+ * so it is one of the catalogue's own keys by construction, and used as the
+ * `defaults` LAYER rather than as a constructor fallback — the difference being
+ * that a layer can be overridden and reported on, and a constructor cannot.
+ */
+export const DEFAULT_EXECUTOR_ID = CLAUDE_CODE_TRAITS.executorId;
+/** Every id a selection may name, in catalogue order. */
+export function availableExecutorIds() {
+    return [...EXECUTOR_CATALOGUE.keys()];
+}
+/** Brambo ships no adapter under the name that was asked for. */
+export function unknownExecutor(executorId) {
+    return new BramboError(BRAMBO_ERROR_CODES.executorNotFound, `brambo has no adapter named '${executorId}'; available executors: ${availableExecutorIds().join(', ')}`);
+}
+/**
+ * The adapter for one catalogue id, or brambo's default when none is named.
+ *
+ * The default flows from `DEFAULT_EXECUTOR_ID` through the same catalogue lookup
+ * every other id takes, so there is no path on which a hardcoded constructor
+ * runs. An id the catalogue does not hold is a coded failure, never a fallback.
+ *
+ * `options` is the adapter's OWN seam — a child-process spawner, or a binary
+ * path that overrides the trait's command. `SessionOptions.adapterOptions`
+ * threads it through from `runSession` and from `brambo run`, so it is a live
+ * seam rather than flexibility no caller could reach.
+ */
+export function createExecutorAdapter(executorId = DEFAULT_EXECUTOR_ID, options) {
+    const shipped = EXECUTOR_CATALOGUE.get(executorId);
+    if (shipped === undefined)
+        throw unknownExecutor(executorId);
+    return shipped.create(options);
+}

package/dist/executors/claude-code.d.ts

@@ -0,0 +1,3 @@
+import type { CliExecutorAdapter, CliExecutorAdapterOptions, ExecutorTraits } from '../traits.ts';
+export declare const CLAUDE_CODE_TRAITS: ExecutorTraits;
+export declare function createClaudeCodeAdapter(options?: CliExecutorAdapterOptions): CliExecutorAdapter;

package/dist/executors/claude-code.js

@@ -0,0 +1,125 @@
+import { createCliExecutorAdapter } from '../traits.js';
+// Claude Code trait record.
+//
+// Headless print mode: `--print --output-format stream-json --verbose` prints
+// newline-delimited EVENTS on stdout, and the prompt arrives via stdin (the
+// CLI's piped-input convention). Session persistence is off so no session state
+// outlives the workspace; permissions are bypassed because headless execution
+// has no interactive approver.
+//
+// The stream, MEASURED (M15.A) on 2.1.260 by running the binary and reading its
+// own stdout, exactly as the `--output-format json` mode below was:
+//   `--verbose` is REQUIRED. Without it, `--print --output-format stream-json`
+//   exits 1 printing "Error: When using --print, --output-format=stream-json
+//   requires --verbose" and produces no output at all. Measured by running it;
+//   it costs no quota, because the refusal is argument validation.
+//   With it: exit 0, and stderr carried NOTHING.
+// The 14 events of a one-word task were, in order: four `system/hook_started`,
+// `system/hook_response` x2, `system/hook_progress`, `system/hook_response` x2,
+// `system/init`, `system/informational`, `assistant`, `rate_limit_event`, and
+// the terminal `result/success`.
+//
+// WHY THE MODE CHANGED, and what did not: `--output-format json` carries NO
+// quota surface. Its top-level keys were dumped in full and the list is the
+// control that the search saw the object: duration_api_ms, stop_reason,
+// session_id, total_cost_usd, usage, modelUsage, ... and no `rate_limit_info`.
+// The stream's terminal `result/success` event carries every one of those same
+// fields, so the ENVELOPE is fed from it rather than rebuilt, and it is
+// identical to the one the single-object mode produced. `test/stream-mode-live.test.ts`
+// proves that against the old mode by running both, rather than asserting it.
+//
+// `failureWhen` is what keeps that equivalence true. The single-object mode had
+// exactly one record, so "the record that reports failure" was the result by
+// construction; the stream's `system/*` events carry a `subtype` of their own,
+// and without the discriminator the `error` prefix would be tested against
+// nine records that are not the result.
+//
+// Quota, MEASURED in the same run (Story M15.A): the `rate_limit_event` carries
+// `rate_limit_info.unifiedWindows`, a MAP of the vendor's own window names to
+// `{utilization, resetsAt}` — `five_hour {0.13, 1788491400}` and
+// `seven_day {0.22, 1788728400}`. `resetsAt` is a Unix epoch in SECONDS, a
+// NUMBER, and `utilization` is a fraction rather than a percentage. Both are
+// reported verbatim under the vendor's own names; brambo converts neither.
+// It arrives WITHOUT `--include-hook-events`, which the original measurement
+// happened to pass and which brambo therefore does not.
+//
+// Failure shape: print-mode payloads carry `is_error` plus a `subtype`
+// ('success', 'error_max_turns', …). Both must surface as FAILED envelopes even
+// when the process exited 0, which is exactly what the flag/status-prefix
+// traits below express.
+//
+// Usage, VERIFIED by running `claude --print --output-format json` (2.1.246) and
+// reading its own stdout: the result object carries a `usage` object with
+//   input_tokens, output_tokens,
+//   cache_creation_input_tokens, cache_read_input_tokens
+// Observed on a one-word task: 2 / 4 / 42206 / 17630. The four are DISJOINT, and
+// the vendor's own printout proves it rather than the name suggesting it: pricing
+// each component at its own published rate reconstructs the `total_cost_usd` the
+// same payload reports, to the last digit. `input_tokens` counts only the uncached
+// input, so charging it alone would have priced that run at 2 tokens instead of
+// 59842 — the budget figure is their sum.
+//
+// The one result object is the only record here, and `usageWhen` pins it to
+// `type == "result"` so a future print-mode event carrying a `usage` of its own
+// cannot join the sum.
+//
+// Confinement, MEASURED (M4.A) by running the real binary and looking at the
+// filesystem, not by reading a flag: told to create a file, claude created it in
+// the cwd it was spawned in while `PWD` named a directory OUTSIDE that cwd and
+// `INIT_CWD` a third one. claude resolves the write against its cwd. It confines
+// a workspace-relative write, which is not the same as being confined: MEASURED
+// in the same story, claude asked for an ABSOLUTE path outside the workspace
+// created the file there without hesitating. brambo runs it with
+// `--dangerously-skip-permissions` and spawns an ordinary child with the user's
+// own privileges, so there is nothing between the two. Epic 4 inherits that.
+//
+// `test/confinement-live.test.ts` keeps this true, and it spawns claude
+// deliberately OUTSIDE brambo's spawner to do it: brambo now hands every child a
+// `PWD` equal to its cwd, so a claude that started following `$PWD` tomorrow
+// would still land in the workspace and a through-brambo check could never
+// notice. The lie has to reach the child for the claim to be falsifiable.
+//
+// The same payload also reports `total_cost_usd` and a per-model `modelUsage`
+// (which restates the four figures under different spellings, and is what the live
+// check reads as an INDEPENDENT oracle); money is Ask-First, so neither ships.
+export const CLAUDE_CODE_TRAITS = {
+    executorId: 'claude-code',
+    command: 'claude',
+    args: Object.freeze([
+        '--print',
+        '--output-format',
+        'stream-json',
+        // Not optional and not cosmetic: `stream-json` under `--print` exits 1
+        // without it. `test/executors.test.ts` pins the pair (E7).
+        '--verbose',
+        '--no-session-persistence',
+        '--dangerously-skip-permissions',
+    ]),
+    promptDelivery: 'stdin',
+    output: {
+        payload: 'jsonl',
+        resultPath: ['result'],
+        resultWhen: { path: ['type'], equals: 'result' },
+        failureWhen: { path: ['type'], equals: 'result' },
+        errorFlagPath: ['is_error'],
+        statusPath: ['subtype'],
+        errorStatusPrefix: 'error',
+        metadata: { subtype: ['subtype'], session_id: ['session_id'] },
+        usageWhen: { path: ['type'], equals: 'result' },
+        usagePaths: [
+            ['usage', 'input_tokens'],
+            ['usage', 'output_tokens'],
+            ['usage', 'cache_creation_input_tokens'],
+            ['usage', 'cache_read_input_tokens'],
+        ],
+        usageWindows: {
+            when: { path: ['type'], equals: 'rate_limit_event' },
+            path: ['rate_limit_info', 'unifiedWindows'],
+            utilizationKey: 'utilization',
+            resetsAtKey: 'resetsAt',
+        },
+    },
+};
+export function createClaudeCodeAdapter(options = {}) {
+    return createCliExecutorAdapter(CLAUDE_CODE_TRAITS, options);
+}

package/dist/executors/codex.d.ts

@@ -0,0 +1,3 @@
+import type { CliExecutorAdapter, CliExecutorAdapterOptions, ExecutorTraits } from '../traits.ts';
+export declare const CODEX_TRAITS: ExecutorTraits;
+export declare function createCodexAdapter(options?: CliExecutorAdapterOptions): CliExecutorAdapter;

package/dist/executors/codex.js

@@ -0,0 +1,89 @@
+import { createCliExecutorAdapter } from '../traits.js';
+// Codex trait record.
+//
+// `codex exec [OPTIONS] [PROMPT]` reads the instructions from STDIN when the
+// positional PROMPT is omitted, and `--json` prints its ThreadEvent stream to
+// stdout as JSONL.
+//
+// Result location, verified against codex-rs/exec/src/exec_events.rs: items
+// arrive as `{"type":"item.completed","item":{…}}`, where `ThreadItemDetails`
+// is serialized `#[serde(tag = "type", rename_all = "snake_case")]`. The answer
+// is `AgentMessageItem { text }` at `item.type == "agent_message"`. The
+// discriminator is NOT optional here: `ReasoningItem` also has a `text` field,
+// so without it the scan would happily return the model's chain-of-thought as
+// the result.
+//
+// `--skip-git-repo-check` is required because a brambo workspace is not
+// necessarily a git repository, and codex exec otherwise refuses to run. No cwd
+// flag: the spawn seam already starts the child in `workspace.rootPath`.
+//
+// Failure shape: fatal problems arrive as `{"type":"error","message":"…"}`, so
+// the status prefix rule matches on `type` and the detail comes from `message`.
+//
+// Usage, VERIFIED by running `codex exec --json --skip-git-repo-check`
+// (codex-cli 0.149.1) and reading its own stdout: usage is NOT on the answer
+// item. It arrives on a later event of its own,
+//   {"type":"turn.completed","usage":{input_tokens, cached_input_tokens,
+//    cache_write_input_tokens, output_tokens, reasoning_output_tokens}}
+// Observed on a one-word task: 28451 / 6912 / 0 / 61 / 54. Only `input_tokens`
+// and `output_tokens` are summed: `cached_input_tokens` is a BREAKDOWN of the
+// input already counted (6912 of the 28451), and `reasoning_output_tokens` is
+// likewise a share of the output. Codex says so itself — its session rollout
+// records `total_tokens` as input + output with the cached figure EXCLUDED
+// (27189 = 27184 + 5 on a measured run); summing it would have billed 53557 for
+// a 28512-token turn.
+//
+// Confinement, MEASURED (M4.A) by running the real binary and looking at the
+// filesystem. The verdict has to be stated about the argv ABOVE, not about codex
+// in general, and they differ:
+//
+// AS BRAMBO SHIPS IT, codex writes nothing at all. `codex exec` defaults to the
+// `read-only` sandbox: asked to create a file it completes its turn and reports
+// that write access is denied, leaving the workspace empty. So brambo's workspace
+// boundary is never tested by codex, and `brambo run --executor codex` is a
+// coding agent that cannot edit code. That is the fact a user meets, so that is
+// the fact `test/confinement-live.test.ts` guards — with these exact args, and
+// it goes red the day codex ships a writable default.
+//
+// MEASURED ONCE with `-s workspace-write`, which brambo does not pass: codex
+// wrote through `apply_patch` to an ABSOLUTE path resolved from its own cwd,
+// ignoring a `PWD` aimed elsewhere. Recorded, NOT guarded — a standing check on
+// argv brambo never sends would be testing a configuration nobody ships.
+// ponytail: if brambo ever ships codex writable, that measurement becomes a
+// claim and needs its own case.
+//
+// Also measured under `-s workspace-write`: told to write to an ABSOLUTE path
+// outside the workspace, codex REFUSED — "I can't write outside the permitted
+// workspace". That is codex's own sandbox, not brambo's; claude, which brambo runs
+// with `--dangerously-skip-permissions`, wrote the same file without hesitating.
+// So of the three, codex is the only one that enforces anything, and it does so
+// by not writing at all in the mode brambo ships.
+//
+// Loosening the shipped sandbox is a vendor-configuration decision, deliberately
+// not taken here.
+//
+// `usageWhen` pins the sum to `turn.completed`. `codex exec` runs one turn, so
+// today that is one record; summing across them is the right answer if a future
+// stream reports more, because each carries its own turn's spend.
+export const CODEX_TRAITS = {
+    executorId: 'codex',
+    command: 'codex',
+    args: Object.freeze(['exec', '--json', '--skip-git-repo-check']),
+    promptDelivery: 'stdin',
+    output: {
+        payload: 'jsonl',
+        resultPath: ['item', 'text'],
+        resultWhen: { path: ['item', 'type'], equals: 'agent_message' },
+        statusPath: ['type'],
+        errorStatusPrefix: 'error',
+        errorMessagePath: ['message'],
+        usageWhen: { path: ['type'], equals: 'turn.completed' },
+        usagePaths: [
+            ['usage', 'input_tokens'],
+            ['usage', 'output_tokens'],
+        ],
+    },
+};
+export function createCodexAdapter(options = {}) {
+    return createCliExecutorAdapter(CODEX_TRAITS, options);
+}

package/dist/executors/opencode.d.ts

@@ -0,0 +1,3 @@
+import type { CliExecutorAdapter, CliExecutorAdapterOptions, ExecutorTraits } from '../traits.ts';
+export declare const OPENCODE_TRAITS: ExecutorTraits;
+export declare function createOpenCodeAdapter(options?: CliExecutorAdapterOptions): CliExecutorAdapter;

package/dist/executors/opencode.js

@@ -0,0 +1,74 @@
+import { createCliExecutorAdapter } from '../traits.js';
+// OpenCode trait record.
+//
+// `opencode run [message..]` takes the prompt as a POSITIONAL argument — there
+// is no stdin path — and `--format json` streams raw JSON events, one per line.
+// `--` separates the prompt from the flags so a prompt starting with `-` is not
+// parsed as one; `run` joins everything after it into the message.
+//
+// Result location: every event shares the envelope `{type, timestamp,
+// sessionID, …}`, and assistant output arrives as
+// `{"type":"text","part":{"type":"text","text":"…"}}`. The `part.type` guard
+// matters because `reasoning` events (emitted with `--thinking`) carry a `part`
+// with a `text` field too. The `step_finish` event that follows carries no
+// text, so the scan steps over it either way.
+//
+// Failure shape: `{"type":"error","error":{…}}` — the detail is an OBJECT, which
+// the engine stringifies rather than dropping. OpenCode also emits RECOVERABLE
+// error events and keeps going, which is why failure detection is non-positional.
+//
+// Usage, VERIFIED by running `opencode run --format json` (1.18.23) and reading
+// its own stdout: the `step_finish` event carries
+//   part.tokens = { total, input, output, reasoning, cache: { write, read } }
+// and `total` is opencode's OWN sum of its own components — on a one-word task,
+// total 42599 = input 34390 + output 17 + reasoning 0 + cache.write 0 +
+// cache.read 8192.
+//
+// `step_finish` is emitted PER STEP and each `total` is that step's own spend,
+// not a running one. Measured on a three-step task: 42770, 42875 and 43025, each
+// equal to its own components, for a run that really cost 128670. Taking the last
+// record billed 43025, and a run whose final step is a one-line answer bills
+// almost nothing — so the engine sums every `step_finish`, and `usageWhen` is
+// what bounds which records join that sum.
+//
+// The event also carries `cost`, which is money and Ask-First.
+//
+// Confinement, MEASURED (M4.A) by running the real binary and looking at the
+// filesystem. opencode does NOT bind its file tools to its working directory: it
+// resolves them against `$PWD`. Told to create a file "in the current working
+// directory" while `PWD` named a decoy outside its cwd, its own `write` tool
+// call carried the decoy's absolute path and the file landed there — twice —
+// which is the escape the M3.C ledger recorded from `packages/adapter-cli`.
+// `node-child-spawner.ts` now hands every child a `PWD` equal to its cwd, and
+// the same measurement then shows opencode confined, twice. So opencode confines
+// BECAUSE brambo tells it the truth about where it is, not on its own account,
+// and `test/confinement-live.test.ts` is what keeps that true: deleting the
+// correction turns it red with opencode's own tool call as the evidence.
+//
+// Also measured, and NOT fixed: opencode keeps ONE SQLite database per USER
+// (`~/.local/share/opencode/opencode.db` — 522 MB on the machine this was
+// measured on), so two concurrent brambo sessions in two workspaces share it. Their FILES stay apart; their executor state does
+// not. `HOME` is deliberately passed through untouched — scrubbing it would
+// break all three executors — so this is a limit Epic 4 inherits rather than a
+// defect this story can close.
+export const OPENCODE_TRAITS = {
+    executorId: 'opencode',
+    command: 'opencode',
+    args: Object.freeze(['run', '--format', 'json']),
+    promptDelivery: 'argument',
+    promptArgSeparator: '--',
+    output: {
+        payload: 'jsonl',
+        resultPath: ['part', 'text'],
+        resultWhen: { path: ['part', 'type'], equals: 'text' },
+        statusPath: ['type'],
+        errorStatusPrefix: 'error',
+        errorMessagePath: ['error'],
+        metadata: { sessionID: ['sessionID'] },
+        usageWhen: { path: ['type'], equals: 'step_finish' },
+        usagePaths: [['part', 'tokens', 'total']],
+    },
+};
+export function createOpenCodeAdapter(options = {}) {
+    return createCliExecutorAdapter(OPENCODE_TRAITS, options);
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createCliExecutorAdapter } from './traits.ts';
+export type { AdapterTiming, CliExecutorAdapter, CliExecutorAdapterOptions, ExecutorOutputTraits, ExecutorTraits, PathMatch, PayloadShape, PromptDelivery, UsageWindowTraits, } from './traits.ts';
+export { CLAUDE_CODE_TRAITS, createClaudeCodeAdapter } from './executors/claude-code.ts';
+export { CODEX_TRAITS, createCodexAdapter } from './executors/codex.ts';
+export { OPENCODE_TRAITS, createOpenCodeAdapter } from './executors/opencode.ts';
+export { createNodeChildSpawner, routesThroughCmdShim } from './node-child-spawner.ts';
+export type { ChildProcessSpawner, SpawnedChild, SpawnOptions, SpawnOutcome, } from './spawn-seam.ts';
+export { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, availableExecutorIds, createExecutorAdapter, unknownExecutor, type ShippedExecutor, } from './catalogue.ts';
+export { DEFAULT_EXECUTOR_ACTION_COST, EXECUTOR_CONFIG_KEY, EXECUTOR_PLUGIN_ID, EXECUTOR_SERVICE, createExecutorPlugin, type ExecutorPlugin, type ExecutorPluginOptions, type ExecutorService, } from './plugin.ts';