Harden real Codex workflow runs

Author: robzilla1738

AGENTS.md

@@ -53,7 +53,9 @@ For MCP smoke testing, start the generated server from
   Node built-in access.
 - Bug-finding workflows should default to read-only workers.
 - Model overrides from the caller beat workflow defaults.
-- Preserve durable run state under `.codex-workflows/runs/<run-id>/`.
+- Default durable run state belongs under Codex home so read-only runs do not
+  dirty target repos. Project-local `.codex-workflows/runs/<run-id>/` is opt-in
+  and legacy-readable.
 
 ## Writing style
 

CLAUDE.md

@@ -53,7 +53,9 @@ For MCP smoke testing, start the generated server from
   Node built-in access.
 - Bug-finding workflows should default to read-only workers.
 - Model overrides from the caller beat workflow defaults.
-- Preserve durable run state under `.codex-workflows/runs/<run-id>/`.
+- Default durable run state belongs under Codex home so read-only runs do not
+  dirty target repos. Project-local `.codex-workflows/runs/<run-id>/` is opt-in
+  and legacy-readable.
 
 ## Writing style
 

README.md

@@ -27,7 +27,7 @@ codex plugin add codex-workflows@codex-workflows
 Start a new Codex thread after installing. Then ask:
 
 ```text
-Use codex-workflows to run the bug-sweep workflow with adapter sdk.
+Use codex-workflows to run the bug-sweep workflow with adapter auto.
 Open the live dashboard automatically and tell me the run id and status.
 ```
 
@@ -44,7 +44,10 @@ from Codex or from the CLI.
   boundary review.
 - Live dashboard with phases, agent rows, token/tool/time metrics, detail view,
   pause/resume/stop/restart/save controls, and final report path.
-- Durable run state under `.codex-workflows/runs/<run-id>/`.
+- Durable run state under `${CODEX_HOME:-~/.codex}/codex-workflows/projects/<project-hash>/runs/<run-id>/`
+  by default, so read-only bug hunts do not dirty the target repo.
+- Project-local storage remains available with `storageScope: "project"` or
+  `--storage-scope project`.
 - Isolated workflow script loading through QuickJS. Workflow scripts define
   phases and agent prompts; they do not get direct filesystem, shell, network,
   process, or Node built-in access.
@@ -54,7 +57,7 @@ from Codex or from the CLI.
 You can route models globally or by phase/agent:
 
 ```text
-Use codex-workflows to run bug-sweep with adapter sdk,
+Use codex-workflows to run bug-sweep with adapter auto,
 model gpt-5.5, reasoning xhigh,
 and modelMap {"find":"gpt-5.4-mini","synthesize":"gpt-5.5"}.
 ```
@@ -66,6 +69,10 @@ Caller overrides win over workflow defaults:
 - `modelMap`: phase id, agent id, or `phase:agent` overrides.
 - `promptSuffix`: extra instruction appended to every worker.
 
+Model names are validated against the local `codex debug models` catalog before
+any agents launch. Short names such as `5.4-mini` are rejected with a suggestion
+like `gpt-5.4-mini`; they are not silently rewritten.
+
 Bug-finding workflows default to read-only workers unless a workflow explicitly
 declares otherwise.
 
@@ -77,6 +84,7 @@ pnpm validate:plugin
 pnpm test
 pnpm cwf validate workflows/bug-sweep.workflow.js
 pnpm cwf run workflows/bug-sweep.workflow.js --watch --adapter simulate
+pnpm cwf run workflows/bug-sweep.workflow.js --watch --adapter auto --model gpt-5.4-mini
 ```
 
 Useful local commands:

docs/architecture.md

@@ -20,7 +20,13 @@ The code is split so those two jobs do not get tangled.
 
 ## Run state
 
-Every run writes to `.codex-workflows/runs/<run-id>/`:
+By default, read-only workflow runs write under
+`${CODEX_HOME:-~/.codex}/codex-workflows/projects/<project-hash>/runs/<run-id>/`
+so bug hunts do not dirty the target checkout. Project-local storage is still
+available with `storageScope: "project"` or `--storage-scope project`, and
+legacy `.codex-workflows/runs/<run-id>/` directories remain readable.
+
+Each run directory contains:
 
 - `manifest.json`: workflow definition, args, and launch options.
 - `status.json`: current summary for the TUI and MCP status calls.

docs/claude-workflows-parity.md

@@ -200,11 +200,13 @@ Use a supervisor process:
 4. Require approval for the script hash and capabilities.
 5. Execute phases.
 6. Spawn workers through Codex SDK/app-server, with `codex exec --json` as fallback.
-7. Persist all events to `.codex-workflows/runs/<run-id>/events.jsonl`.
+7. Persist all events to the run store, defaulting to
+   `${CODEX_HOME:-~/.codex}/codex-workflows/projects/<project-hash>/runs/<run-id>/events.jsonl`
+   so read-only runs do not dirty target repos.
 8. Persist checkpoints, agent results, token usage, patches, and final report.
 9. Expose status through MCP and the `cwf` CLI.
 
-Suggested run directory:
+Suggested project-local run directory when `storageScope: "project"` is used:
 
 ```text
 .codex-workflows/runs/2026-06-03T20-12-48Z-abc123/

docs/plugin-distribution.md

@@ -33,7 +33,7 @@ codex plugin add codex-workflows@codex-workflows
 After installing, start a new Codex thread and ask:
 
 ```text
-Use codex-workflows to run the bug-sweep workflow with adapter sdk.
+Use codex-workflows to run the bug-sweep workflow with adapter auto.
 Open the live dashboard automatically and tell me the run id.
 ```
 
@@ -77,7 +77,8 @@ reload plugin skills and MCP tools.
    ```
 
 5. Smoke the generated MCP server from `plugins/codex-workflows`.
-6. Run at least one real `adapter: sdk` workflow before tagging a release.
+6. Run at least one real `adapter: auto` workflow before tagging a release and
+   confirm the actual adapter is recorded in the run status.
 7. Tag and push:
 
    ```bash

packages/cli/src/dashboard.tsx

@@ -1,13 +1,15 @@
 import { useEffect, useMemo, useState } from "react";
 import { spawn } from "node:child_process";
 import { Box, Text, useInput, useStdout } from "ink";
-import type { AgentSummary, RunSummary } from "@codex-workflows/schemas";
-import { nowIso, RunStore } from "@codex-workflows/runtime";
+import type { AgentSummary, RunSummary, StorageScope } from "@codex-workflows/schemas";
+import { defaultStoreRoot, nowIso, RunStore } from "@codex-workflows/runtime";
 import { formatCount, formatDuration, truncateMiddle } from "./format.js";
 
 export interface DashboardProps {
   cwd: string;
   runId: string;
+  storageScope?: StorageScope;
+  storeRoot?: string;
   exitOnComplete?: boolean;
   onExit?: () => void;
 }
@@ -117,6 +119,18 @@ export function DashboardFrame({
         </Text>
       </Box>
       <Text color="gray">{summary.description}</Text>
+      <Box justifyContent="space-between">
+        <Text color={summary.status === "failed" ? "red" : summary.status === "completed" ? "green" : "gray"}>
+          {summary.status}
+          {summary.error ? ` · ${truncateMiddle(summary.error, Math.max(20, width - 72))}` : ""}
+        </Text>
+        <Text color="gray">
+          {summary.requestedAdapter ?? "auto"} → {summary.actualAdapter ?? "pending"}
+        </Text>
+      </Box>
+      {summary.finalReportPath ? (
+        <Text color="gray">Report: {truncateMiddle(summary.finalReportPath, width - 8)}</Text>
+      ) : null}
       <Box marginTop={1} borderStyle="single" borderColor="gray">
         <Box width={sidebarWidth} flexDirection="column" borderStyle="single" borderTop={false} borderBottom={false} borderLeft={false}>
           <Text>Phases</Text>
@@ -198,8 +212,19 @@ export function DashboardFrame({
   );
 }
 
-export function RunDashboard({ cwd, runId, exitOnComplete = false, onExit }: DashboardProps) {
-  const store = useMemo(() => new RunStore(cwd), [cwd]);
+export function RunDashboard({
+  cwd,
+  runId,
+  storageScope = "codex-home",
+  storeRoot,
+  exitOnComplete = false,
+  onExit
+}: DashboardProps) {
+  const resolvedStoreRoot = storeRoot ?? defaultStoreRoot(cwd, storageScope);
+  const store = useMemo(
+    () => new RunStore(cwd, { storageScope, storeRoot: resolvedStoreRoot }),
+    [cwd, resolvedStoreRoot, storageScope]
+  );
   const [summary, setSummary] = useState<RunSummary | null>(null);
   const [selectedPhaseId, setSelectedPhaseId] = useState<string | undefined>();
   const [selectedAgentId, setSelectedAgentId] = useState<string | undefined>();
@@ -313,7 +338,18 @@ export function RunDashboard({ cwd, runId, exitOnComplete = false, onExit }: Das
     if (input === "r" && selectedAgentId) {
       const child = spawn(
         process.execPath,
-        [process.argv[1] ?? "", "restart-agent", runId, selectedAgentId, "--cwd", cwd],
+        [
+          process.argv[1] ?? "",
+          "restart-agent",
+          runId,
+          selectedAgentId,
+          "--cwd",
+          cwd,
+          "--storage-scope",
+          storageScope,
+          "--store-root",
+          resolvedStoreRoot
+        ],
         { stdio: "ignore", detached: true }
       );
       child.unref();