Skip to content

SettingsBackport + MergeSettings: a backported hook edit makes the overlay own hooks, and the next SessionStart merge drops every hook it does not list #2820

Open

Description

@Luo0oo

The SessionStart hook runs SettingsBackport.ts; MergeSettings.ts --system … --user … --output settings.json. v8.761.0's settings.system.json ships no hooks key, and hooks is in MergeSettings.ts INSTALLER_OWNED_KEYS: mergeSettingsPreserving carries it from the existing settings.json only while neither layer defines it.

1. Silent hook loss (most serious). SettingsBackport.ts never consults INSTALLER_OWNED_KEYS. When anything edits part of live hooks, the backport writes that part into USER/CONFIG/settings.user.json, and from then on the overlay owns hooks. If the edit changes a group (a timeout, say), the drift counts as one element removed and one added, so it is backported as a whole array. That array verifies, and the next merge writes a settings.json holding only the backported event. Every other hook event is gone, and nothing reports the dropped events: the backport only warns that the one array is now pinned.

Repro, in a throwaway CLAUDE_CONFIG_DIR:

  • the system layer has no hooks;
  • the overlay is {"model":"x"};
  • the snapshot and live settings.json carry SessionStart, PreToolUse and Stop;
  • change one PreToolUse hook's timeout in live;
  • run SettingsBackport, then MergeSettings.

Expected: all three events in the output. Actual: only PreToolUse.

A tool that re-registers its own hooks at startup by removing its groups and appending them again (which moves them to the end) is enough to trigger the reorder form, § 2 below.

2. Nested annotations never resolve, so the chain wedges. This part is #2636 (and #2737), both closed as fixed for the next release; it is kept here because § 1 depends on it. In mergeSettings, a user key that the system layer lacks recurses as mergeSettings(undefined, user[key]). A plain object then falls through to cloneJsonValue(user), and any __merge annotation inside is copied out raw:

mergeSettings({}, { hooks: { X: { __merge: "append", values: [1] } } })
// → { hooks: { X: { __merge: "append", values: [1] } } }   expected { hooks: { X: [1] } }

__merge: "remove" leaks the same way. The control is the same overlay merged against a system layer that has hooks: {}: it resolves to { hooks: { X: [1] } }.

In the chain:

  • A reorder of live hook groups backports as append annotations, so SettingsBackport's verification fails, MergeSettings refuses to write ("backporting its hand edits failed"), and the merge snapshot never refreshes. Every later session start repeats it.
  • Adding one spinner tip does the same, because the system layer has no spinnerTipsOverride, so the backport appends onto a parent the merge cannot resolve.

Refusing is the safe outcome here, but it hides § 1. Fixing § 2 first, on an install whose overlay already holds a captured partial hooks, turns the wedge into the loss in § 1. That is the order the #2636 fix puts installs in: once it reaches them, a wedged chain stops refusing and the next session start writes settings.json with only the hooks the overlay captured. Shipping § 1's guard (fix 1 or 2 below) in the same release as the #2636 fix avoids that.

3. Smaller defects in the same chain.

  • SettingsBackport writes settings.user.json before it verifies, and does not roll back a failed non-deletion change.
  • permissions arrays are planned as sets (ORDER_FREE_ROOTS) but verified in order, so a reordered allow list plus one new rule plans an append that then fails verification.
  • An array drift onto a non-array system value plans an append, and the merge throws __merge: "append" requires the system value to be an array or absent.
  • Verification compares the merge with the live file, so a permission the system layer added since the last snapshot, together with one added live in the same window, makes a correct append fail verification (system ["Read","Bash"], snapshot ["Read"], live ["Read","Write"]). The chain then refuses again on every later session start.
  • SettingsBackport ignores flags it does not know: SettingsBackport.ts --help runs a real backport, and writes the overlay if there is drift. Only --dry-run is recognised.

A possible fix.

  1. SettingsBackport drops drift under any INSTALLER_OWNED_KEYS entry that neither layer defines. The merge already carries those keys from live, so a hand edit survives without a backport.
  2. MergeSettings --output refuses to write while the merge would remove any hook registration that the existing settings.json has, unless --allow-hook-drop is passed. A registration is counted with multiplicity and keyed by event, matcher, and the hook record apart from timeout. Keying on event + command alone misses a removed matcher group whose command still runs under another matcher. This catches § 1 whatever the cause, including a future settings.system.json that starts shipping hooks.
  3. SettingsBackport appends only when the system layer has the array's parent object and the leaf is an array or absent, and otherwise writes the array whole. Order-free roots verify as sets.
  4. With 1-3 in place, fixing § 2 is safe. Rejecting unknown flags fixes the last bullet of § 3.

Related. #2636 and #2737 (§ 2, closed); #2736 (SettingsBackport refuses on a missing system key, the same wedge from another trigger); #2759 (a fresh install's first merge drops all hooks, because InstallAll writes them into settings.json only). § 1 is a different path to the same loss as #2759: it needs no fresh install, only one backported hook edit.

Activity

  1. gjaworski86 commented on Nov 16, 2026

    @gjaworski86

    Note

    🤖 Klaudia (AI assistant) responding on behalf of Grzegorz

    Version

    LifeOS 8.761.0 · attestation: 40 system file(s) differ from danielmiessler/LifeOS@v8.761.0:

    • hooks/SatisfactionCapture.hook.ts
    • hooks/README.md
    • skills/CreateCLI/SKILL.md
    • skills/CreateCLI/Intents/CreateCli.md
    • skills/Prompting/SKILL.md
    • skills/RichFormat/tests/engine.test.tsx
    • skills/RichFormat/hooks/register.tsx
    • skills/LifeOSHooks/hooks/lib/build.ts
    • skills/Herdr/Intents/Configure.md
    • skills/LifeOS/SKILL.md
    • skills/LifeOS/Intents/Setup.md
    • skills/Fabric/SKILL.md
    • agents/Astra.md
    • agents/Sol.md
    • LIFEOS/TOOLS/SettingsBackport.ts
    • LIFEOS/TOOLS/VideoMeaning/README.md
    • LIFEOS/TOOLS/MemoryRetriever.ts
    • LIFEOS/TOOLS/MergeSettings.ts
    • LIFEOS/TOOLS/SchedulerWatch.ts
    • LIFEOS/TOOLS/models.ts
    • LIFEOS/TOOLS/model-pricing.json
    • LIFEOS/TOOLS/Worker.ts
    • LIFEOS/DOCUMENTATION/Tools/Tools.md
    • LIFEOS/DOCUMENTATION/Memory/MemorySystem.md
    • LIFEOS/DOCUMENTATION/Config/ConfigSystem.md
    • LIFEOS/DOCUMENTATION/Location/LocationSystem.md
    • LIFEOS/DOCUMENTATION/Pulse/TerminalTabs.md
    • LIFEOS/DOCUMENTATION/Pulse/PulseSystem.md
    • LIFEOS/DOCUMENTATION/Workflows/WorkflowsSystem.md
    • LIFEOS/DOCUMENTATION/LifeosSystemArchitecture.md
    • LIFEOS/DOCUMENTATION/ARCHITECTURE_SUMMARY.md
    • LIFEOS/DOCUMENTATION/Algorithm/AscentStates.md
    • LIFEOS/DOCUMENTATION/Testing/TestingDoctrine.md
    • LIFEOS/DOCUMENTATION/Hooks/HookSystem.md
    • LIFEOS/DOCUMENTATION/Work/WorkSystem.md
    • LIFEOS/DOCUMENTATION/Assay/AssaySystem.md
    • LIFEOS/DOCUMENTATION/Services/BackgroundServices.md
    • LIFEOS/DOCUMENTATION/Router/RouterSystem.md
    • LIFEOS/ALGORITHM/AlgorithmReference.md
    • LIFEOS/ERRATA/fixtures/LabelBrief.md

    What is broken

    Confirming #2820 §1–§3 on 8.761.0, with a small fix and a regression suite. Once SettingsBackport records a hand edit under hooks (an installer-owned key the system layer does not define), it writes hooks.<event> into the overlay as an append; from then on mergeSettingsPreserving stops carrying the installer's hooks, so the next merge would drop every installer hook. Its verification also cannot pass (it merges without the installer layer, compares permission sets in order, and counts a deleted key that no layer supplies as a failure), so MergeSettings refuses at every SessionStart and settings.json stays frozen. Here it stayed frozen for five days.

    Where (file:line)

    LIFEOS/TOOLS/SettingsBackport.ts:315, LIFEOS/TOOLS/MergeSettings.ts:169

    Repro on a clean tree

    1. On a stock 8.761.0 install with a user overlay, add any hook to settings.json by hand (or let the harness insert an "always allow" rule mid-array in `permissions.allow`).
    2. Start a session. SettingsBackport writes `hooks.PreToolUse: {"__merge":"append",...}` into settings.user.json and reports `verification failed — $.permissions.allow, $.hooks.PreToolUse`; MergeSettings prints `refusing to overwrite settings.json: backporting its hand edits failed` on every later SessionStart.
    3. `MergeSettings --check settings.json` now shows every installer hook event missing from the merge result and the raw `__merge` annotation under `hooks.PreToolUse`.
    The attached suite (11 tests, synthetic data, temp CLAUDE_CONFIG_DIR) drives both CLIs the way SessionStart does: 9 fail on the shipped tools, 11 pass with the patch.

    Negative control

    Probe: cd /private/tmp/claude-501/-Users-<user>--claude/6c197f74-819b-4b11-a672-475667d218e0/scratchpad && TOOLS_DIR=/private/tmp/claude-501/-Users-<user>--claude/6c197f74-819b-4b11-a672-475667d218e0/scratchpad/orig-tools/LIFEOS/TOOLS bun test ~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts · exit 1 · captured 2026-11-16T20:20:46.460Z

    Red looks like: 9 fail

    bun test v1.4.4 (38afee6c8)
    
    --- stderr ---
    
    ../../../../../..~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:
    46 |   test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    47 |     const live = { ...system, hooks };
    48 |     const r = root(live, snap, system, {});
    49 |     for (const run of [1, 2, 3]) {
    50 |       const s = sessionStart(r);
    51 |       expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                              ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:51:38)
    (fail) hooks carried verbatim, overlay untouched: added user hook [25.96ms]
    46 |   test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    47 |     const live = { ...system, hooks };
    48 |     const r = root(live, snap, system, {});
    49 |     for (const run of [1, 2, 3]) {
    50 |       const s = sessionStart(r);
    51 |       expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                              ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:51:38)
    (fail) hooks carried verbatim, overlay untouched: option-only edit [25.50ms]
    46 |   test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    47 |     const live = { ...system, hooks };
    48 |     const r = root(live, snap, system, {});
    49 |     for (const run of [1, 2, 3]) {
    50 |       const s = sessionStart(r);
    51 |       expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                              ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:51:38)
    (fail) hooks carried verbatim, overlay untouched: withdrawn installer hook in a mixed group [25.27ms]
    46 |   test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    47 |     const live = { ...system, hooks };
    48 |     const r = root(live, snap, system, {});
    49 |     for (const run of [1, 2, 3]) {
    50 |       const s = sessionStart(r);
    51 |       expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                              ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:51:38)
    (fail) hooks carried verbatim, overlay untouched: same command, distinct args and if [25.04ms]
    46 |   test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    47 |     const live = { ...system, hooks };
    48 |     const r = root(live, snap, system, {});
    49 |     for (const run of [1, 2, 3]) {
    50 |       const s = sessionStart(r);
    51 |       expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                              ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:51:38)
    (fail) hooks carried verbatim, overlay untouched: non-command hook types [25.47ms]
    58 | test("permission inserted mid-array by the harness: backported as a set, no refusal", () => {
    59 |   const live = { permissions: { allow: ["Read", "Bash(run:*)", "Grep", "Glob"] }, theme: "dark", hooks: installed };
    60 |   const r = root(live, snap, system, {});
    61 |   for (const run of [1, 2]) {
    62 |     const s = sessionStart(r);
    63 |     expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                            ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:63:36)
    (fail) permission inserted mid-array by the harness: backported as a set, no refusal [25.79ms]
    68 | 
    69 | test("a key deleted in settings.json that no layer supplies is already done, not a failure", () => {
    70 |   const r = root({ ...system, hooks: installed }, snap, system, {});
    71 |   for (const run of [1, 2]) {
    72 |     const s = sessionStart(r);
    73 |     expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
                                            ^
    error: expect(received).toEqual(expected)
    
    @@ -2,4 +2,4 @@
        1,
    -   0,
    -   0,
    +   1,
    +   1,
      ]
    
    - Expected  - 2
    + Received  + 2
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:73:36)
    (fail) a key deleted in settings.json that no layer supplies is already done, not a failure [24.31ms]
    78 | test("an overlay-only object's nested append annotation is consumed, never emitted raw", () => {
    79 |   const user = { spinnerTipsOverride: { tips: { __merge: "append", values: ["a"] } } };
    80 |   const r = root({ ...system }, { ...system }, system, user);
    81 |   const s = sessionStart(r);
    82 |   expect(s.merge).toBe(0);
    83 |   expect(s.out.spinnerTipsOverride).toEqual({ tips: ["a"] });
                                             ^
    error: expect(received).toEqual(expected)
    
      {
    -   "tips": [
    -     "a",
    -   ],
    +   "tips": {
    +     "__merge": "append",
    +     "values": [
    +       "a",
    +     ],
    +   },
      }
    
    - Expected  - 3
    + Received  + 6
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:83:37)
    (fail) an overlay-only object's nested append annotation is consumed, never emitted raw [24.57ms]
    88 |   const live = { ...system, ...owned, statusLine: { type: "command", command: "s2.ts" } }; // hand edit under one of them
    89 |   const r = root(live, { ...system, ...owned }, system, {});
    90 |   for (const run of [1, 2]) {
    91 |     const s = sessionStart(r);
    92 |     expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    93 |     for (const k of Object.keys(owned)) expect([k, s.out[k]]).toEqual([k, live[k as keyof typeof live]]);
                                                                       ^
    error: expect(received).toEqual(expected)
    
    @@ -4,3 +4,2 @@
          "command": "s2.ts",
    -     "type": "command",
        },
    
    - Expected  - 1
    + Received  + 0
    
          at <anonymous> (~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts:93:63)
    (fail) all four installer-owned keys are carried over and never captured into the overlay [25.54ms]
    
     2 pass
     9 fail
     18 expect() calls
    Ran 11 tests across 1 file. [284.00ms]
    

    Suggested fix

    Smallest fix we found that holds (+32/−6 across the two tools, plus the suite): one ownership predicate, isCarriedForward(key, system, user), shared by MergeSettings and SettingsBackport. The merge already carries installer-owned keys over from settings.json when neither layer defines them, so the backport now skips drift under exactly those keys: hand edits there are kept by the merge itself and the overlay never comes to own hooks. Same direction as the fix promised in #2488. Also in the diff: permission arrays verify as sets (#2162), a deletion of a key no layer supplies is no longer a failure (#2736), and a user-only object is merged against {} so nested annotations are consumed (#2636).
    We first tried merging hooks per event with the installer payload as a base layer; four rounds of adversarial review kept finding new hook-identity defects (shared matchers, options-only edits, args/if handlers), so we dropped it. Not fixed by this patch and present before it: a new live object plus a concurrent system-side sibling still refuses, and an edit under an overlay {"__merge":"remove"} parent still yields an invalid annotation. An overlay that already holds hooks must have that key removed by hand.

    diff --git a/LIFEOS/TOOLS/MergeSettings.ownership.test.ts b/LIFEOS/TOOLS/MergeSettings.ownership.test.ts
    new file mode 100644
    index 0000000..4501f15
    --- /dev/null
    +++ b/LIFEOS/TOOLS/MergeSettings.ownership.test.ts
    @@ -0,0 +1,116 @@
    +// Regression suite for the settings merge/backport ownership rule (#2820): the overlay never holds keys the merge carries
    +// over from settings.json. Drives the real CLIs against a temp config root. Synthetic data only.
    +import { test, expect } from "bun:test";
    +import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from "node:fs";
    +import { tmpdir } from "node:os";
    +import { join } from "node:path";
    +
    +const TOOLS = process.env.TOOLS_DIR ?? import.meta.dir;
    +const H = (command: string, extra: Record<string, unknown> = {}) => ({ type: "command", command, ...extra });
    +const G = (matcher: string, ...hooks: any[]) => ({ matcher, hooks });
    +
    +function root(live: any, snapshot: any, system: any, user: any) {
    +  const r = mkdtempSync(join(tmpdir(), "merge-v7-"));
    +  mkdirSync(join(r, "LIFEOS/USER/CONFIG"), { recursive: true });
    +  mkdirSync(join(r, "LIFEOS/MEMORY/STATE"), { recursive: true });
    +  const w = (p: string, v: any) => writeFileSync(join(r, p), JSON.stringify(v, null, 2) + "\n");
    +  w("settings.system.json", system);
    +  w("LIFEOS/USER/CONFIG/settings.user.json", user);
    +  w("settings.json", live);
    +  w("LIFEOS/MEMORY/STATE/settings-merge-snapshot.json", snapshot);
    +  return r;
    +}
    +const env = (r: string) => ({ ...process.env, CLAUDE_CONFIG_DIR: r, LIFEOS_DIR: "" });
    +function sessionStart(r: string) {
    +  const back = Bun.spawnSync(["bun", join(TOOLS, "SettingsBackport.ts")], { env: env(r) });
    +  const merge = Bun.spawnSync(["bun", join(TOOLS, "MergeSettings.ts"), "--system", join(r, "settings.system.json"),
    +    "--user", join(r, "LIFEOS/USER/CONFIG/settings.user.json"), "--output", join(r, "settings.json")], { env: env(r) });
    +  return { back: back.exitCode, merge: merge.exitCode, out: JSON.parse(readFileSync(join(r, "settings.json"), "utf8")),
    +    overlay: JSON.parse(readFileSync(join(r, "LIFEOS/USER/CONFIG/settings.user.json"), "utf8")) };
    +}
    +const system = { permissions: { allow: ["Read", "Grep", "Glob"] }, theme: "dark" };
    +const installed = { PreToolUse: [G("Agent", H("agent.ts")), G("Bash", H("a.ts"), H("b.ts"))], Stop: [G("", H("stop.ts", { async: true }))] };
    +const snap = { ...system, model: "opus", hooks: installed };
    +
    +// Every hand edit Sol's audits used against v2–v6, applied to settings.json hooks, must come out byte-for-byte.
    +const hookEdits: Record<string, any> = {
    +  "added user hook": { ...installed, PreToolUse: [...installed.PreToolUse, G("Bash", H("mine.ts", { timeout: 30 }))] },
    +  "option-only edit": { ...installed, Stop: [G("", H("stop.ts", { async: true, timeout: 123 }))] },
    +  "withdrawn installer hook in a mixed group": { ...installed, PreToolUse: [installed.PreToolUse[0], G("Bash", H("b.ts"))] },
    +  "same command, distinct args and if": { ...installed, PreToolUse: [...installed.PreToolUse,
    +    G("Bash", { type: "command", command: "bun", args: ["security.ts"] }), G("Bash", { type: "command", command: "bun", args: ["audit.ts"] }),
    +    G("Bash", H("guard.ts", { if: "Bash(rm *)" })), G("Bash", H("guard.ts", { if: "Bash(git push *)" }))] },
    +  "non-command hook types": { ...installed, Stop: [...installed.Stop, G("", { type: "prompt", prompt: "check" }), G("", { type: "http", url: "https://example.invalid", headers: { A: "1" } })] },
    +};
    +for (const [name, hooks] of Object.entries(hookEdits)) {
    +  test(`hooks carried verbatim, overlay untouched: ${name}`, () => {
    +    const live = { ...system, hooks };
    +    const r = root(live, snap, system, {});
    +    for (const run of [1, 2, 3]) {
    +      const s = sessionStart(r);
    +      expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +      expect(s.out.hooks).toEqual(hooks);
    +      expect(s.overlay.hooks).toBeUndefined();
    +    }
    +  });
    +}
    +
    +test("permission inserted mid-array by the harness: backported as a set, no refusal", () => {
    +  const live = { permissions: { allow: ["Read", "Bash(run:*)", "Grep", "Glob"] }, theme: "dark", hooks: installed };
    +  const r = root(live, snap, system, {});
    +  for (const run of [1, 2]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    expect(new Set(s.out.permissions.allow)).toEqual(new Set(live.permissions.allow));
    +    expect(s.out.hooks).toEqual(installed);
    +  }
    +});
    +
    +test("a key deleted in settings.json that no layer supplies is already done, not a failure", () => {
    +  const r = root({ ...system, hooks: installed }, snap, system, {});
    +  for (const run of [1, 2]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    expect(s.out.model).toBeUndefined();
    +  }
    +});
    +
    +test("an overlay-only object's nested append annotation is consumed, never emitted raw", () => {
    +  const user = { spinnerTipsOverride: { tips: { __merge: "append", values: ["a"] } } };
    +  const r = root({ ...system }, { ...system }, system, user);
    +  const s = sessionStart(r);
    +  expect(s.merge).toBe(0);
    +  expect(s.out.spinnerTipsOverride).toEqual({ tips: ["a"] });
    +});
    +
    +test("all four installer-owned keys are carried over and never captured into the overlay", () => {
    +  const owned = { hooks: installed, statusLine: { type: "command", command: "s.ts" }, spinnerVerbs: { mode: "append", verbs: ["x"] }, spinnerTipsOverride: { tips: ["t"] } };
    +  const live = { ...system, ...owned, statusLine: { type: "command", command: "s2.ts" } }; // hand edit under one of them
    +  const r = root(live, { ...system, ...owned }, system, {});
    +  for (const run of [1, 2]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    for (const k of Object.keys(owned)) expect([k, s.out[k]]).toEqual([k, live[k as keyof typeof live]]);
    +    for (const k of Object.keys(owned)) expect([k, k in s.overlay]).toEqual([k, false]);
    +  }
    +});
    +
    +test("an installer-owned key the overlay defines is not carried over: the overlay wins", () => {
    +  const user = { statusLine: { type: "command", command: "mine.ts" } };
    +  const live = { ...system, hooks: installed, statusLine: { type: "command", command: "old.ts" } };
    +  const r = root(live, { ...live }, system, user);
    +  const s = sessionStart(r);
    +  expect([s.back, s.merge]).toEqual([0, 0]);
    +  expect(s.out.statusLine).toEqual(user.statusLine);
    +  expect(s.out.hooks).toEqual(installed);
    +});
    +
    +test("hooks defined by a source layer still backport (carry-over does not apply there)", () => {
    +  const sys = { ...system, hooks: { Stop: [G("", H("sys.ts"))] } };
    +  const live = { ...sys, hooks: { Stop: [G("", H("sys.ts")), G("", H("mine.ts"))] } };
    +  const r = root(live, { ...sys }, sys, {});
    +  const s = sessionStart(r);
    +  expect([s.back, s.merge]).toEqual([0, 0]);
    +  expect(s.out.hooks.Stop).toEqual(live.hooks.Stop);
    +  expect(s.overlay.hooks).toBeDefined();
    +});
    diff --git a/LIFEOS/TOOLS/MergeSettings.ts b/LIFEOS/TOOLS/MergeSettings.ts
    index 4e673d8..781dd2c 100755
    --- a/LIFEOS/TOOLS/MergeSettings.ts
    +++ b/LIFEOS/TOOLS/MergeSettings.ts
    @@ -161,13 +161,22 @@ export function guardPermissionOverlays(system: any, user: any, merged: any): st
      */
     export const INSTALLER_OWNED_KEYS = ["hooks", "statusLine", "spinnerVerbs", "spinnerTipsOverride"] as const;
     
    +/**
    + * True when the merge carries key `k` over from the existing settings.json: an installer-owned key
    + * that neither source layer defines. The one ownership rule — SettingsBackport skips these keys
    + * because the merge already preserves every edit made under them (#2820).
    + */
    +export function isCarriedForward(k: string, system: any, user: any): boolean {
    +  const inLayer = (system && typeof system === "object" && k in system) || (user && typeof user === "object" && k in user);
    +  return (INSTALLER_OWNED_KEYS as readonly string[]).includes(k) && !inLayer;
    +}
    +
     /** system ⊕ user, plus the installer-owned keys of `existing` that neither layer defines. */
     export function mergeSettingsPreserving(system: any, user: any, existing: any): any {
       const merged = mergeSettings(system, user);
       if (existing && typeof existing === "object") {
         for (const k of INSTALLER_OWNED_KEYS) {
    -      const inLayer = (system && typeof system === "object" && k in system) || (user && typeof user === "object" && k in user);
    -      if (!inLayer && k in existing) merged[k] = existing[k];
    +      if (isCarriedForward(k, system, user) && k in existing) merged[k] = existing[k];
         }
       }
       return merged;
    @@ -184,6 +193,11 @@ export function mergeSettings(system: any, user: any): any {
         );
       }
     
    +  // An overlay-only object merges against an empty base, so nested annotations are consumed, never emitted raw.
    +  if (system === undefined && isObjectRecord(user)) {
    +    return mergeSettings({}, user);
    +  }
    +
       if (isObjectRecord(system) && isObjectRecord(user)) {
         const merged: Record<string, any> = {};
     
    diff --git a/LIFEOS/TOOLS/SettingsBackport.ts b/LIFEOS/TOOLS/SettingsBackport.ts
    index 750b6b6..279c081 100755
    --- a/LIFEOS/TOOLS/SettingsBackport.ts
    +++ b/LIFEOS/TOOLS/SettingsBackport.ts
    @@ -49,7 +49,7 @@
     import { existsSync } from "node:fs";
     import path from "node:path";
     import os from "node:os";
    -import { mergeSettings, deepEqual, parseJsonFileOrThrow, MERGE_SNAPSHOT_PATH } from "./MergeSettings";
    +import { mergeSettings, deepEqual, parseJsonFileOrThrow, MERGE_SNAPSHOT_PATH, isCarriedForward } from "./MergeSettings";
     import { atomicWriteText } from "../PULSE/lib/atomic-write";
     import { getClaudeDir } from "./Paths"; // public issue #1974 @sabo961, PR #1918 @PigLardLord
     
    @@ -247,7 +247,10 @@ async function run(dryRun: boolean): Promise<number> {
       }
       const snapshot = await parseJsonFileOrThrow(MERGE_SNAPSHOT_PATH);
     
    -  const drift = collectDrift(snapshot, actual);
    +  // Keys the merge carries over from settings.json itself (installer-owned, defined by neither layer)
    +  // already keep every edit made under them; backporting them would make the overlay define the key
    +  // and stop the carry-over. #2820
    +  const drift = collectDrift(snapshot, actual).filter((d) => !isCarriedForward(d.segments[0], system, user));
     
       if (drift.length === 0) {
         console.log("settings.json matches the last merge snapshot — nothing to backport");
    @@ -317,7 +320,12 @@ async function run(dryRun: boolean): Promise<number> {
         ...changes.map((d) => ({ segments: d.segments, value: d.value })),
         ...arrayPlans.map((p) => ({ segments: p.segments, value: p.after })),
       ];
    -  const remaining = expectations.filter((e) => !deepEqual(getAtPath(verified, e.segments), e.value));
    +  // Order-free roots (permission sets) verify as sets, the way they were planned (public issue #2162).
    +  const sameValue = (segments: string[], got: any, want: any) =>
    +    ORDER_FREE_ROOTS.has(segments[0]) && Array.isArray(got) && Array.isArray(want)
    +      ? (({ added, removed }) => added.length === 0 && removed.length === 0)(classifyArrayDrift(got, want))
    +      : deepEqual(got, want);
    +  const remaining = expectations.filter((e) => !sameValue(e.segments, getAtPath(verified, e.segments), e.value));
     
       // Deletions the system half resurrects: restore the overlay entry and warn.
       const resurrected = removed.filter((r) => getAtPath(verified, r.segments) !== undefined);
    @@ -350,7 +358,11 @@ async function run(dryRun: boolean): Promise<number> {
         }
       }
     
    -  const failed = remaining.length + resurrected.length + (deletions.length - removed.length);
    +  // A deletion no overlay entry supplied fails only while the merge still produces the key; absent is done.
    +  const stillPresent = deletions.filter(
    +    (d) => !removed.some((r) => deepEqual(r.segments, d.segments)) && getAtPath(verified, d.segments) !== undefined,
    +  ).length;
    +  const failed = remaining.length + resurrected.length + stillPresent;
       if (failed > 0) return 1;
       console.log("verified: every backported change survives merge(system, user)");
       return 0;

    Verified after fix

    Probe: cd /private/tmp/claude-501/-Users-<user>--claude/6c197f74-819b-4b11-a672-475667d218e0/scratchpad && bun test ~/.claude/LIFEOS/TOOLS/MergeSettings.ownership.test.ts · exit 0 · captured 2026-11-16T20:20:10.915Z

    bun test v1.4.4 (38afee6c8)
    
    --- stderr ---
    
     11 pass
     0 fail
     81 expect() calls
    Ran 11 tests across 1 file. [708.00ms]
    

    Environment

    • OS: macOS 27.2.1 (arm64)
    • Harness: claude-code
    • bun: 1.4.4 · git: 2.54.0
    • Doctor broken: none
  2. gjaworski86 commented on Nov 16, 2026

    @gjaworski86

    Note

    🤖 Klaudia (AI assistant) responding on behalf of Grzegorz

    Follow-up to my earlier comment: the two defects I listed there as "not fixed by this patch", plus one more, with a fix and a regression run. All three are present on stock 8.761.0 (main matches the release for both files).

    What is broken

    1. New live object + concurrent system sibling (§3, fourth bullet, object form). Live adds env: {X} (or permissions: {allow: [...]}) while the system layer adds env.Y (or permissions.deny). collectDrift reports the whole new object as one change, the overlay pins it, and verification compares {X} with the merged {X, Y}, so it fails. MergeSettings refuses at every SessionStart. This needs a system-layer change, so it fires during an update.
    2. Edit under a parent the overlay removes. With env: {"__merge":"remove"} in the overlay, a backported env.X is written into the annotation ({"__merge":"remove","X":"new"}) and every merge throws __merge annotations must use…. When the drift is the whole object instead, the remove is replaced, the other system keys come back, and verification fails. /statusline off is a shipped writer of this annotation.
    3. Append dedup is key-order sensitive. applyArrayMerge dedups by JSON.stringify, so a system hook group and the same group with other key order in an append annotation both end up in settings.json.

    Also: the SettingsBackport header says the merge format has no delete annotation, but mergeSettings supports {"__merge":"remove"} (CoreConfig.md documents it).

    Repro

    Each case runs SettingsBackport and then MergeSettings, three times, against a temp CLAUDE_CONFIG_DIR (synthetic data). The five tests below were appended to the suite from my earlier comment.

    Case system overlay snapshot live expected actual
    1 env {env:{Y}} {} {} {env:{X}} exit 0/0, env {Y,X} exit 1/1 every run
    1 permissions {permissions:{deny:[r]}} {} {} {permissions:{allow:[a,b]}} exit 0/0, both arrays exit 1/1 every run
    2 (×2 snapshots) {env:{X:old,Z}} {env:remove} {env:{X:old}} or {} {env:{X:new}} exit 0/0, env {X:new} exit 1/1 every run
    3 {hooks:{PreToolUse:[g]}} append [g′] (g, keys reordered) live {hooks:{PreToolUse:[g]}} one group two groups

    Negative control

    Suite with the new tests on the unpatched tools: 11 pass, 5 fail. The five failures are the new tests, and each fails on its assertion (exit codes or group count), not on setup.

    Suggested fix (+35/−7 across the two tools, plus 42 test lines)

    • collectDrift: a key missing from the snapshot whose live value is a non-empty object drifts per leaf, so the overlay gets env.X and the system env.Y still reaches the merge.
    • deepSet: writing under an overlay {"__merge":"remove"} expands it into one remove per system key at that path, so the written key lands and the other system keys stay removed.
    • applyArrayMerge: dedup by canonical JSON (keys sorted at every level).
    • The header now describes the remove annotation correctly.

    1 and 2 should ship together: with 1 alone, the case "snapshot taken after the remove" goes from a refusal to a thrown annotation error.

    A larger direction, not in this diff: both tools encode the annotation format, mergeSettings reading it and SettingsBackport writing it. Most defects in this thread (§3, #2736, the cases above) come from the writer not being the exact inverse of the reader. One overlay module that owns merge and its inverse, with a property test that merge(system, backport(snapshot, live, overlay)) reproduces live, would close the class.

    Diff
    diff --git a/LIFEOS/TOOLS/MergeSettings.ownership.test.ts b/LIFEOS/TOOLS/MergeSettings.ownership.test.ts
    index 4501f15..0248136 100644
    --- a/LIFEOS/TOOLS/MergeSettings.ownership.test.ts
    +++ b/LIFEOS/TOOLS/MergeSettings.ownership.test.ts
    @@ -114,3 +114,45 @@ test("hooks defined by a source layer still backport (carry-over does not apply
       expect(s.out.hooks.Stop).toEqual(live.hooks.Stop);
       expect(s.overlay.hooks).toBeDefined();
     });
    +
    +// #2820 §3 follow-up: a new live object, a parent the overlay removes, and append dedup by key order.
    +test("a new live object with a concurrent system sibling merges, no refusal", () => {
    +  const r = root({ env: { X: "hand-added" } }, {}, { env: { Y: "source-added" } }, {});
    +  for (const run of [1, 2, 3]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    expect(s.out.env).toEqual({ Y: "source-added", X: "hand-added" });
    +  }
    +});
    +
    +test("a new live permission array with a concurrent system array merges, no refusal", () => {
    +  const r = root({ permissions: { allow: ["Read", "Glob"] } }, {}, { permissions: { deny: ["Bash(rm:*)"] } }, {});
    +  for (const run of [1, 2, 3]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    expect(s.out.permissions).toEqual({ deny: ["Bash(rm:*)"], allow: ["Read", "Glob"] });
    +  }
    +});
    +
    +for (const [name, snapshot] of [["snapshot before the remove", { env: { X: "old" } }], ["snapshot after the remove", {}]] as const) {
    +  test(`an edit under a parent the overlay removes lands, other system keys stay removed: ${name}`, () => {
    +    const r = root({ env: { X: "new" } }, snapshot, { env: { X: "old", Z: "sys" } }, { env: { __merge: "remove" } });
    +    for (const run of [1, 2, 3]) {
    +      const s = sessionStart(r);
    +      expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +      expect(s.out.env).toEqual({ X: "new" });
    +    }
    +  });
    +}
    +
    +test("append dedup ignores key order", () => {
    +  const a = { matcher: "Bash", hooks: [{ type: "command", command: "guard.ts" }] };
    +  const b = { hooks: [{ command: "guard.ts", type: "command" }], matcher: "Bash" };
    +  const live = { hooks: { PreToolUse: [a] } };
    +  const r = root(live, live, { hooks: { PreToolUse: [a] } }, { hooks: { PreToolUse: { __merge: "append", values: [b] } } });
    +  for (const run of [1, 2, 3]) {
    +    const s = sessionStart(r);
    +    expect([run, s.back, s.merge]).toEqual([run, 0, 0]);
    +    expect(s.out.hooks.PreToolUse.length).toBe(1);
    +  }
    +});
    diff --git a/LIFEOS/TOOLS/MergeSettings.ts b/LIFEOS/TOOLS/MergeSettings.ts
    index 781dd2c..9df765b 100755
    --- a/LIFEOS/TOOLS/MergeSettings.ts
    +++ b/LIFEOS/TOOLS/MergeSettings.ts
    @@ -90,6 +90,15 @@ function cloneJsonValue(value: any): any {
       return value;
     }
     
    +/** JSON with object keys sorted at every level, so key order never makes two equal values differ. */
    +export function canonicalJson(value: any): string {
    +  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(",")}]`;
    +  if (isObjectRecord(value)) {
    +    return `{${Object.keys(value).sort().map((k) => `${JSON.stringify(k)}:${canonicalJson(value[k])}`).join(",")}}`;
    +  }
    +  return JSON.stringify(value);
    +}
    +
     export function applyArrayMerge(systemValue: any, userValue: AppendAnnotation): any[] {
       if (systemValue === undefined) {
         return cloneJsonValue(userValue.values);
    @@ -97,9 +106,10 @@ export function applyArrayMerge(systemValue: any, userValue: AppendAnnotation):
     
       if (Array.isArray(systemValue)) {
         // An appended value the system layer already carries adds nothing; keep only the first copy.
    -    const seen = new Set(systemValue.map((item) => JSON.stringify(item)));
    +    // Canonical JSON (sorted keys): the same entry written with another key order is still a duplicate (#2820).
    +    const seen = new Set(systemValue.map((item) => canonicalJson(item)));
         const added = userValue.values.filter((item) => {
    -      const key = JSON.stringify(item);
    +      const key = canonicalJson(item);
           if (seen.has(key)) return false;
           seen.add(key);
           return true;
    diff --git a/LIFEOS/TOOLS/SettingsBackport.ts b/LIFEOS/TOOLS/SettingsBackport.ts
    index 279c081..bb7b401 100755
    --- a/LIFEOS/TOOLS/SettingsBackport.ts
    +++ b/LIFEOS/TOOLS/SettingsBackport.ts
    @@ -21,9 +21,12 @@
      * here and flow through the MergeSettings run that follows. No snapshot on
      * disk → skip cleanly (never guess).
      *
    - * Key DELETIONS backport too, by removing the key from the overlay. This is the
    - * only representation the merge format has for "absent" — there is no delete
    - * annotation — so it works exactly when the overlay is what supplied the key.
    + * Key DELETIONS backport too, by removing the key from the overlay. The merge
    + * format does have a delete annotation, { "__merge": "remove" }, but a deletion
    + * is backported only by removing the overlay entry, so it works exactly when the
    + * overlay is what supplied the key. A value written under a parent the overlay
    + * removes expands that annotation into one remove per system key, so the other
    + * system keys stay removed (#2820).
      * A key still supplied by settings.system.json survives the merge regardless;
      * that case is un-backportable, the overlay entry is restored untouched, and
      * the tool warns per key (fix it by hand in settings.system.json). Deleting the
    @@ -49,7 +52,7 @@
     import { existsSync } from "node:fs";
     import path from "node:path";
     import os from "node:os";
    -import { mergeSettings, deepEqual, parseJsonFileOrThrow, MERGE_SNAPSHOT_PATH, isCarriedForward } from "./MergeSettings";
    +import { mergeSettings, deepEqual, parseJsonFileOrThrow, MERGE_SNAPSHOT_PATH, isCarriedForward, isRemoveAnnotation } from "./MergeSettings";
     import { atomicWriteText } from "../PULSE/lib/atomic-write";
     import { getClaudeDir } from "./Paths"; // public issue #1974 @sabo961, PR #1918 @PigLardLord
     
    @@ -84,7 +87,13 @@ export function collectDrift(expected: any, actual: any, segments: string[] = []
         for (const key of Object.keys(actual)) {
           const childSegments = [...segments, key];
           if (!Object.prototype.hasOwnProperty.call(expected, key)) {
    -        drift.push({ kind: "changed", segments: childSegments, value: actual[key] });
    +        // A new non-empty object drifts per leaf: backporting it whole would pin it, and a sibling the
    +        // system layer adds under the same parent would fail verification forever (#2820 §3).
    +        if (isObjectRecord(actual[key]) && Object.keys(actual[key]).length > 0) {
    +          drift.push(...collectDrift({}, actual[key], childSegments));
    +        } else {
    +          drift.push({ kind: "changed", segments: childSegments, value: actual[key] });
    +        }
           } else {
             drift.push(...collectDrift(expected[key], actual[key], childSegments));
           }
    @@ -149,10 +158,16 @@ export function planArrayBackport<D extends { segments: string[]; before: any[];
     }
     
     /** Deep-set a value into an object, creating intermediate objects as needed. */
    -export function deepSet(target: Record<string, any>, segments: string[], value: any): void {
    +export function deepSet(target: Record<string, any>, segments: string[], value: any, system?: any): void {
       let cursor = target;
       for (let i = 0; i < segments.length - 1; i += 1) {
         const key = segments[i];
    +    // Writing under a removed parent: the remove becomes one remove per system key there, so the
    +    // written key lands and every other system key stays removed (#2820).
    +    if (isRemoveAnnotation(cursor[key])) {
    +      const base = getAtPath(system, segments.slice(0, i + 1));
    +      cursor[key] = Object.fromEntries(Object.keys(isObjectRecord(base) ? base : {}).map((k) => [k, { __merge: "remove" }]));
    +    }
         if (!isObjectRecord(cursor[key])) {
           cursor[key] = {};
         }
    @@ -289,10 +304,10 @@ async function run(dryRun: boolean): Promise<number> {
       }
     
       for (const d of changes) {
    -    deepSet(user, d.segments, d.value);
    +    deepSet(user, d.segments, d.value, system);
       }
       for (const p of arrayPlans) {
    -    deepSet(user, p.segments, p.appendable ? { __merge: "append", values: p.appended } : p.after);
    +    deepSet(user, p.segments, p.appendable ? { __merge: "append", values: p.appended } : p.after, system);
       }
     
       // A deletion is expressed by removing the overlay entry — the merge format has

    Verified after fix

    Same suite on the patched tools: 16 pass, 0 fail. On a real install's settings files, mergeSettingsPreserving and collectDrift give byte-identical results before and after the patch. A /statusline off round-trip passes 2/2 both before and after.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions