@amsterdamdatalabs/adl-agent-control-linux-x64 0.1.12 → 0.1.28

package/packages/agent-settings/src/kimi-hooks.ts

@@ -30,14 +30,14 @@
  * file may contain provider API keys, so this script never prints file
  * content — only marker state, paths, and validation results.
  *
- * STATUS.md 12p decision 13 (Tarun, 2026-09-29, "adl is LOCAL REPO FIRST …
+ * Local-repo-first rule (Tarun, 2026-09-29, "adl is LOCAL REPO FIRST …
  * the repos where adl-config.toml does not exist has no business of running
  * hooks"): this carrier STAYS global, as the one exception, because Kimi has
  * no per-repo hook configuration to deploy into — confirmed from Kimi's own
  * docs, <https://moonshotai.github.io/kimi-code/en/customization/hooks.html>
  * (fetched 2026-09-29): "All hook rules are written in the `[[hooks]]` array
  * in `~/.kimi-code/config.toml`", no project-local alternative documented.
- * Decision 13's per-repo-only requirement covers Kimi too, and is built —
+ * The per-repo-only requirement covers Kimi too, and is built —
  * not here, since the TOML `command` string this file writes is a fixed
  * shell command with no access to the hook payload's JSON `cwd`, but inside
  * `adl hook` itself, which resolves the invoking repository root from the
@@ -48,13 +48,21 @@
  * So this global carrier is safe: a Kimi session outside a managed repo
  * still invokes `adl hook`, which no-ops before any rule runs.
  */
-import { spawnSync } from 'node:child_process'
-import { createHash } from 'node:crypto'
-import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
-import { dirname, isAbsolute, join, resolve } from 'node:path'
-
-export const BEGIN = '# BEGIN ADL KIMI HOOKS'
-export const END = '# END ADL KIMI HOOKS'
+import { spawnSync } from "node:child_process";
+import { createHash } from "node:crypto";
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+
+export const BEGIN = "# BEGIN ADL KIMI HOOKS";
+export const END = "# END ADL KIMI HOOKS";
 
 /**
  * Legacy markers used before the Enact -> adl rename. A real Kimi install
@@ -66,10 +74,30 @@ export const END = '# END ADL KIMI HOOKS'
  * replaced IN PLACE with the current-marker block on a plain apply/uninstall
  * — never left orphaned alongside a freshly-inserted second block.
  */
-const LEGACY_BEGIN = '# BEGIN ENACT KIMI HOOKS'
-const LEGACY_END = '# END ENACT KIMI HOOKS'
+const LEGACY_BEGIN = "# BEGIN ENACT KIMI HOOKS";
+const LEGACY_END = "# END ENACT KIMI HOOKS";
+
+const HOOK_BIN = "adl hook";
+
+interface DoctorCommandResult {
+  readonly status: number | null;
+  readonly stdout: string;
+  readonly stderr: string;
+}
 
-const HOOK_BIN = 'adl hook'
+export type DoctorCommandRunner = (
+  command: string,
+  args: readonly string[],
+) => DoctorCommandResult;
+
+const runDoctorCommand: DoctorCommandRunner = (command, args) => {
+  const result = spawnSync(command, [...args], { encoding: "utf8" });
+  return {
+    status: result.status,
+    stdout: result.stdout,
+    stderr: result.stderr,
+  };
+};
 
 /**
  * Broad file-write tool matcher shared with every other host's CRG
@@ -80,13 +108,13 @@ const HOOK_BIN = 'adl hook'
  * simply never matches.
  */
 const CRG_WRITE_MATCHER =
-  'Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file'
+  "Write|Edit|MultiEdit|StrReplace|str_replace_editor|edit_file|str_replace|replace_in_file|create_file|write_file";
 
 export interface HookEntry {
-  readonly event: string
-  readonly matcher?: string
-  readonly command: string
-  readonly timeout: number
+  readonly event: string;
+  readonly matcher?: string;
+  readonly command: string;
+  readonly timeout: number;
 }
 
 /**
@@ -96,17 +124,15 @@ export interface HookEntry {
  * read-only reference — see the "why hardcode, not derive" note below):
  *   - PreToolUse (no matcher -> every tool) -> pre-tool-use gate
  *   - PreToolUse (matcher "Bash") -> CRG pre-commit
- *   - PreToolUse (no matcher -> every tool) -> lean-ctx pre-tool-use
  *   - UserPromptSubmit (no matcher -> every prompt) -> skill-match suggestions
  *   - SessionStart (no matcher -> both "startup" and "resume") -> briefing
  *   - PostToolUse on file-write tools -> CRG after-file-edit
- *   - PostToolUse (no matcher -> every tool) -> lean-ctx post-tool-use
  *   - SessionEnd (no matcher -> both "exit" and "archive"; the session-close
  *     event, not the per-turn "Stop" event) -> CRG session-stop, matching
  *     every other host's own sessionEnd/SessionEnd wiring for this hook.
  *
  * Order within PreToolUse mirrors the canonical file exactly: catch-all guard
- * -> Bash-matched crg pre-commit -> catch-all lean-ctx. The guard must see
+ * -> Bash-matched crg pre-commit. The guard must see
  * every tool before host-specific narrower checks run.
  *
  * Why this is hardcoded rather than derived from the canonical hooks list at
@@ -124,32 +150,60 @@ export interface HookEntry {
  * pinned copy, so a deployer change requires an explicit behavior review.
  */
 export const MANAGED_HOOKS: readonly HookEntry[] = [
-  { event: 'PreToolUse', command: `${HOOK_BIN} pre-tool-use --host=kimi`, timeout: 30 },
-  { event: 'PreToolUse', matcher: 'Bash', command: `${HOOK_BIN} crg pre-commit --host=kimi`, timeout: 30 },
-  { event: 'PreToolUse', command: `${HOOK_BIN} lean-ctx pre-tool-use --host=kimi`, timeout: 30 },
-  { event: 'UserPromptSubmit', command: `${HOOK_BIN} user-prompt-submit --host=kimi`, timeout: 30 },
-  { event: 'SessionStart', command: `${HOOK_BIN} briefing --host=kimi`, timeout: 15 },
-  { event: 'PostToolUse', matcher: CRG_WRITE_MATCHER, command: `${HOOK_BIN} crg after-file-edit --host=kimi`, timeout: 30 },
-  { event: 'PostToolUse', command: `${HOOK_BIN} lean-ctx post-tool-use --host=kimi`, timeout: 30 },
-  { event: 'SessionEnd', command: `${HOOK_BIN} crg session-stop --host=kimi`, timeout: 30 },
-]
+  {
+    event: "PreToolUse",
+    command: `${HOOK_BIN} pre-tool-use --host=kimi`,
+    timeout: 30,
+  },
+  {
+    event: "PreToolUse",
+    matcher: "Bash",
+    command: `${HOOK_BIN} crg pre-commit --host=kimi`,
+    timeout: 30,
+  },
+  {
+    event: "UserPromptSubmit",
+    command: `${HOOK_BIN} user-prompt-submit --host=kimi`,
+    timeout: 30,
+  },
+  {
+    event: "SessionStart",
+    command: `${HOOK_BIN} briefing --host=kimi`,
+    timeout: 15,
+  },
+  {
+    event: "PostToolUse",
+    matcher: CRG_WRITE_MATCHER,
+    command: `${HOOK_BIN} crg after-file-edit --host=kimi`,
+    timeout: 30,
+  },
+  {
+    event: "SessionEnd",
+    command: `${HOOK_BIN} crg session-stop --host=kimi`,
+    timeout: 30,
+  },
+];
 
 function tomlEntry(entry: HookEntry): string {
-  const lines = ['[[hooks]]', `event = ${JSON.stringify(entry.event)}`]
-  if (entry.matcher !== undefined) lines.push(`matcher = ${JSON.stringify(entry.matcher)}`)
-  lines.push(`command = ${JSON.stringify(entry.command)}`, `timeout = ${entry.timeout}`)
-  return lines.join('\n')
+  const lines = ["[[hooks]]", `event = ${JSON.stringify(entry.event)}`];
+  if (entry.matcher !== undefined)
+    lines.push(`matcher = ${JSON.stringify(entry.matcher)}`);
+  lines.push(
+    `command = ${JSON.stringify(entry.command)}`,
+    `timeout = ${entry.timeout}`,
+  );
+  return lines.join("\n");
 }
 
 export function managedBlock(): string {
   const header = [
     BEGIN,
-    '# Deployed by packages/agent-settings/src/kimi-hooks.ts (bin/kimi-hooks).',
-    '# Everything between the markers is regenerated on every apply —',
-    '# edit the deployer, not this block.',
-  ]
-  const body = MANAGED_HOOKS.map(tomlEntry).join('\n\n')
-  return [...header, body, END].join('\n')
+    "# Deployed by packages/agent-settings/src/kimi-hooks.ts (bin/kimi-hooks).",
+    "# Everything between the markers is regenerated on every apply —",
+    "# edit the deployer, not this block.",
+  ];
+  const body = MANAGED_HOOKS.map(tomlEntry).join("\n\n");
+  return [...header, body, END].join("\n");
 }
 
 /**
@@ -164,14 +218,14 @@ export function managedBlock(): string {
  */
 const PRIOR_BLOCK_HASHES: readonly string[] = [
   // 5-hook block (PreToolUse guard, UserPromptSubmit, SessionStart, PostToolUse crg, SessionEnd) —
-  // shipped before crg pre-commit / lean-ctx pre-tool-use / lean-ctx post-tool-use parity was added.
-  'fa83560b374bb59b7a45ffa91b5c9d3bfbc2aea36b7e28293b58168fb77db292',
+  // shipped before crg pre-commit parity was added.
+  "fa83560b374bb59b7a45ffa91b5c9d3bfbc2aea36b7e28293b58168fb77db292",
   // 8-hook block before the repository guard became a catch-all PreToolUse hook.
-  '9e6ef84ff230cf29011408dfc7d5798059a6df7790892213efc343e03381d85a',
+  "9e6ef84ff230cf29011408dfc7d5798059a6df7790892213efc343e03381d85a",
   // 8-hook block calling the standalone `enact-hook` binary, before it folded
   // into the one `adl` binary (item 15/P4, docs/specs/two-branch-standard-
   // 2026-09-27.md) and HOOK_BIN became `adl hook` — hard cut, no compat shim.
-  '0fa75023b0bb836c199bb0f1f7327fafacea73b4e494a0f45662a1fa3522b7ef',
+  "0fa75023b0bb836c199bb0f1f7327fafacea73b4e494a0f45662a1fa3522b7ef",
   // Same 8-hook `enact-hook` body as the entry above, but from one generation
   // earlier: the header comment still reads the pre-reorg deployer path
   // ("global-surface-sweep/src/kimi-hooks.ts") because `acf8ab1` (reorganise
@@ -185,29 +239,43 @@ const PRIOR_BLOCK_HASHES: readonly string[] = [
   // managed block was classified `drifted` instead of `ours-outdated`,
   // aborting a plain `apply` with "hand-edited, or unrecognized content"
   // even though it is byte-for-byte a block this deployer itself shipped.
-  'bc3f34452cbec3dc0aeb77d917816fd4fbc73a8baedfa09f4e9313a56b330d94',
-]
+  "bc3f34452cbec3dc0aeb77d917816fd4fbc73a8baedfa09f4e9313a56b330d94",
+  // 10-hook `adl hook` block from the window after the enact→adl rename but
+  // before lean-ctx was retired (2026-10-04): current markers, current header,
+  // and the two `adl hook lean-ctx pre|post-tool-use` entries the canonical
+  // block no longer carries. Found live on m3's ~/.kimi-code/config.toml —
+  // classified `drifted` and aborted the scheduled reconcile's plain apply
+  // even though the only delta from canonical is the two retired lean-ctx
+  // entries (diff verified byte-for-byte; see PREVIOUS_LEAN_CTX_ERA_BLOCK in
+  // tests/kimi-hooks-upgrade.test.ts).
+  "29d2953dd893b6d244bf825b10a7e9deb1a1c25b2acc0db1b74327e19cc8a253",
+];
 
 function hashBlock(text: string): string {
-  return createHash('sha256').update(text).digest('hex')
+  return createHash("sha256").update(text).digest("hex");
 }
 
-export type BlockState = 'missing' | 'matches' | 'ours-outdated' | 'drifted' | 'malformed'
+export type BlockState =
+  | "missing"
+  | "matches"
+  | "ours-outdated"
+  | "drifted"
+  | "malformed";
 
 interface Region {
-  readonly start: number
+  readonly start: number;
   /** Exclusive — the index immediately after the closing marker's text. */
-  readonly end: number
+  readonly end: number;
 }
 
-type RegionResult = Region | 'missing' | 'malformed'
+type RegionResult = Region | "missing" | "malformed";
 
 function findRegion(content: string, begin: string, end: string): RegionResult {
-  const start = content.indexOf(begin)
-  const stop = content.indexOf(end)
-  if (start < 0 && stop < 0) return 'missing'
-  if (start < 0 || stop < 0 || stop < start) return 'malformed'
-  return { start, end: stop + end.length }
+  const start = content.indexOf(begin);
+  const stop = content.indexOf(end);
+  if (start < 0 && stop < 0) return "missing";
+  if (start < 0 || stop < 0 || stop < start) return "malformed";
+  return { start, end: stop + end.length };
 }
 
 /**
@@ -217,9 +285,9 @@ function findRegion(content: string, begin: string, end: string): RegionResult {
  * never mistaken for "missing" and duplicated alongside a fresh insert.
  */
 function locateManagedRegion(content: string): RegionResult {
-  const current = findRegion(content, BEGIN, END)
-  if (current !== 'missing') return current
-  return findRegion(content, LEGACY_BEGIN, LEGACY_END)
+  const current = findRegion(content, BEGIN, END);
+  if (current !== "missing") return current;
+  return findRegion(content, LEGACY_BEGIN, LEGACY_END);
 }
 
 /**
@@ -228,24 +296,27 @@ function locateManagedRegion(content: string): RegionResult {
  * missing) and pass it in.
  */
 export function classifyBlock(existingContent: string | null): BlockState {
-  if (existingContent === null || existingContent.length === 0) return 'missing'
-  const region = locateManagedRegion(existingContent)
-  if (region === 'missing') return 'missing'
-  if (region === 'malformed') return 'malformed'
-  const installed = existingContent.slice(region.start, region.end)
-  if (installed === managedBlock()) return 'matches'
-  return PRIOR_BLOCK_HASHES.includes(hashBlock(installed)) ? 'ours-outdated' : 'drifted'
+  if (existingContent === null || existingContent.length === 0)
+    return "missing";
+  const region = locateManagedRegion(existingContent);
+  if (region === "missing") return "missing";
+  if (region === "malformed") return "malformed";
+  const installed = existingContent.slice(region.start, region.end);
+  if (installed === managedBlock()) return "matches";
+  return PRIOR_BLOCK_HASHES.includes(hashBlock(installed))
+    ? "ours-outdated"
+    : "drifted";
 }
 
 function spliceIn(base: string): string {
-  const block = managedBlock()
-  const region = locateManagedRegion(base)
-  if (region !== 'missing' && region !== 'malformed') {
-    return `${base.slice(0, region.start)}${block}${base.slice(region.end)}`
+  const block = managedBlock();
+  const region = locateManagedRegion(base);
+  if (region !== "missing" && region !== "malformed") {
+    return `${base.slice(0, region.start)}${block}${base.slice(region.end)}`;
   }
-  if (base.length === 0) return `${block}\n`
-  const trimmed = base.replace(/\n+$/, '')
-  return `${trimmed}\n\n${block}\n`
+  if (base.length === 0) return `${block}\n`;
+  const trimmed = base.replace(/\n+$/, "");
+  return `${trimmed}\n\n${block}\n`;
 }
 
 /**
@@ -255,50 +326,63 @@ function spliceIn(base: string): string {
  * freshly-applied block returns the file to byte-identical pre-apply content.
  */
 function spliceOut(base: string): string {
-  const region = locateManagedRegion(base)
-  if (region === 'missing' || region === 'malformed') return base
-  const head = base.slice(0, region.start).replace(/\n+$/, '')
-  const tail = base.slice(region.end).replace(/^\n+/, '')
-  if (head.length === 0) return tail
-  if (tail.length === 0) return `${head}\n`
-  return `${head}\n\n${tail}`
+  const region = locateManagedRegion(base);
+  if (region === "missing" || region === "malformed") return base;
+  const head = base.slice(0, region.start).replace(/\n+$/, "");
+  const tail = base.slice(region.end).replace(/^\n+/, "");
+  if (head.length === 0) return tail;
+  if (tail.length === 0) return `${head}\n`;
+  return `${head}\n\n${tail}`;
 }
 
 function resolveConfigPath(home: string): string {
-  if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`)
-  return join(resolve(home), '.kimi-code', 'config.toml')
+  if (!isAbsolute(home)) throw new Error(`--home must be absolute: ${home}`);
+  return join(resolve(home), ".kimi-code", "config.toml");
 }
 
 function readConfig(path: string): string | null {
-  if (!existsSync(path)) return null
-  return readFileSync(path, 'utf8')
+  if (!existsSync(path)) return null;
+  return readFileSync(path, "utf8");
 }
 
 /** Real TOML syntax check via Bun's built-in parser — never a stub. */
 function assertParseable(text: string, context: string): void {
-  if (text.trim().length === 0) return
+  if (text.trim().length === 0) return;
   try {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any -- Bun global, no @types/bun in this package
-    ;(globalThis as any).Bun.TOML.parse(text)
+    (globalThis as any).Bun.TOML.parse(text);
   } catch (error) {
-    throw new Error(`${context} is not valid TOML: ${error instanceof Error ? error.message : String(error)}`)
+    throw new Error(
+      `${context} is not valid TOML: ${error instanceof Error ? error.message : String(error)}`,
+    );
   }
 }
 
 /** Best-effort schema check against the real `kimi` CLI when it is on PATH; a no-op note otherwise. */
-function doctorCheck(path: string): string | null {
-  const which = spawnSync('bash', ['-lc', 'command -v kimi'], { encoding: 'utf8' })
-  if (which.status !== 0) return null
-  const result = spawnSync('kimi', ['doctor', 'config', path], { encoding: 'utf8' })
+function doctorCheck(
+  path: string,
+  runCommand: DoctorCommandRunner,
+): string | null {
+  // Probe the effective PATH this wrapper established. A login shell can add
+  // user startup paths and accidentally run an unrelated host Kimi install.
+  const which = runCommand("bash", ["-c", "command -v kimi"]);
+  if (which.status !== 0) return null;
+  const kimi = which.stdout.trim();
+  const result = runCommand(kimi, ["doctor", "config", path]);
   if (result.status !== 0) {
-    throw new Error(`kimi doctor rejected the candidate config: ${(result.stderr || result.stdout || '').trim()}`)
+    throw new Error(
+      `kimi doctor rejected the candidate config: ${(result.stderr || result.stdout || "").trim()}`,
+    );
   }
-  return 'kimi doctor: OK'
+  return "kimi doctor: OK";
 }
 
 function backupPath(configPath: string): string {
-  const stamp = new Date().toISOString().replace(/[-:]/g, '').replace(/\.\d+Z$/, 'Z')
-  return `${configPath}.pre-kimi-hooks-${stamp}`
+  const stamp = new Date()
+    .toISOString()
+    .replace(/[-:]/g, "")
+    .replace(/\.\d+Z$/, "Z");
+  return `${configPath}.pre-kimi-hooks-${stamp}`;
 }
 
 /**
@@ -307,149 +391,212 @@ function backupPath(configPath: string): string {
  * the existing file, then atomically rename the staged file into place. A
  * rejected candidate leaves the existing config completely untouched.
  */
-function commitConfig(path: string, next: string, notes: string[]): string | undefined {
-  assertParseable(next, 'candidate config')
-  mkdirSync(dirname(path), { recursive: true })
-  const temporary = join(dirname(path), `.kimi-hooks.${process.pid}.${Date.now()}.tmp`)
-  writeFileSync(temporary, next)
+function commitConfig(
+  path: string,
+  next: string,
+  notes: string[],
+  runCommand: DoctorCommandRunner = runDoctorCommand,
+): string | undefined {
+  assertParseable(next, "candidate config");
+  mkdirSync(dirname(path), { recursive: true });
+  const temporary = join(
+    dirname(path),
+    `.kimi-hooks.${process.pid}.${Date.now()}.tmp`,
+  );
+  writeFileSync(temporary, next);
   try {
-    const doctorNote = doctorCheck(temporary)
-    if (doctorNote) notes.push(doctorNote)
+    const doctorNote = doctorCheck(temporary, runCommand);
+    if (doctorNote) notes.push(doctorNote);
   } catch (error) {
-    rmSync(temporary, { force: true })
-    throw error
+    rmSync(temporary, { force: true });
+    throw error;
   }
-  let backup: string | undefined
+  let backup: string | undefined;
   if (existsSync(path)) {
-    backup = backupPath(path)
-    copyFileSync(path, backup)
-    notes.push(`backed up previous config to ${backup}`)
+    backup = backupPath(path);
+    copyFileSync(path, backup);
+    notes.push(`backed up previous config to ${backup}`);
   }
-  renameSync(temporary, path)
-  return backup
+  renameSync(temporary, path);
+  return backup;
 }
 
 export interface PlanResult {
-  readonly path: string
-  readonly state: BlockState
-  readonly wouldChangeOnApply: boolean
-  readonly wouldChangeOnUninstall: boolean
+  readonly path: string;
+  readonly state: BlockState;
+  readonly wouldChangeOnApply: boolean;
+  readonly wouldChangeOnUninstall: boolean;
 }
 
 /** Read-only: current state and what apply/uninstall would do. Never touches the file. */
 export function planKimiHooks(home: string): PlanResult {
-  const path = resolveConfigPath(home)
-  const state = classifyBlock(readConfig(path))
+  const path = resolveConfigPath(home);
+  const state = classifyBlock(readConfig(path));
   return {
     path,
     state,
-    wouldChangeOnApply: state === 'missing' || state === 'drifted' || state === 'ours-outdated',
-    wouldChangeOnUninstall: state === 'matches' || state === 'drifted' || state === 'ours-outdated',
-  }
+    wouldChangeOnApply:
+      state === "missing" || state === "drifted" || state === "ours-outdated",
+    wouldChangeOnUninstall:
+      state === "matches" || state === "drifted" || state === "ours-outdated",
+  };
 }
 
 export interface OpResult {
-  readonly path: string
-  readonly stateBefore: BlockState
-  readonly action: 'none' | 'installed' | 'updated' | 'removed'
-  readonly notes: readonly string[]
-  readonly backupPath: string | undefined
+  readonly path: string;
+  readonly stateBefore: BlockState;
+  readonly action: "none" | "installed" | "updated" | "removed";
+  readonly notes: readonly string[];
+  readonly backupPath: string | undefined;
 }
 
-export function applyKimiHooks(home: string, options: { readonly force?: boolean } = {}): OpResult {
-  const path = resolveConfigPath(home)
-  const base = readConfig(path)
-  const state = classifyBlock(base)
-  const notes: string[] = []
-
-  if (state === 'malformed') {
-    throw new Error(`malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`)
+export function applyKimiHooks(
+  home: string,
+  options: {
+    readonly force?: boolean;
+    readonly doctorCommandRunner?: DoctorCommandRunner;
+  } = {},
+): OpResult {
+  const path = resolveConfigPath(home);
+  const base = readConfig(path);
+  const state = classifyBlock(base);
+  const notes: string[] = [];
+
+  if (state === "malformed") {
+    throw new Error(
+      `malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`,
+    );
   }
-  if (base !== null) assertParseable(base, path)
-
-  if (state === 'matches') {
-    notes.push('managed hook block already present and canonical')
-    return { path, stateBefore: state, action: 'none', notes, backupPath: undefined }
+  if (base !== null) assertParseable(base, path);
+
+  if (state === "matches") {
+    notes.push("managed hook block already present and canonical");
+    return {
+      path,
+      stateBefore: state,
+      action: "none",
+      notes,
+      backupPath: undefined,
+    };
   }
-  if (state === 'ours-outdated') {
-    notes.push('upgrading managed hook block from a previous ENACT version (no --force needed)')
+  if (state === "ours-outdated") {
+    notes.push(
+      "upgrading managed hook block from a previous ENACT version (no --force needed)",
+    );
   }
-  if (state === 'drifted' && !(options.force ?? false)) {
+  if (state === "drifted" && !(options.force ?? false)) {
     throw new Error(
       `${path} has a managed hook block that differs from the canonical block (hand-edited, or unrecognized content) — rerun apply with --force to overwrite it`,
-    )
+    );
   }
 
-  const next = spliceIn(base ?? '')
-  const backup = commitConfig(path, next, notes)
-  return { path, stateBefore: state, action: state === 'missing' ? 'installed' : 'updated', notes, backupPath: backup }
+  const next = spliceIn(base ?? "");
+  const backup = commitConfig(path, next, notes, options.doctorCommandRunner);
+  return {
+    path,
+    stateBefore: state,
+    action: state === "missing" ? "installed" : "updated",
+    notes,
+    backupPath: backup,
+  };
 }
 
-export function uninstallKimiHooks(home: string, options: { readonly force?: boolean } = {}): OpResult {
-  const path = resolveConfigPath(home)
-  const base = readConfig(path)
-  const state = classifyBlock(base)
-  const notes: string[] = []
+export function uninstallKimiHooks(
+  home: string,
+  options: { readonly force?: boolean } = {},
+): OpResult {
+  const path = resolveConfigPath(home);
+  const base = readConfig(path);
+  const state = classifyBlock(base);
+  const notes: string[] = [];
 
-  if (state === 'malformed') {
-    throw new Error(`malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`)
+  if (state === "malformed") {
+    throw new Error(
+      `malformed managed-block markers in ${path} (BEGIN/END unpaired or out of order) — fix manually`,
+    );
   }
-  if (base !== null) assertParseable(base, path)
-
-  if (state === 'missing') {
-    notes.push('managed hook block not present; nothing to remove')
-    return { path, stateBefore: state, action: 'none', notes, backupPath: undefined }
+  if (base !== null) assertParseable(base, path);
+
+  if (state === "missing") {
+    notes.push("managed hook block not present; nothing to remove");
+    return {
+      path,
+      stateBefore: state,
+      action: "none",
+      notes,
+      backupPath: undefined,
+    };
   }
-  if (state === 'ours-outdated') {
-    notes.push('removing managed hook block from a previous ENACT version (no --force needed)')
+  if (state === "ours-outdated") {
+    notes.push(
+      "removing managed hook block from a previous ENACT version (no --force needed)",
+    );
   }
-  if (state === 'drifted' && !(options.force ?? false)) {
+  if (state === "drifted" && !(options.force ?? false)) {
     throw new Error(
       `${path} has a managed hook block that differs from the canonical block (hand-edited, or unrecognized content) — rerun uninstall with --force to remove it anyway`,
-    )
+    );
   }
 
-  const next = spliceOut(base as string)
-  const backup = commitConfig(path, next, notes)
-  return { path, stateBefore: state, action: 'removed', notes, backupPath: backup }
+  const next = spliceOut(base as string);
+  const backup = commitConfig(path, next, notes);
+  return {
+    path,
+    stateBefore: state,
+    action: "removed",
+    notes,
+    backupPath: backup,
+  };
 }
 
 function usage(): never {
-  throw new Error('usage: kimi-hooks --home ABSOLUTE_PATH --mode plan|apply|uninstall [--force]')
+  throw new Error(
+    "usage: kimi-hooks --home ABSOLUTE_PATH --mode plan|apply|uninstall [--force]",
+  );
 }
 
 export function main(argv: readonly string[]): void {
-  let home = ''
-  let mode = ''
-  let force = false
-  for (let index = 0; index < argv.length; index += 1) {
-    const argument = argv[index]
-    if (argument === '--home') home = argv[++index] ?? ''
-    else if (argument === '--mode') mode = argv[++index] ?? ''
-    else if (argument === '--force') force = true
-    else usage()
-  }
-  if (home.length === 0 || !['plan', 'apply', 'uninstall'].includes(mode)) usage()
-
-  if (mode === 'plan') {
-    const result = planKimiHooks(home)
-    console.log(`kimi-hooks: config=${result.path}`)
-    console.log(`kimi-hooks: state=${result.state}`)
-    console.log(`kimi-hooks: apply would ${result.wouldChangeOnApply ? 'change this file' : 'no-op'}`)
-    console.log(`kimi-hooks: uninstall would ${result.wouldChangeOnUninstall ? 'change this file' : 'no-op'}`)
-    return
+  try {
+    let home = "";
+    let mode = "";
+    let force = false;
+    for (let index = 0; index < argv.length; index += 1) {
+      const argument = argv[index];
+      if (argument === "--home") home = argv[++index] ?? "";
+      else if (argument === "--mode") mode = argv[++index] ?? "";
+      else if (argument === "--force") force = true;
+      else usage();
+    }
+    if (home.length === 0 || !["plan", "apply", "uninstall"].includes(mode))
+      usage();
+
+    if (mode === "plan") {
+      const result = planKimiHooks(home);
+      console.log(`kimi-hooks: config=${result.path}`);
+      console.log(`kimi-hooks: state=${result.state}`);
+      console.log(
+        `kimi-hooks: apply would ${result.wouldChangeOnApply ? "change this file" : "no-op"}`,
+      );
+      console.log(
+        `kimi-hooks: uninstall would ${result.wouldChangeOnUninstall ? "change this file" : "no-op"}`,
+      );
+      return;
+    }
+
+    const result =
+      mode === "apply"
+        ? applyKimiHooks(home, { force })
+        : uninstallKimiHooks(home, { force });
+    for (const note of result.notes) console.log(`kimi-hooks: ${note}`);
+    console.log(`kimi-hooks: ${result.action} (${result.path})`);
+  } catch (cause) {
+    console.error(
+      `kimi-hooks: ${cause instanceof Error ? cause.message : String(cause)}`,
+    );
+    process.exitCode = 1;
   }
-
-  const result = mode === 'apply' ? applyKimiHooks(home, { force }) : uninstallKimiHooks(home, { force })
-  for (const note of result.notes) console.log(`kimi-hooks: ${note}`)
-  console.log(`kimi-hooks: ${result.action} (${result.path})`)
 }
 
 if (import.meta.main) {
-  try {
-    main(process.argv.slice(2))
-  } catch (cause) {
-    console.error(`kimi-hooks: ${cause instanceof Error ? cause.message : String(cause)}`)
-    process.exitCode = 1
-  }
+  main(process.argv.slice(2));
 }