@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.4

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

@@ -0,0 +1,158 @@
+/**
+ * This package's own doctor (D6b / H5): checks the DEPLOYED state of a
+ * target repository against assets/hooks.json + the deploy profile, for
+ * every surface. Mirrors packages/agent-skills/src/doctor.ts's shape.
+ *
+ * For the JSON-hooks and cursor-hooks-v1 surfaces, "does the deployed file
+ * match" is answered by running the SAME merge deploy.ts would run (with the
+ * repo's own current lock as `previousOwned`) and checking whether it would
+ * change anything — a missing file, a hand-edited owned entry, and a
+ * dropped-from-assets entry still sitting there all show up as "would
+ * change" via json-merge.ts's own diff, with `changedEvents` giving the
+ * per-entry reason. For opencode-plugin (wholly adl-owned, H3), doctor
+ * compares the deployed file byte-for-byte against what deploy would write,
+ * and separately fails when a non-adl file occupies that path (a conflict
+ * deploy itself refuses to overwrite).
+ */
+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 { renderOpencodePlugin } from './opencode-template.ts'
+import {
+  DEFAULT_PROFILE_PATH,
+  DEFAULT_PROFILE_SCHEMA_PATH,
+  type HookDeployProfile,
+  type HookSurface,
+  validateProfileDocument,
+} from './profile.ts'
+import { renderCursorEntries, renderJsonHooksGroups } from './render.ts'
+import { type CanonicalHooksDoc, loadHooksSource } from './source.ts'
+
+export interface DoctorIssue {
+  readonly severity: 'error' | 'info'
+  readonly path: string
+  readonly reason: string
+}
+
+export interface DoctorResult {
+  readonly ok: boolean
+  readonly issues: readonly DoctorIssue[]
+}
+
+function toResult(issues: readonly DoctorIssue[]): DoctorResult {
+  return { ok: issues.every((issue) => issue.severity !== 'error'), issues }
+}
+
+export { validateProfileDocument }
+
+export interface DoctorDeploymentOptions {
+  readonly assetsDir: string
+  readonly targetRepo: string
+  readonly profilePath?: string
+  readonly profileSchemaPath?: string
+}
+
+/**
+ * Every call site (`doctorJsonSurface`, below) has already run its own
+ * `JSON.parse` on this same file and returned early when that threw — so the
+ * parse here can never fail, and there is no unreachable-catch branch to
+ * carry. The non-object-result guard stays: it is reachable (a file can
+ * parse fine as `[]` or `"x"`).
+ */
+function readExistingJson(path: string): Record<string, unknown> | undefined {
+  if (!existsSync(path)) return undefined
+  const doc = JSON.parse(readFileSync(path, 'utf8'))
+  if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) return undefined
+  return doc as Record<string, unknown>
+}
+
+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 : {}
+
+  let parseFailed = false
+  if (exists) {
+    try {
+      JSON.parse(readFileSync(targetAbs, 'utf8'))
+    } catch {
+      parseFailed = true
+    }
+  }
+  if (parseFailed) return [{ severity: 'error', path: surface.file, reason: 'deployed file is not valid JSON' }]
+
+  const existingRaw = readExistingJson(targetAbs)
+  const merged =
+    surface.format === 'cursor-hooks-v1'
+      ? mergeCursorHooksFile(existingRaw, renderCursorEntries(hooksDoc, surface), previousOwned)
+      : mergeJsonHooksFile(existingRaw, renderJsonHooksGroups(hooksDoc, surface), previousOwned)
+
+  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) => ({
+    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',
+  }))
+}
+
+function doctorOpencodeSurface(surface: HookSurface, ctx: { assetsDir: string; targetRepo: string; hooksDoc: CanonicalHooksDoc; lock: ReturnType<typeof readLock> }): DoctorIssue[] {
+  const targetAbs = join(ctx.targetRepo, surface.file)
+  const exists = existsSync(targetAbs)
+  const lockEntry = ctx.lock.entries[surface.file]
+  const wasOwned = lockEntry?.format === 'opencode-plugin' && lockEntry.owned === true
+
+  if (!exists) {
+    return [{ severity: 'error', path: surface.file, reason: 'expected hook wiring has not been deployed' }]
+  }
+  if (!wasOwned) {
+    return [{ severity: 'error', path: surface.file, reason: 'a non-adl file occupies this path; deploy would refuse to overwrite it (conflict)' }]
+  }
+  const expected = renderOpencodePlugin({ assetsDir: ctx.assetsDir, surface, hooksDoc: ctx.hooksDoc })
+  const actual = readFileSync(targetAbs, 'utf8')
+  if (actual !== expected) {
+    return [{ severity: 'error', path: surface.file, reason: 'deploy-written file was modified since deploy, or assets/hooks.json changed since; run deploy to update' }]
+  }
+  return []
+}
+
+export function doctorDeployment(options: DoctorDeploymentOptions): DoctorResult {
+  const profilePath = options.profilePath ?? DEFAULT_PROFILE_PATH
+  const schemaPath = options.profileSchemaPath ?? DEFAULT_PROFILE_SCHEMA_PATH
+
+  let profileDoc: unknown
+  try {
+    profileDoc = JSON.parse(readFileSync(profilePath, 'utf8'))
+  } catch (cause) {
+    return toResult([{ severity: 'error', path: profilePath, reason: `deploy profile is not valid JSON: ${(cause as Error).message}` }])
+  }
+  const profileIssues = validateProfileDocument(profileDoc, schemaPath)
+  if (profileIssues.length > 0) {
+    return toResult(profileIssues.map((issue) => ({ severity: 'error' as const, path: profilePath, reason: `${issue.path}: ${issue.message}` })))
+  }
+  const profile = profileDoc as HookDeployProfile
+
+  let hooksDoc: CanonicalHooksDoc
+  try {
+    hooksDoc = loadHooksSource(join(dirname(options.assetsDir), profile.source))
+  } catch (cause) {
+    return toResult([{ severity: 'error', path: profile.source, reason: (cause as Error).message }])
+  }
+
+  const lock = readLock(options.targetRepo)
+  const issues: DoctorIssue[] = []
+  for (const surface of profile.surfaces) {
+    if (surface.format === 'opencode-plugin') {
+      issues.push(...doctorOpencodeSurface(surface, { assetsDir: options.assetsDir, targetRepo: options.targetRepo, hooksDoc, lock }))
+    } else {
+      issues.push(...doctorJsonSurface(surface, options.targetRepo, hooksDoc, lock))
+    }
+  }
+  return toResult(issues)
+}

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

@@ -0,0 +1,17 @@
+export { deployHooks, type DeployHooksOptions, type DeployHooksResult, type HookConflict } from './deploy.ts'
+export { doctorDeployment, type DoctorDeploymentOptions, type DoctorIssue, type DoctorResult } from './doctor.ts'
+export { formatHookLine, listHooks, type HookListing, type HookListingEntry, type HookOwner, type ListHooksOptions } from './list.ts'
+export { type HookLock, type HookLockEntry, LOCK_RELATIVE_PATH, lockPathFor, readLock, writeLock } from './lock.ts'
+export {
+  DEFAULT_PROFILE_PATH,
+  DEFAULT_PROFILE_SCHEMA_PATH,
+  type HookDeployProfile,
+  HOOK_WIRE_FORMATS,
+  type HookSurface,
+  type HookWireFormat,
+  loadProfile,
+  type ProfileIssue,
+  validateProfileDocument,
+} from './profile.ts'
+export { renderCursorEntries, renderJsonHooksGroups, renderOpencodeSlots } from './render.ts'
+export { DEFAULT_HOOKS_SOURCE_PATH, flattenSourceHooks, hookLabel, loadHooksSource, type CanonicalHooksDoc } from './source.ts'

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

@@ -0,0 +1,115 @@
+/**
+ * Merges rendered hook wiring into an existing (or absent) target JSON file,
+ * touching only entries a PREVIOUS run of this deploy recorded as its own
+ * (per lock.ts) — every other key, and every hook entry this deploy did not
+ * write, survives untouched (H4). Two shapes: `mergeJsonHooksFile` for
+ * claude-settings/codex-hooks' `{hooks:{Event:[{matcher?,hooks:[...]}]}}`,
+ * `mergeCursorHooksFile` for cursor-hooks-v1's flat
+ * `{version:1,hooks:{event:[{command,...}]}}`.
+ *
+ * For a target file that does not exist yet, `existing` is `undefined` and
+ * the result is built fresh in the profile's own (= source hooks.json's)
+ * 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).
+ */
+import type { RenderedCursorEntry, RenderedGroup } from './render.ts'
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+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. */
+  readonly ownedCommands: Readonly<Record<string, readonly string[]>>
+  readonly changed: boolean
+  /** Events whose array actually differs from what was already on disk — doctor.ts's per-entry reasons. */
+  readonly changedEvents: readonly string[]
+}
+
+/** 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[]>>,
+): JsonHooksMergeResult {
+  const base: Record<string, unknown> = existing ? { ...existing } : {}
+  const existingHooks = isRecord(base.hooks) ? base.hooks : {}
+
+  const orderedEvents: string[] = [...Object.keys(existingHooks)]
+  for (const event of desired.keys()) if (!orderedEvents.includes(event)) orderedEvents.push(event)
+
+  const newHooks: Record<string, unknown> = {}
+  const ownedCommands: Record<string, readonly string[]> = {}
+  const changedEvents: string[] = []
+  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 desiredGroups = desired.get(event) ?? []
+    if (desiredGroups.length > 0) {
+      ownedCommands[event] = desiredGroups.flatMap((g) => g.hooks.map((h) => h.command))
+    }
+    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
+      changedEvents.push(event)
+    }
+  }
+
+  base.hooks = newHooks
+  return { fileContent: base, ownedCommands, changed, changedEvents }
+}
+
+export interface CursorHooksMergeResult {
+  readonly fileContent: Record<string, unknown>
+  /** New lock contents: Cursor's own event name -> the command strings this deploy now owns there. */
+  readonly ownedCommands: Readonly<Record<string, readonly string[]>>
+  readonly changed: boolean
+  /** Events whose array actually differs from what was already on disk — doctor.ts's per-entry reasons. */
+  readonly changedEvents: readonly string[]
+}
+
+/** For cursor-hooks-v1: `{version: 1, hooks: {event: [{command, statusMessage, timeout, matcher?}]}}`. */
+export function mergeCursorHooksFile(
+  existing: Record<string, unknown> | undefined,
+  desired: ReadonlyMap<string, readonly RenderedCursorEntry[]>,
+  previousOwned: Readonly<Record<string, readonly string[]>>,
+): CursorHooksMergeResult {
+  const base: Record<string, unknown> = existing ? { ...existing } : { version: 1 }
+  if (base.version === undefined) base.version = 1
+  const existingHooks = isRecord(base.hooks) ? base.hooks : {}
+
+  const orderedEvents: string[] = [...Object.keys(existingHooks)]
+  for (const event of desired.keys()) if (!orderedEvents.includes(event)) orderedEvents.push(event)
+
+  const newHooks: Record<string, unknown> = {}
+  const ownedCommands: Record<string, readonly string[]> = {}
+  const changedEvents: string[] = []
+  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 desiredEntries = desired.get(event) ?? []
+    if (desiredEntries.length > 0) ownedCommands[event] = desiredEntries.map((e) => e.command)
+    const merged = [...keptEntries, ...desiredEntries]
+    if (merged.length > 0) newHooks[event] = merged
+    if (JSON.stringify(existingHooks[event] ?? null) !== JSON.stringify(merged.length > 0 ? merged : null)) {
+      changed = true
+      changedEvents.push(event)
+    }
+  }
+
+  base.hooks = newHooks
+  return { fileContent: base, ownedCommands, changed, changedEvents }
+}

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

@@ -0,0 +1,213 @@
+/**
+ * Takeover of hook wiring the pre-agent-hooks engine (packages/agent-skills'
+ * repo-local installer, lockVersion 2) already wrote into a target repo.
+ *
+ * That engine recorded what it wrote only in its own
+ * `.agents/adl-repo.lock.json` (or whatever `deploy-profile.json`'s
+ * `legacyLock` names): for a json-hooks surface,
+ * `merged[<surface file>].entries[]` holds one `{type:"item",
+ * path:["hooks",<event>], sha256}` per hook entry it merged into that
+ * event's array; for the opencode-plugin surface, `files[<surface
+ * file>].sha256` is the whole rendered file's hash. This package's own
+ * `.agents/agent-hooks.lock.json` (lock.ts) knows nothing about any of that,
+ * so left alone, `deployHooks` would see every one of those entries as
+ * foreign (H4) and ADD a second copy of each one instead of replacing it.
+ *
+ * Takeover rule (Tarun, 2026-09-28, chat approval "yes lets take over
+ * adl-azdo"): an existing hook entry whose content hash equals a sha256 the
+ * legacy lock recorded for that exact (surface file, event) is adl-written
+ * -> deploy.ts treats it exactly as if ITS OWN previous run had written it
+ * (folds its command(s) into the `previousOwned` set passed to
+ * json-merge.ts), so the normal merge replaces or removes it like any other
+ * owned entry and never duplicates it. A hash that does not match (hand
+ * edited since, or never adl's) stays foreign — reported, untouched, no
+ * different from a user hook deploy never wrote. Same idea for the
+ * opencode-plugin file: a whole-file hash match makes deploy.ts treat it as
+ * already-owned so it gets REWRITTEN with the current template rather than
+ * refused as a conflict.
+ *
+ * Once at least one entry has actually been taken over this run, this
+ * package's own footprint in the legacy lock — the three hook `merged`
+ * sections and the opencode-plugin `files` entry — is stale: ownership has
+ * now fully moved to `.agents/agent-hooks.lock.json`, so `stripLegacyOwnership`
+ * removes it (and the whole legacy lock file, if nothing else is left in it).
+ * A hand-modified entry that stayed foreign leaves no orphaned record behind
+ * either way: it was never adl-owned content once its hash stopped matching,
+ * so there is nothing further for the legacy lock to say about it.
+ */
+import { createHash } from 'node:crypto'
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs'
+
+export const sha256Hex = (input: string | Buffer): string => createHash('sha256').update(input).digest('hex')
+
+/**
+ * Key-order-independent serialisation, ported verbatim from
+ * packages/agent-skills/src/internal/json-merge.ts's `stableStringify` — the
+ * exact function that computed every sha256 in a legacy lock's `merged`
+ * section. An item's identity must not change just because a host or a user
+ * rewrote the file and reordered its keys.
+ */
+export function stableStringify(value: unknown): string {
+  if (Array.isArray(value)) return `[${value.map(stableStringify).join(',')}]`
+  if (value && typeof value === 'object') {
+    return `{${Object.keys(value as Record<string, unknown>)
+      .sort()
+      .map((k) => `${JSON.stringify(k)}:${stableStringify((value as Record<string, unknown>)[k])}`)
+      .join(',')}}`
+  }
+  return JSON.stringify(value)
+}
+
+/** Content hash of a JSON value, exactly as the legacy engine recorded it. */
+export const legacyValueHash = (value: unknown): string => sha256Hex(stableStringify(value))
+
+export interface LegacyJsonMergeEntry {
+  readonly type: string
+  readonly path: readonly (string | number)[]
+  readonly sha256: string
+}
+
+export interface LegacyMergedRecord {
+  readonly entries?: readonly LegacyJsonMergeEntry[]
+}
+
+export interface LegacyLockDoc {
+  readonly files?: Readonly<Record<string, { readonly sha256: string }>>
+  readonly merged?: Readonly<Record<string, LegacyMergedRecord>>
+  readonly toml?: Readonly<Record<string, unknown>>
+  readonly gitignore?: Readonly<Record<string, unknown>>
+  readonly [key: string]: unknown
+}
+
+/** Reads and parses a legacy lock at `path`, or `undefined` when it does not exist. Fails loud on unparsable or non-object content. */
+export function readLegacyLock(path: string): LegacyLockDoc | undefined {
+  if (!existsSync(path)) return undefined
+  let doc: unknown
+  try {
+    doc = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (cause) {
+    throw new Error(`legacy lock is not valid JSON: ${path} (${(cause as Error).message})`)
+  }
+  if (typeof doc !== 'object' || doc === null || Array.isArray(doc)) {
+    throw new Error(`legacy lock has an unrecognized shape: ${path}`)
+  }
+  return doc as LegacyLockDoc
+}
+
+/** The sha256 set the legacy lock recorded under `merged[file].entries` for exactly path `["hooks", event]`. Empty when the lock, the file, or the event is unrecorded. */
+export function legacyHookHashes(doc: LegacyLockDoc | undefined, file: string, event: string): ReadonlySet<string> {
+  const entries = doc?.merged?.[file]?.entries ?? []
+  const hashes = new Set<string>()
+  for (const entry of entries) {
+    if (entry.type === 'item' && entry.path.length === 2 && entry.path[0] === 'hooks' && entry.path[1] === event) {
+      hashes.add(entry.sha256)
+    }
+  }
+  return hashes
+}
+
+/** The legacy lock's recorded whole-file sha256 for `file` under `files`, or `undefined` when unrecorded. */
+export function legacyFileHash(doc: LegacyLockDoc | undefined, file: string): string | undefined {
+  return doc?.files?.[file]?.sha256
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+export interface LegacyTakeover {
+  /** Event -> command strings from entries this run is taking over there; feed into previousOwned before merging. */
+  readonly ownedByEvent: Readonly<Record<string, readonly string[]>>
+  /** True when at least one existing entry in this file was taken over. */
+  readonly matched: boolean
+}
+
+const EMPTY_TAKEOVER: LegacyTakeover = { ownedByEvent: {}, matched: false }
+
+/**
+ * Existing entries in `existing.hooks` whose content hash matches a legacy
+ * sha256 recorded for that (file, event) — for both json-hooks shapes at
+ * once: claude/codex's `{matcher?, hooks:[{command,...}]}` groups (every
+ * command inside a matched group is taken over) and cursor's flat
+ * `{command, statusMessage, timeout, matcher?}` entries (the entry's own
+ * command is taken over).
+ */
+export function legacyTakeoverForJsonHooksSurface(existing: Record<string, unknown> | undefined, legacyDoc: LegacyLockDoc | undefined, file: string): LegacyTakeover {
+  if (!legacyDoc || !existing || !isRecord(existing.hooks)) return EMPTY_TAKEOVER
+
+  const ownedByEvent: Record<string, string[]> = {}
+  let matched = false
+
+  for (const [event, value] of Object.entries(existing.hooks)) {
+    if (!Array.isArray(value)) continue
+    const legacyHashes = legacyHookHashes(legacyDoc, file, event)
+    if (legacyHashes.size === 0) continue
+
+    const commands: string[] = []
+    for (const entry of value) {
+      if (!legacyHashes.has(legacyValueHash(entry))) continue
+      matched = true
+      if (isRecord(entry) && Array.isArray(entry.hooks)) {
+        for (const h of entry.hooks) if (isRecord(h) && typeof h.command === 'string') commands.push(h.command)
+      } else if (isRecord(entry) && typeof entry.command === 'string') {
+        commands.push(entry.command)
+      }
+    }
+    if (commands.length > 0) ownedByEvent[event] = commands
+  }
+
+  return { ownedByEvent, matched }
+}
+
+const MERGED_HOOK_FILES = ['.claude/settings.json', '.codex/hooks.json', '.cursor/hooks.json'] as const
+
+/** Merges `previous` (this deploy's own prior ownership) and `takeover` (freshly taken-over legacy ownership) into one previousOwned map, per event. */
+export function unionOwnedCommands(previous: Readonly<Record<string, readonly string[]>>, takeover: Readonly<Record<string, readonly string[]>>): Readonly<Record<string, readonly string[]>> {
+  const events = new Set([...Object.keys(previous), ...Object.keys(takeover)])
+  const out: Record<string, readonly string[]> = {}
+  for (const event of events) {
+    out[event] = [...new Set([...(previous[event] ?? []), ...(takeover[event] ?? [])])]
+  }
+  return out
+}
+
+function isEmptyRecord(value: unknown): boolean {
+  return typeof value === 'object' && value !== null && Object.keys(value).length === 0
+}
+
+/**
+ * Removes this package's own footprint from a legacy lock — the three hook
+ * `merged` sections and the opencode-plugin `files` entry — and rewrites it
+ * at `lockPath`; deletes the file entirely when `files`, `merged`, `toml`
+ * and `gitignore` are then all empty. A no-op (returns `false`, never
+ * writes) when none of those keys were present in `doc` to begin with —
+ * sibling packages (agent-skills, agent-settings) own everything else in
+ * the same lock and are never touched here.
+ */
+export function stripLegacyOwnership(doc: LegacyLockDoc, lockPath: string, opencodeFile?: string): boolean {
+  const merged = { ...(doc.merged ?? {}) }
+  const files = { ...(doc.files ?? {}) }
+  let touched = false
+
+  for (const file of MERGED_HOOK_FILES) {
+    if (file in merged) {
+      delete merged[file]
+      touched = true
+    }
+  }
+  if (opencodeFile !== undefined && opencodeFile in files) {
+    delete files[opencodeFile]
+    touched = true
+  }
+  if (!touched) return false
+
+  const next: LegacyLockDoc = { ...doc, files, merged }
+  const nothingLeft = isEmptyRecord(next.files) && isEmptyRecord(next.merged) && isEmptyRecord(next.toml ?? {}) && isEmptyRecord(next.gitignore ?? {})
+
+  if (nothingLeft) {
+    unlinkSync(lockPath)
+  } else {
+    writeFileSync(lockPath, `${JSON.stringify(next, null, 2)}\n`)
+  }
+  return true
+}

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

@@ -0,0 +1,117 @@
+/**
+ * Lists every hook available in assets/hooks.json AND every hook command
+ * found actually written into a target repo's surfaces, merged into one
+ * entry per hook name — mirrors packages/agent-skills/src/list.ts's shape
+ * and line format.
+ */
+import { existsSync, readFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { type HookLockEntry, readLock } from './lock.ts'
+import { type HookDeployProfile, type HookSurface, loadProfile } from './profile.ts'
+import { flattenSourceHooks, hookLabel, loadHooksSource, type CanonicalHooksDoc } from './source.ts'
+
+export type HookOwner = 'adl' | 'user' | 'conflict' | '-'
+
+export interface HookListingEntry {
+  readonly name: string
+  readonly available: boolean
+  /** Surface names (profile.ts `HookSurface.name`) this hook is currently found deployed to, sorted. */
+  readonly deployedIn: readonly string[]
+  readonly owner: HookOwner
+  readonly line: string
+}
+
+export interface HookListing {
+  readonly entries: readonly HookListingEntry[]
+  readonly lines: readonly string[]
+}
+
+export interface ListHooksOptions {
+  readonly assetsDir: string
+  readonly targetRepo: string
+  readonly profile?: HookDeployProfile
+  readonly hooksDoc?: CanonicalHooksDoc
+}
+
+/** One line per hook: `<name>  available|-  deployed:<surface,surface|-> owner:adl|user|conflict|-`. */
+export function formatHookLine(entry: Pick<HookListingEntry, 'name' | 'available' | 'deployedIn' | 'owner'>): string {
+  const available = entry.available ? 'available' : '-'
+  const deployed = entry.deployedIn.length > 0 ? [...entry.deployedIn].sort().join(',') : '-'
+  return `${entry.name}  ${available}  deployed:${deployed}  owner:${entry.owner}`
+}
+
+/**
+ * Every "adl hook ..." command string found in raw text, stripped to its
+ * label (`source.ts`'s `hookLabel`, with `surface.hostSuffix`'s
+ * ` --host=<suffix>` also stripped). Deliberately format-agnostic: it matches
+ * both JSON's `"command": "..."` and the opencode plugin's TS `command: "..."`,
+ * so list.ts/doctor.ts need no per-format parser to answer "is this hook
+ * present here".
+ */
+function extractCommandLabels(text: string, hostSuffix: string): ReadonlySet<string> {
+  const out = new Set<string>()
+  const re = /"command"\s*:\s*"([^"]+)"|(?<!")\bcommand:\s*"([^"]+)"/g
+  const hostRe = new RegExp(`\\s*--host=${hostSuffix}$`)
+  let match: RegExpExecArray | null
+  while ((match = re.exec(text)) !== null) {
+    const raw = match[1] ?? match[2]
+    if (raw === undefined) continue
+    out.add(hookLabel(raw.replace(hostRe, '')))
+  }
+  return out
+}
+
+function ownedLabelsForSurface(entry: HookLockEntry | undefined, surface: HookSurface, present: ReadonlySet<string>): ReadonlySet<string> {
+  if (entry === undefined) return new Set()
+  if (entry.format === 'opencode-plugin') return entry.owned ? new Set(present) : new Set()
+  if (entry.format !== surface.format) return new Set()
+  const hostRe = new RegExp(`\\s*--host=${surface.hostSuffix}$`)
+  const out = new Set<string>()
+  for (const commands of Object.values(entry.ownedCommands)) {
+    for (const command of commands) out.add(hookLabel(command.replace(hostRe, '')))
+  }
+  return out
+}
+
+export function listHooks(options: ListHooksOptions): HookListing {
+  const profile = options.profile ?? loadProfile()
+  const hooksDoc = options.hooksDoc ?? loadHooksSource(join(dirname(options.assetsDir), profile.source))
+  const sourceLabels = new Set(flattenSourceHooks(hooksDoc).map((ref) => hookLabel(ref.command.command)))
+  const lock = readLock(options.targetRepo)
+
+  const perSurface = profile.surfaces.map((surface) => {
+    const targetAbs = join(options.targetRepo, surface.file)
+    const text = existsSync(targetAbs) ? readFileSync(targetAbs, 'utf8') : ''
+    const present = extractCommandLabels(text, surface.hostSuffix)
+    const owned = ownedLabelsForSurface(lock.entries[surface.file], surface, present)
+    return { surface, present, owned }
+  })
+
+  const allNames = new Set<string>(sourceLabels)
+  for (const { present } of perSurface) for (const name of present) allNames.add(name)
+
+  const entries: HookListingEntry[] = [...allNames].sort().map((name) => {
+    const deployedIn: string[] = []
+    let anyOwned = false
+    let anyUnowned = false
+    for (const { surface, present, owned } of perSurface) {
+      if (!present.has(name)) continue
+      deployedIn.push(surface.name)
+      if (owned.has(name)) anyOwned = true
+      else anyUnowned = true
+    }
+
+    const available = sourceLabels.has(name)
+    let owner: HookOwner = '-'
+    if (deployedIn.length > 0) {
+      if (anyOwned && anyUnowned) owner = 'conflict'
+      else if (anyOwned) owner = 'adl'
+      else owner = available ? 'conflict' : 'user'
+    }
+
+    const base = { name, available, deployedIn: deployedIn.sort(), owner }
+    return { ...base, line: formatHookLine(base) }
+  })
+
+  return { entries, lines: entries.map((entry) => entry.line) }
+}