okstra 0.155.0 → 0.157.0

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

@@ -5,6 +5,17 @@ const USAGE = `okstra worker-liveness — report whether pending workers are sti
 Usage:
   okstra worker-liveness [--team-state <path> --worker <worker-id>]...
                          [--max-idle <seconds>] [--launch-grace <seconds>] [--json]
+  okstra worker-liveness --wait [--team-state <path> --worker <worker-id>]...
+                         [--interval <seconds>] [--timeout <seconds>]
+
+--wait polls until every named worker's persisted resultPath lands (exit 0), one
+          worker probes unhealthy (exit 1), or --timeout passes (exit 2).
+          Defaults: --interval 20, --timeout 2400. Run it as a background
+          command and branch on the exit code. Use this instead of writing a
+          poll loop: both the "is it done" test (the persisted resultPath, not a
+          filename you assemble) and the "is it dead" test live in here, and a
+          hand-written loop re-derives them and gets one wrong. A worker row
+          without a resultPath is refused rather than waited on by guess.
 
 --team-state and --worker select one pending worker. The worker row's
           livenessMode picks the probe: audit-heartbeat reads the in-process
@@ -15,9 +26,10 @@ Usage:
           is reused on re-dispatch, so the previous attempt's last heartbeat is
           not this dispatch's signal.
 
-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.
+Output: JSON { ok, checkedAt, probes[], unhealthy[] }, plus { outcome, pending[],
+waitedSeconds } under --wait. Exit 1 when any worker is stalled or did not
+launch, so a caller can branch on the exit code. Read-only: it reports, it never
+kills or re-dispatches.
 `;
 
 export async function run(args) {

package/src/commands/lifecycle/install.mjs

@@ -8,10 +8,13 @@ import { fileExists } from "../../lib/proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "../../lib/runtime-manifest.mjs";
 import { normalizeRuntimeRequest, resolveRuntime } from "../../lib/runtime-resolver.mjs";
 import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
+import {
+  AGENTS_MANIFEST_REL,
+  SKILLS_MANIFEST_REL,
+} from "../../lib/install-assets.mjs";
 import { renderWorkerAgentDefinitions } from "../../lib/worker-agent-render.mjs";
 
-const SKILLS_MANIFEST_REL = "installed-skills.json";
-const AGENTS_MANIFEST_REL = "installed-agents.json";
+
 const USER_HOME = homedir();
 const CLAUDE_HOME = join(USER_HOME, ".claude");
 const AGENTS_HOME = join(USER_HOME, ".agents");
@@ -236,15 +239,42 @@ async function writeFileAtomic(target, data, mode) {
   await fs.rename(tmp, target);
 }
 
+// Files the destination has and the payload no longer ships. Left in place they
+// are indistinguishable from current code — Python imports whatever is on disk,
+// so a module dropped in release N+1 keeps being importable after the upgrade,
+// and a rename leaves both spellings live at once.
+async function pruneOrphans(srcRoot, dstRoot, opts) {
+  const { dryRun = false } = opts ?? {};
+  if (!(await dirExists(dstRoot))) return 0;
+  let pruned = 0;
+  for await (const dstPath of walkFiles(dstRoot)) {
+    const rel = relative(dstRoot, dstPath);
+    try {
+      await fs.access(join(srcRoot, rel));
+      continue;
+    } catch {
+      // not in the payload → orphan
+    }
+    if (dryRun) {
+      process.stdout.write(`[dry-run] prune ${dstPath}\n`);
+    } else {
+      await fs.rm(dstPath, { force: true });
+    }
+    pruned++;
+  }
+  return pruned;
+}
+
 async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
   const { refresh = false, dryRun = false, mode } = opts ?? {};
   let copied = 0;
   let skipped = 0;
+  let pruned = 0;
   let missingSource = false;
 
   if (!(await dirExists(srcRoot))) {
     missingSource = true;
-    return { copied, skipped, missingSource };
+    return { copied, skipped, pruned, missingSource };
   }
 
   for await (const srcPath of walkFiles(srcRoot)) {
@@ -276,7 +306,8 @@ async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
     copied++;
   }
 
-  return { copied, skipped, missingSource };
+  pruned = await pruneOrphans(srcRoot, dstRoot, { dryRun });
+  return { copied, skipped, pruned, missingSource };
 }
 
 async function ensureSymlink(target, linkPath, opts) {
@@ -970,6 +1001,23 @@ function summarise(label, result, target) {
   );
 }
 
+// `0.156.0` → [0, 156, 0]. Anything else → null, so a caller falls back to the
+// plain inequality test rather than guessing an ordering.
+function parseSemver(value) {
+  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(value ?? "").trim());
+  return match ? match.slice(1, 4).map(Number) : null;
+}
+
+export function installedStampIsNewer(stamp, packageVersion) {
+  const installed = parseSemver(stamp);
+  const running = parseSemver(packageVersion);
+  if (!installed || !running) return false;
+  for (let i = 0; i < 3; i++) {
+    if (installed[i] !== running[i]) return installed[i] > running[i];
+  }
+  return false;
+}
+
 export function parseEnsureInstalledArgs(args) {
   const result = {
     quiet: false,
@@ -1009,6 +1057,23 @@ export async function runEnsureInstalled(args) {
     return 2;
   }
 
+  // A newer install than the package running this check means an upgrade
+  // arrived by another route — `npx -y okstra@latest install`, or an install
+  // from a checkout — while this command still resolves an older payload.
+  // Reinstalling here would quietly DOWNGRADE the user's runtime, and every
+  // skill preflight calls this, so the downgrade lands on the next command
+  // after the upgrade. Refuse and say so; an explicit `okstra install` is
+  // still honoured, because that one is the user's own decision.
+  if (installedStampIsNewer(paths.version, paths.package)) {
+    process.stderr.write(
+      `okstra: installed runtime ${paths.version} is newer than this package ` +
+        `(${paths.package}) — skipping auto-install so it is not downgraded. ` +
+        `Run 'okstra install' explicitly to force this package's payload, or ` +
+        `update the okstra package itself.\n`,
+    );
+    return 0;
+  }
+
   const reasons = [];
   if (!paths.version) reasons.push("no version stamp");
   else if (paths.version !== paths.package) {

package/src/commands/lifecycle/uninstall.mjs

@@ -7,6 +7,12 @@ import {
   runtimeManifestIncludesClaudeAssets,
 } from "../../lib/runtime-manifest.mjs";
 import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
+import {
+  AGENTS_MANIFEST_REL,
+  INSTALLED_FILES,
+  INSTALLED_TREES,
+  SKILLS_MANIFEST_REL,
+} from "../../lib/install-assets.mjs";
 
 // Manifest-less uninstall must clean out every okstra skill directory — the
 // live names AND every former/renamed one. Both sets are the single source of
@@ -34,8 +40,7 @@ const FALLBACK_SKILL_ROOTS = [
   CLAUDE_SKILLS_DIR,
   AGENTS_SKILLS_DIR,
 ];
-const SKILLS_MANIFEST_REL = "installed-skills.json";
-const AGENTS_MANIFEST_REL = "installed-agents.json";
+
 
 const USAGE = `okstra uninstall — remove installed runtime and okstra skills
 
@@ -147,21 +152,16 @@ export async function runUninstall(args) {
     process.stdout.write(`uninstalling okstra runtime\n`);
     process.stdout.write(`  home: ${paths.home}\n`);
   }
-  await removePath(paths.pythonpath, opts);
-  // lib/validators — installed wholesale by copy mode (runtime/validators).
-  // Without removing it, `lib` stays non-empty so the rmdir below is skipped and
-  // a stale validator survives uninstall → reinstall, diverging from the current
-  // template's section schema (observed: a pre-renumber `## 4.5 Stage Map`
-  // validator outliving every later install).
-  await removePath(join(paths.home, "lib", "validators"), opts);
-  // bin/ tree — install copies the whole runtime/bin payload (entrypoints +
-  // bin/lib helpers) in copy mode, so a per-name list always drifts behind
-  // additions (e.g. okstra-inject-report-index.py, okstra-spawn-followups.sh).
-  // Remove the directory wholesale, matching how install populates it; nothing
-  // under ~/.okstra/bin is user data.
-  await removePath(paths.bin, opts);
-  // Clean now-empty lib parent (best-effort) — pythonpath + validators were the
-  // only okstra-owned children.
+  // Every tree the install writes, read from the list install itself copies
+  // from. A per-name list here drifts behind additions the moment one lands on
+  // the install side only — which is how a stale validator, a stale schema and
+  // a stale prompts tree each survived uninstall→reinstall in turn, one bug
+  // report at a time.
+  for (const tree of INSTALLED_TREES) {
+    await removePath(join(paths.home, ...tree.to), opts);
+  }
+  // Clean now-empty lib parent (best-effort) — the trees above were the only
+  // okstra-owned children.
   const libDir = join(paths.home, "lib");
   if (await pathExists(libDir)) {
     try {
@@ -175,15 +175,6 @@ export async function runUninstall(args) {
     }
   }
 
-  // schemas/ tree — installed by copy mode (runtime/schemas). Older uninstall
-  // never removed it, leaving a stale final-report schema behind.
-  await removePath(join(paths.home, "schemas"), opts);
-
-  // prompts/ tree — installed by copy mode (runtime/prompts): lead contracts
-  // + coding-preflight resource pack. Remove so an upgrade never serves stale
-  // operating contracts.
-  await removePath(join(paths.home, "prompts"), opts);
-
   // Remove the skills we own. Manifest v2 records every target root; legacy
   // manifests fall back to Claude-only names when the runtime manifest says
   // Claude assets may have been installed.
@@ -210,20 +201,15 @@ export async function runUninstall(args) {
   for (const name of agentNames) {
     await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
   }
-  await removePath(join(paths.home, AGENTS_MANIFEST_REL), opts);
-
-  // templates/ tree — installed wholesale by copy mode (runtime/templates),
-  // including the seeded settings.local.json sidecar. Remove the whole tree so
-  // an upgrade/reinstall never serves a stale report.css / *.template.md.
-  await removePath(join(paths.home, "templates"), opts);
   // Per-project <PROJECT>/.claude/settings.local.json symlinks are NOT removed
   // here — uninstall is machine-level and does not know which projects opted
   // in. They will dangle until the user removes them manually or re-runs
   // okstra install + okstra setup.
 
-  await removePath(join(paths.home, "version"), opts);
-  await removePath(join(paths.home, "dev-link"), opts);
-  await removePath(join(paths.home, RUNTIMES_MANIFEST_REL), opts);
+  // Stamps and manifests, last: the skill/agent removal above reads two of them.
+  for (const name of INSTALLED_FILES) {
+    await removePath(join(paths.home, name), opts);
+  }
 
   if (!opts.quiet) {
     process.stdout.write("done. user data preserved (recent.jsonl, projects/, archive/, ...).\n");

package/src/lib/install-assets.mjs

@@ -0,0 +1,37 @@
+// What `okstra install` puts under ~/.okstra, as one list.
+//
+// install and uninstall each used to carry their own copy of this, so an asset
+// added to one and not the other survived every uninstall — `installed-from`
+// sat in real homes for months that way, written by a version that no longer
+// exists and removed by nothing.
+//
+// Skills and agents are NOT here: they install outside ~/.okstra (host skill
+// homes, ~/.claude/agents) and are tracked per-target by their own manifests.
+
+// runtime/<from> is mirrored to ~/.okstra/<to...>. Mirrored, not merged: a file
+// the payload no longer ships is removed from the install, because Python
+// imports whatever is on disk and a stale module outlives the release that
+// dropped it.
+export const INSTALLED_TREES = [
+  { from: "python", to: ["lib", "python"] },
+  { from: "bin", to: ["bin"] },
+  { from: "templates", to: ["templates"] },
+  { from: "schemas", to: ["schemas"] },
+  { from: "validators", to: ["lib", "validators"] },
+  { from: "prompts", to: ["prompts"] },
+];
+
+// Single files the install stamps into ~/.okstra. Every one is removed by
+// uninstall; `installed-from` is written by no current code path and is listed
+// so that homes carrying it from an older version still get cleaned.
+export const INSTALLED_FILES = [
+  "version",
+  "dev-link",
+  "installed-from",
+  "installed-skills.json",
+  "installed-agents.json",
+  "installed-runtimes.json",
+];
+
+export const SKILLS_MANIFEST_REL = "installed-skills.json";
+export const AGENTS_MANIFEST_REL = "installed-agents.json";