@indigoai-us/hq-cloud 6.18.44-alpha.48 → 6.18.44-alpha.49

package/dist/cli/rescue-settings-reconcile.test.js

@@ -0,0 +1,610 @@
+/**
+ * Regression tests for the `.claude/settings.json` reconcile in rescue-core.ts.
+ *
+ * `.claude/settings.json` is a machine-local, *generated* file: setup.sh step 3b
+ * composes the machine's env.PATH into the release's PATH-less template. On an
+ * existing install it therefore always differs from every release blob, so the
+ * old rescue rescued it into personal/ and laid a PATH-less template on top —
+ * dropping the machine PATH and (per drift/history state) failing to wire in a
+ * newly-released hook registration even though the hook FILE synced in.
+ *
+ * The fix re-composes env.PATH onto the release baseline and relocates genuine
+ * user drift (vs the last-sync floor) into settings.local.json. These tests
+ * cover the pure drift/merge helpers and reproduce the real field case with a
+ * real (non-dry-run) overlay against a local fixture "release" repo.
+ */
+import { describe, it, expect, beforeAll, afterAll } from "vitest";
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { runRescue, reconcileClaudeSettings, settingsDrift, deepMergeSettings, applyArrayRemovals, jsonDeepEqual, } from "./rescue-core.js";
+import { setupPathSettingsLocalFlagEnabled } from "./rescue.js";
+describe("rescue setup PATH flag", () => {
+    it("uses the core flag reader and defaults off when the reader is unavailable", () => {
+        const root = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-path-flag-"));
+        const reader = path.join(root, "core", "scripts", "setup-path-flag.cjs");
+        fs.mkdirSync(path.dirname(reader), { recursive: true });
+        try {
+            fs.writeFileSync(reader, 'process.stdout.write("true\\n");\n');
+            expect(setupPathSettingsLocalFlagEnabled(root, {})).toBe(true);
+            fs.writeFileSync(reader, 'process.stdout.write("false\\n");\n');
+            expect(setupPathSettingsLocalFlagEnabled(root, {})).toBe(false);
+            fs.rmSync(reader);
+            expect(setupPathSettingsLocalFlagEnabled(root, {})).toBe(false);
+        }
+        finally {
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+    });
+});
+// ── Unit: pure drift / merge helpers ────────────────────────────────────────
+describe("settingsDrift", () => {
+    it("excludes env.PATH (machine-local) from drift", () => {
+        const ours = { env: { PATH: "/machine/bin:/usr/bin", MAX: "1" } };
+        const base = { env: { MAX: "1" } };
+        // Only PATH differs, and PATH is excluded -> no drift.
+        expect(settingsDrift(ours, base)).toBeUndefined();
+    });
+    it("captures an added scalar and a changed scalar", () => {
+        const ours = { model: "opus", newKey: "x" };
+        const base = { model: "sonnet" };
+        expect(settingsDrift(ours, base)).toEqual({ model: "opus", newKey: "x" });
+    });
+    it("captures only the extra array elements (union-friendly)", () => {
+        const ours = { permissions: { allow: ["Bash(git:*)", "Bash(mytool:*)"] } };
+        const base = { permissions: { allow: ["Bash(git:*)"] } };
+        expect(settingsDrift(ours, base)).toEqual({
+            permissions: { allow: ["Bash(mytool:*)"] },
+        });
+    });
+    it("returns undefined when ours equals base", () => {
+        const v = { a: 1, b: [1, 2], c: { d: "e" } };
+        expect(settingsDrift(v, structuredClone(v))).toBeUndefined();
+    });
+    it("treats a wholly-new subtree as drift but still honors env.PATH exclusion", () => {
+        const ours = { env: { PATH: "/machine/bin" } };
+        const base = {};
+        // env is new, but its only member is the excluded PATH -> no drift.
+        expect(settingsDrift(ours, base)).toBeUndefined();
+        const ours2 = { env: { PATH: "/machine/bin", HQ_FOO: "1" } };
+        expect(settingsDrift(ours2, {})).toEqual({ env: { HQ_FOO: "1" } });
+    });
+});
+describe("deepMergeSettings", () => {
+    it("unions arrays without duplicates and adds absent scalars", () => {
+        const target = { permissions: { allow: ["Bash(git:*)"] } };
+        const patch = { permissions: { allow: ["Bash(git:*)", "Bash(mytool:*)"] }, model: "opus" };
+        deepMergeSettings(target, patch);
+        expect(target.permissions.allow).toEqual(["Bash(git:*)", "Bash(mytool:*)"]);
+        expect(target.model).toBe("opus"); // absent -> added
+    });
+    it("does NOT overwrite a scalar already present in the target (Local wins)", () => {
+        // Project drift `model: opus` must not clobber the higher-precedence Local
+        // `model: sonnet` — the effective config must remain sonnet.
+        const target = { model: "sonnet" };
+        deepMergeSettings(target, { model: "opus" });
+        expect(target.model).toBe("sonnet");
+    });
+    it("preserves an existing NESTED Local scalar while adding a sibling", () => {
+        // Local env.HQ_FOO must survive; only the genuinely-new HQ_BAR is introduced.
+        const target = { env: { HQ_FOO: "1" } };
+        deepMergeSettings(target, { env: { HQ_FOO: "2", HQ_BAR: "3" } });
+        expect(target.env).toEqual({ HQ_FOO: "1", HQ_BAR: "3" });
+    });
+    it("preserves existing Local array elements and never drops a sibling key", () => {
+        // The existing allow entry and the untouched deny key must both survive; the
+        // drift permission is appended, not substituted.
+        const target = { permissions: { allow: ["Bash(git:*)"], deny: ["Read(~/.ssh/**)"] } };
+        deepMergeSettings(target, { permissions: { allow: ["Bash(mytool:*)"] } });
+        expect(target.permissions.allow).toEqual(["Bash(git:*)", "Bash(mytool:*)"]);
+        expect(target.permissions.deny).toEqual(["Read(~/.ssh/**)"]); // untouched sibling
+    });
+    it("keeps a Local value when the drift has the same key with a different type", () => {
+        // Local scalar must not be replaced by a Project array/object of the same key.
+        const target = { hooks: "local-wins" };
+        deepMergeSettings(target, {
+            hooks: { PreToolUse: [] },
+        });
+        expect(target.hooks).toBe("local-wins");
+    });
+    it("leaves keys unique to Local completely untouched", () => {
+        const target = { onlyLocal: { a: 1 }, model: "sonnet" };
+        deepMergeSettings(target, { permissions: { allow: ["X"] } });
+        expect(target.onlyLocal).toEqual({ a: 1 });
+        expect(target.model).toBe("sonnet");
+    });
+    it("is idempotent on re-merge (no duplicate array entries)", () => {
+        const target = { permissions: { allow: ["Bash(mytool:*)"] } };
+        deepMergeSettings(target, { permissions: { allow: ["Bash(mytool:*)"] } });
+        expect(target.permissions.allow).toEqual(["Bash(mytool:*)"]);
+    });
+});
+describe("applyArrayRemovals", () => {
+    it("removes an element the user deleted (present in base, absent in ours)", () => {
+        const theirs = { permissions: { allow: ["Bash(git:*)", "Bash(rm:*)"] } };
+        const ours = { permissions: { allow: ["Bash(git:*)"] } }; // user removed rm
+        const base = { permissions: { allow: ["Bash(git:*)", "Bash(rm:*)"] } };
+        applyArrayRemovals(theirs, ours, base);
+        expect(theirs.permissions.allow).toEqual(["Bash(git:*)"]);
+    });
+    it("leaves release-only additions intact (base lacked them)", () => {
+        const theirs = { permissions: { allow: ["Bash(git:*)", "Bash(new:*)"] } };
+        const ours = { permissions: { allow: ["Bash(git:*)"] } };
+        const base = { permissions: { allow: ["Bash(git:*)"] } }; // base never had new
+        applyArrayRemovals(theirs, ours, base);
+        // "Bash(new:*)" is a release addition, not a user removal — keep it.
+        expect(theirs.permissions.allow).toEqual(["Bash(git:*)", "Bash(new:*)"]);
+    });
+});
+describe("jsonDeepEqual", () => {
+    it("compares nested structures", () => {
+        expect(jsonDeepEqual({ a: [1, { b: 2 }] }, { a: [1, { b: 2 }] })).toBe(true);
+        expect(jsonDeepEqual({ a: [1] }, { a: [2] })).toBe(false);
+    });
+});
+// ── Integration: real overlay reproduces the field case ─────────────────────
+function hasBin(bin, args = ["--version"]) {
+    try {
+        execFileSync(bin, args, { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+const canRun = hasBin("git") && hasBin("rsync");
+function runRescueCapture(argv, env) {
+    let stdout = "";
+    let stderr = "";
+    const origOut = process.stdout.write.bind(process.stdout);
+    const origErr = process.stderr.write.bind(process.stderr);
+    process.stdout.write = ((chunk) => {
+        stdout += String(chunk);
+        return true;
+    });
+    process.stderr.write = ((chunk) => {
+        stderr += String(chunk);
+        return true;
+    });
+    let status;
+    try {
+        status = runRescue(argv, { env }).status;
+    }
+    finally {
+        process.stdout.write = origOut;
+        process.stderr.write = origErr;
+    }
+    return { status, stdout, stderr };
+}
+// A release composer fixture that adds managed toolchain paths. Rescue owns
+// ordering and temporary-path filtering around composer output.
+const COMPOSER = `#!/usr/bin/env bash
+set -euo pipefail
+BASE="\${1:-$PATH}"
+TOOLCHAIN="\${HQ_TOOLCHAIN_DIR:-$HOME/Library/Application Support/Indigo HQ/toolchain}"
+path_contains() { case ":$1:" in *":$2:"*) return 0 ;; *) return 1 ;; esac; }
+COMPOSED="$BASE"
+for dir in "$TOOLCHAIN/git/bin" "$TOOLCHAIN/npm-global/bin" "$TOOLCHAIN/node/bin"; do
+  if [[ -d "$dir" ]] && ! path_contains "$COMPOSED" "$dir"; then
+    COMPOSED="$dir:$COMPOSED"
+  fi
+done
+printf '%s\\n' "$COMPOSED"
+`;
+describe.skipIf(!canRun)("rescue .claude/settings.json reconcile (real overlay)", () => {
+    let workDir;
+    let upstream;
+    let shimDir;
+    let floorSha;
+    let env;
+    const MACHINE_PATH = "/opt/machine/bin:/usr/bin:/bin";
+    const NEW_HOOK_CMD = 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/new-hook.sh"';
+    const git = (cwd, ...args) => execFileSync("git", args, {
+        cwd,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: {
+            ...process.env,
+            GIT_AUTHOR_NAME: "t",
+            GIT_AUTHOR_EMAIL: "t@t",
+            GIT_COMMITTER_NAME: "t",
+            GIT_COMMITTER_EMAIL: "t@t",
+        },
+    })
+        .toString()
+        .trim();
+    // Release template as of the floor: PATH-less, with a baseline permission and
+    // a pre-existing hook, but WITHOUT the new-hook registration.
+    const floorSettings = {
+        model: "claude-opus-4-8",
+        permissions: { allow: ["Bash(git:*)"], deny: [] },
+        env: { MAX_THINKING_TOKENS: "31999" },
+        hooks: {
+            PreToolUse: [
+                { hooks: [{ type: "command", command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/old-hook.sh"' }] },
+            ],
+        },
+    };
+    // New release (HEAD): adds the new-hook FILE + its REGISTRATION. Still no PATH.
+    const headSettings = {
+        model: "claude-opus-4-8",
+        permissions: { allow: ["Bash(git:*)"], deny: [] },
+        env: { MAX_THINKING_TOKENS: "31999" },
+        hooks: {
+            PreToolUse: [
+                { hooks: [{ type: "command", command: 'bash "$CLAUDE_PROJECT_DIR/.claude/hooks/old-hook.sh"' }] },
+                { hooks: [{ type: "command", command: NEW_HOOK_CMD }] },
+            ],
+        },
+    };
+    beforeAll(() => {
+        workDir = fs.mkdtempSync(path.join(os.tmpdir(), "hq-rescue-settings-"));
+        // --- Fixture "release" repo: floor commit, then a HEAD commit that adds the
+        //     new hook file + registration. ---
+        upstream = path.join(workDir, "upstream");
+        fs.mkdirSync(path.join(upstream, ".claude", "hooks"), { recursive: true });
+        fs.mkdirSync(path.join(upstream, "core", "scripts"), { recursive: true });
+        git(workDir, "init", "-b", "main", "upstream");
+        fs.writeFileSync(path.join(upstream, ".claude", "settings.json"), JSON.stringify(floorSettings, null, 2) + "\n");
+        fs.writeFileSync(path.join(upstream, ".claude", "hooks", "old-hook.sh"), "#!/usr/bin/env bash\n");
+        fs.writeFileSync(path.join(upstream, "core", "scripts", "compose-settings-path.sh"), COMPOSER, { mode: 0o755 });
+        fs.writeFileSync(path.join(upstream, "core", "keep.md"), "same\n");
+        git(upstream, "add", "-A");
+        git(upstream, "commit", "-m", "floor");
+        floorSha = git(upstream, "rev-parse", "HEAD");
+        // HEAD: new hook file + registration land in the release.
+        fs.writeFileSync(path.join(upstream, ".claude", "settings.json"), JSON.stringify(headSettings, null, 2) + "\n");
+        fs.writeFileSync(path.join(upstream, ".claude", "hooks", "new-hook.sh"), "#!/usr/bin/env bash\n# new\n");
+        git(upstream, "add", "-A");
+        git(upstream, "commit", "-m", "add new-hook");
+        // --- git shim: rewrite `git clone <github-url> dest` to the local fixture. ---
+        const realGit = execFileSync("bash", ["-c", "command -v git"]).toString().trim() || "/usr/bin/git";
+        shimDir = path.join(workDir, "shim");
+        fs.mkdirSync(shimDir, { recursive: true });
+        const shim = `#!/usr/bin/env bash
+if [ "$1" = "clone" ] || [ "$1" = "ls-remote" ]; then
+  args=()
+  for a in "$@"; do
+    case "$a" in
+      https://github.com/*) a=${JSON.stringify(upstream)} ;;
+    esac
+    args+=("$a")
+  done
+  exec ${JSON.stringify(realGit)} "\${args[@]}"
+fi
+exec ${JSON.stringify(realGit)} "$@"
+`;
+        fs.writeFileSync(path.join(shimDir, "git"), shim, { mode: 0o755 });
+        // Pin the composer's toolchain root to a path that never exists. Without
+        // this the fixture falls back to $HOME/Library/Application Support/Indigo
+        // HQ/toolchain, which is real on any Mac with the HQ app installed, so the
+        // composed PATH picked up the host's toolchain dirs and these assertions
+        // failed on macOS only. The test that exercises toolchain dirs overrides it.
+        env = {
+            ...process.env,
+            PATH: `${shimDir}:/usr/bin:/bin`,
+            HQ_TOOLCHAIN_DIR: path.join(workDir, "no-toolchain"),
+        };
+    }, 120_000);
+    afterAll(() => {
+        if (workDir)
+            fs.rmSync(workDir, { recursive: true, force: true });
+    });
+    let installSeq = 0;
+    /**
+     * Build a fresh fake install (an existing HQ root) with the given on-disk
+     * settings.json (`ours`) and settings.local.json (`local`). The hook FILE the
+     * earlier release added is present but unwired (mirrors the field box). A
+     * composer script is on the local tree (the overlay refreshes it anyway).
+     */
+    function makeInstall(ours, local) {
+        installSeq += 1;
+        const root = path.join(workDir, `hq-${installSeq}`);
+        fs.mkdirSync(path.join(root, ".claude", "hooks"), { recursive: true });
+        fs.mkdirSync(path.join(root, "core", "scripts"), { recursive: true });
+        fs.mkdirSync(path.join(root, "personal"), { recursive: true });
+        fs.mkdirSync(path.join(root, "companies"), { recursive: true });
+        fs.writeFileSync(path.join(root, ".claude", "settings.json"), JSON.stringify(ours, null, 2) + "\n");
+        fs.writeFileSync(path.join(root, ".claude", "hooks", "old-hook.sh"), "#!/usr/bin/env bash\n");
+        fs.writeFileSync(path.join(root, ".claude", "settings.local.json"), JSON.stringify(local, null, 2) + "\n");
+        fs.writeFileSync(path.join(root, "core", "scripts", "compose-settings-path.sh"), COMPOSER, { mode: 0o755 });
+        fs.writeFileSync(path.join(root, "core", "keep.md"), "same\n");
+        return root;
+    }
+    const rescueArgs = (root, floor) => {
+        const a = ["--hq-root", root, "--source", "test/repo", "--ref", "main", "--yes", "--no-backup"];
+        if (floor)
+            a.push("--floor-sha", floor);
+        else
+            a.push("--no-history-check");
+        return a;
+    };
+    const readSettings = (root) => JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.json"), "utf-8"));
+    const readLocal = (root) => JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.local.json"), "utf-8"));
+    const cmdsOf = (s) => s.hooks.PreToolUse.flatMap((g) => g.hooks.map((h) => h.command));
+    it("writes the composed PATH to settings.local.json when the setup flag is enabled", () => {
+        const prior = structuredClone(floorSettings);
+        prior.env.PATH = MACHINE_PATH;
+        const root = makeInstall(prior, { env: { HQ_FOO: "1" } });
+        const releaseTemplate = structuredClone(headSettings);
+        delete releaseTemplate.env.PATH;
+        fs.writeFileSync(path.join(root, ".claude", "settings.json"), JSON.stringify(releaseTemplate, null, 2) + "\n");
+        reconcileClaudeSettings({
+            hqRoot: root,
+            srcDir: root,
+            env: { PATH: MACHINE_PATH },
+            historyFloor: "",
+            baselineMode: "head_compare",
+            preserveSubpaths: [],
+            setupPathSettingsLocal: true,
+        }, JSON.stringify(prior), () => { }, () => { });
+        expect(readSettings(root)).toEqual(releaseTemplate);
+        expect(fs.readFileSync(path.join(root, ".claude", "settings.json"), "utf-8")).toBe(JSON.stringify(releaseTemplate, null, 2) + "\n");
+        expect(readLocal(root).env?.PATH).toBe(MACHINE_PATH);
+        expect(readLocal(root).env?.HQ_FOO).toBe("1");
+    }, 120_000);
+    it("keeps legitimate tmp-named PATH entries and excludes actual temporary paths", () => {
+        const prior = structuredClone(floorSettings);
+        prior.env.PATH = `/project/bin:/home/u/tmp/bin:/shared:${path.join(os.tmpdir(), "project-temp")}`;
+        const root = makeInstall(prior, {
+            env: { PATH: `/local/bin:/home/u/tmp/bin:/shared:${path.join(os.tmpdir(), "local-temp")}`, HQ_FOO: "1" },
+        });
+        const releaseTemplate = structuredClone(headSettings);
+        delete releaseTemplate.env.PATH;
+        fs.writeFileSync(path.join(root, ".claude", "settings.json"), JSON.stringify(releaseTemplate, null, 2) + "\n");
+        reconcileClaudeSettings({
+            hqRoot: root,
+            srcDir: root,
+            env: { ...env, PATH: "/npx/cache/_npx/run/node_modules/.bin:/process/bin:/shared" },
+            historyFloor: "",
+            baselineMode: "head_compare",
+            preserveSubpaths: [],
+            setupPathSettingsLocal: true,
+        }, JSON.stringify(prior), () => { }, () => { });
+        expect(readLocal(root).env?.PATH).toBe("/local/bin:/home/u/tmp/bin:/shared:/project/bin:/process/bin");
+        expect(readSettings(root).env.PATH).toBeUndefined();
+        expect(readLocal(root).env?.HQ_FOO).toBe("1");
+    }, 120_000);
+    it.each([
+        { tempRoot: "/", home: "/home/u" },
+        { tempRoot: "/home", home: "/home/u" },
+    ])("does not treat a broad root ($tempRoot) as a temporary directory", ({ tempRoot, home }) => {
+        const prior = structuredClone(floorSettings);
+        delete prior.env.PATH;
+        const root = makeInstall(prior, { env: {} });
+        const releaseTemplate = structuredClone(headSettings);
+        delete releaseTemplate.env.PATH;
+        fs.writeFileSync(path.join(root, ".claude", "settings.json"), JSON.stringify(releaseTemplate, null, 2) + "\n");
+        reconcileClaudeSettings({
+            hqRoot: root,
+            srcDir: root,
+            env: { ...env, PATH: "/home/u/bin", HOME: home, TMPDIR: tempRoot },
+            historyFloor: "",
+            baselineMode: "head_compare",
+            preserveSubpaths: [],
+            setupPathSettingsLocal: true,
+        }, JSON.stringify(prior), () => { }, () => { });
+        expect(readLocal(root).env?.PATH).toBe("/home/u/bin");
+    }, 120_000);
+    it("wires in the new hook registration, preserves machine PATH, and relocates drift", () => {
+        // ours = floor template + machine env.PATH + a user-drift permission, and
+        // (crucially) WITHOUT the new-hook registration.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow.push("Bash(mytool:*)");
+        const root = makeInstall(ours, { env: { HQ_FOO: "1" } });
+        const r = runRescueCapture(rescueArgs(root, floorSha), env);
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        expect(out).toContain(`Baseline: ${floorSha}`);
+        expect(out).toContain("Reconciled .claude/settings.json to release baseline");
+        const settings = readSettings(root);
+        const local = readLocal(root);
+        // (1) The newly-released hook registration is now present in settings.json,
+        //     and the hook FILE landed too.
+        expect(cmdsOf(settings)).toContain(NEW_HOOK_CMD);
+        expect(fs.existsSync(path.join(root, ".claude", "hooks", "new-hook.sh"))).toBe(true);
+        // (3) Machine env.PATH is preserved/composed — never dropped, never the
+        //     release's (the release ships none), never hardcoded.
+        expect(settings.env.PATH).toBe(MACHINE_PATH);
+        // (2) The user-drift permission moved OUT of settings.json (back to the
+        //     shipped baseline) and INTO settings.local.json — not lost.
+        expect(settings.permissions.allow).toEqual(["Bash(git:*)"]);
+        expect(local.permissions?.allow).toContain("Bash(mytool:*)");
+        // The pre-existing local override survives.
+        expect(local.env?.HQ_FOO).toBe("1");
+        // Effective merged settings (Project ⊕ Local, union of permissions) still
+        // grant the user's tool.
+        const effectiveAllow = new Set([
+            ...settings.permissions.allow,
+            ...(local.permissions?.allow ?? []),
+        ]);
+        expect(effectiveAllow.has("Bash(mytool:*)")).toBe(true);
+        expect(effectiveAllow.has("Bash(git:*)")).toBe(true);
+        // No junk personal/ copy of settings.json is minted.
+        expect(fs.existsSync(path.join(root, "personal", ".claude", "settings.json"))).toBe(false);
+    }, 120_000);
+    it("appends relocated drift to an existing settings.local.json array without overwriting it", () => {
+        // The user's settings.local.json ALREADY customizes permissions.allow and an
+        // env var. Rescue relocates a NEW drift permission but must not overwrite the
+        // existing local entries — they must all survive.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow.push("Bash(mytool:*)"); // drift to relocate
+        const root = makeInstall(ours, {
+            permissions: { allow: ["Bash(existing:*)"] },
+            env: { HQ_FOO: "1" },
+        });
+        const r = runRescueCapture(rescueArgs(root, floorSha), env);
+        expect(r.status, `${r.stdout}\n${r.stderr}`).toBe(0);
+        const local = readLocal(root);
+        // Existing local entry preserved; drift appended (order preserved, no dup).
+        expect(local.permissions?.allow).toEqual(["Bash(existing:*)", "Bash(mytool:*)"]);
+        // Existing local env override untouched.
+        expect(local.env?.HQ_FOO).toBe("1");
+    }, 120_000);
+    it("relocates a user-added permission even with no reachable floor (head_compare fallback)", () => {
+        // No --floor-sha, --no-history-check -> head_compare mode (base = release
+        // HEAD). A user-added permission absent from the release must still be
+        // preserved, the new hook registration must still wire in, and env.PATH must
+        // still be composed.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow.push("Bash(mytool:*)");
+        const root = makeInstall(ours, {});
+        const r = runRescueCapture(rescueArgs(root), env);
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        expect(out).toContain("HEAD compare");
+        expect(out).toContain("Reconciled .claude/settings.json to release baseline");
+        const settings = readSettings(root);
+        const local = readLocal(root);
+        expect(cmdsOf(settings)).toContain(NEW_HOOK_CMD); // release baseline wins
+        expect(settings.env.PATH).toBe(MACHINE_PATH); // machine PATH composed
+        // The user-added permission the release never had is relocated, not lost.
+        expect(settings.permissions.allow).toEqual(["Bash(git:*)"]);
+        expect(local.permissions?.allow).toContain("Bash(mytool:*)");
+        expect(fs.existsSync(path.join(root, "personal", ".claude", "settings.json"))).toBe(false);
+    }, 120_000);
+    it("does not add temporary toolchain paths returned by an old release composer", () => {
+        // ours has a machine PATH but is MISSING the managed toolchain dirs. The
+        // A prior-release composer may suggest toolchain paths from a temp test
+        // tree. Rescue must exclude those temporary paths.
+        const toolchain = path.join(workDir, `toolchain-${installSeq + 1}`);
+        for (const d of ["node/bin", "npm-global/bin", "git/bin"]) {
+            fs.mkdirSync(path.join(toolchain, d), { recursive: true });
+        }
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH; // no toolchain dirs present
+        const root = makeInstall(ours, {});
+        const r = runRescueCapture(rescueArgs(root, floorSha), {
+            ...env,
+            HQ_TOOLCHAIN_DIR: toolchain,
+        });
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        const composed = readSettings(root).env.PATH;
+        expect(composed).toBe(MACHINE_PATH);
+    }, 120_000);
+    it("persists a user's array removal against the release baseline (thread 1)", () => {
+        // ours REMOVES the shipped "Bash(git:*)" permission. A union Local overlay
+        // cannot express a removal, so the reconcile must strip it from the Project
+        // baseline (theirs) instead — otherwise the release re-introduces it.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow = []; // removed Bash(git:*)
+        const root = makeInstall(ours, {});
+        const r = runRescueCapture(rescueArgs(root, floorSha), env);
+        expect(r.status, `${r.stdout}\n${r.stderr}`).toBe(0);
+        const settings = readSettings(root);
+        // The deliberately-removed permission stays gone, and the new hook still lands.
+        expect(settings.permissions.allow).toEqual([]);
+        expect(cmdsOf(settings)).toContain(NEW_HOOK_CMD);
+    }, 120_000);
+    it("keeps the original settings.json when settings.local.json is unwritable (thread 3)", () => {
+        // ours has a drift permission to relocate; make settings.local.json a
+        // DIRECTORY so the relocation write fails. The reconcile must then preserve
+        // ours rather than overwrite it with the drift-less release baseline.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow.push("Bash(mytool:*)");
+        const root = makeInstall(ours, {});
+        // Replace the local file with a directory (write will EISDIR). It is a
+        // carve-out, so the shuttle restores it as a directory across the overlay.
+        fs.rmSync(path.join(root, ".claude", "settings.local.json"));
+        fs.mkdirSync(path.join(root, ".claude", "settings.local.json"));
+        const r = runRescueCapture(rescueArgs(root, floorSha), env);
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        expect(out).toContain("settings update not applied");
+        // ours is preserved verbatim — the drift permission is NOT lost.
+        const settings = readSettings(root);
+        expect(settings.permissions.allow).toContain("Bash(mytool:*)");
+        expect(settings.env.PATH).toBe(MACHINE_PATH);
+    }, 120_000);
+    it("backs up a malformed pre-rescue settings.json instead of destroying it (thread 5)", () => {
+        // Pre-rescue settings.json is invalid JSON. The overlay replaces it, so the
+        // reconcile must preserve the raw bytes under personal/ and still leave a
+        // working (composed) settings.json.
+        const root = makeInstall(structuredClone(floorSettings), {});
+        fs.writeFileSync(path.join(root, ".claude", "settings.json"), "{ this is : not json ");
+        const r = runRescueCapture(rescueArgs(root, floorSha), env);
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        // Raw malformed content preserved under personal/.
+        const backup = path.join(root, "personal", ".claude", "settings.json");
+        expect(fs.existsSync(backup)).toBe(true);
+        expect(fs.readFileSync(backup, "utf-8")).toBe("{ this is : not json ");
+        // settings.json is valid again (release baseline + composed PATH + new hook).
+        const settings = readSettings(root);
+        expect(cmdsOf(settings)).toContain(NEW_HOOK_CMD);
+        expect(typeof settings.env.PATH).toBe("string");
+    }, 120_000);
+    it("honors an explicit --preserve-subpath of settings.json (thread 6)", () => {
+        // The caller asked to keep settings.json; the reconcile must not rewrite it,
+        // and the (preserved) old file — without the new registration — stays as-is.
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        const root = makeInstall(ours, {});
+        const r = runRescueCapture([...rescueArgs(root, floorSha), "--preserve-subpath", ".claude/settings.json"], env);
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        expect(out).toContain("explicitly preserved");
+        const settings = readSettings(root);
+        // Preserved verbatim: no reconcile, so the new registration did NOT land.
+        expect(cmdsOf(settings)).not.toContain(NEW_HOOK_CMD);
+        expect(settings.env.PATH).toBe(MACHINE_PATH);
+    }, 120_000);
+    it("restores the machine settings.json when a release drops the template (thread 4)", () => {
+        // A dedicated fixture whose HEAD DELETES .claude/settings.json (floor had
+        // it). Overwrite-safe deletes ours; the overlay lays nothing; the reconcile
+        // must restore ours so PATH + customizations survive under --no-backup.
+        const up2 = path.join(workDir, "upstream-drop");
+        fs.mkdirSync(path.join(up2, ".claude"), { recursive: true });
+        fs.mkdirSync(path.join(up2, "core", "scripts"), { recursive: true });
+        git(workDir, "init", "-b", "main", "upstream-drop");
+        fs.writeFileSync(path.join(up2, ".claude", "settings.json"), JSON.stringify(floorSettings, null, 2) + "\n");
+        fs.writeFileSync(path.join(up2, "core", "scripts", "compose-settings-path.sh"), COMPOSER, { mode: 0o755 });
+        fs.writeFileSync(path.join(up2, "core", "keep.md"), "same\n");
+        git(up2, "add", "-A");
+        git(up2, "commit", "-m", "floor with settings");
+        const floor2 = git(up2, "rev-parse", "HEAD");
+        // HEAD removes the template.
+        fs.rmSync(path.join(up2, ".claude", "settings.json"));
+        git(up2, "add", "-A");
+        git(up2, "commit", "-m", "drop settings.json");
+        // A shim that points clones at up2 instead of the shared upstream.
+        const realGit = execFileSync("bash", ["-c", "command -v git"]).toString().trim() || "/usr/bin/git";
+        const shim2 = path.join(workDir, "shim-drop");
+        fs.mkdirSync(shim2, { recursive: true });
+        fs.writeFileSync(path.join(shim2, "git"), `#!/usr/bin/env bash
+if [ "$1" = "clone" ] || [ "$1" = "ls-remote" ]; then
+  args=()
+  for a in "$@"; do
+    case "$a" in
+      https://github.com/*) a=${JSON.stringify(up2)} ;;
+    esac
+    args+=("$a")
+  done
+  exec ${JSON.stringify(realGit)} "\${args[@]}"
+fi
+exec ${JSON.stringify(realGit)} "$@"
+`, { mode: 0o755 });
+        const ours = structuredClone(floorSettings);
+        ours.env.PATH = MACHINE_PATH;
+        ours.permissions.allow.push("Bash(mytool:*)");
+        const root = makeInstall(ours, {});
+        const r = runRescueCapture(rescueArgs(root, floor2), {
+            ...env,
+            PATH: `${shim2}:${process.env.PATH ?? ""}`,
+        });
+        const out = `${r.stdout}\n${r.stderr}`;
+        expect(r.status, out).toBe(0);
+        expect(out).toContain("Release no longer ships .claude/settings.json");
+        // ours restored — machine PATH and the user's customization survive.
+        const settings = readSettings(root);
+        expect(settings.env.PATH).toBe(MACHINE_PATH);
+        expect(settings.permissions.allow).toContain("Bash(mytool:*)");
+    }, 120_000);
+});
+//# sourceMappingURL=rescue-settings-reconcile.test.js.map