@opsee/cli 0.11.9

package/src/foreman/codex-worker-adapter.ts

@@ -0,0 +1,472 @@
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { Account } from "./account.js";
+import { COMPLETION_REPORT_CONTRACT, COMPLETION_REPORT_JSON_SCHEMA, completedEvent } from "./completion-report.js";
+import { VENDOR_CONFIG_DIR_ENV } from "./vendor.js";
+import type { InteractiveCommand, InteractiveSessionRequest, McpServerSpec, OutputContract, TurnFailureReason, TurnHandle, TurnRequest, TurnSandbox, WorkerAdapter } from "./worker-adapter.js";
+import {
+  buildWorkerEnv,
+  errorMessage,
+  failedHandle,
+  launchFailureReason,
+  ProcessTurn,
+  rateLimitedEvent,
+  spawnProcess,
+  type ProcessSpawner,
+  type ProcessTurnSpec,
+} from "./worker-process.js";
+
+/**
+ * The Worker Adapter for Codex (ADR-0001): the vendor's own `codex` binary in non-interactive
+ * `exec` mode with JSONL output, under one Account and pinned to one directory. It answers to the
+ * same interface and the same contract suite as the Claude Code adapter, so every later Foreman
+ * feature runs on either vendor.
+ *
+ * Flags, checked against `codex exec --help` and `codex exec resume --help` of codex-cli 0.147.0
+ * and against two recorded runs of it (the happy-turn and resumed-turn fixtures), plus the docs
+ * at https://learn.chatgpt.com/docs/non-interactive-mode (where developers.openai.com/codex
+ * redirects) and the event vocabulary in codex-rs/exec/src/exec_events.rs:
+ *
+ * - `exec [PROMPT]` runs one turn without a terminal; `--json` prints one event per line:
+ *   `thread.started` (with `thread_id`, the only place the session id appears), `turn.started`,
+ *   `item.started|updated|completed` (items typed `agent_message`, `reasoning`,
+ *   `command_execution`, `file_change`, `mcp_tool_call`, `web_search`, `todo_list`, `error`),
+ *   then `turn.completed` (token `usage`, no cost) or `turn.failed` (`error.message`). A
+ *   top-level `error` event is non-fatal on its own; the run ends only with a `turn.*` line.
+ * - `--output-schema <FILE>` takes a *path* to a JSON Schema for the final response. Codex hands
+ *   it to the model as a strict structured output, and the OpenAI endpoint rejects the shared
+ *   report schema verbatim ("'required' is required to be supplied and to be an array including
+ *   every key in properties", observed live), so `CODEX_OUTPUT_SCHEMA` below is the strict
+ *   projection of `COMPLETION_REPORT_JSON_SCHEMA`: every property required and the optional ones
+ *   nullable. The report then arrives as the text of the last `agent_message` item and the nulls
+ *   are folded away before the shared validator sees it. Each turn writes the schema to its own
+ *   temporary file and removes it when the turn ends.
+ * - `-s workspace-write` lets an unattended Worker edit its Workspace without an approval nobody
+ *   is there to give (exec defaults to a read-only sandbox). `exec resume` has no `-s`, so both
+ *   forms set it through `-c sandbox_mode="workspace-write"`, which is the same setting. A
+ *   `readonly-browser` turn (`TurnRequest.sandbox`, the Verifier's) gets
+ *   `-c sandbox_mode="read-only"` and `-c approval_policy="never"` instead (the config keys
+ *   behind `-s read-only` and `-a never`; `exec` has no `-a` of its own and `exec resume` has
+ *   neither flag), so a command the model proposes runs read-only and a request for more is
+ *   refused rather than waited on.
+ * - `--skip-git-repo-check`: a Workspace is a git worktree, but the debug command's cwd need not
+ *   be, and the check would otherwise refuse to start.
+ * - `-c mcp_servers.<name>.command=...` and `-c mcp_servers.<name>.args=[...]` add an MCP server
+ *   for the turn the way `~/.codex/config.toml` would (`[mcp_servers.<name>]`, the same keys;
+ *   https://developers.openai.com/codex/mcp): the Verifier's Playwright MCP, core/verifier.ts.
+ *   The value of `-c` is parsed as TOML, so strings are quoted and the arguments are an array.
+ * - `exec resume <SESSION_ID> [PROMPT]` continues a stored session; its `thread.started` line
+ *   carries the resumed id. There is no `-C` on resume; the cwd is the spawn's, as it is for
+ *   `exec`. Codex has no per-turn cap, so `TurnRequest.maxTurns` is not applied and this adapter
+ *   never fails with `max_turns`.
+ * - Stdin is closed at spawn (`stdio: "ignore"`); Codex notes "Reading additional input from
+ *   stdin..." on stderr, reads the empty stream and goes on.
+ *
+ * Rate limits do not have an event of their own in the exec stream (exec_events.rs defines none;
+ * the JSONL processor caches token usage and drops the rest), so they are recognised from the
+ * message of `turn.failed` or a preceding `error` line, with the strings in
+ * codex-rs/protocol/src/error.rs: "You've hit your usage limit. ... Try again at <local time>."
+ * on a ChatGPT plan, "rate limit exceeded: ..." / "exceeded retry limit, last status: 429" on an
+ * API key, "Quota exceeded. ...".
+ *
+ * The credential boundary (ADR-0013) is kept the way the Claude adapter keeps it: a subscription
+ * Account is named to the process only through `CODEX_HOME`, an API-key Account only through the
+ * value of the variable it names, copied into `CODEX_API_KEY`, which `codex exec` takes ahead of
+ * any stored login ("API key via env var takes precedence over any other auth method",
+ * codex-rs/login/src/auth/manager.rs, `load_auth`; `OPENAI_API_KEY` is read only by the
+ * interactive onboarding). Nothing here opens a path inside the config directory, and
+ * account-boundary.test.ts runs this adapter under the same fs audit as registration.
+ */
+
+export const CODEX_BINARY = "codex";
+export const CODEX_SANDBOX_MODE = "workspace-write";
+/** The sandbox and approval policy of a `readonly-browser` turn. */
+export const CODEX_READONLY_SANDBOX_MODE = "read-only";
+export const CODEX_READONLY_APPROVAL_POLICY = "never";
+/** The variable `codex exec` reads an API key from, ahead of `auth.json` in `CODEX_HOME`. */
+export const CODEX_API_KEY_ENV = "CODEX_API_KEY";
+/** File name of the per-turn schema file handed to `--output-schema`. */
+export const CODEX_SCHEMA_FILE = "completion-report.schema.json";
+
+/**
+ * `COMPLETION_REPORT_JSON_SCHEMA` as the OpenAI structured-output endpoint accepts it: every key
+ * required, so `handOff` becomes nullable and its two fields nullable-and-required. The two
+ * schemas describe the same reports; `normalizeCodexReport` maps one shape onto the other, and
+ * the test pins that the projection is derived from the shared schema rather than a copy.
+ */
+export const CODEX_OUTPUT_SCHEMA = codexOutputSchema(COMPLETION_REPORT_CONTRACT);
+
+type JsonSchema = { type?: string | string[]; properties?: Record<string, unknown>; required?: readonly string[]; anyOf?: unknown[]; [key: string]: unknown };
+
+/** The strict projection of a contract's schema: what `--output-schema` gets for that turn. */
+export function codexOutputSchema(contract: Pick<OutputContract, "jsonSchema">): Record<string, unknown> {
+  return strictProjection(contract.jsonSchema as JsonSchema);
+}
+
+function strictProjection(schema: JsonSchema): Record<string, unknown> {
+  const project = (node: JsonSchema, nullable: boolean): Record<string, unknown> => {
+    if (node.type !== "object" || !node.properties) {
+      if (!nullable) return { ...node };
+      const type = Array.isArray(node.type) ? node.type : node.type ? [node.type] : [];
+      return { ...node, type: type.includes("null") ? type : [...type, "null"] };
+    }
+    const required = new Set(node.required ?? []);
+    const properties: Record<string, unknown> = {};
+    for (const [name, child] of Object.entries(node.properties)) {
+      properties[name] = project(child as JsonSchema, !required.has(name));
+    }
+    const object = { ...node, properties, required: Object.keys(node.properties) };
+    return nullable ? { anyOf: [object, { type: "null" }] } : object;
+  };
+  return project(schema, false);
+}
+
+/** Folds the strict projection's nulls back into the contract's own shape: a null where the
+ * contract's schema has an optional key is an absent key, at every level of nested objects.
+ * Anything else is left for the validator to judge. */
+export function foldNulls(schema: Pick<OutputContract, "jsonSchema">, candidate: unknown): unknown {
+  const fold = (node: JsonSchema | undefined, value: unknown): unknown => {
+    if (!node || node.type !== "object" || !node.properties || typeof value !== "object" || value === null || Array.isArray(value)) return value;
+    const required = new Set(node.required ?? []);
+    const record: Record<string, unknown> = {};
+    for (const [key, v] of Object.entries(value as Record<string, unknown>)) {
+      if (v === null && key in node.properties && !required.has(key)) continue;
+      record[key] = fold(node.properties[key] as JsonSchema | undefined, v);
+    }
+    return record;
+  };
+  return fold(schema.jsonSchema as JsonSchema, candidate);
+}
+
+/** `foldNulls` for the Completion Report: a null `handOff` is an absent one, and null
+ * `branch`/`prUrl` inside it are absent too. */
+export function normalizeCodexReport(candidate: unknown): unknown {
+  return foldNulls({ jsonSchema: COMPLETION_REPORT_JSON_SCHEMA as unknown as Record<string, unknown> }, candidate);
+}
+
+export interface CodexWorkerAdapterOptions {
+  spawn?: ProcessSpawner;
+  /** Base environment the Worker inherits before the Account's variables are applied. */
+  baseEnv?: Readonly<Record<string, string | undefined>>;
+  /** Sees every raw stdout line before it is parsed; the debug command uses it to re-record fixtures. */
+  onLine?: (line: string) => void;
+}
+
+/** The Worker's environment for one Account (see `buildWorkerEnv`). */
+export function buildCodexEnv(
+  account: Account,
+  baseEnv: Readonly<Record<string, string | undefined>>,
+  overrides: Readonly<Record<string, string>> = {},
+  sandbox: TurnSandbox = "worker",
+): Record<string, string> {
+  return buildWorkerEnv(account, { configDir: VENDOR_CONFIG_DIR_ENV.codex, apiKey: CODEX_API_KEY_ENV }, baseEnv, overrides, sandbox);
+}
+
+/** The attended turn (story 53): `codex resume <session-id>`, the interactive TUI's own resume of a
+ * stored session (`codex resume --help` of codex-cli 0.147.0: "Resume a previous interactive
+ * session"), which is the same session `exec resume` continues unattended. No flags: `resume` has
+ * no `--skip-git-repo-check` (that one is `exec`'s, and `resume` rejects it), and the cwd is the
+ * spawn's, the Workspace, which is a git worktree anyway. */
+export function buildCodexInteractiveArgs(sessionId: string): string[] {
+  return ["resume", sessionId];
+}
+
+/** A TOML value for `-c`: JSON's string and array-of-string forms are valid TOML for the plain
+ * ASCII a command line carries; an inline table for the environment. */
+function toml(value: string | string[] | Readonly<Record<string, string>>): string {
+  if (typeof value === "string") return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map((v) => JSON.stringify(v)).join(", ")}]`;
+  return `{ ${Object.entries(value).map(([k, v]) => `${JSON.stringify(k)} = ${JSON.stringify(v)}`).join(", ")} }`;
+}
+
+/** The `-c` overrides that add the request's MCP servers for this turn. */
+export function codexMcpOverrides(servers: Readonly<Record<string, McpServerSpec>>): string[] {
+  const args: string[] = [];
+  for (const [name, s] of Object.entries(servers)) {
+    args.push("-c", `mcp_servers.${name}.command=${toml(s.command)}`, "-c", `mcp_servers.${name}.args=${toml(s.args)}`);
+    if (s.env) args.push("-c", `mcp_servers.${name}.env=${toml(s.env)}`);
+  }
+  return args;
+}
+
+/** The attended planning session (story 10): `codex <prompt>`, the interactive TUI with the prompt
+ * as its first message (`codex [OPTIONS] [PROMPT]` in `codex --help` of codex-cli 0.147.0). No
+ * `exec`, no sandbox flag, no schema: the human is there to answer, and `--skip-git-repo-check`
+ * is `exec`'s alone. */
+export function buildCodexInteractiveSessionArgs(prompt: string): string[] {
+  return [prompt];
+}
+
+/** The `codex` command line for one turn; `schemaPath` is where this turn's schema file is. */
+export function buildCodexArgs(request: TurnRequest, schemaPath: string, resumeSessionId?: string): string[] {
+  const args = ["exec"];
+  if (resumeSessionId !== undefined) args.push("resume", resumeSessionId);
+  if (request.sandbox === "readonly-browser") {
+    args.push("--json", "--skip-git-repo-check", "-c", `sandbox_mode=${JSON.stringify(CODEX_READONLY_SANDBOX_MODE)}`, "-c", `approval_policy=${JSON.stringify(CODEX_READONLY_APPROVAL_POLICY)}`);
+  } else {
+    args.push("--json", "--skip-git-repo-check", "-c", `sandbox_mode=${JSON.stringify(CODEX_SANDBOX_MODE)}`);
+  }
+  args.push(...codexMcpOverrides(request.mcpServers ?? {}));
+  args.push("--output-schema", schemaPath, request.prompt);
+  return args;
+}
+
+/** How a rate limit reads in a `turn.failed` or `error` message (codex-rs/protocol/src/error.rs).
+ * Matched only against those, never against a Worker's own report. */
+export const CODEX_RATE_LIMIT_PATTERNS: readonly RegExp[] = [
+  /hit your usage limit/i,
+  /exceeded retry limit, last status: 429/i,
+  /quota exceeded/i,
+  /too many requests/i,
+  /rate limit/i,
+];
+
+/**
+ * How a dead credential reads in a `turn.failed` or `error` message (OPS-288).
+ *
+ * Codex has no auth variant in `CodexErr` the way it has rate-limit ones, so its authentication
+ * failures arrive as the transport's own status text — `unexpected status 401 Unauthorized`, and
+ * the `exceeded retry limit, last status: 401` form that is the exact sibling of the 429 already
+ * matched above (openai/codex issues 5456, 13838, 19743). The two remaining patterns are the
+ * messages the token-refresh path produces when the stored login is gone.
+ *
+ * Matched only against `turn.failed` and `error` text, and only after `CODEX_RATE_LIMIT_PATTERNS`:
+ * `last status: 429` and `last status: 401` differ by three characters, and getting that ordering
+ * wrong would quarantine an Account the vendor had merely throttled.
+ */
+export const CODEX_CREDENTIAL_PATTERNS: readonly RegExp[] = [
+  /401 unauthorized/i,
+  /status: 401/i,
+  /refresh token was revoked/i,
+  /no auth credentials found/i,
+];
+
+/**
+ * Codex prints the reset as local wall-clock text: " Try again at 3:10 AM." on the same day,
+ * " Try again at Sep 8th, 2026 3:10 AM." otherwise (`format_retry_timestamp`). The dated form is
+ * parsed in this machine's zone, which is the zone Codex formatted it in; the time-only form
+ * names no date and is left to the scheduler's default, as the Claude adapter leaves "resets 5am".
+ */
+export function resetAtFromCodexLimitText(text: string): string | undefined {
+  const match = /try again at ([^.]*?\d{4} \d{1,2}:\d{2} [AP]M)\./i.exec(text);
+  if (!match) return undefined;
+  const parsed = new Date(match[1].replace(/(\d)(st|nd|rd|th),/, "$1,"));
+  return Number.isNaN(parsed.getTime()) ? undefined : parsed.toISOString();
+}
+
+interface CodexItem {
+  id?: string;
+  type?: string;
+  text?: string;
+  message?: string;
+  server?: string;
+  tool?: string;
+  status?: string;
+}
+
+interface CodexEvent {
+  type?: string;
+  thread_id?: string;
+  item?: CodexItem;
+  error?: { message?: string };
+  message?: string;
+  usage?: unknown;
+}
+
+/** Item types that are the Worker doing something, reported as `tool` when they start. */
+const TOOL_ITEMS = new Set(["command_execution", "file_change", "mcp_tool_call", "web_search"]);
+
+/** Translates one `codex exec --json` stream into the adapter's event stream; one per turn. */
+class CodexTurn extends ProcessTurn {
+  private lastAgentMessage: string | undefined;
+  private rateLimit: { message: string; resetAt?: string } | undefined;
+  private lastError: string | undefined;
+
+  constructor(
+    spec: ProcessTurnSpec,
+    private readonly schemaDir: string,
+    private readonly contract: OutputContract,
+  ) {
+    super(spec);
+    this.begin();
+  }
+
+  protected cleanup(): void {
+    rmSync(this.schemaDir, { recursive: true, force: true });
+  }
+
+  protected handleMessage(parsed: unknown): void {
+    const event = parsed as CodexEvent;
+    switch (event.type) {
+      case "thread.started":
+        if (typeof event.thread_id === "string" && event.thread_id !== "") {
+          this.sessionId = event.thread_id;
+          this.emit({ type: "started", sessionId: event.thread_id });
+        }
+        return;
+      case "item.started":
+        this.handleItemStarted(event.item);
+        return;
+      case "item.completed":
+        this.handleItemCompleted(event.item);
+        return;
+      case "error":
+        this.handleError(typeof event.message === "string" ? event.message : "");
+        return;
+      case "turn.completed":
+        this.handleCompleted();
+        return;
+      case "turn.failed":
+        this.handleFailed(typeof event.error?.message === "string" ? event.error.message : "");
+        return;
+      default:
+        return;
+    }
+  }
+
+  private handleItemStarted(item: CodexItem | undefined): void {
+    if (!item?.type || !TOOL_ITEMS.has(item.type)) return;
+    const name = item.type === "mcp_tool_call" && item.server && item.tool ? `mcp:${item.server}/${item.tool}` : item.type;
+    this.emit({ type: "tool", name });
+  }
+
+  private handleItemCompleted(item: CodexItem | undefined): void {
+    if (!item) return;
+    if (item.type === "agent_message" && typeof item.text === "string" && item.text !== "") {
+      // Under --output-schema every message is schema-shaped, so the report is the last non-empty
+      // one; the earlier ones are progress and shown as such, never parsed.
+      this.lastAgentMessage = item.text;
+      this.emit({ type: "output", text: item.text });
+    } else if (item.type === "error" && typeof item.message === "string" && item.message !== "") {
+      // Warnings (config, deprecation, model rerouted) arrive as error items; progress, not failure.
+      this.emit({ type: "output", text: item.message });
+    }
+  }
+
+  /** A top-level error does not end the run by itself (the processor keeps going and `turn.*`
+   * decides); it is remembered for the failure that may follow and reported at once when it is a
+   * rate limit, so the scheduler can pause the Account even if the turn goes on to complete. */
+  private handleError(message: string): void {
+    if (message === "") return;
+    this.lastError = message;
+    if (!this.rateLimit && CODEX_RATE_LIMIT_PATTERNS.some((p) => p.test(message))) {
+      const resetAt = resetAtFromCodexLimitText(message);
+      this.rateLimit = { message, resetAt };
+      this.emit(rateLimitedEvent(message, resetAt));
+    } else {
+      this.emit({ type: "output", text: message });
+    }
+  }
+
+  private handleCompleted(): void {
+    const sessionId = this.sessionId;
+    const failure = (reason: TurnFailureReason, message: string, details?: string[]) =>
+      this.end({ type: "failed", reason, message, sessionId, details });
+    if (this.lastAgentMessage === undefined) {
+      failure("invalid_report", "The Worker finished without a final message", ["no final message"]);
+      return;
+    }
+    let candidate: unknown = this.lastAgentMessage;
+    try {
+      candidate = foldNulls(this.contract, JSON.parse(this.lastAgentMessage));
+    } catch {
+      // Not JSON: the validator says so in its own words.
+    }
+    const parsed = this.contract.parse(candidate);
+    if (!parsed.ok) {
+      failure("invalid_report", `The Worker's final message is not a ${this.contract.name}`, parsed.errors);
+    } else if (sessionId === undefined) {
+      failure("vendor_error", "The Worker reported without ever naming its session");
+    } else {
+      this.end({ type: "completed", sessionId, ...completedEvent(this.contract, parsed.value, sessionId) });
+    }
+  }
+
+  private handleFailed(message: string): void {
+    const sessionId = this.sessionId;
+    const text = message || this.lastError || "turn failed";
+    if (this.rateLimit) {
+      this.end({ type: "failed", reason: "rate_limited", message: this.rateLimit.message, sessionId, details: text !== this.rateLimit.message ? [text] : undefined });
+      return;
+    }
+    if (CODEX_RATE_LIMIT_PATTERNS.some((p) => p.test(text))) {
+      this.emit(rateLimitedEvent(text, resetAtFromCodexLimitText(text)));
+      this.end({ type: "failed", reason: "rate_limited", message: text, sessionId });
+      return;
+    }
+    // After the rate limit, so `last status: 429` is never read as `last status: 401` (OPS-288).
+    if (CODEX_CREDENTIAL_PATTERNS.some((p) => p.test(text))) {
+      this.end({ type: "failed", reason: "credential_failed", message: text, sessionId });
+      return;
+    }
+    this.end({ type: "failed", reason: "vendor_error", message: text, sessionId });
+  }
+}
+
+export class CodexWorkerAdapter implements WorkerAdapter {
+  private readonly spawn: ProcessSpawner;
+  private readonly baseEnv: Readonly<Record<string, string | undefined>>;
+  private readonly onLine: ((line: string) => void) | undefined;
+
+  constructor(options: CodexWorkerAdapterOptions = {}) {
+    this.spawn = options.spawn ?? spawnProcess;
+    this.baseEnv = options.baseEnv ?? process.env;
+    this.onLine = options.onLine;
+  }
+
+  launch(request: TurnRequest): TurnHandle {
+    return this.start(request, undefined);
+  }
+
+  resume(sessionId: string, request: TurnRequest): TurnHandle {
+    return this.start(request, sessionId);
+  }
+  interactiveCommand(sessionId: string, request: Pick<TurnRequest, "account" | "cwd">): InteractiveCommand {
+    return { command: CODEX_BINARY, args: buildCodexInteractiveArgs(sessionId), cwd: request.cwd, env: buildCodexEnv(request.account, this.baseEnv) };
+  }
+
+  interactiveSession(request: InteractiveSessionRequest): InteractiveCommand {
+    return { command: CODEX_BINARY, args: buildCodexInteractiveSessionArgs(request.prompt), cwd: request.cwd, env: buildCodexEnv(request.account, this.baseEnv) };
+  }
+
+
+  private start(request: TurnRequest, resumeSessionId: string | undefined): TurnHandle {
+    let env: Record<string, string>;
+    try {
+      env = buildCodexEnv(request.account, this.baseEnv, request.env, request.sandbox);
+    } catch (error) {
+      return failedHandle(errorMessage(error), launchFailureReason(error));
+    }
+    // The schema goes to a temp file of its own, never into the Workspace, whose contents belong
+    // to the Worker; the turn removes the directory when it ends.
+    let schemaDir: string;
+    try {
+      schemaDir = mkdtempSync(join(tmpdir(), "opsee-foreman-codex-"));
+    } catch (error) {
+      return failedHandle(`Could not create the schema directory: ${errorMessage(error)}`);
+    }
+    const contract = request.contract ?? COMPLETION_REPORT_CONTRACT;
+    const schemaPath = join(schemaDir, CODEX_SCHEMA_FILE);
+    try {
+      writeFileSync(schemaPath, JSON.stringify(contract === COMPLETION_REPORT_CONTRACT ? CODEX_OUTPUT_SCHEMA : codexOutputSchema(contract)), { mode: 0o600 });
+    } catch (error) {
+      rmSync(schemaDir, { recursive: true, force: true });
+      return failedHandle(`Could not write the schema file: ${errorMessage(error)}`);
+    }
+    return new CodexTurn(
+      {
+        spawn: this.spawn,
+        command: CODEX_BINARY,
+        args: buildCodexArgs(request, schemaPath, resumeSessionId),
+        options: { cwd: request.cwd, env },
+        stallTimeoutMs: request.stallTimeoutMs,
+        sessionId: resumeSessionId,
+        onLine: this.onLine,
+      },
+      schemaDir,
+      contract,
+    );
+  }
+}
+

package/src/foreman/completion-report.ts

@@ -0,0 +1,153 @@
+/**
+ * The Completion Report (see ../../CONTEXT.md): the structured record a Worker produces at the end
+ * of a turn. It is what the Worker Adapter demands as the final message of every unattended turn,
+ * so a turn that ends without one is a typed failure, never a free-text guess (story 43).
+ */
+import type { OutputContract } from "./worker-adapter.js";
+
+export const OUTCOMES = ["done", "blocked", "failed"] as const;
+export type Outcome = (typeof OUTCOMES)[number];
+
+export interface HandOff {
+  branch?: string;
+  prUrl?: string;
+}
+
+export interface CompletionReport {
+  outcome: Outcome;
+  /** One paragraph for the human who reads the Tracker comment. */
+  summary: string;
+  /** Choices made that a later Worker or reviewer would otherwise re-litigate. */
+  decisions: string[];
+  /** What was attempted, including what did not work; the memory that stops a sibling retrying it. */
+  tried: string[];
+  /** Why the outcome is not `done`, when it is not. */
+  blockers: string[];
+  /** Proposed Learnings: reusable observations about the repo, not yet trusted. */
+  proposedLearnings: string[];
+  /** The Hand-off, when the Worker opened one. */
+  handOff?: HandOff;
+}
+
+/**
+ * The same shape as a JSON Schema for the vendor's structured-output flag. Declared once here and
+ * checked against `CompletionReport` by the test, so the two cannot drift.
+ */
+export const COMPLETION_REPORT_JSON_SCHEMA = {
+  type: "object",
+  additionalProperties: false,
+  required: ["outcome", "summary", "decisions", "tried", "blockers", "proposedLearnings"],
+  properties: {
+    outcome: { type: "string", enum: [...OUTCOMES] },
+    summary: { type: "string" },
+    decisions: { type: "array", items: { type: "string" } },
+    tried: { type: "array", items: { type: "string" } },
+    blockers: { type: "array", items: { type: "string" } },
+    proposedLearnings: { type: "array", items: { type: "string" } },
+    handOff: {
+      type: "object",
+      additionalProperties: false,
+      properties: {
+        branch: { type: "string" },
+        prUrl: { type: "string" },
+      },
+    },
+  },
+} as const;
+
+export type ParsedReport = { ok: true; report: CompletionReport } | { ok: false; errors: string[] };
+
+const STRING_LISTS = ["decisions", "tried", "blockers", "proposedLearnings"] as const;
+
+function isStringArray(value: unknown): value is string[] {
+  return Array.isArray(value) && value.every((v) => typeof v === "string");
+}
+
+/**
+ * Validates a candidate report. A string is parsed as JSON first, since a vendor that fails to
+ * apply the schema still tends to hand the object back as text. Every defect is reported, not only
+ * the first, because the list goes into the failure event a human reads.
+ */
+export function parseCompletionReport(candidate: unknown): ParsedReport {
+  let value = candidate;
+  if (typeof value === "string") {
+    try {
+      value = JSON.parse(value);
+    } catch {
+      return { ok: false, errors: ["report is not JSON"] };
+    }
+  }
+  if (typeof value !== "object" || value === null || Array.isArray(value)) {
+    return { ok: false, errors: ["report must be an object"] };
+  }
+  const record = value as Record<string, unknown>;
+  const errors: string[] = [];
+
+  if (!(OUTCOMES as readonly unknown[]).includes(record.outcome)) {
+    errors.push(`outcome must be one of ${OUTCOMES.map((o) => `"${o}"`).join(", ")}`);
+  }
+  if (typeof record.summary !== "string") {
+    errors.push("summary must be a string");
+  }
+  for (const field of STRING_LISTS) {
+    if (!isStringArray(record[field])) errors.push(`${field} must be an array of strings`);
+  }
+
+  let handOff: HandOff | undefined;
+  if (record.handOff !== undefined) {
+    if (typeof record.handOff !== "object" || record.handOff === null || Array.isArray(record.handOff)) {
+      errors.push("handOff must be an object");
+    } else {
+      const raw = record.handOff as Record<string, unknown>;
+      handOff = {};
+      for (const field of ["branch", "prUrl"] as const) {
+        if (raw[field] === undefined) continue;
+        if (typeof raw[field] !== "string") errors.push(`handOff.${field} must be a string`);
+        else handOff[field] = raw[field];
+      }
+    }
+  }
+
+  if (errors.length > 0) return { ok: false, errors };
+  const report: CompletionReport = {
+    outcome: record.outcome as Outcome,
+    summary: record.summary as string,
+    decisions: record.decisions as string[],
+    tried: record.tried as string[],
+    blockers: record.blockers as string[],
+    proposedLearnings: record.proposedLearnings as string[],
+  };
+  if (handOff) report.handOff = handOff;
+  return { ok: true, report };
+}
+
+/** The Completion Report as an output contract (worker-adapter.ts `OutputContract`): what every
+ * implementing turn runs under when its request names none. */
+export const COMPLETION_REPORT_CONTRACT: OutputContract<CompletionReport> = {
+  name: "Completion Report",
+  jsonSchema: COMPLETION_REPORT_JSON_SCHEMA as unknown as Record<string, unknown>,
+  parse(candidate) {
+    const parsed = parseCompletionReport(candidate);
+    return parsed.ok ? { ok: true, value: parsed.report } : parsed;
+  },
+};
+
+/** The stand-in Completion Report a turn under another contract completes with: the stream's
+ * `completed` event always carries a report, and this one says where the real result is. */
+export function contractReport(contract: Pick<OutputContract, "name">): CompletionReport {
+  return {
+    outcome: "done",
+    summary: `The turn ran under the ${contract.name} contract; its result is the structured output, not this report.`,
+    decisions: [],
+    tried: [],
+    blockers: [],
+    proposedLearnings: [],
+  };
+}
+
+/** The `completed` event for a validated final message: the report itself under the Completion
+ * Report contract, or the stand-in with the object under `structured` under any other. */
+export function completedEvent(contract: OutputContract, value: unknown, sessionId: string): { report: CompletionReport; structured?: unknown } {
+  if (contract === COMPLETION_REPORT_CONTRACT) return { report: value as CompletionReport };
+  return { report: contractReport(contract), structured: value };
+}