okstra 0.14.2 → 0.16.0

package/bin/okstra

@@ -9,6 +9,11 @@ const COMMANDS = new Map([
   ["doctor", () => import("../src/doctor.mjs").then((m) => m.run)],
   ["setup", () => import("../src/setup.mjs").then((m) => m.run)],
   ["check-project", () => import("../src/check-project.mjs").then((m) => m.run)],
+  ["task-list", () => import("../src/task-list.mjs").then((m) => m.run)],
+  ["task-show", () => import("../src/task-show.mjs").then((m) => m.run)],
+  ["worktree-lookup", () => import("../src/worktree-lookup.mjs").then((m) => m.run)],
+  ["plan-validate", () => import("../src/plan-validate.mjs").then((m) => m.run)],
+  ["render-bundle", () => import("../src/render-bundle.mjs").then((m) => m.run)],
 ]);
 
 const USAGE = `okstra — multi-agent cross-verification orchestrator for Claude Code
@@ -37,6 +42,14 @@ Admin commands:
   check-project          Verify the current project has been registered with setup
   paths                  Print runtime paths (workspace/agents/pythonpath/bin/home/version)
 
+Introspection commands (JSON output, used by skills to avoid python heredocs):
+  task-list              List tasks registered in the current project
+  task-show              Summarize a task's manifest + workflow phase state
+  worktree-lookup        Look up registered worktree for a task-key
+  plan-validate          Check an approved-plan file for the approval marker
+  render-bundle          Preview prepare_task_bundle() output (forwards to
+                         python3 -m okstra_ctl.run --render-only)
+
 Global options:
   --version              Print okstra version and exit
   --help                 Print this help

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "okstra",
-  "version": "0.14.2",
+  "version": "0.16.0",
   "description": "Multi-agent cross-verification orchestrator runtime + Claude Code skills.",
   "license": "MIT",
   "author": "devonshin",

package/runtime/BUILD.json

@@ -1,5 +1,5 @@
 {
-  "package": "0.14.2",
-  "builtAt": "2026-05-13T03:43:46.461Z",
+  "package": "0.16.0",
+  "builtAt": "2026-05-13T06:50:20.316Z",
   "repoRoot": "/home/runner/work/okstra/okstra"
 }

package/runtime/skills/okstra-run/SKILL.md

@@ -75,35 +75,23 @@ After Step 0 the following are guaranteed:
 
 ## Step 1: Resolve PROJECT_ROOT and projectId
 
+Prefer `$OKSTRA_PROJECT_INFO` from Step 0 — it already carries `{ok, projectRoot, projectJsonPath, projectId}`. Only re-resolve when that JSON's `ok` is false (cwd outside an okstra project):
+
 ```bash
-python3 - <<'PY'
-import sys, json
-from okstra_project import resolve_project_root, ResolverError
-try:
-    pr = resolve_project_root(explicit_root="", cwd=".")
-except ResolverError as e:
-    print(f"FAIL\t{e}"); raise SystemExit(0)
-print(f"OK\t{pr}")
-PY
+okstra check-project --cwd "$(pwd)"
 ```
 
-- If `OK`: read `<PROJECT_ROOT>/.project-docs/okstra/project.json` and extract `projectId`.
-- If `FAIL`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun the resolver with `explicit_root=<their input>`.
+- If `ok: true`: read `projectRoot` and `projectId` from the JSON.
+- If `ok: false`: ask the user (`AskUserQuestion`, free text) for an absolute project-root path; rerun with `okstra check-project --cwd <their input>`.
 
 ## Step 2: Choose task — existing vs new
 
 ```bash
-python3 -c "
-import json, sys
-from pathlib import Path
-from okstra_project import list_project_tasks, read_latest_task
-pr = Path(sys.argv[1])
-tasks = list_project_tasks(pr)
-latest = read_latest_task(pr)
-print(json.dumps({'tasks': tasks, 'latest': latest}))
-" "$PROJECT_ROOT"
+okstra task-list --project "$PROJECT_ROOT"
 ```
 
+Output is JSON `{ok, projectRoot, tasks: [...], latest: {...}|null}`.
+
 Use `AskUserQuestion`:
 
 - **Label**: "Which task?"
@@ -151,21 +139,12 @@ silently inherits an unrelated branch you happen to be checked out on.
 First, decide whether to ask:
 
 ```bash
-python3 - <<PY
-import sys
-from pathlib import Path
-sys.path.insert(0, "$OKSTRA_PYTHONPATH".split(":")[0])
-from okstra_ctl import worktree_registry
-from okstra_ctl.ids import _safe_fs_segment
-entry = worktree_registry.lookup(
-    _safe_fs_segment("<project-id>"),
-    _safe_fs_segment("<task-group>"),
-    _safe_fs_segment("<task-id>"),
-)
-print("REUSE" if (entry and entry.status == "active") else "ASK")
-PY
+okstra worktree-lookup "<project-id>" "<task-group>" "<task-id>"
 ```
 
+Output JSON: `{ok: true, entry: null}` means no active worktree → **ASK**. A
+non-null `entry` with `status: "active"` → **REUSE**.
+
 - `REUSE` → the registered worktree is reused; set `base_ref=""` and skip the
   question (the registered base is authoritative).
 - `ASK` → this is the first phase for this task-key. Continue.
@@ -235,7 +214,7 @@ For prompts whose target worker is NOT in the resolved workers list (after overr
 
 ## Step 6.5: Confirm selections before rendering
 
-Before calling `prepare_task_bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
+Before invoking `okstra render-bundle`, echo the resolved selections back to the user in a compact block so they can verify what will be passed. Show the **effective** values, not the raw input — i.e. when the user left a field blank, display `default` (and where known, the actual default such as `opus` / `sonnet`). Example for an `implementation` run:
 
 ```
 선택 확인:
@@ -255,50 +234,40 @@ Before calling `prepare_task_bundle`, echo the resolved selections back to the u
 
 Then `AskUserQuestion`: `"이대로 진행할까요?"` with options `Proceed` / `Edit`. On `Edit`, return to the relevant Step 6 sub-prompt.
 
-## Step 7: Call `prepare_task_bundle` directly
+## Step 7: Call `okstra render-bundle`
 
-This is the single line that materializes the entire task bundle. **Pass `render_only=True`** — the current claude session itself takes over as lead; we do not exec a new claude.
+This is the single command that materializes the entire task bundle. The
+subcommand auto-supplies `--workspace-root` (from `okstra paths --field
+workspace`) and forces `--render-only`, so the current claude session itself
+takes over as lead — no new claude is spawned.
 
 ```bash
-python3 - <<PY
-import os
-from pathlib import Path
-from okstra_ctl.run import PrepareInputs, prepare_task_bundle
-from okstra_ctl.path_resolve import resolve_user_file
-
-project_root = Path("<project-root>")
-brief_abs = resolve_user_file("<brief-path-from-user>", project_root)
-clarification_abs = resolve_user_file("<clarification-or-empty>", project_root) if "<clarification-or-empty>" else None
-
-out = prepare_task_bundle(PrepareInputs(
-    workspace_root=Path(os.environ["OKSTRA_WORKSPACE"]),
-    project_root=project_root,
-    project_id="<project-id>",
-    task_group="<task-group>",
-    task_id="<task-id>",
-    task_type="<task-type>",
-    brief_path=brief_abs,
-    directive="<directive or empty>",
-    workers_override="<comma-separated worker list, or empty for profile default; MUST be empty for implementation>",
-    lead_model="...", claude_model="...", codex_model="...",
-    gemini_model="...", report_writer_model="...",
-    related_tasks_raw="...",
-    executor="<claude|codex|gemini or empty>",  # implementation only; empty → default (claude / OKSTRA_DEFAULT_EXECUTOR)
-    base_ref="<chosen-ref-from-step-4.6 or empty when reusing existing worktree>",
-    approved_plan_path="<approved-plan-or-empty>",
-    clarification_response_path=str(clarification_abs) if clarification_abs else "",
-    render_only=True,
-))
-
-# Print key paths so the next step can read them.
-ctx = out.ctx
-print("TASK_ROOT", ctx["TASK_ROOT"])
-print("INSTRUCTION_SET_DIR", ctx["INSTRUCTION_SET_DIR"])
-print("LEAD_PROMPT", str(Path(ctx["INSTRUCTION_SET_DIR"]) / "claude-execution-prompt.md"))
-PY
+okstra render-bundle \
+  --project-root "<project-root>" \
+  --project-id "<project-id>" \
+  --task-group "<task-group>" \
+  --task-id "<task-id>" \
+  --task-type "<task-type>" \
+  --task-brief "<brief-path-from-user>" \
+  --executor "<claude|codex|gemini or empty for default>" \
+  --approved-plan "<approved-plan-or-empty>" \
+  --base-ref "<chosen-ref-from-step-4.6 or empty when reusing existing worktree>" \
+  --workers "<comma-separated worker list, or empty for profile default; MUST be empty for implementation>" \
+  --directive "<directive or empty>" \
+  --lead-model "..." --claude-model "..." --codex-model "..." \
+  --gemini-model "..." --report-writer-model "..." \
+  --related-tasks "..." \
+  --clarification-response "<clarification-or-empty>"
 ```
 
-The python function is mutex-protected (`~/.okstra/.locks/<task-key>.lock`), writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
+Stdout prints `okstra task root:`, `okstra instruction-set:`, and the full
+rendered lead-prompt text (because `--render-only` is on). Parse the labelled
+lines to get `TASK_ROOT`, `INSTRUCTION_SET_DIR`, and from there the
+`claude-execution-prompt.md` path used by Step 8.
+
+The python function underneath is mutex-protected (`~/.okstra/.locks/<task-key>.lock`),
+writes `run-context-*.json` + `run-inputs-*.json` + all manifests + discovery
+files, and registers the run in `~/.okstra/recent.jsonl` with status `prepared`.
 
 ## Step 8: Take over as Claude lead
 
@@ -327,7 +296,7 @@ Inform the user with one short line:
 |---|---|---|
 | `okstra runtime missing: ...` | First run on this machine, or stale install | `npx okstra@latest install` once, retry. |
 | `OKSTRA_PYTHONPATH unbound` / `ModuleNotFoundError: okstra_project` | Step 0 was skipped or env vars dropped | Re-run Step 0; never invoke python without exporting `PYTHONPATH=$OKSTRA_PYTHONPATH`. |
-| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2; show available keys from `list_project_tasks` |
+| `task root not found for <key>` | catalog entry stale or task-key typo | Re-run Step 2 (`okstra task-list`) and show available keys |
 | `PROJECT_ROOT 를 해석할 수 없습니다` | cwd outside okstra project, no git toplevel | Ask user for absolute path |
 | `approved plan has no recognised user-approval marker` | `implementation` without proper approval | Ask user to add `APPROVED` to the plan, or pick a different task-type |
 | `task brief not found` | brief-path doesn't resolve relative to cwd or project-root | Re-ask Step 5 |

package/runtime/skills/okstra-setup/SKILL.md

@@ -72,19 +72,12 @@ them from the env vars.
 ## Step 3: Resolve PROJECT_ROOT
 
 ```bash
-python3 - <<'PY'
-from okstra_project import resolve_project_root, ResolverError
-try:
-    pr = resolve_project_root(explicit_root="", cwd=".")
-    print(f"OK\t{pr}")
-except ResolverError as e:
-    print(f"FAIL\t{e}")
-PY
+okstra check-project --cwd "$(pwd)"
 ```
 
-- `OK` line → use that as `PROJECT_ROOT`.
-- `FAIL` line → ask the user (`AskUserQuestion`, free text) for an absolute
-  project root. Re-run with `explicit_root=<their answer>`.
+The JSON includes `projectRoot` on success. On failure (`ok: false`,
+`stage: "resolve"`) ask the user (`AskUserQuestion`, free text) for an
+absolute project root and rerun with `--cwd <their answer>`.
 
 ## Step 4: Inspect or create `project.json`
 
@@ -108,12 +101,7 @@ If the file does NOT exist, ask via `AskUserQuestion`:
 Then create the file:
 
 ```bash
-python3 - <<PY
-from pathlib import Path
-from okstra_project import upsert_project_json
-result = upsert_project_json(Path("$PROJECT_ROOT"), "$PROJECT_ID")
-print(result)
-PY
+okstra setup --yes --project-root "$PROJECT_ROOT" --project-id "$PROJECT_ID"
 ```
 
 ## Step 4.5 (optional): customise worktree sync dirs

package/runtime/templates/reports/settings.template.json

@@ -46,6 +46,8 @@
       "Bash(pytest:*)",
       "Bash(bash:*)",
       "Bash(sh:*)",
+      "Bash(eval:*)",
+      "Bash(cd:*)",
       "Bash(printf:*)",
       "Bash(echo:*)",
       "Bash(export:*)",
@@ -57,6 +59,7 @@
       "Bash(false)",
       "Bash(codex:*)",
       "Bash(codex exec:*)",
+      "Bash(okstra:*)",
       "Bash($HOME/.okstra/bin/okstra-codex-exec.sh:*)",
       "Bash(gemini:*)",
       "Bash($HOME/.okstra/bin/okstra-gemini-exec.sh:*)",

package/src/_python-helper.mjs

@@ -0,0 +1,42 @@
+import { spawn } from "node:child_process";
+import { resolvePaths } from "./paths.mjs";
+
+export async function runPythonSnippet({ script, args = [], extraEnv = {} }) {
+  const paths = await resolvePaths();
+  return new Promise((resolve) => {
+    const child = spawn("python3", ["-c", script, ...args], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+export async function runPythonModule({ module, args = [], extraEnv = {}, stdio = "inherit-stdout" }) {
+  const paths = await resolvePaths();
+  return new Promise((resolve) => {
+    const child = spawn("python3", ["-m", module, ...args], {
+      stdio: stdio === "capture" ? ["ignore", "pipe", "pipe"] : ["ignore", "inherit", "inherit"],
+      env: { ...process.env, PYTHONPATH: paths.pythonpath, ...extraEnv },
+    });
+    let stdout = "";
+    let stderr = "";
+    if (stdio === "capture") {
+      child.stdout.on("data", (b) => (stdout += b.toString()));
+      child.stderr.on("data", (b) => (stderr += b.toString()));
+    }
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+export function emitJsonError({ stage, reason, extra = {} }) {
+  process.stdout.write(
+    JSON.stringify({ ok: false, stage, reason, ...extra }, null, 2) + "\n",
+  );
+}

package/src/plan-validate.mjs

@@ -0,0 +1,68 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra plan-validate — verify an approved-plan file has a recognised approval marker
+
+Usage:
+  okstra plan-validate <plan-path>
+
+Output: JSON { ok: true, planPath } on success.
+On failure: { ok: false, reason } with non-zero exit code.
+
+Replaces the \`from okstra_ctl.run import _validate_approved_plan\` heredoc
+pattern. Use this in flows that need to confirm a plan was approved
+without invoking the full prepare_task_bundle pipeline.
+`;
+
+function parseArgs(args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const unknown = args.filter((a) => a.startsWith("--"));
+  if (unknown.length) throw new Error(`unknown argument '${unknown[0]}'`);
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <plan-path>");
+  }
+  return { planPath: positional[0] };
+}
+
+const SCRIPT = `
+import json, sys
+from okstra_ctl.run import _validate_approved_plan, PrepareError
+
+path = sys.argv[1]
+try:
+    _validate_approved_plan(path)
+except PrepareError as e:
+    print(json.dumps({"ok": False, "stage": "validation", "reason": str(e), "planPath": path}))
+    sys.exit(1)
+
+print(json.dumps({"ok": True, "planPath": path}))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.planPath],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/render-bundle.mjs

@@ -0,0 +1,60 @@
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra render-bundle — preview the task bundle without launching claude
+
+This is a thin shim over \`python3 -m okstra_ctl.run\` that forces
+\`--render-only\`. Use it to preview where prepare_task_bundle() would
+materialize files (INSTRUCTION_SET_DIR, RUN_DIR, lead prompt path,
+final report template path, etc.) for a given task/phase, without
+actually creating the run-state or spawning the launcher.
+
+Usage:
+  okstra render-bundle --project-root <dir> --project-id <id> \\
+    --task-group <tg> --task-id <tid> --task-type <type> \\
+    --task-brief <path-or-rel> [--executor <name>] \\
+    [--approved-plan <path>] [--workers <list>] [--directive <text>] \\
+    [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
+    [--gemini-model <m>] [--report-writer-model <m>] \\
+    [--related-tasks <list>] [--base-ref <ref>] \\
+    [--clarification-response <path>] [--work-category <cat>]
+
+All flags pass through unchanged to \`python3 -m okstra_ctl.run\`. The
+shim auto-supplies \`--workspace-root\` (from \`okstra paths --field workspace\`)
+and \`--render-only\`, so callers do not need to set those.
+
+Replaces the long \`from okstra_ctl.run import PrepareInputs,
+prepare_task_bundle\` heredoc pattern.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const paths = await resolvePaths();
+
+  // Callers should not pass these; we own them.
+  const forbidden = ["--workspace-root", "--render-only"];
+  for (const f of forbidden) {
+    if (args.includes(f)) {
+      process.stderr.write(
+        `error: ${f} is set by 'okstra render-bundle' itself — remove it from your args\n`,
+      );
+      return 2;
+    }
+  }
+
+  const finalArgs = [
+    "--workspace-root", paths.workspace,
+    "--render-only",
+    ...args,
+  ];
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: finalArgs,
+    stdio: "inherit-stdout",
+  });
+  return result.code ?? 0;
+}

package/src/task-list.mjs

@@ -0,0 +1,86 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra task-list — list okstra tasks registered in this project
+
+Usage:
+  okstra task-list                   Resolve PROJECT_ROOT from cwd, list tasks
+  okstra task-list --cwd <dir>       Start resolution from <dir> instead of cwd
+  okstra task-list --project <dir>   Use <dir> directly as PROJECT_ROOT
+
+Output: JSON { ok, projectRoot, tasks: [...], latest: {...}|null }.
+
+Replaces the common pattern of loading okstra_project and calling
+list_project_tasks + read_latest_task from a python heredoc.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "" };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else {
+      throw new Error(`unknown argument '${a}'`);
+    }
+  }
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import (
+    list_project_tasks, read_latest_task,
+    resolve_project_root, ResolverError,
+)
+
+explicit = sys.argv[1]
+cwd = sys.argv[2]
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+pr_path = Path(pr)
+print(json.dumps({
+    "ok": True,
+    "projectRoot": str(pr_path),
+    "tasks": list_project_tasks(pr_path),
+    "latest": read_latest_task(pr_path),
+}, default=str))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/task-show.mjs

@@ -0,0 +1,120 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra task-show — summarize a task's manifest and workflow state
+
+Usage:
+  okstra task-show <task-key>                  task-key is project-id:task-group:task-id
+  okstra task-show <task-key> --cwd <dir>      Resolve PROJECT_ROOT from <dir>
+  okstra task-show <task-key> --project <dir>  Use <dir> directly as PROJECT_ROOT
+
+Output: JSON with taskKey, taskType, taskRoot, brief path, workflow phases,
+artifacts, modelAssignments, latestRunPath. Replaces the
+\`cat task-manifest.json | python3 -c ...\` summarization pattern.
+`;
+
+function parseArgs(args) {
+  const opts = { cwd: process.cwd(), projectRoot: "", taskKey: "" };
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === "--cwd") {
+      opts.cwd = args[++i];
+      if (!opts.cwd) throw new Error("--cwd requires a path");
+    } else if (a === "--project") {
+      opts.projectRoot = args[++i];
+      if (!opts.projectRoot) throw new Error("--project requires a path");
+    } else if (a.startsWith("--")) {
+      throw new Error(`unknown argument '${a}'`);
+    } else {
+      positional.push(a);
+    }
+  }
+  if (positional.length !== 1) {
+    throw new Error("expected exactly one positional argument: <task-key>");
+  }
+  opts.taskKey = positional[0];
+  return opts;
+}
+
+const SCRIPT = `
+import json, sys
+from pathlib import Path
+from okstra_project import (
+    resolve_project_root, find_task_root, read_task_manifest,
+    ResolverError,
+)
+
+explicit = sys.argv[1]
+cwd = sys.argv[2]
+task_key = sys.argv[3]
+
+try:
+    pr = resolve_project_root(explicit_root=explicit, cwd=cwd)
+except ResolverError as e:
+    print(json.dumps({"ok": False, "stage": "resolve", "reason": str(e)}))
+    sys.exit(2)
+
+pr_path = Path(pr)
+task_root = find_task_root(pr_path, task_key)
+if task_root is None:
+    print(json.dumps({"ok": False, "stage": "task_root_missing", "reason": f"no task root for {task_key}"}))
+    sys.exit(1)
+
+manifest = read_task_manifest(task_root)
+if manifest is None:
+    print(json.dumps({"ok": False, "stage": "manifest_missing", "reason": f"task-manifest.json missing in {task_root}"}))
+    sys.exit(1)
+
+wf = manifest.get("workflow", {}) or {}
+out = {
+    "ok": True,
+    "projectRoot": str(pr_path),
+    "taskKey": manifest.get("taskKey"),
+    "taskType": manifest.get("taskType"),
+    "taskRoot": str(task_root),
+    "taskBriefPath": manifest.get("taskBriefPath"),
+    "workflow": {
+        "currentPhase": wf.get("currentPhase"),
+        "currentPhaseState": wf.get("currentPhaseState"),
+        "lastCompletedPhase": wf.get("lastCompletedPhase"),
+        "nextRecommendedPhase": wf.get("nextRecommendedPhase"),
+        "routingStatus": wf.get("routingStatus"),
+        "phaseStates": wf.get("phaseStates"),
+    },
+    "resultContract": manifest.get("resultContract"),
+    "artifacts": manifest.get("artifacts"),
+    "modelAssignments": manifest.get("modelAssignments"),
+    "latestRunPath": manifest.get("latestRunPath"),
+}
+print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectRoot, opts.cwd, opts.taskKey],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}

package/src/worktree-lookup.mjs

@@ -0,0 +1,91 @@
+import { runPythonSnippet, emitJsonError } from "./_python-helper.mjs";
+
+const USAGE = `okstra worktree-lookup — look up registered worktree for a task-key
+
+Usage:
+  okstra worktree-lookup <project-id> <task-group> <task-id>
+
+The three identifiers are slugified by the runtime before lookup, so
+case/whitespace variants are tolerated.
+
+Output: JSON with the registry entry (worktreePath, branch, baseRef,
+status, lastPhase, createdAt). Emits {"ok": true, "entry": null} when
+the task-key has no active worktree.
+
+Replaces the okstra_ctl.worktree_registry.lookup() heredoc pattern.
+`;
+
+function parseArgs(args) {
+  const positional = args.filter((a) => !a.startsWith("--"));
+  const unknown = args.filter((a) => a.startsWith("--"));
+  if (unknown.length) throw new Error(`unknown argument '${unknown[0]}'`);
+  if (positional.length !== 3) {
+    throw new Error("expected exactly three positional arguments: <project-id> <task-group> <task-id>");
+  }
+  return { projectId: positional[0], taskGroup: positional[1], taskId: positional[2] };
+}
+
+const SCRIPT = `
+import json, sys
+from dataclasses import asdict
+from okstra_ctl import worktree_registry
+from okstra_ctl.ids import _safe_fs_segment
+
+pid, tg, tid = sys.argv[1], sys.argv[2], sys.argv[3]
+entry = worktree_registry.lookup(
+    _safe_fs_segment(pid),
+    _safe_fs_segment(tg),
+    _safe_fs_segment(tid),
+)
+if entry is None:
+    print(json.dumps({"ok": True, "entry": None}))
+else:
+    d = asdict(entry)
+    # rename for camelCase API symmetry
+    out = {
+        "ok": True,
+        "entry": {
+            "taskKey": d.get("task_key"),
+            "projectId": d.get("project_id"),
+            "taskGroup": d.get("task_group"),
+            "taskId": d.get("task_id"),
+            "worktreePath": d.get("worktree_path"),
+            "branch": d.get("branch"),
+            "baseRef": d.get("base_ref"),
+            "createdAt": d.get("created_at"),
+            "lastPhase": d.get("last_phase"),
+            "status": d.get("status"),
+        },
+    }
+    print(json.dumps(out, ensure_ascii=False, default=str, indent=2))
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  let opts;
+  try {
+    opts = parseArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n\n${USAGE}`);
+    return 2;
+  }
+
+  const result = await runPythonSnippet({
+    script: SCRIPT,
+    args: [opts.projectId, opts.taskGroup, opts.taskId],
+  });
+
+  if (result.code !== 0 && !result.stdout.trim()) {
+    emitJsonError({
+      stage: "python",
+      reason: `python invocation failed: ${result.stderr.trim() || "no output"}`,
+    });
+    return 1;
+  }
+
+  process.stdout.write(result.stdout);
+  return result.code === 0 ? 0 : result.code;
+}