feat: add local codex trace collector

scripts/src/help.ts

@@ -385,9 +385,12 @@ function scheduleHelp(): unknown {
 
 function codexHelp(): unknown {
   return {
-    command: "codex deploy|submit|task|tasks|unread|output|read|dev-ready|skills-sync|execution-plane|pr-preflight|judge|steer|resume|interrupt|cancel|queues|queue|move",
+    command: "codex trace|deploy|submit|task|tasks|unread|output|read|dev-ready|skills-sync|execution-plane|pr-preflight|judge|steer|resume|interrupt|cancel|queues|queue|move",
     output: "json",
     usage: [
+      "bun scripts/cli.ts codex trace list [--root ~/.codex] [--limit 30]",
+      "bun scripts/cli.ts codex trace collect [--root ~/.codex] [--output .state/codex-trace/<timestamp>] [--limit 30]",
+      "bun scripts/cli.ts codex trace show --file sessions/2026/06/16/<session>.jsonl [--root ~/.codex] [--tail-bytes 12000]",
       "bun scripts/cli.ts codex deploy <commitId> # disabled legacy deployment entry",
       "bun scripts/cli.ts agentrun get tasks --queue commander --limit 20",
       "bun scripts/cli.ts agentrun describe aipodspec/Artificer",
@@ -435,6 +438,13 @@ function codexHelp(): unknown {
       default: "codex read marks a terminal task read and returns terminal metadata, final response, last error/judge, counts, and drill-down commands.",
       disclosure: "Full prompt, tool logs, and feedback prompts are not printed by codex read; use codex task/detail/trace/output for progressive disclosure.",
     },
+    localTrace: {
+      defaultRoot: "~/.codex",
+      defaultIncludes: ["sessions/*.jsonl", "history.jsonl", "shell_snapshots", "*.log", "trace-named text files"],
+      defaultExcludes: ["auth/config", "sqlite", "cache/.tmp/generated_images/plugins/skills"],
+      collectOutput: ".state/codex-trace/<timestamp>/manifest.json",
+      note: "Use --root <dir> to scan another local Codex trace directory; collect copies bounded files locally and never uploads or deletes source files.",
+    },
     unreadTriage: {
       default: "codex unread is read-only by default and returns counts, buckets, compact task rows, and one-time drill-down templates; per-task command blocks require --full or list.",
       mutationGuard: "Batch mark-read is blocked unless the explicit mark-read subcommand is used with --confirm; use codex read <taskId> for per-task review.",
@@ -716,6 +726,7 @@ export async function staticNamespaceHelp(args: string[]): Promise<unknown | nul
   if (top === "gc") return gcHelp();
   if (top === "commander") return commanderHelp();
   if (top === "schedule") return scheduleHelp();
+  if (top === "codex" && sub === "trace") return loadHelp(async () => (await import("./codex-trace")).codexTraceHelp(), codexHelp());
   if (top === "codex") return codexHelp();
   if (top === "job") return jobHelp();
   if (top === "debug") return debugHelp();