@cairnkeep/cli 2.9.0 → 2.12.0

package/scripts/harness-registry.mjs

@@ -0,0 +1,126 @@
+import { pathToFileURL } from "node:url";
+
+/**
+ * Declarative registry for every CLI harness supported by project setup.
+ *
+ * Keep harness-specific project assets and lifecycle guidance here. Consumers
+ * must derive choices from this registry instead of maintaining local lists.
+ */
+const DEFINITIONS = [
+  {
+    id: "claude",
+    title: "Claude Code",
+    launcher: { template: "start-claude.sh.template", path: ".ai/start-claude.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync --apply",
+  },
+  {
+    id: "opencode",
+    title: "OpenCode",
+    launcher: { template: "start-opencode.sh.template", path: ".ai/start-opencode.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync --apply",
+  },
+  {
+    id: "pi",
+    title: "Pi",
+    launcher: { template: "start-pi.sh.template", path: ".ai/start-pi.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync-pi --apply",
+  },
+  {
+    id: "kimi",
+    title: "Kimi Code",
+    launcher: { template: "start-kimi.sh.template", path: ".ai/start-kimi.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: "cairn sync-kimi --apply",
+  },
+  {
+    id: "qwen",
+    title: "Qwen Code",
+    launcher: { template: "start-qwen.sh.template", path: ".ai/start-qwen.sh", mode: 0o755 },
+    project_assets: [],
+    machine_sync: null,
+  },
+  {
+    id: "codex",
+    title: "Codex CLI",
+    launcher: { template: "start-codex.sh.template", path: ".ai/start-codex.sh", mode: 0o755 },
+    project_assets: [
+      {
+        template: "codex-config.toml.template",
+        path: ".codex/config.toml",
+        mode: 0o644,
+        memory: "local",
+        // An existing operator-owned TOML file is valid when doctor finds the
+        // exact MCP table; it must not become setup/uninstall-owned.
+        required: false,
+      },
+    ],
+    machine_sync: null,
+  },
+];
+
+function freezeDefinition(definition) {
+  const launcher = Object.freeze({ ...definition.launcher });
+  const projectAssets = Object.freeze(definition.project_assets.map((asset) => Object.freeze({ ...asset })));
+  return Object.freeze({ ...definition, launcher, project_assets: projectAssets });
+}
+
+export const HARNESS_REGISTRY = Object.freeze(DEFINITIONS.map(freezeDefinition));
+export const HARNESS_IDS = Object.freeze(HARNESS_REGISTRY.map(({ id }) => id));
+
+export function harnessDefinition(id) {
+  return HARNESS_REGISTRY.find((definition) => definition.id === id) ?? null;
+}
+
+export function harnessProjectAssets(id, memory = "local") {
+  const definition = harnessDefinition(id);
+  if (!definition) throw new Error(`Unknown harness: ${id}.`);
+  return Object.freeze([
+    definition.launcher,
+    ...definition.project_assets.filter((asset) => !asset.memory || asset.memory === memory),
+  ]);
+}
+
+export function requiredHarnessAssetPaths(harnesses, memory = "local") {
+  return Object.freeze(harnesses.flatMap((id) => harnessProjectAssets(id, memory)
+    .filter((asset) => asset.required !== false)
+    .map(({ path }) => path)));
+}
+
+export function machineSyncCommand(harnesses) {
+  const commands = harnesses.map(harnessDefinition).map((definition) => definition?.machine_sync).filter(Boolean);
+  if (commands.includes("cairn sync-pi --apply")) return "cairn sync-pi --apply";
+  return commands[0] ?? null;
+}
+
+function validateRegistry() {
+  if (new Set(HARNESS_IDS).size !== HARNESS_IDS.length) throw new Error("Harness registry contains duplicate IDs.");
+  for (const definition of HARNESS_REGISTRY) {
+    if (!/^[a-z][a-z0-9-]*$/.test(definition.id) || !definition.title) throw new Error("Invalid harness registry entry.");
+    const assets = [definition.launcher, ...definition.project_assets];
+    if (new Set(assets.map(({ path }) => path)).size !== assets.length) throw new Error(`Duplicate project asset for ${definition.id}.`);
+    for (const asset of assets) {
+      if (!asset.template || !asset.path || ![0o600, 0o644, 0o755].includes(asset.mode)) throw new Error(`Invalid project asset for ${definition.id}.`);
+    }
+  }
+}
+
+validateRegistry();
+
+// The legacy bootstrap is a shell script for Bash 3.2 portability. This bounded
+// output lets it consume the same registry without parsing JavaScript or JSON.
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+  if (!new Set(["bootstrap-assets", "ids"]).has(process.argv[2])) {
+    console.error("Usage: node harness-registry.mjs bootstrap-assets|ids");
+    process.exitCode = 2;
+  } else if (process.argv[2] === "ids") {
+    process.stdout.write(`${HARNESS_IDS.join(" ")}\n`);
+  } else {
+    for (const definition of HARNESS_REGISTRY) {
+      const asset = definition.launcher;
+      process.stdout.write(`${asset.template}\t${asset.path}\t${asset.mode.toString(8)}\n`);
+    }
+  }
+}

package/scripts/memory-wiki-audit.mjs

@@ -0,0 +1,95 @@
+#!/usr/bin/env node
+
+import { existsSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { homedir } from "node:os";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+function option(name, fallback) {
+  const index = process.argv.indexOf(name);
+  return index >= 0 && process.argv[index + 1] ? process.argv[index + 1] : fallback;
+}
+
+const para = resolve(option("--para-root", join(homedir(), "PARA")));
+const staleDays = Number(option("--stale-days", "30"));
+const reportPath = option("--report", "");
+const cutoff = Date.now() - staleDays * 86_400_000;
+const findings = [];
+let stale = 0;
+let hard = 0;
+let orphan = 0;
+let staged = 0;
+let noteStatus = "";
+
+function directories(root, depth = 0) {
+  if (!existsSync(root) || depth > 5) return [];
+  const result = [];
+  for (const entry of readdirSync(root, { withFileTypes: true })) {
+    if (!entry.isDirectory()) continue;
+    const path = join(root, entry.name);
+    if (entry.name === "wiki" && basename(dirname(path)) === ".planning") result.push(path);
+    else result.push(...directories(path, depth + 1));
+  }
+  return result;
+}
+
+for (const wiki of directories(para)) {
+  const project = resolve(wiki, "..", "..");
+  const rows = [];
+  const sources = join(wiki, "sources");
+  const sourceFiles = existsSync(sources) ? readdirSync(sources).filter((name) => name.endsWith(".md")) : [];
+  const staleFiles = sourceFiles.filter((name) => {
+    const match = readFileSync(join(sources, name), "utf8").match(/Last reviewed\*?\*?:\s*(\d{4}-\d{2}-\d{2})/i);
+    return match && Date.parse(`${match[1]}T00:00:00Z`) < cutoff;
+  });
+  if (staleFiles.length) { stale += staleFiles.length; rows.push(`- stale source pages (${staleFiles.length}): ${staleFiles.join(", ")}`); }
+  const contradictions = join(wiki, "CONTRADICTIONS.md");
+  if (existsSync(contradictions)) {
+    const open = readFileSync(contradictions, "utf8").match(/wiki:contradictions:open:start -->([\s\S]*?)<!-- wiki:contradictions:open:end/)?.[1] ?? "";
+    const count = (open.match(/severity:\s*hard|hard contradiction/gi) ?? []).length;
+    if (count) { hard += count; rows.push(`- open HARD contradictions: ${count}`); }
+  }
+  const indexPath = join(wiki, "index.md");
+  if (existsSync(indexPath)) {
+    const index = readFileSync(indexPath, "utf8");
+    const orphans = sourceFiles.filter((name) => !index.includes(name));
+    if (orphans.length) { orphan += orphans.length; rows.push(`- orphan source pages (${orphans.length}): ${orphans.join(", ")}`); }
+  }
+  const staging = join(project, ".planning", "memory-staging");
+  if (existsSync(staging)) {
+    const count = readdirSync(staging).filter((name) => name.endsWith(".json") && statSync(join(staging, name)).mtimeMs < cutoff).length;
+    if (count) { staged += count; rows.push(`- unreviewed staged memory candidates (>${staleDays} days): ${count}`); }
+  }
+  if (rows.length) findings.push(`### ${basename(project)}\n\n${rows.join("\n")}`);
+}
+
+let noteEligible = /^(1|true|yes|on)$/i.test(process.env.CAIRN_NOTE_DISTILLATION ?? "");
+if (/^(1|true|yes|on)$/i.test(process.env.CAIRN_CAPABILITY_CONTRACT ?? "")) {
+  const status = spawnSync(process.execPath, [join(ROOT, "bin", "cairn"), "capabilities", "status", "--json"], { encoding: "utf8", windowsHide: true });
+  try {
+    const value = JSON.parse(status.stdout);
+    noteEligible = value.capabilities?.some((row) => row.id === "notes.distill" && row.enabled === true) ?? false;
+  } catch { noteEligible = false; }
+}
+if (noteEligible) {
+  const result = spawnSync(process.execPath, [join(ROOT, "bin", "cairn"), "notes", "distill", "--all-projects", "--para-root", para, "--json"], { stdio: "ignore", windowsHide: true });
+  noteStatus = result.status === 0 ? "completed" : "failed (deterministic wiki findings remain valid)";
+}
+
+const report = `# Memory + Wiki Audit Report
+
+- Generated: ${new Date().toISOString().replace(/\.\d{3}Z$/, "Z")}
+- Scope: ${para} (staleness threshold: ${staleDays} days)
+- Stale source pages: ${stale}
+- Open hard contradictions: ${hard}
+- Orphan source pages: ${orphan}
+- Unreviewed staged candidates: ${staged}
+${noteStatus ? `- Note distillation: ${noteStatus}\n` : ""}
+
+${findings.length ? findings.join("\n\n") : "No deterministic findings."}
+`;
+process.stdout.write(report);
+if (reportPath) writeFileSync(resolve(reportPath), report, "utf8");

package/scripts/phase26-test-manifest.mjs

@@ -0,0 +1,26 @@
+const REQUIRED_PHASE26_TEST_PATHS = Object.freeze([
+  "scripts/test-setup-preflight.mjs",
+  "scripts/test-setup-reconcile.mjs",
+  "scripts/test-setup-compatibility.mjs",
+  "scripts/test-pi-lifecycle.mjs",
+  "mcp-memory-server/scripts/smoke-pi-mcp-bridge.mjs",
+]);
+
+export const PHASE26_TEST_MANIFEST = Object.freeze(REQUIRED_PHASE26_TEST_PATHS.map((path) => Object.freeze({
+  path,
+  state: "routine",
+})));
+
+export function validatePhase26TestManifest(entries = PHASE26_TEST_MANIFEST) {
+  if (!Array.isArray(entries)) throw new Error("Phase 26 test manifest must be an array.");
+  if (entries.length !== REQUIRED_PHASE26_TEST_PATHS.length) throw new Error("Phase 26 test manifest entry count drifted.");
+  const paths = entries.map((entry) => entry?.path);
+  if (JSON.stringify(paths) !== JSON.stringify(REQUIRED_PHASE26_TEST_PATHS)) throw new Error("Phase 26 test manifest paths or order drifted.");
+  if (new Set(paths).size !== paths.length) throw new Error("Phase 26 test manifest contains duplicate paths.");
+  for (const entry of entries) {
+    if (!entry || typeof entry !== "object" || Array.isArray(entry)) throw new Error("Phase 26 test manifest entry must be an object.");
+    if (Object.keys(entry).sort().join(",") !== "path,state") throw new Error(`Phase 26 test manifest fields drifted for ${entry.path ?? "unknown"}.`);
+    if (entry.state !== "red-only" && entry.state !== "routine") throw new Error(`Invalid Phase 26 test state for ${entry.path}.`);
+  }
+  return entries;
+}

package/scripts/run-repository-tests.mjs

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+
+import { readdirSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { fileURLToPath } from "node:url";
+
+import { PHASE26_TEST_MANIFEST, validatePhase26TestManifest } from "./phase26-test-manifest.mjs";
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+export function dispatchPhase26Tests(spawn = spawnSync) {
+  const results = [];
+  for (const entry of validatePhase26TestManifest().filter(({ state }) => state === "routine")) {
+    const result = spawn(process.execPath, [join(root, ...entry.path.split("/"))], { cwd: root, stdio: "inherit" });
+    results.push({ path: entry.path, status: result.status ?? 1 });
+    if (result.status !== 0) break;
+  }
+  return results;
+}
+
+function verifyPhase26RedRegistration() {
+  validatePhase26TestManifest();
+  const scheduled = dispatchPhase26Tests((_command, args) => {
+    throw new Error(`RED-only Phase 26 test was scheduled: ${args[0]}`);
+  });
+  if (scheduled.length !== 0) throw new Error("RED-only Phase 26 tests must not run in routine dispatch.");
+  console.log(`PASS: Phase 26 manifest has ${PHASE26_TEST_MANIFEST.length} exact RED-only entries and routine dispatch schedules none`);
+}
+
+function verifyPhase26RoutineRegistration() {
+  const entries = validatePhase26TestManifest();
+  if (!entries.every(({ state }) => state === "routine")) {
+    throw new Error("Every Phase 26 test must be routine after learning and track routing complete.");
+  }
+  const recorded = [];
+  const scheduled = dispatchPhase26Tests((command, args, options) => {
+    if (command !== process.execPath) throw new Error("Phase 26 dispatch must use the active Node executable.");
+    if (!Array.isArray(args) || args.length !== 1) throw new Error("Phase 26 dispatch arguments drifted.");
+    if (options?.cwd !== root || options?.stdio !== "inherit") throw new Error("Phase 26 dispatch options drifted.");
+    recorded.push(relative(root, args[0]).split(sep).join("/"));
+    return { status: 0 };
+  });
+  const expected = entries.map(({ path }) => path);
+  if (JSON.stringify(recorded) !== JSON.stringify(expected)) throw new Error("Phase 26 executable dispatch paths or order drifted.");
+  if (JSON.stringify(scheduled.map(({ path }) => path)) !== JSON.stringify(expected)) throw new Error("Phase 26 dispatch result paths drifted.");
+  if (new Set(recorded).size !== expected.length) throw new Error("Phase 26 executable dispatch scheduled a duplicate contract.");
+  console.log(`PASS: Phase 26 routine dispatch schedules all ${expected.length} exact contracts once`);
+}
+
+function run() {
+  const args = process.argv.slice(2);
+  if (args.length === 1 && args[0] === "--verify-phase26-registration=red") {
+    verifyPhase26RedRegistration();
+    return;
+  }
+  if (args.length === 1 && args[0] === "--verify-phase26-registration=routine") {
+    verifyPhase26RoutineRegistration();
+    return;
+  }
+  if (args.length !== 0) throw new Error(`Unknown repository test option: ${args.join(" ")}`);
+
+  if (process.platform !== "win32") {
+    for (const test of readdirSync(join(root, "scripts")).filter((name) => /^test-.*\.sh$/.test(name)).sort()) {
+      const result = spawnSync(join(root, "scripts", test), [], { cwd: root, stdio: "inherit" });
+      if (result.status !== 0) process.exit(result.status ?? 1);
+    }
+  }
+  const native = spawnSync(process.execPath, [join(root, "scripts", "test-windows-native.mjs")], { cwd: root, stdio: "inherit" });
+  if (native.status !== 0) process.exit(native.status ?? 1);
+  const phase26 = dispatchPhase26Tests();
+  const failed = phase26.find(({ status }) => status !== 0);
+  if (failed) process.exit(failed.status);
+}
+
+run();

package/scripts/setup-core.mjs

@@ -0,0 +1,312 @@
+import { closeSync, constants, existsSync, fstatSync, lstatSync, openSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { accessSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { dirname, join, parse, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { HARNESS_IDS, harnessProjectAssets } from "./harness-registry.mjs";
+
+const ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const TEMPLATE_ROOT = join(ROOT, "templates");
+const POLICY_LIMIT_BYTES = 1024 * 1024;
+const GIT_MODES = Object.freeze(["init", "existing", "none"]);
+const HARNESSES = HARNESS_IDS;
+const MEMORY_MODES = Object.freeze(["local", "none"]);
+
+const COMMON_ASSETS = Object.freeze([
+  ["env.example.template", ".ai/env.example", 0o644],
+  ["trajectory-redaction.json.template", ".ai/trajectory-redaction.json", 0o644],
+  ["capabilities.json.template", ".ai/capabilities.json", 0o600],
+  ["agentfs-gitignore.template", ".agentfs/.gitignore", 0o644],
+  ["planning-config.json.template", ".planning/config.json", 0o644],
+  ["project-brief.md.template", ".planning/PROJECT-BRIEF.md", 0o644],
+  ["wiki-index.md.template", ".planning/wiki/index.md", 0o644],
+  ["wiki-policy.md.template", ".planning/wiki/policy.md", 0o644],
+  ["wiki-contradictions.md.template", ".planning/wiki/CONTRADICTIONS.md", 0o644],
+  ["wiki-log.md.template", ".planning/wiki/LOG.md", 0o644],
+  ["alignment-policy.md.template", ".planning/alignment/policy.md", 0o644],
+  ["alignment-gap-register.yaml.template", ".planning/alignment/gap-register.yaml", 0o644],
+  ["graph-policy.md.template", ".planning/graphs/policy.md", 0o644],
+  ["graphs-gitignore.template", ".planning/graphs/.gitignore", 0o644],
+  ["security-policy.md.template", ".planning/security/policy.md", 0o644],
+]);
+
+class SetupInputError extends Error {
+  constructor(kind, message, status = 1) {
+    super(message);
+    this.name = "SetupInputError";
+    this.kind = kind;
+    this.status = status;
+  }
+}
+
+function usage(message) {
+  return new SetupInputError("usage", `${message} Usage: cairn setup PATH --git init|existing|none --harness LIST --memory local|none [--policy PATH] --yes [--json]`, 2);
+}
+
+function operational(kind, message) {
+  return new SetupInputError(kind, message, 1);
+}
+
+function exactKeys(value, allowed, label) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw operational("unsafe-policy", `Invalid setup policy ${label}.`);
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw operational("unsafe-policy", `Invalid setup policy: unknown ${label} field ${unknown.join(", ")}.`);
+}
+
+function enumValue(value, allowed, label, optional = false) {
+  if (optional && value === undefined) return undefined;
+  if (typeof value !== "string" || !allowed.includes(value)) throw operational("unsafe-policy", `Invalid setup policy ${label}; allowed values are ${allowed.join(", ")}.`);
+  return value;
+}
+
+function enumArray(value, allowed, label, optional = false) {
+  if (optional && value === undefined) return undefined;
+  if (!Array.isArray(value) || value.length === 0 || value.some((item) => typeof item !== "string" || !allowed.includes(item))) {
+    throw operational("unsafe-policy", `Invalid setup policy ${label}; allowed values are ${allowed.join(", ")}.`);
+  }
+  if (new Set(value).size !== value.length) throw operational("unsafe-policy", `Invalid setup policy ${label}; duplicate values are not allowed.`);
+  return allowed.filter((item) => value.includes(item));
+}
+
+function deepFreeze(value) {
+  if (!value || typeof value !== "object" || ArrayBuffer.isView(value)) return value;
+  for (const child of Object.values(value)) deepFreeze(child);
+  return Object.freeze(value);
+}
+
+function parsePolicy(value) {
+  exactKeys(value, ["schema_version", "defaults", "constraints"], "root");
+  if (value.schema_version !== 1) throw operational("unsafe-policy", "Invalid setup policy schema version; expected schema_version 1.");
+  exactKeys(value.defaults, ["git", "harnesses", "memory"], "defaults");
+  exactKeys(value.constraints, ["git", "harnesses", "required_harnesses", "memory"], "constraints");
+  const policy = {
+    schema_version: 1,
+    defaults: {
+      ...(value.defaults.git !== undefined ? { git: enumValue(value.defaults.git, GIT_MODES, "defaults.git") } : {}),
+      ...(value.defaults.harnesses !== undefined ? { harnesses: enumArray(value.defaults.harnesses, HARNESSES, "defaults.harnesses") } : {}),
+      ...(value.defaults.memory !== undefined ? { memory: enumValue(value.defaults.memory, MEMORY_MODES, "defaults.memory") } : {}),
+    },
+    constraints: {
+      ...(value.constraints.git !== undefined ? { git: enumArray(value.constraints.git, GIT_MODES, "constraints.git") } : {}),
+      ...(value.constraints.harnesses !== undefined ? { harnesses: enumArray(value.constraints.harnesses, HARNESSES, "constraints.harnesses") } : {}),
+      ...(value.constraints.required_harnesses !== undefined ? { required_harnesses: enumArray(value.constraints.required_harnesses, HARNESSES, "constraints.required_harnesses") } : {}),
+      ...(value.constraints.memory !== undefined ? { memory: enumArray(value.constraints.memory, MEMORY_MODES, "constraints.memory") } : {}),
+    },
+  };
+  if (policy.defaults.git && policy.constraints.git && !policy.constraints.git.includes(policy.defaults.git)) {
+    throw operational("unsafe-policy", "Invalid setup policy: defaults.git violates constraints.git.");
+  }
+  if (policy.defaults.memory && policy.constraints.memory && !policy.constraints.memory.includes(policy.defaults.memory)) {
+    throw operational("unsafe-policy", "Invalid setup policy: defaults.memory violates constraints.memory.");
+  }
+  if (policy.defaults.harnesses && policy.constraints.harnesses
+      && policy.defaults.harnesses.some((name) => !policy.constraints.harnesses.includes(name))) {
+    throw operational("unsafe-policy", "Invalid setup policy: defaults.harnesses violates constraints.harnesses.");
+  }
+  if (policy.constraints.required_harnesses && policy.constraints.harnesses
+      && policy.constraints.required_harnesses.some((name) => !policy.constraints.harnesses.includes(name))) {
+    throw operational("unsafe-policy", "Invalid setup policy: required harnesses must be allowed by constraints.harnesses.");
+  }
+  return deepFreeze(policy);
+}
+
+export function readSetupPolicy(path, options = {}) {
+  const lstat = options.lstat ?? lstatSync;
+  const read = options.readFile ?? readFileSync;
+  let info;
+  try {
+    info = lstat(path);
+  } catch (error) {
+    throw operational("unsafe-policy", `Setup policy could not be read: ${error instanceof Error ? error.message : String(error)}.`);
+  }
+  if (!info.isFile() || info.isSymbolicLink()) throw operational("unsafe-policy", "Setup policy must be a regular file, not a symbolic link or device.");
+  if (info.size > POLICY_LIMIT_BYTES) throw operational("unsafe-policy", "Setup policy exceeds the size limit.");
+  if (process.platform !== "win32" && (info.mode & 0o111) !== 0) throw operational("unsafe-policy", "Setup policy must not be executable.");
+  let descriptor;
+  let bytes;
+  try {
+    if (options.readFile) bytes = read(path);
+    else {
+      descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+      const opened = fstatSync(descriptor);
+      if (!opened.isFile() || opened.dev !== info.dev || opened.ino !== info.ino) throw operational("unsafe-policy", "Setup policy changed during validation.");
+      if (opened.size > POLICY_LIMIT_BYTES || (process.platform !== "win32" && (opened.mode & 0o111) !== 0)) {
+        throw operational("unsafe-policy", "Setup policy type, size, or executable mode is unsafe.");
+      }
+      bytes = read(descriptor);
+    }
+  } catch (error) {
+    if (error instanceof SetupInputError) throw error;
+    throw operational("unsafe-policy", `Setup policy could not be opened safely: ${error instanceof Error ? error.message : String(error)}.`);
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+  if (bytes.byteLength > POLICY_LIMIT_BYTES) throw operational("unsafe-policy", "Setup policy exceeds the size limit.");
+  let parsed;
+  try {
+    parsed = JSON.parse(bytes.toString("utf8"));
+  } catch {
+    throw operational("unsafe-policy", "Invalid setup policy JSON syntax.");
+  }
+  return parsePolicy(parsed);
+}
+
+function parseHarnesses(raw) {
+  const values = raw.split(",").map((value) => value.trim()).filter(Boolean);
+  if (values.length === 0 || values.some((value) => !HARNESSES.includes(value)) || new Set(values).size !== values.length) {
+    throw usage(`Invalid harness choice: ${raw || "missing"}.`);
+  }
+  return HARNESSES.filter((name) => values.includes(name));
+}
+
+export function parseSetupArgs(args, options = {}) {
+  const isTTY = options.isTTY ?? Boolean(process.stdin.isTTY);
+  const parsed = { target: null, git: null, harnesses: null, memory: null, policyPath: null, confirmed: false, json: false };
+  const seen = new Set();
+  for (let index = 0; index < args.length; index += 1) {
+    const arg = args[index];
+    if (["--git", "--harness", "--memory", "--policy"].includes(arg)) {
+      if (seen.has(arg)) throw usage(`Invalid duplicate ${arg} option.`);
+      seen.add(arg);
+      const value = args[index + 1];
+      if (!value || value.startsWith("--")) throw usage(`Missing value for ${arg}.`);
+      index += 1;
+      if (arg === "--git") {
+        if (!GIT_MODES.includes(value)) throw usage(`Invalid Git mode: ${value}.`);
+        parsed.git = value;
+      } else if (arg === "--harness") parsed.harnesses = parseHarnesses(value);
+      else if (arg === "--memory") {
+        if (!MEMORY_MODES.includes(value)) throw usage(`Invalid memory mode: ${value}.`);
+        parsed.memory = value;
+      } else parsed.policyPath = value;
+    } else if (arg === "--yes" || arg === "--json") {
+      if (seen.has(arg)) throw usage(`Invalid duplicate ${arg} option.`);
+      seen.add(arg);
+      if (arg === "--yes") parsed.confirmed = true;
+      else parsed.json = true;
+    } else if (arg.startsWith("-")) throw usage(`Unknown setup option: ${arg}.`);
+    else if (parsed.target !== null) throw usage("Invalid extra target/path positional argument.");
+    else parsed.target = arg;
+  }
+  if (!isTTY) {
+    if (!parsed.target) throw usage("Missing setup target path.");
+    const canUsePolicyDefaults = Boolean(parsed.policyPath);
+    if (!canUsePolicyDefaults && !parsed.git) throw usage("Non-TTY setup requires an explicit Git choice.");
+    if (!canUsePolicyDefaults && !parsed.harnesses) throw usage("Non-TTY setup requires an explicit harness choice.");
+    if (!canUsePolicyDefaults && !parsed.memory) throw usage("Non-TTY setup requires an explicit memory choice.");
+    if (!parsed.confirmed) throw usage("Non-TTY setup requires explicit confirmation with --yes.");
+  }
+  return deepFreeze(parsed);
+}
+
+function pathParts(path) {
+  const result = [];
+  let cursor = resolve(path);
+  const root = parse(cursor).root;
+  while (cursor !== root) {
+    result.push(cursor);
+    cursor = dirname(cursor);
+  }
+  result.push(root);
+  return result.reverse();
+}
+
+export function classifySetupTarget(target, options = {}) {
+  const lstat = options.lstat ?? lstatSync;
+  const exists = options.exists ?? existsSync;
+  const readdir = options.readdir ?? readdirSync;
+  const realpath = options.realpath ?? realpathSync;
+  const access = options.access ?? accessSync;
+  const run = options.run ?? spawnSync;
+  const absolute = resolve(target);
+  let nearest = parse(absolute).root;
+  for (const candidate of pathParts(absolute)) {
+    if (!exists(candidate)) break;
+    const info = lstat(candidate);
+    if (info.isSymbolicLink()) throw operational("unsafe-target", "Setup target or an ancestor is a symbolic link and is unsafe.");
+    if (!info.isDirectory()) throw operational("unsafe-target", "Setup target ancestor is not a regular directory.");
+    nearest = candidate;
+  }
+  const targetExists = exists(absolute);
+  const targetState = targetExists ? (readdir(absolute).length === 0 ? "empty" : "non-empty") : "missing";
+  try {
+    access(nearest, constants.R_OK | constants.W_OK | constants.X_OK);
+  } catch {
+    throw operational("target-denied", "Setup target cannot be created or inspected because access to its parent is denied.");
+  }
+  const canonicalNearest = realpath(nearest);
+  if (canonicalNearest !== nearest) throw operational("unsafe-target", "Setup target resolves through an unsafe ancestor.");
+
+  const runOptions = { encoding: "utf8", shell: false };
+  const version = run("git", ["--version"], runOptions);
+  if (version.error?.code === "ENOENT") {
+    return Object.freeze({ target: absolute, targetState, gitExecutable: "missing", repository: "unknown" });
+  }
+  if (version.error || version.status !== 0) {
+    throw operational("git-probe", "Git availability could not be determined safely.");
+  }
+  const worktree = run("git", ["-C", targetExists ? absolute : nearest, "rev-parse", "--is-inside-work-tree"], runOptions);
+  let repository = "none";
+  if (worktree.error?.code === "ENOENT") return Object.freeze({ target: absolute, targetState, gitExecutable: "missing", repository: "unknown" });
+  if (worktree.status === 0) repository = worktree.stdout.trim() === "true" ? "work-tree" : "bare";
+  return Object.freeze({ target: absolute, targetState, gitExecutable: "available", repository });
+}
+
+function requiredChoice(value, name) {
+  if (value === null || value === undefined || (Array.isArray(value) && value.length === 0)) throw usage(`Missing required ${name} choice.`);
+  return value;
+}
+
+export function resolveSetupChoices({ parsed, preflight, policy = null, interactive = null }) {
+  const git = requiredChoice(parsed.git ?? policy?.defaults?.git ?? interactive?.git, "Git");
+  const harnesses = requiredChoice(parsed.harnesses ?? policy?.defaults?.harnesses ?? interactive?.harnesses, "harness");
+  const memory = requiredChoice(parsed.memory ?? policy?.defaults?.memory ?? interactive?.memory, "memory");
+  const confirmed = parsed.confirmed || interactive?.confirmed === true;
+  if (!confirmed) throw usage("Missing setup confirmation; use --yes or confirm interactively.");
+  if (!GIT_MODES.includes(git)) throw usage(`Invalid Git choice: ${git}.`);
+  if (!Array.isArray(harnesses) || harnesses.length === 0 || harnesses.some((name) => !HARNESSES.includes(name))) throw usage("Invalid harness choice.");
+  if (!MEMORY_MODES.includes(memory)) throw usage(`Invalid memory choice: ${memory}.`);
+  const normalizedHarnesses = HARNESSES.filter((name) => harnesses.includes(name));
+  if (git !== "none" && preflight.gitExecutable === "missing") throw operational("missing-git", `Git executable is required for --git ${git}.`);
+  if (git === "existing" && preflight.repository !== "work-tree") throw operational("non-repository", "--git existing requires the target to be inside a Git work tree.");
+
+  const constraints = policy?.constraints ?? {};
+  if (constraints.git && !constraints.git.includes(git)) throw operational("policy-constraint", `Git choice ${git} violates policy constraints.`);
+  if (constraints.memory && !constraints.memory.includes(memory)) throw operational("policy-constraint", `Memory choice ${memory} violates policy constraints.`);
+  if (constraints.harnesses && normalizedHarnesses.some((name) => !constraints.harnesses.includes(name))) {
+    throw operational("policy-constraint", "Harness choice violates policy constraints.");
+  }
+  const missingRequired = (constraints.required_harnesses ?? []).filter((name) => !normalizedHarnesses.includes(name));
+  if (missingRequired.length) throw operational("policy-constraint", `Harness constraint requires ${missingRequired.join(", ")}.`);
+  return deepFreeze({ git, harnesses: normalizedHarnesses, memory, confirmed: true, limited: git === "none" });
+}
+
+function templateAsset(template, path, mode, harness) {
+  const asset = { path, bytes: readFileSync(join(TEMPLATE_ROOT, template)), mode, template, ...(harness ? { harness } : {}) };
+  return Object.freeze(asset);
+}
+
+export function buildSetupPlan({ target, preflight, choices }) {
+  const absolute = resolve(target);
+  if (preflight.target && resolve(preflight.target) !== absolute) throw operational("unsafe-target", "Setup target changed after preflight.");
+  if (!choices?.confirmed) throw usage("Missing setup confirmation before mutation planning.");
+  if (choices.git === "existing" && preflight.repository !== "work-tree") throw operational("non-repository", "Existing Git mode requires a work tree.");
+  if (choices.git !== "none" && preflight.gitExecutable === "missing") throw operational("missing-git", "The selected Git mode requires the Git executable.");
+  const harnesses = HARNESSES.filter((name) => choices.harnesses.includes(name));
+  const assets = [
+    ...harnesses.flatMap((harness) => harnessProjectAssets(harness, choices.memory)
+      .map(({ template, path, mode }) => templateAsset(template, path, mode, harness))),
+    ...COMMON_ASSETS.map(([template, path, mode]) => templateAsset(template, path, mode)),
+  ];
+  const version = JSON.parse(readFileSync(join(ROOT, "package.json"), "utf8")).version;
+  return deepFreeze({
+    target: absolute,
+    targetState: preflight.targetState,
+    version,
+    git: choices.git,
+    memory: choices.memory,
+    harnesses,
+    limited: choices.git === "none",
+    assets: Object.freeze(assets),
+  });
+}