@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/dist/cli/rescue-core.d.ts

@@ -97,5 +97,90 @@ export type RescueDecision = {
     kind: "wholesale-replace-template";
     rel: "companies/_template";
 };
+type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [k: string]: JsonValue;
+};
+/** Structural deep equality for JSON values (stable, order-sensitive for objects). */
+export declare function jsonDeepEqual(a: JsonValue, b: JsonValue): boolean;
+/**
+ * Compute the drift of `ours` relative to `base` (the three-way "ours − base").
+ * Returns a partial object holding only the values `ours` added or changed
+ * versus `base`, suitable for merging into settings.local.json so Claude Code's
+ * higher-precedence Local scope re-supplies them on top of the release baseline.
+ *
+ *  - object: recurse per key; a key absent from `base` is drift wholesale.
+ *  - array: drift = the elements present in `ours` but not deep-contained in
+ *    `base`. This matches Claude Code's union merge for permissions/hooks, so a
+ *    relocated allow/deny entry unions back into the effective settings.
+ *  - scalar / type-mismatch: drift = ours's value when not deep-equal.
+ *
+ * `excludePath` names dotted key paths that are NEVER drift (env.PATH — a
+ * machine-local value re-composed onto the release baseline, not relocated).
+ * Returns `undefined` when there is no drift at this node.
+ */
+export declare function settingsDrift(ours: JsonValue, base: JsonValue | undefined, excludePath?: string[], pathPrefix?: string): JsonValue | undefined;
+/**
+ * Deep-merge `patch` into `target` in place and return it. Objects merge
+ * per-key; arrays union (append patch elements not already deep-present, so a
+ * re-run is idempotent and no duplicate permission/hook entries accumulate);
+ * scalars are added ONLY when the key is absent from `target`. A scalar the
+ * user already set in Local is the higher-precedence value and MUST NOT be
+ * clobbered by the lower-precedence Project drift (e.g. Project `model: opus` +
+ * Local `model: sonnet` must stay `sonnet` after rescue). Mirrors how Claude
+ * Code's Local scope overrides/unions over Project.
+ */
+export declare function deepMergeSettings(target: {
+    [k: string]: JsonValue;
+}, patch: {
+    [k: string]: JsonValue;
+}): {
+    [k: string]: JsonValue;
+};
+/**
+ * Apply the user's array REMOVALS (elements present in `base` but absent from
+ * `ours`) to the corresponding arrays in `theirs`, in place. A union-style Local
+ * overlay cannot express a removal, so a permission/hook a user deliberately
+ * deleted from the generated settings.json would otherwise be restored by the
+ * release baseline and never removable. Filtering `theirs` — the Project file we
+ * now own — is the only representation of that intent. Recurses through objects;
+ * only acts when all three nodes are arrays (or objects to recurse). Requires a
+ * REAL floor base: never call with base = theirs (HEAD), or release-only entries
+ * would be mistaken for removals.
+ */
+export declare function applyArrayRemovals(theirs: {
+    [k: string]: JsonValue;
+}, ours: {
+    [k: string]: JsonValue;
+}, base: {
+    [k: string]: JsonValue;
+}): void;
+interface ReconcileCtx {
+    hqRoot: string;
+    srcDir: string;
+    env: NodeJS.ProcessEnv;
+    historyFloor: string;
+    baselineMode: "history_floor" | "head_compare";
+    /** cfg.preserveSubpaths — used to honor an explicit `--preserve-subpath` of
+     *  settings.json (or the whole `.claude` tree). */
+    preserveSubpaths: string[];
+}
+/**
+ * Post-overlay reconcile for the machine-local, generated `.claude/settings.json`.
+ *
+ * At entry the overlay has already re-laid the release template (theirs) over
+ * settings.json, and the user's settings.local.json has been restored from the
+ * preserve shuttle. This function:
+ *   1. re-composes env.PATH onto theirs (machine-specific; deliverable 3), and
+ *   2. extracts ours's drift versus the last-sync floor (base) — excluding
+ *      env.PATH — and merges it into settings.local.json (deliverable 2),
+ * so the EFFECTIVE merged settings (Project ⊕ Local, per Claude Code's rules)
+ * are preserved while the Project base returns to the shipped composition with
+ * any newly-released hook registrations wired in (deliverable 1).
+ *
+ * Best-effort and non-fatal: unreadable/invalid JSON degrades to a
+ * PATH-recompose-only pass (never worse than the old behavior), matching
+ * rescue's posture elsewhere.
+ */
+export declare function reconcileClaudeSettings(ctx: ReconcileCtx, preRescueSettingsJson: string | null, out: (s: string) => void, err: (s: string) => void): void;
 export {};
 //# sourceMappingURL=rescue-core.d.ts.map

package/dist/cli/rescue-core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"rescue-core.d.ts","sourceRoot":"","sources":["../../src/cli/rescue-core.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAa7B,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AA0CD,UAAU,MAAM;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AA2BD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS3D;AA0FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAwJtD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,GACrC,eAAe,CAkCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,IAAI,CAAC,YAAmB,GAAG,OAAO,CAGhG;AAu2BD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,4BAA4B,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAA;CAAE,CAAC"}
+{"version":3,"file":"rescue-core.d.ts","sourceRoot":"","sources":["../../src/cli/rescue-core.ts"],"names":[],"mappings":"AA6BA,OAAO,KAAK,IAAI,MAAM,MAAM,CAAC;AAa7B,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,MAAM,CAAC;CAChB;AA0CD,UAAU,MAAM;IACd,GAAG,EAAE,MAAM,CAAC;IACZ,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,OAAO,CAAC;IAChB,SAAS,EAAE,OAAO,CAAC;IACnB,WAAW,EAAE,OAAO,CAAC;IACrB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,gBAAgB,EAAE,MAAM,EAAE,CAAC;IAC3B,WAAW,EAAE,MAAM,EAAE,CAAC;IACtB,cAAc,EAAE,MAAM,CAAC;IACvB,YAAY,EAAE,OAAO,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,OAAO,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,oBAAoB,EAAE,MAAM,CAAC;CAC9B;AA2BD;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,CAS3D;AA0FD;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,MAAM,CAwJtD;AAED;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,IAAI,EAAE,MAAM,EAAE,EACd,IAAI,GAAE;IAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,CAAA;CAAO,GACrC,eAAe,CAkCjB;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,YAAY,GAAE,IAAI,CAAC,YAAmB,GAAG,OAAO,CAGhG;AA24BD,MAAM,MAAM,cAAc,GACtB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC7B;IAAE,IAAI,EAAE,wBAAwB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC/C;IAAE,IAAI,EAAE,qBAAqB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC5C;IAAE,IAAI,EAAE,sBAAsB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC7D;IAAE,IAAI,EAAE,WAAW,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAClC;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,uBAAuB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC9C;IAAE,IAAI,EAAE,0BAA0B,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACjD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GACzD;IAAE,IAAI,EAAE,oBAAoB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAC3C;IAAE,IAAI,EAAE,kBAAkB,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GACzC;IAAE,IAAI,EAAE,4BAA4B,CAAC;IAAC,GAAG,EAAE,qBAAqB,CAAA;CAAE,CAAC;AAuYvE,KAAK,SAAS,GACV,MAAM,GACN,MAAM,GACN,OAAO,GACP,IAAI,GACJ,SAAS,EAAE,GACX;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAAC;AAM/B,sFAAsF;AACtF,wBAAgB,aAAa,CAAC,CAAC,EAAE,SAAS,EAAE,CAAC,EAAE,SAAS,GAAG,OAAO,CAajE;AAWD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,aAAa,CAC3B,IAAI,EAAE,SAAS,EACf,IAAI,EAAE,SAAS,GAAG,SAAS,EAC3B,WAAW,GAAE,MAAM,EAAiB,EACpC,UAAU,SAAK,GACd,SAAS,GAAG,SAAS,CA6CvB;AAED;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAC/B,MAAM,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAClC,KAAK,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAChC;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,CAkB5B;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAClC,IAAI,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,EAChC,IAAI,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CAAE,GAC/B,IAAI,CAcN;AA8BD,UAAU,YAAY;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;IACvB,YAAY,EAAE,MAAM,CAAC;IACrB,YAAY,EAAE,eAAe,GAAG,cAAc,CAAC;IAC/C;uDACmD;IACnD,gBAAgB,EAAE,MAAM,EAAE,CAAC;CAC5B;AAeD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,YAAY,EACjB,qBAAqB,EAAE,MAAM,GAAG,IAAI,EACpC,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,EACxB,GAAG,EAAE,CAAC,CAAC,EAAE,MAAM,KAAK,IAAI,GACvB,IAAI,CAqKN"}

package/dist/cli/rescue-core.js

@@ -466,6 +466,25 @@ function doRescue(cfg, env, out, err, setTmp) {
     // which merely starts but exits non-zero used to trigger an enormous cp -a
     // fallback, then fail later at overlay.  Stop before classification/allocation.
     requireWorkingRsync(env, err);
+    // --- Capture the pre-rescue .claude/settings.json (BEFORE the wipe) ---
+    // This is `ours` for the post-overlay settings reconcile. It must be read now
+    // because the overlay-safe classification deletes/overwrites it before
+    // reconcileClaudeSettings runs. `null` when absent (fresh install / narrow
+    // mode that excludes .claude).
+    const claudeSettingsRel = ".claude/settings.json";
+    const claudeSettingsInScope = cfg.narrowPaths.length === 0 || cfg.narrowPaths.includes(".claude");
+    let preRescueSettingsJson = null;
+    if (claudeSettingsInScope) {
+        const p = path.join(hqRoot, claudeSettingsRel);
+        if (isFileFollow(p)) {
+            try {
+                preRescueSettingsJson = fs.readFileSync(p, "utf-8");
+            }
+            catch {
+                preRescueSettingsJson = null;
+            }
+        }
+    }
     // --- Read prior sync-point metadata (BEFORE the wipe) ---
     let prevSyncSha = "";
     let prevSyncSource = "";
@@ -957,6 +976,16 @@ function doRescue(cfg, env, out, err, setTmp) {
                 out(`    restored ${rel}\n`);
             }
         }
+        // --- Reconcile the generated .claude/settings.json ---
+        // Runs AFTER the overlay (which re-laid the release template, wiring in any
+        // newly-released hook registrations) and AFTER the preserve-subpath restore
+        // (which brought back the user's .claude/settings.local.json). Re-composes the
+        // machine env.PATH onto the release baseline and relocates genuine user drift
+        // (vs the last-sync floor) into settings.local.json so the effective merged
+        // settings are preserved. No-op in narrow mode that excludes .claude.
+        if (claudeSettingsInScope) {
+            reconcileClaudeSettings({ hqRoot, srcDir, env, historyFloor, baselineMode, preserveSubpaths: cfg.preserveSubpaths }, preRescueSettingsJson, out, err);
+        }
         // --- Restore executable bit on shipped shebang scripts (defense-in-depth) ---
         // rsync -a already propagated each file's upstream git tree mode; this guards
         // the case where upstream itself committed an executable script as 0644 -- a
@@ -1344,7 +1373,17 @@ function isOverwriteSafe(rel) {
     return (rel === "AGENTS.md" ||
         rel === "USER-GUIDE.md" ||
         rel === "core/docs/hq/USER-GUIDE.md" ||
-        rel === "core/policies/_digest.md");
+        rel === "core/policies/_digest.md" ||
+        // `.claude/settings.json` is a machine-local *generated* file (setup.sh
+        // step 3b composes env.PATH into the release template). It always differs
+        // from every release blob because of that PATH, so the generic classifier
+        // would rescue it into personal/ and lay a PATH-less template on top —
+        // dropping the machine PATH and (depending on drift/history state) failing
+        // to wire in newly-released hook registrations. Instead let the overlay
+        // always re-lay the release template (no personal/ copy), then
+        // reconcileClaudeSettings() re-composes env.PATH and relocates genuine user
+        // drift into settings.local.json. See reconcileClaudeSettings.
+        rel === ".claude/settings.json");
 }
 function masterSyncSymlinkTarget(localPath) {
     const st = lstatOrNull(localPath);
@@ -1509,6 +1548,356 @@ function diffAppendClaudeMd(ctx) {
     ctx.out("    diff-appended: .claude/CLAUDE.md additions -> personal/CLAUDE.md\n");
     ctx.counts.claudeDiffAppend += 1;
 }
+function isPlainObject(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/** Structural deep equality for JSON values (stable, order-sensitive for objects). */
+export function jsonDeepEqual(a, b) {
+    if (a === b)
+        return true;
+    if (Array.isArray(a) && Array.isArray(b)) {
+        if (a.length !== b.length)
+            return false;
+        return a.every((x, i) => jsonDeepEqual(x, b[i]));
+    }
+    if (isPlainObject(a) && isPlainObject(b)) {
+        const ak = Object.keys(a);
+        const bk = Object.keys(b);
+        if (ak.length !== bk.length)
+            return false;
+        return ak.every((k) => k in b && jsonDeepEqual(a[k], b[k]));
+    }
+    return false;
+}
+function jsonParseOrNull(text) {
+    if (text == null)
+        return null;
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Compute the drift of `ours` relative to `base` (the three-way "ours − base").
+ * Returns a partial object holding only the values `ours` added or changed
+ * versus `base`, suitable for merging into settings.local.json so Claude Code's
+ * higher-precedence Local scope re-supplies them on top of the release baseline.
+ *
+ *  - object: recurse per key; a key absent from `base` is drift wholesale.
+ *  - array: drift = the elements present in `ours` but not deep-contained in
+ *    `base`. This matches Claude Code's union merge for permissions/hooks, so a
+ *    relocated allow/deny entry unions back into the effective settings.
+ *  - scalar / type-mismatch: drift = ours's value when not deep-equal.
+ *
+ * `excludePath` names dotted key paths that are NEVER drift (env.PATH — a
+ * machine-local value re-composed onto the release baseline, not relocated).
+ * Returns `undefined` when there is no drift at this node.
+ */
+export function settingsDrift(ours, base, excludePath = ["env.PATH"], pathPrefix = "") {
+    const here = pathPrefix;
+    if (excludePath.includes(here))
+        return undefined;
+    if (base === undefined) {
+        // Whole subtree is new in ours — but still honor exclusions nested under it.
+        if (isPlainObject(ours)) {
+            const out = {};
+            let any = false;
+            for (const k of Object.keys(ours)) {
+                const child = settingsDrift(ours[k], undefined, excludePath, here ? `${here}.${k}` : k);
+                if (child !== undefined) {
+                    out[k] = child;
+                    any = true;
+                }
+            }
+            return any ? out : undefined;
+        }
+        return ours;
+    }
+    if (isPlainObject(ours) && isPlainObject(base)) {
+        const out = {};
+        let any = false;
+        for (const k of Object.keys(ours)) {
+            const child = settingsDrift(ours[k], k in base ? base[k] : undefined, excludePath, here ? `${here}.${k}` : k);
+            if (child !== undefined) {
+                out[k] = child;
+                any = true;
+            }
+        }
+        return any ? out : undefined;
+    }
+    if (Array.isArray(ours) && Array.isArray(base)) {
+        const extra = ours.filter((el) => !base.some((b) => jsonDeepEqual(el, b)));
+        return extra.length > 0 ? extra : undefined;
+    }
+    return jsonDeepEqual(ours, base) ? undefined : ours;
+}
+/**
+ * Deep-merge `patch` into `target` in place and return it. Objects merge
+ * per-key; arrays union (append patch elements not already deep-present, so a
+ * re-run is idempotent and no duplicate permission/hook entries accumulate);
+ * scalars are added ONLY when the key is absent from `target`. A scalar the
+ * user already set in Local is the higher-precedence value and MUST NOT be
+ * clobbered by the lower-precedence Project drift (e.g. Project `model: opus` +
+ * Local `model: sonnet` must stay `sonnet` after rescue). Mirrors how Claude
+ * Code's Local scope overrides/unions over Project.
+ */
+export function deepMergeSettings(target, patch) {
+    for (const k of Object.keys(patch)) {
+        const pv = patch[k];
+        const tv = target[k];
+        if (Array.isArray(pv) && Array.isArray(tv)) {
+            for (const el of pv) {
+                if (!tv.some((x) => jsonDeepEqual(x, el)))
+                    tv.push(el);
+            }
+        }
+        else if (isPlainObject(pv) && isPlainObject(tv)) {
+            deepMergeSettings(tv, pv);
+        }
+        else if (!(k in target)) {
+            // Key absent from Local — safe to introduce the relocated drift value.
+            target[k] = pv;
+        }
+        // else: Local already defines this scalar (or a differently-typed value);
+        // it is the higher-precedence override and is left untouched.
+    }
+    return target;
+}
+/**
+ * Apply the user's array REMOVALS (elements present in `base` but absent from
+ * `ours`) to the corresponding arrays in `theirs`, in place. A union-style Local
+ * overlay cannot express a removal, so a permission/hook a user deliberately
+ * deleted from the generated settings.json would otherwise be restored by the
+ * release baseline and never removable. Filtering `theirs` — the Project file we
+ * now own — is the only representation of that intent. Recurses through objects;
+ * only acts when all three nodes are arrays (or objects to recurse). Requires a
+ * REAL floor base: never call with base = theirs (HEAD), or release-only entries
+ * would be mistaken for removals.
+ */
+export function applyArrayRemovals(theirs, ours, base) {
+    for (const k of Object.keys(base)) {
+        const bv = base[k];
+        const ov = ours[k];
+        const tv = theirs[k];
+        if (Array.isArray(bv) && Array.isArray(ov) && Array.isArray(tv)) {
+            const removed = bv.filter((b) => !ov.some((o) => jsonDeepEqual(o, b)));
+            if (removed.length > 0) {
+                theirs[k] = tv.filter((t) => !removed.some((r) => jsonDeepEqual(r, t)));
+            }
+        }
+        else if (isPlainObject(bv) && isPlainObject(ov) && isPlainObject(tv)) {
+            applyArrayRemovals(tv, ov, bv);
+        }
+    }
+}
+/**
+ * Re-compose the machine env.PATH for the freshly-overlaid release template.
+ * Runs the SAME composer setup.sh uses (core/scripts/compose-settings-path.sh)
+ * with the machine's own PATH as the base — preferring the pre-rescue snapshot
+ * so a working PATH is never degraded by a possibly-truncated rescue-process
+ * PATH — so the value is always machine-specific and never a hardcoded release
+ * PATH (the release template ships none). Prefers the release clone's composer,
+ * falls back to the overlaid one; if neither runs, carries `basePath` verbatim.
+ */
+function composeSettingsPath(srcDir, hqRoot, basePath, env) {
+    const candidates = [
+        path.join(srcDir, "core", "scripts", "compose-settings-path.sh"),
+        path.join(hqRoot, "core", "scripts", "compose-settings-path.sh"),
+    ];
+    for (const script of candidates) {
+        if (!isFileFollow(script))
+            continue;
+        const r = run("bash", [script, basePath], { env });
+        const composed = r.stdout.replace(/\n+$/, "");
+        if (r.status === 0 && composed)
+            return composed;
+    }
+    return basePath;
+}
+/** True when `.claude/settings.json` is covered by an EXPLICIT preserve subpath
+ *  (the caller asked rescue to keep it, so the reconcile must not rewrite it).
+ *  The always-on carve-outs never cover settings.json, so any match here is a
+ *  deliberate caller request. */
+function settingsExplicitlyPreserved(preserveSubpaths) {
+    const rel = ".claude/settings.json";
+    for (const sp of preserveSubpaths) {
+        const s = sp.replace(/\/$/, "");
+        if (s === rel || s === ".claude" || rel.startsWith(s + "/"))
+            return true;
+    }
+    return false;
+}
+/**
+ * Post-overlay reconcile for the machine-local, generated `.claude/settings.json`.
+ *
+ * At entry the overlay has already re-laid the release template (theirs) over
+ * settings.json, and the user's settings.local.json has been restored from the
+ * preserve shuttle. This function:
+ *   1. re-composes env.PATH onto theirs (machine-specific; deliverable 3), and
+ *   2. extracts ours's drift versus the last-sync floor (base) — excluding
+ *      env.PATH — and merges it into settings.local.json (deliverable 2),
+ * so the EFFECTIVE merged settings (Project ⊕ Local, per Claude Code's rules)
+ * are preserved while the Project base returns to the shipped composition with
+ * any newly-released hook registrations wired in (deliverable 1).
+ *
+ * Best-effort and non-fatal: unreadable/invalid JSON degrades to a
+ * PATH-recompose-only pass (never worse than the old behavior), matching
+ * rescue's posture elsewhere.
+ */
+export function reconcileClaudeSettings(ctx, preRescueSettingsJson, out, err) {
+    const { hqRoot, srcDir, env, historyFloor, baselineMode, preserveSubpaths } = ctx;
+    const settingsPath = path.join(hqRoot, ".claude", "settings.json");
+    const localPath = path.join(hqRoot, ".claude", "settings.local.json");
+    // The caller explicitly asked to keep settings.json (via `--preserve-subpath
+    // .claude/settings.json` or `--preserve-subpath .claude`). The shuttle already
+    // restored their file; honor that and do not rewrite it (nor land new
+    // registrations — that is the point of an explicit preserve).
+    if (settingsExplicitlyPreserved(preserveSubpaths)) {
+        out("==> Skipped .claude/settings.json reconcile (explicitly preserved by --preserve-subpath)\n");
+        return;
+    }
+    const overlaidTemplateExists = isFileFollow(settingsPath);
+    if (!overlaidTemplateExists) {
+        // The release no longer ships .claude/settings.json, but the overwrite-safe
+        // classification already deleted the local file. Restore the pre-rescue copy
+        // so the machine PATH and every user customization survive (critical under
+        // --no-backup, where no snapshot exists to recover from).
+        if (preRescueSettingsJson !== null) {
+            try {
+                fs.mkdirSync(path.dirname(settingsPath), { recursive: true });
+                fs.writeFileSync(settingsPath, preRescueSettingsJson);
+                out("==> Release no longer ships .claude/settings.json; restored your existing settings.json (no reconcile).\n");
+            }
+            catch {
+                err("    WARN: could not restore pre-rescue .claude/settings.json after the release dropped the template\n");
+            }
+        }
+        return;
+    }
+    const theirsRaw = (() => {
+        try {
+            return fs.readFileSync(settingsPath, "utf-8");
+        }
+        catch {
+            return null;
+        }
+    })();
+    const theirs = jsonParseOrNull(theirsRaw);
+    if (!isPlainObject(theirs)) {
+        err("    WARN: overlaid .claude/settings.json is not valid JSON; skipping settings reconcile\n");
+        return;
+    }
+    const ours = jsonParseOrNull(preRescueSettingsJson);
+    const oursIsValid = isPlainObject(ours);
+    // The pre-rescue settings.json existed but was not parseable, and the overlay
+    // already replaced it. Preserve the raw bytes under personal/ (the same place
+    // a user-edit rescue would have put them) so a temporarily-malformed file is
+    // never destroyed by a --no-backup run. Then continue with a PATH-recompose
+    // pass so the machine still works.
+    if (preRescueSettingsJson !== null && !oursIsValid) {
+        const backup = path.join(hqRoot, "personal", ".claude", "settings.json");
+        try {
+            fs.mkdirSync(path.dirname(backup), { recursive: true });
+            fs.writeFileSync(backup, preRescueSettingsJson);
+            err("    WARN: pre-rescue .claude/settings.json was not valid JSON; preserved a copy at personal/.claude/settings.json\n");
+        }
+        catch {
+            err("    WARN: pre-rescue .claude/settings.json was not valid JSON and could not be backed up\n");
+        }
+    }
+    const oursEnvPath = oursIsValid && isPlainObject(ours.env) && typeof ours.env.PATH === "string"
+        ? ours.env.PATH
+        : undefined;
+    // 1) Re-compose env.PATH onto the release baseline. Base = the machine's own
+    //    prior PATH snapshot when present, else this process's PATH.
+    const basePath = oursEnvPath ?? env.PATH ?? "";
+    const composedPath = composeSettingsPath(srcDir, hqRoot, basePath, env);
+    if (composedPath) {
+        const envObj = isPlainObject(theirs.env) ? theirs.env : (theirs.env = {});
+        envObj.PATH = composedPath;
+    }
+    // 2) Relocate genuine user drift (ours vs floor baseline) into settings.local,
+    //    and apply user array removals to the Project baseline.
+    let driftKeys = 0;
+    let relocationFailed = false;
+    if (oursIsValid) {
+        // realBase = settings.json at the last-sync floor (only trustworthy in
+        // history_floor mode). Removals require it; additions fall back to theirs.
+        let realBase;
+        if (baselineMode === "history_floor" && historyFloor) {
+            const show = run("git", ["show", `${historyFloor}:.claude/settings.json`], {
+                cwd: srcDir,
+                env,
+            });
+            if (show.status === 0)
+                realBase = jsonParseOrNull(show.stdout);
+        }
+        // Removals: only with a REAL floor base (never theirs — release-only entries
+        // would look like removals).
+        if (isPlainObject(realBase)) {
+            applyArrayRemovals(theirs, ours, realBase);
+        }
+        // Additions drift: base = realBase when available, else theirs (conservative
+        // head_compare fallback — never loses a customization). See design note.
+        const additionsBase = isPlainObject(realBase) ? realBase : theirs;
+        const drift = settingsDrift(ours, additionsBase);
+        if (isPlainObject(drift) && Object.keys(drift).length > 0) {
+            const existingLocal = jsonParseOrNull((() => {
+                try {
+                    return isFileFollow(localPath) ? fs.readFileSync(localPath, "utf-8") : null;
+                }
+                catch {
+                    return null;
+                }
+            })());
+            const localObj = isPlainObject(existingLocal) ? existingLocal : {};
+            deepMergeSettings(localObj, drift);
+            driftKeys = Object.keys(drift).length;
+            try {
+                fs.mkdirSync(path.dirname(localPath), { recursive: true });
+                fs.writeFileSync(localPath, JSON.stringify(localObj, null, 2) + "\n");
+            }
+            catch {
+                relocationFailed = true;
+                err("    WARN: could not write .claude/settings.local.json during settings reconcile\n");
+            }
+        }
+    }
+    // If drift relocation into settings.local.json failed, DO NOT overwrite
+    // settings.json with the release baseline — that would drop the drift with no
+    // on-disk copy under --no-backup. Restore the pre-rescue file so nothing is
+    // lost; the update simply isn't applied to settings this run (the user can
+    // retry once settings.local.json is writable).
+    if (relocationFailed) {
+        if (preRescueSettingsJson !== null) {
+            try {
+                fs.writeFileSync(settingsPath, preRescueSettingsJson);
+            }
+            catch {
+                err("    WARN: could not restore pre-rescue .claude/settings.json after a failed drift relocation\n");
+            }
+        }
+        err("    WARN: kept your original .claude/settings.json (settings update not applied — settings.local.json was unwritable)\n");
+        return;
+    }
+    // Write the re-composed release baseline back to settings.json.
+    try {
+        fs.writeFileSync(settingsPath, JSON.stringify(theirs, null, 2) + "\n");
+    }
+    catch {
+        err("    WARN: could not write re-composed .claude/settings.json during reconcile\n");
+        return;
+    }
+    if (driftKeys > 0) {
+        out(`==> Reconciled .claude/settings.json to release baseline (env.PATH re-composed; ` +
+            `relocated ${driftKeys} drift key(s) -> .claude/settings.local.json)\n`);
+    }
+    else {
+        out("==> Reconciled .claude/settings.json to release baseline (env.PATH re-composed; no local drift to relocate)\n");
+    }
+}
 /**
  * Defense-in-depth for executable scaffold scripts. `rescue` rebuilds the tree
  * with `git clone` + `rsync -a`, faithfully propagating each file's git tree