okstra 0.125.5 → 0.127.0

package/src/commands/inspect/worker-liveness.mjs

@@ -0,0 +1,31 @@
+import { runPythonModule } from "../../lib/python-helper.mjs";
+
+const USAGE = `okstra worker-liveness — report whether pending workers are still alive
+
+Usage:
+  okstra worker-liveness [--audit <path>]... [--prompt <path>]...
+                         [--max-idle <seconds>] [--launch-grace <seconds>] [--json]
+
+--audit   a claude-worker audit sidecar; stale past the heartbeat cadence means
+          the in-process worker hung.
+--prompt  a CLI-wrapper prompt-history path; no sibling .log or .status.json
+          past the launch grace means the wrapper never started.
+
+Output: JSON { ok, checkedAt, probes[], unhealthy[] }. Exit 1 when any worker is
+stalled or did not launch, so a poll loop can branch on the exit code. Read-only:
+it reports, it never kills or re-dispatches.
+`;
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const result = await runPythonModule({
+    module: "okstra_ctl.worker_liveness",
+    args,
+    stdio: "inherit-stdout",
+  });
+  return result.code;
+}

package/src/commands/lifecycle/preflight.mjs

@@ -1,5 +1,8 @@
 import { checkProject } from "./check-project.mjs";
 import { runEnsureInstalled } from "./install.mjs";
+import { missingHelperScripts } from "../../lib/helper-scripts.mjs";
+import { resolveInstalledScript } from "../../lib/python-helper.mjs";
+import { resolvePaths } from "../../lib/paths.mjs";
 
 const USAGE = `okstra preflight — one-call skill preflight (ensure-installed + check-project)
 
@@ -11,8 +14,9 @@ verifies the target project has .okstra/project.json. Prints one JSON object:
 
   ok: true   {ok, projectRoot, projectJsonPath, projectId}
   ok: false  {ok, stage, reason, ...}
-             stage: install | resolve | project_json_missing |
-                    project_json_invalid | python | parse
+             stage: install | helper_scripts_missing | resolve |
+                    project_json_missing | project_json_invalid |
+                    python | parse
 
 Options:
   --runtime <name>   Runtime whose assets must be present (e.g. claude-code);
@@ -48,6 +52,12 @@ function emit(payload) {
   process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
 }
 
+// A BLOCKING lead step calls these mid-run; resolving them here turns a stale
+// install into an up-front failure instead of a dead end hours into a run.
+async function findMissingHelperScripts() {
+  return missingHelperScripts(await resolvePaths(), resolveInstalledScript);
+}
+
 export async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -76,6 +86,19 @@ export async function run(args) {
     return installCode === 2 ? 2 : 1;
   }
 
+  const missingHelpers = await findMissingHelperScripts();
+  if (missingHelpers.length > 0) {
+    emit({
+      ok: false,
+      stage: "helper_scripts_missing",
+      missingHelpers,
+      reason:
+        `${missingHelpers.length} helper script(s) a lead prompt can call are not ` +
+        "installed — run 'okstra install' to repair before starting a run.",
+    });
+    return 1;
+  }
+
   const { code, payload } = await checkProject({ cwd: opts.cwd });
   emit(payload);
   return code;

package/src/lib/helper-scripts.mjs

@@ -0,0 +1,23 @@
+// Single source of truth for the python helper scripts that `okstra <cmd>`
+// subcommands front through runInstalledScript(). Preflight asserts every one
+// of them resolves under ~/.okstra/bin so a stale install fails at the cheap
+// environment gate instead of at the blocking lead step that calls it mid-run.
+// A contract test keeps this list in step with the `scriptName:` literals in
+// src/commands/**.
+
+export const HELPER_SCRIPT_NAMES = Object.freeze([
+  "okstra-error-log.py",
+  "okstra-incremental-carry.py",
+  "okstra-incremental-scope.py",
+  "okstra-inject-report-index.py",
+  "okstra-render-final-report.py",
+  "okstra-render-report-views.py",
+  "okstra-spawn-followups.py",
+  "okstra-token-usage.py",
+]);
+
+// `resolve` is the same resolver the wrappers call, so preflight cannot pass a
+// script the dispatch path would then fail to find.
+export function missingHelperScripts(paths, resolve) {
+  return HELPER_SCRIPT_NAMES.filter((name) => !resolve(paths, name));
+}

package/src/lib/python-helper.mjs

@@ -4,7 +4,7 @@ import { join, resolve as resolvePath } from "node:path";
 import { fileURLToPath } from "node:url";
 import { buildPythonpath, resolvePaths } from "./paths.mjs";
 
-function resolveInstalledScript(paths, scriptName) {
+export function resolveInstalledScript(paths, scriptName) {
   // Prefer the installed copy under ~/.okstra/bin (what production users run);
   // fall back to the in-repo source when invoked from a checkout that has not
   // been installed (dev / CI).