okstra 0.76.0 → 0.78.0

package/src/install.mjs

@@ -5,6 +5,7 @@ import { join, relative, resolve as resolveAbs } from "node:path";
 import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists } from "./_proc.mjs";
+import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
@@ -20,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",
@@ -36,6 +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|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.
@@ -50,6 +53,7 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
   ${"$HOME"}/.claude/skills/<name> <- runtime/skills/<name>   (per skill)
   ${"$HOME"}/.claude/agents/<worker>.md <- runtime/agents/workers/<worker>.md
+  ${"$HOME"}/.okstra/installed-runtimes.json <- manifest of installed runtime adapters
   ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
   ${"$HOME"}/.okstra/installed-agents.json   <- manifest of installed workers
   ${"$HOME"}/.okstra/version       <- installed package version stamp
@@ -78,11 +82,37 @@ 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|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", "external", "all"]);
+
+export function runtimeIncludesClaudeAssets(runtime) {
+  return runtime === "claude-code" || runtime === "all";
+}
+
+function readRuntimeFlag(args, index) {
+  const arg = args[index];
+  if (arg.startsWith("--runtime=")) {
+    return { value: arg.slice("--runtime=".length), nextIndex: index };
+  }
+  const next = args[index + 1];
+  if (!next || next.startsWith("--")) {
+    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, external, all)`);
+  }
+  return value;
+}
+
 async function hashFile(path) {
   const buf = await fs.readFile(path);
   return createHash("sha256").update(buf).digest("hex");
@@ -223,7 +253,7 @@ async function ensureSymlink(target, linkPath, opts) {
 }
 
 async function installLinkMode(repoPath, paths, opts) {
-  const { dryRun, quiet } = opts;
+  const { dryRun, quiet, runtime } = opts;
   const repoAbs = resolveAbs(repoPath);
 
   if (!(await dirExists(repoAbs))) {
@@ -240,6 +270,7 @@ async function installLinkMode(repoPath, paths, opts) {
 
   if (!quiet) {
     process.stdout.write(`installing okstra runtime in LINK mode (package ${paths.package})\n`);
+    process.stdout.write(`  runtime: ${runtime}\n`);
     process.stdout.write(`  repo:   ${repoAbs}\n`);
     process.stdout.write(`  home:   ${paths.home}\n`);
   }
@@ -271,14 +302,19 @@ async function installLinkMode(repoPath, paths, opts) {
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
 
-  const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
-  const leadSkillResult = await installLeadSkillLink(repoAbs, { dryRun, quiet });
-  await writeSkillsManifest(paths.home, [...skillResult.installed, ...leadSkillResult], { dryRun });
+  if (runtimeIncludesClaudeAssets(runtime)) {
+    const skillResult = await installSkillsLink(repoAbs, { dryRun, quiet });
+    const leadSkillResult = await installLeadSkillLink(repoAbs, { dryRun, quiet });
+    await writeSkillsManifest(paths.home, [...skillResult.installed, ...leadSkillResult], { dryRun });
 
-  const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
-  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
+    const agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
+    await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
+  } else if (!quiet) {
+    process.stdout.write("  claude assets: skipped for runtime=codex\n");
+  }
 
   await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  await writeRuntimeManifest(paths.home, runtime, { dryRun });
 
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
@@ -345,6 +381,20 @@ async function writeAgentsManifest(home, names, opts) {
   );
 }
 
+async function writeRuntimeManifest(home, runtime, opts) {
+  const { dryRun = false } = opts ?? {};
+  const data = buildRuntimeManifest(runtime);
+  if (dryRun) {
+    process.stdout.write(`[dry-run] write runtime manifest: ${data.runtimes.join(",")}\n`);
+    return;
+  }
+  await writeFileAtomic(
+    join(home, RUNTIMES_MANIFEST_REL),
+    JSON.stringify(data, null, 2) + "\n",
+    0o644,
+  );
+}
+
 async function listWorkerFiles(workersRoot) {
   try {
     const entries = await fs.readdir(workersRoot, { withFileTypes: true });
@@ -553,19 +603,24 @@ async function installLeadSkillLink(repoAbs, opts) {
   return [LEAD_SKILL_NAME];
 }
 
-function parseInstallArgs(args) {
+export function parseInstallArgs(args) {
   const result = {
     dryRun: false,
     refresh: false,
     quiet: false,
     linkRepo: null,
+    runtime: "claude-code",
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
     if (a === "--dry-run") result.dryRun = true;
     else if (a === "--refresh") result.refresh = true;
     else if (a === "-q" || a === "--quiet") result.quiet = true;
-    else if (a === "--link") {
+    else if (a === "--runtime" || a.startsWith("--runtime=")) {
+      const parsed = readRuntimeFlag(args, i);
+      result.runtime = validateInstallRuntime(parsed.value);
+      i = parsed.nextIndex;
+    } else if (a === "--link") {
       const next = args[i + 1];
       if (!next || next.startsWith("--")) {
         throw new Error("--link requires a repo path");
@@ -585,7 +640,13 @@ export async function runInstall(args) {
     return 0;
   }
 
-  const opts = parseInstallArgs(args);
+  let opts;
+  try {
+    opts = parseInstallArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 2;
+  }
   const pkgRoot = getPackageRoot();
   const runtimeRoot = join(pkgRoot, "runtime");
   const paths = await resolvePaths();
@@ -607,6 +668,7 @@ export async function runInstall(args) {
 
   if (!opts.quiet) {
     process.stdout.write(`installing okstra runtime (package ${paths.package})\n`);
+    process.stdout.write(`  runtime: ${opts.runtime}\n`);
     process.stdout.write(`  source: ${runtimeRoot}\n`);
     process.stdout.write(`  home:   ${paths.home}\n`);
   }
@@ -688,18 +750,23 @@ export async function runInstall(args) {
     );
   }
 
-  const skillResult = await installSkillsCopy(runtimeRoot, opts);
-  const leadSkillResult = await installLeadSkillCopy(runtimeRoot, opts);
-  await writeSkillsManifest(
-    paths.home,
-    [...skillResult.installed, ...leadSkillResult],
-    { dryRun: opts.dryRun },
-  );
+  if (runtimeIncludesClaudeAssets(opts.runtime)) {
+    const skillResult = await installSkillsCopy(runtimeRoot, opts);
+    const leadSkillResult = await installLeadSkillCopy(runtimeRoot, opts);
+    await writeSkillsManifest(
+      paths.home,
+      [...skillResult.installed, ...leadSkillResult],
+      { dryRun: opts.dryRun },
+    );
 
-  const agentResult = await installAgentsCopy(runtimeRoot, opts);
-  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
+    const agentResult = await installAgentsCopy(runtimeRoot, opts);
+    await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
+  } else if (!opts.quiet) {
+    process.stdout.write("  claude assets: skipped for runtime=codex\n");
+  }
 
   await installNamedTemplate(runtimeRoot, paths, { mode: "copy", ...opts }, SETTINGS_TEMPLATE_DESCRIPTOR);
+  await writeRuntimeManifest(paths.home, opts.runtime, { dryRun: opts.dryRun });
 
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -751,12 +818,38 @@ function summarise(label, result, target) {
   );
 }
 
+export function parseEnsureInstalledArgs(args) {
+  const result = {
+    quiet: false,
+    runtime: "claude-code",
+  };
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg === "-q" || arg === "--quiet") {
+      result.quiet = true;
+    } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
+      const parsed = readRuntimeFlag(args, i);
+      result.runtime = validateInstallRuntime(parsed.value);
+      i = parsed.nextIndex;
+    } else {
+      throw new Error(`unknown argument '${arg}'`);
+    }
+  }
+  return result;
+}
+
 export async function runEnsureInstalled(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(ENSURE_USAGE);
     return 0;
   }
-  const quiet = args.includes("-q") || args.includes("--quiet");
+  let opts;
+  try {
+    opts = parseEnsureInstalledArgs(args);
+  } catch (err) {
+    process.stderr.write(`error: ${err.message}\n`);
+    return 2;
+  }
   const paths = await resolvePaths();
 
   const reasons = [];
@@ -769,18 +862,22 @@ export async function runEnsureInstalled(args) {
   if (!(await fileExists(join(paths.home, "schemas", "final-report-v1.0.schema.json")))) {
     reasons.push(`missing ${join(paths.home, "schemas", "final-report-v1.0.schema.json")}`);
   }
-  if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
-    reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
-  }
-  for (const reason of await agentDriftReasons(paths)) {
-    reasons.push(reason);
+  if (runtimeIncludesClaudeAssets(opts.runtime)) {
+    if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
+      reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
+    }
+    for (const reason of await agentDriftReasons(paths)) {
+      reasons.push(reason);
+    }
   }
 
   if (reasons.length === 0) {
-    if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);
+    if (!opts.quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);
     return 0;
   }
 
   process.stderr.write(`okstra runtime needs install: ${reasons.join("; ")}\n`);
-  return await runInstall(quiet ? ["-q"] : []);
+  const installArgs = ["--runtime", opts.runtime];
+  if (opts.quiet) installArgs.push("-q");
+  return await runInstall(installArgs);
 }

package/src/paths.mjs

@@ -1,5 +1,6 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
+import { existsSync } from "node:fs";
 import { getPackageRoot, getPackageVersion } from "./version.mjs";
 
 const USAGE = `okstra paths — print runtime paths
@@ -52,7 +53,7 @@ const SHELL_EXPORTS = [
 ];
 
 export async function resolvePaths() {
-  const home = join(homedir(), ".okstra");
+  const home = process.env.OKSTRA_HOME?.trim() || join(homedir(), ".okstra");
   const pkgRoot = getPackageRoot();
   const devLink = await readSimpleFile(join(home, "dev-link"));
   const runtimeRoot = devLink || join(pkgRoot, "runtime");
@@ -68,18 +69,31 @@ export async function resolvePaths() {
   };
 }
 
+function workspacePythonpath(paths) {
+  const candidates = [
+    join(paths.workspace, "python"),
+    join(paths.workspace, "scripts"),
+  ];
+  return candidates.find((candidate) => existsSync(candidate)) || "";
+}
+
 // Compose the PYTHONPATH spawned python3 subprocesses should see.
 //
 // Precedence (first wins):
 //   1. process.env.PYTHONPATH (user override — e.g. in-repo `PYTHONPATH=scripts`
 //      for dev work without re-running `okstra install`).
-//   2. The installed user-runtime path (~/.okstra/lib/python).
+//   2. The package/dev-link workspace runtime selected by `okstra paths`.
+//   3. The installed user-runtime path (~/.okstra/lib/python).
 //
 // This is a colon-joined string suitable for direct assignment into the child
 // process env. Empty segments are dropped so a missing env var does not produce
 // a leading ':' (which Python treats as 'current directory').
 export function buildPythonpath(paths) {
-  const fragments = [process.env.PYTHONPATH, paths.pythonpath].filter(
+  const fragments = [
+    process.env.PYTHONPATH,
+    workspacePythonpath(paths),
+    paths.pythonpath,
+  ].filter(
     (s) => typeof s === "string" && s.length > 0,
   );
   return fragments.join(":");

package/src/render-bundle.mjs

@@ -16,6 +16,7 @@ Usage:
     [--approved-plan <path>] [--workers <list>] [--directive <text>] \\
     [--lead-model <m>] [--claude-model <m>] [--codex-model <m>] \\
     [--gemini-model <m>] [--report-writer-model <m>] \\
+    [--lead-runtime claude-code|codex] \\
     [--related-tasks <list>] [--base-ref <ref>] \\
     [--clarification-response <path>] [--work-category <cat>] \\
     [--stage <auto|N>] [--stages <csv>] [--pr-template-path <path>] \\
@@ -23,6 +24,7 @@ Usage:
 
   --stage             implementation / final-verification only
   --stages            release-handoff only: PR stage bundle csv (empty = whole-task)
+  --lead-runtime      lead adapter marker; codex is render-only in this version
   --pr-template-path  release-handoff only
   --fix-cycle         entry phase only: record this re-entry of a done task as a
                       bug-fix cycle (yes opens/continues the cycle)

package/src/runtime-manifest.mjs

@@ -0,0 +1,29 @@
+export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
+
+export function runtimeListForSelection(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 {
+    installedAt,
+    runtime,
+    runtimes: runtimeListForSelection(runtime),
+    assets: {
+      sharedRuntime: true,
+      claudeSkills: includesClaude,
+      claudeAgents: includesClaude,
+      codexAdapter: includesCodex,
+      externalAdapter: includesExternal,
+    },
+    version: 1,
+  };
+}
+
+export function runtimeManifestIncludesClaudeAssets(data) {
+  return data?.assets?.claudeSkills === true || data?.assets?.claudeAgents === true;
+}

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

@@ -2,10 +2,15 @@ import { promises as fs } from "node:fs";
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { resolvePaths } from "./paths.mjs";
+import {
+  RUNTIMES_MANIFEST_REL,
+  runtimeManifestIncludesClaudeAssets,
+} from "./runtime-manifest.mjs";
 
 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",
@@ -56,8 +61,8 @@ const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib (python + validators),
                                 bin/<known>, schemas, templates, version,
-                                dev-link, installed-skills.json,
-                                installed-agents.json} AND
+                                dev-link, installed-runtimes.json,
+                                installed-skills.json, installed-agents.json} AND
                                 ~/.claude/skills/<name> AND
                                 ~/.claude/agents/<worker>.md for every
                                 entry in the install manifests (fallback:
@@ -188,7 +193,9 @@ export async function runUninstall(args) {
   // Remove the skills we own. Manifest is authoritative; fall back to the
   // hard-coded okstra-* names if it is missing (e.g. an install from an old
   // version that did not write the manifest).
-  const skillNames = await readSkillsManifest(paths.home);
+  const runtimeManifest = await readRuntimeManifest(paths.home);
+  const shouldRemoveClaudeAssets = shouldUseClaudeAssetFallback(runtimeManifest);
+  const skillNames = shouldRemoveClaudeAssets ? await readSkillsManifest(paths.home) : [];
   if (!opts.quiet) {
     process.stdout.write(`  skills: removing ${skillNames.length} entries from ${CLAUDE_SKILLS_DIR}\n`);
   }
@@ -198,7 +205,7 @@ export async function runUninstall(args) {
   await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
 
   // Remove worker agents we own. Same authoritative-manifest pattern as skills.
-  const agentNames = await readAgentsManifest(paths.home);
+  const agentNames = shouldRemoveClaudeAssets ? await readAgentsManifest(paths.home) : [];
   if (!opts.quiet) {
     process.stdout.write(`  agents: removing ${agentNames.length} entries from ${CLAUDE_AGENTS_DIR}\n`);
   }
@@ -218,6 +225,7 @@ export async function runUninstall(args) {
 
   await removePath(join(paths.home, "version"), opts);
   await removePath(join(paths.home, "dev-link"), opts);
+  await removePath(join(paths.home, RUNTIMES_MANIFEST_REL), opts);
 
   if (!opts.quiet) {
     process.stdout.write("done. user data preserved (recent.jsonl, projects/, archive/, ...).\n");
@@ -225,6 +233,21 @@ export async function runUninstall(args) {
   return 0;
 }
 
+async function readRuntimeManifest(home) {
+  try {
+    const raw = await fs.readFile(join(home, RUNTIMES_MANIFEST_REL), "utf8");
+    const data = JSON.parse(raw);
+    return data && typeof data === "object" ? data : null;
+  } catch {
+    return null;
+  }
+}
+
+export function shouldUseClaudeAssetFallback(runtimeManifest) {
+  if (runtimeManifest === null) return true;
+  return runtimeManifestIncludesClaudeAssets(runtimeManifest);
+}
+
 async function readSkillsManifest(home) {
   try {
     const raw = await fs.readFile(join(home, SKILLS_MANIFEST_REL), "utf8");