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

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

@@ -17,7 +17,7 @@
 import { existsSync, readFileSync } from 'node:fs'
 import { dirname, join } from 'node:path'
 import { mergeCursorHooksFile, mergeJsonHooksFile } from './json-merge.ts'
-import { readLock } from './lock.ts'
+import { type JsonHooksLockEntry, readLock } from './lock.ts'
 import { renderOpencodePlugin } from './opencode-template.ts'
 import {
   DEFAULT_PROFILE_PATH,
@@ -70,7 +70,14 @@ function readExistingJson(path: string): Record<string, unknown> | undefined {
 function doctorJsonSurface(surface: HookSurface, targetRepo: string, hooksDoc: CanonicalHooksDoc, lock: ReturnType<typeof readLock>): DoctorIssue[] {
   const targetAbs = join(targetRepo, surface.file)
   const exists = existsSync(targetAbs)
-  const previousOwned = lock.entries[surface.file]?.format === surface.format ? (lock.entries[surface.file] as { ownedCommands: Record<string, readonly string[]> }).ownedCommands : {}
+  const lockEntry = lock.entries[surface.file]?.format === surface.format ? (lock.entries[surface.file] as JsonHooksLockEntry) : undefined
+  // Same fallback deploy.ts itself uses: a lock with no ownedEntries at all
+  // (every repo enrolled before the content-hash fix) has no hashes to
+  // give, so its OLD ownedCommands feeds the command-anywhere channel
+  // instead -- otherwise doctor would report drift for every currently-
+  // enrolled repo's untouched content that deploy itself recognizes fine.
+  const recordedEntries = lockEntry?.ownedEntries ?? {}
+  const legacyCommandsAnywhere = lockEntry !== undefined && lockEntry.ownedEntries === undefined ? lockEntry.ownedCommands : {}
 
   let parseFailed = false
   if (exists) {
@@ -85,21 +92,64 @@ function doctorJsonSurface(surface: HookSurface, targetRepo: string, hooksDoc: C
   const existingRaw = readExistingJson(targetAbs)
   const merged =
     surface.format === 'cursor-hooks-v1'
-      ? mergeCursorHooksFile(existingRaw, renderCursorEntries(hooksDoc, surface), previousOwned)
-      : mergeJsonHooksFile(existingRaw, renderJsonHooksGroups(hooksDoc, surface), previousOwned)
+      ? mergeCursorHooksFile(existingRaw, renderCursorEntries(hooksDoc, surface), recordedEntries, legacyCommandsAnywhere)
+      : mergeJsonHooksFile(existingRaw, renderJsonHooksGroups(hooksDoc, surface), recordedEntries, legacyCommandsAnywhere)
 
   if (!exists) {
     return [{ severity: 'error', path: surface.file, reason: 'expected hook wiring has not been deployed' }]
   }
-  if (!merged.changed) return []
-  return merged.changedEvents.map((event) => ({
+  // Independent review, 2026-09-30, round 5 (finding 1, pair-scoped —
+  // never flags a same-command entry under a different matcher): a
+  // duplicated adl-owned (command, matcher) pair can sit in the file
+  // even when the merge is otherwise a structural no-op (the duplicate
+  // isn't healed into the verified original, but it also isn't
+  // restructured — nothing else changes), so this check runs
+  // UNCONDITIONALLY, never gated behind `merged.changed`.
+  const duplicateIssues: DoctorIssue[] = Object.entries(merged.duplicateCommands).flatMap(([event, commands]) =>
+    commands.map((command) => ({
+      severity: 'error' as const,
+      path: `${surface.file}#${event}`,
+      reason: `adl-owned command appears more than once (a duplicate, not a self-heal): ${command} — the hook runs twice; deploy does not remove a user's copy, so remove the extra copy by hand`,
+    })),
+  )
+  // Round 5, finding 2: more than one unverified candidate for a pair is
+  // ambiguous — deploy heals neither, so this is ALSO unconditional
+  // (never gated behind `merged.changed`, since a frozen event by
+  // definition never registers as changed).
+  const ambiguousIssues: DoctorIssue[] = merged.ambiguousConflicts.map((conflict) => ({
     severity: 'error' as const,
-    path: `${surface.file}#${event}`,
-    reason:
-      previousOwned[event] !== undefined
-        ? 'deploy-written hook entries were modified since deploy, or assets/hooks.json changed since; run deploy to update'
-        : 'expected hook wiring for this event has not been deployed',
+    path: `${surface.file}#${conflict.event}`,
+    reason: `two unverified copies of this adl-owned hook exist (ambiguous — matcher ${conflict.matcher ?? 'none'}, command "${conflict.command}"); deploy will not choose one for you, resolve by hand`,
   }))
+  if (!merged.changed) return [...duplicateIssues, ...ambiguousIssues]
+  // Round 5, finding 2: when a heal is about to happen (not just "some
+  // drift"), doctor's own PREVIEW names exactly what would be restored —
+  // "restored adl hook <event>/<matcher>/<command>" — instead of the
+  // generic "modified since deploy" wording, matching what deploy's own
+  // output and `adl install` will say.
+  const restoredByEvent = new Map(merged.restored.map((r) => [r.event, r] as const))
+  return [
+    ...duplicateIssues,
+    ...ambiguousIssues,
+    ...merged.changedEvents.map((event) => {
+      const restoredHere = restoredByEvent.get(event)
+      if (restoredHere !== undefined) {
+        return {
+          severity: 'error' as const,
+          path: `${surface.file}#${event}`,
+          reason: `restored adl hook ${event}/${restoredHere.matcher ?? '-'}/${restoredHere.command} — local changes to it were replaced; run deploy to apply`,
+        }
+      }
+      return {
+        severity: 'error' as const,
+        path: `${surface.file}#${event}`,
+        reason:
+          recordedEntries[event] !== undefined || legacyCommandsAnywhere[event] !== undefined
+            ? 'deploy-written hook entries were modified since deploy, or assets/hooks.json changed since; run deploy to update'
+            : 'expected hook wiring for this event has not been deployed',
+      }
+    }),
+  ]
 }
 
 function doctorOpencodeSurface(surface: HookSurface, ctx: { assetsDir: string; targetRepo: string; hooksDoc: CanonicalHooksDoc; lock: ReturnType<typeof readLock> }): DoctorIssue[] {

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 }
 }