@indigoai-us/hq-cloud 6.14.49 → 6.15.0

package/src/cli/rescue-core.ts

@@ -531,6 +531,26 @@ function doRescue(
   // 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: string | null = 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 = "";
@@ -1050,6 +1070,22 @@ function doRescue(
     }
   }
 
+  // --- 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
@@ -1548,7 +1584,17 @@ function isOverwriteSafe(rel: string): boolean {
     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"
   );
 }
 
@@ -1713,6 +1759,418 @@ function diffAppendClaudeMd(ctx: WalkCtx): void {
   ctx.counts.claudeDiffAppend += 1;
 }
 
+// --- .claude/settings.json reconcile (recompose env.PATH + relocate drift) ---
+
+type JsonValue =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonValue[]
+  | { [k: string]: JsonValue };
+
+function isPlainObject(v: unknown): v is { [k: string]: JsonValue } {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Structural deep equality for JSON values (stable, order-sensitive for objects). */
+export function jsonDeepEqual(a: JsonValue, b: JsonValue): boolean {
+  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: string | null | undefined): JsonValue | null {
+  if (text == null) return null;
+  try {
+    return JSON.parse(text) as JsonValue;
+  } 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: JsonValue,
+  base: JsonValue | undefined,
+  excludePath: string[] = ["env.PATH"],
+  pathPrefix = "",
+): JsonValue | undefined {
+  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: { [k: string]: JsonValue } = {};
+      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: { [k: string]: JsonValue } = {};
+    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: { [k: string]: JsonValue },
+  patch: { [k: string]: JsonValue },
+): { [k: string]: JsonValue } {
+  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: { [k: string]: JsonValue },
+  ours: { [k: string]: JsonValue },
+  base: { [k: string]: JsonValue },
+): void {
+  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: string,
+  hqRoot: string,
+  basePath: string,
+  env: NodeJS.ProcessEnv,
+): string {
+  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;
+}
+
+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[];
+}
+
+/** 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: string[]): boolean {
+  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: ReconcileCtx,
+  preRescueSettingsJson: string | null,
+  out: (s: string) => void,
+  err: (s: string) => void,
+): void {
+  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: JsonValue | undefined;
+    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: JsonValue = 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