okstra 0.102.2 → 0.102.3

package/docs/superpowers/plans/2026-06-14-host-runtime-auto-execution.md

@@ -1,1775 +0,0 @@
-# Host Runtime Auto Execution Implementation Plan
-
-> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
-
-**Goal:** Add host-based runtime auto-detection and auto-execution so `okstra` can pick Claude Code, Codex, or external/tmux execution safely from the current host.
-
-**Architecture:** Add a Node runtime resolver as the single reference point for host/capability decisions. Keep Python `prepare_task_bundle()` provider-neutral and render-only for non-Claude runtimes; Node high-level orchestration resolves runtime and calls the existing low-level commands. Replace ambiguous v1 install manifest adapter flags with v2 request/resolution/assets fields while preserving v1 reads.
-
-**Tech Stack:** Node ESM, `node:test`, Python 3.11, pytest, existing `okstra_ctl.run` renderer, existing `okstra team` and `okstra codex-*` CLIs.
-
----
-
-## File Structure
-
-- Create `src/runtime-resolver.mjs`
-  - Owns runtime request validation, host signal detection, capability normalization, safe fallback, and resolution payload shape.
-- Create `tests-js/runtime-resolver.test.mjs`
-  - Unit-test resolver decisions without shelling out.
-- Modify `src/runtime-manifest.mjs`
-  - Write v2 install manifests and read both v1/v2 for Claude asset checks.
-- Modify `src/install.mjs`
-  - Accept `auto`, default install/ensure to `auto`, resolve before copying runtime-specific assets, write v2 manifest.
-- Modify `tests-js/install-runtime.test.mjs`
-  - Cover auto defaults, v2 manifest, external host install, v1 compatibility.
-- Modify `src/doctor.mjs`
-  - Accept/default `auto`, resolve before selecting checks, emit `runtimeResolution` in JSON.
-- Modify `tests-js/doctor-runtime.test.mjs`
-  - Cover auto defaults and JSON resolution.
-- Modify `src/render-bundle.mjs`
-  - Default `--lead-runtime auto`, resolve to explicit runtime before calling Python, pass resolution metadata.
-- Modify `scripts/okstra_ctl/run.py`
-  - Accept `--lead-runtime-request` and `--runtime-resolution-json`, store them in `ctx`, print `okstra run manifest:` summary line.
-- Modify `scripts/okstra_ctl/render.py`
-  - Write `leadRuntimeRequest` and `runtimeResolution` into run manifest.
-- Modify `tests/test_lead_runtime_marker.py`
-  - Cover run manifest request/resolution fields.
-- Create `src/run.mjs`
-  - High-level CLI driver for Codex/external auto execution; fail with `/okstra-run` guidance for bare Claude Code resolution.
-- Create `tests-js/run.test.mjs`
-  - Unit-test command planning and stdout parsing without dispatching real workers.
-- Modify `src/cli-registry.mjs`
-  - Register `run` and update command counts/help.
-- Modify `tests-js/cli-registry.test.mjs`
-  - Update command counts and help assertions.
-- Modify `skills/okstra-run/SKILL.md`
-  - Mark Claude Code host explicitly via `OKSTRA_RUNTIME_HOST=claude-code` and keep slash-skill path as the Claude front door.
-- Modify `docs/project-structure-overview.md`, `docs/kr/cli.md`, `docs/superpowers/specs/2026-06-14-host-runtime-auto-execution-design.md` only if implementation details diverge from the approved design.
-- Modify `tests/test_docs_runtime_contract.py`
-  - Pin auto/default/runtime manifest v2 documentation.
-
----
-
-### Task 1: Runtime Resolver
-
-**Files:**
-- Create: `src/runtime-resolver.mjs`
-- Create: `tests-js/runtime-resolver.test.mjs`
-
-- [ ] **Step 1: Write the failing resolver tests**
-
-Create `tests-js/runtime-resolver.test.mjs` with:
-
-```js
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  RUNTIME_AUTO,
-  VALID_RUNTIME_REQUESTS,
-  normalizeRuntimeRequest,
-  resolveRuntime,
-} from "../src/runtime-resolver.mjs";
-
-const BASE_CAPABILITIES = Object.freeze({
-  claudeAssetsInstalled: false,
-  codexCliAvailable: false,
-  tmuxAvailable: false,
-  claudeSkillHandoff: false,
-});
-
-function resolve(overrides = {}) {
-  return resolveRuntime({
-    requestedRuntime: overrides.requestedRuntime ?? RUNTIME_AUTO,
-    command: overrides.command ?? "run",
-    env: overrides.env ?? {},
-    capabilities: { ...BASE_CAPABILITIES, ...(overrides.capabilities ?? {}) },
-  });
-}
-
-test("valid runtime requests include auto and explicit runtimes", () => {
-  assert.deepEqual(VALID_RUNTIME_REQUESTS, [
-    "auto",
-    "claude-code",
-    "codex",
-    "external",
-    "all",
-  ]);
-});
-
-test("normalizeRuntimeRequest defaults blank values to auto", () => {
-  assert.equal(normalizeRuntimeRequest(""), "auto");
-  assert.equal(normalizeRuntimeRequest(undefined), "auto");
-  assert.equal(normalizeRuntimeRequest(" external "), "external");
-});
-
-test("normalizeRuntimeRequest rejects unknown values", () => {
-  assert.throws(
-    () => normalizeRuntimeRequest("cursor"),
-    /unknown runtime 'cursor'/,
-  );
-});
-
-test("explicit runtime bypasses host auto detection", () => {
-  const result = resolve({
-    requestedRuntime: "codex",
-    env: { OKSTRA_RUNTIME_HOST: "external" },
-    capabilities: { tmuxAvailable: true },
-  });
-
-  assert.equal(result.requestedRuntime, "codex");
-  assert.equal(result.resolvedRuntime, "codex");
-  assert.equal(result.host, "explicit");
-  assert.equal(result.fallbackFrom, null);
-});
-
-test("auto uses explicit OKSTRA_RUNTIME_HOST for Claude Code", () => {
-  const result = resolve({
-    env: { OKSTRA_RUNTIME_HOST: "claude-code" },
-    capabilities: { claudeAssetsInstalled: true, claudeSkillHandoff: true },
-  });
-
-  assert.equal(result.resolvedRuntime, "claude-code");
-  assert.equal(result.host, "claude-code");
-  assert.match(result.reason, /OKSTRA_RUNTIME_HOST=claude-code/);
-});
-
-test("auto uses explicit OKSTRA_RUNTIME_HOST for Codex", () => {
-  const result = resolve({
-    env: { OKSTRA_RUNTIME_HOST: "codex" },
-    capabilities: { codexCliAvailable: true },
-  });
-
-  assert.equal(result.resolvedRuntime, "codex");
-  assert.equal(result.host, "codex");
-  assert.match(result.reason, /OKSTRA_RUNTIME_HOST=codex/);
-});
-
-test("auto uses explicit OKSTRA_RUNTIME_HOST for external", () => {
-  const result = resolve({
-    env: { OKSTRA_RUNTIME_HOST: "external" },
-    capabilities: { tmuxAvailable: true },
-  });
-
-  assert.equal(result.resolvedRuntime, "external");
-  assert.equal(result.host, "external");
-  assert.match(result.reason, /OKSTRA_RUNTIME_HOST=external/);
-});
-
-test("binary availability alone does not choose Codex host", () => {
-  const result = resolve({ capabilities: { codexCliAvailable: true, tmuxAvailable: true } });
-
-  assert.equal(result.resolvedRuntime, "external");
-  assert.equal(result.host, "generic-terminal");
-});
-
-test("generic terminal with tmux resolves external", () => {
-  const result = resolve({ capabilities: { tmuxAvailable: true } });
-
-  assert.equal(result.resolvedRuntime, "external");
-  assert.equal(result.host, "generic-terminal");
-  assert.match(result.reason, /tmux is available/);
-});
-
-test("unknown host without tmux fails fast", () => {
-  const result = resolve();
-
-  assert.equal(result.resolvedRuntime, null);
-  assert.equal(result.host, "unknown");
-  assert.equal(result.ok, false);
-  assert.match(result.reason, /host unknown/);
-});
-
-test("all remains an explicit admin runtime", () => {
-  const result = resolve({ requestedRuntime: "all" });
-
-  assert.equal(result.resolvedRuntime, "all");
-  assert.equal(result.host, "explicit");
-});
-```
-
-- [ ] **Step 2: Run the resolver tests and verify they fail**
-
-Run:
-
-```bash
-node --test tests-js/runtime-resolver.test.mjs
-```
-
-Expected: FAIL with `Cannot find module ... src/runtime-resolver.mjs`.
-
-- [ ] **Step 3: Implement the minimal resolver**
-
-Create `src/runtime-resolver.mjs` with:
-
-```js
-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: [],
-  };
-}
-
-function hostOverride(env) {
-  const host = clean(env?.OKSTRA_RUNTIME_HOST);
-  return VALID_HOSTS.has(host) ? host : "";
-}
-
-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);
-  void command;
-
-  if (request !== RUNTIME_AUTO) return explicitResult(request);
-
-  const host = hostOverride(env);
-  if (host) {
-    return okResult({
-      requestedRuntime: request,
-      resolvedRuntime: host,
-      host,
-      reason: `OKSTRA_RUNTIME_HOST=${host} selected runtime '${host}'.`,
-    });
-  }
-
-  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 --lead-runtime explicitly.",
-  );
-}
-```
-
-- [ ] **Step 4: Run the resolver tests and verify they pass**
-
-Run:
-
-```bash
-node --test tests-js/runtime-resolver.test.mjs
-```
-
-Expected: PASS, 11 tests.
-
-- [ ] **Step 5: Commit Task 1**
-
-Run:
-
-```bash
-git add src/runtime-resolver.mjs tests-js/runtime-resolver.test.mjs
-git commit -m "feat(runtime): add host runtime resolver"
-```
-
----
-
-### Task 2: Runtime Manifest v2
-
-**Files:**
-- Modify: `src/runtime-manifest.mjs`
-- Modify: `tests-js/install-runtime.test.mjs`
-
-- [ ] **Step 1: Add failing manifest v2 tests**
-
-In `tests-js/install-runtime.test.mjs`, extend the import from `runtime-manifest.mjs`:
-
-```js
-import {
-  buildRuntimeManifest,
-  installedRuntimesFromManifest,
-  runtimeManifestIncludesClaudeAssets,
-} from "../src/runtime-manifest.mjs";
-```
-
-Add these tests after the existing runtime manifest tests:
-
-```js
-test("runtime manifest v2 separates install request from resolved runtime", () => {
-  const resolution = {
-    requestedRuntime: "auto",
-    resolvedRuntime: "external",
-    host: "generic-terminal",
-    confidence: "high",
-    reason: "No Claude Code or Codex host signal; tmux is available.",
-    fallbackFrom: null,
-    warnings: [],
-  };
-
-  const manifest = buildRuntimeManifest("auto", "2026-06-14T00:00:00Z", resolution);
-
-  assert.equal(manifest.schemaVersion, 2);
-  assert.equal(manifest.installRequest, "auto");
-  assert.deepEqual(manifest.installedRuntimes, ["external"]);
-  assert.deepEqual(manifest.runtimeResolution, resolution);
-  assert.equal(manifest.installedAssets.sharedRuntime, true);
-  assert.equal(manifest.installedAssets.claudeSkills, false);
-  assert.equal(manifest.installedAssets.claudeAgents, false);
-  assert.equal("codexAdapter" in manifest.installedAssets, false);
-  assert.equal("externalAdapter" in manifest.installedAssets, false);
-});
-
-test("runtime manifest v2 records all admin install", () => {
-  const manifest = buildRuntimeManifest("all", "2026-06-14T00:00:00Z");
-
-  assert.equal(manifest.schemaVersion, 2);
-  assert.equal(manifest.installRequest, "all");
-  assert.deepEqual(manifest.installedRuntimes, ["claude-code", "codex", "external"]);
-  assert.equal(runtimeManifestIncludesClaudeAssets(manifest), true);
-});
-
-test("runtime manifest readers preserve v1 compatibility", () => {
-  const v1 = {
-    installedAt: "2026-06-12T00:00:00Z",
-    runtime: "claude-code",
-    runtimes: ["claude-code"],
-    assets: {
-      sharedRuntime: true,
-      claudeSkills: true,
-      claudeAgents: true,
-      codexAdapter: false,
-      externalAdapter: false,
-    },
-    version: 1,
-  };
-
-  assert.equal(runtimeManifestIncludesClaudeAssets(v1), true);
-  assert.deepEqual(installedRuntimesFromManifest(v1), ["claude-code"]);
-});
-```
-
-- [ ] **Step 2: Run the manifest tests and verify they fail**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-```
-
-Expected: FAIL because `installedRuntimesFromManifest` is not exported and `buildRuntimeManifest("auto", ...)` still writes v1-style fields.
-
-- [ ] **Step 3: Implement v2 manifest writing and v1 reads**
-
-Replace `src/runtime-manifest.mjs` with:
-
-```js
-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, resolution = null) {
-  if (runtime === "all") return [...EXPLICIT_RUNTIME_VALUES];
-  if (runtime === "auto") {
-    const resolved = resolution?.resolvedRuntime;
-    return resolved && resolved !== "all" ? [resolved] : [];
-  }
-  return [runtime];
-}
-
-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) {
-  const runtimeResolution = resolution ?? defaultResolution(runtime);
-  const includesClaude = includesClaudeRuntime(runtime, runtimeResolution);
-  return {
-    schemaVersion: RUNTIME_MANIFEST_SCHEMA_VERSION,
-    installedAt,
-    installRequest: runtime,
-    runtimeResolution,
-    installedRuntimes: runtimeListForSelection(runtime, runtimeResolution),
-    installedAssets: {
-      sharedRuntime: true,
-      claudeSkills: includesClaude,
-      claudeAgents: includesClaude,
-      binWrappers: true,
-      templates: true,
-      schemas: true,
-      validators: true,
-    },
-  };
-}
-
-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;
-}
-```
-
-- [ ] **Step 4: Update old v1 expectations in `tests-js/install-runtime.test.mjs`**
-
-Change assertions that read `manifest.runtimes` / `manifest.assets` for newly built manifests to v2 fields:
-
-```js
-assert.deepEqual(manifest.installedRuntimes, ["codex"]);
-assert.equal(manifest.installedAssets.sharedRuntime, true);
-assert.equal(runtimeManifestIncludesClaudeAssets(manifest), false);
-```
-
-For `external`:
-
-```js
-assert.deepEqual(manifest.installedRuntimes, ["external"]);
-assert.equal(manifest.installedAssets.sharedRuntime, true);
-assert.equal(runtimeManifestIncludesClaudeAssets(manifest), false);
-```
-
-For `all`:
-
-```js
-assert.deepEqual(manifest.installedRuntimes, ["claude-code", "codex", "external"]);
-assert.equal(runtimeManifestIncludesClaudeAssets(manifest), true);
-```
-
-- [ ] **Step 5: Run the manifest tests and verify they pass**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 6: Commit Task 2**
-
-Run:
-
-```bash
-git add src/runtime-manifest.mjs tests-js/install-runtime.test.mjs
-git commit -m "feat(runtime): write runtime manifest v2"
-```
-
----
-
-### Task 3: Install and Ensure Default to Auto
-
-**Files:**
-- Modify: `src/install.mjs`
-- Modify: `tests-js/install-runtime.test.mjs`
-
-- [ ] **Step 1: Add failing install auto tests**
-
-In `tests-js/install-runtime.test.mjs`, extend the install argument tests:
-
-```js
-test("install defaults to auto runtime", () => {
-  assert.equal(parseInstallArgs([]).runtime, "auto");
-  assert.equal(runtimeIncludesClaudeAssets("auto", {
-    requestedRuntime: "auto",
-    resolvedRuntime: "external",
-  }), false);
-});
-
-test("ensure-installed defaults to auto runtime", () => {
-  assert.deepEqual(parseEnsureInstalledArgs([]), {
-    quiet: false,
-    runtime: "auto",
-  });
-});
-
-test("install accepts auto runtime explicitly", () => {
-  const opts = parseInstallArgs(["--runtime", "auto", "--dry-run"]);
-
-  assert.equal(opts.runtime, "auto");
-  assert.equal(opts.dryRun, true);
-});
-
-test("install auto external host writes manifest v2 without Claude assets", () => {
-  const { root, env } = makeInstallEnv();
-  const okstraHome = join(root, ".okstra");
-
-  const install = runCli(["install"], {
-    ...env,
-    OKSTRA_RUNTIME_HOST: "external",
-  });
-  assert.equal(install.code, 0, install.stderr);
-
-  const installedRuntimes = JSON.parse(
-    readFileSync(join(okstraHome, "installed-runtimes.json"), "utf8"),
-  );
-  assert.equal(installedRuntimes.schemaVersion, 2);
-  assert.equal(installedRuntimes.installRequest, "auto");
-  assert.equal(installedRuntimes.runtimeResolution.resolvedRuntime, "external");
-  assert.deepEqual(installedRuntimes.installedRuntimes, ["external"]);
-  assert.equal(installedRuntimes.installedAssets.claudeSkills, false);
-  assert.equal(installedRuntimes.installedAssets.claudeAgents, false);
-});
-```
-
-Remove or rewrite the old test named `install defaults to Claude Code runtime` so there is only one default-runtime assertion.
-
-- [ ] **Step 2: Run install tests and verify they fail**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-```
-
-Expected: FAIL because `auto` is not accepted and defaults remain `claude-code`.
-
-- [ ] **Step 3: Update runtime validation and Claude asset helper**
-
-In `src/install.mjs`, import the resolver:
-
-```js
-import { resolveRuntime, normalizeRuntimeRequest } from "./runtime-resolver.mjs";
-```
-
-Change the runtime set and helper:
-
-```js
-const INSTALL_RUNTIMES = new Set(["auto", "claude-code", "codex", "external", "all"]);
-
-export function runtimeIncludesClaudeAssets(runtime, resolution = null) {
-  if (runtime === "all" || runtime === "claude-code") return true;
-  return runtime === "auto" && resolution?.resolvedRuntime === "claude-code";
-}
-```
-
-Change `validateInstallRuntime`:
-
-```js
-export function validateInstallRuntime(value) {
-  const runtime = normalizeRuntimeRequest(value);
-  if (!INSTALL_RUNTIMES.has(runtime)) {
-    throw new Error(`unknown runtime '${runtime}' (expected: auto, claude-code, codex, external, all)`);
-  }
-  return runtime;
-}
-```
-
-Change parser defaults:
-
-```js
-const result = {
-  dryRun: false,
-  refresh: false,
-  quiet: false,
-  linkRepo: null,
-  runtime: "auto",
-};
-```
-
-and:
-
-```js
-const result = {
-  quiet: false,
-  runtime: "auto",
-};
-```
-
-- [ ] **Step 4: Resolve runtime inside install before asset-specific writes**
-
-In `runInstall`, after `const paths = await resolvePaths();`, add:
-
-```js
-  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;
-```
-
-Replace output line:
-
-```js
-process.stdout.write(`  runtime: ${opts.runtime} -> ${resolvedRuntime}\n`);
-```
-
-Replace Claude asset condition:
-
-```js
-if (runtimeIncludesClaudeAssets(opts.runtime, runtimeResolution)) {
-```
-
-Replace manifest write:
-
-```js
-await writeRuntimeManifest(paths.home, opts.runtime, {
-  dryRun: opts.dryRun,
-  resolution: runtimeResolution,
-});
-```
-
-Update `writeRuntimeManifest` signature if needed:
-
-```js
-async function writeRuntimeManifest(home, runtime, opts = {}) {
-  const payload = buildRuntimeManifest(runtime, new Date().toISOString(), opts.resolution ?? null);
-  if (!opts.dryRun) {
-    await writeFileAtomic(join(home, RUNTIMES_MANIFEST_REL), JSON.stringify(payload, null, 2) + "\n", 0o644);
-  }
-}
-```
-
-- [ ] **Step 5: Resolve runtime in ensure-installed**
-
-In `runEnsureInstalled`, after resolving paths, add the same resolver call with `command: "ensure-installed"`. Use `runtimeIncludesClaudeAssets(opts.runtime, runtimeResolution)` for Claude checks. When reinstalling, pass the original request:
-
-```js
-const installArgs = ["--runtime", opts.runtime];
-```
-
-- [ ] **Step 6: Run install tests and verify they pass**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit Task 3**
-
-Run:
-
-```bash
-git add src/install.mjs tests-js/install-runtime.test.mjs
-git commit -m "feat(runtime): default install to auto runtime"
-```
-
----
-
-### Task 4: Doctor Auto Runtime
-
-**Files:**
-- Modify: `src/doctor.mjs`
-- Modify: `tests-js/doctor-runtime.test.mjs`
-
-- [ ] **Step 1: Add failing doctor auto tests**
-
-In `tests-js/doctor-runtime.test.mjs`, change `runCli` to accept env:
-
-```js
-function runCli(args, env = {}) {
-  try {
-    const stdout = execFileSync("node", [BIN, ...args], {
-      cwd: REPO,
-      env: { ...process.env, ...env },
-      encoding: "utf8",
-    });
-    return { code: 0, stdout, stderr: "" };
-  } catch (err) {
-    return {
-      code: err.status ?? 1,
-      stdout: (err.stdout || "").toString(),
-      stderr: (err.stderr || "").toString(),
-    };
-  }
-}
-```
-
-Replace the default test with:
-
-```js
-test("doctor defaults to auto runtime checks", () => {
-  assert.deepEqual(parseDoctorArgs([]), {
-    jsonMode: false,
-    phase: null,
-    runtime: "auto",
-  });
-});
-```
-
-Add:
-
-```js
-test("doctor JSON includes runtime resolution", () => {
-  const result = runCli(["doctor", "--json"], {
-    OKSTRA_RUNTIME_HOST: "external",
-  });
-
-  assert.equal(result.code, 0, result.stderr);
-  const payload = JSON.parse(result.stdout);
-  assert.equal(payload.runtime, "external");
-  assert.equal(payload.runtimeRequest, "auto");
-  assert.equal(payload.runtimeResolution.requestedRuntime, "auto");
-  assert.equal(payload.runtimeResolution.resolvedRuntime, "external");
-});
-```
-
-Update the phase parse test expected runtime from `claude-code` to `auto`.
-
-- [ ] **Step 2: Run doctor tests and verify they fail**
-
-Run:
-
-```bash
-node --test tests-js/doctor-runtime.test.mjs
-```
-
-Expected: FAIL because doctor still defaults to `claude-code` and JSON lacks `runtimeResolution`.
-
-- [ ] **Step 3: Implement doctor resolution**
-
-In `src/doctor.mjs`, import resolver:
-
-```js
-import { resolveRuntime } from "./runtime-resolver.mjs";
-```
-
-Change parser default:
-
-```js
-runtime: "auto",
-```
-
-In `run`, after `const paths = await resolvePaths();`, add:
-
-```js
-  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;
-```
-
-Use `resolvedRuntime` when selecting required skills:
-
-```js
-requiredSkillNamesForRuntime(resolvedRuntime).map((name) =>
-```
-
-Change JSON output fields:
-
-```js
-runtimeRequest: opts.runtime,
-runtime: resolvedRuntime,
-runtimeResolution,
-```
-
-Keep non-JSON output unchanged except optionally print the resolution before checks:
-
-```js
-process.stdout.write(`runtime: ${opts.runtime} -> ${resolvedRuntime} (${runtimeResolution.host})\n`);
-```
-
-- [ ] **Step 4: Run doctor tests and verify they pass**
-
-Run:
-
-```bash
-node --test tests-js/doctor-runtime.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 5: Commit Task 4**
-
-Run:
-
-```bash
-git add src/doctor.mjs tests-js/doctor-runtime.test.mjs
-git commit -m "feat(runtime): resolve doctor runtime automatically"
-```
-
----
-
-### Task 5: Render-Bundle and Run Manifest Runtime Resolution
-
-**Files:**
-- Modify: `src/render-bundle.mjs`
-- Modify: `scripts/okstra_ctl/run.py`
-- Modify: `scripts/okstra_ctl/render.py`
-- Modify: `tests/test_lead_runtime_marker.py`
-
-- [ ] **Step 1: Add failing Python manifest test**
-
-In `tests/test_lead_runtime_marker.py`, add after `test_rendered_artifacts_record_external_lead_runtime`:
-
-```python
-def test_run_manifest_records_runtime_request_and_resolution(tmp_path: Path) -> None:
-    ctx = _ctx(tmp_path, lead_runtime="external")
-    ctx["LEAD_RUNTIME_REQUEST"] = "auto"
-    ctx["RUNTIME_RESOLUTION_JSON"] = json.dumps(
-        {
-            "requestedRuntime": "auto",
-            "resolvedRuntime": "external",
-            "host": "generic-terminal",
-            "confidence": "high",
-            "reason": "No Claude Code or Codex host signal; tmux is available.",
-            "fallbackFrom": None,
-            "warnings": [],
-        }
-    )
-
-    render_task_manifest(ctx["TASK_MANIFEST_PATH"], ctx)
-    render_run_manifest(ctx["RUN_MANIFEST_PATH"], ctx)
-
-    run_manifest = _read(ctx["RUN_MANIFEST_PATH"])
-    assert run_manifest["leadRuntime"] == "external"
-    assert run_manifest["leadRuntimeRequest"] == "auto"
-    assert run_manifest["runtimeResolution"]["requestedRuntime"] == "auto"
-    assert run_manifest["runtimeResolution"]["resolvedRuntime"] == "external"
-    assert run_manifest["runtimeResolution"]["host"] == "generic-terminal"
-```
-
-- [ ] **Step 2: Run the Python test and verify it fails**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_lead_runtime_marker.py::test_run_manifest_records_runtime_request_and_resolution -q
-```
-
-Expected: FAIL with missing `leadRuntimeRequest`.
-
-- [ ] **Step 3: Add Python inputs and context fields**
-
-In `scripts/okstra_ctl/run.py`, add fields to `PrepareInputs`:
-
-```python
-    lead_runtime_request: str = ""
-    runtime_resolution_json: str = ""
-```
-
-In the argparse section near `--lead-runtime`, add:
-
-```python
-    p.add_argument(
-        "--lead-runtime-request",
-        default="",
-        dest="lead_runtime_request",
-        help="Original lead runtime request before Node-side resolution, e.g. auto.",
-    )
-    p.add_argument(
-        "--runtime-resolution-json",
-        default="",
-        dest="runtime_resolution_json",
-        help="Node-side runtime resolution payload serialized as JSON.",
-    )
-```
-
-When constructing `PrepareInputs`, pass:
-
-```python
-        lead_runtime_request=args.lead_runtime_request,
-        runtime_resolution_json=args.runtime_resolution_json,
-```
-
-In `prepare_task_bundle`, after `lead_runtime = _normalize_lead_runtime(inp.lead_runtime)`, add:
-
-```python
-    lead_runtime_request = (inp.lead_runtime_request or lead_runtime).strip()
-    runtime_resolution_json = (inp.runtime_resolution_json or "{}").strip()
-    try:
-        json.loads(runtime_resolution_json or "{}")
-    except json.JSONDecodeError as exc:
-        raise PrepareError(f"invalid --runtime-resolution-json: {exc}") from exc
-```
-
-In the `ctx` dict, add:
-
-```python
-        "LEAD_RUNTIME_REQUEST": lead_runtime_request,
-        "RUNTIME_RESOLUTION_JSON": runtime_resolution_json or "{}",
-```
-
-- [ ] **Step 4: Write runtime fields in run manifest**
-
-In `scripts/okstra_ctl/render.py`, add a helper near the other small helpers:
-
-```python
-def _runtime_resolution(ctx: dict) -> dict:
-    raw = ctx.get("RUNTIME_RESOLUTION_JSON", "") or "{}"
-    try:
-        payload = json.loads(raw)
-    except Exception:
-        return {}
-    return payload if isinstance(payload, dict) else {}
-```
-
-In `render_run_manifest`, after `"leadRuntime": _lead_runtime(ctx),`, add:
-
-```python
-        "leadRuntimeRequest": ctx.get("LEAD_RUNTIME_REQUEST", "") or _lead_runtime(ctx),
-        "runtimeResolution": _runtime_resolution(ctx),
-```
-
-- [ ] **Step 5: Print run manifest summary line**
-
-In `scripts/okstra_ctl/run.py`, after line printing `okstra instruction-set`, add:
-
-```python
-    print(f"okstra run manifest: {ctx['RUN_MANIFEST_PATH']}")
-```
-
-This line is required for `okstra run` to parse the prepared manifest without guessing paths.
-
-- [ ] **Step 6: Update render-bundle to resolve `auto` before Python**
-
-In `src/render-bundle.mjs`, import resolver:
-
-```js
-import { resolveRuntime } from "./runtime-resolver.mjs";
-```
-
-Add helpers:
-
-```js
-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;
-}
-```
-
-Before building `finalArgs`, add:
-
-```js
-  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;
-  }
-```
-
-Build final args with explicit resolved runtime and metadata:
-
-```js
-  const finalArgs = [
-    "--workspace-root", paths.workspace,
-    "--render-only",
-    "--lead-runtime", runtimeResolution.resolvedRuntime,
-    "--lead-runtime-request", requestedRuntime,
-    "--runtime-resolution-json", JSON.stringify(runtimeResolution),
-    ...withoutLeadRuntime(args),
-  ];
-```
-
-- [ ] **Step 7: Run targeted tests and verify they pass**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_lead_runtime_marker.py -q
-node --test tests-js/team.test.mjs tests-js/codex-run.test.mjs
-```
-
-Expected: Python lead runtime tests PASS, Node low-level command tests PASS.
-
-- [ ] **Step 8: Commit Task 5**
-
-Run:
-
-```bash
-git add src/render-bundle.mjs scripts/okstra_ctl/run.py scripts/okstra_ctl/render.py tests/test_lead_runtime_marker.py
-git commit -m "feat(runtime): record resolved runtime in run manifests"
-```
-
----
-
-### Task 6: High-Level `okstra run` Driver
-
-**Files:**
-- Create: `src/run.mjs`
-- Create: `tests-js/run.test.mjs`
-- Modify: `src/cli-registry.mjs`
-- Modify: `tests-js/cli-registry.test.mjs`
-
-- [ ] **Step 1: Add failing run driver tests**
-
-Create `tests-js/run.test.mjs`:
-
-```js
-import test from "node:test";
-import assert from "node:assert/strict";
-
-import {
-  buildRunPlan,
-  extractLabel,
-  requestedRuntimeFromArgs,
-  withoutLeadRuntimeFlags,
-} from "../src/run.mjs";
-
-const PATHS = Object.freeze({ workspace: "/runtime", bin: "/home/.okstra/bin" });
-
-const EXTERNAL_RESOLUTION = Object.freeze({
-  ok: true,
-  requestedRuntime: "auto",
-  resolvedRuntime: "external",
-  host: "generic-terminal",
-  confidence: "high",
-  reason: "No Claude Code or Codex host signal; tmux is available.",
-  fallbackFrom: null,
-  warnings: [],
-});
-
-const CODEX_RESOLUTION = Object.freeze({
-  ok: true,
-  requestedRuntime: "auto",
-  resolvedRuntime: "codex",
-  host: "codex",
-  confidence: "high",
-  reason: "OKSTRA_RUNTIME_HOST=codex selected runtime 'codex'.",
-  fallbackFrom: null,
-  warnings: [],
-});
-
-const CLAUDE_RESOLUTION = Object.freeze({
-  ok: true,
-  requestedRuntime: "auto",
-  resolvedRuntime: "claude-code",
-  host: "claude-code",
-  confidence: "high",
-  reason: "OKSTRA_RUNTIME_HOST=claude-code selected runtime 'claude-code'.",
-  fallbackFrom: null,
-  warnings: [],
-});
-
-test("requestedRuntimeFromArgs defaults to auto", () => {
-  assert.equal(requestedRuntimeFromArgs(["--task-type", "error-analysis"]), "auto");
-});
-
-test("requestedRuntimeFromArgs reads explicit lead runtime", () => {
-  assert.equal(requestedRuntimeFromArgs(["--lead-runtime", "external"]), "external");
-  assert.equal(requestedRuntimeFromArgs(["--lead-runtime=codex"]), "codex");
-});
-
-test("withoutLeadRuntimeFlags removes owned runtime flags", () => {
-  assert.deepEqual(
-    withoutLeadRuntimeFlags(["--task-type", "error-analysis", "--lead-runtime", "external", "--workers", ""]),
-    ["--task-type", "error-analysis", "--workers", ""],
-  );
-  assert.deepEqual(
-    withoutLeadRuntimeFlags(["--lead-runtime=codex", "--task-type", "error-analysis"]),
-    ["--task-type", "error-analysis"],
-  );
-});
-
-test("extractLabel reads run manifest label", () => {
-  const stdout = [
-    "okstra task key: p:g:t",
-    "okstra run manifest: /tmp/project/.okstra/tasks/g/t/runs/error-analysis/manifests/run.json",
-    "",
-  ].join("\n");
-
-  assert.equal(
-    extractLabel(stdout, "okstra run manifest"),
-    "/tmp/project/.okstra/tasks/g/t/runs/error-analysis/manifests/run.json",
-  );
-});
-
-test("external run plan prepares render bundle then team dispatch and await", () => {
-  const plan = buildRunPlan({
-    args: ["--project-root", "/project", "--task-type", "error-analysis"],
-    paths: PATHS,
-    resolution: EXTERNAL_RESOLUTION,
-    runManifestPath: "/project/.okstra/run.json",
-  });
-
-  assert.deepEqual(plan.commands, [
-    {
-      name: "render-bundle",
-      args: [
-        "--lead-runtime", "external",
-        "--lead-runtime-request", "auto",
-        "--runtime-resolution-json", JSON.stringify(EXTERNAL_RESOLUTION),
-        "--project-root", "/project",
-        "--task-type", "error-analysis",
-      ],
-      capture: true,
-    },
-    {
-      name: "team dispatch",
-      args: ["dispatch", "--project-root", "/project", "--run-manifest", "/project/.okstra/run.json"],
-      capture: false,
-    },
-    {
-      name: "team await",
-      args: ["await", "--project-root", "/project", "--run-manifest", "/project/.okstra/run.json"],
-      capture: false,
-    },
-  ]);
-});
-
-test("codex run plan prepares codex-run then codex-dispatch", () => {
-  const plan = buildRunPlan({
-    args: ["--project-root", "/project", "--task-type", "error-analysis"],
-    paths: PATHS,
-    resolution: CODEX_RESOLUTION,
-    runManifestPath: "/project/.okstra/run.json",
-  });
-
-  assert.deepEqual(plan.commands.map((item) => item.name), ["codex-run", "codex-dispatch"]);
-  assert.deepEqual(plan.commands[1].args, [
-    "--project-root", "/project",
-    "--run-manifest", "/project/.okstra/run.json",
-  ]);
-});
-
-test("codex run plan forwards codex dispatch opt-in flags", () => {
-  const plan = buildRunPlan({
-    args: [
-      "--project-root", "/project",
-      "--task-type", "error-analysis",
-      "--enable-codex-report-writer",
-      "--report-writer-codex-model", "gpt-5.5",
-    ],
-    paths: PATHS,
-    resolution: CODEX_RESOLUTION,
-    runManifestPath: "/project/.okstra/run.json",
-  });
-
-  assert.deepEqual(plan.commands[1].args, [
-    "--project-root", "/project",
-    "--run-manifest", "/project/.okstra/run.json",
-    "--enable-codex-report-writer",
-    "--report-writer-codex-model", "gpt-5.5",
-  ]);
-});
-
-test("bare Node run cannot execute Claude Code native teams", () => {
-  const plan = buildRunPlan({
-    args: ["--project-root", "/project", "--task-type", "error-analysis"],
-    paths: PATHS,
-    resolution: CLAUDE_RESOLUTION,
-    runManifestPath: "",
-  });
-
-  assert.equal(plan.ok, false);
-  assert.match(plan.reason, /\/okstra-run/);
-  assert.match(plan.reason, /TeamCreate/);
-});
-```
-
-- [ ] **Step 2: Run run driver tests and verify they fail**
-
-Run:
-
-```bash
-node --test tests-js/run.test.mjs
-```
-
-Expected: FAIL because `src/run.mjs` does not exist.
-
-- [ ] **Step 3: Implement pure planning helpers**
-
-Create `src/run.mjs` with the helper exports first:
-
-```js
-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 renderArgs(args, resolution) {
-  return [
-    "--lead-runtime", resolution.resolvedRuntime,
-    "--lead-runtime-request", resolution.requestedRuntime,
-    "--runtime-resolution-json", JSON.stringify(resolution),
-    ...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: [] };
-}
-```
-
-- [ ] **Step 4: Run run driver tests and verify helper tests pass**
-
-Run:
-
-```bash
-node --test tests-js/run.test.mjs
-```
-
-Expected: PASS for helper tests.
-
-- [ ] **Step 5: Implement CLI execution path**
-
-Append to `src/run.mjs`:
-
-```js
-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 ensureCode = await ensureRuntime(requestedRuntime);
-  if (ensureCode !== 0) return ensureCode;
-
-  const firstPlan = buildRunPlan({ args, paths, resolution });
-  if (!firstPlan.ok) {
-    process.stderr.write(`error: ${firstPlan.reason}\n`);
-    return 2;
-  }
-
-  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;
-}
-```
-
-- [ ] **Step 6: Register CLI command and update registry test**
-
-In `src/cli-registry.mjs`, add after `render-bundle`:
-
-```js
-  {
-    name: "run",
-    module: "./run.mjs",
-    export: "run",
-    category: "introspection",
-    summary: ["Host-aware auto execution front door"],
-  },
-```
-
-In `tests-js/cli-registry.test.mjs`:
-
-```js
-assert.equal(registryNames.length, 29);
-assert.equal(COMMANDS.size, 29);
-assert.equal(introspection.length, 18);
-```
-
-Add assertion:
-
-```js
-assert.match(USAGE, /run\s+Host-aware auto execution front door/);
-```
-
-- [ ] **Step 7: Run run and registry tests**
-
-Run:
-
-```bash
-node --test tests-js/run.test.mjs tests-js/cli-registry.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 8: Commit Task 6**
-
-Run:
-
-```bash
-git add src/run.mjs tests-js/run.test.mjs src/cli-registry.mjs tests-js/cli-registry.test.mjs
-git commit -m "feat(runtime): add host-aware run driver"
-```
-
----
-
-### Task 7: Claude Skill Host Marker and Docs Contract
-
-**Files:**
-- Modify: `skills/okstra-run/SKILL.md`
-- Modify: `docs/project-structure-overview.md`
-- Modify: `docs/kr/cli.md`
-- Modify: `tests/test_docs_runtime_contract.py`
-
-- [ ] **Step 1: Add failing docs contract checks**
-
-In `tests/test_docs_runtime_contract.py`, add:
-
-```python
-def test_docs_state_runtime_auto_detection_contract():
-    cli_text = _read_doc("docs/kr/cli.md")
-    structure_text = _read_doc("docs/project-structure-overview.md")
-    skill_text = _read_doc("skills/okstra-run/SKILL.md")
-
-    cli_fragments = [
-        "기본 runtime은 `auto`",
-        "host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve",
-        "bare `okstra run` cannot invoke Claude Code `TeamCreate` / `Agent(...)`",
-        "Claude Code에서는 `/okstra-run`이 front door",
-        "`installed-runtimes.json` schemaVersion 2",
-        "`codexAdapter` / `externalAdapter`는 v1 compatibility read path",
-    ]
-    for fragment in cli_fragments:
-        assert fragment in cli_text
-
-    structure_fragments = [
-        "`src/runtime-resolver.mjs` is the single reference point",
-        "`okstra install` defaults to `--runtime auto`",
-        "Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`",
-    ]
-    for fragment in structure_fragments:
-        assert fragment in structure_text
-
-    assert "OKSTRA_RUNTIME_HOST=claude-code okstra ensure-installed" in skill_text
-    assert "OKSTRA_RUNTIME_HOST=claude-code okstra render-bundle" in skill_text
-```
-
-- [ ] **Step 2: Run docs contract test and verify it fails**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py::test_docs_state_runtime_auto_detection_contract -q
-```
-
-Expected: FAIL with missing fragments.
-
-- [ ] **Step 3: Update `skills/okstra-run/SKILL.md`**
-
-Change Step 1 command from:
-
-```markdown
-1. `okstra ensure-installed`
-```
-
-to:
-
-```markdown
-1. `OKSTRA_RUNTIME_HOST=claude-code okstra ensure-installed`
-```
-
-Change the render command block from:
-
-```bash
-okstra render-bundle \
-```
-
-to:
-
-```bash
-OKSTRA_RUNTIME_HOST=claude-code okstra render-bundle \
-```
-
-Add one sentence near the render command:
-
-```markdown
-The Claude Code skill is the Claude execution front door, so it marks the host explicitly with `OKSTRA_RUNTIME_HOST=claude-code`; bare `okstra run` cannot invoke native `TeamCreate` / `Agent(...)` from a terminal.
-```
-
-- [ ] **Step 4: Update CLI docs**
-
-In `docs/kr/cli.md`, add a concise runtime auto section under the runtime docs:
-
-```markdown
-기본 runtime은 `auto` 입니다. `auto` 는 host 기반으로 `claude-code`, `codex`, `external` 중 하나로 resolve 됩니다.
-
-- Claude Code에서는 `/okstra-run`이 front door 입니다. bare `okstra run` cannot invoke Claude Code `TeamCreate` / `Agent(...)` from a terminal.
-- Codex host에서는 `okstra run`이 `codex-run` → `codex-dispatch`를 orchestration 합니다.
-- generic terminal + tmux에서는 `okstra run`이 `render-bundle --lead-runtime external` → `okstra team dispatch` → `okstra team await`를 orchestration 합니다.
-
-`installed-runtimes.json` schemaVersion 2는 `installRequest`, `runtimeResolution`, `installedRuntimes`, `installedAssets`를 분리합니다. `codexAdapter` / `externalAdapter`는 v1 compatibility read path 에서만 해석됩니다.
-```
-
-- [ ] **Step 5: Update project structure docs**
-
-In `docs/project-structure-overview.md`, add under the install output section:
-
-```markdown
-`src/runtime-resolver.mjs` is the single reference point for runtime auto-detection. `okstra install` defaults to `--runtime auto`, records the request and resolution in `installed-runtimes.json` schemaVersion 2, and still copies the shared runtime payload from the installed package `runtime/` tree.
-
-Dynamic capabilities such as `tmux` and `codex` CLI availability are checked by `doctor` and `run`, not frozen into the install manifest.
-```
-
-- [ ] **Step 6: Run docs tests and verify they pass**
-
-Run:
-
-```bash
-python3 -m pytest tests/test_docs_runtime_contract.py -q
-```
-
-Expected: PASS.
-
-- [ ] **Step 7: Commit Task 7**
-
-Run:
-
-```bash
-git add skills/okstra-run/SKILL.md docs/project-structure-overview.md docs/kr/cli.md tests/test_docs_runtime_contract.py
-git commit -m "docs(runtime): document host runtime auto execution"
-```
-
----
-
-### Task 8: Full Verification and Cleanup
-
-**Files:**
-- Review all changed files from Tasks 1-7.
-- Modify only files with failing tests or stale docs.
-
-- [ ] **Step 1: Run targeted Node tests**
-
-Run:
-
-```bash
-node --test \
-  tests-js/runtime-resolver.test.mjs \
-  tests-js/install-runtime.test.mjs \
-  tests-js/doctor-runtime.test.mjs \
-  tests-js/run.test.mjs \
-  tests-js/cli-registry.test.mjs \
-  tests-js/codex-run.test.mjs \
-  tests-js/team.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 2: Run targeted Python tests**
-
-Run:
-
-```bash
-python3 -m pytest \
-  tests/test_lead_runtime_marker.py \
-  tests/test_docs_runtime_contract.py
-```
-
-Expected: PASS.
-
-- [ ] **Step 3: Run install round-trip tests**
-
-Run:
-
-```bash
-node --test tests-js/install-runtime.test.mjs tests-js/runtime-build-sync.test.mjs
-```
-
-Expected: PASS.
-
-- [ ] **Step 4: Run project check**
-
-Run:
-
-```bash
-npm run check
-```
-
-Expected: exit code 0.
-
-- [ ] **Step 5: Run graphify update**
-
-Run:
-
-```bash
-graphify update .
-```
-
-Expected: exit code 0. If it fails with the existing HTML graph node-count limit, record the exact failure in the final report and do not edit graph outputs by hand.
-
-- [ ] **Step 6: Grep new identifiers for consistency**
-
-Use the search tool, not shell grep, for these identifiers:
-
-```text
-OKSTRA_RUNTIME_HOST
-runtimeResolution
-leadRuntimeRequest
-installedAssets
-installedRuntimes
-schemaVersion": 2
-```
-
-Expected:
-
-- `OKSTRA_RUNTIME_HOST` appears in resolver tests, docs, and `skills/okstra-run/SKILL.md`.
-- `runtimeResolution` appears in resolver, manifest, doctor JSON, run manifest, tests, and docs.
-- `leadRuntimeRequest` appears in Python run/render code and run manifest tests.
-- `codexAdapter` / `externalAdapter` appear only in v1 compatibility tests/docs or old manifest read compatibility.
-
-- [ ] **Step 7: Commit verification fixes if any**
-
-If any command in Steps 1-6 required code/doc fixes, commit them:
-
-```bash
-git add <fixed-files>
-git commit -m "fix(runtime): align auto runtime verification"
-```
-
-If no fixes were needed, do not create an empty commit.
-
-- [ ] **Step 8: Final status**
-
-Run:
-
-```bash
-git status --short
-```
-
-Expected: no unstaged implementation changes. Test artifacts under `.okstra` or temp directories must not be committed.