@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/src/cli/rescue-settings-reconcile.test.ts

@@ -0,0 +1,637 @@
+/**
+ * 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,
+  settingsDrift,
+  deepMergeSettings,
+  applyArrayRemovals,
+  jsonDeepEqual,
+} from "./rescue-core.js";
+
+// ── 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 as { model?: string }).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: Record<string, unknown> = { hooks: "local-wins" };
+    deepMergeSettings(target as { [k: string]: never }, {
+      hooks: { PreToolUse: [] },
+    } as unknown as { [k: string]: never });
+    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: string, args: string[] = ["--version"]): boolean {
+  try {
+    execFileSync(bin, args, { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const canRun = hasBin("git") && hasBin("rsync");
+
+function runRescueCapture(argv: string[], env: NodeJS.ProcessEnv) {
+  let stdout = "";
+  let stderr = "";
+  const origOut = process.stdout.write.bind(process.stdout);
+  const origErr = process.stderr.write.bind(process.stderr);
+  process.stdout.write = ((chunk: unknown) => {
+    stdout += String(chunk);
+    return true;
+  }) as typeof process.stdout.write;
+  process.stderr.write = ((chunk: unknown) => {
+    stderr += String(chunk);
+    return true;
+  }) as typeof process.stderr.write;
+  let status: number;
+  try {
+    status = runRescue(argv, { env }).status;
+  } finally {
+    process.stdout.write = origOut;
+    process.stderr.write = origErr;
+  }
+  return { status, stdout, stderr };
+}
+
+// A faithful copy of core/scripts/compose-settings-path.sh: prepend managed
+// toolchain bin dirs that exist on disk but are missing from the base PATH,
+// else pass the base through unchanged.
+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"
+`;
+
+interface TestSettings {
+  model?: string;
+  permissions: { allow: string[]; deny: string[] };
+  env: Record<string, string>;
+  hooks: { PreToolUse: { hooks: { type?: string; command: string }[] }[] };
+}
+
+describe.skipIf(!canRun)("rescue .claude/settings.json reconcile (real overlay)", () => {
+  let workDir: string;
+  let upstream: string;
+  let shimDir: string;
+  let floorSha: string;
+  let env: NodeJS.ProcessEnv;
+
+  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: string, ...args: string[]) =>
+    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: TestSettings = {
+    model: "claude-opus-4-8",
+    permissions: { allow: ["Bash(git:*)"], deny: [] as string[] },
+    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: TestSettings = {
+    model: "claude-opus-4-8",
+    permissions: { allow: ["Bash(git:*)"], deny: [] as string[] },
+    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" ]; 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 });
+
+    env = { ...process.env, PATH: `${shimDir}:${process.env.PATH ?? ""}` };
+  }, 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: TestSettings,
+    local: Record<string, unknown>,
+  ): string {
+    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: string, floor?: string) => {
+    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: string) =>
+    JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.json"), "utf-8")) as TestSettings;
+  const readLocal = (root: string) =>
+    JSON.parse(fs.readFileSync(path.join(root, ".claude", "settings.local.json"), "utf-8")) as {
+      permissions?: { allow?: string[] };
+      env?: Record<string, string>;
+    };
+  const cmdsOf = (s: TestSettings) => s.hooks.PreToolUse.flatMap((g) => g.hooks.map((h) => h.command));
+
+  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("composes env.PATH through the release composer (toolchain dirs prepended, not hardcoded)", () => {
+    // ours has a machine PATH but is MISSING the managed toolchain dirs. The
+    // reconcile must run them through compose-settings-path.sh so the toolchain
+    // is prepended — proving env.PATH is genuinely COMPOSED (deliverable 3),
+    // not merely copied and not hardcoded from any release blob.
+    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;
+    // installer ordering: node, npm-global, git prepended ahead of the base.
+    expect(composed).toBe(
+      `${toolchain}/node/bin:${toolchain}/npm-global/bin:${toolchain}/git/bin:${MACHINE_PATH}`,
+    );
+    // The machine base is still present (never dropped).
+    expect(composed.endsWith(MACHINE_PATH)).toBe(true);
+  }, 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" ]; 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);
+});

package/src/index.ts

@@ -412,11 +412,9 @@ export {
   decodePushEvent,
   NoopPushTransport,
   HttpPushTransport,
-  FEATURE_FLAG_TENANTS_ENV_VAR,
-  FEATURE_FLAG_LEGACY_GLOBAL_ENV_VAR,
-  EnvTenantListFlagProvider,
+  EVENT_SYNC_LOCAL_DISABLE_ENV_VAR,
+  isEventSyncLocallyDisabled,
   StaticFlagProvider,
-  defaultFlagProvider,
 } from "./sync/index.js";
 export type {
   PushEvent,