@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.7 → 0.1.9

package/packages/agent-hooks/src/deploy/json-merge.ts

@@ -12,28 +12,317 @@
  * event order — this is what makes a deploy into an empty repo reproduce
  * this repo's own committed `.claude/settings.json` / `.codex/hooks.json` /
  * `.cursor/hooks.json` byte-for-byte (json-merge.test.ts / deploy.test.ts).
+ *
+ * Merge contract, ownership mechanism corrected TWICE by independent
+ * reviews the same day (2026-09-29):
+ *
+ * Review 1 found: identifying "still-desired" entries by stripping their
+ * `--host=<surface>` suffix and comparing the remainder ALSO matched a
+ * user's own lookalike entry (same command text, different matcher, never
+ * written by adl) and deleted it.
+ *
+ * Review 2 found the FIRST fix (pure array-index tracking) had two of its
+ * own bugs: (a) CRITICAL — every repo enrolled before that fix has a lock
+ * with no recorded indices at all, so the very first deploy after
+ * upgrading read "owns nothing" and duplicated every adl hook; (b) HIGH —
+ * position tracking broke the moment a user inserted or removed an entry
+ * BEFORE adl's own block (everything downstream shifted, capturing/
+ * overwriting the user's entry and duplicating adl's), and could not
+ * express "a user hook appended INSIDE an adl-owned group's own `hooks`
+ * array" — that got silently deleted instead of kept.
+ *
+ * Ownership is now CONTENT-ADDRESSED (`isOwnedHook`, below): an existing
+ * hook is adl's iff EITHER (a) its own hash (type+command+statusMessage+
+ * timeper — never the group's `matcher`, which is a group-level field)
+ * matches a hash THIS package's lock recorded writing, ANYWHERE in the
+ * array (survives reordering/insertion/deletion elsewhere — closes (b)),
+ * or (b) it sits at the GROUP INDEX a recorded hook was written at and its
+ * `command` still matches (a tampered field OTHER than command, restored
+ * in place — the position signal is now a NARROW fallback, not the whole
+ * mechanism). A GROUP with a mix of adl and user hooks is SPLIT
+ * (`splitGroupHooks`): the user's hooks survive in their own group at that
+ * position; adl's slot is restored separately, right there — never
+ * deleted, never duplicated.
+ *
+ * A lock recording no hashes at all (`ownedEntries` absent — every repo
+ * enrolled before this fix; closes (a)) falls back, for exactly this one
+ * transitional deploy, to command-anywhere matching against the lock's OLD
+ * `ownedCommands` — the only signal that data has — via the SAME
+ * `legacyOwnedCommands` channel the pre-agent-hooks engine's own takeover
+ * already used (both are "we have no better proof than an exact command
+ * string" signals). This run then persists real content hashes
+ * (`ownedEntries`), so every later deploy uses the full contract.
+ *
+ * THIRD independent review (2026-09-30) found the fallback ITSELF still
+ * leaked through raw array position, in two ways:
+ *   2E — the hash omitted the group's `matcher` entirely, so a byte-
+ *        identical copy of an adl hook object pasted into a DIFFERENT
+ *        matcher's group still hash-matched and got captured.
+ *   2G/2F/H — the position-based fallback compared a candidate's RAW
+ *        array index to `recorded`'s ORDINAL index. A user group that
+ *        merely happened to sit at the same raw index adl's entry once
+ *        occupied (whether by coincidence, 2G, or because an unrelated
+ *        earlier insert shifted adl's own tampered entry away from it,
+ *        2F/H) was captured or missed by that coincidence alone.
+ *
+ * Both are closed by dropping index-based reasoning entirely:
+ *   - `hashHook`/`hashCursorEntry` now include `matcher` AND `event` in
+ *     the digest, so a lookalike with a different matcher simply never
+ *     hash-matches, full stop (closes 2E).
+ *   - The fallback is now a PAIR rule, not a position rule: a non-hash-
+ *     matching candidate heals in place iff its (command, matcher) pair
+ *     is one adl recorded for this event AND no OTHER entry ANYWHERE in
+ *     the array already hash-verifies that exact pair. A verified copy
+ *     existing elsewhere means THIS candidate is the user's — a
+ *     lookalike or a genuine accidental duplicate — never healed (closes
+ *     2G and 2F/H at once; a raw index is never consulted).
+ *
+ * FOURTH independent review (2026-09-30, round 5) found two more real
+ * bugs, both in how that pair rule counted things PER COMMAND instead of
+ * per (command, matcher) pair, and in what it did when MULTIPLE
+ * unverified candidates shared one pair:
+ *
+ *   1. MED — `duplicateCommands` counted every existing occurrence of a
+ *      RECORDED COMMAND, ignoring matcher entirely. A legit user hook
+ *      that reuses one of adl's command STRINGS under a genuinely
+ *      DIFFERENT matcher (already proven safe from capture by 2E/2G) got
+ *      counted as "the same command appears twice" and flagged by doctor
+ *      forever — deploy has nothing to change (the merge is correctly a
+ *      no-op), so the error could never clear.
+ *   2. MED — the old fallback healed whichever unverified candidate for
+ *      a pair it happened to encounter FIRST in iteration order. When a
+ *      user's OWN customized copy of a pair coexisted with adl's real
+ *      entry ALSO tampered (both unverified), the fallback picked one
+ *      arbitrarily: either the user's copy got silently overwritten with
+ *      no explanation (item 2, case a: adl's real entry was simply gone,
+ *      only the user's customized one remained — a single unverified
+ *      candidate, which is a legitimate heal, but it was never NAMED in
+ *      any output), or — worse — the user's copy got treated as "the
+ *      heal target" while adl's own genuinely-tampered entry was left
+ *      standing as "the user's", running the hook twice forever with no
+ *      error (item 2, case a2: TWO unverified candidates for one pair).
+ *
+ * DECISION (Tarun, 2026-09-30):
+ *   - `duplicateCommands` (doctor's own flag) now keys on the exact
+ *     (command, matcher) PAIR, never command alone: it fires only when
+ *     more than one entry hash-verifies for the same pair, or an
+ *     unverified entry shares a pair with a verified one. A different
+ *     matcher is never counted together with anything, full stop.
+ *   - Exactly one unverified candidate for a pair, and zero verified
+ *     ones -> heals in place (unchanged contract: a customized variant
+ *     under the SAME matcher is adl's and gets restored) but the heal is
+ *     now NAMED on the result (`restored`) so deploy, doctor's preview,
+ *     and `adl install` can all say so explicitly.
+ *   - MORE than one unverified candidate sharing a pair, with zero
+ *     verified -> genuinely ambiguous: healing either one is a guess.
+ *     Neither heals. The WHOLE EVENT for that surface is left exactly as
+ *     found (no group split, no restore, nothing consumed from
+ *     `desired`) and reported as a conflict (`ambiguousConflicts`) —
+ *     deploy.ts turns this into a real `HookConflict`, non-zero exit.
  */
-import type { RenderedCursorEntry, RenderedGroup } from './render.ts'
+import { createHash } from 'node:crypto'
+import type { RenderedCursorEntry, RenderedGroup, RenderedHookCommand } from './render.ts'
 
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === 'object' && value !== null && !Array.isArray(value)
 }
 
+/** sha256 of a hook's OWN fields PLUS its group's `matcher` and the event name (2026-09-30, finding 2E: matcher used to be omitted as "a group-level field", which let a byte-identical copy pasted into a different matcher's group hash-match anyway). */
+function hashHook(hook: { readonly type: string; readonly command: string; readonly statusMessage: string; readonly timeout: number }, matcher: string | undefined, event: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ event, matcher: matcher ?? null, type: hook.type, command: hook.command, statusMessage: hook.statusMessage, timeout: hook.timeout }))
+    .digest('hex')
+}
+
+/** sha256 of a cursor entry's own fields, INCLUDING `matcher` (entry-level here) and the event name — same finding 2E rationale as `hashHook`. */
+function hashCursorEntry(entry: { readonly command: string; readonly statusMessage: string; readonly timeout: number; readonly matcher?: string }, event: string): string {
+  return createHash('sha256')
+    .update(JSON.stringify({ event, command: entry.command, statusMessage: entry.statusMessage, timeout: entry.timeout, matcher: entry.matcher ?? null }))
+    .digest('hex')
+}
+
+export interface OwnedEntry {
+  readonly hash: string
+  readonly command: string
+  /** The matcher this entry was recorded under (group-level for claude/codex, entry-level for cursor) — `undefined` when adl rendered no matcher. Needed by the PAIR fallback (2G/2F/H): "no verified hash exists for this (command, matcher)" cannot be answered from `command` alone. */
+  readonly matcher?: string
+}
+
+function pairKey(command: string, matcher: string | undefined): string {
+  return `${command}\u0000${matcher ?? ''}`
+}
+
+/** Builds an `OwnedEntry`, omitting `matcher` entirely when undefined (this package's `exactOptionalPropertyTypes` refuses an explicit `matcher: undefined`). */
+function makeOwnedEntry(hash: string, command: string, matcher: string | undefined): OwnedEntry {
+  return matcher !== undefined ? { hash, command, matcher } : { hash, command }
+}
+
+function isRecordHookCommand(value: unknown): value is RenderedHookCommand {
+  return isRecord(value) && typeof value.type === 'string' && typeof value.command === 'string' && typeof value.statusMessage === 'string' && typeof value.timeout === 'number'
+}
+
+/** One RECORDED pair's decoded identity, for building conflict/restore messages without re-parsing `pairKey`'s own encoding. */
+interface PairIdentity {
+  readonly command: string
+  readonly matcher: string | undefined
+}
+
+/**
+ * Per-pair classification for one event, computed in a first pass over
+ * EVERY existing hook-like entry before any restore/split decision is
+ * made (2026-09-30, round 5 — see this file's header for the full
+ * history). Only pairs adl actually RECORDED are ever classified; a pair
+ * with no recorded entry at all is simply not adl's concern here.
+ *
+ *   - `healablePairs`: zero verified copies, EXACTLY one unverified
+ *     candidate — heals in place, named in `restored`.
+ *   - `ambiguousPairs`: zero verified copies, MORE than one unverified
+ *     candidate — genuinely ambiguous, healing either is a guess. Ownership
+ *     of NEITHER is claimed; the whole event freezes (see the merge
+ *     functions below) and this pair is reported as a conflict.
+ *   - `duplicateCommands`: at least one verified copy, AND (more than one
+ *     verified copy, OR at least one unverified copy sharing the SAME
+ *     pair) — a real duplicate sitting alongside a provably-intact
+ *     original. Reported for doctor, never affects the merge itself (the
+ *     verified copy stays owned via its hash regardless; the extra
+ *     copy(ies) are simply the user's, kept as-is).
+ */
+interface PairClassification {
+  readonly healablePairs: ReadonlySet<string>
+  readonly ambiguousPairs: ReadonlySet<string>
+  readonly ambiguousIdentities: readonly PairIdentity[]
+  readonly duplicateCommands: readonly string[]
+}
+
+function classifyPairs(
+  hookLikes: readonly { readonly command: string; readonly hash: string; readonly matcher: string | undefined }[],
+  hashSet: ReadonlySet<string>,
+  recordedPairs: ReadonlyMap<string, PairIdentity>,
+): PairClassification {
+  const verifiedCount = new Map<string, number>()
+  const unverifiedCount = new Map<string, number>()
+  for (const { command, hash, matcher } of hookLikes) {
+    const key = pairKey(command, matcher)
+    if (!recordedPairs.has(key)) continue // only adl-recorded pairs matter for heal/ambiguity/duplicate reasoning
+    if (hashSet.has(hash)) verifiedCount.set(key, (verifiedCount.get(key) ?? 0) + 1)
+    else unverifiedCount.set(key, (unverifiedCount.get(key) ?? 0) + 1)
+  }
+
+  const healablePairs = new Set<string>()
+  const ambiguousPairs = new Set<string>()
+  const ambiguousIdentities: PairIdentity[] = []
+  const duplicateCommandSet = new Set<string>()
+  for (const [key, identity] of recordedPairs) {
+    const v = verifiedCount.get(key) ?? 0
+    const u = unverifiedCount.get(key) ?? 0
+    if (v === 0 && u > 1) {
+      ambiguousPairs.add(key)
+      ambiguousIdentities.push(identity)
+    } else if (v === 0 && u === 1) {
+      healablePairs.add(key)
+    } else if (v >= 1 && (v > 1 || u >= 1)) {
+      duplicateCommandSet.add(identity.command)
+    }
+  }
+  return { healablePairs, ambiguousPairs, ambiguousIdentities, duplicateCommands: [...duplicateCommandSet].sort() }
+}
+
+interface PairContext {
+  readonly hashSet: ReadonlySet<string>
+  readonly healablePairs: ReadonlySet<string>
+  readonly legacyCommandsAnywhere: ReadonlySet<string>
+}
+
+/** One healed hook's identity, for the `restored` report ("restored adl hook <event>/<matcher>/<command> — local changes to it were replaced"). */
+export interface RestoredHook {
+  readonly command: string
+  readonly matcher?: string
+}
+
+/**
+ * Content-addressed ownership check for one existing hook/entry. The
+ * fallback is a PAIR rule, never a position/index rule (2026-09-30,
+ * findings 2G/2F/H): a non-hash-matching candidate heals in place iff
+ * its (command, matcher) pair is in `healablePairs` — which
+ * `classifyPairs` (above) has ALREADY confirmed has zero verified
+ * copies and EXACTLY one unverified candidate, so there is no ambiguity
+ * left to resolve here.
+ */
+function isOwnedHook(
+  candidate: { readonly command: string },
+  candidateHash: string,
+  matcher: string | undefined,
+  ctx: PairContext,
+): boolean {
+  if (ctx.hashSet.has(candidateHash)) return true
+  if (ctx.legacyCommandsAnywhere.has(candidate.command)) return true
+  return ctx.healablePairs.has(pairKey(candidate.command, matcher))
+}
+
+/** Splits an existing group's own `hooks` array into adl's (owned) and the user's (everything else), preserving the group's `matcher`. Collects any hook healed via the PAIR fallback (not hash, not legacy) into `restored`. */
+function splitGroupHooks(
+  hooks: readonly unknown[],
+  matcher: string | undefined,
+  event: string,
+  ctx: PairContext,
+  restored: RestoredHook[],
+): { readonly ownedCount: number; readonly userHooks: readonly unknown[] } {
+  let ownedCount = 0
+  const userHooks: unknown[] = []
+  for (const hook of hooks) {
+    if (!isRecordHookCommand(hook)) {
+      userHooks.push(hook)
+      continue
+    }
+    const hash = hashHook(hook, matcher, event)
+    if (isOwnedHook(hook, hash, matcher, ctx)) {
+      ownedCount += 1
+      if (!ctx.hashSet.has(hash) && !ctx.legacyCommandsAnywhere.has(hook.command)) {
+        restored.push(matcher !== undefined ? { command: hook.command, matcher } : { command: hook.command })
+      }
+    } else {
+      userHooks.push(hook)
+    }
+  }
+  return { ownedCount, userHooks }
+}
+
+/** One event's ambiguous-pair conflict, for `JsonHooksMergeResult.ambiguousConflicts`/`CursorHooksMergeResult.ambiguousConflicts`. */
+export interface AmbiguousPairConflict {
+  readonly event: string
+  readonly command: string
+  readonly matcher?: string
+}
+
+/** Builds an `AmbiguousPairConflict`, omitting `matcher` entirely when undefined (same `exactOptionalPropertyTypes` concern as `makeOwnedEntry`). */
+function makeAmbiguousConflict(event: string, identity: PairIdentity): AmbiguousPairConflict {
+  return identity.matcher !== undefined ? { event, command: identity.command, matcher: identity.matcher } : { event, command: identity.command }
+}
+
 export interface JsonHooksMergeResult {
   /** The complete object to JSON.stringify and write. */
   readonly fileContent: Record<string, unknown>
-  /** New lock contents: surface event name -> the command strings this deploy now owns there. */
+  /** New lock contents: surface event name -> the command strings this deploy now owns there (informational — list.ts). */
   readonly ownedCommands: Readonly<Record<string, readonly string[]>>
+  /** New lock contents: surface event name -> this deploy's own written hooks, content-addressed — the actual ownership record the next run reads back. */
+  readonly ownedEntries: Readonly<Record<string, readonly OwnedEntry[]>>
   readonly changed: boolean
   /** Events whose array actually differs from what was already on disk — doctor.ts's per-entry reasons. */
   readonly changedEvents: readonly string[]
+  /** Event -> adl-owned commands with a genuine duplicate (2026-09-30, round 5, finding 1: pair-scoped — a different matcher is never counted). Set even when the merge is otherwise a structural no-op, since the duplicate can sit in an already-unchanged file. doctor.ts turns this into its own dedicated issue. */
+  readonly duplicateCommands: Readonly<Record<string, readonly string[]>>
+  /** Hooks healed via the PAIR fallback this run (not by hash, not by the legacy channel) — named so deploy/doctor/`adl install` can report "restored adl hook <event>/<matcher>/<command>" (2026-09-30, round 5, finding 2). */
+  readonly restored: readonly (RestoredHook & { readonly event: string })[]
+  /** Events frozen this run because more than one unverified candidate shared a recorded pair — genuinely ambiguous, neither healed, the event's array left exactly as found (2026-09-30, round 5, finding 2). deploy.ts turns each into a real conflict. */
+  readonly ambiguousConflicts: readonly AmbiguousPairConflict[]
 }
 
 /** For claude-settings / codex-hooks: `{hooks: {Event: [{matcher?, hooks: [...]}]}}`. */
 export function mergeJsonHooksFile(
   existing: Record<string, unknown> | undefined,
   desired: ReadonlyMap<string, readonly RenderedGroup[]>,
-  previousOwned: Readonly<Record<string, readonly string[]>>,
+  recordedEntries: Readonly<Record<string, readonly OwnedEntry[]>>,
+  legacyOwnedCommands: Readonly<Record<string, readonly string[]>> = {},
 ): JsonHooksMergeResult {
   const base: Record<string, unknown> = existing ? { ...existing } : {}
   const existingHooks = isRecord(base.hooks) ? base.hooks : {}
@@ -43,21 +332,83 @@ export function mergeJsonHooksFile(
 
   const newHooks: Record<string, unknown> = {}
   const ownedCommands: Record<string, readonly string[]> = {}
+  const ownedEntries: Record<string, readonly OwnedEntry[]> = {}
   const changedEvents: string[] = []
+  const duplicateCommands: Record<string, readonly string[]> = {}
+  const restored: (RestoredHook & { readonly event: string })[] = []
+  const ambiguousConflicts: AmbiguousPairConflict[] = []
   let changed = existing === undefined
 
   for (const event of orderedEvents) {
     const existingGroups = Array.isArray(existingHooks[event]) ? (existingHooks[event] as unknown[]) : []
-    const prevOwnedSet = new Set(previousOwned[event] ?? [])
-    const keptGroups = existingGroups.filter((group) => {
-      if (!isRecord(group) || !Array.isArray(group.hooks) || group.hooks.length === 0) return true
-      return !group.hooks.every((h) => isRecord(h) && typeof h.command === 'string' && prevOwnedSet.has(h.command))
-    })
+    const recorded = recordedEntries[event] ?? []
+    const hashSet = new Set(recorded.map((r) => r.hash))
+    const recordedPairs = new Map(recorded.map((r) => [pairKey(r.command, r.matcher), { command: r.command, matcher: r.matcher }] as const))
+    const legacyCommandsAnywhere = new Set(legacyOwnedCommands[event] ?? [])
     const desiredGroups = desired.get(event) ?? []
+
+    // Pass 1: classify every existing hook-like by (command, matcher)
+    // pair BEFORE any restore/split decision — the fallback rule for one
+    // entry depends on whether ANOTHER entry (anywhere) already proves
+    // the real one is intact, or shares its own ambiguity.
+    const existingHookLikes = existingGroups.flatMap((group) =>
+      isRecord(group) && Array.isArray(group.hooks)
+        ? group.hooks.filter(isRecordHookCommand).map((hook) => ({ command: hook.command, hash: hashHook(hook, group.matcher as string | undefined, event), matcher: group.matcher as string | undefined }))
+        : [],
+    )
+    const { healablePairs, ambiguousPairs, ambiguousIdentities, duplicateCommands: dupes } = classifyPairs(existingHookLikes, hashSet, recordedPairs)
+    if (dupes.length > 0) duplicateCommands[event] = dupes
+
+    if (ambiguousPairs.size > 0) {
+      // Genuinely ambiguous: more than one unverified candidate shares a
+      // pair adl recorded. Heal neither — freeze this WHOLE event exactly
+      // as found, carry the lock's own record forward unchanged (so a
+      // later run re-evaluates the same state, never silently forgetting
+      // ownership), and report it as a conflict.
+      for (const identity of ambiguousIdentities) ambiguousConflicts.push(makeAmbiguousConflict(event, identity))
+      if (recorded.length > 0) {
+        ownedCommands[event] = recorded.map((r) => r.command)
+        ownedEntries[event] = recorded
+      }
+      if (existingGroups.length > 0) newHooks[event] = existingGroups
+      continue // no consumeDesired at all -- nothing in this event changes this run
+    }
+
+    const ctx: PairContext = { hashSet, healablePairs, legacyCommandsAnywhere }
+    const restoredThisEvent: RestoredHook[] = []
+
+    const merged: unknown[] = []
+    let desiredCursor = 0
+    const consumeDesired = (): void => {
+      if (desiredCursor < desiredGroups.length) {
+        merged.push(desiredGroups[desiredCursor])
+        desiredCursor += 1
+      }
+    }
+
+    for (const group of existingGroups) {
+      if (!isRecord(group) || !Array.isArray(group.hooks) || group.hooks.length === 0) {
+        merged.push(group)
+        continue
+      }
+      const { ownedCount, userHooks } = splitGroupHooks(group.hooks, group.matcher as string | undefined, event, ctx, restoredThisEvent)
+      if (ownedCount === 0) {
+        merged.push(group) // fully the user's -- untouched, no desired slot consumed
+        continue
+      }
+      if (userHooks.length > 0) {
+        // split: the user's remainder survives in its own group, right here.
+        merged.push(group.matcher !== undefined ? { matcher: group.matcher, hooks: userHooks } : { hooks: userHooks })
+      }
+      consumeDesired() // restore/replace adl's slot at this position
+    }
+    while (desiredCursor < desiredGroups.length) consumeDesired()
+    for (const hook of restoredThisEvent) restored.push({ ...hook, event })
+
     if (desiredGroups.length > 0) {
       ownedCommands[event] = desiredGroups.flatMap((g) => g.hooks.map((h) => h.command))
+      ownedEntries[event] = desiredGroups.flatMap((g) => g.hooks.map((h) => makeOwnedEntry(hashHook(h, g.matcher, event), h.command, g.matcher)))
     }
-    const merged = [...keptGroups, ...desiredGroups]
     if (merged.length > 0) newHooks[event] = merged
     if (JSON.stringify(existingHooks[event] ?? null) !== JSON.stringify(merged.length > 0 ? merged : null)) {
       changed = true
@@ -66,23 +417,32 @@ export function mergeJsonHooksFile(
   }
 
   base.hooks = newHooks
-  return { fileContent: base, ownedCommands, changed, changedEvents }
+  return { fileContent: base, ownedCommands, ownedEntries, changed, changedEvents, duplicateCommands, restored, ambiguousConflicts }
 }
 
 export interface CursorHooksMergeResult {
   readonly fileContent: Record<string, unknown>
-  /** New lock contents: Cursor's own event name -> the command strings this deploy now owns there. */
+  /** New lock contents: Cursor's own event name -> the command strings this deploy now owns there (informational — list.ts). */
   readonly ownedCommands: Readonly<Record<string, readonly string[]>>
+  /** New lock contents: Cursor's own event name -> this deploy's own written entries, content-addressed. */
+  readonly ownedEntries: Readonly<Record<string, readonly OwnedEntry[]>>
   readonly changed: boolean
   /** Events whose array actually differs from what was already on disk — doctor.ts's per-entry reasons. */
   readonly changedEvents: readonly string[]
+  /** Event -> adl-owned commands with a genuine duplicate — see `JsonHooksMergeResult`'s own field for the full rationale. */
+  readonly duplicateCommands: Readonly<Record<string, readonly string[]>>
+  /** Entries healed via the PAIR fallback this run — see `JsonHooksMergeResult`'s own field for the full rationale. */
+  readonly restored: readonly (RestoredHook & { readonly event: string })[]
+  /** Events frozen this run because of an ambiguous pair — see `JsonHooksMergeResult`'s own field for the full rationale. */
+  readonly ambiguousConflicts: readonly AmbiguousPairConflict[]
 }
 
-/** For cursor-hooks-v1: `{version: 1, hooks: {event: [{command, statusMessage, timeout, matcher?}]}}`. */
+/** For cursor-hooks-v1: `{version: 1, hooks: {event: [{command, statusMessage, timeout, matcher?}]}}`. No groups here — each entry is classified (and, unlike claude/codex, never split) on its own. */
 export function mergeCursorHooksFile(
   existing: Record<string, unknown> | undefined,
   desired: ReadonlyMap<string, readonly RenderedCursorEntry[]>,
-  previousOwned: Readonly<Record<string, readonly string[]>>,
+  recordedEntries: Readonly<Record<string, readonly OwnedEntry[]>>,
+  legacyOwnedCommands: Readonly<Record<string, readonly string[]>> = {},
 ): CursorHooksMergeResult {
   const base: Record<string, unknown> = existing ? { ...existing } : { version: 1 }
   if (base.version === undefined) base.version = 1
@@ -93,16 +453,68 @@ export function mergeCursorHooksFile(
 
   const newHooks: Record<string, unknown> = {}
   const ownedCommands: Record<string, readonly string[]> = {}
+  const ownedEntries: Record<string, readonly OwnedEntry[]> = {}
   const changedEvents: string[] = []
+  const duplicateCommands: Record<string, readonly string[]> = {}
+  const restored: (RestoredHook & { readonly event: string })[] = []
+  const ambiguousConflicts: AmbiguousPairConflict[] = []
   let changed = existing === undefined
 
   for (const event of orderedEvents) {
     const existingEntries = Array.isArray(existingHooks[event]) ? (existingHooks[event] as unknown[]) : []
-    const prevOwnedSet = new Set(previousOwned[event] ?? [])
-    const keptEntries = existingEntries.filter((entry) => !(isRecord(entry) && typeof entry.command === 'string' && prevOwnedSet.has(entry.command)))
+    const recorded = recordedEntries[event] ?? []
+    const hashSet = new Set(recorded.map((r) => r.hash))
+    const recordedPairs = new Map(recorded.map((r) => [pairKey(r.command, r.matcher), { command: r.command, matcher: r.matcher }] as const))
+    const legacyCommandsAnywhere = new Set(legacyOwnedCommands[event] ?? [])
     const desiredEntries = desired.get(event) ?? []
-    if (desiredEntries.length > 0) ownedCommands[event] = desiredEntries.map((e) => e.command)
-    const merged = [...keptEntries, ...desiredEntries]
+
+    const existingHookLikes = existingEntries
+      .filter((entry): entry is Record<string, unknown> => isRecord(entry) && typeof entry.command === 'string')
+      .map((entry) => ({ command: entry.command as string, hash: hashCursorEntry(entry as never, event), matcher: entry.matcher as string | undefined }))
+    const { healablePairs, ambiguousPairs, ambiguousIdentities, duplicateCommands: dupes } = classifyPairs(existingHookLikes, hashSet, recordedPairs)
+    if (dupes.length > 0) duplicateCommands[event] = dupes
+
+    if (ambiguousPairs.size > 0) {
+      for (const identity of ambiguousIdentities) ambiguousConflicts.push(makeAmbiguousConflict(event, identity))
+      if (recorded.length > 0) {
+        ownedCommands[event] = recorded.map((r) => r.command)
+        ownedEntries[event] = recorded
+      }
+      if (existingEntries.length > 0) newHooks[event] = existingEntries
+      continue
+    }
+
+    const merged: unknown[] = []
+    let desiredCursor = 0
+    for (const entry of existingEntries) {
+      if (!isRecord(entry) || typeof entry.command !== 'string') {
+        merged.push(entry)
+        continue
+      }
+      const matcher = entry.matcher as string | undefined
+      const hash = hashCursorEntry(entry as never, event)
+      const isOwned = isOwnedHook(entry as { command: string }, hash, matcher, { hashSet, healablePairs, legacyCommandsAnywhere })
+      if (!isOwned) {
+        merged.push(entry)
+        continue
+      }
+      if (!hashSet.has(hash) && !legacyCommandsAnywhere.has(entry.command)) {
+        restored.push(matcher !== undefined ? { command: entry.command, matcher, event } : { command: entry.command, event })
+      }
+      if (desiredCursor < desiredEntries.length) {
+        merged.push(desiredEntries[desiredCursor])
+        desiredCursor += 1
+      }
+    }
+    while (desiredCursor < desiredEntries.length) {
+      merged.push(desiredEntries[desiredCursor])
+      desiredCursor += 1
+    }
+
+    if (desiredEntries.length > 0) {
+      ownedCommands[event] = desiredEntries.map((e) => e.command)
+      ownedEntries[event] = desiredEntries.map((e) => makeOwnedEntry(hashCursorEntry(e, event), e.command, e.matcher))
+    }
     if (merged.length > 0) newHooks[event] = merged
     if (JSON.stringify(existingHooks[event] ?? null) !== JSON.stringify(merged.length > 0 ? merged : null)) {
       changed = true
@@ -111,5 +523,5 @@ export function mergeCursorHooksFile(
   }
 
   base.hooks = newHooks
-  return { fileContent: base, ownedCommands, changed, changedEvents }
+  return { fileContent: base, ownedCommands, ownedEntries, changed, changedEvents, duplicateCommands, restored, ambiguousConflicts }
 }

package/packages/agent-hooks/src/deploy/lock.ts

@@ -17,10 +17,41 @@ import { dirname, join } from 'node:path'
 
 export const LOCK_RELATIVE_PATH = '.agents/agent-hooks.lock.json'
 
+/**
+ * One adl-written hook's content-addressed identity: `hash` is sha256 of
+ * its OWN fields PLUS its `matcher` and event name (2026-09-30, finding
+ * 2E — matcher used to be left out as "a group-level field", which let a
+ * byte-identical hook object pasted into a DIFFERENT matcher's group
+ * still hash-match); `command` and `matcher` are kept alongside the hash
+ * for the PAIR fallback (json-merge.ts's own header has the full rule):
+ * a non-hash-matching entry heals in place only when no OTHER entry
+ * anywhere already hash-verifies this exact (command, matcher) pair —
+ * never by array position/index, which the second independent review
+ * already ruled unreliable.
+ */
+export interface OwnedHookEntry {
+  readonly hash: string
+  readonly command: string
+  readonly matcher?: string
+}
+
 export interface JsonHooksLockEntry {
   readonly format: 'claude-settings' | 'codex-hooks' | 'cursor-hooks-v1'
-  /** Surface event name -> the exact command strings (with --host) this deploy wrote into that event's array. */
+  /** Surface event name -> the exact command strings (with --host) this deploy wrote into that event's array — informational only (list.ts); ownership itself is `ownedEntries`, below. */
   readonly ownedCommands: Readonly<Record<string, readonly string[]>>
+  /**
+   * Surface event name -> this deploy's own written hooks, content-
+   * addressed (second independent review, 2026-09-29: the FIRST fix here,
+   * pure array-index tracking, broke the moment a user inserted or
+   * removed an entry before adl's own block, and could not express
+   * "split a group" when a user hook was appended inside one — see
+   * json-merge.ts's header for the corrected rule). Absent on a lock
+   * written before EITHER ownership fix existed (every repo enrolled
+   * before this one) — every reader treats that as "derive ownership
+   * once from `ownedCommands` by exact command match, then persist real
+   * entries here," never as malformed.
+   */
+  readonly ownedEntries?: Readonly<Record<string, readonly OwnedHookEntry[]>>
 }
 
 export interface OpencodePluginLockEntry {
@@ -58,8 +89,11 @@ export function readLock(targetRepo: string): HookLock {
   return { version: 1, entries: record.entries as Record<string, HookLockEntry> }
 }
 
+/** Skips the write entirely when the serialized content is already byte-identical (independent review, 2026-09-29, finding 8: a genuine no-op run must not touch the lock file's mtime either). */
 export function writeLock(targetRepo: string, lock: HookLock): void {
   const path = lockPathFor(targetRepo)
+  const next = `${JSON.stringify(lock, null, 2)}\n`
+  if (existsSync(path) && readFileSync(path, 'utf8') === next) return
   mkdirSync(dirname(path), { recursive: true })
-  writeFileSync(path, `${JSON.stringify(lock, null, 2)}\n`)
+  writeFileSync(path, next)
 }

package/packages/agent-hooks/src/lean-ctx/env.ts

@@ -71,6 +71,22 @@ export function resolveLeanCtxDir(root: string): string {
   return decoded.value.hooks.leanCtxDir ?? DEFAULT_LEAN_CTX_DIR
 }
 
+/**
+ * Set on EVERY `lean-ctx` child this package spawns, managed repo or not.
+ *
+ * lean-ctx 3.10.5's MCP `initialize` handler runs a startup maintenance
+ * block that calls `refresh_installed_hooks()`, re-writing raw
+ * `lean-ctx hook …` entries into the GLOBAL `~/.claude/settings.json`
+ * (upstream `rust/src/server/server_handler.rs` ~L180-209, issue #1879).
+ * `[setup] auto_inject_*` does not gate it; the only switch in that release
+ * is `LEAN_CTX_HEADLESS` (any value), checked first in that block. Measured
+ * 2026-09-30 on a real $HOME: unset → nine global hook entries re-appeared
+ * seconds after start; set → none, and the same 12 MCP tools are served.
+ * Those global hooks are what put lean-ctx's global shell allowlist in front
+ * of agents in unrelated, unmanaged folders — lean-ctx stays repo-local only.
+ */
+export const LEAN_CTX_HEADLESS_ENV: Readonly<Record<'LEAN_CTX_HEADLESS', string>> = { LEAN_CTX_HEADLESS: '1' }
+
 /**
  * Build the env for a `lean-ctx` subprocess rooted at repository `root`,
  * merged over `base` (normally `inv.env`/`process.env`) so every other
@@ -87,6 +103,7 @@ export function leanCtxEnv(
     LEAN_CTX_DATA_DIR: join(root, leanCtxDir, 'data'),
     LEAN_CTX_STATE_DIR: join(root, leanCtxDir, 'state'),
     LEAN_CTX_CACHE_DIR: join(root, leanCtxDir, 'cache'),
+    ...LEAN_CTX_HEADLESS_ENV,
   }
 }
 

package/packages/agent-hooks/src/lean-ctx/mcp.ts

@@ -37,7 +37,7 @@
 
 import { join } from 'node:path'
 import { findGitRoot, MARKER, realRootIO, type RootIO } from '../gating/root.ts'
-import { leanCtxEnvFor } from './env.ts'
+import { LEAN_CTX_HEADLESS_ENV, leanCtxEnvFor } from './env.ts'
 
 export interface LeanCtxMcpEnvResult {
   readonly env: Readonly<Record<string, string | undefined>>
@@ -111,7 +111,9 @@ export async function runLeanCtxMcp(
   const { env, note } = resolveLeanCtxMcpEnv(cwd, baseEnv, deps.io ?? realRootIO)
   if (note) writeStderr(note)
 
-  const child = spawn(['lean-ctx', 'mcp'], { cwd, env: env as Record<string, string | undefined> })
+  // Headless in an unmanaged folder too: see LEAN_CTX_HEADLESS_ENV — without
+  // it this very start re-writes lean-ctx's hooks into the global settings.
+  const child = spawn(['lean-ctx', 'mcp'], { cwd, env: { ...env, ...LEAN_CTX_HEADLESS_ENV } })
 
   const onSigint = () => {
     try {

package/packages/agent-settings/assets/lean-ctx/config.toml

@@ -1,7 +1,10 @@
+# >>> adl managed (do not edit within this block) >>>
 minimal_overhead = true
 structure_first = true
 journal_enabled = true
 auto_capture = true
+update_check_disabled = true
+# <<< adl managed <<<
 shell_allowlist_extra = [
     "pi",
     "install",

package/packages/agent-settings/assets/lean-ctx/gitignore

@@ -1,6 +1,10 @@
+# >>> adl managed (do not edit within this block) >>>
 /lean-ctx/data/
 /lean-ctx/cache/
 /lean-ctx/state/
 /lean-ctx/bin/
 /hooks/hooks.log
 /hooks/hooks-activity.log
+/lean-ctx/config/lean-ctx/workspace-trust.toml
+*.bak
+# <<< adl managed <<<