okstra 0.174.0 → 0.176.0

package/dist/commands/lifecycle/install.mjs

@@ -0,0 +1,1077 @@
+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);
+}
+//# sourceMappingURL=install.mjs.map