okstra 0.1.0

package/runtime/validators/validate-workflow.sh

@@ -0,0 +1,190 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+SOURCE_PATH="${BASH_SOURCE[0]}"
+while [[ -L "$SOURCE_PATH" ]]; do
+  SOURCE_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+  SOURCE_PATH="$(readlink "$SOURCE_PATH")"
+  [[ "$SOURCE_PATH" != /* ]] && SOURCE_PATH="$SOURCE_DIR/$SOURCE_PATH"
+done
+
+SCRIPT_DIR="$(cd -P "$(dirname "$SOURCE_PATH")" && pwd)"
+WORKSPACE_ROOT="$(cd -P "$SCRIPT_DIR/.." && pwd)"
+PROJECT_ID="okstra-validation"
+PROJECT_ROOT="${OKSTRA_VALIDATION_PROJECT_ROOT:-/tmp/okstra-validate.workflow}"
+WORKSPACE_APP_PATH="$PROJECT_ROOT"
+OKSTRA_SCRIPT="$WORKSPACE_ROOT/scripts/okstra.sh"
+RUN_VALIDATOR_SCRIPT="$WORKSPACE_ROOT/validators/validate-run.py"
+SOURCE_ASSET_ROOT="$WORKSPACE_ROOT/agents"
+TASK_TYPE="final-verification"
+MARKER="MANUAL-VALIDATION-MARKER"
+PRIMARY_TASK_GROUP="validation"
+PRIMARY_TASK_ID="asset-refresh-and-reference-expectations"
+PRIMARY_BRIEF_FILENAME="validation-brief-primary.md"
+SECONDARY_TASK_GROUP="discovery"
+SECONDARY_TASK_ID="task-catalog"
+SECONDARY_BRIEF_FILENAME="validation-brief-secondary.md"
+LATEST_TASK_RELATIVE_PATH=".project-docs/okstra/discovery/latest-task.json"
+TASK_CATALOG_RELATIVE_PATH=".project-docs/okstra/discovery/task-catalog.json"
+
+# shellcheck source=lib/common.sh
+source "$SCRIPT_DIR/lib/common.sh"
+# shellcheck source=lib/paths.sh
+source "$SCRIPT_DIR/lib/paths.sh"
+# shellcheck source=lib/fixtures.sh
+source "$SCRIPT_DIR/lib/fixtures.sh"
+# shellcheck source=lib/runners.sh
+source "$SCRIPT_DIR/lib/runners.sh"
+# shellcheck source=lib/validate-assets.sh
+source "$SCRIPT_DIR/lib/validate-assets.sh"
+# shellcheck source=lib/validate-prompt-metadata.sh
+source "$SCRIPT_DIR/lib/validate-prompt-metadata.sh"
+# shellcheck source=lib/validate-tasks.sh
+source "$SCRIPT_DIR/lib/validate-tasks.sh"
+# shellcheck source=lib/summary.sh
+source "$SCRIPT_DIR/lib/summary.sh"
+
+trap 'on_error "$LINENO"' ERR
+
+require_file "$OKSTRA_SCRIPT"
+require_file "$RUN_VALIDATOR_SCRIPT"
+
+validate_project_root_safety
+
+PRIMARY_BRIEF_PATH="$PROJECT_ROOT/$PRIMARY_BRIEF_FILENAME"
+SECONDARY_BRIEF_PATH="$PROJECT_ROOT/$SECONDARY_BRIEF_FILENAME"
+DISCOVERY_FILE="$PROJECT_ROOT/$LATEST_TASK_RELATIVE_PATH"
+CATALOG_FILE="$PROJECT_ROOT/$TASK_CATALOG_RELATIVE_PATH"
+MARKER_FILE="$PROJECT_ROOT/.claude/agents/codex-worker.md"
+PRIMARY_TASK_KEY="$(task_key "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")"
+SECONDARY_TASK_KEY="$(task_key "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID")"
+PRIMARY_REFERENCE_EXPECTATIONS_FILE="$(task_root "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID")/instruction-set/reference-expectations.md"
+SECONDARY_REFERENCE_EXPECTATIONS_FILE="$(task_root "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID")/instruction-set/reference-expectations.md"
+
+step "Resetting the validation root"
+reset_validation_root
+pass "Validation root reset: $PROJECT_ROOT"
+
+step "Writing validation briefs for multiple tasks"
+write_validation_brief \
+  "$PRIMARY_BRIEF_PATH" \
+  "Primary validation brief for reference expectations" \
+  "$PRIMARY_TASK_GROUP" \
+  "$PRIMARY_TASK_ID" \
+  "verify the initial task bundle and discovery pointer"
+write_validation_brief \
+  "$SECONDARY_BRIEF_PATH" \
+  "Secondary validation brief for discovery catalog" \
+  "$SECONDARY_TASK_GROUP" \
+  "$SECONDARY_TASK_ID" \
+  "verify task catalog retention across multiple prepared tasks"
+require_file "$PRIMARY_BRIEF_PATH"
+require_file "$SECONDARY_BRIEF_PATH"
+pass "Validation briefs created for primary and secondary tasks"
+
+step "Running the initial render-only okstra validation for the primary task"
+if ! run_okstra "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" "$PRIMARY_BRIEF_FILENAME"; then
+  fail "Initial okstra render-only validation for the primary task failed"
+fi
+pass "Primary task render-only validation completed"
+
+step "Checking seeded assets and primary task discovery artifacts"
+if ! validate_seeded_assets match; then
+  fail "Seeded project-local okstra assets are missing or do not match the source files"
+fi
+if ! validate_reference_expectations "$PRIMARY_BRIEF_PATH" "$PRIMARY_REFERENCE_EXPECTATIONS_FILE" "$PRIMARY_TASK_KEY"; then
+  fail "Primary reference-expectations.md does not preserve the expected brief content"
+fi
+if ! validate_task_artifacts "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID"; then
+  fail "Primary task manifest or run manifest validation failed"
+fi
+if ! validate_worker_prompt_metadata "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID"; then
+  fail "Primary worker prompt metadata validation failed"
+fi
+if ! validate_latest_task_pointer "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID"; then
+  fail "latest-task.json did not point to the primary task after the first run"
+fi
+if ! validate_task_catalog "$PRIMARY_TASK_KEY" "$PRIMARY_TASK_KEY"; then
+  fail "task-catalog.json did not preserve the expected primary task entry"
+fi
+pass "Primary task discovery artifacts are valid"
+
+step "Preparing validator fixture artifacts for the primary task"
+if ! prepare_run_validator_fixture "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" codex; then
+  fail "Failed to prepare validator fixture artifacts for the primary task"
+fi
+pass "Primary task validator fixture prepared with an intentionally missing Codex prompt history file"
+
+step "Ensuring the run validator rejects attempted workers without prompt history"
+if ! run_validator_expectation "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" failed "Codex worker with status \`timeout\` is missing worker prompt history file"; then
+  fail "Run validator did not reject the missing worker prompt history artifact"
+fi
+pass "Run validator rejected the missing worker prompt history artifact as expected"
+
+step "Restoring the missing worker prompt history file and rerunning the validator"
+if ! write_worker_prompt_history_fixture "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" codex; then
+  fail "Failed to write the missing worker prompt history fixture"
+fi
+if ! run_validator_expectation "$PRIMARY_TASK_GROUP" "$PRIMARY_TASK_ID" passed; then
+  fail "Run validator did not pass after restoring the worker prompt history artifact"
+fi
+pass "Run validator passed after the missing worker prompt history artifact was restored"
+
+step "Running a second render-only okstra validation for the secondary task"
+if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME"; then
+  fail "Render-only validation for the secondary task failed"
+fi
+pass "Secondary task render-only validation completed"
+
+step "Checking that latest-task.json moves while task-catalog.json retains both tasks"
+if ! validate_reference_expectations "$SECONDARY_BRIEF_PATH" "$SECONDARY_REFERENCE_EXPECTATIONS_FILE" "$SECONDARY_TASK_KEY"; then
+  fail "Secondary reference-expectations.md does not preserve the expected brief content"
+fi
+if ! validate_task_artifacts "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
+  fail "Secondary task manifest or run manifest validation failed"
+fi
+if ! validate_worker_prompt_metadata "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
+  fail "Secondary worker prompt metadata validation failed"
+fi
+if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
+  fail "latest-task.json did not point to the secondary task after the second run"
+fi
+if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
+  fail "task-catalog.json did not preserve both prepared tasks"
+fi
+pass "latest-task.json and task-catalog.json now reflect distinct primary and secondary tasks"
+
+step "Verifying that rerun without refresh preserves project-local assets"
+require_file "$MARKER_FILE"
+printf '\n%s\n' "$MARKER" >>"$MARKER_FILE"
+assert_contains "$MARKER_FILE" "$MARKER"
+if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME"; then
+  fail "Secondary task rerun without refresh failed"
+fi
+assert_contains "$MARKER_FILE" "$MARKER"
+if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
+  fail "latest-task.json changed unexpectedly during secondary rerun without refresh"
+fi
+if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
+  fail "task-catalog.json changed unexpectedly during secondary rerun without refresh"
+fi
+pass "Rerun without refresh preserved the modified project-local asset and retained both catalog entries"
+
+step "Verifying that rerun with refresh regenerates project-local assets"
+if ! run_okstra "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID" "$SECONDARY_BRIEF_FILENAME" --refresh-assets; then
+  fail "Secondary task rerun with --refresh-assets failed"
+fi
+assert_not_contains "$MARKER_FILE" "$MARKER"
+if ! validate_seeded_assets match; then
+  fail "Refreshed project-local okstra assets do not match the source files"
+fi
+if ! validate_latest_task_pointer "$SECONDARY_TASK_GROUP" "$SECONDARY_TASK_ID"; then
+  fail "latest-task.json became invalid after refresh"
+fi
+if ! validate_task_catalog "$SECONDARY_TASK_KEY" "$PRIMARY_TASK_KEY" "$SECONDARY_TASK_KEY"; then
+  fail "task-catalog.json became invalid after refresh"
+fi
+pass "Refresh regenerated the mapped project-local okstra assets while preserving both catalog entries"
+
+print_summary

package/src/doctor.mjs

@@ -0,0 +1,127 @@
+import { promises as fs } from "node:fs";
+import { spawn } from "node:child_process";
+import { join } from "node:path";
+import { resolvePaths } from "./paths.mjs";
+
+const USAGE = `okstra doctor — diagnose the installed runtime
+
+Usage:
+  okstra doctor               Run all checks and print a summary
+  okstra doctor --json        Machine-readable result
+
+Checks:
+  - python3 binary and version (>= 3.10)
+  - okstra_project module importable from $HOME/.okstra/lib/python
+  - okstra_ctl module importable
+  - bash entrypoints present and executable in $HOME/.okstra/bin
+  - agents/ directory exists inside the okstra package
+  - version stamp matches package version
+`;
+
+async function pathExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function runProcess(cmd, args, opts = {}) {
+  return new Promise((resolve) => {
+    const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], ...opts });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (b) => (stdout += b.toString()));
+    child.stderr.on("data", (b) => (stderr += b.toString()));
+    child.on("error", (err) => resolve({ code: -1, stdout, stderr: err.message }));
+    child.on("close", (code) => resolve({ code, stdout, stderr }));
+  });
+}
+
+async function checkPython3() {
+  const r = await runProcess("python3", ["--version"]);
+  if (r.code !== 0) return { ok: false, detail: `python3 not found: ${r.stderr.trim() || "missing binary"}` };
+  const out = (r.stdout + r.stderr).trim();
+  const m = out.match(/Python\s+(\d+)\.(\d+)/);
+  if (!m) return { ok: false, detail: `unparsable python version: ${out}` };
+  const [_, maj, min] = m.map(Number);
+  if (maj < 3 || (maj === 3 && min < 10)) {
+    return { ok: false, detail: `python ${maj}.${min} is too old (need 3.10+)` };
+  }
+  return { ok: true, detail: out };
+}
+
+async function checkPythonImport(moduleName, pythonpath) {
+  const r = await runProcess("python3", ["-c", `import ${moduleName}; print(${moduleName}.__name__)`], {
+    env: { ...process.env, PYTHONPATH: pythonpath },
+  });
+  if (r.code !== 0) {
+    return { ok: false, detail: `import ${moduleName} failed: ${r.stderr.trim().split("\n").pop()}` };
+  }
+  return { ok: true, detail: `${moduleName} importable` };
+}
+
+async function checkBashEntry(binDir, name) {
+  const p = join(binDir, name);
+  if (!(await pathExists(p))) return { ok: false, detail: `missing ${p}` };
+  try {
+    const st = await fs.stat(p);
+    if (!(st.mode & 0o111)) return { ok: false, detail: `${name} not executable` };
+  } catch (err) {
+    return { ok: false, detail: `stat ${name} failed: ${err.message}` };
+  }
+  return { ok: true, detail: `${name} OK` };
+}
+
+async function check(name, fn) {
+  try {
+    const result = await fn();
+    return { name, ...result };
+  } catch (err) {
+    return { name, ok: false, detail: `unexpected error: ${err.message}` };
+  }
+}
+
+export async function run(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(USAGE);
+    return 0;
+  }
+  const jsonMode = args.includes("--json");
+  const paths = await resolvePaths();
+
+  const results = [
+    await check("python3", checkPython3),
+    await check("okstra_project import", () => checkPythonImport("okstra_project", paths.pythonpath)),
+    await check("okstra_ctl import", () => checkPythonImport("okstra_ctl", paths.pythonpath)),
+    await check("agents dir", async () =>
+      (await pathExists(paths.agents))
+        ? { ok: true, detail: paths.agents }
+        : { ok: false, detail: `not found: ${paths.agents}` },
+    ),
+    await check("bin: okstra.sh", () => checkBashEntry(paths.bin, "okstra.sh")),
+    await check("bin: okstra-codex-exec.sh", () => checkBashEntry(paths.bin, "okstra-codex-exec.sh")),
+    await check("bin: okstra-gemini-exec.sh", () => checkBashEntry(paths.bin, "okstra-gemini-exec.sh")),
+    await check("bin: okstra-central.sh", () => checkBashEntry(paths.bin, "okstra-central.sh")),
+    await check("version stamp", async () =>
+      paths.version === paths.package
+        ? { ok: true, detail: paths.version }
+        : { ok: false, detail: `stamp=${paths.version || "(none)"} package=${paths.package}` },
+    ),
+  ];
+
+  const allOk = results.every((r) => r.ok);
+
+  if (jsonMode) {
+    process.stdout.write(`${JSON.stringify({ ok: allOk, paths, checks: results }, null, 2)}\n`);
+    return allOk ? 0 : 1;
+  }
+
+  for (const r of results) {
+    const mark = r.ok ? "OK  " : "FAIL";
+    process.stdout.write(`  [${mark}] ${r.name}: ${r.detail}\n`);
+  }
+  process.stdout.write(`\nresult: ${allOk ? "OK" : "FAIL"}\n`);
+  return allOk ? 0 : 1;
+}

package/src/install.mjs

@@ -0,0 +1,355 @@
+import { promises as fs } from "node:fs";
+import { createHash } from "node:crypto";
+import { join, relative, resolve as resolveAbs } from "node:path";
+import { getPackageRoot } from "./version.mjs";
+import { resolvePaths } from "./paths.mjs";
+
+const PYTHON_PACKAGES = ["okstra_project", "okstra_ctl", "okstra_token_usage", "lib"];
+const BIN_ENTRYPOINTS = [
+  "okstra.sh",
+  "okstra-codex-exec.sh",
+  "okstra-gemini-exec.sh",
+  "okstra-central.sh",
+  "okstra-token-usage.py",
+  "okstra-error-log.py",
+];
+
+const INSTALL_USAGE = `okstra install — install runtime into ~/.okstra
+
+Usage:
+  okstra install              Install/update runtime (copy mode)
+  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   <- packages/okstra/runtime/python
+  ${"$HOME"}/.okstra/bin           <- packages/okstra/runtime/bin
+  ${"$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/dev-link         <- <repo> path stamp
+  ${"$HOME"}/.okstra/version          <- installed package version stamp
+
+agents/ is NOT copied — it stays inside the package (copy mode) or is
+resolved to <repo>/agents (link mode) via 'okstra paths --field agents'.
+`;
+
+const ENSURE_USAGE = `okstra ensure-installed — idempotent install check
+
+Usage:
+  okstra ensure-installed     Verify install; reinstall if version/files drift
+  okstra ensure-installed -q  Same, but suppress success output
+
+Skills call this on every run. Returns 0 quickly when the install is fresh.
+`;
+
+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* 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);
+}
+
+async function copyTreeIfChanged(srcRoot, dstRoot, opts) {
+  const { refresh = false, dryRun = false, mode } = opts ?? {};
+  let copied = 0;
+  let skipped = 0;
+  let missingSource = false;
+
+  if (!(await dirExists(srcRoot))) {
+    missingSource = true;
+    return { copied, skipped, 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++;
+  }
+
+  return { copied, skipped, 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 });
+  try {
+    await fs.unlink(linkPath);
+  } catch (err) {
+    if (err.code !== "ENOENT") {
+      // Existing directory or regular file — refuse to clobber automatically.
+      throw new Error(
+        `refuse to replace ${linkPath} (not a symlink). Remove it manually and retry, or run 'okstra uninstall' first.`,
+      );
+    }
+  }
+  await fs.symlink(target, linkPath);
+  return "linked";
+}
+
+async function installLinkMode(repoPath, paths, opts) {
+  const { dryRun, quiet } = 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(`  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`);
+  }
+
+  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");
+  }
+  return 0;
+}
+
+async function fileExists(p) {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function parseInstallArgs(args) {
+  const result = {
+    dryRun: false,
+    refresh: false,
+    quiet: false,
+    linkRepo: null,
+  };
+  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 === "--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;
+  }
+
+  const opts = parseInstallArgs(args);
+  const pkgRoot = getPackageRoot();
+  const runtimeRoot = join(pkgRoot, "runtime");
+  const paths = await resolvePaths();
+
+  if (!opts.dryRun) {
+    await fs.mkdir(paths.home, { recursive: true });
+  }
+
+  if (opts.linkRepo) {
+    return await installLinkMode(opts.linkRepo, paths, opts);
+  }
+
+  // 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(`  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 },
+  );
+
+  if (!opts.quiet) {
+    summarise("python", pythonResult, paths.pythonpath);
+    summarise("bin", binResult, paths.bin);
+  }
+
+  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 (!opts.dryRun) {
+    await writeFileAtomic(join(paths.home, "version"), paths.package + "\n", 0o644);
+  }
+  if (!opts.quiet) {
+    process.stdout.write(`  version stamp: ${paths.package}\n`);
+    process.stdout.write("done.\n");
+  }
+  return 0;
+}
+
+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`,
+  );
+}
+
+export async function runEnsureInstalled(args) {
+  if (args.includes("--help") || args.includes("-h")) {
+    process.stdout.write(ENSURE_USAGE);
+    return 0;
+  }
+  const quiet = args.includes("-q") || args.includes("--quiet");
+  const paths = await resolvePaths();
+
+  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}`);
+
+  if (reasons.length === 0) {
+    if (!quiet) process.stdout.write(`okstra runtime OK (package ${paths.package})\n`);
+    return 0;
+  }
+
+  process.stderr.write(`okstra runtime needs install: ${reasons.join("; ")}\n`);
+  return await runInstall(quiet ? ["-q"] : []);
+}