okstra 0.174.0 → 0.176.0

package/src/commands/lifecycle/install.mjs

@@ -1,1170 +0,0 @@
-import { promises as fs } from "node:fs";
-import { createHash } from "node:crypto";
-import { homedir } from "node:os";
-import { join, relative, resolve as resolveAbs } from "node:path";
-import { getPackageRoot } from "../../lib/version.mjs";
-import { resolvePaths } from "../../lib/paths.mjs";
-import { fileExists } from "../../lib/proc.mjs";
-import { buildRuntimeManifest, RUNTIMES_MANIFEST_REL } from "../../lib/runtime-manifest.mjs";
-import { normalizeHostRequest, resolveRuntime } from "../../lib/host-registry-client.mjs";
-import { OBSOLETE_SKILL_NAMES, USER_SKILL_NAMES } from "../../lib/skill-catalog.mjs";
-import {
-  AGENTS_MANIFEST_REL,
-  LEGACY_TRANSPORT_AGENT_NAMES,
-  SKILLS_MANIFEST_REL,
-} from "../../lib/install-assets.mjs";
-
-
-const USER_HOME = homedir();
-const CLAUDE_HOME = join(USER_HOME, ".claude");
-const AGENTS_HOME = join(USER_HOME, ".agents");
-const CLAUDE_SKILLS_DIR = join(CLAUDE_HOME, "skills");
-const AGENTS_SKILLS_DIR = join(AGENTS_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"];
-// Destination under ~/.okstra/. Project-local .claude/settings.local.json symlinks here.
-const SETTINGS_TEMPLATE_DST_REL = ["templates", "settings.local.json"];
-
-const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "okstra_vendor"];
-const BIN_ENTRYPOINTS = [
-  "okstra.sh",
-  "okstra-codex-exec.sh",
-  "okstra-claude-exec.sh",
-  "okstra-antigravity-exec.sh",
-  "okstra-grok-exec.sh",
-  "okstra-kimi-exec.sh",
-  "okstra-provider-exec.py",
-  "okstra-trace-cleanup.sh",
-  "okstra-team-reconcile.sh",
-  "okstra-central.sh",
-  "okstra-token-usage.py",
-  "okstra-error-log.py",
-  "okstra-render-report-views.py",
-  "okstra-render-final-report.py",
-  "okstra-wrapper-status.py",
-  "okstra-spawn-followups.py",
-];
-
-// Runtime prompt resources the launch prompt and routed coding-preflight pack
-// depend on. Intentionally an exact allowlist, not a directory wildcard.
-const REQUIRED_PROMPT_RESOURCE_FILES = Object.freeze([
-  ["prompts", "lead", "okstra-lead-contract.md"],
-  ["prompts", "lead", "context-loader.md"],
-  ["prompts", "lead", "team-contract.md"],
-  ["prompts", "lead", "convergence.md"],
-  ["prompts", "lead", "plan-body-verification.md"],
-  ["prompts", "lead", "report-writer.md"],
-  ["prompts", "coding-preflight", "overview.md"],
-  ["prompts", "coding-preflight", "clean-code.md"],
-  ["prompts", "coding-preflight", "languages", "javascript-typescript.md"],
-  ["prompts", "coding-preflight", "languages", "python.md"],
-  ["prompts", "coding-preflight", "languages", "rust.md"],
-  ["prompts", "coding-preflight", "languages", "java.md"],
-  ["prompts", "coding-preflight", "languages", "kotlin.md"],
-  ["prompts", "coding-preflight", "languages", "sql.md"],
-  ["prompts", "coding-preflight", "frameworks", "node-server.md"],
-  ["prompts", "coding-preflight", "architectures", "hexagonal.md"],
-]);
-
-const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
-
-Usage:
-  okstra install              Install/update runtime (copy mode)
-  okstra install --runtime <host-id|alias|all>
-  okstra install --link <p>   Dev only: symlink ~/.okstra/{lib/python,bin}
-                              to the source repo at <p>. agents/ resolves
-                              to <p>/agents. Not advertised to end users.
-  okstra install --dry-run    Print the plan without touching disk
-  okstra install --refresh    Re-copy even files that match by hash
-
-Effect (copy mode):
-  ${"$HOME"}/.okstra/lib/python   <- runtime/python
-  ${"$HOME"}/.okstra/lib/validators <- runtime/validators  (stage/report structure validators)
-  ${"$HOME"}/.okstra/bin           <- runtime/bin
-  ${"$HOME"}/.okstra/templates     <- runtime/templates  (v1 assets + v2 AI/HTML template trees)
-  ${"$HOME"}/.okstra/schemas       <- runtime/schemas  (final-report schema v1 + v2)
-  ${"$HOME"}/.okstra/prompts       <- runtime/prompts  (lead contracts + coding-preflight pack)
-  ${"$HOME"}/.okstra/templates/settings.local.json <- runtime/templates/reports/settings.template.json
-  ${"$HOME"}/.claude/skills/<name> <- skills when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.agents/skills/<name> <- skills (created when needed)
-  ${"$HOME"}/.claude/agents/<worker>.md <- worker agents when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.okstra/installed-runtimes.json <- install request/resolution manifest
-  ${"$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
-
-Effect (link mode):
-  ${"$HOME"}/.okstra/lib/python/<pkg> -> <repo>/scripts/<pkg>   (symlink)
-  ${"$HOME"}/.okstra/bin/<name>.sh    -> <repo>/scripts/<name>.sh
-  ${"$HOME"}/.okstra/prompts          -> <repo>/prompts
-  ${"$HOME"}/.okstra/templates/settings.local.json -> <repo>/templates/reports/settings.template.json
-  ${"$HOME"}/.claude/skills/<name>    -> <repo>/skills/<name> when ${"$HOME"}/.claude exists
-  ${"$HOME"}/.agents/skills/<name>    -> <repo>/skills/<name> (created when needed)
-  ${"$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
-
-The settings.local.json file is the symlink target referenced by every
-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/ only
-when ${"$HOME"}/.claude exists, so Claude Code's subagent discovery can pick
-them up. Agent skill targets receive skill markdown only.
-
-Default auto runtime installation does not require host detection; it still
-installs shared runtime files, the Agent skill target, and any Claude home it finds.
-`;
-
-const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
-
-Usage:
-  okstra ensure-installed     Verify install; reinstall if version/files drift
-  okstra ensure-installed --runtime <host-id|alias|all>
-  okstra ensure-installed -q  Same, but suppress success output
-
-Skills call this on every run. Returns 0 quickly when the install is fresh.
-`;
-
-export function runtimeIncludesClaudeAssets(resolution) {
-  return resolution?.installTargets?.includes("claude") === true;
-}
-
-function readRuntimeFlag(args, index) {
-  const arg = args[index];
-  if (arg.startsWith("--runtime=")) {
-    return { value: arg.slice("--runtime=".length), nextIndex: index };
-  }
-  const next = args[index + 1];
-  if (!next || next.startsWith("--")) {
-    throw new Error("--runtime requires a host ID, alias, or all");
-  }
-  return { value: next, nextIndex: index + 1 };
-}
-
-export function validateInstallRuntime(value) {
-  return normalizeHostRequest(value);
-}
-
-async function resolveInstallRuntime(runtime, command) {
-  const resolution = await resolveRuntime({
-    requestedRuntime: runtime,
-    command,
-    env: process.env,
-    capabilities: { tmuxAvailable: Boolean(process.env.TMUX) },
-  });
-  if (resolution.ok || runtime !== "auto") return resolution;
-  return {
-    ...resolution,
-    confidence: "none",
-    warnings: [resolution.reason],
-  };
-}
-
-function formatInstallRuntimeLabel(runtime, resolution) {
-  if (resolution.resolvedRuntime) return `${runtime} -> ${resolution.resolvedRuntime}`;
-  return `${runtime} (host unresolved; installing target assets)`;
-}
-
-async function hashFile(path) {
-  const buf = await fs.readFile(path);
-  return createHash("sha256").update(buf).digest("hex");
-}
-
-async function dirExists(path) {
-  try {
-    const st = await fs.stat(path);
-    return st.isDirectory();
-  } catch {
-    return false;
-  }
-}
-
-async function pathEntryExists(path) {
-  try {
-    await fs.lstat(path);
-    return true;
-  } catch (err) {
-    if (err.code === "ENOENT") return false;
-    throw err;
-  }
-}
-
-async function* walkFiles(root) {
-  let entries;
-  try {
-    entries = await fs.readdir(root, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return;
-    throw err;
-  }
-  for (const ent of entries) {
-    if (ent.name === "__pycache__" || ent.name === ".DS_Store") continue;
-    if (ent.name.endsWith(".pyc")) continue;
-    const abs = join(root, ent.name);
-    if (ent.isDirectory()) {
-      yield* walkFiles(abs);
-    } else if (ent.isFile()) {
-      yield abs;
-    }
-  }
-}
-
-async function writeFileAtomic(target, data, mode) {
-  await fs.mkdir(join(target, ".."), { recursive: true });
-  const tmp = `${target}.tmp.${process.pid}.${Date.now()}`;
-  await fs.writeFile(tmp, data, { mode });
-  await fs.rename(tmp, target);
-}
-
-// Files the destination has and the payload no longer ships. Left in place they
-// are indistinguishable from current code — Python imports whatever is on disk,
-// so a module dropped in release N+1 keeps being importable after the upgrade,
-// and a rename leaves both spellings live at once.
-async function pruneOrphans(srcRoot, dstRoot, opts) {
-  const { dryRun = false } = opts ?? {};
-  if (!(await dirExists(dstRoot))) return 0;
-  let pruned = 0;
-  for await (const dstPath of walkFiles(dstRoot)) {
-    const rel = relative(dstRoot, dstPath);
-    try {
-      await fs.access(join(srcRoot, rel));
-      continue;
-    } catch {
-      // not in the payload → orphan
-    }
-    if (dryRun) {
-      process.stdout.write(`[dry-run] prune ${dstPath}\n`);
-    } else {
-      await fs.rm(dstPath, { force: true });
-    }
-    pruned++;
-  }
-  return pruned;
-}
-
-async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
-  const { refresh = false, dryRun = false, mode } = opts ?? {};
-  let copied = 0;
-  let skipped = 0;
-  let pruned = 0;
-  let missingSource = false;
-
-  if (!(await dirExists(srcRoot))) {
-    missingSource = true;
-    return { copied, skipped, pruned, missingSource };
-  }
-
-  for await (const srcPath of walkFiles(srcRoot)) {
-    const rel = relative(srcRoot, srcPath);
-    const dstPath = join(dstRoot, rel);
-
-    let needsCopy = refresh;
-    if (!needsCopy) {
-      try {
-        await fs.access(dstPath);
-        const [srcHash, dstHash] = await Promise.all([hashFile(srcPath), hashFile(dstPath)]);
-        needsCopy = srcHash !== dstHash;
-      } catch {
-        needsCopy = true;
-      }
-    }
-
-    if (!needsCopy) {
-      skipped++;
-      continue;
-    }
-
-    if (dryRun) {
-      process.stdout.write(`[dry-run] copy ${srcPath} -> ${dstPath}\n`);
-    } else {
-      const buf = await fs.readFile(srcPath);
-      await writeFileAtomic(dstPath, buf, mode);
-    }
-    copied++;
-  }
-
-  pruned = await pruneOrphans(srcRoot, dstRoot, { dryRun });
-  return { copied, skipped, pruned, missingSource };
-}
-
-async function ensureSymlink(target, linkPath, opts) {
-  const { dryRun = false } = opts ?? {};
-  try {
-    const current = await fs.readlink(linkPath);
-    if (current === target) return "skipped";
-  } catch (err) {
-    if (err.code !== "ENOENT" && err.code !== "EINVAL") throw err;
-  }
-  if (dryRun) {
-    process.stdout.write(`[dry-run] symlink ${linkPath} -> ${target}\n`);
-    return "linked";
-  }
-  await fs.mkdir(join(linkPath, ".."), { recursive: true });
-  // readlink returns EINVAL for both a missing link and an existing non-symlink
-  // file, so unlink alone would silently destroy a real file. lstat lets us
-  // refuse to clobber any existing entry that is not a symlink.
-  let existing;
-  try {
-    existing = await fs.lstat(linkPath);
-  } catch (err) {
-    if (err.code !== "ENOENT") throw err;
-  }
-  if (existing && !existing.isSymbolicLink()) {
-    throw new Error(
-      `refuse to replace ${linkPath} (not a symlink). Remove it manually and retry, or run 'okstra uninstall' first.`,
-    );
-  }
-  if (existing) await fs.unlink(linkPath);
-  await fs.symlink(target, linkPath);
-  return "linked";
-}
-
-async function installLinkMode(repoPath, paths, opts) {
-  const { dryRun, quiet, runtime } = opts;
-  const repoAbs = resolveAbs(repoPath);
-
-  if (!(await dirExists(repoAbs))) {
-    throw new Error(`repo path not found: ${repoAbs}`);
-  }
-  const scriptsDir = join(repoAbs, "scripts");
-  if (!(await dirExists(scriptsDir))) {
-    throw new Error(`<repo>/scripts not found: ${scriptsDir}`);
-  }
-  const agentsDir = join(repoAbs, "agents");
-  if (!(await dirExists(agentsDir))) {
-    throw new Error(`<repo>/agents not found: ${agentsDir}`);
-  }
-
-  if (!quiet) {
-    process.stdout.write(`installing okstra runtime in LINK mode (package ${paths.package})\n`);
-    process.stdout.write(`  runtime: ${runtime}\n`);
-    process.stdout.write(`  repo:   ${repoAbs}\n`);
-    process.stdout.write(`  home:   ${paths.home}\n`);
-  }
-
-  if (!dryRun) {
-    await fs.mkdir(paths.pythonpath, { recursive: true });
-    await fs.mkdir(paths.bin, { recursive: true });
-  }
-
-  for (const pkg of PYTHON_PACKAGES) {
-    const src = join(scriptsDir, pkg);
-    const dst = join(paths.pythonpath, pkg);
-    if (!(await dirExists(src))) {
-      if (!quiet) process.stdout.write(`  python/${pkg}: missing in repo — skipped\n`);
-      continue;
-    }
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  python/${pkg}: ${action}\n`);
-  }
-
-  for (const name of BIN_ENTRYPOINTS) {
-    const src = join(scriptsDir, name);
-    const dst = join(paths.bin, name);
-    if (!(await fileExists(src))) {
-      if (!quiet) process.stdout.write(`  bin/${name}: missing in repo — skipped\n`);
-      continue;
-    }
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  bin/${name}: ${action}\n`);
-  }
-  const promptsSrc = join(repoAbs, "prompts");
-  const promptsDst = join(paths.home, "prompts");
-  if (await dirExists(promptsSrc)) {
-    const action = await ensureSymlink(promptsSrc, promptsDst, { dryRun });
-    if (!quiet) process.stdout.write(`  prompts: ${action}\n`);
-  } else if (!quiet) {
-    process.stdout.write("  prompts: missing in repo — skipped\n");
-  }
-
-
-  const skillTargets = await detectSkillTargets();
-  const installedSkillTargets = await installSkillTargetsLink(repoAbs, skillTargets, { dryRun, quiet });
-  await writeSkillsManifest(paths.home, installedSkillTargets, { dryRun });
-
-  let agentResult = { installed: [] };
-  if (skillTargets.some((target) => target.provider === "claude")) {
-    await pruneOwnedLegacyTransportAgents(paths.home, { dryRun, quiet });
-    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,
-    resolution: opts.resolution,
-    installedAssets: installedAssetOverrides(installedSkillTargets, agentResult.installed),
-  });
-
-  if (!dryRun) {
-    await writeFileAtomic(join(paths.home, "dev-link"), repoAbs + "\n", 0o644);
-    await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
-  }
-  if (!quiet) {
-    process.stdout.write(`  dev-link stamp: ${repoAbs}\n`);
-    process.stdout.write(`  version stamp: ${paths.package}\n`);
-    process.stdout.write("done.\n");
-    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 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",
-    );
-  }
-  return 0;
-
-}
-
-async function detectSkillTargets() {
-  const targets = [];
-  const hasClaude = await dirExists(CLAUDE_HOME);
-  if (hasClaude) {
-    targets.push({ provider: "claude", home: CLAUDE_HOME, skillsDir: CLAUDE_SKILLS_DIR });
-  }
-  targets.push({ provider: "agent", home: AGENTS_HOME, skillsDir: AGENTS_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"),
-    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: 2,
-    installedAt: new Date().toISOString(),
-    skills: installedSkillNames(targets),
-    targets: manifestTargets,
-  };
-  if (dryRun) {
-    process.stdout.write(
-      `[dry-run] write skills manifest: ${data.skills.length} skills across ${data.targets.length} targets\n`,
-    );
-    return;
-  }
-  await writeFileAtomic(
-    join(home, SKILLS_MANIFEST_REL),
-    JSON.stringify(data, null, 2) + "\n",
-    0o644,
-  );
-}
-
-async function writeAgentsManifest(home, names, opts) {
-  const { dryRun = false } = opts ?? {};
-  const data = {
-    version: 1,
-    installedAt: new Date().toISOString(),
-    agents: Array.from(new Set(names)).sort(),
-  };
-  if (dryRun) {
-    process.stdout.write(`[dry-run] write agents manifest: ${data.agents.length} entries\n`);
-    return;
-  }
-  await writeFileAtomic(
-    join(home, AGENTS_MANIFEST_REL),
-    JSON.stringify(data, null, 2) + "\n",
-    0o644,
-  );
-}
-
-async function pruneOwnedLegacyTransportAgents(home, opts) {
-  const { dryRun = false, quiet = false } = opts ?? {};
-  let previous = [];
-  try {
-    const data = JSON.parse(
-      await fs.readFile(join(home, AGENTS_MANIFEST_REL), "utf8"),
-    );
-    if (Array.isArray(data?.agents)) previous = data.agents;
-  } catch (err) {
-    if (err.code !== "ENOENT" && !(err instanceof SyntaxError)) throw err;
-  }
-  const ownedLegacy = LEGACY_TRANSPORT_AGENT_NAMES.filter((name) => (
-    previous.includes(name)
-  ));
-  for (const name of ownedLegacy) {
-    const target = join(CLAUDE_AGENTS_DIR, name);
-    if (dryRun) {
-      process.stdout.write(`[dry-run] remove retired agent ${target}\n`);
-      continue;
-    }
-    try {
-      await fs.unlink(target);
-      if (!quiet) process.stdout.write(`  agents/${name}: removed retired wrapper\n`);
-    } catch (err) {
-      if (err.code !== "ENOENT") throw err;
-    }
-  }
-}
-
-async function writeRuntimeManifest(home, runtime, opts) {
-  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.installedRuntimes.join(",")}\n`);
-    return;
-  }
-  await writeFileAtomic(
-    join(home, RUNTIMES_MANIFEST_REL),
-    JSON.stringify(data, null, 2) + "\n",
-    0o644,
-  );
-}
-
-async function listWorkerFiles(workersRoot) {
-  try {
-    const entries = await fs.readdir(workersRoot, { withFileTypes: true });
-    return entries
-      .filter((e) => (
-        e.isFile() && e.name.endsWith(".md") && !e.name.startsWith("_")
-      ))
-      .map((e) => e.name);
-  } catch (err) {
-    if (err.code === "ENOENT") return [];
-    throw err;
-  }
-}
-
-async function installAgentsCopy(runtimeRoot, opts) {
-  const { refresh, dryRun, quiet } = opts;
-  const srcRoot = join(runtimeRoot, "agents", "workers");
-  const names = await listWorkerFiles(srcRoot);
-  if (names.length === 0) {
-    if (!quiet) process.stdout.write("  agents: runtime/agents/workers empty — skipped\n");
-    return { installed: [] };
-  }
-  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
-  let copied = 0;
-  let skipped = 0;
-  for (const name of names) {
-    const src = join(srcRoot, name);
-    const dst = join(CLAUDE_AGENTS_DIR, name);
-    let needsCopy = refresh;
-    if (!needsCopy) {
-      try {
-        await fs.access(dst);
-        const [a, b] = await Promise.all([hashFile(src), hashFile(dst)]);
-        needsCopy = a !== b;
-      } catch {
-        needsCopy = true;
-      }
-    }
-    if (!needsCopy) {
-      skipped++;
-      continue;
-    }
-    if (dryRun) {
-      process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
-    } else {
-      const buf = await fs.readFile(src);
-      await writeFileAtomic(dst, buf, 0o644);
-    }
-    copied++;
-  }
-  if (!quiet) {
-    process.stdout.write(
-      `  agents: copied=${copied} skipped=${skipped} -> ${CLAUDE_AGENTS_DIR}/ (${names.length} workers)\n`,
-    );
-  }
-  return { installed: names };
-}
-
-async function installAgentsLink(repoAbs, opts) {
-  const { dryRun, quiet } = opts;
-  const srcRoot = join(repoAbs, "agents", "workers");
-  const sourceNames = await listWorkerFiles(srcRoot);
-  const names = [...sourceNames].sort();
-  if (names.length === 0) {
-    if (!quiet) process.stdout.write("  agents: <repo>/agents/workers missing — skipped\n");
-    return { installed: [] };
-  }
-  if (!dryRun) await fs.mkdir(CLAUDE_AGENTS_DIR, { recursive: true });
-  for (const name of sourceNames) {
-    const src = join(srcRoot, name);
-    const dst = join(CLAUDE_AGENTS_DIR, name);
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  agents/${name}: ${action}\n`);
-  }
-  return { installed: names };
-}
-
-async function installNamedTemplate(srcRoot, paths, opts, descriptor) {
-  const { mode, refresh = false, dryRun = false, quiet = false } = opts;
-  const { srcRel, dstRel, label } = descriptor;
-  const src = join(srcRoot, ...srcRel);
-  const dst = join(paths.home, ...dstRel);
-
-  if (!(await fileExists(src))) {
-    if (!quiet) process.stdout.write(`  ${label}: source missing — skipped (${src})\n`);
-    return { installed: false };
-  }
-
-  if (!dryRun) await fs.mkdir(join(dst, ".."), { recursive: true });
-
-  if (mode === "link") {
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  ${label}: ${action} (${dst} -> ${src})\n`);
-    return { installed: action !== "skipped" };
-  }
-
-  // copy mode — hash-skip mirrors copyTreeIfChanged behavior for a single file.
-  let needsCopy = refresh;
-  if (!needsCopy) {
-    try {
-      await fs.access(dst);
-      const [srcHash, dstHash] = await Promise.all([hashFile(src), hashFile(dst)]);
-      needsCopy = srcHash !== dstHash;
-    } catch {
-      needsCopy = true;
-    }
-  }
-
-  if (!needsCopy) {
-    if (!quiet) process.stdout.write(`  ${label}: skipped (hash match)\n`);
-    return { installed: false };
-  }
-
-  if (dryRun) {
-    process.stdout.write(`[dry-run] copy ${src} -> ${dst}\n`);
-  } else {
-    const buf = await fs.readFile(src);
-    await writeFileAtomic(dst, buf, 0o644);
-  }
-  if (!quiet) process.stdout.write(`  ${label}: copied -> ${dst}\n`);
-  return { installed: true };
-}
-
-const SETTINGS_TEMPLATE_DESCRIPTOR = {
-  srcRel: SETTINGS_TEMPLATE_SRC_REL,
-  dstRel: SETTINGS_TEMPLATE_DST_REL,
-  label: "settings template",
-};
-
-async function installSkillsCopy(runtimeRoot, target, opts) {
-  const { refresh, dryRun, quiet } = opts;
-  const srcRoot = join(runtimeRoot, "skills");
-  let copied = 0;
-  let skipped = 0;
-  for (const name of USER_SKILL_NAMES) {
-    const r = await copyTreeIfChanged(
-      join(srcRoot, name),
-      join(target.skillsDir, name),
-      { refresh, dryRun, mode: 0o644 },
-    );
-    copied += r.copied;
-    skipped += r.skipped;
-  }
-  const pruned = await pruneObsoleteSkills(target, opts);
-  if (!quiet) {
-    process.stdout.write(
-      `  ${target.provider} skills: copied=${copied} skipped=${skipped} pruned=${pruned} -> ${target.skillsDir}/ (${USER_SKILL_NAMES.length} skills)\n`,
-    );
-  }
-  return { ...target, installed: [...USER_SKILL_NAMES] };
-}
-
-async function installSkillsLink(repoAbs, target, opts) {
-  const { dryRun, quiet } = opts;
-  const srcRoot = join(repoAbs, "skills");
-  if (!dryRun) await fs.mkdir(target.skillsDir, { recursive: true });
-  for (const name of USER_SKILL_NAMES) {
-    const src = join(srcRoot, name);
-    const dst = join(target.skillsDir, name);
-    const action = await ensureSymlink(src, dst, { dryRun });
-    if (!quiet) process.stdout.write(`  ${target.provider} skills/${name}: ${action}\n`);
-  }
-  const pruned = await pruneObsoleteSkills(target, opts);
-  if (!quiet && pruned > 0) {
-    process.stdout.write(`  ${target.provider} obsolete internal skills: pruned=${pruned}\n`);
-  }
-  return { ...target, installed: [...USER_SKILL_NAMES] };
-}
-
-// Remove former skill directories left by older installs. Exact-name only
-// (OBSOLETE_SKILL_NAMES) — never wildcard-delete okstra-*.
-async function pruneObsoleteSkills(target, opts) {
-  let pruned = 0;
-  for (const name of OBSOLETE_SKILL_NAMES) {
-    const path = join(target.skillsDir, name);
-    if (!(await pathEntryExists(path))) continue;
-    pruned += 1;
-    if (opts.dryRun) {
-      process.stdout.write(`[dry-run] rm ${path}\n`);
-      continue;
-    }
-    await fs.rm(path, { recursive: true, force: true });
-  }
-  return pruned;
-}
-
-async function installSkillTargetsCopy(runtimeRoot, targets, opts) {
-  if (targets.length === 0) {
-    if (!opts.quiet) process.stdout.write("  skills: no skill target 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 skill target 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: "auto",
-  };
-  for (let i = 0; i < args.length; i++) {
-    const a = args[i];
-    if (a === "--dry-run") result.dryRun = true;
-    else if (a === "--refresh") result.refresh = true;
-    else if (a === "-q" || a === "--quiet") result.quiet = true;
-    else if (a === "--runtime" || a.startsWith("--runtime=")) {
-      const parsed = readRuntimeFlag(args, i);
-      result.runtime = validateInstallRuntime(parsed.value);
-      i = parsed.nextIndex;
-    } else if (a === "--link") {
-      const next = args[i + 1];
-      if (!next || next.startsWith("--")) {
-        throw new Error("--link requires a repo path");
-      }
-      result.linkRepo = next;
-      i++;
-    } else {
-      throw new Error(`unknown argument '${a}'`);
-    }
-  }
-  return result;
-}
-
-export async function runInstall(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(INSTALL_USAGE);
-    return 0;
-  }
-
-  let opts;
-  try {
-    opts = parseInstallArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 2;
-  }
-  const pkgRoot = getPackageRoot();
-  const runtimeRoot = join(pkgRoot, "runtime");
-  const paths = await resolvePaths();
-  const runtimeResolution = await resolveInstallRuntime(opts.runtime, "install");
-  if (!runtimeResolution.ok && opts.runtime !== "auto") {
-    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
-    return 2;
-  }
-
-  if (!opts.dryRun) {
-    await fs.mkdir(paths.home, { recursive: true });
-  }
-
-  if (opts.linkRepo) {
-    return await installLinkMode(opts.linkRepo, paths, { ...opts, resolution: runtimeResolution });
-  }
-
-  // copy mode — if a prior dev-link is present, refuse rather than silently overwriting.
-  if (paths["dev-link"]) {
-    throw new Error(
-      `~/.okstra/dev-link is set to ${paths["dev-link"]}. Run 'okstra uninstall' first, then 'okstra install' in copy mode.`,
-    );
-  }
-
-  if (!opts.quiet) {
-    process.stdout.write(`installing okstra runtime (package ${paths.package})\n`);
-    process.stdout.write(`  runtime: ${formatInstallRuntimeLabel(opts.runtime, runtimeResolution)}\n`);
-    process.stdout.write(`  source: ${runtimeRoot}\n`);
-    process.stdout.write(`  home:   ${paths.home}\n`);
-  }
-
-  const pythonResult = await copyTreeIfChanged(
-    join(runtimeRoot, "python"),
-    paths.pythonpath,
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
-  );
-  const binResult = await copyTreeIfChanged(
-    join(runtimeRoot, "bin"),
-    paths.bin,
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
-  );
-  // templates/ tree — the v1 report.css/report.js compatibility assets, the
-  // v2 AI handoff template, and the task-specific html/** tree are consumed by
-  // okstra-render-report-views.py and final-report assembly. They
-  // are NOT covered by installNamedTemplate (which only handles the renamed
-  // settings.local.json sidecar), so without this step copy-mode installs
-  // miss every asset other than that single file. See
-  // okstra-render-report-views.py _TEMPLATES_DIRS for the lookup path.
-  const templatesResult = await copyTreeIfChanged(
-    join(runtimeRoot, "templates"),
-    join(paths.home, "templates"),
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
-  );
-  // schemas/ tree — version-selected final-report v1/v2 schemas are loaded by
-  // okstra_ctl.final_report_schema. They support bundle excerpts, legacy
-  // re-renders, new task HTML, and validate-run. Link mode resolves the same
-  // files through the repo symlink.
-  const schemasResult = await copyTreeIfChanged(
-    join(runtimeRoot, "schemas"),
-    join(paths.home, "schemas"),
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
-  );
-  // validators/ tree — validate-implementation-plan-stages.py (+ lib/) is
-  // resolved at runtime by run.py / validate-run.py via the installed package's
-  // `parents[2]/validators`, i.e. ~/.okstra/lib/validators. Without this step a
-  // copy-mode UPGRADE bumps the version stamp but never refreshes the
-  // validators, so a stale validator (e.g. a pre-renumber section schema)
-  // survives and render-bundle's stage-structure check diverges from the
-  // current template (observed: render-bundle demanding `## 4.5 Stage Map`
-  // while the report + wizard validator use `## 5.5`). Mode 0o755 preserves the
-  // executable .sh helpers in the tree.
-  const validatorsResult = await copyTreeIfChanged(
-    join(runtimeRoot, "validators"),
-    join(paths.home, "lib", "validators"),
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o755 },
-  );
-  // prompts/ tree — lead/internal operating contracts (prompts/lead/*.md) and
-  // the coding-preflight resource pack (prompts/coding-preflight/*) are read at
-  // runtime by the lead and executor via absolute ~/.okstra/prompts/ paths
-  // (paths.py OKSTRA_LEAD_CONTRACT_PATH / OKSTRA_CODING_PREFLIGHT_DIR). Run-prep
-  // reads prompts/profiles + launch.template from the package runtime dir, but
-  // the lead's runtime Read needs them under the home tree like templates.
-  const promptsResult = await copyTreeIfChanged(
-    join(runtimeRoot, "prompts"),
-    join(paths.home, "prompts"),
-    { refresh: opts.refresh, dryRun: opts.dryRun, mode: 0o644 },
-  );
-
-  if (!opts.quiet) {
-    summarise("python", pythonResult, paths.pythonpath);
-    summarise("bin", binResult, paths.bin);
-    summarise("templates", templatesResult, join(paths.home, "templates"));
-    summarise("schemas", schemasResult, join(paths.home, "schemas"));
-    summarise("validators", validatorsResult, join(paths.home, "lib", "validators"));
-    summarise("prompts", promptsResult, join(paths.home, "prompts"));
-  }
-
-  if (pythonResult.missingSource && binResult.missingSource) {
-    process.stderr.write(
-      "warning: runtime/{python,bin} are both empty. Runtime sync (build step) has not been performed.\n",
-    );
-  }
-  if (templatesResult.missingSource) {
-    process.stderr.write(
-      "warning: runtime/templates is empty. final-report Markdown and HTML templates will be missing — re-run the build step.\n",
-    );
-  }
-  if (schemasResult.missingSource) {
-    process.stderr.write(
-      "warning: runtime/schemas is empty. final-report schema validation + excerpt generation will be unavailable — re-run the build step.\n",
-    );
-  }
-  if (validatorsResult.missingSource) {
-    process.stderr.write(
-      "warning: runtime/validators is empty. stage-structure / report validation will use stale or missing validators — re-run the build step.\n",
-    );
-  }
-  if (promptsResult.missingSource) {
-    process.stderr.write(
-      "warning: runtime/prompts is empty. lead contracts + coding-preflight resources will be missing — re-run the build step.\n",
-    );
-  }
-
-  const skillTargets = await detectSkillTargets();
-  const installedSkillTargets = await installSkillTargetsCopy(runtimeRoot, skillTargets, opts);
-  await writeSkillsManifest(paths.home, installedSkillTargets, { dryRun: opts.dryRun });
-
-  let agentResult = { installed: [] };
-  if (skillTargets.some((target) => target.provider === "claude")) {
-    await pruneOwnedLegacyTransportAgents(paths.home, opts);
-    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,
-    resolution: runtimeResolution,
-    installedAssets: installedAssetOverrides(installedSkillTargets, agentResult.installed),
-  });
-
-  if (!opts.dryRun) {
-    await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
-  }
-  if (!opts.quiet) {
-    // The source is already named at the top of the run; what the stamp line
-    // could not say is whether this install moved anything. `copied=0 skipped=N`
-    // plus a bare version reads identically for "already current" and "an older
-    // payload just landed over a newer home" — the latter cost a full run,
-    // caught only by hand-diffing installed files.
-    process.stdout.write(
-      `  version stamp: ${formatVersionTransition(paths.version, paths.package)}\n`,
-    );
-    process.stdout.write("done.\n");
-    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 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",
-    );
-  }
-  return 0;
-}
-
-async function skillTargetDriftReasons(targets) {
-  const reasons = [];
-  for (const target of targets) {
-    for (const name of USER_SKILL_NAMES) {
-      const skillPath = join(target.skillsDir, name, "SKILL.md");
-      if (!(await fileExists(skillPath))) {
-        reasons.push(`missing ${skillPath}`);
-      }
-    }
-  }
-  return reasons;
-}
-
-async function promptResourceDriftReasons(paths) {
-  const reasons = [];
-  for (const parts of REQUIRED_PROMPT_RESOURCE_FILES) {
-    const path = join(paths.home, ...parts);
-    if (!(await fileExists(path))) reasons.push(`missing ${path}`);
-  }
-  return reasons;
-}
-
-async function hostRelayDriftReasons(paths) {
-  const reasons = [];
-  const hostsRoot = join(paths.pythonpath, "okstra_ctl", "adapters", "hosts");
-  let entries;
-  try {
-    entries = await fs.readdir(hostsRoot, { withFileTypes: true });
-  } catch (err) {
-    if (err.code === "ENOENT") return [`missing ${hostsRoot}`];
-    throw err;
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) continue;
-    const adapterRoot = join(hostsRoot, entry.name);
-    const manifestPath = join(adapterRoot, "manifest.json");
-    if (!(await fileExists(manifestPath))) continue;
-    let manifest;
-    try {
-      manifest = JSON.parse(await fs.readFile(manifestPath, "utf8"));
-    } catch {
-      reasons.push(`invalid ${manifestPath}`);
-      continue;
-    }
-    const relayContract = manifest?.relayContract;
-    if (typeof relayContract !== "string" || !relayContract) {
-      reasons.push(`invalid relayContract in ${manifestPath}`);
-      continue;
-    }
-    const relayPath = resolveAbs(adapterRoot, relayContract);
-    const relayRelative = relative(adapterRoot, relayPath);
-    if (relayRelative.startsWith("..") || resolveAbs(adapterRoot) === relayPath) {
-      reasons.push(`invalid relayContract in ${manifestPath}`);
-    } else if (!(await fileExists(relayPath))) {
-      reasons.push(`missing ${relayPath}`);
-    }
-  }
-  return reasons;
-}
-
-async function agentDriftReasons(paths) {
-  const reasons = [];
-  const workersDir = join(paths.agents, "workers");
-  const expected = await listWorkerFiles(workersDir);
-  if (expected.length === 0) return reasons;
-  for (const name of expected) {
-    const target = join(CLAUDE_AGENTS_DIR, name);
-    try {
-      const lst = await fs.lstat(target);
-      if (lst.isSymbolicLink()) {
-        try {
-          await fs.stat(target);
-        } catch {
-          reasons.push(`dangling symlink ${target}`);
-        }
-      }
-    } catch {
-      reasons.push(`missing agent ${target}`);
-    }
-  }
-  return reasons;
-}
-
-// What the stamp did, not just where it landed: `0.165.3 -> 0.166.0` and
-// `0.166.0 (unchanged)` are the two cases a bare version line cannot tell apart,
-// and they mean opposite things about whether the install did anything.
-export function formatVersionTransition(previous, next) {
-  const from = String(previous ?? "").trim();
-  if (!from) return next;
-  return from === next ? `${next} (unchanged)` : `${from} -> ${next}`;
-}
-
-function summarise(label, result, target) {
-  if (result.missingSource) {
-    process.stdout.write(`  ${label}: source directory missing — skipped\n`);
-    return;
-  }
-  process.stdout.write(
-    `  ${label}: copied=${result.copied} skipped=${result.skipped} -> ${target}\n`,
-  );
-}
-
-// `0.156.0` → [0, 156, 0]. Anything else → null, so a caller falls back to the
-// plain inequality test rather than guessing an ordering.
-function parseSemver(value) {
-  const match = /^(\d+)\.(\d+)\.(\d+)/.exec(String(value ?? "").trim());
-  return match ? match.slice(1, 4).map(Number) : null;
-}
-
-export function installedStampIsNewer(stamp, packageVersion) {
-  const installed = parseSemver(stamp);
-  const running = parseSemver(packageVersion);
-  if (!installed || !running) return false;
-  for (let i = 0; i < 3; i++) {
-    if (installed[i] !== running[i]) return installed[i] > running[i];
-  }
-  return false;
-}
-
-export function parseEnsureInstalledArgs(args) {
-  const result = {
-    quiet: false,
-    runtime: "auto",
-  };
-  for (let i = 0; i < args.length; i++) {
-    const arg = args[i];
-    if (arg === "-q" || arg === "--quiet") {
-      result.quiet = true;
-    } else if (arg === "--runtime" || arg.startsWith("--runtime=")) {
-      const parsed = readRuntimeFlag(args, i);
-      result.runtime = validateInstallRuntime(parsed.value);
-      i = parsed.nextIndex;
-    } else {
-      throw new Error(`unknown argument '${arg}'`);
-    }
-  }
-  return result;
-}
-
-export async function runEnsureInstalled(args) {
-  if (args.includes("--help") || args.includes("-h")) {
-    process.stdout.write(ENSURE_USAGE);
-    return 0;
-  }
-  let opts;
-  try {
-    opts = parseEnsureInstalledArgs(args);
-  } catch (err) {
-    process.stderr.write(`error: ${err.message}\n`);
-    return 2;
-  }
-  const paths = await resolvePaths();
-  const runtimeResolution = await resolveInstallRuntime(opts.runtime, "ensure-installed");
-  if (!runtimeResolution.ok && opts.runtime !== "auto") {
-    process.stderr.write(`error: ${runtimeResolution.reason}\n`);
-    return 2;
-  }
-
-  // A newer install than the package running this check means an upgrade
-  // arrived by another route — `npx -y okstra@latest install`, or an install
-  // from a checkout — while this command still resolves an older payload.
-  // Reinstalling here would quietly DOWNGRADE the user's runtime, and every
-  // skill preflight calls this, so the downgrade lands on the next command
-  // after the upgrade. Refuse and say so; an explicit `okstra install` is
-  // still honoured, because that one is the user's own decision.
-  if (installedStampIsNewer(paths.version, paths.package)) {
-    process.stderr.write(
-      `okstra: installed runtime ${paths.version} is newer than this package ` +
-        `(${paths.package}) — skipping auto-install so it is not downgraded. ` +
-        `Run 'okstra install' explicitly to force this package's payload, or ` +
-        `update the okstra package itself.\n`,
-    );
-    return 0;
-  }
-
-  const reasons = [];
-  if (!paths.version) reasons.push("no version stamp");
-  else if (paths.version !== paths.package) {
-    reasons.push(`version drift (stamp=${paths.version}, package=${paths.package})`);
-  }
-  if (!(await dirExists(paths.pythonpath))) reasons.push(`missing ${paths.pythonpath}`);
-  if (!(await dirExists(paths.agents))) reasons.push(`missing agents dir ${paths.agents}`);
-  for (const relative of [
-    ["schemas", "final-report-v2.0.schema.json"],
-    ["templates", "reports", "final-report-v2.template.md"],
-    ["templates", "reports", "html", "base.template.html"],
-  ]) {
-    const installedPath = join(paths.home, ...relative);
-    if (!(await fileExists(installedPath))) reasons.push(`missing ${installedPath}`);
-  }
-  for (const reason of await promptResourceDriftReasons(paths)) {
-    reasons.push(reason);
-  }
-  for (const reason of await hostRelayDriftReasons(paths)) {
-    reasons.push(reason);
-  }
-  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);
-    }
-  }
-
-  if (reasons.length === 0) {
-    if (!opts.quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);
-    return 0;
-  }
-
-  process.stderr.write(`okstra runtime needs install: ${reasons.join("; ")}\n`);
-  const installArgs = ["--runtime", opts.runtime];
-  if (opts.quiet) installArgs.push("-q");
-  return await runInstall(installArgs);
-}