okstra 0.77.0 → 0.78.0

package/src/cli-registry.mjs

@@ -0,0 +1,277 @@
+const SUMMARY_COLUMN = 25;
+
+export const COMMAND_REGISTRY = [
+  {
+    name: "install",
+    module: "./install.mjs",
+    export: "runInstall",
+    category: "admin",
+    summary: ["Install runtime; --runtime codex skips ~/.claude assets"],
+  },
+  {
+    name: "ensure-installed",
+    module: "./install.mjs",
+    export: "runEnsureInstalled",
+    category: "admin",
+    summary: ["Verify install is fresh; reinstall if stale (idempotent)"],
+  },
+  {
+    name: "uninstall",
+    module: "./uninstall.mjs",
+    export: "runUninstall",
+    category: "admin",
+    summary: ["Remove runtime + skills (user data preserved by default)"],
+  },
+  {
+    name: "setup",
+    module: "./setup.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Register the current project (.okstra/project.json)"],
+  },
+  {
+    name: "doctor",
+    module: "./doctor.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Diagnostic check; --runtime selects assets, --phase checks readiness",
+    ],
+  },
+  {
+    name: "check-project",
+    module: "./check-project.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Verify the current project has been registered with setup"],
+  },
+  {
+    name: "config",
+    module: "./config.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Read / write okstra settings (e.g. PR template path)"],
+  },
+  {
+    name: "migrate",
+    module: "./migrate.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Move legacy .project-docs/okstra/ to .okstra/ (one-shot)"],
+  },
+  {
+    name: "git-reconcile",
+    module: "./git-reconcile.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Reconcile stale stage SHAs after external git history changes"],
+  },
+  {
+    name: "handoff",
+    module: "./handoff.mjs",
+    export: "run",
+    category: "admin",
+    summary: ["Stage-group release-handoff helpers (eligible/assemble/record)"],
+  },
+  {
+    name: "paths",
+    module: "./paths.mjs",
+    export: "run",
+    category: "admin",
+    summary: [
+      "Print runtime paths (workspace/agents/pythonpath/bin/home/version)",
+    ],
+  },
+  {
+    name: "task-list",
+    module: "./task-list.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["List tasks registered in the current project"],
+  },
+  {
+    name: "task-show",
+    module: "./task-show.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Summarize a task's manifest + workflow phase state"],
+  },
+  {
+    name: "context-cost",
+    module: "./context-cost.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Estimate file/read context cost for a task bundle"],
+  },
+  {
+    name: "worktree-lookup",
+    module: "./worktree-lookup.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Look up registered worktree for a task-key"],
+  },
+  {
+    name: "plan-validate",
+    module: "./plan-validate.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Check an approved-plan file for the approval marker"],
+  },
+  {
+    name: "render-bundle",
+    module: "./render-bundle.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Preview prepare_task_bundle() output (forwards to",
+      "python3 -m okstra_ctl.run --render-only)",
+    ],
+  },
+  {
+    name: "codex-run",
+    module: "./codex-run.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Prepare a render-only Codex lead task bundle",
+      "(--lead-runtime codex, no worker dispatch)",
+    ],
+  },
+  {
+    name: "codex-dispatch",
+    module: "./codex-dispatch.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dispatch CLI-backed workers for a prepared Codex run"],
+  },
+  {
+    name: "team",
+    module: "./team.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Dispatch and await tmux-pane workers for external leads"],
+  },
+  {
+    name: "wizard",
+    module: "./wizard.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Drive the okstra-run interactive input state machine",
+      "(init / step / render-args / confirmation)",
+    ],
+  },
+  {
+    name: "token-usage",
+    module: "./token-usage.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Collect token usage for a run (wraps the installed",
+      "okstra-token-usage.py so skills avoid emitting",
+      'python3 "$HOME/..." invocations).',
+    ],
+  },
+  {
+    name: "render-views",
+    module: "./render-views.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Render slim AI + self-contained HTML views of a final report"],
+  },
+  {
+    name: "render-final-report",
+    module: "./render-final-report.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Render the markdown sibling of a final-report data.json"],
+  },
+  {
+    name: "inject-report-index",
+    module: "./inject-report-index.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Add the top-of-report Index + scroll anchors to a report"],
+  },
+  {
+    name: "spawn-followups",
+    module: "./spawn-followups.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Create follow-up task bundles from a final report"],
+  },
+  {
+    name: "error-log",
+    module: "./error-log.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Append run error events to the run error log"],
+  },
+  {
+    name: "memory",
+    module: "./memory.mjs",
+    export: "run",
+    category: "introspection",
+    summary: [
+      "Store and find user-home conversation memory under",
+      "~/.okstra/memory-book.",
+    ],
+  },
+];
+
+export const COMMANDS = new Map(
+  COMMAND_REGISTRY.map((c) => [
+    c.name,
+    () => import(c.module).then((m) => m[c.export]),
+  ]),
+);
+
+const PREAMBLE = `okstra — multi-agent cross-verification orchestrator for Claude Code
+
+This CLI is the installer/admin tool. Day-to-day usage happens inside a
+Claude Code session via slash commands (/okstra-setup, /okstra-run, ...).
+
+Quick start (CLI):
+  1. npx -y okstra@latest install                       # one-time, this machine
+  2. cd <your project>
+  3. npx -y okstra@latest setup --project-id <id>       # one-time, this project
+  4. open a Claude Code session and run /okstra-run     # start a task
+
+Inside a Claude Code session you can replace step 3 with /okstra-setup —
+both write the same <PROJECT_ROOT>/.okstra/project.json.
+
+Usage:
+  okstra <command> [options]
+`;
+
+const GLOBAL_OPTIONS = `  --version              Print okstra version and exit
+  --help                 Print this help`;
+
+const FOOTER = `
+
+Run 'okstra <command> --help' for command-specific options.
+Docs: https://github.com/Devonshin/okstra#readme
+`;
+
+function renderRow(command) {
+  const [first, ...rest] = command.summary;
+  const head = "  " + command.name.padEnd(SUMMARY_COLUMN - 2) + first;
+  const continuations = rest.map((line) => " ".repeat(SUMMARY_COLUMN) + line);
+  return [head, ...continuations].join("\n");
+}
+
+function renderRows(category) {
+  return COMMAND_REGISTRY.filter((c) => c.category === category)
+    .map(renderRow)
+    .join("\n");
+}
+
+export const USAGE =
+  PREAMBLE +
+  "\nAdmin commands:\n" +
+  renderRows("admin") +
+  "\n\nIntrospection commands (JSON output, used by skills to avoid python heredocs):\n" +
+  renderRows("introspection") +
+  "\n\nGlobal options:\n" +
+  GLOBAL_OPTIONS +
+  FOOTER;

package/src/doctor.mjs

@@ -3,6 +3,7 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists, runProcess } from "./_proc.mjs";
+import { runPythonSnippet } from "./_python-helper.mjs";
 import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
@@ -12,9 +13,9 @@ const USAGE = `okstra doctor — diagnose the installed runtime
 
 Usage:
   okstra doctor               Run all checks and print a summary
-  okstra doctor --runtime <claude-code|codex|all>
+  okstra doctor --runtime <claude-code|codex|external|all>
+  okstra doctor --phase <phase>
   okstra doctor --json        Machine-readable result
-
 Checks:
   - python3 binary and version (>= 3.10)
   - okstra_project module importable from $HOME/.okstra/lib/python
@@ -24,11 +25,19 @@ Checks:
   - canonical skills present at $HOME/.claude/skills/<name>/SKILL.md
     (skipped with --runtime codex)
   - version stamp matches package version
+  - optional phase readiness checks with --phase <phase>
+
+Supported phase readiness checks:
+  - implementation: git worktree support, approved-plan validator, worker agents
+  - final-verification: worktree registry, validators, final-report assets
+  - release-handoff: gh auth, clean git tree, remote, non-base branch
+  - improvement-discovery: required workers and lens whitelist
 `;
 
 export function parseDoctorArgs(args) {
   const result = {
     jsonMode: false,
+    phase: null,
     runtime: "claude-code",
   };
   for (let i = 0; i < args.length; i++) {
@@ -38,10 +47,17 @@ export function parseDoctorArgs(args) {
     } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
       const value = arg.startsWith("--runtime=") ? arg.slice("--runtime=".length) : args[i + 1];
       if (!value || value.startsWith("--")) {
-        throw new Error("--runtime requires one of: claude-code, codex, all");
+        throw new Error("--runtime requires one of: claude-code, codex, external, all");
       }
       result.runtime = validateInstallRuntime(value);
       if (arg === "--runtime") i++;
+    } else if (arg === "--phase" || arg.startsWith("--phase=")) {
+      const value = arg.startsWith("--phase=") ? arg.slice("--phase=".length) : args[i + 1];
+      if (!value || value.startsWith("--")) {
+        throw new Error("--phase requires a phase name");
+      }
+      result.phase = value;
+      if (arg === "--phase") i++;
     } else {
       throw new Error(`unknown argument '${arg}'`);
     }
@@ -53,6 +69,24 @@ export function requiredSkillNamesForRuntime(runtime) {
   return runtimeIncludesClaudeAssets(runtime) ? REQUIRED_SKILLS : [];
 }
 
+export function phaseDiagnosticsToChecks(phase, phaseDiagnostics) {
+  const checks = Array.isArray(phaseDiagnostics.checks) ? phaseDiagnostics.checks : [];
+  if (checks.length === 0) {
+    return [
+      {
+        name: `phase ${phase}: diagnostics`,
+        ok: false,
+        detail: phaseDiagnostics.reason || "phase diagnostics returned no checks",
+      },
+    ];
+  }
+  return checks.map((item) => ({
+    name: `phase ${phase}: ${item.name}`,
+    ok: Boolean(item.ok),
+    detail: String(item.detail ?? ""),
+  }));
+}
+
 async function checkPython3() {
   const r = await runProcess("python3", ["--version"]);
   if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
@@ -99,6 +133,42 @@ async function check(name, fn) {
   }
 }
 
+async function loadPhaseDiagnostics(phase, paths) {
+  const script = [
+    "import json, sys",
+    "from okstra_ctl.doctor import phase_diagnostics",
+    "payload = phase_diagnostics(",
+    "    sys.argv[1],",
+    "    cwd=sys.argv[2],",
+    "    workspace_root=sys.argv[3],",
+    "    home=sys.argv[4],",
+    ")",
+    "print(json.dumps(payload, ensure_ascii=False))",
+  ].join("\n");
+  const result = await runPythonSnippet({
+    script,
+    args: [phase, process.cwd(), paths.workspace, paths.home],
+  });
+  if (result.code !== 0 && !result.stdout.trim()) {
+    return {
+      ok: false,
+      usageError: false,
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+      checks: [],
+    };
+  }
+  try {
+    return JSON.parse(result.stdout);
+  } catch (err) {
+    return {
+      ok: false,
+      usageError: false,
+      reason: `could not parse phase diagnostics output: ${err.message}`,
+      checks: [],
+    };
+  }
+}
+
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -143,10 +213,29 @@ export async function run(args) {
     ),
   ];
 
+  let phaseDiagnostics = null;
+  if (opts.phase) {
+    phaseDiagnostics = await loadPhaseDiagnostics(opts.phase, paths);
+    if (phaseDiagnostics.usageError) {
+      process.stderr.write(`error: ${phaseDiagnostics.reason}\n`);
+      return 2;
+    }
+    results.push(...phaseDiagnosticsToChecks(opts.phase, phaseDiagnostics));
+  }
+
   const allOk = results.every((r) => r.ok);
 
   if (opts.jsonMode) {
-    process.stdout.write(`${JSON.stringify({ ok: allOk, runtime: opts.runtime, paths, checks: results }, null, 2)}\n`);
+    process.stdout.write(
+      `${JSON.stringify({
+        ok: allOk,
+        runtime: opts.runtime,
+        phase: opts.phase,
+        paths,
+        phaseDiagnostics,
+        checks: results,
+      }, null, 2)}\n`,
+    );
     return allOk ? 0 : 1;
   }
 

package/src/install.mjs

@@ -21,6 +21,7 @@ const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
+  "okstra-claude-exec.sh",
   "okstra-gemini-exec.sh",
   "okstra-trace-cleanup.sh",
   "okstra-team-reconcile.sh",
@@ -37,7 +38,7 @@ const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
 
 Usage:
   okstra install              Install/update runtime (copy mode)
-  okstra install --runtime <claude-code|codex|all>
+  okstra install --runtime <claude-code|codex|external|all>
   okstra install --link <p>   Dev only: symlink ~/.okstra/{lib/python,bin}
                               to the source repo at <p>. agents/ resolves
                               to <p>/agents. Not advertised to end users.
@@ -81,13 +82,13 @@ const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
 
 Usage:
   okstra ensure-installed     Verify install; reinstall if version/files drift
-  okstra ensure-installed --runtime <claude-code|codex|all>
+  okstra ensure-installed --runtime <claude-code|codex|external|all>
   okstra ensure-installed -q  Same, but suppress success output
 
 Skills call this on every run. Returns 0 quickly when the install is fresh.
 `;
 
-const INSTALL_RUNTIMES = new Set(["claude-code", "codex", "all"]);
+const INSTALL_RUNTIMES = new Set(["claude-code", "codex", "external", "all"]);
 
 export function runtimeIncludesClaudeAssets(runtime) {
   return runtime === "claude-code" || runtime === "all";
@@ -100,14 +101,14 @@ function readRuntimeFlag(args, index) {
   }
   const next = args[index + 1];
   if (!next || next.startsWith("--")) {
-    throw new Error("--runtime requires one of: claude-code, codex, all");
+    throw new Error("--runtime requires one of: claude-code, codex, external, all");
   }
   return { value: next, nextIndex: index + 1 };
 }
 
 export function validateInstallRuntime(value) {
   if (!INSTALL_RUNTIMES.has(value)) {
-    throw new Error(`unknown runtime '${value}' (expected: claude-code, codex, all)`);
+    throw new Error(`unknown runtime '${value}' (expected: claude-code, codex, external, all)`);
   }
   return value;
 }

package/src/runtime-manifest.mjs

@@ -1,14 +1,15 @@
 export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
 
 export function runtimeListForSelection(runtime) {
-  return runtime === "all" ? ["claude-code", "codex"] : [runtime];
+  if (runtime === "all") return ["claude-code", "codex", "external"];
+  return [runtime];
 }
 
 export function buildRuntimeManifest(runtime, installedAt = new Date().toISOString()) {
   const includesClaude = runtime === "claude-code" || runtime === "all";
   const includesCodex = runtime === "codex" || runtime === "all";
+  const includesExternal = runtime === "external" || runtime === "all";
   return {
-    version: 1,
     installedAt,
     runtime,
     runtimes: runtimeListForSelection(runtime),
@@ -17,7 +18,9 @@ export function buildRuntimeManifest(runtime, installedAt = new Date().toISOStri
       claudeSkills: includesClaude,
       claudeAgents: includesClaude,
       codexAdapter: includesCodex,
+      externalAdapter: includesExternal,
     },
+    version: 1,
   };
 }
 

package/src/team.mjs

@@ -0,0 +1,63 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra team — dispatch and await tmux-pane workers for external leads
+
+Usage:
+  okstra team dispatch --project-root <dir> --run-manifest <path> \
+    [--workers <csv>] [--jobs-file <path>] [--dry-run] \
+    [--idle-timeout-seconds <n>] [--dispatch-kind <kind>]
+  okstra team await --project-root <dir> --run-manifest <path> \
+    [--poll-interval-seconds <n>] [--timeout-seconds <n>] \
+    [--heartbeat-seconds <n>] [--json]
+  okstra team teardown --project-root <dir> --run-manifest <path> \
+    [--dry-run] [--json]
+
+This command is for leadRuntime=external bundles. It dispatches okstra-owned
+worker panes through tmux when possible and degrades to CLI wrappers when tmux is
+unavailable to the lead harness.
+
+  --workspace-root and --okstra-bin are owned by this command.
+`;
+
+const OWNED_FLAGS = new Set(["--workspace-root", "--okstra-bin"]);
+
+function isOwnedFlag(arg) {
+  if (OWNED_FLAGS.has(arg)) return true;
+  return [...OWNED_FLAGS].some((flag) => arg.startsWith(`${flag}=`));
+}
+
+export function buildTeamArgs(args, paths) {
+  return [
+    "--workspace-root", paths.workspace,
+    "--okstra-bin", paths.bin,
+    ...args,
+  ];
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  if (args.length === 0) {
+    process.stdout.write(USAGE);
+    return 2;
+  }
+
+  const forbidden = args.find(isOwnedFlag);
+  if (forbidden) {
+    process.stderr.write(
+      `error: ${forbidden} is set by 'okstra team' itself — remove it from your args\n`,
+    );
+    return 2;
+  }
+
+  const paths = await resolvePaths();
+  const result = await runPythonModule({
+    module: "okstra_ctl.team",
+    args: buildTeamArgs(args, paths),
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/uninstall.mjs

@@ -10,6 +10,7 @@ import {
 const BIN_ENTRYPOINTS = [
   "okstra.sh",
   "okstra-codex-exec.sh",
+  "okstra-claude-exec.sh",
   "okstra-gemini-exec.sh",
   "okstra-trace-cleanup.sh",
   "okstra-team-reconcile.sh",