@cairnkeep/cli 2.8.0 → 2.11.0

package/scripts/test-setup-overlay.sh

@@ -0,0 +1,113 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+ROOT=$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)
+EXPECTED_RED_EXIT=86
+RED_MARKER="PHASE26_RED:SETUP_OVERLAY_MISSING"
+
+fail() { echo "FAIL: $1" >&2; exit 1; }
+
+# The existing managed-distribution schema and package checks remain part of
+# this contract and must pass before the new setup-policy seam is evaluated.
+bash "$ROOT/scripts/test-overlay-schema.sh" >/dev/null || fail "existing overlay schema contract failed"
+
+tmp=$(mktemp -d)
+trap 'rm -rf "$tmp"' EXIT
+mkdir -p "$tmp/project"
+printf '%s\n' '{"schema_version":1,"defaults":{"git":"none","harnesses":["claude","pi"],"memory":"local"},"constraints":{"git":["none","existing"],"harnesses":["claude","pi"],"required_harnesses":["pi"],"memory":["local"]}}' >"$tmp/policy.json"
+node -e 'const p=require(process.argv[1]);if(p.schema_version!==1||Object.keys(p).sort().join(",")!=="constraints,defaults,schema_version")process.exit(1)' "$tmp/policy.json" || fail "policy fixture is invalid"
+[[ ! -e "$tmp/project/.ai" && ! -e "$tmp/project/.planning" && ! -e "$tmp/project/.agentfs" ]] || fail "policy fixture created managed paths"
+
+if [[ ! -f "$ROOT/scripts/setup-core.mjs" || ! -f "$ROOT/schemas/cairnkeep-setup-policy.schema.json" ]]; then
+  if [[ "${CAIRN_PHASE26_RED:-0}" == 1 ]]; then
+    echo "$RED_MARKER"
+    exit "$EXPECTED_RED_EXIT"
+  fi
+  echo "SKIP: setup overlay policy production surface is not complete"
+  exit 0
+fi
+
+node --input-type=module - "$ROOT" "$tmp" <<'NODE'
+import assert from "node:assert/strict";
+import fs from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+
+const [root, sandbox] = process.argv.slice(2);
+const core = await import(pathToFileURL(path.join(root, "scripts/setup-core.mjs")).href);
+const policyPath = path.join(sandbox, "policy.json");
+const target = path.join(sandbox, "project");
+const policy = core.readSetupPolicy(policyPath);
+
+assert.deepEqual(Object.keys(policy).sort(), ["constraints", "defaults", "schema_version"]);
+assert.equal(policy.schema_version, 1);
+assert.deepEqual(policy.defaults, { git: "none", harnesses: ["claude", "pi"], memory: "local" });
+
+const fromDefaults = core.resolveSetupChoices({
+  parsed: { target, git: null, harnesses: null, memory: null, confirmed: true },
+  preflight: { targetState: "empty", gitExecutable: "available", repository: "none" },
+  policy,
+  interactive: null,
+});
+assert.equal(fromDefaults.git, "none");
+assert.deepEqual(fromDefaults.harnesses, ["claude", "pi"]);
+assert.equal(fromDefaults.memory, "local");
+
+const cliWins = core.resolveSetupChoices({
+  parsed: { target, git: "existing", harnesses: ["pi"], memory: "local", confirmed: true },
+  preflight: { targetState: "non-empty", gitExecutable: "available", repository: "work-tree" },
+  policy,
+  interactive: null,
+});
+assert.equal(cliWins.git, "existing");
+assert.deepEqual(cliWins.harnesses, ["pi"]);
+assert.equal(cliWins.memory, "local");
+
+assert.throws(
+  () => core.resolveSetupChoices({
+    parsed: { target, git: "existing", harnesses: ["claude"], memory: "local", confirmed: true },
+    preflight: { targetState: "non-empty", gitExecutable: "available", repository: "work-tree" },
+    policy,
+    interactive: null,
+  }),
+  /constraint|required|pi/i,
+);
+
+const invalidPolicies = {
+  unknown: { schema_version: 1, defaults: {}, constraints: {}, extra: true },
+  version: { schema_version: 2, defaults: {}, constraints: {} },
+  url: { schema_version: 1, defaults: {}, constraints: {}, endpoint: "https://example.invalid" },
+  credential: { schema_version: 1, defaults: {}, constraints: {}, token: "fixture-secret" },
+  executable: { schema_version: 1, defaults: { launcher: "node helper.mjs" }, constraints: {} },
+};
+for (const [name, value] of Object.entries(invalidPolicies)) {
+  const candidate = path.join(sandbox, `${name}.json`);
+  fs.writeFileSync(candidate, `${JSON.stringify(value)}\n`);
+  assert.throws(() => core.readSetupPolicy(candidate), /invalid|unknown|policy|schema|allowed/i, name);
+}
+
+const oversized = path.join(sandbox, "oversized.json");
+fs.writeFileSync(oversized, " ".repeat(1024 * 1024 + 1));
+assert.throws(() => core.readSetupPolicy(oversized), /size|large|policy/i);
+
+const linked = path.join(sandbox, "linked.json");
+fs.symlinkSync(policyPath, linked);
+assert.throws(() => core.readSetupPolicy(linked), /symbolic|symlink|unsafe|policy/i);
+
+const executable = path.join(sandbox, "executable.json");
+fs.writeFileSync(executable, '{"schema_version":1,"defaults":{},"constraints":{}}\n', { mode: 0o755 });
+fs.chmodSync(executable, 0o755);
+assert.throws(() => core.readSetupPolicy(executable), /executable|mode|unsafe|policy/i);
+
+for (const managed of [".ai", ".planning", ".agentfs"]) {
+  assert.equal(fs.existsSync(path.join(target, managed)), false, `policy validation created ${managed}`);
+}
+
+const schema = JSON.parse(fs.readFileSync(path.join(root, "schemas/cairnkeep-setup-policy.schema.json"), "utf8"));
+assert.equal(schema.$schema, "https://json-schema.org/draft/2020-12/schema");
+assert.equal(schema.additionalProperties, false);
+assert.deepEqual(schema.required, ["schema_version", "defaults", "constraints"]);
+assert.deepEqual(Object.keys(schema.properties).sort(), ["constraints", "defaults", "schema_version"]);
+NODE
+
+echo "PASS: provider-neutral setup overlay policy and precedence contract"

package/scripts/test-setup-preflight.mjs

@@ -0,0 +1,281 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import {
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const EXPECTED_RED_EXIT = 86;
+const RED_MARKER = "PHASE26_RED:SETUP_CORE_MISSING";
+const here = dirname(fileURLToPath(import.meta.url));
+const setupCorePath = join(here, "setup-core.mjs");
+const setupPath = join(here, "setup.mjs");
+const MANAGED_PATHS = [".ai", ".planning", ".agentfs"];
+
+function assertNoManagedPaths(target, label) {
+  for (const relative of MANAGED_PATHS) {
+    assert.equal(existsSync(join(target, relative)), false, `${label} created ${relative}`);
+  }
+}
+
+function assertUsageError(fn, field) {
+  assert.throws(fn, (error) => {
+    assert.equal(error?.kind, "usage");
+    assert.equal(error?.status, 2);
+    assert.match(String(error?.message), new RegExp(field, "i"));
+    assert.match(String(error?.message), /usage|requires|invalid|missing/i);
+    return true;
+  });
+}
+
+function validateFixtures() {
+  const sandbox = mkdtempSync(join(tmpdir(), "cairn-setup-preflight-fixture-"));
+  try {
+    const missing = join(sandbox, "missing");
+    const empty = join(sandbox, "empty");
+    const nonempty = join(sandbox, "nonempty");
+    const linked = join(sandbox, "linked");
+    mkdirSync(empty);
+    mkdirSync(nonempty);
+    writeFileSync(join(nonempty, "operator.txt"), "preserve\n");
+    symlinkSync(nonempty, linked, "dir");
+    assert.equal(existsSync(missing), false);
+    assert.deepEqual(lstatSync(empty).isDirectory(), true);
+    assert.deepEqual(lstatSync(nonempty).isDirectory(), true);
+    assert.deepEqual(lstatSync(linked).isSymbolicLink(), true);
+    assertNoManagedPaths(sandbox, "fixture self-validation");
+
+    const invocations = [];
+    const run = (executable, args, options) => {
+      invocations.push({ executable, args: [...args], options: { ...options } });
+      return { status: 0, stdout: "git version fixture\n", stderr: "" };
+    };
+    run("git", ["--version"], { encoding: "utf8", shell: false });
+    assert.deepEqual(invocations, [{
+      executable: "git",
+      args: ["--version"],
+      options: { encoding: "utf8", shell: false },
+    }]);
+    return { sandbox, missing, empty, nonempty, linked };
+  } catch (error) {
+    rmSync(sandbox, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function loadSetupCore() {
+  return import(pathToFileURL(setupCorePath).href);
+}
+
+async function loadSetup() {
+  return import(pathToFileURL(setupPath).href);
+}
+
+function assertExports(core) {
+  for (const name of [
+    "parseSetupArgs",
+    "readSetupPolicy",
+    "classifySetupTarget",
+    "resolveSetupChoices",
+    "buildSetupPlan",
+  ]) assert.equal(typeof core[name], "function", `setup-core must export ${name}`);
+}
+
+function completeArgs(target) {
+  return [target, "--git", "init", "--harness", "claude,pi", "--memory", "local", "--yes"];
+}
+
+function testChoiceContract(core, fixture) {
+  const { parseSetupArgs, resolveSetupChoices } = core;
+  const complete = parseSetupArgs(completeArgs(fixture.missing), { isTTY: false });
+  assert.equal(complete.target, fixture.missing);
+  assert.equal(complete.git, "init");
+  assert.deepEqual(complete.harnesses, ["claude", "pi"]);
+  assert.equal(complete.memory, "local");
+  assert.equal(complete.confirmed, true);
+
+  const syntaxCases = [
+    { args: [fixture.empty, "--unknown"], field: "unknown" },
+    { args: [fixture.empty, "--git"], field: "git" },
+    { args: [fixture.empty, "--git", "sometimes"], field: "git" },
+    { args: [fixture.empty, "--harness", "claude,unknown"], field: "harness" },
+    { args: [fixture.empty, "--memory", "remote"], field: "memory" },
+    { args: [fixture.empty, fixture.nonempty], field: "target|path|positional" },
+  ];
+  for (const { args, field } of syntaxCases) {
+    assertUsageError(() => parseSetupArgs(args, { isTTY: false }), field);
+    assertNoManagedPaths(fixture.sandbox, `invalid syntax ${args.join(" ")}`);
+  }
+
+  const incompleteCases = [
+    { args: [], field: "target" },
+    { args: [fixture.empty, "--harness", "claude", "--memory", "local", "--yes"], field: "git" },
+    { args: [fixture.empty, "--git", "init", "--memory", "local", "--yes"], field: "harness" },
+    { args: [fixture.empty, "--git", "init", "--harness", "claude", "--yes"], field: "memory" },
+    { args: [fixture.empty, "--git", "init", "--harness", "claude", "--memory", "local"], field: "confirm|yes" },
+    { args: [fixture.empty, "--yes"], field: "git|harness|memory" },
+  ];
+  for (const { args, field } of incompleteCases) {
+    assertUsageError(() => parseSetupArgs(args, { isTTY: false }), field);
+    assertNoManagedPaths(fixture.sandbox, `incomplete non-TTY choices ${args.join(" ")}`);
+  }
+
+  const resolved = resolveSetupChoices({
+    parsed: complete,
+    preflight: { targetState: "missing", gitExecutable: "available", repository: "none" },
+    policy: null,
+    interactive: null,
+  });
+  assert.deepEqual(resolved.harnesses, ["claude", "pi"]);
+  assert.equal(resolved.git, "init");
+  assert.equal(resolved.memory, "local");
+  assert.equal(resolved.confirmed, true);
+  assert.equal(Object.isFrozen(resolved), true);
+}
+
+function scriptedGit(kind, calls) {
+  return (executable, args, options) => {
+    calls.push({ executable, args: [...args], options: { ...options } });
+    assert.equal(executable, "git");
+    assert.equal(options?.shell, false);
+    if (kind === "missing") return { status: null, stdout: "", stderr: "", error: { code: "ENOENT" } };
+    if (args.includes("--version")) return { status: 0, stdout: "git version fixture\n", stderr: "" };
+    if (kind === "bare") return { status: 0, stdout: "false\n", stderr: "" };
+    if (kind === "work-tree") return { status: 0, stdout: "true\n", stderr: "" };
+    return { status: 128, stdout: "", stderr: "not a repository" };
+  };
+}
+
+function testPreflightContract(core, fixture) {
+  const { classifySetupTarget, buildSetupPlan } = core;
+  const cases = [
+    [fixture.missing, "missing", "none"],
+    [fixture.empty, "empty", "none"],
+    [fixture.nonempty, "non-empty", "none"],
+    [fixture.empty, "empty", "work-tree"],
+    [fixture.nonempty, "non-empty", "bare"],
+    [fixture.nonempty, "non-empty", "missing"],
+  ];
+  for (const [target, targetState, gitKind] of cases) {
+    const calls = [];
+    const result = classifySetupTarget(target, { run: scriptedGit(gitKind, calls) });
+    assert.equal(result.targetState, targetState);
+    assert.equal(result.gitExecutable, gitKind === "missing" ? "missing" : "available");
+    assert.equal(result.repository, gitKind === "work-tree" ? "work-tree" : gitKind === "bare" ? "bare" : gitKind === "missing" ? "unknown" : "none");
+    assert.equal(Object.isFrozen(result), true);
+    assert.ok(calls.every(({ options }) => options.shell === false));
+    assertNoManagedPaths(fixture.sandbox, `preflight ${targetState}/${gitKind}`);
+  }
+
+  assert.throws(
+    () => classifySetupTarget(fixture.linked, { run: scriptedGit("none", []) }),
+    (error) => error?.kind === "unsafe-target" && error?.status !== 2,
+  );
+  assertNoManagedPaths(fixture.sandbox, "unsafe symlink target");
+
+  const plan = buildSetupPlan({
+    target: fixture.missing,
+    preflight: { targetState: "missing", gitExecutable: "available", repository: "none" },
+    choices: Object.freeze({ git: "init", harnesses: ["claude", "pi"], memory: "local", confirmed: true }),
+  });
+  assert.equal(plan.target, resolve(fixture.missing));
+  assert.deepEqual(plan.harnesses, ["claude", "pi"]);
+  assert.equal(plan.git, "init");
+  assert.equal(plan.memory, "local");
+  assert.ok(Array.isArray(plan.assets));
+  assert.equal(Object.isFrozen(plan), true);
+  assertNoManagedPaths(fixture.sandbox, "mutation planning");
+}
+
+function captureStream() {
+  let output = "";
+  return {
+    stream: { write(value) { output += String(value); return true; } },
+    read() { return output; },
+  };
+}
+
+async function runInteractive(setup, args, responses) {
+  const prompts = [];
+  const remaining = [...responses];
+  const output = captureStream();
+  const error = captureStream();
+  const status = await setup.runSetup(args, {
+    isTTY: true,
+    input: { isTTY: false },
+    output: output.stream,
+    error: error.stream,
+    question: async (prompt) => {
+      prompts.push(prompt);
+      assert.ok(remaining.length > 0, `unexpected interactive prompt: ${prompt}`);
+      return remaining.shift();
+    },
+  });
+  assert.deepEqual(remaining, [], "not all scripted interactive answers were consumed");
+  return { status, prompts, output: output.read(), error: error.read() };
+}
+
+async function testInteractiveGitRecommendation(setup, fixture) {
+  const accepted = await runInteractive(setup, [], [fixture.missing, "init", "pi", "local", "yes"]);
+  assert.equal(accepted.status, 0);
+  assert.equal(accepted.error, "");
+  assert.match(accepted.prompts[0], /target path/i);
+  assert.match(accepted.prompts[1], /init recommended/i);
+  assert.equal(existsSync(join(fixture.missing, ".git")), true);
+  assert.equal(existsSync(join(fixture.missing, ".ai", "cairnkeep.json")), true);
+
+  const refused = await runInteractive(setup, [fixture.empty], ["init", "pi", "local", "no"]);
+  assert.equal(refused.status, 0);
+  assert.equal(refused.error, "");
+  assert.ok(refused.prompts.some((prompt) => /init recommended/i.test(prompt)));
+  assert.match(refused.output, /cancelled; no files were changed/i);
+  assert.equal(existsSync(join(fixture.empty, ".git")), false);
+  assertNoManagedPaths(fixture.empty, "refused interactive setup");
+
+  const existing = await runInteractive(setup, [fixture.nonempty], ["none", "pi", "local", "yes"]);
+  assert.equal(existing.status, 0);
+  assert.equal(existing.error, "");
+  const gitPrompt = existing.prompts.find((prompt) => /Git mode/i.test(prompt));
+  assert.match(gitPrompt, /init requires explicit choice/i);
+  assert.doesNotMatch(gitPrompt, /init recommended/i);
+  assert.equal(existsSync(join(fixture.nonempty, ".git")), false);
+  assert.equal(readFileSync(join(fixture.nonempty, "operator.txt"), "utf8"), "preserve\n");
+  assert.equal(existsSync(join(fixture.nonempty, ".ai", "cairnkeep.json")), true);
+}
+
+async function main() {
+  const fixture = validateFixtures();
+  try {
+    let core;
+    try {
+      core = await loadSetupCore();
+    } catch (error) {
+      if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.message).includes("setup-core.mjs")) {
+        console.log(RED_MARKER);
+        process.exitCode = EXPECTED_RED_EXIT;
+        return;
+      }
+      throw error;
+    }
+    assertExports(core);
+    testChoiceContract(core, fixture);
+    testPreflightContract(core, fixture);
+    const setup = await loadSetup();
+    await testInteractiveGitRecommendation(setup, fixture);
+    console.log("PASS: setup target, Git, syntax, choice, and no-write preflight contract");
+  } finally {
+    rmSync(fixture.sandbox, { recursive: true, force: true });
+  }
+}
+
+await main();

package/scripts/test-setup-reconcile.mjs

@@ -0,0 +1,257 @@
+#!/usr/bin/env node
+
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import {
+  chmodSync,
+  existsSync,
+  lstatSync,
+  mkdtempSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  symlinkSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+const EXPECTED_RED_EXIT = 86;
+const RED_MARKER = "PHASE26_RED:SETUP_RECONCILE_MISSING";
+const here = dirname(fileURLToPath(import.meta.url));
+const reconcilerPath = join(here, "setup-reconcile.mjs");
+
+function digest(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+function asset(path, value, mode, template, harness = null) {
+  return Object.freeze({
+    path,
+    bytes: Buffer.from(value, "utf8"),
+    mode,
+    template,
+    ...(harness ? { harness } : {}),
+  });
+}
+
+function plan(target, assets, overrides = {}) {
+  return Object.freeze({
+    target: resolve(target),
+    version: "fixture-1",
+    git: "existing",
+    memory: "local",
+    harnesses: ["claude"],
+    assets: Object.freeze(assets),
+    ...overrides,
+  });
+}
+
+function ownedState(rows, overrides = {}) {
+  return {
+    schema_version: 1,
+    cairnkeep_version: "fixture-1",
+    git: "existing",
+    memory: "local",
+    harnesses: ["claude"],
+    assets: Object.fromEntries(rows.map(({ path, bytes, mode, template }) => [path, {
+      digest: digest(bytes),
+      mode,
+      template,
+    }])),
+    ...overrides,
+  };
+}
+
+function assertCounts(result, counts) {
+  assert.deepEqual(result.counts, counts);
+  assert.deepEqual(
+    result.changes.map(({ status }) => status).sort(),
+    Object.entries(counts).flatMap(([status, count]) => Array(count).fill(status)).sort(),
+  );
+}
+
+function assertStrictState(state, target) {
+  assert.deepEqual(Object.keys(state).sort(), [
+    "assets",
+    "cairnkeep_version",
+    "git",
+    "harnesses",
+    "memory",
+    "schema_version",
+  ]);
+  assert.equal(state.schema_version, 1);
+  assert.deepEqual(state.harnesses, ["claude"]);
+  assert.ok(["existing", "init", "none"].includes(state.git));
+  assert.ok(["local", "none"].includes(state.memory));
+  for (const [path, record] of Object.entries(state.assets)) {
+    assert.equal(path.startsWith(".") && !path.startsWith("..") && !path.includes("\\"), true, `unsafe state path ${path}`);
+    assert.deepEqual(Object.keys(record).sort(), ["digest", "mode", "template"]);
+    assert.match(record.digest, /^[a-f0-9]{64}$/);
+    assert.equal(Number.isInteger(record.mode), true);
+    assert.equal(typeof record.template, "string");
+  }
+  const serialized = JSON.stringify(state);
+  assert.equal(serialized.includes(resolve(target)), false, "state leaked absolute target");
+  assert.doesNotMatch(serialized, /(?:token|secret|credential|endpoint|username|environment|https?:)/i);
+}
+
+function validateFixtures() {
+  const sandbox = mkdtempSync(join(tmpdir(), "cairn-setup-reconcile-fixture-"));
+  try {
+    const target = join(sandbox, "project");
+    const outside = join(sandbox, "outside");
+    mkdirSync(target);
+    mkdirSync(outside);
+    const first = asset(".ai/start-claude.sh", "#!/bin/sh\necho one\n", 0o755, "start-claude.sh.template", "claude");
+    const config = asset(".planning/config.json", "{\"fixture\":true}\n", 0o644, "planning-config.json.template");
+    assert.equal(first.path.startsWith(".ai/"), true);
+    assert.equal(config.path.startsWith(".planning/"), true);
+    assert.equal(digest(first.bytes), createHash("sha256").update(first.bytes).digest("hex"));
+    assert.deepEqual(ownedState([first]).assets[first.path], {
+      digest: digest(first.bytes),
+      mode: 0o755,
+      template: "start-claude.sh.template",
+    });
+    return { sandbox, target, outside, first, config };
+  } catch (error) {
+    rmSync(sandbox, { recursive: true, force: true });
+    throw error;
+  }
+}
+
+async function loadReconciler() {
+  return import(pathToFileURL(reconcilerPath).href);
+}
+
+function assertExports(reconciler) {
+  assert.equal(reconciler.SETUP_STATE_SCHEMA_VERSION, 1);
+  for (const name of ["hashSetupAsset", "reconcileSetupPlan", "writeSetupStateAtomic"]) {
+    assert.equal(typeof reconciler[name], "function", `setup-reconcile must export ${name}`);
+  }
+}
+
+async function testCreateAndIdempotence(reconciler, fixture) {
+  const selectedPlan = plan(fixture.target, [fixture.first, fixture.config]);
+  const unselected = join(fixture.target, ".ai", "start-pi.sh");
+  mkdirSync(dirname(unselected), { recursive: true });
+  symlinkSync(join(fixture.outside, "missing-pi"), unselected);
+
+  const created = await reconciler.reconcileSetupPlan(selectedPlan);
+  assertCounts(created, { created: 2, updated: 0, unchanged: 0, skipped: 0 });
+  assert.deepEqual(readFileSync(join(fixture.target, fixture.first.path)), fixture.first.bytes);
+  assert.deepEqual(readFileSync(join(fixture.target, fixture.config.path)), fixture.config.bytes);
+  assert.equal((statSync(join(fixture.target, fixture.first.path)).mode & 0o777), 0o755);
+  assert.equal((statSync(join(fixture.target, fixture.config.path)).mode & 0o777), 0o644);
+  assert.equal(lstatSync(unselected).isSymbolicLink(), true, "unselected harness asset was inspected or removed");
+  assertStrictState(created.state, fixture.target);
+  const statePath = join(fixture.target, ".ai", "cairnkeep.json");
+  assert.deepEqual(JSON.parse(readFileSync(statePath, "utf8")), created.state);
+
+  const mtimes = new Map(selectedPlan.assets.map(({ path }) => [path, statSync(join(fixture.target, path)).mtimeMs]));
+  const stateMtime = statSync(statePath).mtimeMs;
+  const unchanged = await reconciler.reconcileSetupPlan(selectedPlan);
+  assertCounts(unchanged, { created: 0, updated: 0, unchanged: 2, skipped: 0 });
+  for (const [path, mtime] of mtimes) assert.equal(statSync(join(fixture.target, path)).mtimeMs, mtime, `identical rerun touched ${path}`);
+  assert.equal(statSync(statePath).mtimeMs, stateMtime, "identical rerun rewrote setup state");
+  assert.equal(lstatSync(unselected).isSymbolicLink(), true);
+  return { selectedPlan, created };
+}
+
+async function testOwnershipBranches(reconciler, fixture, baseline) {
+  const ownedPath = join(fixture.target, fixture.first.path);
+  const previous = baseline.created.state;
+
+  const next = asset(fixture.first.path, "#!/bin/sh\necho two\n", 0o755, fixture.first.template, "claude");
+  const updated = await reconciler.reconcileSetupPlan(plan(fixture.target, [next]), { previousState: previous });
+  assertCounts(updated, { created: 0, updated: 1, unchanged: 0, skipped: 0 });
+  assert.deepEqual(readFileSync(ownedPath), next.bytes);
+
+  writeFileSync(ownedPath, "operator-owned\n");
+  chmodSync(ownedPath, 0o700);
+  const userBytes = readFileSync(ownedPath);
+  const userMtime = statSync(ownedPath).mtimeMs;
+  const diverged = await reconciler.reconcileSetupPlan(plan(fixture.target, [fixture.first]), { previousState: updated.state });
+  assertCounts(diverged, { created: 0, updated: 0, unchanged: 0, skipped: 1 });
+  assert.deepEqual(readFileSync(ownedPath), userBytes);
+  assert.equal(statSync(ownedPath).mtimeMs, userMtime);
+
+  const unownedPath = join(fixture.target, ".planning", "operator.md");
+  writeFileSync(unownedPath, "operator\n");
+  const unowned = asset(".planning/operator.md", "desired\n", 0o644, "operator.template");
+  const skipped = await reconciler.reconcileSetupPlan(plan(fixture.target, [unowned]), { previousState: null });
+  assertCounts(skipped, { created: 0, updated: 0, unchanged: 0, skipped: 1 });
+  assert.equal(readFileSync(unownedPath, "utf8"), "operator\n");
+}
+
+async function testUnsafePaths(reconciler, fixture) {
+  for (const kind of ["symlink-ancestor", "file-ancestor", "symlink-destination"]) {
+    const target = join(fixture.sandbox, kind);
+    mkdirSync(target);
+    const outsideSentinel = join(fixture.outside, `${kind}.txt`);
+    writeFileSync(outsideSentinel, "outside\n");
+    if (kind === "symlink-ancestor") symlinkSync(fixture.outside, join(target, ".ai"), "dir");
+    else if (kind === "file-ancestor") writeFileSync(join(target, ".ai"), "not-a-directory\n");
+    else {
+      mkdirSync(join(target, ".ai"));
+      symlinkSync(outsideSentinel, join(target, ".ai", "start-claude.sh"));
+    }
+    await assert.rejects(
+      reconciler.reconcileSetupPlan(plan(target, [fixture.first])),
+      /unsafe|symbolic|regular|contain|ancestor/i,
+    );
+    assert.equal(readFileSync(outsideSentinel, "utf8"), "outside\n");
+    assert.equal(existsSync(join(target, ".planning")), false, `${kind} left partial state`);
+    assert.equal(existsSync(join(target, ".agentfs")), false, `${kind} left partial state`);
+  }
+}
+
+async function testStateInterruptionAndPrivacy(reconciler, fixture) {
+  const statePath = join(fixture.target, ".ai", "cairnkeep.json");
+  const before = readFileSync(statePath);
+  const hostile = ownedState([fixture.first], { endpoint: "https://invalid.example", target: fixture.target });
+  await assert.rejects(reconciler.writeSetupStateAtomic(statePath, hostile), /invalid|unknown|unsafe|state/i);
+  assert.deepEqual(readFileSync(statePath), before);
+
+  const replacement = ownedState([fixture.first], { cairnkeep_version: "fixture-2" });
+  await assert.rejects(
+    reconciler.writeSetupStateAtomic(statePath, replacement, {
+      atomicReplace: async () => { throw new Error("fixture interruption before replacement"); },
+    }),
+    /fixture interruption/,
+  );
+  assert.deepEqual(readFileSync(statePath), before, "interrupted replacement changed prior state");
+  const temporary = readdirSync(dirname(statePath)).filter((name) => name.includes("cairnkeep.json") && name.endsWith(".tmp"));
+  assert.deepEqual(temporary, [], "interrupted replacement leaked a temporary state file");
+}
+
+async function main() {
+  const fixture = validateFixtures();
+  try {
+    let reconciler;
+    try {
+      reconciler = await loadReconciler();
+    } catch (error) {
+      if (error?.code === "ERR_MODULE_NOT_FOUND" && String(error.message).includes("setup-reconcile.mjs")) {
+        console.log(RED_MARKER);
+        process.exitCode = EXPECTED_RED_EXIT;
+        return;
+      }
+      throw error;
+    }
+    assertExports(reconciler);
+    assert.equal(reconciler.hashSetupAsset(fixture.first.bytes), digest(fixture.first.bytes));
+    const baseline = await testCreateAndIdempotence(reconciler, fixture);
+    await testOwnershipBranches(reconciler, fixture, baseline);
+    await testUnsafePaths(reconciler, fixture);
+    await testStateInterruptionAndPrivacy(reconciler, fixture);
+    console.log("PASS: setup ownership, idempotence, containment, privacy, and atomic state contract");
+  } finally {
+    rmSync(fixture.sandbox, { recursive: true, force: true });
+  }
+}
+
+await main();