@cairnkeep/cli 2.8.0 → 2.11.0

package/scripts/test-package-install.sh

@@ -86,6 +86,23 @@ do
   [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
 done
 
+for required in \
+  schemas/context-pack.schema.json \
+  mcp-memory-server/dist/mcp-tool-catalog.js \
+  mcp-memory-server/dist/mcp-tool-profile.js \
+  mcp-memory-server/dist/mcp-tool-cli.js \
+  mcp-memory-server/dist/context-pack.js \
+  mcp-memory-server/dist/context-pack-cli.js \
+  docs/mcp-tool-profiles.md \
+  docs/context-packs.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted $required"
+done
+CAIRN_PACK_BASE_DIR="$tmp/installed-packs" cairn pack list --json >"$tmp/installed-pack-list.json" || \
+  fail "installed package pack CLI failed"
+cairn mcp-tools list --json >"$tmp/installed-mcp-tools.json" || \
+  fail "installed package mcp-tools CLI failed"
+
 for required in \
   schemas/skill-adapter.schema.json \
   schemas/skill-proposal-protocol.schema.json \
@@ -314,4 +331,68 @@ fi
 [[ "$(sha256sum "$ROOT/package-lock.json" | cut -d' ' -f1)" == "$root_lock_before" ]] || fail "root lockfile changed during pack/install"
 [[ "$(sha256sum "$ROOT/mcp-memory-server/package-lock.json" | cut -d' ' -f1)" == "$server_lock_before" ]] || fail "server lockfile changed during pack/install"
 
+phase26_surface_complete=true
+for required in \
+  scripts/setup.mjs \
+  scripts/setup-core.mjs \
+  scripts/setup-reconcile.mjs \
+  schemas/cairnkeep-setup.schema.json \
+  schemas/cairnkeep-setup-policy.schema.json \
+  mcp-memory-server/dist/pi-mcp-bridge.js \
+  pi/extensions/cairnkeep-memory.ts \
+  docs/operating.md \
+  docs/harness-compatibility.md \
+  docs/native-windows.md \
+  docs/building-an-overlay.md
+do
+  [[ -f "$ROOT/$required" ]] || phase26_surface_complete=false
+done
+
+if [[ "$phase26_surface_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "PHASE26_RED:SETUP_PACKAGE_MISSING"
+    exit 86
+  fi
+  echo "SKIP: packaged guided setup and Pi bridge surface is not complete"
+  echo "PASS: npm tarball installs a self-contained CLI and MCP server"
+  exit 0
+fi
+
+for required in \
+  scripts/setup.mjs \
+  scripts/setup-core.mjs \
+  scripts/setup-reconcile.mjs \
+  schemas/cairnkeep-setup.schema.json \
+  schemas/cairnkeep-setup-policy.schema.json \
+  mcp-memory-server/dist/pi-mcp-bridge.js \
+  pi/extensions/cairnkeep-memory.ts \
+  docs/operating.md \
+  docs/harness-compatibility.md \
+  docs/native-windows.md \
+  docs/building-an-overlay.md
+do
+  [[ -f "$installed_root/$required" ]] || fail "npm tarball omitted Phase 26 asset $required"
+done
+
+installed_setup_target="$tmp/Installed Setup – Unicode"
+(cd "$tmp" && cairn setup "$installed_setup_target" \
+  --git none --harness claude,pi --memory local --yes --json) >"$tmp/installed-setup.json" \
+  || fail "installed cairn setup failed outside the source checkout"
+node - "$tmp/installed-setup.json" "$installed_setup_target" <<'NODE'
+const fs = require("fs");
+const [resultPath, target] = process.argv.slice(2);
+const result = JSON.parse(fs.readFileSync(resultPath, "utf8"));
+if (result.schema_version !== 1 || result.status !== "limited") process.exit(1);
+if (result.git !== "none" || result.memory !== "local") process.exit(1);
+if (JSON.stringify(result.harnesses) !== JSON.stringify(["claude", "pi"])) process.exit(1);
+if (!fs.existsSync(`${target}/.ai/cairnkeep.json`)) process.exit(1);
+NODE
+
+if find "$installed_root" -type f \( \
+  -name '.env' -o -name '*.tmp' -o -name '*.bak' -o -name 'cairnkeep.json' \
+  -o -path '*/.planning/*' -o -path '*/.agentfs/*' \
+\) | grep -q .; then
+  fail "npm tarball included temporary or project-private setup state"
+fi
+
 echo "PASS: npm tarball installs a self-contained CLI and MCP server"

package/scripts/test-phase17-artifact-lifecycle.sh

@@ -48,7 +48,7 @@ run_shell_syntax_baseline() {
   local script
   while IFS= read -r script; do
     bash -n "$script" || return 1
-  done < <(find "$ROOT/bin" "$ROOT/scripts" -type f \( -name '*.sh' -o -name 'cairn' \) | sort)
+  done < <(find "$ROOT/bin" "$ROOT/scripts" -type f -name '*.sh' | sort)
 }
 
 run_baseline() {

package/scripts/test-phase18-capability-lifecycle.sh

@@ -142,7 +142,7 @@ run_baseline() {
   run_baseline_check "$ROOT/scripts/test-completion.sh"
   run_baseline_check "$ROOT/scripts/test-package-install.sh"
   run_baseline_check "$ROOT/scripts/test-uninstall.sh"
-  run_baseline_check bash -n "$ROOT/bin/cairn"
+  run_baseline_check node --check "$ROOT/bin/cairn"
   run_master_off_identity
   echo "PASS: Phase 18 master-off CLI/package/lifecycle identity baseline"
 }

package/scripts/test-pi-lifecycle.mjs

@@ -0,0 +1,190 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { existsSync, mkdtempSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { runWindowsCommand } from "./windows-platform.mjs";
+
+const EXPECTED_RED_EXIT = 86;
+const RED_MARKER = "PHASE26_RED:PI_LIFECYCLE_MISSING";
+const root = resolve(fileURLToPath(new URL("..", import.meta.url)));
+
+function run(command, args, options = {}) {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 20_000, ...options });
+  if (result.error) throw result.error;
+  return result;
+}
+
+function assertFixtureContract(sandbox) {
+  const project = join(sandbox, "Project with spaces – Unicode");
+  const piLive = join(sandbox, "Pi Agent");
+  mkdirSync(project, { recursive: true });
+  mkdirSync(join(piLive, "extensions"), { recursive: true });
+  const setupState = {
+    schema_version: 1,
+    cairnkeep_version: "fixture-1",
+    git: "none",
+    memory: "local",
+    harnesses: ["pi"],
+    assets: {},
+  };
+  assert.equal(setupState.harnesses.includes("pi"), true);
+  assert.equal(setupState.harnesses.includes("claude"), false);
+  assert.equal(existsSync(join(piLive, "extensions", "cairnkeep-memory.ts")), false, "project setup fixture auto-synced machine state");
+  writeFileSync(join(piLive, "extensions", "operator-extension.ts"), "operator bytes\n");
+  return { project, piLive };
+}
+
+function productionComplete() {
+  const required = [
+    "pi/extensions/cairnkeep-memory.ts",
+    "mcp-memory-server/dist/pi-mcp-bridge.js",
+    "scripts/setup.mjs",
+    "scripts/sync-pi-assets.sh",
+    "scripts/uninstall.sh",
+    "schemas/cairnkeep-setup.schema.json",
+  ];
+  if (!required.every((path) => existsSync(join(root, path)))) return false;
+  const sync = readFileSync(join(root, "scripts", "sync-pi-assets.sh"), "utf8");
+  const uninstall = readFileSync(join(root, "scripts", "uninstall.sh"), "utf8");
+  const windows = readFileSync(join(root, "scripts", "windows-platform.mjs"), "utf8");
+  return [sync, uninstall, windows].every((text) => text.includes("extensions/cairnkeep-memory.ts"));
+}
+
+async function exerciseSelectedSetup(sandbox, fixture) {
+  const env = { ...process.env, HOME: join(sandbox, "setup-home") };
+  mkdirSync(env.HOME, { recursive: true });
+  if (process.platform !== "win32") {
+    const result = run(join(root, "bin", "cairn"), [
+      "setup", fixture.project,
+      "--git", "none",
+      "--harness", "pi",
+      "--memory", "local",
+      "--yes",
+      "--json",
+    ], { env });
+    assert.equal(result.status, 0, result.stderr);
+    assert.deepEqual(JSON.parse(result.stdout).harnesses, ["pi"]);
+    assert.equal(existsSync(join(fixture.project, ".ai", "start-pi.sh")), true);
+    assert.equal(existsSync(join(fixture.project, ".ai", "start-claude.sh")), false);
+  }
+  assert.equal(existsSync(join(fixture.piLive, "extensions", "cairnkeep-memory.ts")), false, "setup auto-synced Pi machine assets");
+
+  const windowsProject = join(sandbox, "Windows selected project – Unicode");
+  let output = "";
+  const originalWrite = process.stdout.write.bind(process.stdout);
+  process.stdout.write = ((chunk) => {
+    output += String(chunk);
+    return true;
+  });
+  try {
+    const handled = await runWindowsCommand({
+      command: "setup",
+      args: [windowsProject, "--git", "none", "--harness", "pi", "--memory", "local", "--yes", "--json"],
+      root,
+    });
+    assert.equal(handled, true);
+  } finally {
+    process.stdout.write = originalWrite;
+  }
+  assert.deepEqual(JSON.parse(output).harnesses, ["pi"]);
+  assert.equal(existsSync(join(windowsProject, ".ai", "start-pi.cmd")), true);
+  assert.equal(existsSync(join(windowsProject, ".ai", "start-claude.cmd")), false);
+}
+
+async function exerciseWindowsLifecycle(sandbox) {
+  const live = join(sandbox, "Windows Pi Agent");
+  mkdirSync(join(live, "extensions"), { recursive: true });
+  writeFileSync(join(live, "extensions", "operator-extension.ts"), "operator bytes\n");
+  process.exitCode = 0;
+  await runWindowsCommand({ command: "sync-pi", args: ["--apply", "--live-root", live], root });
+  assert.equal(process.exitCode, 0);
+  for (const path of [
+    "extensions/cairnkeep-memory.ts",
+    "extensions/cairnkeep-trajectory.ts",
+    "prompts/graphify.md",
+  ]) assert.equal(existsSync(join(live, ...path.split("/"))), true, `Windows sync omitted ${path}`);
+  assert.equal(readFileSync(join(live, "extensions", "operator-extension.ts"), "utf8"), "operator bytes\n");
+
+  await runWindowsCommand({ command: "sync-pi", args: ["--check", "--live-root", live], root });
+  assert.equal(process.exitCode, 0);
+}
+
+function exercisePosixLifecycle(sandbox, fixture) {
+  const env = { ...process.env, HOME: join(sandbox, "home"), PI_CODING_AGENT_DIR: fixture.piLive };
+  mkdirSync(env.HOME, { recursive: true });
+  let result = run(join(root, "scripts", "sync-pi-assets.sh"), ["--apply", "--live-root", fixture.piLive], { env });
+  assert.equal(result.status, 0, result.stderr);
+  for (const path of [
+    "extensions/cairnkeep-memory.ts",
+    "extensions/cairnkeep-trajectory.ts",
+    "prompts/graphify.md",
+  ]) assert.equal(existsSync(join(fixture.piLive, ...path.split("/"))), true, `POSIX sync omitted ${path}`);
+  assert.equal(readFileSync(join(fixture.piLive, "extensions", "operator-extension.ts"), "utf8"), "operator bytes\n");
+
+  const memoryExtension = join(fixture.piLive, "extensions", "cairnkeep-memory.ts");
+  rmSync(memoryExtension);
+  result = run(join(root, "scripts", "sync-pi-assets.sh"), ["--check", "--live-root", fixture.piLive], { env });
+  assert.notEqual(result.status, 0);
+  assert.match(result.stderr, /Missing live Pi asset.*cairnkeep-memory\.ts/);
+  assert.match(`${result.stdout}${result.stderr}`, /sync-pi-assets\.sh --apply|--apply/);
+
+  result = run(join(root, "scripts", "sync-pi-assets.sh"), ["--apply", "--live-root", fixture.piLive], { env });
+  assert.equal(result.status, 0, result.stderr);
+  writeFileSync(memoryExtension, `${readFileSync(memoryExtension, "utf8")}\n// operator-modified fixture\n`);
+  const modifiedBytes = readFileSync(memoryExtension);
+
+  const store = join(env.HOME, ".cairnkeep");
+  const packs = join(store, "packs", "objects", "fixture");
+  mkdirSync(join(store, "memory"), { recursive: true });
+  mkdirSync(packs, { recursive: true });
+  writeFileSync(join(store, "memory", "record"), "memory bytes\n");
+  writeFileSync(join(packs, "record"), "pack bytes\n");
+  result = run(join(root, "scripts", "uninstall.sh"), ["--yes", "--live-root", join(sandbox, "unused-live"), "--pi-live-root", fixture.piLive], {
+    env: { ...env, CAIRN_AGENTFS_BASE_DIR: store, CAIRN_PACK_BASE_DIR: join(store, "packs") },
+  });
+  assert.equal(result.status, 0, result.stderr);
+  assert.equal(existsSync(memoryExtension), false);
+  assert.equal(readFileSync(join(fixture.piLive, "extensions", "operator-extension.ts"), "utf8"), "operator bytes\n");
+  assert.equal(readFileSync(join(store, "memory", "record"), "utf8"), "memory bytes\n");
+  assert.equal(readFileSync(join(packs, "record"), "utf8"), "pack bytes\n");
+
+  const backupName = readdirSync(env.HOME)
+    .filter((name) => name.startsWith(".cairnkeep-uninstall-"))
+    .sort()
+    .at(-1);
+  assert.equal(typeof backupName, "string");
+  const backup = join(env.HOME, backupName);
+  const manifest = readFileSync(join(backup, "manifest.tsv"), "utf8");
+  assert.equal(manifest.includes(memoryExtension), true);
+  assert.equal(existsSync(join(backup, "revert.sh")), true);
+  result = run("bash", [join(backup, "revert.sh")], { env });
+  assert.equal(result.status, 0, result.stderr);
+  assert.deepEqual(readFileSync(memoryExtension), modifiedBytes);
+}
+
+async function main() {
+  const sandbox = mkdtempSync(join(tmpdir(), "cairn-pi-lifecycle-"));
+  const originalExitCode = process.exitCode;
+  try {
+    const fixture = assertFixtureContract(sandbox);
+    if (!productionComplete()) {
+      console.log(RED_MARKER);
+      process.exitCode = EXPECTED_RED_EXIT;
+      return;
+    }
+    await exerciseSelectedSetup(sandbox, fixture);
+    await exerciseWindowsLifecycle(sandbox);
+    if (process.platform !== "win32") exercisePosixLifecycle(sandbox, fixture);
+    assert.equal(existsSync(join(fixture.piLive, "extensions", "operator-extension.ts")), true);
+    console.log("PASS: Pi memory-extension sync, drift, backup, revert, and preservation lifecycle contract");
+  } finally {
+    if (process.exitCode !== EXPECTED_RED_EXIT) process.exitCode = originalExitCode;
+    rmSync(sandbox, { recursive: true, force: true });
+  }
+}
+
+await main();

package/scripts/test-setup-compatibility.mjs

@@ -0,0 +1,186 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { bootstrapWindows } from "./windows-platform.mjs";
+
+const EXPECTED_RED_EXIT = 86;
+const RED_MARKER = "PHASE26_RED:SETUP_RECONCILE_MISSING";
+const here = dirname(fileURLToPath(import.meta.url));
+const root = resolve(here, "..");
+const setupCorePath = join(here, "setup-core.mjs");
+const setupReconcilePath = join(here, "setup-reconcile.mjs");
+const HARNESSES = ["claude", "opencode", "pi", "kimi", "qwen"];
+const MANAGED_ROOTS = [".ai", ".planning", ".agentfs"];
+
+function run(executable, args, options = {}) {
+  const result = spawnSync(executable, args, {
+    cwd: options.cwd ?? root,
+    encoding: "utf8",
+    env: { ...process.env, ...options.env },
+    shell: false,
+  });
+  assert.equal(result.status, options.status ?? 0, `${executable} ${args.join(" ")} failed:\n${result.stdout}${result.stderr}`);
+  return result;
+}
+
+function walkFiles(base, prefix = "") {
+  if (!existsSync(base)) return [];
+  const files = [];
+  for (const entry of readdirSync(base, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+    const next = prefix ? join(prefix, entry.name) : entry.name;
+    if (entry.isDirectory()) files.push(...walkFiles(join(base, entry.name), next));
+    else if (entry.isFile()) files.push(next.replaceAll("\\", "/"));
+  }
+  return files;
+}
+
+function snapshot(target) {
+  const result = new Map();
+  for (const managed of MANAGED_ROOTS) {
+    for (const path of walkFiles(join(target, managed), managed)) {
+      const absolute = join(target, ...path.split("/"));
+      result.set(path, {
+        bytes: readFileSync(absolute),
+        executable: (statSync(absolute).mode & 0o111) !== 0,
+        private: (statSync(absolute).mode & 0o077) === 0,
+      });
+    }
+  }
+  return result;
+}
+
+function assertSnapshotEqual(actual, expected, label, allowedAdditions = []) {
+  const unexpected = [...actual.keys()].filter((path) => !expected.has(path) && !allowedAdditions.includes(path));
+  assert.deepEqual(unexpected, [], `${label} added unexpected managed paths`);
+  for (const [path, before] of expected) {
+    assert.ok(actual.has(path), `${label} omitted ${path}`);
+    const after = actual.get(path);
+    assert.deepEqual(after.bytes, before.bytes, `${label} changed bytes for ${path}`);
+    assert.equal(after.executable, before.executable, `${label} changed executable semantics for ${path}`);
+    if (path === ".ai/capabilities.json") assert.equal(after.private, true, `${label} weakened private mode for ${path}`);
+  }
+}
+
+function validateLegacyOracles(sandbox) {
+  const posix = join(sandbox, "posix");
+  const windows = join(sandbox, "windows");
+  mkdirSync(posix);
+  mkdirSync(windows);
+
+  const first = run("bash", [join(here, "bootstrap.sh"), posix]);
+  assert.equal(first.stderr, "");
+  assert.match(first.stdout, /Cairnkeep bootstrapped into/);
+  for (const harness of HARNESSES) assert.ok(existsSync(join(posix, ".ai", `start-${harness}.sh`)), `${harness} POSIX launcher missing`);
+  const posixBefore = snapshot(posix);
+  writeFileSync(join(posix, ".ai", "env.example"), "operator-owned\n");
+  chmodSync(join(posix, ".ai", "env.example"), 0o640);
+  const operatorBytes = readFileSync(join(posix, ".ai", "env.example"));
+  const rerun = run("bash", [join(here, "bootstrap.sh"), posix]);
+  assert.match(rerun.stdout, /skip \(exists\): \.ai\/env\.example/);
+  assert.deepEqual(readFileSync(join(posix, ".ai", "env.example")), operatorBytes);
+
+  bootstrapWindows(root, [windows]);
+  const windowsSnapshot = snapshot(windows);
+  for (const harness of HARNESSES) {
+    assert.ok(windowsSnapshot.has(`.ai/start-${harness}.sh`), `${harness} Windows shell launcher missing`);
+    assert.ok(windowsSnapshot.has(`.ai/start-${harness}.cmd`), `${harness} Windows cmd launcher missing`);
+  }
+  for (const [path, value] of posixBefore) {
+    assert.ok(windowsSnapshot.has(path), `Windows bootstrap omitted POSIX asset ${path}`);
+    assert.deepEqual(windowsSnapshot.get(path).bytes, value.bytes, `Windows bootstrap changed common asset ${path}`);
+  }
+
+  const plain = join(sandbox, "plain");
+  mkdirSync(plain);
+  const rejected = run("bash", [join(here, "bootstrap.sh"), "--untracked", plain], { status: 1 });
+  assert.match(rejected.stderr, /--untracked requires.*git repository/i);
+  for (const managed of MANAGED_ROOTS) assert.equal(existsSync(join(plain, managed)), false, `legacy --untracked failure created ${managed}`);
+
+  const repo = join(sandbox, "repo");
+  mkdirSync(repo);
+  run("git", ["init", "-q", repo]);
+  run("bash", [join(here, "bootstrap.sh"), "--untracked", repo]);
+  assert.equal(run("git", ["-C", repo, "status", "--porcelain"]).stdout, "");
+  return { posixBefore, windowsSnapshot };
+}
+
+async function loadProduction() {
+  const core = await import(pathToFileURL(setupCorePath).href);
+  const reconcile = await import(pathToFileURL(setupReconcilePath).href);
+  return { core, reconcile };
+}
+
+function assertProductionExports({ core, reconcile }) {
+  assert.equal(typeof core.buildSetupPlan, "function");
+  assert.equal(typeof reconcile.reconcileSetupPlan, "function");
+  assert.equal(typeof reconcile.writeSetupStateAtomic, "function");
+}
+
+async function testSetupCompatibility(production, sandbox, legacy) {
+  const target = join(sandbox, "setup");
+  mkdirSync(target);
+  const plan = production.core.buildSetupPlan({
+    target,
+    preflight: { targetState: "empty", gitExecutable: "available", repository: "work-tree" },
+    choices: Object.freeze({ git: "existing", harnesses: HARNESSES, memory: "local", confirmed: true }),
+  });
+  const result = await production.reconcile.reconcileSetupPlan(plan);
+  assert.deepEqual(result.counts, { created: legacy.posixBefore.size, updated: 0, unchanged: 0, skipped: 0 });
+  const current = snapshot(target);
+  assertSnapshotEqual(current, legacy.posixBefore, "deterministic setup", [".ai/cairnkeep.json"]);
+  assert.ok(current.has(".ai/cairnkeep.json"), "setup state missing");
+  const state = JSON.parse(current.get(".ai/cairnkeep.json").bytes.toString("utf8"));
+  assert.deepEqual(state.harnesses, HARNESSES);
+  assert.equal(state.git, "existing");
+  assert.equal(state.memory, "local");
+  assert.doesNotMatch(JSON.stringify(state), new RegExp(sandbox.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")));
+
+  const beforeMtimes = new Map([...legacy.posixBefore.keys()].map((path) => [path, statSync(join(target, ...path.split("/"))).mtimeMs]));
+  const rerun = await production.reconcile.reconcileSetupPlan(plan);
+  assert.equal(rerun.counts.created, 0);
+  assert.equal(rerun.counts.updated, 0);
+  assert.equal(rerun.counts.skipped, 0);
+  for (const [path, mtime] of beforeMtimes) assert.equal(statSync(join(target, ...path.split("/"))).mtimeMs, mtime, `rerun touched ${path}`);
+}
+
+async function main() {
+  const sandbox = mkdtempSync(join(tmpdir(), "cairn-setup-compatibility-"));
+  try {
+    const legacy = validateLegacyOracles(sandbox);
+    let production;
+    try {
+      production = await loadProduction();
+    } catch (error) {
+      const message = String(error?.message ?? "");
+      if (error?.code === "ERR_MODULE_NOT_FOUND" && (message.includes("setup-core.mjs") || message.includes("setup-reconcile.mjs"))) {
+        console.log(RED_MARKER);
+        process.exitCode = EXPECTED_RED_EXIT;
+        return;
+      }
+      throw error;
+    }
+    assertProductionExports(production);
+    await testSetupCompatibility(production, sandbox, legacy);
+    console.log("PASS: legacy POSIX/Windows bootstrap and deterministic setup compatibility contract");
+  } finally {
+    rmSync(sandbox, { recursive: true, force: true });
+  }
+}
+
+await main();

package/scripts/test-setup-output.sh

@@ -0,0 +1,131 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+EXPECTED_RED_EXIT=86
+RED_MARKER="PHASE26_RED:SETUP_OUTPUT_MISSING"
+MANAGED_PATHS=(.ai .planning .agentfs)
+
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+
+assert_no_managed_paths() {
+  local target=$1 label=$2 path
+  for path in "${MANAGED_PATHS[@]}"; do
+    [[ ! -e "$target/$path" ]] || fail "$label created $path"
+  done
+}
+
+# Baseline and fixture checks always run, including while this is an intentional
+# RED contract. This keeps routine test discovery useful before setup ships.
+"$ROOT/bin/cairn" help >/dev/null || fail "existing help dispatch failed"
+mkdir -p "$tmp/complete target" "$tmp/limited target" "$tmp/invalid target"
+printf 'operator\n' >"$tmp/invalid target/operator.txt"
+assert_no_managed_paths "$tmp/complete target" "complete fixture"
+assert_no_managed_paths "$tmp/limited target" "limited fixture"
+assert_no_managed_paths "$tmp/invalid target" "invalid fixture"
+
+setup_surface_complete=true
+for required in \
+  "$ROOT/scripts/setup.mjs" \
+  "$ROOT/scripts/setup-core.mjs" \
+  "$ROOT/scripts/setup-reconcile.mjs" \
+  "$ROOT/schemas/cairnkeep-setup.schema.json" \
+  "$ROOT/schemas/cairnkeep-setup-policy.schema.json"; do
+  [[ -f "$required" ]] || setup_surface_complete=false
+done
+
+if [[ "$setup_surface_complete" != true ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "$RED_MARKER"
+    exit "$EXPECTED_RED_EXIT"
+  fi
+  echo "SKIP: guided setup output production surface is not complete"
+  exit 0
+fi
+
+complete_json="$tmp/complete.json"
+"$ROOT/bin/cairn" setup "$tmp/complete target" \
+  --git init --harness claude,pi --memory local --yes --json >"$complete_json"
+node --input-type=module - "$complete_json" <<'NODE'
+import assert from "node:assert/strict";
+import fs from "node:fs";
+
+const result = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+assert.equal(result.schema_version, 1);
+assert.equal(result.status, "complete");
+assert.equal(result.git, "init");
+assert.equal(result.memory, "local");
+assert.deepEqual(result.harnesses, ["claude", "pi"]);
+assert.deepEqual(Object.keys(result.counts).sort(), ["created", "skipped", "unchanged", "updated"]);
+for (const value of Object.values(result.counts)) assert.equal(Number.isInteger(value) && value >= 0, true);
+assert.equal(Array.isArray(result.verification) && result.verification.length > 0, true);
+assert.equal(Array.isArray(result.launch_commands) && result.launch_commands.length, 2);
+assert.equal(result.launch_commands.some((line) => /start-claude\.sh/.test(line)), true);
+assert.equal(result.launch_commands.some((line) => /start-pi\.sh/.test(line)), true);
+assert.equal(Array.isArray(result.recovery), true);
+assert.equal(result.machine_sync.automatic, false);
+assert.match(result.machine_sync.command, /^cairn sync(?:-pi)? --(?:check|apply)/);
+NODE
+
+complete_human="$tmp/complete.txt"
+"$ROOT/bin/cairn" setup "$tmp/complete target" \
+  --git init --harness claude,pi --memory local --yes >"$complete_human"
+for expected in \
+  "Harnesses: claude, pi" \
+  "Git mode: init" \
+  "Memory mode: local" \
+  "Created:" \
+  "Updated:" \
+  "Unchanged:" \
+  "Skipped:" \
+  "Verification:" \
+  "Launch:" \
+  "Recovery:"; do
+  grep -qF "$expected" "$complete_human" || fail "human output missing $expected"
+done
+grep -qE 'cairn sync(-pi)? --(check|apply)' "$complete_human" || fail "human output omitted explicit machine sync direction"
+
+limited_json="$tmp/limited.json"
+"$ROOT/bin/cairn" setup "$tmp/limited target" \
+  --git none --harness kimi --memory none --yes --json >"$limited_json"
+node --input-type=module - "$limited_json" <<'NODE'
+import assert from "node:assert/strict";
+import fs from "node:fs";
+const result = JSON.parse(fs.readFileSync(process.argv[2], "utf8"));
+assert.equal(result.schema_version, 1);
+assert.equal(result.status, "limited");
+assert.equal(result.git, "none");
+assert.equal(result.memory, "none");
+assert.deepEqual(result.harnesses, ["kimi"]);
+assert.equal(Array.isArray(result.limitations) && result.limitations.length > 0, true);
+assert.equal(result.limitations.some((line) => /git|repository/i.test(line)), true);
+assert.equal(Array.isArray(result.recovery), true);
+NODE
+
+set +e
+"$ROOT/bin/cairn" setup "$tmp/invalid target" --yes >"$tmp/incomplete.out" 2>"$tmp/incomplete.err"
+incomplete_status=$?
+"$ROOT/bin/cairn" setup "$tmp/invalid target" --git sometimes --harness claude --memory local --yes >"$tmp/invalid.out" 2>"$tmp/invalid.err"
+invalid_status=$?
+set -e
+[[ "$incomplete_status" -eq 2 ]] || fail "incomplete non-TTY choices must exit 2"
+[[ "$invalid_status" -eq 2 ]] || fail "invalid syntax must exit 2"
+grep -Eqi 'usage|requires|missing' "$tmp/incomplete.err" || fail "incomplete choices lack actionable usage"
+grep -Eqi 'git|invalid|usage' "$tmp/invalid.err" || fail "invalid Git mode lacks actionable usage"
+assert_no_managed_paths "$tmp/invalid target" "usage failures"
+
+mkdir -p "$tmp/no-git-bin"
+ln -s "$(command -v node)" "$tmp/no-git-bin/node"
+set +e
+PATH="$tmp/no-git-bin" "$ROOT/bin/cairn" setup "$tmp/operational target" \
+  --git existing --harness claude --memory local --yes >"$tmp/operational.out" 2>"$tmp/operational.err"
+operational_status=$?
+set -e
+[[ "$operational_status" -ne 0 && "$operational_status" -ne 2 ]] || fail "missing Git was collapsed into a usage error"
+grep -qi 'git' "$tmp/operational.err" || fail "missing Git failure lacks recovery context"
+assert_no_managed_paths "$tmp/operational target" "operational preflight failure"
+
+echo "PASS: guided setup human, JSON, limited, usage, and recovery output contract"