okstra 0.79.0 → 0.81.0

package/runtime/skills/okstra-team-contract/SKILL.md

@@ -2,6 +2,7 @@
 name: okstra-team-contract
 description: Use when okstra is in Phases 2–5 and needs team operating rules for the Claude lead + worker structure, or when verifying worker roster and model assignments.
 user-invocable: false
+hide: true
 ---
 
 # OKSTRA Team Contract

package/src/cli-registry.mjs

@@ -6,7 +6,7 @@ export const COMMAND_REGISTRY = [
     module: "./install.mjs",
     export: "runInstall",
     category: "admin",
-    summary: ["Install runtime; --runtime codex skips ~/.claude assets"],
+    summary: ["Install runtime; seed skills into existing agent homes"],
   },
   {
     name: "ensure-installed",
@@ -127,6 +127,13 @@ export const COMMAND_REGISTRY = [
       "python3 -m okstra_ctl.run --render-only)",
     ],
   },
+  {
+    name: "run",
+    module: "./run.mjs",
+    export: "run",
+    category: "introspection",
+    summary: ["Host-aware auto execution front door"],
+  },
   {
     name: "codex-run",
     module: "./codex-run.mjs",

package/src/doctor.mjs

@@ -5,6 +5,7 @@ import { resolvePaths } from "./paths.mjs";
 import { fileExists, runProcess } from "./_proc.mjs";
 import { runPythonSnippet } from "./_python-helper.mjs";
 import { runtimeIncludesClaudeAssets, validateInstallRuntime } from "./install.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
 
 const CLAUDE_SKILLS_DIR = join(homedir(), ".claude", "skills");
 const REQUIRED_SKILLS = ["okstra-setup", "okstra-run"];
@@ -38,7 +39,7 @@ export function parseDoctorArgs(args) {
   const result = {
     jsonMode: false,
     phase: null,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -182,6 +183,17 @@ export async function run(args) {
     return 2;
   }
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "doctor",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
+  const resolvedRuntime = runtimeResolution.resolvedRuntime;
 
   const results = [
     await check("python3", checkPython3),
@@ -197,7 +209,7 @@ export async function run(args) {
     await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
     await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
     ...(await Promise.all(
-      requiredSkillNamesForRuntime(opts.runtime).map((name) =>
+      requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
         check(`skill: ${name}`, async () => {
           const p = join(CLAUDE_SKILLS_DIR, name, "SKILL.md");
           return (await fileExists(p))
@@ -229,7 +241,9 @@ export async function run(args) {
     process.stdout.write(
       `${JSON.stringify({
         ok: allOk,
-        runtime: opts.runtime,
+        runtimeRequest: opts.runtime,
+        runtime: resolvedRuntime,
+        runtimeResolution,
         phase: opts.phase,
         paths,
         phaseDiagnostics,

package/src/install.mjs

@@ -6,11 +6,18 @@ import { getPackageRoot } from "./version.mjs";
 import { resolvePaths } from "./paths.mjs";
 import { fileExists } from "./_proc.mjs";
 import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "./runtime-manifest.mjs";
+import { normalizeRuntimeRequest, resolveRuntime } from "./runtime-resolver.mjs";
 
 const SKILLS_MANIFEST_REL = "installed-skills.json";
 const AGENTS_MANIFEST_REL = "installed-agents.json";
-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");
 
 // Source template (relative to runtime root in copy mode, or repo root in link mode).
 const SETTINGS_TEMPLATE_SRC_REL = ["templates", "reports", "settings.template.json"];
@@ -51,10 +58,12 @@ Effect (copy mode):
   ${"$HOME"}/.okstra/bin           <- runtime/bin
   ${"$HOME"}/.okstra/templates     <- runtime/templates  (report.css / report.js / *.template.md)
   ${"$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"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
+  ${"$HOME"}/.codex/skills/<name>  <- skills when ${"$HOME"}/.codex exists
+  ${"$HOME"}/.omp/agent/skills/<name> <- skills fallback when Claude/Codex homes are absent
+  ${"$HOME"}/.claude/agents/<worker>.md <- worker agents when ${"$HOME"}/.claude exists
   ${"$HOME"}/.okstra/installed-runtimes.json <- manifest of installed runtime adapters
-  ${"$HOME"}/.okstra/installed-skills.json   <- manifest of installed skills
+  ${"$HOME"}/.okstra/installed-skills.json   <- target-aware manifest of installed skills
   ${"$HOME"}/.okstra/installed-agents.json   <- manifest of installed workers
   ${"$HOME"}/.okstra/version       <- installed package version stamp
 
@@ -62,8 +71,10 @@ Effect (link mode):
   ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
   ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
   ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
-  ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name>   (symlink dir)
-  ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md
+  ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name> when ${"$HOME"}/.claude exists
+  ${"$HOME"}/.codex/skills/<name>     -> <repo>/skills/<name> when ${"$HOME"}/.codex exists
+  ${"$HOME"}/.omp/agent/skills/<name> -> <repo>/skills/<name> fallback
+  ${"$HOME"}/.claude/agents/<worker>.md -> <repo>/agents/workers/<worker>.md when ${"$HOME"}/.claude exists
   ${"$HOME"}/.okstra/dev-link         <- <repo> path stamp
   ${"$HOME"}/.okstra/version          <- installed package version stamp
 
@@ -72,10 +83,9 @@ project-local <project>/.claude/settings.local.json that okstra-setup
 provisions, granting per-project Claude Code permissions for okstra
 worker wrapper scripts without modifying the user's global settings.
 
-Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ so
-that Claude Code's subagent discovery picks them up; they cannot live
-inside the package alone because the harness only scans ~/.claude/agents/
-and <project>/.claude/agents/.
+Worker agent definitions are installed into ${"$HOME"}/.claude/agents/ only
+when ${"$HOME"}/.claude exists, so Claude Code's subagent discovery can pick
+them up. Codex/OMP skill targets receive skill markdown only.
 `;
 
 const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
@@ -88,10 +98,11 @@ Usage:
 Skills call this on every run. Returns 0 quickly when the install is fresh.
 `;
 
-const INSTALL_RUNTIMES = new Set(["claude-code", "codex", "external", "all"]);
+const INSTALL_RUNTIMES = new Set(["auto", "claude-code", "codex", "external", "all"]);
 
-export function runtimeIncludesClaudeAssets(runtime) {
-  return runtime === "claude-code" || runtime === "all";
+export function runtimeIncludesClaudeAssets(runtime, resolution = null) {
+  if (runtime === "claude-code" || runtime === "all") return true;
+  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
 }
 
 function readRuntimeFlag(args, index) {
@@ -107,10 +118,11 @@ function readRuntimeFlag(args, index) {
 }
 
 export function validateInstallRuntime(value) {
-  if (!INSTALL_RUNTIMES.has(value)) {
-    throw new Error(`unknown runtime '${value}' (expected: claude-code, codex, external, all)`);
+  const runtime = normalizeRuntimeRequest(value);
+  if (!INSTALL_RUNTIMES.has(runtime)) {
+    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, external, all)`);
   }
-  return value;
+  return runtime;
 }
 
 async function hashFile(path) {
@@ -302,19 +314,22 @@ async function installLinkMode(repoPath, paths, opts) {
     if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
   }
 
-  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 skillTargets = await detectSkillTargets();
+  const installedSkillTargets = await installSkillTargetsLink(repoAbs, skillTargets, { dryRun, quiet });
+  await writeSkillsManifest(paths.home, installedSkillTargets, { 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");
+  let agentResult = { installed: [] };
+  if (skillTargets.some((target) => target.provider === "claude")) {
+    agentResult = await installAgentsLink(repoAbs, { dryRun, quiet });
   }
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun });
 
   await installNamedTemplate(repoAbs, paths, { mode: "link", dryRun, quiet }, SETTINGS_TEMPLATE_DESCRIPTOR);
-  await writeRuntimeManifest(paths.home, runtime, { dryRun });
+  await writeRuntimeManifest(paths.home, runtime, {
+    dryRun,
+    resolution: opts.resolution,
+    installedAssets: installedAssetOverrides(installedSkillTargets, agentResult.installed),
+  });
 
   if (!dryRun) {
     await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
@@ -327,7 +342,7 @@ async function installLinkMode(repoPath, paths, opts) {
     process.stdout.write(
       "\nNext step: register the current project.\n" +
         "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
-        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "  (or run /okstra-setup inside a Harness Agent session (e.g. claude codex, codex, pi.. ))\n" +
         "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
         "  npm i -g okstra\n",
     );
@@ -345,15 +360,58 @@ async function listSkillDirs(skillsRoot) {
   }
 }
 
-async function writeSkillsManifest(home, names, opts) {
+async function detectSkillTargets() {
+  const targets = [];
+  const [hasClaude, hasCodex] = await Promise.all([dirExists(CLAUDE_HOME), dirExists(CODEX_HOME)]);
+  if (hasClaude) {
+    targets.push({ provider: "claude", home: CLAUDE_HOME, skillsDir: CLAUDE_SKILLS_DIR });
+  }
+  if (hasCodex) {
+    targets.push({ provider: "codex", home: CODEX_HOME, skillsDir: CODEX_SKILLS_DIR });
+  }
+  if (targets.length === 0 && (await dirExists(OMP_AGENT_HOME))) {
+    targets.push({ provider: "omp", home: OMP_AGENT_HOME, skillsDir: OMP_SKILLS_DIR });
+  }
+  return targets;
+}
+
+function skillTargetManifest(targets) {
+  return targets.map((target) => ({
+    provider: target.provider,
+    root: target.skillsDir,
+    skills: Array.from(new Set(target.installed)).sort(),
+  }));
+}
+
+function installedAssetOverrides(skillTargets, agentNames) {
+  const providers = new Set(skillTargets.map((target) => target.provider));
+  return {
+    claudeSkills: providers.has("claude"),
+    claudeAgents: agentNames.length > 0,
+    codexSkills: providers.has("codex"),
+    ompSkills: providers.has("omp"),
+    skillTargets: Array.from(providers).sort(),
+  };
+}
+
+function installedSkillNames(targets) {
+  return Array.from(new Set(targets.flatMap((target) => target.installed))).sort();
+}
+
+
+async function writeSkillsManifest(home, targets, opts) {
   const { dryRun = false } = opts ?? {};
+  const manifestTargets = skillTargetManifest(targets);
   const data = {
-    version: 1,
+    version: 2,
     installedAt: new Date().toISOString(),
-    skills: Array.from(new Set(names)).sort(),
+    skills: installedSkillNames(targets),
+    targets: manifestTargets,
   };
   if (dryRun) {
-    process.stdout.write(`[dry-run] write skills manifest: ${data.skills.length} entries\n`);
+    process.stdout.write(
+      `[dry-run] write skills manifest: ${data.skills.length} skills across ${data.targets.length} targets\n`,
+    );
     return;
   }
   await writeFileAtomic(
@@ -382,10 +440,15 @@ async function writeAgentsManifest(home, names, opts) {
 }
 
 async function writeRuntimeManifest(home, runtime, opts) {
-  const { dryRun = false } = opts ?? {};
-  const data = buildRuntimeManifest(runtime);
+  const { dryRun = false, resolution = null, installedAssets = null } = opts ?? {};
+  const data = buildRuntimeManifest(
+    runtime,
+    new Date().toISOString(),
+    resolution,
+    installedAssets,
+  );
   if (dryRun) {
-    process.stdout.write(`[dry-run] write runtime manifest: ${data.runtimes.join(",")}\n`);
+    process.stdout.write(`[dry-run] write runtime manifest: ${data.installedRuntimes.join(",")}\n`);
     return;
   }
   await writeFileAtomic(
@@ -521,95 +584,107 @@ const SETTINGS_TEMPLATE_DESCRIPTOR = {
   label: "settings template",
 };
 
-async function installSkillsCopy(runtimeRoot, opts) {
+const LEAD_SKILL_NAME = "okstra";
+
+async function installSkillsCopy(runtimeRoot, target, opts) {
   const { refresh, dryRun, quiet } = opts;
   const srcRoot = join(runtimeRoot, "skills");
   const names = await listSkillDirs(srcRoot);
-  if (names.length === 0) {
-    if (!quiet) process.stdout.write("  skills: runtime/skills empty — skipped\n");
-    return { installed: [] };
-  }
   let copied = 0;
   let skipped = 0;
   for (const name of names) {
     const r = await copyTreeIfChanged(
       join(srcRoot, name),
-      join(CLAUDE_SKILLS_DIR, name),
+      join(target.skillsDir, name),
       { refresh, dryRun, mode: 0o644 },
     );
     copied += r.copied;
     skipped += r.skipped;
   }
+  const lead = await installLeadSkillCopy(runtimeRoot, target, opts);
   if (!quiet) {
+    const totalCopied = copied + lead.copied;
+    const totalSkipped = skipped + lead.skipped;
+    const totalSkills = names.length + lead.installed.length;
     process.stdout.write(
-      `  skills: copied=${copied} skipped=${skipped} -> ${CLAUDE_SKILLS_DIR}/ (${names.length} skills)\n`,
+      `  ${target.provider} skills: copied=${totalCopied} skipped=${totalSkipped} -> ${target.skillsDir}/ (${totalSkills} skills)\n`,
     );
   }
-  return { installed: names };
+  return { ...target, installed: [...names, ...lead.installed] };
 }
 
-async function installSkillsLink(repoAbs, opts) {
+async function installSkillsLink(repoAbs, target, opts) {
   const { dryRun, quiet } = opts;
   const srcRoot = join(repoAbs, "skills");
   const names = await listSkillDirs(srcRoot);
-  if (names.length === 0) {
-    if (!quiet) process.stdout.write("  skills: <repo>/skills missing — skipped\n");
-    return { installed: [] };
-  }
-  if (!dryRun) await fs.mkdir(CLAUDE_SKILLS_DIR, { recursive: true });
+  if (!dryRun) await fs.mkdir(target.skillsDir, { recursive: true });
   for (const name of names) {
     const src = join(srcRoot, name);
-    const dst = join(CLAUDE_SKILLS_DIR, name);
+    const dst = join(target.skillsDir, name);
     const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  skills/${name}: ${action}\n`);
+    if (!quiet) process.stdout.write(`  ${target.provider} skills/${name}: ${action}\n`);
   }
-  return { installed: names };
+  const lead = await installLeadSkillLink(repoAbs, target, opts);
+  return { ...target, installed: [...names, ...lead] };
 }
 
-// The lead `okstra` skill source is agents/SKILL.md (frontmatter `name: okstra`);
-// it doubles as the lead agent contract, so it lives under agents/ rather than
-// skills/. Claude Code only discovers skills at ~/.claude/skills/<name>/SKILL.md,
-// so it must be installed there as its own skill dir — otherwise install ships
-// every okstra-* helper skill but not the lead skill, and edits to agents/SKILL.md
-// never reach the running lead.
-const LEAD_SKILL_NAME = "okstra";
-
-async function installLeadSkillCopy(runtimeRoot, opts) {
+async function installLeadSkillCopy(runtimeRoot, target, opts) {
   const { refresh, dryRun, quiet } = opts;
   const src = join(runtimeRoot, "agents", "SKILL.md");
-  const dst = join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME, "SKILL.md");
+  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
   const r = await copyFileIfChanged(src, dst, { refresh, dryRun, mode: 0o644 });
   if (r.missingSource) {
-    if (!quiet) process.stdout.write("  skills/okstra: runtime/agents/SKILL.md missing — skipped\n");
-    return [];
-  }
-  if (!quiet) {
-    process.stdout.write(`  skills/okstra: ${r.copied ? "copied" : "unchanged"} -> ${dst}\n`);
+    if (!quiet) {
+      process.stdout.write(
+        `  ${target.provider} skills/okstra: runtime/agents/SKILL.md missing — skipped\n`,
+      );
+    }
+    return { installed: [], copied: 0, skipped: 0 };
   }
-  return [LEAD_SKILL_NAME];
+  return { installed: [LEAD_SKILL_NAME], copied: r.copied, skipped: r.skipped };
 }
 
-async function installLeadSkillLink(repoAbs, opts) {
+async function installLeadSkillLink(repoAbs, target, opts) {
   const { dryRun, quiet } = opts;
   const src = join(repoAbs, "agents", "SKILL.md");
   if (!(await fileExists(src))) {
-    if (!quiet) process.stdout.write("  skills/okstra: <repo>/agents/SKILL.md missing — skipped\n");
+    if (!quiet) {
+      process.stdout.write(
+        `  ${target.provider} skills/okstra: <repo>/agents/SKILL.md missing — skipped\n`,
+      );
+    }
     return [];
   }
-  const dst = join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME, "SKILL.md");
-  if (!dryRun) await fs.mkdir(join(CLAUDE_SKILLS_DIR, LEAD_SKILL_NAME), { recursive: true });
+  const dst = join(target.skillsDir, LEAD_SKILL_NAME, "SKILL.md");
+  if (!dryRun) await fs.mkdir(join(target.skillsDir, LEAD_SKILL_NAME), { recursive: true });
   const action = await ensureSymlink(src, dst, { dryRun });
-  if (!quiet) process.stdout.write(`  skills/okstra/SKILL.md: ${action}\n`);
+  if (!quiet) process.stdout.write(`  ${target.provider} skills/okstra/SKILL.md: ${action}\n`);
   return [LEAD_SKILL_NAME];
 }
 
+async function installSkillTargetsCopy(runtimeRoot, targets, opts) {
+  if (targets.length === 0) {
+    if (!opts.quiet) process.stdout.write("  skills: no Claude, Codex, or OMP agent home found — skipped\n");
+    return [];
+  }
+  return await Promise.all(targets.map((target) => installSkillsCopy(runtimeRoot, target, opts)));
+}
+
+async function installSkillTargetsLink(repoAbs, targets, opts) {
+  if (targets.length === 0) {
+    if (!opts.quiet) process.stdout.write("  skills: no Claude, Codex, or OMP agent home found — skipped\n");
+    return [];
+  }
+  return await Promise.all(targets.map((target) => installSkillsLink(repoAbs, target, opts)));
+}
+
 export function parseInstallArgs(args) {
   const result = {
     dryRun: false,
     refresh: false,
     quiet: false,
     linkRepo: null,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const a = args[i];
@@ -650,13 +725,24 @@ export async function runInstall(args) {
   const pkgRoot = getPackageRoot();
   const runtimeRoot = join(pkgRoot, "runtime");
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "install",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
+  const resolvedRuntime = runtimeResolution.resolvedRuntime;
 
   if (!opts.dryRun) {
     await fs.mkdir(paths.home, { recursive: true });
   }
 
   if (opts.linkRepo) {
-    return await installLinkMode(opts.linkRepo, paths, opts);
+    return await installLinkMode(opts.linkRepo, paths, { ...opts, resolution: runtimeResolution });
   }
 
   // copy mode — if a prior dev-link is present, refuse rather than silently overwriting.
@@ -668,7 +754,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(`  runtime: ${opts.runtime} -> ${resolvedRuntime}\n`);
     process.stdout.write(`  source: ${runtimeRoot}\n`);
     process.stdout.write(`  home:   ${paths.home}\n`);
   }
@@ -750,23 +836,22 @@ export async function runInstall(args) {
     );
   }
 
-  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 skillTargets = await detectSkillTargets();
+  const installedSkillTargets = await installSkillTargetsCopy(runtimeRoot, skillTargets, opts);
+  await writeSkillsManifest(paths.home, installedSkillTargets, { 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");
+  let agentResult = { installed: [] };
+  if (skillTargets.some((target) => target.provider === "claude")) {
+    agentResult = await installAgentsCopy(runtimeRoot, opts);
   }
+  await writeAgentsManifest(paths.home, agentResult.installed, { dryRun: opts.dryRun });
 
   await installNamedTemplate(runtimeRoot, paths, { mode: "copy", ...opts }, SETTINGS_TEMPLATE_DESCRIPTOR);
-  await writeRuntimeManifest(paths.home, opts.runtime, { dryRun: opts.dryRun });
+  await writeRuntimeManifest(paths.home, opts.runtime, {
+    dryRun: opts.dryRun,
+    resolution: runtimeResolution,
+    installedAssets: installedAssetOverrides(installedSkillTargets, agentResult.installed),
+  });
 
   if (!opts.dryRun) {
     await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
@@ -777,7 +862,7 @@ export async function runInstall(args) {
     process.stdout.write(
       "\nNext step: register the current project.\n" +
         "  cd <your project> && npx -y okstra@latest setup --project-id <id>\n" +
-        "  (or run /okstra-setup inside a Claude Code session)\n" +
+        "  (or run /okstra-setup inside a Harness Agent session (e.g. claude codex, codex, pi.. ))\n" +
         "\nTip: to use a bare 'okstra' command instead of npx, run:\n" +
         "  npm i -g okstra\n",
     );
@@ -785,6 +870,19 @@ export async function runInstall(args) {
   return 0;
 }
 
+async function skillTargetDriftReasons(targets) {
+  const reasons = [];
+  for (const target of targets) {
+    for (const name of ["okstra-run", LEAD_SKILL_NAME]) {
+      const skillPath = join(target.skillsDir, name, "SKILL.md");
+      if (!(await fileExists(skillPath))) {
+        reasons.push(`missing ${skillPath}`);
+      }
+    }
+  }
+  return reasons;
+}
+
 async function agentDriftReasons(paths) {
   const reasons = [];
   const workersDir = join(paths.agents, "workers");
@@ -821,7 +919,7 @@ function summarise(label, result, target) {
 export function parseEnsureInstalledArgs(args) {
   const result = {
     quiet: false,
-    runtime: "claude-code",
+    runtime: "auto",
   };
   for (let i = 0; i < args.length; i++) {
     const arg = args[i];
@@ -851,6 +949,16 @@ export async function runEnsureInstalled(args) {
     return 2;
   }
   const paths = await resolvePaths();
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime: opts.runtime,
+    command: "ensure-installed",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
 
   const reasons = [];
   if (!paths.version) reasons.push("no version stamp");
@@ -862,10 +970,11 @@ 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 (runtimeIncludesClaudeAssets(opts.runtime)) {
-    if (!(await fileExists(join(CLAUDE_SKILLS_DIR, "okstra-setup", "SKILL.md")))) {
-      reasons.push(`missing ${CLAUDE_SKILLS_DIR}/okstra-setup/SKILL.md`);
-    }
+  const skillTargets = await detectSkillTargets();
+  for (const reason of await skillTargetDriftReasons(skillTargets)) {
+    reasons.push(reason);
+  }
+  if (skillTargets.some((target) => target.provider === "claude")) {
     for (const reason of await agentDriftReasons(paths)) {
       reasons.push(reason);
     }

package/src/render-bundle.mjs

@@ -1,5 +1,6 @@
 import { runPythonModule } from "./_python-helper.mjs";
 import { resolvePaths } from "./paths.mjs";
+import { resolveRuntime } from "./runtime-resolver.mjs";
 
 const USAGE = `okstra render-bundle — preview the task bundle without launching claude
 
@@ -41,6 +42,27 @@ Replaces the long \`from okstra_ctl.run import PrepareInputs,
 prepare_task_bundle\` heredoc pattern.
 `;
 
+function findFlagValue(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] : "";
+}
+
+function withoutLeadRuntime(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 async function run(args) {
   if (args.includes("--help") || args.includes("-h")) {
     process.stdout.write(USAGE);
@@ -59,10 +81,25 @@ export async function run(args) {
     }
   }
 
+  const requestedRuntime = findFlagValue(args, "--lead-runtime") || "auto";
+  const runtimeResolution = resolveRuntime({
+    requestedRuntime,
+    command: "render",
+    env: process.env,
+    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
+  });
+  if (!runtimeResolution.ok) {
+    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
+    return 2;
+  }
+
   const finalArgs = [
     "--workspace-root", paths.workspace,
     "--render-only",
-    ...args,
+    "--lead-runtime", runtimeResolution.resolvedRuntime,
+    "--lead-runtime-request", requestedRuntime,
+    "--runtime-resolution-json", JSON.stringify(runtimeResolution),
+    ...withoutLeadRuntime(args),
   ];
 
   const result = await runPythonModule({