okstra 0.79.0 → 0.81.0

package/src/run.mjs

@@ -0,0 +1,201 @@
+import { runEnsureInstalled } from "./install.mjs";
+import { runPythonModule } from "./_python-helper.mjs";
+import { resolvePaths } from "./paths.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
+
+const USAGE = `okstra run — host-aware okstra execution front door
+
+Usage:
+  okstra run --project-root <dir> --project-id <id> --task-group <tg> \\
+    --task-id <tid> --task-type <type> [--lead-runtime auto|claude-code|codex|external]
+
+Claude Code native execution remains the /okstra-run skill front door. Bare
+'okstra run' orchestrates Codex and external/tmux CLI execution.
+`;
+
+function flagValue(args, flag) {
+  const equals = args.find((arg) => arg.startsWith(`${flag}=`));
+  if (equals) return equals.slice(flag.length + 1);
+  const index = args.indexOf(flag);
+  return index >= 0 ? args[index + 1] : "";
+}
+
+export function requestedRuntimeFromArgs(args) {
+  return flagValue(args, "--lead-runtime") || "auto";
+}
+
+export function withoutLeadRuntimeFlags(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--lead-runtime") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--lead-runtime=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+export function extractLabel(stdout, label) {
+  const prefix = `${label}:`;
+  const line = String(stdout || "").split("\n").find((item) => item.startsWith(prefix));
+  return line ? line.slice(prefix.length).trim() : "";
+}
+
+function projectRootFromArgs(args) {
+  return flagValue(args, "--project-root");
+}
+
+function withoutDispatchOnlyFlags(args) {
+  const out = [];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--enable-codex-report-writer") continue;
+    if (arg === "--report-writer-codex-model") {
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--report-writer-codex-model=")) continue;
+    out.push(arg);
+  }
+  return out;
+}
+
+function renderArgs(args, resolution) {
+  return [
+    "--lead-runtime", resolution.resolvedRuntime,
+    "--lead-runtime-request", resolution.requestedRuntime,
+    "--runtime-resolution-json", JSON.stringify(resolution),
+    ...withoutDispatchOnlyFlags(withoutLeadRuntimeFlags(args)),
+  ];
+}
+
+function codexDispatchArgs(args, projectRoot, runManifestPath) {
+  const out = ["--project-root", projectRoot, "--run-manifest", runManifestPath];
+  for (let i = 0; i < args.length; i += 1) {
+    const arg = args[i];
+    if (arg === "--enable-codex-report-writer") {
+      out.push(arg);
+      continue;
+    }
+    if (arg === "--report-writer-codex-model") {
+      out.push(arg, args[i + 1] ?? "");
+      i += 1;
+      continue;
+    }
+    if (arg.startsWith("--report-writer-codex-model=")) out.push(arg);
+  }
+  return out;
+}
+
+export function buildRunPlan({ args, paths, resolution, runManifestPath = "" }) {
+  void paths;
+  const projectRoot = projectRootFromArgs(args);
+  if (resolution.resolvedRuntime === "claude-code") {
+    return {
+      ok: false,
+      reason: "Bare okstra run cannot invoke Claude Code TeamCreate / Agent(...). Use /okstra-run in Claude Code or pass --lead-runtime external|codex.",
+      commands: [],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "external") {
+    return {
+      ok: true,
+      reason: resolution.reason,
+      commands: [
+        { name: "render-bundle", args: renderArgs(args, resolution), capture: true },
+        { name: "team dispatch", args: ["dispatch", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
+        { name: "team await", args: ["await", "--project-root", projectRoot, "--run-manifest", runManifestPath], capture: false },
+      ],
+    };
+  }
+
+  if (resolution.resolvedRuntime === "codex") {
+    return {
+      ok: true,
+      reason: resolution.reason,
+      commands: [
+        { name: "codex-run", args: renderArgs(args, resolution), capture: true },
+        { name: "codex-dispatch", args: codexDispatchArgs(args, projectRoot, runManifestPath), capture: false },
+      ],
+    };
+  }
+
+  return { ok: false, reason: `unsupported resolved runtime: ${resolution.resolvedRuntime}`, commands: [] };
+}
+
+async function ensureRuntime(requestedRuntime) {
+  return await runEnsureInstalled(["--runtime", requestedRuntime, "-q"]);
+}
+
+async function runRenderCommand(command, paths) {
+  const result = await runPythonModule({
+    module: "okstra_ctl.run",
+    args: ["--workspace-root", paths.workspace, "--render-only", ...command.args],
+    stdio: "capture",
+  });
+  process.stdout.write(result.stdout);
+  if (result.stderr) process.stderr.write(result.stderr);
+  return result;
+}
+
+async function runTeam(args) {
+  const { run: runTeamCommand } = await import("./team.mjs");
+  return await runTeamCommand(args);
+}
+
+async function runCodexDispatch(args) {
+  const { run: runCodexDispatchCommand } = await import("./codex-dispatch.mjs");
+  return await runCodexDispatchCommand(args);
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+
+  const paths = await resolvePaths();
+  const requestedRuntime = requestedRuntimeFromArgs(args);
+  const resolution = resolveRuntime({
+    requestedRuntime,
+    command: "run",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!resolution.ok) {
+    process.stderr.write(`error: ${resolution.reason}\n`);
+    return 2;
+  }
+
+  const firstPlan = buildRunPlan({ args, paths, resolution });
+  if (!firstPlan.ok) {
+    process.stderr.write(`error: ${firstPlan.reason}\n`);
+    return 2;
+  }
+
+  const ensureCode = await ensureRuntime(requestedRuntime);
+  if (ensureCode !== 0) return ensureCode;
+
+  const render = firstPlan.commands[0];
+  const prepared = await runRenderCommand(render, paths);
+  if (prepared.code !== 0) return prepared.code ?? 1;
+
+  const runManifestPath = extractLabel(prepared.stdout, "okstra run manifest");
+  if (!runManifestPath) {
+    process.stderr.write("error: render output did not include 'okstra run manifest:'\n");
+    return 1;
+  }
+
+  const plan = buildRunPlan({ args, paths, resolution, runManifestPath });
+  for (const command of plan.commands.slice(1)) {
+    const code = command.name.startsWith("team ")
+      ? await runTeam(command.args)
+      : await runCodexDispatch(command.args);
+    if (code !== 0) return code;
+  }
+  return 0;
+}

package/src/runtime-manifest.mjs

@@ -1,29 +1,72 @@
 export const RUNTIMES_MANIFEST_REL = "installed-runtimes.json";
+export const RUNTIME_MANIFEST_SCHEMA_VERSION = 2;
+export const EXPLICIT_RUNTIME_VALUES = ["claude-code", "codex", "external"];
 
-export function runtimeListForSelection(runtime) {
-  if (runtime === "all") return ["claude-code", "codex", "external"];
+export function runtimeListForSelection(runtime, resolution = null) {
+  if (runtime === "all") return [...EXPLICIT_RUNTIME_VALUES];
+  if (runtime === "auto") {
+    const resolved = resolution?.resolvedRuntime;
+    return resolved && resolved !== "all" ? [resolved] : [];
+  }
   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";
+function includesClaudeRuntime(runtime, resolution = null) {
+  if (runtime === "all") return true;
+  if (runtime === "claude-code") return true;
+  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
+}
+
+function defaultResolution(runtime) {
+  if (runtime === "auto") return null;
   return {
+    requestedRuntime: runtime,
+    resolvedRuntime: runtime,
+    host: "explicit",
+    confidence: "high",
+    reason: `Explicit runtime '${runtime}' requested.`,
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+export function buildRuntimeManifest(
+  runtime,
+  installedAt = new Date().toISOString(),
+  resolution = null,
+  installedAssets = null,
+) {
+  const runtimeResolution = resolution ?? defaultResolution(runtime);
+  const includesClaude = includesClaudeRuntime(runtime, runtimeResolution);
+  const defaultAssets = {
+    sharedRuntime: true,
+    claudeSkills: includesClaude,
+    claudeAgents: includesClaude,
+    binWrappers: true,
+    templates: true,
+    schemas: true,
+    validators: true,
+  };
+  return {
+    schemaVersion: RUNTIME_MANIFEST_SCHEMA_VERSION,
     installedAt,
-    runtime,
-    runtimes: runtimeListForSelection(runtime),
-    assets: {
-      sharedRuntime: true,
-      claudeSkills: includesClaude,
-      claudeAgents: includesClaude,
-      codexAdapter: includesCodex,
-      externalAdapter: includesExternal,
-    },
-    version: 1,
+    installRequest: runtime,
+    runtimeResolution,
+    installedRuntimes: runtimeListForSelection(runtime, runtimeResolution),
+    installedAssets: { ...defaultAssets, ...(installedAssets ?? {}) },
   };
 }
 
+export function installedRuntimesFromManifest(data) {
+  if (Array.isArray(data?.installedRuntimes)) return data.installedRuntimes;
+  if (Array.isArray(data?.runtimes)) return data.runtimes;
+  if (typeof data?.runtime === "string" && data.runtime) return runtimeListForSelection(data.runtime);
+  return [];
+}
+
 export function runtimeManifestIncludesClaudeAssets(data) {
+  if (data?.schemaVersion === RUNTIME_MANIFEST_SCHEMA_VERSION) {
+    return data?.installedAssets?.claudeSkills === true || data?.installedAssets?.claudeAgents === true;
+  }
   return data?.assets?.claudeSkills === true || data?.assets?.claudeAgents === true;
 }

package/src/runtime-resolver.mjs

@@ -0,0 +1,123 @@
+export const RUNTIME_AUTO = "auto";
+export const EXPLICIT_RUNTIMES = ["claude-code", "codex", "external"];
+export const VALID_RUNTIME_REQUESTS = [RUNTIME_AUTO, ...EXPLICIT_RUNTIMES, "all"];
+
+const VALID_HOSTS = new Set(EXPLICIT_RUNTIMES);
+const VALID_REQUESTS = new Set(VALID_RUNTIME_REQUESTS);
+
+function clean(value) {
+  return String(value ?? "").trim();
+}
+
+export function normalizeRuntimeRequest(value) {
+  const runtime = clean(value) || RUNTIME_AUTO;
+  if (!VALID_REQUESTS.has(runtime)) {
+    throw new Error(`unknown runtime '${runtime}' (expected: ${VALID_RUNTIME_REQUESTS.join(", ")})`);
+  }
+  return runtime;
+}
+
+function normalizeCapabilities(capabilities = {}) {
+  return {
+    claudeAssetsInstalled: capabilities.claudeAssetsInstalled === true,
+    codexCliAvailable: capabilities.codexCliAvailable === true,
+    tmuxAvailable: capabilities.tmuxAvailable === true,
+    claudeSkillHandoff: capabilities.claudeSkillHandoff === true,
+  };
+}
+
+function explicitResult(runtime) {
+  return {
+    ok: true,
+    requestedRuntime: runtime,
+    resolvedRuntime: runtime,
+    host: "explicit",
+    confidence: "high",
+    reason: `Explicit runtime '${runtime}' requested.`,
+    fallbackFrom: null,
+    warnings: [],
+  };
+}
+
+const RUNTIME_FLAG_COMMANDS = new Set(["install", "ensure-installed", "doctor"]);
+
+function explicitRuntimeFlag(command) {
+  return RUNTIME_FLAG_COMMANDS.has(command) ? "--runtime" : "--lead-runtime";
+}
+
+function okResult({ requestedRuntime, resolvedRuntime, host, reason, warnings = [] }) {
+  return {
+    ok: true,
+    requestedRuntime,
+    resolvedRuntime,
+    host,
+    confidence: "high",
+    reason,
+    fallbackFrom: null,
+    warnings,
+  };
+}
+
+function failResult(requestedRuntime, reason, warnings = []) {
+  return {
+    ok: false,
+    requestedRuntime,
+    resolvedRuntime: null,
+    host: "unknown",
+    confidence: "low",
+    reason,
+    fallbackFrom: null,
+    warnings,
+  };
+}
+
+export function resolveRuntime({
+  requestedRuntime = RUNTIME_AUTO,
+  command = "run",
+  env = {},
+  capabilities = {},
+} = {}) {
+  const request = normalizeRuntimeRequest(requestedRuntime);
+  const caps = normalizeCapabilities(capabilities);
+
+  if (request !== RUNTIME_AUTO) return explicitResult(request);
+
+  const rawHost = clean(env?.OKSTRA_RUNTIME_HOST);
+  if (rawHost) {
+    if (!VALID_HOSTS.has(rawHost)) {
+      return failResult(
+        request,
+        `invalid OKSTRA_RUNTIME_HOST '${rawHost}' (expected: ${EXPLICIT_RUNTIMES.join("|")}).`,
+      );
+    }
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: rawHost,
+      host: rawHost,
+      reason: `OKSTRA_RUNTIME_HOST=${rawHost} selected runtime '${rawHost}'.`,
+    });
+  }
+
+  if (caps.claudeSkillHandoff) {
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: "claude-code",
+      host: "claude-code",
+      reason: "Claude Code skill handoff selected runtime 'claude-code'.",
+    });
+  }
+
+  if (caps.tmuxAvailable) {
+    return okResult({
+      requestedRuntime: request,
+      resolvedRuntime: "external",
+      host: "generic-terminal",
+      reason: "No Claude Code or Codex host signal; tmux is available.",
+    });
+  }
+
+  return failResult(
+    request,
+    `host unknown: set OKSTRA_RUNTIME_HOST=claude-code|codex|external or pass ${explicitRuntimeFlag(command)} explicitly.`,
+  );
+}

package/src/uninstall.mjs

@@ -51,22 +51,36 @@ const FALLBACK_AGENT_NAMES = [
   "report-writer-worker.md",
 ];
 
-const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
-const CLAUDE_AGENTS_DIR = join(homedir(), ".claude", "agents");
+const USER_HOME = homedir();
+const CLAUDE_HOME = join(USER_HOME, ".claude");
+const CODEX_HOME = join(USER_HOME, ".codex");
+const OMP_AGENT_HOME = join(USER_HOME, ".omp", "agent");
+const CLAUDE_SKILLS_DIR = join(CLAUDE_HOME, "skills");
+const CODEX_SKILLS_DIR = join(CODEX_HOME, "skills");
+const OMP_SKILLS_DIR = join(OMP_AGENT_HOME, "skills");
+const CLAUDE_AGENTS_DIR = join(CLAUDE_HOME, "agents");
+const FALLBACK_SKILL_ROOTS = [
+  CLAUDE_SKILLS_DIR,
+  CODEX_SKILLS_DIR,
+  OMP_SKILLS_DIR,
+];
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
 
-const USAGE = `okstra uninstall — remove installed runtime from ~/.okstra, ~/.claude/skills, ~/.claude/agents
+const USAGE = `okstra uninstall — remove installed runtime and okstra skills
 
 Usage:
   okstra uninstall              Remove ~/.okstra/{lib (python + validators),
                                 bin/<known>, schemas, templates, version,
                                 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:
-                                hard-coded okstra-* / *-worker.md names).
+                                every skill target recorded in
+                                installed-skills.json
+                                (~/.claude/skills, ~/.codex/skills, or
+                                ~/.omp/agent/skills). Claude worker agents are
+                                removed from ~/.claude/agents when installed.
+                                Missing manifests fall back to hard-coded
+                                Claude okstra-* / *-worker.md names.
                                 Preserves user data: recent.jsonl,
                                 active.jsonl, projects/, archive/,
                                 state.json, .locks/
@@ -74,7 +88,7 @@ Usage:
                                 (<PROJECT>/.claude/settings.local.json symlink)
                                 are NOT touched — remove them manually if needed.
   okstra uninstall --purge      Remove the entire ~/.okstra directory AND
-                                ~/.claude/skills/<okstra-*> AND
+                                okstra skills in Claude/Codex/OMP homes AND
                                 ~/.claude/agents/<*-worker.md> (DESTRUCTIVE).
                                 Requires -y or an interactive confirmation
   okstra uninstall --dry-run    Print the plan without touching disk
@@ -138,7 +152,7 @@ export async function runUninstall(args) {
   if (opts.purge) {
     if (!opts.yes && !opts.dryRun) {
       const ok = await promptConfirm(
-        `purge entire ${paths.home} AND ~/.claude/skills/{okstra-*,okstra-setup}? user data will be lost.`,
+        `purge entire ${paths.home} AND okstra skills in Claude/Codex/OMP homes? user data will be lost.`,
       );
       if (!ok) {
         process.stdout.write("aborted.\n");
@@ -148,8 +162,10 @@ export async function runUninstall(args) {
     if (!opts.quiet) process.stdout.write(`purging ${paths.home}\n`);
     await removePath(paths.home, opts);
     // Skills and worker agents live outside ~/.okstra — purge those too.
-    for (const name of FALLBACK_SKILL_NAMES) {
-      await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+    for (const root of FALLBACK_SKILL_ROOTS) {
+      for (const name of FALLBACK_SKILL_NAMES) {
+        await removePath(join(root, name), opts);
+      }
     }
     for (const name of FALLBACK_AGENT_NAMES) {
       await removePath(join(CLAUDE_AGENTS_DIR, name), opts);
@@ -190,22 +206,26 @@ export async function runUninstall(args) {
   // never removed it, leaving a stale final-report schema behind.
   await removePath(join(paths.home, "schemas"), opts);
 
-  // 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).
+  // 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.
   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`);
-  }
-  for (const name of skillNames) {
-    await removePath(join(CLAUDE_SKILLS_DIR, name), opts);
+  const skillTargets = await readSkillsManifest(paths.home, runtimeManifest);
+  for (const target of skillTargets) {
+    if (!opts.quiet) {
+      process.stdout.write(`  skills: removing ${target.skills.length} entries from ${target.root}\n`);
+    }
+    for (const name of target.skills) {
+      await removePath(join(target.root, name), opts);
+    }
   }
   await removePath(join(paths.home, SKILLS_MANIFEST_REL), opts);
 
-  // Remove worker agents we own. Same authoritative-manifest pattern as skills.
-  const agentNames = shouldRemoveClaudeAssets ? await readAgentsManifest(paths.home) : [];
+  // Remove worker agents we own. Agents only live in Claude Code's agent home.
+  const shouldRemoveClaudeAgents =
+    skillTargets.some((target) => target.provider === "claude") ||
+    shouldUseClaudeAssetFallback(runtimeManifest);
+  const agentNames = shouldRemoveClaudeAgents ? await readAgentsManifest(paths.home) : [];
   if (!opts.quiet) {
     process.stdout.write(`  agents: removing ${agentNames.length} entries from ${CLAUDE_AGENTS_DIR}\n`);
   }
@@ -248,15 +268,38 @@ export function shouldUseClaudeAssetFallback(runtimeManifest) {
   return runtimeManifestIncludesClaudeAssets(runtimeManifest);
 }
 
-async function readSkillsManifest(home) {
+function normalizeSkillTargets(data) {
+  if (Array.isArray(data?.targets)) {
+    return data.targets
+      .filter((target) => typeof target?.root === "string" && Array.isArray(target?.skills))
+      .map((target) => ({
+        provider: typeof target.provider === "string" ? target.provider : "unknown",
+        root: target.root,
+        skills: target.skills.filter((name) => typeof name === "string"),
+      }));
+  }
+  if (Array.isArray(data?.skills)) {
+    return [{
+      provider: "claude",
+      root: CLAUDE_SKILLS_DIR,
+      skills: data.skills.filter((name) => typeof name === "string"),
+    }];
+  }
+  return null;
+}
+
+async function readSkillsManifest(home, runtimeManifest) {
   try {
     const raw = await fs.readFile(join(home, SKILLS_MANIFEST_REL), "utf8");
     const data = JSON.parse(raw);
-    if (Array.isArray(data?.skills)) return data.skills;
+    const targets = normalizeSkillTargets(data);
+    if (targets !== null) return targets;
   } catch {
     /* fall through */
   }
-  return FALLBACK_SKILL_NAMES;
+  return shouldUseClaudeAssetFallback(runtimeManifest)
+    ? [{ provider: "claude", root: CLAUDE_SKILLS_DIR, skills: FALLBACK_SKILL_NAMES }]
+    : [];
 }
 
 async function readAgentsManifest(home) {