@kal-elsam/kairo-runtime 0.16.0 → 0.17.0

package/CHANGELOG.md

@@ -5,6 +5,56 @@ Historical entries below may reference the legacy `@kal-elsam/harness` package n
 
 ## Unreleased
 
+## 0.17.0 — 2026-09-17 (Kairo Runtime)
+
+Minor release. Execution-worktree isolation (real git worktrees, per-role
+commit transactions, preview + `git merge --ff-only` apply, cancellation
+and crash recovery), a per-provider budget/usage state machine, automatic
+Builder→Debugger→Tester orchestration, and several real `/project`
+cockpit UX fixes.
+
+### Added
+
+- Execution-worktree isolation (`execution-worktree-manager.js`): real
+  `git worktree add`-backed isolation per task, a per-role commit
+  transaction (`beginRoleRun`/`completeRoleRun`) that only ever commits
+  a role's own validated diff (Kairo owns every real commit, never the
+  agent), `previewWorktreeMerge`/`applyWorktreeMerge` (confirmation
+  bound to an exact `{baseSha, finalHeadSha, fingerprint}`, applied only
+  via `git merge --ff-only`), and `cancelWorktree`/`reconcileWorktrees`/
+  `discardWorktree` for cancellation and crash recovery.
+- `controlledHeadSha`: every state-changing boundary (not just ACTIVE)
+  verifies the worktree's real HEAD against the last commit Kairo itself
+  produced, closing a rogue-commit bypass reachable while a worktree sat
+  idle in PENDING.
+- Per-provider budget/usage state machine (`usage-manager.js`):
+  cumulative token/cost tracking per provider, a
+  HEALTHY/MODERATE/CONSERVE/CRITICAL/EXHAUSTED classification against a
+  configurable `profile.providerTokenBudgets`, and one real enforcement
+  point — a new run is refused once its provider is EXHAUSTED.
+- `runOrchestratedChain` (`execution-worktree-orchestrator.js`):
+  automatic Builder→Debugger→Tester chaining inside one execution
+  worktree, stopping immediately on any real failure. Injects matching
+  real project skills (`docs/skills`, `.claude/skills`, etc. — the same
+  catalog ASK-mode routing already reads) into each role's task by
+  name/path, never their body content.
+- `/project` cockpit overlay: the PROJECT TEAM panel now shows the real
+  decision reason behind each role's model, a real bordered panel, the
+  cockpit's own live spinner during every in-flight action, and real
+  mouse support (clicks now reach the analyst/role picker lists).
+
+### Fixed
+
+- Dashboard and `/project status` showed `qualityTeam` (comparative
+  reference) under a "PROJECT TEAM" title while the interactive overlay
+  showed the real operational `projectTeam` — both now read the same
+  real operational team.
+- MCP snapshot writes require `--workspace-bound` plus an absolute `--cwd`
+  that matches `process.cwd()` or the unique `WORKSPACE_FOLDER_PATHS` folder.
+  Bound servers expose only `kairo_publish_work_snapshot`; the Cursor
+  extension ships that runtime as `dist/kairo-workspace.cjs` and spawns
+  absolute Node ≥20 — never PATH `kairo`. See [MCP](docs/mcp.md).
+
 ## 0.16.0 — 2026-08-13 (Kairo Runtime)
 
 Minor release. Public `kairo control-plane` command and

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kal-elsam/kairo-runtime",
-  "version": "0.16.0",
+  "version": "0.17.0",
   "description": "Kairo Runtime — local agent operating system for Codex, Cursor, Claude, Pi, Engram, and Graphify.",
   "type": "module",
   "homepage": "https://github.com/Kal-elSam/harness#readme",
@@ -68,6 +68,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.7.0",
+    "@earendil-works/pi-tui": "0.85.1",
     "@modelcontextprotocol/server": "2.0.0",
     "ansi-escapes": "^7.3.0",
     "ink": "^5.2.1",

package/scripts/cockpit-smoke.mjs

@@ -121,7 +121,7 @@ function smokeNavigation(layoutMode) {
     region: COCKPIT_REGIONS.CONTENT,
     unicode: false
   });
-  assert.match(footer.text, /Tab/);
+  assert.equal(footer.text, "1·2 Select - Enter Run - ? Help - Esc Exit");
 
   state = applyKey(state, { type: "escape" });
   assert.equal(state.view, ORCHESTRATOR_VIEWS.HOME);

package/scripts/ux-smoke-test.sh

@@ -76,9 +76,9 @@ echo "Kairo Runtime UX smoke — capturing terminal output to $CAPTURE_DIR"
 echo
 
 run_capture help help
-assert_contains "$CAPTURE_DIR/help.txt" "JSON output (--json on supported commands):"
-assert_contains "$CAPTURE_DIR/help.txt" "report"
-assert_contains "$CAPTURE_DIR/help.txt" "More examples: README.md"
+assert_contains "$CAPTURE_DIR/help.txt" "Usage:"
+assert_contains "$CAPTURE_DIR/help.txt" "kairo help --all"
+assert_contains "$CAPTURE_DIR/help.txt" "Docs: README.md · docs/cli-reference.md"
 assert_not_contains "$CAPTURE_DIR/help.txt" "Stable fields: ok, overall"
 assert_exit help 0
 

package/src/cli.js

@@ -41,6 +41,10 @@ import { runWorkspaceDetect, runWorkspaceDoctor, runWorkspaceInit, runWorkspaceU
 import { runOrchestratorDiagnostics, runOrchestratorShell } from "./global/orchestrator.js";
 import { runIntelligenceCli } from "./global/intelligence-cli.js";
 import { runGlobalRun, runGlobalRuns } from "./global/runtime/run-cli.js";
+import { runArchitectCli, runPlansCli } from "./global/architect/architect-cli.js";
+import { runConversationCli } from "./global/conversation/cli.js";
+import { runUiCli } from "./global/conversation/ui.js";
+import { runCockpitCli } from "./global/cockpit/cli.js";
 import { runGlobalReview, runGlobalReviews } from "./global/runtime/review/review-cli.js";
 import { runGlobalMonitor } from "./global/runtime/monitor/monitor-cli.js";
 import { runGlobalAlerts } from "./global/runtime/alerts/alert-cli.js";
@@ -116,6 +120,21 @@ export async function runCli(argv) {
     case "runs":
       await runGlobalRuns(optionsWithPolicy, packageManifest);
       return;
+    case "architect":
+      await runArchitectCli(optionsWithPolicy);
+      return;
+    case "plans":
+      await runPlansCli(optionsWithPolicy);
+      return;
+    case "conversation":
+      await runConversationCli(optionsWithPolicy);
+      return;
+    case "ui":
+      await runUiCli(optionsWithPolicy);
+      return;
+    case "start":
+      await runCockpitCli(optionsWithPolicy);
+      return;
     case "review":
       await runGlobalReview(optionsWithPolicy, packageManifest);
       return;
@@ -133,17 +152,11 @@ export async function runCli(argv) {
       return;
     case "mcp": {
       const { runMcpCli } = await import("./global/mcp-install.js");
-      await runMcpCli({
-        mcpAction: optionsWithPolicy.mcpAction ?? "serve",
-        mcpClient: optionsWithPolicy.mcpClient ?? "cursor",
-        yes: optionsWithPolicy.yes === true,
-        json: optionsWithPolicy.json === true,
-        cwd: optionsWithPolicy.cwd,
-        cwdExplicit: optionsWithPolicy.cwdExplicit,
+      await runMcpCli(buildMcpCliOptions(optionsWithPolicy, {
         packageRoot,
         packageName: packageManifest.name,
         version: packageManifest.version
-      });
+      }));
       return;
     }
     case "connections": {
@@ -457,6 +470,19 @@ function argsWantsWorkspaceScope(args) {
   return false;
 }
 
+export function buildMcpCliOptions(options = {}, extras = {}) {
+  return {
+    mcpAction: options.mcpAction ?? "serve",
+    mcpClient: options.mcpClient ?? "cursor",
+    yes: options.yes === true,
+    json: options.json === true,
+    cwd: options.cwd,
+    cwdExplicit: options.cwdExplicit,
+    workspaceBound: options.workspaceBound === true,
+    ...extras
+  };
+}
+
 export function parseArgs(argv) {
   const args = [...argv];
   const firstArg = args[0];
@@ -466,6 +492,7 @@ export function parseArgs(argv) {
   const options = {
     cwd: process.cwd(),
     cwdExplicit: false,
+    workspaceBound: false,
     scope: null,
     mode: "standard",
     modeExplicit: false,
@@ -513,6 +540,9 @@ export function parseArgs(argv) {
     intelligencePaths: [],
     runsAction: null,
     runId: null,
+    plansAction: null,
+    conversationAction: null,
+    taskId: null,
     reviewId: null,
     lineage: null,
     reviewsAction: null,
@@ -552,7 +582,8 @@ export function parseArgs(argv) {
     activeOnly: false,
     timeoutMs: null,
     includePrivate: false,
-    cloudConsent: false
+    cloudConsent: false,
+    port: null
   };
 
   if (command === "components") {
@@ -571,6 +602,12 @@ export function parseArgs(argv) {
     parseRunsAction(args, options);
   }
 
+  if (command === "plans") {
+    parsePlansAction(args, options);
+  }
+
+  if (command === "conversation") parseConversationAction(args, options);
+
   if (command === "reviews") {
     parseReviewsAction(args, options);
   }
@@ -606,6 +643,7 @@ export function parseArgs(argv) {
       options.cwd = resolve(args[++index]);
       options.cwdExplicit = true;
     }
+    else if (arg === "--workspace-bound") options.workspaceBound = true;
     else if (arg === "--scope") options.scope = parseScope(args[++index]);
     else if (arg.startsWith("--scope=")) options.scope = parseScope(arg.slice("--scope=".length));
     else if (arg === "--mode") {
@@ -687,7 +725,7 @@ export function parseArgs(argv) {
     else if (arg === "--simple") options.simple = true;
     else if (arg === "--task" || arg.startsWith("--task=")) {
       const taskValue = arg.startsWith("--task=") ? arg.slice("--task=".length) : args[++index];
-      if (command === "run") options.task = taskValue;
+      if (command === "run" || command === "architect" || command === "conversation") options.task = taskValue;
       else options.intelligenceTask = taskValue;
     }
     else if (arg === "--prompt") options.intelligencePrompt = args[++index];
@@ -698,6 +736,8 @@ export function parseArgs(argv) {
     else if (arg.startsWith("--agent=")) options.agent = arg.slice("--agent=".length);
     else if (arg === "--model") options.model = args[++index];
     else if (arg.startsWith("--model=")) options.model = arg.slice("--model=".length);
+    else if (arg === "--role") options.role = args[++index];
+    else if (arg.startsWith("--role=")) options.role = arg.slice("--role=".length);
     else if (arg === "--strategy") {
       options.strategy = normalizeRunStrategy(requireFlagValue("--strategy", args[++index]));
     } else if (arg.startsWith("--strategy=")) {
@@ -727,6 +767,8 @@ export function parseArgs(argv) {
     else if (arg.startsWith("--timeout=")) options.timeoutMs = parsePositiveInt(arg.slice("--timeout=".length), "timeout") * 1000;
     else if (arg === "--include-private") options.includePrivate = true;
     else if (arg === "--cloud-consent") options.cloudConsent = true;
+    else if (arg === "--port") options.port = parsePositiveInt(args[++index], "port");
+    else if (arg.startsWith("--port=")) options.port = parsePositiveInt(arg.slice("--port=".length), "port");
     else if (arg === "--base") options.base = requireFlagValue("--base", args[++index]);
     else if (arg.startsWith("--base=")) options.base = requireFlagValue("--base", arg.slice("--base=".length));
     else if (arg === "--commit") options.commit = requireFlagValue("--commit", args[++index]);
@@ -743,7 +785,7 @@ export function parseArgs(argv) {
     else throw new Error(`Unknown option "${arg}".`);
   }
 
-  if (command === "run" && !options.task && args.length > 0) {
+  if ((command === "run" || command === "architect") && !options.task && args.length > 0) {
     options.task = args.join(" ").trim();
   }
 
@@ -760,6 +802,24 @@ export function parseArgs(argv) {
   return { command, options, isImplicitCommand: implicitCommand };
 }
 
+function parseConversationAction(args, options) {
+  const action = args[0];
+  if (!action || action.startsWith("-")) {
+    options.conversationAction = "snapshot";
+    return;
+  }
+  if (!new Set(["snapshot", "architect", "show", "approve", "reject", "execute", "cancel"]).has(action)) {
+    throw new Error(`Unknown conversation action "${action}".`);
+  }
+  args.shift();
+  options.conversationAction = action;
+  if (["show", "approve", "reject", "execute", "cancel"].includes(action)) {
+    const taskId = args.shift();
+    if (!taskId || taskId.startsWith("-")) throw new Error(`Missing task id for conversation ${action}.`);
+    options.taskId = taskId;
+  }
+}
+
 function parseComponentsAction(args, options) {
   const action = args[0];
   if (!action || action.startsWith("-")) return;
@@ -878,6 +938,26 @@ function parseRunsAction(args, options) {
   }
 }
 
+function parsePlansAction(args, options) {
+  const action = args[0];
+  if (!action || action.startsWith("-")) {
+    options.plansAction = "list";
+    return;
+  }
+  if (!new Set(["list", "show", "approve", "reject"]).has(action)) {
+    throw new Error(`Unknown plans action "${action}". Use list, show, approve, or reject.`);
+  }
+  args.shift();
+  options.plansAction = action;
+  if (action !== "list") {
+    const taskId = args[0];
+    if (!taskId || taskId.startsWith("-")) {
+      throw new Error(`Missing task id. Use: ${formatCliCommand(`plans ${action} <taskId>`)}`);
+    }
+    options.taskId = args.shift();
+  }
+}
+
 function parseReviewsAction(args, options) {
   const action = args[0];
   if (!action || action.startsWith("-")) {
@@ -1053,6 +1133,11 @@ function normalizeCommand(command) {
   if (command === "orchestrator") return "orchestrator";
   if (command === "run") return "run";
   if (command === "runs") return "runs";
+  if (command === "architect") return "architect";
+  if (command === "plans") return "plans";
+  if (command === "conversation") return "conversation";
+  if (command === "ui") return "ui";
+  if (command === "start") return "start";
   if (command === "review") return "review";
   if (command === "reviews") return "reviews";
   if (command === "monitor") return "monitor";

package/src/global/agent-capabilities/create-capability-adapter.js

@@ -28,9 +28,9 @@ export function createAgentCapabilityAdapter({
       return managedAdapter.detect(context);
     },
 
-    inspect(context, { probeImpl = defaultProbe } = {}) {
+    inspect(context, { probeImpl = defaultProbe, isExecutableAvailableImpl = isExecutableAvailable } = {}) {
       const detected = managedAdapter.detect(context);
-      const cliAvailable = executable ? isExecutableAvailable(executable) : false;
+      const cliAvailable = executable ? isExecutableAvailableImpl(executable) : false;
 
       if (!detected && !cliAvailable) {
         return buildInspection({

package/src/global/architect/architect-cli.js

@@ -0,0 +1,76 @@
+import { resolve } from "node:path";
+import { createArchitecturePlan } from "./architect-manager.js";
+import { PLAN_STATES } from "./architect-types.js";
+import {
+  listTaskRecords, readTaskRecord, resolveProjectRoot, transitionTask
+} from "./architect-store.js";
+import { printJson } from "../json-output.js";
+import { commandHeader } from "../brand/index.js";
+
+function publicRecord(projectRoot, record) {
+  const status = record.status ?? record;
+  const planExists = record.planMarkdown != null
+    || [PLAN_STATES.AWAITING_APPROVAL, PLAN_STATES.APPROVED, PLAN_STATES.REJECTED].includes(status.state);
+  return {
+    ...status,
+    ...(record.taskMarkdown ? { taskMarkdown: record.taskMarkdown } : {}),
+    ...(record.planMarkdown ? { planMarkdown: record.planMarkdown } : {}),
+    planPath: status.artifacts?.plan && planExists
+      ? (record.paths?.planPath ?? resolve(projectRoot, status.artifacts.plan))
+      : null
+  };
+}
+
+export async function runArchitectCli(options, deps = {}) {
+  const createPlan = deps.createPlan ?? createArchitecturePlan;
+  const result = await createPlan({ task: options.task, cwd: options.cwd, model: options.model });
+  const data = {
+    ...publicRecord(result.status.projectRoot, { status: result.status, paths: result.paths }),
+    reused: result.reused === true
+  };
+  if (options.json) printJson(data);
+  else {
+    console.log(commandHeader(`architecture plan · ${data.taskId}`));
+    console.log(`State: ${data.state}`);
+    if (data.planPath) {
+      console.log(`Plan: ${data.artifacts.plan}`);
+      console.log(`Approve: kairo plans approve ${data.taskId}`);
+    } else {
+      console.log("Planning is still active; no plan artifact is ready yet.");
+    }
+  }
+  return data;
+}
+
+export async function runPlansCli(options, deps = {}) {
+  const projectRoot = await (deps.resolveRoot ?? resolveProjectRoot)(options.cwd);
+  const action = options.plansAction ?? "list";
+  if (action === "list") {
+    const plans = await (deps.listRecords ?? listTaskRecords)(projectRoot);
+    const data = { projectRoot, plans };
+    if (options.json) printJson(data);
+    else {
+      console.log(commandHeader("architecture plans"));
+      for (const plan of plans) console.log(`  ${plan.taskId}  ${plan.state}  ${plan.artifacts?.plan ?? ""}`);
+      if (!plans.length) console.log("  (no plans)");
+    }
+    return data;
+  }
+  if (action === "show") {
+    const record = await (deps.readRecord ?? readTaskRecord)(projectRoot, options.taskId);
+    if (!record) throw new Error(`Plan "${options.taskId}" not found.`);
+    const data = publicRecord(projectRoot, record);
+    if (options.json) printJson(data);
+    else {
+      console.log(commandHeader(`architecture plan · ${data.taskId}`));
+      console.log(record.planMarkdown ?? `No plan artifact (${data.state}): ${data.error?.message ?? "planning did not complete"}`);
+    }
+    return data;
+  }
+  const state = action === "approve" ? PLAN_STATES.APPROVED : PLAN_STATES.REJECTED;
+  const record = await (deps.transition ?? transitionTask)(projectRoot, options.taskId, state);
+  const data = publicRecord(projectRoot, record);
+  if (options.json) printJson(data);
+  else console.log(`${data.taskId}: ${data.state}`);
+  return data;
+}

package/src/global/architect/architect-codex.js

@@ -0,0 +1,146 @@
+import {
+  ReviewExecError,
+  assertBoundedProcessOk,
+  runBoundedProcess
+} from "../runtime/review/review-exec.js";
+import { buildCodexCliEnv } from "../runtime/review/review-codex.js";
+
+export const ARCHITECT_CODEX_ERRORS = Object.freeze({
+  INVALID_JSONL: "invalid_jsonl",
+  MISSING_PLAN: "missing_plan",
+  STREAM_ERROR: "stream_error",
+  SUBSCRIPTION_AUTH_REQUIRED: "subscription_auth_required"
+});
+
+const AUTH_TIMEOUT_MS = 10_000;
+const AUTH_OUTPUT_LIMIT = 8_192;
+
+export function buildArchitectCodexArgs({ cwd, model = null } = {}) {
+  if (typeof cwd !== "string" || !cwd) throw new Error("Architect requires cwd.");
+  const args = [
+    "--ask-for-approval", "never",
+    "exec", "--json", "--ephemeral", "--ignore-user-config",
+    "--sandbox", "read-only", "-C", cwd,
+    "-c", "shell_environment_policy.inherit=none"
+  ];
+  if (model) args.push("-m", String(model));
+  args.push("-");
+  return args;
+}
+
+export function buildArchitectPrompt(task, { contextPack = null } = {}) {
+  return [
+    "You are the architecture planner for this repository.",
+    "Use the bounded Kairo context pack below as primary evidence.",
+    "Do not broadly scan the repository. Inspect additional files only when the context pack identifies a concrete gap required to plan safely.",
+    "Honor all AGENTS.md and governance instructions included in the context pack.",
+    "Do not modify files, run destructive commands, or implement code.",
+    "Return a concise implementation plan in Markdown with: Goal, Verified context, Design, Files, Tests, Risks, and Acceptance criteria.",
+    "Challenge unsupported assumptions and identify any blocking unknowns.",
+    "",
+    "TASK",
+    String(task).trim(),
+    "",
+    "BOUNDED KAIRO CONTEXT PACK",
+    contextPack?.systemPrompt ?? "No context pack was available; state this limitation in Verified context."
+  ].join("\n");
+}
+
+export function buildArchitectCodexEnv(sourceEnv = process.env) {
+  const env = buildCodexCliEnv(sourceEnv);
+  // M1 is subscription-only. Never let an ambient API key or alternate paid
+  // endpoint turn subscription exhaustion into PAYG.
+  for (const key of ["OPENAI_API_KEY", "OPENAI_BASE_URL", "OPENAI_API_BASE"]) delete env[key];
+  return env;
+}
+
+export async function verifyCodexSubscriptionAuth({
+  env = process.env, runProcess = runBoundedProcess
+} = {}) {
+  const result = await runProcess({
+    command: "codex",
+    args: ["login", "status"],
+    env: buildArchitectCodexEnv(env),
+    stdin: null,
+    timeoutMs: AUTH_TIMEOUT_MS,
+    stdoutLimit: AUTH_OUTPUT_LIMIT,
+    stderrLimit: AUTH_OUTPUT_LIMIT
+  });
+  assertBoundedProcessOk(result);
+  const evidence = `${result.stdout ?? ""}\n${result.stderr ?? ""}`;
+  if (!/(?:^|\n)Logged in using ChatGPT\r?(?:\n|$)/.test(evidence)) {
+    throw new ReviewExecError(
+      "Codex must be logged in using ChatGPT subscription auth; API-key and unknown auth modes are refused.",
+      { code: ARCHITECT_CODEX_ERRORS.SUBSCRIPTION_AUTH_REQUIRED }
+    );
+  }
+  return { mode: "chatgpt" };
+}
+
+export function parseArchitectCodexJsonl(stdout) {
+  let plan = null;
+  let usage = null;
+  let streamError = null;
+  const raw = String(stdout ?? "");
+  const lines = raw.split(/\r?\n/);
+  const complete = raw.endsWith("\n") || raw.endsWith("\r\n") ? lines : lines.slice(0, -1);
+  for (const line of complete) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    let event;
+    try { event = JSON.parse(trimmed); }
+    catch (error) {
+      throw new ReviewExecError(`Malformed Codex JSONL: ${error.message}`, {
+        code: ARCHITECT_CODEX_ERRORS.INVALID_JSONL
+      });
+    }
+    if (!event || typeof event !== "object") {
+      throw new ReviewExecError("Malformed Codex JSONL event.", {
+        code: ARCHITECT_CODEX_ERRORS.INVALID_JSONL
+      });
+    }
+    if (event.type === "error") streamError = String(event.message ?? "Codex stream error.");
+    else if (event.type === "turn.failed") streamError = String(event.error?.message ?? "Codex turn failed.");
+    else if (event.type === "turn.completed" && event.usage && typeof event.usage === "object") {
+      const input = Number.isFinite(event.usage.input_tokens) ? event.usage.input_tokens : null;
+      const output = Number.isFinite(event.usage.output_tokens) ? event.usage.output_tokens : null;
+      usage = {
+        inputTokens: input,
+        outputTokens: output,
+        totalTokens: input != null && output != null ? input + output : null,
+        cost: null
+      };
+    } else if (event.type === "item.completed" && event.item?.type === "agent_message"
+      && typeof event.item.text === "string") {
+      plan = event.item.text;
+    }
+  }
+  if (streamError) {
+    throw new ReviewExecError(streamError, { code: ARCHITECT_CODEX_ERRORS.STREAM_ERROR });
+  }
+  if (typeof plan !== "string" || !plan.trim()) {
+    throw new ReviewExecError("Codex JSONL missing final architecture plan.", {
+      code: ARCHITECT_CODEX_ERRORS.MISSING_PLAN
+    });
+  }
+  return { plan: plan.trim(), usage };
+}
+
+export async function runArchitectCodex({
+  task, cwd, model = null, contextPack = null, env = process.env, spawnImpl, timeoutMs,
+  runProcess = runBoundedProcess, verifyAuth = verifyCodexSubscriptionAuth
+} = {}) {
+  const codexEnv = buildArchitectCodexEnv(env);
+  await verifyAuth({ env: codexEnv });
+  const result = await runProcess({
+    command: "codex",
+    args: buildArchitectCodexArgs({ cwd, model }),
+    cwd,
+    env: codexEnv,
+    stdin: buildArchitectPrompt(task, { contextPack }),
+    spawnImpl,
+    timeoutMs
+  });
+  assertBoundedProcessOk(result);
+  return parseArchitectCodexJsonl(result.stdout);
+}

package/src/global/architect/architect-manager.js

@@ -0,0 +1,125 @@
+import {
+  PLAN_STATES, ARCHITECT_SCHEMA, createArchitectureRequestKey,
+  createTaskId, normalizeArchitectTask, sha256
+} from "./architect-types.js";
+import { runArchitectCodex } from "./architect-codex.js";
+import {
+  acquireRequestLock, findReusableRequest, prepareTaskDirectory, resolveHead,
+  resolveProjectRoot, writeAtomicText, writeTaskArtifacts
+} from "./architect-store.js";
+import { writeAtomicJson } from "../runtime/write-atomic-json.js";
+import { compileContextPack } from "../intelligence/context-compiler.js";
+
+const REQUEST_DISCOVERY_ATTEMPTS = 40;
+const REQUEST_DISCOVERY_DELAY_MS = 25;
+
+async function waitForReusableRequest(projectRoot, requestKey) {
+  for (let attempt = 0; attempt < REQUEST_DISCOVERY_ATTEMPTS; attempt += 1) {
+    const active = await findReusableRequest(projectRoot, requestKey, {
+      states: [PLAN_STATES.DRAFT, PLAN_STATES.AWAITING_APPROVAL]
+    });
+    if (active) return active;
+    await new Promise((resolve) => setTimeout(resolve, REQUEST_DISCOVERY_DELAY_MS));
+  }
+  return null;
+}
+
+async function prepareUniqueTask(projectRoot, task, now) {
+  const baseId = createTaskId(task, now);
+  for (let attempt = 0; attempt < 100; attempt += 1) {
+    const suffix = attempt === 0 ? "" : `-${attempt + 1}`;
+    const taskId = `${baseId.slice(0, 96 - suffix.length)}${suffix}`;
+    try {
+      const paths = await prepareTaskDirectory(projectRoot, taskId, { createExclusive: true });
+      return { taskId, paths };
+    } catch (error) {
+      if (error?.code !== "EEXIST") throw error;
+    }
+  }
+  throw new Error("Unable to allocate a unique architecture task id.");
+}
+
+export async function createArchitecturePlan({
+  task, cwd = process.cwd(), model = null, now = new Date(), runCodex = runArchitectCodex,
+  resolveRoot = resolveProjectRoot, resolveGitHead = resolveHead,
+  compileContext = compileContextPack, acquireLock = acquireRequestLock
+} = {}) {
+  if (typeof task !== "string" || !task.trim()) throw new Error("Architect task is required.");
+  const projectRoot = await resolveRoot(cwd);
+  const baseHead = resolveGitHead(projectRoot);
+  const normalizedTask = normalizeArchitectTask(task);
+  const normalizedModel = model == null ? null : String(model).trim() || null;
+  const requestKey = createArchitectureRequestKey({
+    projectRoot, baseHead, task: normalizedTask, model: normalizedModel
+  });
+  const reusable = await findReusableRequest(projectRoot, requestKey);
+  if (reusable) return { status: reusable.status, paths: reusable.paths, reused: true };
+
+  const lock = await acquireLock(projectRoot, requestKey, { now });
+  if (!lock.acquired) {
+    const active = await waitForReusableRequest(projectRoot, requestKey);
+    if (active) return { status: active.status, paths: active.paths, reused: true };
+    throw new Error("An identical architecture request is already starting. Retry shortly.");
+  }
+
+  let paths;
+  try {
+    const afterLock = await findReusableRequest(projectRoot, requestKey);
+    if (afterLock) return { status: afterLock.status, paths: afterLock.paths, reused: true };
+    const orphan = await findReusableRequest(projectRoot, requestKey, { states: [PLAN_STATES.DRAFT] });
+    if (orphan) {
+      await writeAtomicJson(orphan.paths.statusPath, {
+        ...orphan.status,
+        state: PLAN_STATES.FAILED,
+        updatedAt: now.toISOString(),
+        error: {
+          code: "stale_architect_request",
+          message: "Recovered an interrupted architecture request whose owner is no longer active."
+        }
+      });
+    }
+    const prepared = await prepareUniqueTask(projectRoot, normalizedTask, now);
+    const taskId = prepared.taskId;
+    paths = prepared.paths;
+    const taskMarkdown = `# Task\n\n${normalizedTask}\n`;
+    const createdAt = now.toISOString();
+    const draft = {
+      schema: ARCHITECT_SCHEMA, taskId, state: PLAN_STATES.DRAFT,
+      requestKey, provider: "codex", model: normalizedModel, projectRoot, baseHead,
+      taskDigest: sha256(normalizedTask), taskArtifactDigest: sha256(taskMarkdown),
+      planArtifactDigest: null, usage: null,
+      createdAt, updatedAt: createdAt, decisionAt: null, decisionHead: null,
+      artifacts: { task: ".ai/tasks/" + taskId + "/task.md", plan: ".ai/tasks/" + taskId + "/plan.md" }
+    };
+    await writeAtomicText(paths.taskPath, taskMarkdown);
+    await writeAtomicJson(paths.statusPath, draft);
+    try {
+      const contextPack = await compileContext({
+        workspaceRoot: projectRoot, task: normalizedTask, relevantPaths: [], includePrivate: false
+      });
+      const result = await runCodex({
+        task: normalizedTask, cwd: projectRoot, model: normalizedModel, contextPack
+      });
+      const planMarkdown = `# Architecture Plan\n\n${result.plan.trim()}\n`;
+      const awaiting = {
+        ...draft,
+        state: PLAN_STATES.AWAITING_APPROVAL,
+        planArtifactDigest: sha256(planMarkdown),
+        usage: result.usage ?? null,
+        updatedAt: new Date().toISOString()
+      };
+      await writeTaskArtifacts({
+        projectRoot, taskId, task: normalizedTask, plan: result.plan, status: awaiting
+      });
+      return { status: awaiting, paths, reused: false };
+    } catch (error) {
+      await writeAtomicJson(paths.statusPath, {
+        ...draft, state: PLAN_STATES.FAILED, updatedAt: new Date().toISOString(),
+        error: { code: error?.code ?? "architect_failed", message: error?.message ?? String(error) }
+      });
+      throw error;
+    }
+  } finally {
+    await lock.release();
+  }
+}