Repository navigation
Description
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.jsoncarrySessionStart,PreToolUseandStop; - change one
PreToolUsehook'stimeoutin 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.jsonbefore it verifies, and does not roll back a failed non-deletion change. permissionsarrays 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 --helpruns a real backport, and writes the overlay if there is drift. Only--dry-runis recognised.
A possible fix.
- SettingsBackport drops drift under any
INSTALLER_OWNED_KEYSentry that neither layer defines. The merge already carries those keys from live, so a hand edit survives without a backport. - MergeSettings
--outputrefuses to write while the merge would remove any hook registration that the existingsettings.jsonhas, unless--allow-hook-dropis passed. A registration is counted with multiplicity and keyed by event, matcher, and the hook record apart fromtimeout. Keying onevent + commandalone misses a removed matcher group whose command still runs under another matcher. This catches § 1 whatever the cause, including a futuresettings.system.jsonthat starts shippinghooks. - 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.
- 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
gjaworski86 commentedon Nov 16, 2026
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:
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 writeshooks.<event>into the overlay as an append; from then onmergeSettingsPreservingstops 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
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.460ZRed looks like: 9 fail
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 ownhooks. 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 holdshooksmust have that key removed by hand.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.915ZEnvironment
gjaworski86 commentedon Nov 16, 2026
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
env: {X}(orpermissions: {allow: [...]}) while the system layer addsenv.Y(orpermissions.deny).collectDriftreports 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.env: {"__merge":"remove"}in the overlay, a backportedenv.Xis 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 offis a shipped writer of this annotation.applyArrayMergededups byJSON.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
mergeSettingssupports{"__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.{env:{Y}}{}{}{env:{X}}{Y,X}{permissions:{deny:[r]}}{}{}{permissions:{allow:[a,b]}}{env:{X:old,Z}}{env:remove}{env:{X:old}}or{}{env:{X:new}}{X:new}{hooks:{PreToolUse:[g]}}[g′](g, keys reordered){hooks:{PreToolUse:[g]}}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 getsenv.Xand the systemenv.Ystill 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).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,
mergeSettingsreading 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 ownsmergeand its inverse, with a property test thatmerge(system, backport(snapshot, live, overlay))reproduces live, would close the class.Diff
Verified after fix
Same suite on the patched tools:
16 pass, 0 fail. On a real install's settings files,mergeSettingsPreservingandcollectDriftgive byte-identical results before and after the patch. A/statusline offround-trip passes 2/2 both before and after.