@ai-codebot/daemon 0.1.0

package/dist/frames.js

@@ -0,0 +1,137 @@
+/**
+ * Wire frame protocol for `/daemon/connect` — TS mirror of the server's
+ * `daemon_frames.py` (PR2). Field-for-field, snake_case keys.
+ *
+ * Directionality (matches the Python contract):
+ *   - Server -> daemon (INBOUND, zod-validated at the boundary):
+ *       HelloAck, Launch, Ping, ServerError
+ *   - Daemon -> server (OUTBOUND, constructed by us, trusted):
+ *       Hello, Progress, Result, Pong
+ *
+ * The server validates the daemon->server direction; we validate the
+ * server->daemon direction. `parseInbound` is the boundary validator: an unknown
+ * `type` or a malformed field throws a `ZodError` the receive loop catches and
+ * ignores (never crashes the loop) — mirroring `parse_inbound`.
+ *
+ * Secrets: `ModelOverride.api_key` is a custom-provider credential — NEVER logged.
+ */
+import { z } from "zod";
+/**
+ * Largest frame we accept (design §8.7 / `daemon_frames.MAX_FRAME_BYTES`): 256 KiB.
+ * Used as the `ws` `maxPayload`. Must equal the server's ceiling field-for-field.
+ */
+export const MAX_FRAME_BYTES = 256 * 1024;
+/** Terminal launch outcomes a daemon may report (`Result.status`). */
+export const RESULT_STATUSES = ["succeeded", "failed", "timed_out"];
+// --------------------------------------------------------------------------- //
+// Shared sub-models
+// --------------------------------------------------------------------------- //
+/** Custom-provider model override carried on a Launch (C4/C8). `apiKey` is secret. */
+export const ModelOverrideSchema = z.object({
+    kind: z.literal("custom").default("custom"),
+    api_url: z.string(),
+    api_key: z.string(),
+});
+// --------------------------------------------------------------------------- //
+// Server -> daemon (INBOUND — we validate these)
+// --------------------------------------------------------------------------- //
+export const HelloAckSchema = z.object({
+    type: z.literal("hello_ack"),
+    machine_id: z.string(),
+    server_time: z.string(),
+    heartbeat_interval_s: z.number().int(),
+});
+export const LaunchSchema = z.object({
+    type: z.literal("launch"),
+    launch_id: z.string(),
+    agent_id: z.string(),
+    prompt: z.string(),
+    repo: z.string().nullish(),
+    model_override: ModelOverrideSchema.nullish(),
+    capabilities: z.array(z.string()).default([]),
+    deadline_s: z.number().int(),
+});
+export const PingSchema = z.object({
+    type: z.literal("ping"),
+    nonce: z.string(),
+});
+export const ServerErrorSchema = z.object({
+    type: z.literal("error"),
+    code: z.string(),
+    detail: z.string(),
+    launch_id: z.string().nullish(),
+});
+/** Discriminated union of every frame the SERVER may send us (inbound). */
+export const InboundFrameSchema = z.discriminatedUnion("type", [
+    HelloAckSchema,
+    LaunchSchema,
+    PingSchema,
+    ServerErrorSchema,
+]);
+// --------------------------------------------------------------------------- //
+// Daemon -> server (OUTBOUND — we construct these)
+// --------------------------------------------------------------------------- //
+// Bounds mirror the server's Hello (`max_length=200`, `max_length=100`): a buggy
+// or oversized Hello cannot store an unbounded scope-attestation blob.
+export const HELLO_MAX_TOOL_LEN = 200;
+export const HELLO_MAX_TOOLS = 100;
+export const HELLO_MAX_VERSION_LEN = 200;
+export const HelloSchema = z.object({
+    type: z.literal("hello"),
+    daemon_version: z.string().max(HELLO_MAX_VERSION_LEN),
+    advertised_tools: z
+        .array(z.string().max(HELLO_MAX_TOOL_LEN))
+        .max(HELLO_MAX_TOOLS)
+        .default([]),
+});
+export const ProgressSchema = z.object({
+    type: z.literal("progress"),
+    launch_id: z.string(),
+    stage: z.string(),
+    message: z.string().default(""),
+});
+export const ResultSchema = z.object({
+    type: z.literal("result"),
+    launch_id: z.string(),
+    status: z.enum(RESULT_STATUSES),
+    text: z.string().nullish(),
+    diff: z.string().nullish(),
+    files: z.array(z.string()).nullish(),
+    cost_usd: z.number().nullish(),
+    tokens: z.number().int().nullish(),
+    error: z.string().nullish(),
+});
+export const PongSchema = z.object({
+    type: z.literal("pong"),
+    nonce: z.string(),
+});
+// --------------------------------------------------------------------------- //
+// Boundary validators
+// --------------------------------------------------------------------------- //
+/**
+ * Validate one decoded server->daemon message at the boundary (mirrors
+ * `parse_inbound`). Throws `ZodError` on an unknown `type` or any malformed
+ * field; the receive loop catches it, logs, and ignores the frame.
+ */
+export function parseInbound(raw) {
+    return InboundFrameSchema.parse(raw);
+}
+// --------------------------------------------------------------------------- //
+// Outbound constructors (typed, defaults filled — never validated, we trust us)
+// --------------------------------------------------------------------------- //
+export function makeHello(daemonVersion, advertisedTools = []) {
+    return {
+        type: "hello",
+        daemon_version: daemonVersion.slice(0, HELLO_MAX_VERSION_LEN),
+        advertised_tools: advertisedTools
+            .slice(0, HELLO_MAX_TOOLS)
+            .map((t) => t.slice(0, HELLO_MAX_TOOL_LEN)),
+    };
+}
+export function makePong(nonce) {
+    return { type: "pong", nonce };
+}
+export function makeProgress(launchId, stage, message = "") {
+    return { type: "progress", launch_id: launchId, stage, message };
+}
+//# sourceMappingURL=frames.js.map

package/dist/frames.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"frames.js","sourceRoot":"","sources":["../src/frames.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+/**
+ * `@ai-codebot/daemon` entrypoint (bin: `codebot-daemon`).
+ *
+ * slock local-runner PR4 — dials the cloud relay over outbound WSS and runs local
+ * coding-agent launches through a 127.0.0.1 capability broker. See README / design
+ * doc `docs/superpowers/specs/2026-06-08-slock-PR4-daemon-package-design.md`.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+/**
+ * `@ai-codebot/daemon` entrypoint (bin: `codebot-daemon`).
+ *
+ * slock local-runner PR4 — dials the cloud relay over outbound WSS and runs local
+ * coding-agent launches through a 127.0.0.1 capability broker. See README / design
+ * doc `docs/superpowers/specs/2026-06-08-slock-PR4-daemon-package-design.md`.
+ */
+import { main } from "./cli.js";
+import { log } from "./logging.js";
+main(process.argv.slice(2))
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((err) => {
+    log.error("daemon.fatal", { error: err.message });
+    process.exitCode = 1;
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,UAAU,CAAC;AAChC,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AAEnC,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;KACxB,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE;IACb,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC;AAC1B,CAAC,CAAC;KACD,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE;IACb,GAAG,CAAC,KAAK,CAAC,cAAc,EAAE,EAAE,KAAK,EAAG,GAAa,CAAC,OAAO,EAAE,CAAC,CAAC;IAC7D,OAAO,CAAC,QAAQ,GAAG,CAAC,CAAC;AACvB,CAAC,CAAC,CAAC"}

package/dist/launch.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Launch orchestration (design §4/§5/§6): on a `Launch` frame, stand up the
+ * per-launch capability broker, build the scrubbed spawn env, run the executor
+ * (PRIMARY CLI → N2 fallback), map the outcome to exactly one `Result`, and tear
+ * everything down idempotently.
+ *
+ * Invariants:
+ *   - 零静默 (C8/C9): exactly ONE terminal `Result` per launch. No silent fallback —
+ *     model unreachable / no model configured / no CLI + no N2 → loud `failed`.
+ *   - The real LLM key lives ONLY in the broker; the child sees a per-launch token.
+ *   - Idempotent teardown on result / deadline / signal: broker close, token unlink,
+ *     child kill. Tracked so SIGINT/SIGTERM tears down ALL live launches.
+ */
+import type { Launch, Result } from "./frames.js";
+import type { CliKind } from "./config.js";
+export interface LaunchRunnerDeps {
+    readonly cliMode: CliKind;
+    /** Optional `--model-url` fallback when the launch carries no model_override. */
+    readonly modelUrlFallback: string | null;
+}
+/**
+ * Owns all in-flight launches so a signal can tear them ALL down (no orphan
+ * children / `0600` token files). One `GrantRegistry` is shared; each launch gets a
+ * fresh token + broker.
+ */
+export declare class LaunchManager {
+    private readonly deps;
+    private readonly grants;
+    private readonly live;
+    constructor(deps: LaunchRunnerDeps);
+    /**
+     * Run one launch end-to-end and return exactly one terminal `Result`. Never
+     * throws — every failure path becomes a `failed` / `timed_out` result.
+     */
+    run(launch: Launch, onProgress: (stage: string) => void): Promise<Result>;
+    /** PRIMARY CLI → N2 fallback. No CLI + N2 unusable → loud failed (handled by N2). */
+    private execute;
+    /** Tear down every live launch (SIGINT/SIGTERM). Idempotent. */
+    shutdownAll(): Promise<void>;
+}

package/dist/launch.js

@@ -0,0 +1,163 @@
+/**
+ * Launch orchestration (design §4/§5/§6): on a `Launch` frame, stand up the
+ * per-launch capability broker, build the scrubbed spawn env, run the executor
+ * (PRIMARY CLI → N2 fallback), map the outcome to exactly one `Result`, and tear
+ * everything down idempotently.
+ *
+ * Invariants:
+ *   - 零静默 (C8/C9): exactly ONE terminal `Result` per launch. No silent fallback —
+ *     model unreachable / no model configured / no CLI + no N2 → loud `failed`.
+ *   - The real LLM key lives ONLY in the broker; the child sees a per-launch token.
+ *   - Idempotent teardown on result / deadline / signal: broker close, token unlink,
+ *     child kill. Tracked so SIGINT/SIGTERM tears down ALL live launches.
+ */
+import { CliContractUnverifiedError, runCli } from "./spawn/cli-runner.js";
+import { detectCli } from "./spawn/detect.js";
+import { buildSpawnEnv, createTokenFile, removeTokenDir, } from "./broker/handoff.js";
+import { GrantRegistry } from "./broker/token.js";
+import { startBroker } from "./broker/server.js";
+import { log } from "./logging.js";
+import { runN2 } from "./spawn/n2-runner.js";
+import { toResult } from "./spawn/result-map.js";
+// Default N2 model id when the launch carries no explicit one.
+// TODO(OQ-6): the Launch wire frame carries NO model id — the broker forwards to the
+// tenant's own endpoint, so the upstream provider resolves the actual model. This
+// placeholder is only the OpenAI-compatible `model` field the request must include;
+// it is NOT authoritative. Track resolving the real per-launch model id in OQ-6.
+const DEFAULT_N2_MODEL = "claude-3-5-sonnet-latest";
+const N2_TEST_TIMEOUT_MS = 120_000;
+/**
+ * Owns all in-flight launches so a signal can tear them ALL down (no orphan
+ * children / `0600` token files). One `GrantRegistry` is shared; each launch gets a
+ * fresh token + broker.
+ */
+export class LaunchManager {
+    deps;
+    grants = new GrantRegistry();
+    live = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /**
+     * Run one launch end-to-end and return exactly one terminal `Result`. Never
+     * throws — every failure path becomes a `failed` / `timed_out` result.
+     */
+    async run(launch, onProgress) {
+        const launchId = launch.launch_id;
+        const repo = launch.repo ?? process.cwd();
+        const deadlineMs = Math.max(1, launch.deadline_s) * 1000;
+        // Resolve the upstream model endpoint: launch.model_override wins, else
+        // --model-url. No model configured → loud failed (P5, no silent server fallback).
+        const upstreamUrl = launch.model_override?.api_url ?? this.deps.modelUrlFallback;
+        const upstreamKey = launch.model_override?.api_key ?? "";
+        if (!upstreamUrl) {
+            return toResult(launchId, {
+                kind: "failed",
+                error: "no model configured (launch has no model_override and no --model-url was given)",
+            });
+        }
+        const grant = this.grants.create(launchId, upstreamUrl, upstreamKey);
+        const abort = new AbortController();
+        let broker = null;
+        let tokenFileHandle = null;
+        let torndown = false;
+        const teardown = async () => {
+            if (torndown)
+                return;
+            torndown = true;
+            abort.abort();
+            this.grants.revoke(grant.token);
+            if (tokenFileHandle !== null)
+                removeTokenDir(tokenFileHandle.dir);
+            if (broker !== null) {
+                try {
+                    await broker.close();
+                }
+                catch (err) {
+                    log.warn("launch.broker_close_failed", {
+                        launch_id: launchId,
+                        error: err.message,
+                    });
+                }
+            }
+            this.live.delete(launchId);
+        };
+        this.live.set(launchId, { launchId, teardown });
+        const deadlineTimer = setTimeout(() => abort.abort(), deadlineMs);
+        try {
+            onProgress("preparing");
+            broker = await startBroker(this.grants);
+            tokenFileHandle = createTokenFile(grant.token);
+            const env = buildSpawnEnv({
+                brokerBaseUrl: broker.baseUrl,
+                token: grant.token,
+                tokenFile: tokenFileHandle.path,
+                capabilities: launch.capabilities ?? [],
+            });
+            onProgress("running");
+            const outcome = await this.execute(launch, repo, env, broker.baseUrl, grant.token, abort.signal, deadlineMs);
+            return toResult(launchId, outcome);
+        }
+        catch (err) {
+            // Defensive: any unexpected throw still yields exactly one failed Result.
+            log.error("launch.unexpected_error", {
+                launch_id: launchId,
+                error: err.message,
+            });
+            return toResult(launchId, {
+                kind: "failed",
+                error: `launch failed: ${err.message}`,
+            });
+        }
+        finally {
+            clearTimeout(deadlineTimer);
+            await teardown();
+        }
+    }
+    /** PRIMARY CLI → N2 fallback. No CLI + N2 unusable → loud failed (handled by N2). */
+    async execute(launch, repo, env, brokerBaseUrl, token, signal, deadlineMs) {
+        const detected = detectCli(this.deps.cliMode, env);
+        if (detected !== null) {
+            try {
+                return await runCli({
+                    cli: detected,
+                    repo,
+                    prompt: launch.prompt,
+                    env,
+                    deadlineMs,
+                    signal,
+                });
+            }
+            catch (err) {
+                if (err instanceof CliContractUnverifiedError) {
+                    // OQ-3: refuse a possibly-wrong invocation → fall through to N2.
+                    log.warn("launch.cli_unverified_fallback_n2", {
+                        launch_id: launch.launch_id,
+                        cli: detected,
+                    });
+                }
+                else {
+                    throw err;
+                }
+            }
+        }
+        // N2 fallback (the fully-working path). Uses the launch's model id if carried in
+        // the prompt's provider expectation — default otherwise; the broker forwards it.
+        return runN2({
+            repo,
+            prompt: launch.prompt,
+            model: DEFAULT_N2_MODEL,
+            brokerBaseUrl,
+            token,
+            env,
+            testTimeoutMs: N2_TEST_TIMEOUT_MS,
+            signal,
+        });
+    }
+    /** Tear down every live launch (SIGINT/SIGTERM). Idempotent. */
+    async shutdownAll() {
+        const pending = [...this.live.values()].map((l) => l.teardown());
+        await Promise.allSettled(pending);
+    }
+}
+//# sourceMappingURL=launch.js.map

package/dist/launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../src/launch.ts"],"names":[],"mappings":"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"}

package/dist/logging.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Structured stderr logging with hard secret redaction (design §10.8).
+ *
+ * Everything goes to **stderr** (stdout is reserved for any future machine-readable
+ * output and must stay clean). Every value is run through `redact()` before it is
+ * written, so the real LLM `api_key`, the per-launch capability token, and the
+ * `ck_machine_` machine key can never appear in a log line — even if a caller
+ * passes one in by mistake.
+ *
+ * Redaction is value-based (mask anything that looks like a known secret) AND
+ * key-based (mask the value of any field whose name is sensitive). Defense in depth:
+ * the daemon never intentionally logs secrets, but a single careless interpolation
+ * must not leak a Tier-A credential.
+ */
+/**
+ * Deep-redact an arbitrary value: mask sensitive-keyed fields wholesale and any
+ * string value carrying a known secret prefix. Returns a NEW structure (never
+ * mutates the input, per the codebase immutability rule).
+ */
+export declare function redact(value: unknown, depth?: number): unknown;
+export type LogFields = Record<string, unknown>;
+export declare const log: {
+    info: (event: string, fields?: LogFields) => void;
+    warn: (event: string, fields?: LogFields) => void;
+    error: (event: string, fields?: LogFields) => void;
+    debug: (event: string, fields?: LogFields) => void;
+};

package/dist/logging.js

@@ -0,0 +1,91 @@
+/**
+ * Structured stderr logging with hard secret redaction (design §10.8).
+ *
+ * Everything goes to **stderr** (stdout is reserved for any future machine-readable
+ * output and must stay clean). Every value is run through `redact()` before it is
+ * written, so the real LLM `api_key`, the per-launch capability token, and the
+ * `ck_machine_` machine key can never appear in a log line — even if a caller
+ * passes one in by mistake.
+ *
+ * Redaction is value-based (mask anything that looks like a known secret) AND
+ * key-based (mask the value of any field whose name is sensitive). Defense in depth:
+ * the daemon never intentionally logs secrets, but a single careless interpolation
+ * must not leak a Tier-A credential.
+ */
+// Sensitive FIELD names — the value of any of these keys is masked wholesale.
+const SENSITIVE_KEYS = new Set([
+    "api_key",
+    "apikey",
+    "apiKey",
+    "key",
+    "token",
+    "capability_token",
+    "capabilityToken",
+    "machine_key",
+    "machineKey",
+    "authorization",
+    "bearer",
+    "secret",
+    "password",
+]);
+// Value PREFIXES that mark a string as a known secret regardless of where it sits.
+const SECRET_PREFIXES = ["ck_machine_", "sk-", "sk_"];
+// The per-launch capability token is 32 bytes base64url (≈43 chars, charset
+// [A-Za-z0-9_-], no prefix). Mask anything matching that shape so a future log of the
+// token under an arbitrary field name is still redacted — defense in depth, since the
+// daemon never intentionally logs it. The 40-48 band is tight enough to avoid masking
+// ordinary identifiers (UUIDs carry `-` groups far shorter than 40 contiguous chars).
+const CAPABILITY_TOKEN_RE = /^[A-Za-z0-9_-]{40,48}$/;
+const MASK = "***REDACTED***";
+/** Mask a single string value if it looks like a known secret. */
+function redactString(value) {
+    for (const prefix of SECRET_PREFIXES) {
+        if (value.startsWith(prefix))
+            return MASK;
+    }
+    if (CAPABILITY_TOKEN_RE.test(value))
+        return MASK;
+    return value;
+}
+/**
+ * Deep-redact an arbitrary value: mask sensitive-keyed fields wholesale and any
+ * string value carrying a known secret prefix. Returns a NEW structure (never
+ * mutates the input, per the codebase immutability rule).
+ */
+export function redact(value, depth = 0) {
+    if (depth > 8)
+        return value; // bound recursion on pathological input
+    if (typeof value === "string")
+        return redactString(value);
+    if (Array.isArray(value))
+        return value.map((v) => redact(v, depth + 1));
+    if (value && typeof value === "object") {
+        const out = {};
+        for (const [k, v] of Object.entries(value)) {
+            out[k] = SENSITIVE_KEYS.has(k) ? MASK : redact(v, depth + 1);
+        }
+        return out;
+    }
+    return value;
+}
+function emit(level, event, fields) {
+    const line = {
+        ts: new Date().toISOString(),
+        level,
+        event,
+    };
+    if (fields) {
+        for (const [k, v] of Object.entries(fields)) {
+            line[k] = SENSITIVE_KEYS.has(k) ? MASK : redact(v);
+        }
+    }
+    // stderr only — keep stdout clean.
+    process.stderr.write(JSON.stringify(line) + "\n");
+}
+export const log = {
+    info: (event, fields) => emit("info", event, fields),
+    warn: (event, fields) => emit("warn", event, fields),
+    error: (event, fields) => emit("error", event, fields),
+    debug: (event, fields) => emit("debug", event, fields),
+};
+//# sourceMappingURL=logging.js.map

package/dist/logging.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logging.js","sourceRoot":"","sources":["../src/logging.ts"],"names":[],"mappings":"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"}

package/dist/spawn/cli-runner.d.ts

@@ -0,0 +1,91 @@
+/**
+ * PRIMARY executor: spawn a real coding-agent CLI (Claude Code / Codex) in
+ * `cwd=repo`, headless, talking to the broker, with the disallowed-tools blacklist
+ * applied (design §4 — R1-NEW / DR-6).
+ *
+ * ─────────────────────────────────────────────────────────────────────────────
+ * OQ-3: the headless / JSON-output / disallowed-tools flag contract per shipped
+ * CLI. `claude` (Claude Code 2.1.169) flag NAMES are VERIFIED against the real
+ * binary (see the contract entry below); `codex` (codex-cli 0.137.0) is left
+ * `verified:false` because it has NO disallowed-tools concept — its sandbox /
+ * approval model does not map to the C5 tool blacklist, so enabling PRIMARY-codex
+ * needs a design decision and until then the runner FAILS FAST → N2. The runner
+ * NEVER emits a silent wrong invocation. The N2 fallback (n2-runner.ts) is the
+ * fully-tested path that covers "no verified CLI".
+ *
+ * NOTE: the live-model E2E spawn proof remains the MANUAL `verify-daemon.mjs`
+ * step — these unit tests pin the argv shape, not a real spawn against a model.
+ * ─────────────────────────────────────────────────────────────────────────────
+ *
+ * To enable a CLI here: verify the real flag names against the shipped binary,
+ * flip the `verified: true` contract entry, and add an integration proof in
+ * `verify-daemon.mjs`. Until then this runner throws `CliContractUnverifiedError`
+ * and `launch.ts` routes to N2.
+ */
+import type { ExecOutcome } from "./result-map.js";
+/**
+ * Per-CLI flag contract. Each entry describes how to invoke that CLI headlessly
+ * with JSON output and (where the CLI supports it) the C5 disallowed-tools
+ * blacklist.
+ *
+ * `verified: false` means the runner refuses to spawn (fail fast → N2). It is set
+ * either because the flag names are unconfirmed OR because the CLI has no way to
+ * honour the C5 blacklist (codex — see below).
+ */
+interface CliFlagContract {
+    /** Confirmed against a shipped CLI version? If false → fail fast, never spawn. */
+    readonly verified: boolean;
+    /**
+     * Non-interactive SUBCOMMAND that precedes the flags, if the CLI requires one
+     * (codex's headless mode is `codex exec …`). `null` when the CLI is headless at
+     * the top level (claude's `--print`).
+     */
+    readonly subcommand: string | null;
+    /** Headless / non-interactive prompt flag. */
+    readonly headlessFlag: string;
+    /** JSON output flag. */
+    readonly jsonOutputFlag: string;
+    /** Permission/sandbox-bypass flag — tenant's own box; the broker is the boundary. */
+    readonly bypassFlag: string;
+    /**
+     * How the C5 disallowed-tools blacklist maps to argv:
+     *   `variadic` => ONE flag followed by all tools as separate args
+     *                 (claude's `--disallowedTools A B C`);
+     *   `repeated` => one flag per tool;
+     *   `csv`      => one flag with a comma-joined value;
+     *   `none`     => the CLI has no disallowed-tools concept (codex — its
+     *                 sandbox/approval model does not map to a tool blacklist).
+     */
+    readonly disallowStyle: "variadic" | "repeated" | "csv" | "none";
+    /** The disallowed-tools flag name (empty when `disallowStyle === "none"`). */
+    readonly disallowFlag: string;
+}
+export declare class CliContractUnverifiedError extends Error {
+    constructor(cli: string);
+}
+export interface CliRunParams {
+    readonly cli: "claude" | "codex";
+    readonly repo: string;
+    readonly prompt: string;
+    readonly env: Record<string, string>;
+    readonly deadlineMs: number;
+    /** Abort signal fired on launch teardown / deadline. */
+    readonly signal: AbortSignal;
+}
+/**
+ * Build the argv for a CLI invocation. PUBLIC for unit testing the argv shape
+ * (disallowed-tools present, bypass flag, headless+json) without spawning.
+ */
+export declare function buildCliArgv(cli: "claude" | "codex", prompt: string): {
+    command: string;
+    args: string[];
+    contract: CliFlagContract;
+};
+/**
+ * Run the PRIMARY CLI. Throws `CliContractUnverifiedError` if the flag contract is
+ * not verified (OQ-3 fail-fast) so the caller routes to N2 — NEVER a silent wrong
+ * invocation. On a verified contract, spawns, captures the BASE..HEAD diff, and
+ * maps the exit code to an outcome.
+ */
+export declare function runCli(params: CliRunParams): Promise<ExecOutcome>;
+export {};