akm-cli 0.9.0-beta.9 → 0.9.0-rc.1

package/dist/integrations/harnesses/amazonq/agent-builder.js

@@ -0,0 +1,153 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Amazon Q Developer CLI agent command builder (P2, plan §"The adapter
+ * contract" step 2 / §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `q` CLI expects. Per the capability matrix the headless
+ * invocation is:
+ *
+ *   q chat --no-interactive --trust-all-tools "<prompt>"
+ *
+ * with `--model <m>` for model selection and `--resume` for resume. Resume is
+ * registry-side (`AkmHarness.resume`, {@link AMAZONQ_RESUME_FLAG}) — and NOTE:
+ * unlike every other harness's resume, Q's `--resume` is a bare flag that
+ * replays the previous conversation *of the working directory*; it takes no
+ * session id. There is nothing to thread from `workflow_run_units` — akm's own
+ * unit rows remain the durable resume source of truth regardless (plan
+ * §"Session, MCP, and identity across harnesses").
+ *
+ * Platform-specific mapping decisions (all localized here, per the adapter
+ * contract):
+ *
+ * - **subcommand** — headless dispatch is the `chat` subcommand. The builder
+ *   prepends `chat` itself (mirroring the codex builder's `exec` handling); a
+ *   user profile that already pins `chat` as its first arg is not doubled.
+ * - **prompt** — the trailing positional `[INPUT]` argument of `q chat`,
+ *   preceded by the `--` end-of-options separator (mirroring the
+ *   claude/codex/pi builders) so a prompt whose text begins with `-`/`--` can
+ *   never be parsed as flags. `--no-interactive` makes Q print the response
+ *   and exit instead of opening the REPL.
+ * - **systemPrompt** — `q chat` has no system-prompt flag (persona/context
+ *   comes from Q's own agent config files), so the system prompt is folded
+ *   into the positional payload ahead of the task prompt, separated by a
+ *   blank line. `assertNotFlag` still guards it.
+ * - **schema** — the matrix places Q in the NO-structured-output tier
+ *   ("via prompt+validate": *(none documented)* — there is no `--json` or
+ *   `--output-format` to ask for). The JSON Schema is therefore passed
+ *   through the prompt: a directive matching the engine's wording
+ *   (`step-work.ts` `buildUnitPrompt`) is appended to the payload.
+ *   Stdout stays plain text; `./result-extractor.ts` strips terminal framing
+ *   and the engine's shared embedded-JSON parse + retry-until-valid loop does
+ *   the rest. No schema temp file is written — that seam is codex-only
+ *   (`--output-schema`); inventing a flag here would produce a silently
+ *   broken command.
+ * - **tools** — a string/array tool policy maps to Q's documented
+ *   `--trust-tools=<t1,t2>` allowlist flag (equals-joined, per `q chat
+ *   --help`). With no policy at all, headless runs need autonomy, so
+ *   `--trust-all-tools` is emitted per the matrix. A *structured* policy
+ *   object is NOT expressible as Q flags; it is deliberately dropped without
+ *   falling back to `--trust-all-tools` (never silently widen a restriction)
+ *   — Q then refuses untrusted tool actions in non-interactive mode, which is
+ *   the conservative failure mode.
+ * - **effort** — stays unconsumed (reserved; the shared request contract's
+ *   "no builder consumes it yet" note stays true).
+ *
+ * NOT registered anywhere: `builders.ts` / `harnesses/index.ts` wiring is a
+ * follow-up integration task (as is the registry-side capability entry —
+ * pattern `local-runner`, structuredOutput `none`). Exported standalone so
+ * that task only adds a registry entry.
+ */
+import { assertNotFlag } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.js";
+/** Canonical harness/platform id used for model-alias resolution. */
+export const AMAZONQ_PLATFORM = "amazonq";
+/**
+ * Resume flag per the capability matrix (`--resume`). Exported for the
+ * integration task's `AkmHarness.resume` registry entry. Bare flag: Q resumes
+ * the previous conversation of the current working directory and takes NO
+ * session id value — do not append one after it.
+ */
+export const AMAZONQ_RESUME_FLAG = "--resume";
+/**
+ * Split a tool policy into individual tool names for `--trust-tools`.
+ * Strings are comma-separated lists; arrays are taken as-is. Structured
+ * policy objects return `undefined` (not expressible as Q flags — see
+ * module doc).
+ */
+function toolPolicyEntries(tools) {
+    if (typeof tools === "string") {
+        return tools
+            .split(",")
+            .map((t) => t.trim())
+            .filter(Boolean);
+    }
+    if (Array.isArray(tools)) {
+        return tools.map((t) => t.trim()).filter(Boolean);
+    }
+    return undefined;
+}
+/**
+ * Assemble the positional prompt payload: optional system prompt, the task
+ * prompt, and — when a schema is requested — the same schema directive the
+ * workflow engine's prompt assembly uses, so both dispatch paths speak one
+ * dialect.
+ */
+function buildPromptPayload(req) {
+    const sections = [];
+    if (req.systemPrompt)
+        sections.push(req.systemPrompt);
+    sections.push(req.prompt);
+    if (req.schema) {
+        sections.push(`Respond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`);
+    }
+    return sections.join("\n\n");
+}
+/**
+ * Amazon Q Developer CLI builder.
+ * Command shape:
+ *   q chat --no-interactive (--trust-all-tools | --trust-tools=<t1,t2>)
+ *          [--model <m>] -- "<systemPrompt?\n\nprompt\n\nschema directive?>"
+ */
+export const amazonqBuilder = {
+    platform: AMAZONQ_PLATFORM,
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        // Built-in q profiles would ship `args: []`; headless dispatch is the
+        // `chat` subcommand. Don't double it when a user profile already pins it.
+        const extra = profile.args[0] === "chat" ? profile.args.slice(1) : [...profile.args];
+        const args = ["chat", ...extra];
+        // Print the response and exit — required for captured dispatch.
+        args.push("--no-interactive");
+        if (req.tools) {
+            // Structured policy objects (entries === undefined) emit NO trust
+            // flags: dropping a restriction must never widen to --trust-all-tools.
+            const entries = toolPolicyEntries(req.tools);
+            if (entries !== undefined) {
+                for (const tool of entries) {
+                    assertNotFlag(tool, "tools entry");
+                }
+                // Q's documented allowlist form is equals-joined and comma-separated
+                // (`--trust-tools=fs_read,fs_write`); an empty list trusts no tools.
+                args.push(`--trust-tools=${entries.join(",")}`);
+            }
+        }
+        else {
+            // Headless default per the capability matrix: units must run without
+            // interactive tool-approval prompts.
+            args.push("--trust-all-tools");
+        }
+        if (req.model) {
+            const resolved = resolveModel(req.model, AMAZONQ_PLATFORM, profile.modelAliases, profile.globalModelAliases);
+            args.push("--model", resolved);
+        }
+        // No system-prompt / schema flags exist on `q chat` — both travel in the
+        // positional payload, after the end-of-options separator.
+        args.push("--");
+        args.push(buildPromptPayload(req));
+        return { argv: [profile.bin, ...args] };
+    },
+};

package/dist/integrations/harnesses/amazonq/index.js

@@ -0,0 +1,59 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * Amazon Q Developer CLI harness (P2 integration, plan §"The adapter
+ * contract").
+ *
+ * Per-harness barrel gathering the Amazon Q integration surfaces:
+ *   - agent command builder → ./agent-builder.ts    (amazonqBuilder)
+ *   - result extractor      → ./result-extractor.ts (amazonqResultExtractor)
+ *
+ * It also defines {@link AmazonqHarness}, the {@link AkmHarness} descriptor
+ * that `HARNESS_REGISTRY` registers. Dispatch-only: no native session-log
+ * reader or config importer yet.
+ */
+import { BaseHarness } from "../types.js";
+import { AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+import { amazonqResultExtractor } from "./result-extractor.js";
+export { AMAZONQ_PLATFORM, AMAZONQ_RESUME_FLAG, amazonqBuilder } from "./agent-builder.js";
+export { amazonqResultExtractor, stripTerminalFraming } from "./result-extractor.js";
+function caps(c) {
+    return {
+        sessionLogs: false,
+        agentDispatch: false,
+        detection: false,
+        configImport: false,
+        runtimeIdentity: false,
+        v1Migration: false,
+        ...c,
+    };
+}
+/**
+ * Amazon Q Developer CLI (`q`).
+ *
+ * Canonical id is `'amazonq'`; no alias or distinct runtime identity.
+ */
+export class AmazonqHarness extends BaseHarness {
+    id = "amazonq";
+    displayName = "Amazon Q Developer CLI";
+    aliases = [];
+    agentBuilder = amazonqBuilder;
+    resultExtractor = amazonqResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // akm spawns `q chat` locally per unit ⇒ local-runner.
+    pattern = "local-runner";
+    // No documented structured output: akm injects the schema into the prompt
+    // and extracts embedded JSON from plain-text stdout.
+    structuredOutput = "none";
+    // Q's `--resume` is a BARE flag (takesSessionId: false): it replays the
+    // previous conversation of the working directory and takes no session id
+    // (see AMAZONQ_RESUME_FLAG in ./agent-builder.ts).
+    resume = { flag: AMAZONQ_RESUME_FLAG, takesSessionId: false };
+    // No `identityEnv`: the matrix lists Q's identity markers as uncertain, and
+    // Q stamps no session var onto child processes.
+    capabilities = caps({
+        agentDispatch: true,
+        detection: true,
+    });
+}

package/dist/integrations/harnesses/amazonq/result-extractor.js

@@ -0,0 +1,48 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+const ESC = "\u001B";
+const BEL = "\u0007";
+/**
+ * Matches ANSI CSI sequences (colors, cursor movement, erase-line) and OSC
+ * sequences (title, hyperlink) terminated by BEL or ST. Built via the RegExp
+ * constructor so the control characters live in named string constants
+ * instead of regex-literal escapes.
+ */
+const ANSI_SEQUENCE = new RegExp(`${ESC}\\[[0-9;?]*[ -/]*[@-~]` + `|${ESC}\\][^${BEL}${ESC}]*(?:${BEL}|${ESC}\\\\)`, "g");
+/**
+ * Resolve carriage-return overwrites within one physical line: a terminal
+ * would redraw from column 0 at each `\r`, so only the segment after the last
+ * `\r` survives (spinner frames like "⠋ Thinking..." disappear exactly as
+ * they do on screen). A trailing bare `\r` (CRLF line endings) is handled by
+ * splitting on `\r?\n` before this runs.
+ */
+function resolveCarriageReturns(line) {
+    const lastCr = line.lastIndexOf("\r");
+    return lastCr === -1 ? line : line.slice(lastCr + 1);
+}
+/** Strip terminal framing from raw captured stdout. See module doc, rule 1. */
+export function stripTerminalFraming(raw) {
+    const lines = raw.split(/\r?\n/).map((line) => resolveCarriageReturns(line).replace(ANSI_SEQUENCE, ""));
+    // Drop Q's "> " response marker from the first non-empty line only — deeper
+    // occurrences may be legitimate content (markdown blockquotes).
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i] ?? "";
+        if (line.trim().length === 0)
+            continue;
+        if (line.startsWith("> "))
+            lines[i] = line.slice(2);
+        break;
+    }
+    return lines.join("\n").trim();
+}
+/**
+ * Normalize a raw Amazon Q run result into `{ text, sessionId? }`.
+ * See the module doc for the rules.
+ */
+export const amazonqResultExtractor = (result) => {
+    const sessionId = result.sessionId;
+    // Rule 2: a pre-parsed whole-stdout JSON *string* is the answer itself.
+    const text = typeof result.parsed === "string" ? result.parsed.trim() : stripTerminalFraming(result.stdout);
+    return { text, ...(sessionId ? { sessionId } : {}) };
+};

package/dist/integrations/harnesses/claude/agent-builder.js

@@ -11,15 +11,49 @@
  * in `agent/builders.ts`, which imports this builder back into
  * `BUILTIN_BUILDERS`.
  *
- * Behaviour-preserving relocation: the produced argv is byte-identical to the
- * pre-migration `claudeBuilder`. The builder's `platform` stays `'claude'` (the
- * canonical harness id).
+ * ## Structured output (Codex round-3 finding A)
+ *
+ * The headless `claude -p` (`--print`) CLI has NO native output-SCHEMA flag
+ * (unlike Codex's `--output-schema <file>`). Its documented structured path is
+ * `--output-format json`, which wraps the run in a RESULT ENVELOPE
+ * (`{"type":"result","result":"<final answer>","session_id":"…", …}`) — the
+ * "native-json" tier, NOT "native-schema". (The registry's earlier
+ * `native-schema` claim described Claude Code's IN-HARNESS `Workflow`/`agent()`
+ * tool-input-schema path, which is a different execution surface than the
+ * agentBuilder dispatch akm's local-runner uses; the descriptor is aligned to
+ * `native-json` to match this builder honestly.)
+ *
+ * So for a schema-bearing unit this builder emits `--output-format json` and
+ * appends the SAME schema directive the engine's prompt assembly uses
+ * (`step-work.ts` `buildUnitPrompt`) so a direct (non-workflow) dispatch is
+ * self-sufficient — matching the copilot/gemini native-json builders. The
+ * result envelope is unwrapped by `./result-extractor.ts`, and the engine's
+ * shared `runStructured` retry-until-valid loop still validates the extracted
+ * text against the node schema (constrained/hinted output is trusted but
+ * verified). Without a schema the argv is byte-identical to the pre-fix shape.
+ *
+ * The builder's `platform` stays `'claude'` (the canonical harness id).
  */
-import { assertNotFlag, normalizeTools } from "../../agent/builder-shared.js";
+import { assertNotFlag, normalizeTools, } from "../../agent/builder-shared.js";
 import { resolveModel } from "../../agent/model-aliases.js";
+/**
+ * Assemble the positional prompt: the task prompt and — when a schema is
+ * requested — the same schema directive the workflow engine's prompt assembly
+ * uses (`step-work.ts` `buildUnitPrompt`), so both dispatch paths speak one
+ * dialect. Claude Code takes the system prompt as a `--system-prompt` FLAG (it
+ * has one, unlike copilot/gemini), so only the schema directive is folded in
+ * here.
+ */
+function buildPromptPayload(req) {
+    if (!req.schema)
+        return req.prompt;
+    return `${req.prompt}\n\nRespond with ONLY a JSON value matching this JSON Schema (no prose, no code fences):\n${JSON.stringify(req.schema)}`;
+}
 /**
  * Claude Code builder.
- * Command shape: claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>] --print "<prompt>"
+ * Command shape:
+ *   claude [--system-prompt "..."] [--model <m>] [--allowedTools <t>]
+ *          [--output-format json] --print -- "<prompt (+ schema directive)>"
  *
  * --print switches Claude Code to non-interactive captured output mode.
  */
@@ -33,16 +67,21 @@ export const claudeBuilder = {
             args.push("--system-prompt", req.systemPrompt);
         }
         if (req.model) {
-            const resolved = resolveModel(req.model, "claude", profile.modelAliases);
+            const resolved = resolveModel(req.model, "claude", profile.modelAliases, profile.globalModelAliases);
             args.push("--model", resolved);
         }
         if (req.tools) {
             args.push("--allowedTools", normalizeTools(req.tools));
         }
+        if (req.schema) {
+            // Structured unit: request the documented JSON result envelope so
+            // `./result-extractor.ts` can pull the final answer + session id.
+            args.push("--output-format", "json");
+        }
         // --print = non-interactive, outputs to stdout — required for captured mode
         args.push("--print");
         args.push("--");
-        args.push(req.prompt);
+        args.push(buildPromptPayload(req));
         return { argv: [profile.bin, ...args] };
     },
 };

package/dist/integrations/harnesses/claude/index.js

@@ -1,32 +1,13 @@
 // This Source Code Form is subject to the terms of the Mozilla Public
 // License, v. 2.0. If a copy of the MPL was not distributed with this
 // file, You can obtain one at https://mozilla.org/MPL/2.0/.
-/**
- * Claude Code harness (#563).
- *
- * This is the per-harness barrel that gathers the Claude Code integration
- * surfaces that were previously scattered across the codebase:
- *   - session-log reader     → ./session-log.ts   (ClaudeCodeProvider)
- *   - agent command builder  → ./agent-builder.ts (claudeBuilder)
- *   - config importer        → ./config-import.ts (claudeCodeImporter)
- *
- * It also defines {@link ClaudeHarness}, the {@link AkmHarness} descriptor that
- * `HARNESS_REGISTRY` registers.
- *
- * ## id normalization bridge ('claude' vs 'claude-code')
- *
- * The canonical, persisted id is `'claude'` (used by the agent runner, agent
- * profiles, the Zod config schema and `--type` resolution after normalization).
- * `'claude-code'` is the historical RUNTIME identity — the string stamped on
- * session-log events/refs, the extracted-session dedup key, and the value
- * `resolveAgentIdentity` reports. It is registered as an `alias` and exposed as
- * `runtimeId` so BOTH directions round-trip via `normalizeHarnessId()` /
- * `denormalizeRuntimeIdentity()`. Existing persisted configs and session logs
- * that say `'claude-code'` keep working unchanged.
- */
 import { BaseHarness } from "../types.js";
+import { claudeBuilder } from "./agent-builder.js";
+import { claudeResultExtractor } from "./result-extractor.js";
+import { ClaudeCodeProvider } from "./session-log.js";
 export { claudeBuilder } from "./agent-builder.js";
 export { claudeCodeImporter } from "./config-import.js";
+export { claudeResultExtractor } from "./result-extractor.js";
 export { ClaudeCodeProvider } from "./session-log.js";
 function caps(c) {
     return {
@@ -53,6 +34,29 @@ export class ClaudeHarness extends BaseHarness {
     // Home-relative config dir scanned by `akm setup` (#567). Claude Code has a
     // session-log provider, so offering it as a stash source is functional.
     setupDetectionDir = ".claude";
+    agentBuilder = claudeBuilder;
+    resultExtractor = claudeResultExtractor;
+    // ── Workflow-engine descriptor (plan §"Capability matrix", P2) ────────────
+    // Claude Code is the in-harness pattern: the orchestrating session itself
+    // drives units via the `akm workflow` gate spine (`claude -p` headless
+    // dispatch also exists via `agentBuilder`, but the pattern classification
+    // follows the matrix row).
+    pattern = "in-harness";
+    // Structured output tier for the AGENT-DISPATCH (`claude -p`) path akm's
+    // local runner uses (Codex round-3 finding A). The headless CLI has NO
+    // output-schema flag — its documented structured path is `--output-format
+    // json`, a RESULT ENVELOPE akm parses (`./result-extractor.ts`) and then
+    // validates against the node schema ⇒ the "native-json" tier. (Claude Code's
+    // in-harness `Workflow`/`agent()` tool-input-schema path IS native-schema,
+    // but that is a different surface than the dispatch builder — the descriptor
+    // is aligned to what the builder honestly does.)
+    structuredOutput = "native-json";
+    // `claude --resume <sessionId>` replays a previous session in headless mode.
+    resume = { flag: "--resume", takesSessionId: true };
+    // Session-id env marker: presence of a concrete session id (not the bare
+    // "running under Claude Code" flag) attributes a run to this harness.
+    identityEnv = ["CLAUDE_SESSION_ID"];
+    sessionLogProvider = () => new ClaudeCodeProvider();
     capabilities = caps({
         sessionLogs: true,
         agentDispatch: true,

package/dist/integrations/harnesses/claude/result-extractor.js

@@ -0,0 +1,52 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function asNonEmptyString(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+/** JSON.parse that returns undefined instead of throwing. */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * Is this parsed object Claude Code's `--output-format json` RESULT ENVELOPE
+ * (rather than a bare JSON answer a schema unit produced without the flag)? A
+ * genuine envelope declares `type: "result"`, or carries the two envelope-only
+ * fields together (a string `result` AND a `session_id`). A bare structured
+ * answer — `{"result":"ok"}` — carries neither marker, so it is passed through
+ * raw and the engine's schema validator sees the whole object.
+ */
+function isResultEnvelope(value) {
+    if (value.type === "result")
+        return true;
+    return typeof value.result === "string" && asNonEmptyString(value.session_id) !== undefined;
+}
+/**
+ * Normalize a raw claude run result into `{ text, sessionId? }`. See the module
+ * doc for the two stdout shapes (JSON result envelope vs plain text).
+ */
+export const claudeResultExtractor = (result) => {
+    const fallbackSessionId = result.sessionId;
+    const raw = result.stdout;
+    const trimmed = raw.trim();
+    // Only attempt an envelope parse when stdout looks like a single JSON object
+    // (`--output-format json`). A plain-text run is passed through UNCHANGED
+    // (untrimmed) so schemaless dispatch stays byte-identical to today.
+    if (trimmed.startsWith("{")) {
+        const whole = result.parsed !== undefined ? result.parsed : tryParseJson(trimmed);
+        if (isRecord(whole) && isResultEnvelope(whole)) {
+            const text = typeof whole.result === "string" ? whole.result : trimmed;
+            const sessionId = asNonEmptyString(whole.session_id) ?? fallbackSessionId;
+            return { text, ...(sessionId ? { sessionId } : {}) };
+        }
+    }
+    return { text: raw, ...(fallbackSessionId ? { sessionId: fallbackSessionId } : {}) };
+};

package/dist/integrations/harnesses/claude/session-log.js

@@ -107,6 +107,16 @@ export class ClaudeCodeProvider {
     isAvailable() {
         return fs.existsSync(claudeProjectsDir());
     }
+    /**
+     * Directory holding Claude Code's per-project session JSONL files
+     * (`~/.claude/projects`, honoring `AKM_CLAUDE_PROJECTS_DIR`). Returns `[]`
+     * when the directory does not exist on this machine. See {@link
+     * SessionLogHarness.watchRoots}.
+     */
+    watchRoots() {
+        const dir = claudeProjectsDir();
+        return fs.existsSync(dir) ? [dir] : [];
+    }
     *readEvents(input) {
         try {
             for (const jsonlPath of this.#walkJsonl(claudeProjectsDir())) {

package/dist/integrations/harnesses/codex/agent-builder.js

@@ -0,0 +1,137 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * OpenAI Codex CLI agent command builder (P2, plan §"The adapter contract" /
+ * §"Capability matrix").
+ *
+ * Translates a platform-agnostic {@link AgentDispatchRequest} into the exact
+ * headless argv the `codex` CLI expects:
+ *
+ *   codex exec --sandbox workspace-write [--model <m>] --json [--output-schema <file>] -- "<prompt>"
+ *
+ * Capability-matrix facts this builder encodes (July 2026 research):
+ *   - Headless invocation is the `exec` subcommand (`codex exec "<p>"`), not a
+ *     flag. The built-in codex profiles carry `args: []`, so the builder
+ *     prepends `exec` itself; a user profile that already pins `exec` as its
+ *     first arg is not doubled.
+ *   - `--json` switches stdout to a JSONL event stream — the input contract of
+ *     `./result-extractor.ts`. Always emitted, mirroring how the Claude builder
+ *     always emits `--print`: dispatch is the captured, non-interactive path.
+ *   - Codex is the NATIVE-SCHEMA tier (plan §"Structured-output
+ *     normalization"): `req.schema` is written to a temp file and passed via
+ *     `--output-schema <file>`. The file is tiny, uniquely named under the OS
+ *     temp dir, and intentionally NOT cleaned up here — `BuiltCommand` has no
+ *     post-run hook, and the spawned process reads the file after `build()`
+ *     returns. OS temp reaping owns the lifecycle. The engine still validates
+ *     the output defensively (the constrained output is trusted but verified).
+ *   - `codex exec` has no system-prompt flag; `req.systemPrompt` is folded
+ *     into the prompt payload (system text first, blank line, then the task),
+ *     after the `--` end-of-options separator so it can never be parsed as a
+ *     flag.
+ *   - Tool policy is omitted, but the builder DOES inject `--sandbox
+ *     workspace-write` so dispatched units can write to their working
+ *     directory.  `codex exec` defaults to a read-only sandbox that silently
+ *     blocks file writes; without this flag the unit returns "workspace is
+ *     read-only" and the engine marks the step complete with no real mutation.
+ *     `--ask-for-approval` is NOT injected — that flag only exists on the
+ *     interactive `codex` command, not on `codex exec`, and exec mode is
+ *     already non-approval-blocking.  Profile-supplied `--sandbox` flags
+ *     (long or short form) are preserved (not duplicated).
+ *   - Resume is the `codex exec resume <id>` SUBCOMMAND, not a flag, so it is
+ *     not expressible through `AgentDispatchRequest` (which has no session
+ *     field yet); {@link codexResumeArgs} exposes the argv prefix for the
+ *     integration task that wires session-id reuse from `workflow_run_units`.
+ *   - `req.effort` stays unconsumed (reserved; codex would take it as
+ *     `-c model_reasoning_effort=<v>` — left to the integration task so the
+ *     shared request contract's "no builder consumes it yet" note stays true).
+ *
+ * NOT registered anywhere yet: `HARNESS_REGISTRY` / `BUILTIN_BUILDERS` wiring
+ * is a follow-up integration task. Exported cleanly for that task to import.
+ */
+import { mkdtempSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { assertNotFlag } from "../../agent/builder-shared.js";
+import { resolveModel } from "../../agent/model-aliases.js";
+/**
+ * Write a node's JSON Schema to a fresh temp file for `--output-schema`.
+ *
+ * A unique `mkdtemp` directory per build avoids collisions between concurrent
+ * fan-out units dispatching in the same process. Returns the absolute file
+ * path (the value handed to the flag).
+ */
+export function writeCodexOutputSchemaFile(schema) {
+    const dir = mkdtempSync(join(tmpdir(), "akm-codex-schema-"));
+    const file = join(dir, "output-schema.json");
+    writeFileSync(file, `${JSON.stringify(schema, null, 2)}\n`, "utf8");
+    return file;
+}
+/**
+ * Argv prefix that resumes a previous codex session: `exec resume <id>`.
+ * Codex resume is a subcommand chain, not a flag — kept here so the flag-shaped
+ * `HarnessResumeSupport` seam is not force-fitted. The harness-native session
+ * id comes from the unit row (stored opportunistically by the result
+ * extractor); akm never depends on it (plan §"Session, MCP, and identity").
+ */
+export function codexResumeArgs(sessionId) {
+    assertNotFlag(sessionId, "sessionId");
+    return ["exec", "resume", sessionId];
+}
+/**
+ * Return `base` plus the `--sandbox workspace-write` flag that makes `codex exec`
+ * able to write to its working directory.  `codex exec` defaults to a read-only
+ * sandbox that silently blocks file writes — without this flag the unit returns
+ * "workspace is read-only" and the engine marks the step complete with no real
+ * mutation.  If the profile already pins `--sandbox` (long or short form) the
+ * default is not duplicated.
+ *
+ * Note: `--ask-for-approval` is an *interactive* codex flag only — `codex exec`
+ * does not accept it (it errors with "unexpected argument").  Non-interactive
+ * exec mode is implicitly non-approval-blocking; `--sandbox workspace-write`
+ * alone is sufficient for dispatched units.
+ */
+function ensureSandboxFlags(base) {
+    const out = [...base];
+    if (!out.includes("--sandbox") && !out.includes("-s")) {
+        out.push("--sandbox", "workspace-write");
+    }
+    return out;
+}
+/**
+ * OpenAI Codex builder.
+ * Command shape: codex exec --sandbox workspace-write [--model <m>] --json [--output-schema <file>] -- "<prompt>"
+ */
+export const codexBuilder = {
+    platform: "codex",
+    build(profile, req) {
+        assertNotFlag(req.systemPrompt, "systemPrompt");
+        assertNotFlag(req.model, "model");
+        // Built-in codex profiles ship `args: []`; headless dispatch is the `exec`
+        // subcommand. Don't double it when a user profile already pins it.
+        const extra = profile.args[0] === "exec" ? profile.args.slice(1) : [...profile.args];
+        // `codex exec` defaults to a read-only sandbox that silently blocks file
+        // writes — dispatched units would return "workspace is read-only" and the
+        // engine would mark them complete with no real mutation.  Force
+        // `workspace-write` (writes scoped to cwd) unless the profile already pins
+        // its own --sandbox flag (`--ask-for-approval` is not injectable here —
+        // see ensureSandboxFlags).
+        const sandboxArgs = ensureSandboxFlags(extra);
+        const args = ["exec", ...sandboxArgs];
+        if (req.model) {
+            const resolved = resolveModel(req.model, "codex", profile.modelAliases, profile.globalModelAliases);
+            args.push("--model", resolved);
+        }
+        // JSONL event stream on stdout — the codex result extractor's input.
+        args.push("--json");
+        if (req.schema) {
+            // Native-schema tier: pass the node schema straight through.
+            args.push("--output-schema", writeCodexOutputSchemaFile(req.schema));
+        }
+        // No system-prompt flag exists on `codex exec` — fold it into the prompt.
+        const prompt = req.systemPrompt ? `${req.systemPrompt}\n\n${req.prompt}` : req.prompt;
+        args.push("--");
+        args.push(prompt);
+        return { argv: [profile.bin, ...args] };
+    },
+};