@skanl/brambo-adapter-cli 0.1.1

package/dist/index.js

@@ -0,0 +1,7 @@
+export { createCliExecutorAdapter } from './traits.js';
+export { CLAUDE_CODE_TRAITS, createClaudeCodeAdapter } from './executors/claude-code.js';
+export { CODEX_TRAITS, createCodexAdapter } from './executors/codex.js';
+export { OPENCODE_TRAITS, createOpenCodeAdapter } from './executors/opencode.js';
+export { createNodeChildSpawner, routesThroughCmdShim } from './node-child-spawner.js';
+export { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, availableExecutorIds, createExecutorAdapter, unknownExecutor, } from './catalogue.js';
+export { DEFAULT_EXECUTOR_ACTION_COST, EXECUTOR_CONFIG_KEY, EXECUTOR_PLUGIN_ID, EXECUTOR_SERVICE, createExecutorPlugin, } from './plugin.js';

package/dist/node-child-spawner.d.ts

@@ -0,0 +1,13 @@
+import type { ChildProcessSpawner } from './spawn-seam.ts';
+/**
+ * True when this command can only be started by rerouting through `cmd.exe`.
+ *
+ * win32 cannot exec .cmd/.bat shims directly (Node refuses them since the
+ * shell-injection hardening, raising EINVAL), so the spawner reroutes them.
+ * That reroute hands the argv to a SHELL, which interprets `&`, `|`, `>`, `^`,
+ * `%VAR%` and newlines — Node's CRT-style quoting does not neutralise any of
+ * them. Callers that would put untrusted text in argv must consult this and
+ * refuse rather than let the shell see it.
+ */
+export declare function routesThroughCmdShim(command: string): boolean;
+export declare function createNodeChildSpawner(): ChildProcessSpawner;

package/dist/node-child-spawner.js

@@ -0,0 +1,287 @@
+import { execFile, spawn } from 'node:child_process';
+import { resolve } from 'node:path';
+// stdout/stderr capture cap per stream; beyond it we truncate and flag, so a
+// chatty executor can never grow the parent's memory without bound. JSONL
+// executors emit an event per token, so this cap is reached in practice, not
+// only in theory — the truncation flag is what stops a chopped stream from
+// being read as a complete answer.
+const STREAM_CAPTURE_CAP_BYTES = 1024 * 1024;
+// Real spawner backed by node:child_process.
+//
+// Tree-kill semantics per platform:
+// - win32: `taskkill /pid <pid> /T /F` walks and force-terminates the whole tree;
+//   Node signals cannot reach grandchildren on Windows, so taskkill is the only
+//   reliable option for spawned .exe/.cmd trees. If taskkill itself fails, the
+//   child gets a direct kill fallback so `done` always settles.
+// - posix: the child is spawned detached into its own process group; killing
+//   -pid takes down every descendant in one signal.
+function killTreeOf(child) {
+    const pid = child.pid;
+    if (pid === undefined)
+        return;
+    if (process.platform === 'win32') {
+        execFile('taskkill', ['/pid', String(pid), '/T', '/F'], (error) => {
+            if (error) {
+                try {
+                    child.kill('SIGKILL');
+                }
+                catch {
+                    // Already exited.
+                }
+            }
+        });
+        return;
+    }
+    try {
+        process.kill(-pid, 'SIGKILL');
+    }
+    catch {
+        // The group may already be gone; fall through to the direct kill below.
+    }
+    try {
+        child.kill('SIGKILL');
+    }
+    catch {
+        // Already exited.
+    }
+}
+/**
+ * True when this command can only be started by rerouting through `cmd.exe`.
+ *
+ * win32 cannot exec .cmd/.bat shims directly (Node refuses them since the
+ * shell-injection hardening, raising EINVAL), so the spawner reroutes them.
+ * That reroute hands the argv to a SHELL, which interprets `&`, `|`, `>`, `^`,
+ * `%VAR%` and newlines — Node's CRT-style quoting does not neutralise any of
+ * them. Callers that would put untrusted text in argv must consult this and
+ * refuse rather than let the shell see it.
+ */
+export function routesThroughCmdShim(command) {
+    return process.platform === 'win32' && /\.(cmd|bat)$/i.test(command);
+}
+/*
+ * The environment a child receives (see `nodeOptions.env` below): brambo's own,
+ * with the ONE variable that claims to name the working directory corrected to
+ * the directory the child is actually given.
+ *
+ * `PWD` is not decoration. A tool that resolves relative paths against
+ * `process.env.PWD` instead of `process.cwd()` writes wherever `PWD` points,
+ * and an inherited `PWD` points at the directory BRAMBO was launched from —
+ * which is how a workspace stops being a boundary. Measured for M4.A against
+ * the real binaries with `PWD` aimed at a decoy directory outside the child's
+ * cwd: `opencode` created its file in the decoy, twice; `claude` used its cwd
+ * and ignored it.
+ *
+ * Corrected rather than deleted, because a shell-hosted tool may legitimately
+ * read `$PWD` and would break on its absence; a `PWD` that agrees with `cwd`
+ * cannot mislead anything. Every other inherited variable is left alone. Of the
+ * 95 a child receives on the machine this was measured on, 39 hold a single
+ * absolute path — `HOME`, `USERPROFILE`, `APPDATA`, `TEMP`, `INIT_CWD`,
+ * `OLDPWD` among them — and exactly one of them CLAIMS to name the child's
+ * working directory. Only that one is brambo's to correct. `INIT_CWD`, the
+ * ledger's named suspect, was RULED OUT by the same measurement: it pointed at
+ * a second, different decoy that stayed empty through every run, and deleting a
+ * variable measured not to matter would be the silent scrub this story exists
+ * to avoid.
+ *
+ * What this does NOT do: it does not confine anything. An executor that asks
+ * for an absolute path outside the workspace gets it — measured, with codex —
+ * and `HOME` still points at the real one, so per-user executor state (opencode
+ * keeps ONE SQLite database there) is shared by every concurrent session. brambo
+ * makes the workspace TRUE for a workspace-relative write; it is not a sandbox.
+ */
+export function createNodeChildSpawner() {
+    return {
+        spawn(command, args, options) {
+            // Resolved once, so a RELATIVE cwd cannot become two different absolute
+            // paths: node resolves `cwd` against the parent's directory, and a relative
+            // `PWD` would be re-resolved against the CHILD's. `resolve` normalises but
+            // does not canonicalise, so `PWD` is the LOGICAL path — through a symlinked
+            // root it names the link where `process.cwd()` names the target, which is
+            // the ordinary shell convention for `$PWD` and not an escape.
+            const cwd = resolve(options.cwd);
+            const nodeOptions = {
+                cwd,
+                env: { ...process.env, PWD: cwd },
+                windowsHide: true,
+                detached: process.platform !== 'win32',
+                stdio: ['pipe', 'pipe', 'pipe'],
+            };
+            // Resolving twice is a no-op: whichever settle path lands first wins.
+            let resolveDone;
+            const done = new Promise((resolveOutcome) => {
+                resolveDone = resolveOutcome;
+            });
+            let settled = false;
+            const settle = (outcome) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolveDone(outcome);
+            };
+            let stdoutTruncated = false;
+            let stderrTruncated = false;
+            function createCapture(markTruncated) {
+                const targetChunks = [];
+                let bytes = 0;
+                return {
+                    push(chunk) {
+                        // Once at the cap nothing more is retained — and discarding is
+                        // itself truncation, including when an earlier chunk filled the cap
+                        // exactly. Failing to advance `bytes` here would let every later
+                        // chunk append another cap-sized slice, i.e. no cap at all.
+                        if (bytes >= STREAM_CAPTURE_CAP_BYTES) {
+                            markTruncated();
+                            return;
+                        }
+                        const remaining = STREAM_CAPTURE_CAP_BYTES - bytes;
+                        if (chunk.length > remaining) {
+                            targetChunks.push(chunk.subarray(0, remaining));
+                            bytes = STREAM_CAPTURE_CAP_BYTES;
+                            markTruncated();
+                            return;
+                        }
+                        bytes += chunk.length;
+                        targetChunks.push(chunk);
+                    },
+                    text() {
+                        return Buffer.concat(targetChunks).toString('utf8');
+                    },
+                };
+            }
+            const stdout = createCapture(() => {
+                stdoutTruncated = true;
+            });
+            const stderr = createCapture(() => {
+                stderrTruncated = true;
+            });
+            // No-op error listeners keep async pipe failures (EPIPE etc.) from crashing
+            // the parent as unhandled 'error' events; stdin breakage is recorded so the
+            // adapter can classify the run as failed instead of trusting the outcome.
+            let streamErrorMessage;
+            // Everything written to stdin is BUFFERED, because the cmd.exe reroute
+            // below arrives asynchronously — by then the caller has usually already
+            // written the prompt and closed stdin on the first child. Without replay
+            // the rerouted child waits on stdin forever and the run hangs.
+            const stdinChunks = [];
+            let stdinEnded = false;
+            let flushedChunks = 0;
+            let flushedEnd = false;
+            let currentSource;
+            let routedThroughCmd = routesThroughCmdShim(command);
+            const cmdArgs = () => ['/d', '/s', '/c', command, ...args];
+            function flushStdin() {
+                const source = currentSource;
+                if (source === undefined || settled || streamErrorMessage !== undefined)
+                    return;
+                try {
+                    while (flushedChunks < stdinChunks.length) {
+                        source.stdin?.write(stdinChunks[flushedChunks]);
+                        flushedChunks++;
+                    }
+                    if (stdinEnded && !flushedEnd) {
+                        source.stdin?.end();
+                        flushedEnd = true;
+                    }
+                }
+                catch (error) {
+                    streamErrorMessage = error instanceof Error ? error.message : String(error);
+                }
+            }
+            const settleFatal = (message) => {
+                settle({ exitCode: null, stdout: '', stderr: '', spawnErrorMessage: message });
+            };
+            function attach(source) {
+                source.stdout?.on('data', (chunk) => stdout.push(chunk));
+                source.stderr?.on('data', (chunk) => stderr.push(chunk));
+                source.stdin?.on('error', (error) => {
+                    streamErrorMessage ??= error instanceof Error ? error.message : String(error);
+                });
+                source.stdout?.on('error', () => { });
+                source.stderr?.on('error', () => { });
+                source.on('error', (error) => {
+                    // Node raises EINVAL asynchronously for shell-restricted commands;
+                    // reroute once through cmd.exe while keeping tree-kill semantics.
+                    const code = error.code;
+                    if (code === 'EINVAL' && process.platform === 'win32' && !routedThroughCmd) {
+                        routedThroughCmd = true;
+                        launch('cmd.exe', cmdArgs());
+                        return;
+                    }
+                    // Spawn failures (ENOENT etc.) may never be followed by 'close', so the
+                    // error settles the child on its own.
+                    settle({
+                        exitCode: null,
+                        stdout: '',
+                        stderr: '',
+                        spawnErrorMessage: error instanceof Error ? error.message : String(error),
+                    });
+                });
+                source.on('close', (exitCode) => {
+                    settle({
+                        exitCode,
+                        stdout: stdout.text(),
+                        stderr: stderr.text(),
+                        ...(streamErrorMessage !== undefined ? { streamErrorMessage } : {}),
+                        ...(stdoutTruncated ? { stdoutTruncated: true } : {}),
+                        ...(stderrTruncated ? { stderrTruncated: true } : {}),
+                    });
+                });
+                // A rerouted child has received nothing yet: replay from the start.
+                currentSource = source;
+                flushedChunks = 0;
+                flushedEnd = false;
+                flushStdin();
+            }
+            function launch(executable, launchArgs) {
+                try {
+                    attach(spawn(executable, [...launchArgs], nodeOptions));
+                    return true;
+                }
+                catch (error) {
+                    settleFatal(error instanceof Error ? error.message : String(error));
+                    return false;
+                }
+            }
+            if (routedThroughCmd)
+                launch('cmd.exe', cmdArgs());
+            else if (!launch(command, args))
+                return failedChild(done);
+            return {
+                get pid() {
+                    return currentSource?.pid;
+                },
+                get settled() {
+                    return settled;
+                },
+                writeStdin(chunk) {
+                    if (stdinEnded)
+                        return;
+                    stdinChunks.push(chunk);
+                    flushStdin();
+                },
+                endStdin() {
+                    stdinEnded = true;
+                    flushStdin();
+                },
+                killTree() {
+                    // Signalling after the child settled could hit a RECYCLED pid, which
+                    // on win32 means taskkill /T /F on somebody else's process tree.
+                    if (settled || currentSource === undefined)
+                        return;
+                    killTreeOf(currentSource);
+                },
+                done,
+            };
+        },
+    };
+}
+function failedChild(done) {
+    return {
+        pid: undefined,
+        settled: true,
+        writeStdin() { },
+        endStdin() { },
+        killTree() { },
+        done,
+    };
+}

package/dist/plugin.d.ts

@@ -0,0 +1,88 @@
+import type { ExecutorAdapter, ResultEnvelope, RunRequest } from '@skanl/brambo-contracts';
+import type { PluginFactory, PluginManifest } from '@skanl/brambo-kernel';
+import { type CliExecutorAdapterOptions } from './traits.ts';
+/** The service name this plugin provides. */
+export declare const EXECUTOR_SERVICE = "executor";
+/** The plugin id this plugin registers under. */
+export declare const EXECUTOR_PLUGIN_ID = "executor";
+/** The key this plugin reads out of the kernel's composed configuration. */
+export declare const EXECUTOR_CONFIG_KEY = "executor";
+/**
+ * What one executor run is ADMITTED at when nothing configures otherwise, before
+ * the vendor says what it actually spent.
+ *
+ * ponytail: still a flat 1. Brambo may not invent a token figure — estimating or
+ * tokenizing is the exact thing this story removes — so the only honest pre-run
+ * number is a placeholder in whatever unit the caller's caps are denominated in.
+ * A host budgeting tokens passes its own `cost`; the settlement then replaces it
+ * with the vendor's own figure either way. Upgrade path: a per-executor estimate,
+ * which is per-model weighting and Ask-First (deferred-work.md).
+ */
+export declare const DEFAULT_EXECUTOR_ACTION_COST = 1;
+/**
+ * What `kernel.getService('executor')` hands back.
+ *
+ * Deliberately NOT an `ExecutorAdapter`. The honest limit is stated on
+ * `createExecutorPlugin` and in `deferred-work.md`: this closes the CONTAINER's
+ * surface, not the process — any package may still import a vendor factory from
+ * this one and drive an adapter itself.
+ */
+export interface ExecutorService {
+    /** Which shipped executor this is driving; a host-supplied adapter reports `'(injected)'`. */
+    readonly executorId: string;
+    /**
+     * Runs one request through the KERNEL's interception waterfall.
+     *
+     * `actionId` names this invocation in the record stream, and the caller owns
+     * it because the caller owns run identity — the session scopes it to the
+     * workspace so two sessions on one pipeline stay distinguishable. The COST is
+     * the plugin's, never the caller's: a caller that could price its own run
+     * could price it at zero and walk through a cost cap. So is the SETTLEMENT —
+     * the plugin observed the vendor, the caller did not, and a caller that could
+     * reconcile its own run to zero has defeated the budget just as thoroughly.
+     */
+    run(actionId: string, request: RunRequest): Promise<ResultEnvelope>;
+}
+export interface ExecutorPluginOptions {
+    /**
+     * Adapter seam; a host that built its own executor passes it here and the
+     * catalogue is never consulted. It still runs through the waterfall — the
+     * seam replaces WHICH executor runs, never WHETHER the pipeline sees it.
+     */
+    readonly createAdapter?: () => ExecutorAdapter;
+    /**
+     * Options handed to the SELECTED adapter: a child-process spawner, or a binary
+     * path that overrides the trait's command. Ignored when `createAdapter` is
+     * supplied, because then the caller built the adapter itself.
+     */
+    readonly adapterOptions?: CliExecutorAdapterOptions;
+    /** What one run costs this kernel's budget. Defaults to `DEFAULT_EXECUTOR_ACTION_COST`. */
+    readonly cost?: number;
+}
+export interface ExecutorPlugin {
+    readonly manifest: PluginManifest;
+    readonly factory: PluginFactory;
+}
+/**
+ * The executor adapter as a kernel plugin: a manifest providing the `executor`
+ * service, a factory that resolves WHICH adapter from the kernel's own composed
+ * configuration, and a disposer that drops it.
+ *
+ * Misconfiguration REJECTS activation (a contained start failure naming this
+ * plugin), never a mid-run surprise — the same rule `@skanl/brambo-registry`'s plugin
+ * follows, and the reason a bad `executor` key cannot take the kernel down.
+ *
+ * The honest scope of the no-bypass claim, corrected on review: this SERVICE
+ * exports no path around the waterfall, and the object it hands back is frozen
+ * so no other caller can be taken off it either. Three routes remain open and
+ * are named in `deferred-work.md` rather than narrated away:
+ *   - anyone who installs THIS package can call `createExecutorAdapter(id)` or
+ *     any of the three vendor factories and drive an adapter directly;
+ *   - this `factory` is a `PluginFactory`, so a holder can invoke it with an
+ *     `ActivationContext` of their own and get a real adapter wired to their own
+ *     pipeline — inherent to the plugin shape, and the reason `@skanl/brambo-session`
+ *     does not re-export it;
+ *   - `kernel.swap` runs a caller-supplied factory against the live registry, so
+ *     a kernel holder can replace this service outright.
+ */
+export declare function createExecutorPlugin(options?: ExecutorPluginOptions): ExecutorPlugin;

package/dist/plugin.js

@@ -0,0 +1,181 @@
+import { BRAMBO_ERROR_CODES, BramboError, defineStandardSchema } from '@skanl/brambo-contracts';
+import { isNonEmptyString, isRecord, issue } from '@skanl/brambo-contracts/validation';
+import { DEFAULT_EXECUTOR_ID, EXECUTOR_CATALOGUE, availableExecutorIds, createExecutorAdapter, unknownExecutor, } from './catalogue.js';
+import { USAGE_DATA_KEY } from './traits.js';
+// The executor adapter, mounted as a kernel plugin (Story M3.B).
+//
+// It is the interesting one of the two this story adds, because of what its
+// SERVICE is. A service that handed back an `ExecutorAdapter` would put `.run()`
+// on the surface of the container, and every consumer of the kernel could then
+// spawn an executor with no budget, no guard and no record — which is exactly
+// the hole AD-10 exists to close. So the service is a RUNNER: the adapter is
+// closed over and never handed out, and the only exported way to reach it
+// registers the invocation on the kernel's own pipeline and invokes it there.
+//
+// Configuration comes from the plugin's own key of the kernel's layered config —
+// `executor`, the same key brambo's `.brambo/config.json` already spells, so one
+// composed document decides both what `brambo run` reports and what this mounts.
+/** The service name this plugin provides. */
+export const EXECUTOR_SERVICE = 'executor';
+/** The plugin id this plugin registers under. */
+export const EXECUTOR_PLUGIN_ID = 'executor';
+/** The key this plugin reads out of the kernel's composed configuration. */
+export const EXECUTOR_CONFIG_KEY = 'executor';
+/**
+ * What one executor run is ADMITTED at when nothing configures otherwise, before
+ * the vendor says what it actually spent.
+ *
+ * ponytail: still a flat 1. Brambo may not invent a token figure — estimating or
+ * tokenizing is the exact thing this story removes — so the only honest pre-run
+ * number is a placeholder in whatever unit the caller's caps are denominated in.
+ * A host budgeting tokens passes its own `cost`; the settlement then replaces it
+ * with the vendor's own figure either way. Upgrade path: a per-executor estimate,
+ * which is per-model weighting and Ask-First (deferred-work.md).
+ */
+export const DEFAULT_EXECUTOR_ACTION_COST = 1;
+/**
+ * The vendor's own usage figure, as the adapter put it on the envelope.
+ *
+ * Forwarded whatever it is, never sanitised here: an absent key means "nothing
+ * observed this run" and charges the estimate, while a PRESENT but broken value
+ * is a coded rejection the pipeline owns and records. Quietly turning the second
+ * into the first would hide a lying adapter behind a normal-looking run.
+ */
+function reportedUsage(envelope) {
+    const data = envelope.data;
+    if (!isRecord(data) || !Object.hasOwn(data, USAGE_DATA_KEY))
+        return undefined;
+    return data[USAGE_DATA_KEY];
+}
+/**
+ * The plugin's own subtree of the kernel's layered configuration.
+ *
+ * That subtree is a STRING, not an object, and that is the point: brambo's
+ * `.brambo/config.json` already spells its executor selection as
+ * `{"executor": "codex"}`, so the plugin reads the document the user already
+ * writes rather than a parallel one invented for the container.
+ */
+const EXECUTOR_CONFIG_SCHEMA = defineStandardSchema((value) => {
+    if (value === undefined)
+        return { value: undefined };
+    if (!isNonEmptyString(value)) {
+        return {
+            issues: [
+                issue(`'${EXECUTOR_CONFIG_KEY}' must be a string naming one of: ${availableExecutorIds().join(', ')}`),
+            ],
+        };
+    }
+    const executorId = value.trim();
+    if (!EXECUTOR_CATALOGUE.has(executorId)) {
+        return { issues: [issue(unknownExecutor(executorId).message)] };
+    }
+    return { value: executorId };
+});
+/**
+ * The executor adapter as a kernel plugin: a manifest providing the `executor`
+ * service, a factory that resolves WHICH adapter from the kernel's own composed
+ * configuration, and a disposer that drops it.
+ *
+ * Misconfiguration REJECTS activation (a contained start failure naming this
+ * plugin), never a mid-run surprise — the same rule `@skanl/brambo-registry`'s plugin
+ * follows, and the reason a bad `executor` key cannot take the kernel down.
+ *
+ * The honest scope of the no-bypass claim, corrected on review: this SERVICE
+ * exports no path around the waterfall, and the object it hands back is frozen
+ * so no other caller can be taken off it either. Three routes remain open and
+ * are named in `deferred-work.md` rather than narrated away:
+ *   - anyone who installs THIS package can call `createExecutorAdapter(id)` or
+ *     any of the three vendor factories and drive an adapter directly;
+ *   - this `factory` is a `PluginFactory`, so a holder can invoke it with an
+ *     `ActivationContext` of their own and get a real adapter wired to their own
+ *     pipeline — inherent to the plugin shape, and the reason `@skanl/brambo-session`
+ *     does not re-export it;
+ *   - `kernel.swap` runs a caller-supplied factory against the live registry, so
+ *     a kernel holder can replace this service outright.
+ */
+export function createExecutorPlugin(options = {}) {
+    // ONE read of every caller-supplied field, at CONSTRUCTION. `createActionPipeline`
+    // states the discipline verbatim — "a budget a caller can raise after
+    // construction by mutating the object it handed in is not a budget" — and
+    // reading `cost` inside the factory reopened exactly that: mutating the
+    // options object between here and `kernel.start()` priced a run at 0 under a
+    // 0.5 cap. Measured, then closed.
+    const { createAdapter, adapterOptions, cost = DEFAULT_EXECUTOR_ACTION_COST } = options;
+    const manifest = {
+        id: EXECUTOR_PLUGIN_ID,
+        version: '0.0.0',
+        provides: [EXECUTOR_SERVICE],
+        consumes: [],
+        configSchema: EXECUTOR_CONFIG_SCHEMA,
+    };
+    const factory = (context) => {
+        // Since M7.C the KERNEL resolves `config.resolve()[manifest.id]`, validates
+        // it against this plugin's own `configSchema`, and refuses the plugin before
+        // this body runs — so the read, the subtree pick, the validate call, the
+        // promise check and the issue mapping that used to live here are gone. What
+        // arrives is the schema's own `value`, already checked.
+        //
+        // The plugin id IS the config key (`executor` both), which is the rule the
+        // kernel now states rather than the convention three plugins each spelled out.
+        const selected = context.settings;
+        const adapter = createAdapter === undefined ? createExecutorAdapter(selected, adapterOptions) : createAdapter();
+        const executorId = createAdapter === undefined ? selected ?? DEFAULT_EXECUTOR_ID : '(injected)';
+        let disposed = false;
+        // FROZEN, and not merely `readonly`: `getService` hands every caller the
+        // same object, so an un-frozen one let a kernel holder who never had the
+        // adapter overwrite `run` and take every OTHER caller off the waterfall —
+        // measured at three runs past a cap of 1 with an empty record stream. The
+        // pipeline freezes its handle and its descriptor for the same reason.
+        const service = Object.freeze({
+            executorId,
+            async run(actionId, request) {
+                if (disposed) {
+                    // Coded, and it names the plugin: a handle kept past `kernel.stop()`
+                    // reaching a live adapter is the disposal leak this pairing exists to
+                    // prevent, and `undefined` is what it would otherwise look like.
+                    throw new BramboError(BRAMBO_ERROR_CODES.kernelPluginInactive, `plugin '${EXECUTOR_PLUGIN_ID}' is inactive: the '${EXECUTOR_SERVICE}' service was disposed with its plugin`);
+                }
+                // Registered per invocation, because `ActionDefinition.run` takes no
+                // arguments: the pipeline reads the operation ONCE at registration and
+                // holds it, which is what stops a caller swapping the operation after
+                // the price was agreed. A per-request handle is the only shape that
+                // survives that rule.
+                //
+                // ponytail: a pipeline remembers every id it ever registered, so a
+                // long-lived kernel running many sessions grows that set. Workspace ids
+                // are UUIDs, so collisions are not the concern — retention is. Upgrade
+                // path: a pipeline that can retire a handle, which is the same mechanism
+                // a post-hoc cost adjustment needs (deferred-work.md).
+                const handle = context.actions.register({
+                    id: actionId,
+                    cost,
+                    run: () => adapter.run(request),
+                    // Admitted at the estimate, reconciled to what the vendor reported.
+                    // Declared HERE, beside `cost` and `run`, because the pipeline reads
+                    // all three once at registration and the caller supplies none of them.
+                    //
+                    // A failed or cancelled run still resolves an envelope, and the adapter
+                    // now reads the vendor's figure off EVERY outcome — a killed child
+                    // settles carrying what it had already printed — so whatever it spent
+                    // before it gave up is charged. A run that produced no figure keeps its
+                    // estimate, and the pipeline floors a settlement at that estimate, so
+                    // there is no path on which failing, cancelling or under-reporting is
+                    // cheaper than reporting honestly.
+                    settle: reportedUsage,
+                });
+                return await handle.invoke();
+            },
+        });
+        return {
+            status: 'activated',
+            services: { [EXECUTOR_SERVICE]: service },
+            dispose: () => {
+                // The adapter itself owns no resource between runs (each run spawns and
+                // reaps its own child), so disposal is about the SERVICE: a handle kept
+                // past `kernel.stop()` must not still be able to spawn.
+                disposed = true;
+            },
+        };
+    };
+    return { manifest, factory };
+}

package/dist/spawn-seam.d.ts

@@ -0,0 +1,38 @@
+export interface SpawnOutcome {
+    /** null when the process was killed by a signal or never spawned. */
+    readonly exitCode: number | null;
+    readonly stdout: string;
+    readonly stderr: string;
+    /** Set only when the process could not be spawned at all (e.g. missing binary). */
+    readonly spawnErrorMessage?: string;
+    /** Set when a pipe to/from the child failed mid-run (e.g. EPIPE on stdin write). */
+    readonly streamErrorMessage?: string;
+    readonly stdoutTruncated?: boolean;
+    readonly stderrTruncated?: boolean;
+}
+export interface SpawnedChild {
+    /** undefined when the platform refused to start the process. */
+    readonly pid: number | undefined;
+    /**
+     * Synchronously true once `done` has been resolved. Callers need this to
+     * decide SYNCHRONOUSLY whether a run already finished: `done.then(...)` only
+     * runs a microtask later, and an abort dispatched inside that window would
+     * otherwise discard a completed run as cancelled.
+     */
+    readonly settled: boolean;
+    writeStdin(chunk: string): void;
+    endStdin(): void;
+    /**
+     * Terminate the child AND every descendant it spawned. Idempotent; safe to
+     * call even when the process already exited.
+     */
+    killTree(): void;
+    /** Resolves exactly once, after the whole tree has settled. Never rejects. */
+    readonly done: Promise<SpawnOutcome>;
+}
+export interface SpawnOptions {
+    readonly cwd: string;
+}
+export interface ChildProcessSpawner {
+    spawn(command: string, args: readonly string[], options: SpawnOptions): SpawnedChild;
+}

package/dist/spawn-seam.js

@@ -0,0 +1,5 @@
+// The child-process seam. The adapter talks to executors exclusively through this
+// interface, so unit tests and the contract suite run against fake children while
+// the real Node spawner (with Windows-safe process-tree termination) is exercised
+// by the overhead measurement and the env-gated live smoke.
+export {};