harnery 0.41.0 → 0.43.0

package/src/core/hooks/cli.ts

@@ -57,7 +57,13 @@ import {
 } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
 import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.ts";
-import { assignName } from "../agents/state/names.ts";
+import {
+  assignName,
+  readForkParent,
+  readForkState,
+  recordForkDetection,
+  resolveName,
+} from "../agents/state/names.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import {
   agentsRequireGitFinalization,
@@ -90,6 +96,7 @@ import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/
 import { stableScopeId } from "../workflow/scope-id.ts";
 import { type AdapterBehavior, adapterBehavior } from "./adapter/behaviors/index.ts";
 import { detectAdapter, shouldSkipHookAdapter } from "./adapter/detect.ts";
+import { ADAPTER_SPECS } from "./adapter/events.ts";
 import {
   extractBashCommand,
   extractToolDescription,
@@ -98,6 +105,7 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
+import { hookTimeoutFor } from "./adapter/wiring.ts";
 import { scheduleBackupSnapshot } from "./backup-schedule.ts";
 import {
   captureImages,
@@ -113,6 +121,7 @@ import {
   soundForEvent,
 } from "./effects/index.ts";
 import { toolInputHash, toolTargetHash } from "./events/input-hash.ts";
+import { detectClaudeCodeFork } from "./fork-lineage.ts";
 import { canonicalize } from "./guard-path.ts";
 import {
   beginHookHealth,
@@ -131,7 +140,9 @@ import {
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
+import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
+import { shellRmReason } from "./shell-rm.ts";
 import { shellWaiterReason } from "./shell-waiter.ts";
 
 interface Argv {
@@ -140,6 +151,7 @@ interface Argv {
 }
 
 let hookHealthState: HookHealthState | undefined;
+let hookRunMarkerPath: string | null = null;
 
 function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
@@ -246,12 +258,14 @@ function assignNameInProcess(
   coordRoot: string,
   instanceId: string,
   kind: "session" | "subagent" | "transient",
-  forkedFrom?: string,
+  fork?: { forkedFrom?: string; fork?: boolean; forkChecked?: boolean },
 ): { name: string; kind: string } | null {
   try {
     const name = assignName(coordRoot, instanceId, kind, {
       freshnessSecs: coordFreshnessSeconds(coordRoot),
-      ...(forkedFrom ? { forkedFrom } : {}),
+      ...(fork?.forkedFrom ? { forkedFrom: fork.forkedFrom } : {}),
+      ...(fork?.fork ? { fork: true } : {}),
+      ...(fork?.forkChecked ? { forkChecked: true } : {}),
     });
     return { name, kind };
   } catch {
@@ -259,6 +273,66 @@ function assignNameInProcess(
   }
 }
 
+/**
+ * Name a main session, recording fork lineage when the instance is new. Every
+ * main-session naming path goes through here: whichever hook first sees a new
+ * instance writes its history row, and lineage can only ride that first row
+ * (later detection appends a `fork.detected` row instead).
+ */
+function assignSessionNameInProcess(
+  coordRoot: string,
+  instanceId: string,
+  payload: ParsedPayload | null,
+  adapter: Adapter,
+): { name: string; kind: string } | null {
+  let fork: { forkedFrom?: string; fork?: boolean; forkChecked?: boolean } | undefined;
+  try {
+    if (
+      adapter === "claude-code" &&
+      payload?.session_id === instanceId &&
+      !resolveName(coordRoot, instanceId)
+    ) {
+      const detected = detectClaudeCodeFork({
+        coordRoot,
+        transcriptPath: payload.transcript_path,
+        sessionId: instanceId,
+        source: payload.source,
+      });
+      fork = {
+        ...(detected.forkedFrom ? { forkedFrom: detected.forkedFrom } : {}),
+        fork: detected.fork,
+        forkChecked: detected.checked,
+      };
+    }
+  } catch {
+    fork = undefined;
+  }
+  return assignNameInProcess(coordRoot, instanceId, "session", fork);
+}
+
+/**
+ * Finish fork detection that session start could not: a CLI fork starts before
+ * its transcript exists, and a mid-flight instance may never see SessionStart.
+ * Runs once per instance; the appended `fork_checked` row stops later calls.
+ */
+function healForkLineage(
+  coordRoot: string,
+  instanceId: string,
+  payload: ParsedPayload | null,
+): void {
+  if (!payload?.transcript_path || payload.session_id !== instanceId) return;
+  const state = readForkState(coordRoot, instanceId);
+  if (!state || state.checked) return;
+  const detected = detectClaudeCodeFork({
+    coordRoot,
+    transcriptPath: payload.transcript_path,
+    sessionId: instanceId,
+    knownFork: state.fork,
+  });
+  if (!detected.checked) return;
+  recordForkDetection(coordRoot, instanceId, detected);
+}
+
 /** Mid-flight sessions can emit tools before SessionStart assigns a pool name.
  * Stamp the disposable cache so Codec does not render the 8-character id. */
 function ensureSessionDisplayName(
@@ -266,13 +340,14 @@ function ensureSessionDisplayName(
   instanceId: string,
   sessionId: string,
   adapter: Adapter,
+  payload: ParsedPayload | null,
 ): void {
   if (coordEnv("WORKFLOW_CHILD") === "1") return;
   const row =
     readLiveCoordinationRow(coordRoot, instanceId) ?? readHeartbeat(coordRoot, instanceId);
   if (row?.kind === "subagent" || row?.kind === "transient" || row?.workflow_run_id) return;
   if (row?.name?.trim()) return;
-  const assigned = assignNameInProcess(coordRoot, instanceId, "session");
+  const assigned = assignSessionNameInProcess(coordRoot, instanceId, payload, adapter);
   if (!assigned?.name) return;
   if (!readHeartbeat(coordRoot, instanceId)) {
     try {
@@ -341,17 +416,22 @@ function buildEventData(
       // The platform label is the adapter id itself; enumerating and defaulting
       // to codex silently mislabels any adapter not in the list.
       const adapterPlatform = ctx.adapter;
-      // Recorded fork lineage is NOT detected here. On claude-code a fork
-      // never fires its own session.started — SessionStart fires under the
-      // PARENT's session id (source=resume) before the fork id is minted
-      // (verified 2026-08-05) — so detection at this point can only mislabel
-      // the resumed parent. The fork's new instance is caught by the
-      // tool.requested heal path instead. The forkedFrom plumbing below stays
-      // for adapters that DO report a parent at session start.
-      const forkedFrom: string | undefined = undefined;
       // Assign (or recover) name + kind in-process. Idempotent: resume
-      // returns the original name; new owner consumes a counter slot.
-      const assigned = assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
+      // returns the original name; new owner consumes a counter slot and,
+      // on claude-code, runs fork detection (fork-lineage.ts). Since Claude
+      // Code 2.1.283 both fork flows fire SessionStart under the FORK's own
+      // id (verified 2026-10-07), superseding the 2026-08-05 finding that a
+      // fork never started on its own id. A resumed parent keeps its existing
+      // history row, so it is never relabeled here.
+      // Workflow children stay unnamed, as on the tool path: a pool name
+      // would make them the addressee of mail held for that name.
+      const assigned =
+        coordEnv("WORKFLOW_CHILD") === "1"
+          ? undefined
+          : assignSessionNameInProcess(ctx.coordRoot, ctx.instanceId, p, ctx.adapter);
+      const forkedFrom = assigned
+        ? readForkParent(ctx.coordRoot, ctx.instanceId)?.instance_id
+        : undefined;
       // Write the adapter pid-map row so `harn agents whoami` ppid-walks find
       // this owner. Prefer the payload pid (the actual claude binary), then the
       // anchor walk (the `node` ancestor for Cursor, which has no payload pid),
@@ -416,8 +496,11 @@ function buildEventData(
       // SessionStart. Mint durable display identity here so a later
       // SessionStart remains idempotent and Codec is not stuck on the
       // 8-character native id.
-      if (!readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name) {
-        assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session");
+      if (
+        coordEnv("WORKFLOW_CHILD") !== "1" &&
+        !readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name
+      ) {
+        assignSessionNameInProcess(ctx.coordRoot, ctx.instanceId, p, ctx.adapter);
       }
       const prompt = p?.prompt ?? "";
       const { value, truncated } = clampString(prompt, 4000);
@@ -663,6 +746,24 @@ async function main(): Promise<number> {
   const { eventName, extra } = parseArgv(process.argv.slice(2));
   const adapter = detectAdapter(process.argv.slice(2));
   const behavior = adapter ? adapterBehavior(adapter) : null;
+  // Adapters that kill a hook at its timeout get a start marker, so a killed
+  // run leaves evidence for doctor (ADR 0197). Written before stdin is read.
+  const markerSpec = adapter ? ADAPTER_SPECS[adapter] : undefined;
+  const markerTimeout =
+    markerSpec && eventName && markerSpec.events.some((e) => e.subcommand === eventName)
+      ? hookTimeoutFor(markerSpec, eventName)
+      : undefined;
+  if (markerTimeout !== undefined && adapter && eventName && coordEnv("AGENT_COORD_OFF") !== "1") {
+    const markerRoot = resolveCoordRoot(process.cwd());
+    if (markerRoot) {
+      hookRunMarkerPath = writeHookRunMarker(markerRoot, {
+        event: eventName,
+        adapter,
+        pid: process.pid,
+        timeout_sec: markerTimeout,
+      });
+    }
+  }
   const raw = await readStdin();
   hookHealthState = beginHookHealth({
     started_at_ms: hookStartedAt,
@@ -821,7 +922,7 @@ async function main(): Promise<number> {
     !priorCoordination?.workflow_run_id &&
     !priorCoordination?.name?.trim()
   ) {
-    assignNameInProcess(coordRoot, owner.instance_id, "session");
+    assignSessionNameInProcess(coordRoot, owner.instance_id, payload, adapter);
   }
 
   const data = buildEventData(norm.event_type, {
@@ -1033,11 +1134,18 @@ function recordSignal(run: HookRun): void {
   }
   if (norm.event_type !== "session.ended") {
     try {
-      ensureSessionDisplayName(coordRoot, owner.instance_id, sessionId, adapter);
+      ensureSessionDisplayName(coordRoot, owner.instance_id, sessionId, adapter, payload);
     } catch (error) {
       logError(coordRoot, error, { phase: "session-display-name" });
     }
   }
+  if (norm.event_type === "tool.requested" && adapter === "claude-code" && run.topLevelSession) {
+    try {
+      healForkLineage(coordRoot, owner.instance_id, payload);
+    } catch (error) {
+      logError(coordRoot, error, { phase: "fork-lineage-heal" });
+    }
+  }
   const v3EventId =
     v3Result && "event" in v3Result
       ? v3Result.event.event_id
@@ -1189,9 +1297,12 @@ async function handleSessionStarted(run: HookRun): Promise<void> {
   const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import(
     "../storage/maintenance-providers.ts"
   );
-  // Effect: throttled daily sweep of expired artifact workspaces (guarded,
-  // managed-expired only; see autoCleanArtifacts). Best-effort like every
-  // janitor here: a failure logs and never blocks session start.
+  // Effect: throttled hourly artifact sweep (see autoCleanArtifacts). It
+  // deletes expired workspaces, plus unheld workspaces over the per-bundle
+  // ceiling or repository budget once they have been idle past
+  // artifacts.idle_grace_hours. Each deletion is rechecked first and recorded
+  // in .harnery/artifact-deletions.jsonl. Best-effort like every janitor
+  // here: a failure logs and never blocks session start.
   try {
     autoCleanArtifacts(coordRoot);
   } catch (err) {
@@ -1526,6 +1637,17 @@ async function handleToolRequested(run: HookRun): Promise<number | undefined> {
     return 0;
   }
 
+  const rmReason = shellRmReason(
+    payload?.tool_name,
+    payload?.tool_input,
+    resolveBinName(coordRoot),
+  );
+  if (rmReason) {
+    const { emitDeny } = await import("./adapter/output.ts");
+    emitDeny(adapter, rmReason);
+    return 0;
+  }
+
   // G-guard for ALL adapters. Claude Code previously ran this via a
   // pre-tool-use bash adapter (which called `agent-coord verdict --rule=claim`);
   // that adapter is now deleted, so agent-hook owns the deny for every adapter.
@@ -1564,7 +1686,8 @@ async function handlePostToolUse(run: HookRun): Promise<void> {
   // status is the wrong place to ask.
   try {
     const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
-    const name = sessionNameDisplayPending(row);
+    // A workflow child has no user-visible title to set.
+    const name = coordEnv("WORKFLOW_CHILD") === "1" ? undefined : sessionNameDisplayPending(row);
     if (name && toolResponseMintedSessionName(payload?.tool_response, name)) {
       // Record the title before asking for it. The suggestion can still
       // change afterwards (an assigned-name rewrite, a lifecycle re-mint, a
@@ -1765,6 +1888,7 @@ async function enforcePendingSessionNameDisplay(
   payload: ParsedPayload | null,
   coordination: Heartbeat | null,
 ): Promise<boolean> {
+  if (coordEnv("WORKFLOW_CHILD") === "1") return true;
   const name = sessionNameDisplayPending(coordination);
   if (!name) return true;
 
@@ -2168,6 +2292,10 @@ async function emitUserPromptSubmitSystemMessage(
   recoveryBriefing = "",
   hostPromptContext = "",
 ): Promise<boolean> {
+  // Workflow children get no prompt-time coordination context, matching
+  // SessionStart. The turn ritual is not enforced for them, the naming nudge
+  // would register them as named peers, and rendering drains peer mail.
+  if (coordEnv("WORKFLOW_CHILD") === "1") return false;
   const behavior = adapterBehavior(adapter);
   const { renderPromptContext } = await import("../agents/render/prompt-context.ts");
   let additionalContext = renderPromptContext({
@@ -2307,6 +2435,7 @@ function completeRecoveryInjection(
 
 main()
   .then(async (code) => {
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,
@@ -2321,6 +2450,7 @@ main()
       pid: process.pid,
       phase: "top-level",
     });
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,

package/src/core/hooks/fork-lineage.ts

@@ -0,0 +1,82 @@
+/**
+ * Claude Code fork detection: decide whether a new main-session instance is a
+ * branch of another session, and which one.
+ *
+ * Two shapes exist as of Claude Code 2.1.283 (verified 2026-10-07):
+ *
+ *   - CLI `--resume <id> --fork-session` fires SessionStart under the FORK's id
+ *     with `source: "fork"`, before its transcript exists, and names no parent.
+ *     The transcript later holds the parent's message uuids with every row's
+ *     `sessionId` rewritten, so the parent is found by uuid containment
+ *     (`detectForkParent`) once the transcript is on disk.
+ *   - The desktop app's "Fork from here" copies the parent's rows into the
+ *     fork's transcript with their original `sessionId`, so inherited rows
+ *     name the parent directly (`detectInheritedSessionParent`).
+ *
+ * Inherited rows alone do not prove a fork: a continuation of a finished
+ * session can carry them too. The parent's liveness separates the two. A
+ * parent with an unended generation is still running (or resumable) and owns
+ * its name, task, and claims, so the new instance is a fork. A finished
+ * parent makes it a continuation, which keeps the generic notice.
+ *
+ * Everything here fails open: an unreadable transcript or an unknown layout
+ * yields "not a fork", never an error.
+ */
+
+import { existsSync } from "node:fs";
+import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import { detectForkParent, detectInheritedSessionParent } from "./resolve/transcript.ts";
+
+export interface ForkDetection {
+  fork: boolean;
+  forkedFrom?: string;
+  /** Detection had the evidence it needs; the tool-path heal can skip it. */
+  checked: boolean;
+}
+
+/** Sources after which a brand-new instance cannot hold inherited history. */
+const FRESH_SOURCES = new Set(["startup", "clear"]);
+
+export function detectClaudeCodeFork(input: {
+  coordRoot: string;
+  transcriptPath: string | undefined;
+  sessionId: string;
+  source?: string;
+  /** The instance was already recorded as a fork without a parent. */
+  knownFork?: boolean;
+  isLive?: (instanceId: string) => boolean;
+}): ForkDetection {
+  try {
+    const declared = input.source === "fork" || input.knownFork === true;
+    const transcriptReady = !!input.transcriptPath && existsSync(input.transcriptPath);
+    const isLive =
+      input.isLive ?? ((id: string) => readLiveCoordinationRow(input.coordRoot, id) !== null);
+
+    const inherited = transcriptReady
+      ? detectInheritedSessionParent(input.transcriptPath, input.sessionId)
+      : undefined;
+    if (inherited && inherited !== input.sessionId) {
+      if (declared || isLive(inherited)) {
+        return { fork: true, forkedFrom: inherited, checked: true };
+      }
+      return { fork: false, checked: true };
+    }
+
+    if (declared) {
+      if (!transcriptReady) return { fork: true, checked: false };
+      const parent = detectForkParent(input.transcriptPath, input.sessionId);
+      return {
+        fork: true,
+        ...(parent && parent !== input.sessionId ? { forkedFrom: parent } : {}),
+        checked: true,
+      };
+    }
+
+    return {
+      fork: false,
+      checked: transcriptReady || FRESH_SOURCES.has(input.source ?? ""),
+    };
+  } catch {
+    return { fork: false, checked: true };
+  }
+}

package/src/core/hooks/resolve/transcript.ts

@@ -356,6 +356,94 @@ const FORK_SCAN_MAX_BYTES = 128 * 1024 * 1024;
 /** How many message uuids to sample across the fork's copied prefix. */
 const FORK_SAMPLE_SIZE = 24;
 
+/** Tail window scanned for inherited rows; a fork's own rows are few when the
+ * scan runs (session start or the first tool call), so the copied history ends
+ * well inside it. */
+const INHERITED_TAIL_BYTES = 4 * 1024 * 1024;
+const INHERITED_HEAD_BYTES = 64 * 1024;
+const SESSION_ID_FIELD_RE =
+  /"sessionId":"([0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12})"/gi;
+
+/**
+ * Detect inherited history from row session ids: the session whose rows were
+ * copied into this transcript, or undefined when every row is this session's.
+ *
+ * Empirical basis (verified 2026-10-07, Claude Code 2.1.283): the desktop
+ * app's "Fork from here" copies the parent's rows into the fork's transcript
+ * WITHOUT rewriting their `sessionId`, so the fork's file opens with thousands
+ * of rows stamped with the parent's id. The CLI `--fork-session` path rewrites
+ * the ids instead and is covered by {@link detectForkParent}.
+ *
+ * When the history is itself several generations deep, the LAST foreign row is
+ * the nearest ancestor, so the tail is scanned first. Whether the foreign
+ * session is a fork parent or a dead predecessor (a continuation) is the
+ * caller's call. Fail-soft: never throws, undefined on any read problem.
+ */
+export function detectInheritedSessionParent(
+  transcriptPath: string | undefined,
+  sessionId: string,
+): string | undefined {
+  try {
+    const readablePath = resolveTranscriptPath(transcriptPath);
+    if (!readablePath || !sessionId) return undefined;
+    const size = statSync(readablePath).size;
+    const fromTail = lastForeignSessionId(
+      readRange(readablePath, Math.max(0, size - INHERITED_TAIL_BYTES), size),
+      sessionId,
+    );
+    if (fromTail || size <= INHERITED_TAIL_BYTES) return fromTail;
+    return lastForeignSessionId(
+      readRange(readablePath, 0, Math.min(size, INHERITED_HEAD_BYTES)),
+      sessionId,
+    );
+  } catch {
+    return undefined;
+  }
+}
+
+function lastForeignSessionId(text: string | undefined, sessionId: string): string | undefined {
+  if (!text) return undefined;
+  const own = sessionId.toLowerCase();
+  const lines = text.split("\n");
+  for (let i = lines.length - 1; i >= 0; i--) {
+    const line = lines[i]!;
+    if (!line.includes('"sessionId":"')) continue;
+    let foreign = false;
+    for (const m of line.matchAll(SESSION_ID_FIELD_RE)) {
+      if (m[1]!.toLowerCase() !== own) foreign = true;
+    }
+    if (!foreign) continue;
+    // Confirm on the parsed row: a nested object can carry another session's
+    // id, but only the row's own top-level field says whose row it is. A
+    // partial line at a window edge fails to parse and is skipped.
+    try {
+      const row = JSON.parse(line) as { sessionId?: unknown };
+      if (typeof row.sessionId === "string" && row.sessionId.toLowerCase() !== own) {
+        return row.sessionId;
+      }
+    } catch {
+      /* torn line */
+    }
+  }
+  return undefined;
+}
+
+function readRange(path: string, start: number, end: number): string | undefined {
+  try {
+    const fs = require("node:fs") as typeof import("node:fs");
+    const fd = fs.openSync(path, "r");
+    try {
+      const buf = Buffer.alloc(Math.max(0, end - start));
+      fs.readSync(fd, buf, 0, buf.length, start);
+      return buf.toString("utf8");
+    } finally {
+      fs.closeSync(fd);
+    }
+  } catch {
+    return undefined;
+  }
+}
+
 /**
  * Detect the parent session of a forked CC conversation from its transcript.
  *

package/src/core/hooks/run-markers.ts

@@ -0,0 +1,132 @@
+/**
+ * Start markers for hook runs on adapters that kill a hook at its `timeout`
+ * (ADR 0197). A Codex hook that times out has its process tree killed and the
+ * tool proceeds without that hook's checks, and the killed process never
+ * reaches the completion receipt in `health.ts`. A small marker written at
+ * start and removed at completion leaves evidence of that case for doctor.
+ *
+ * Observer-only: every write, read, and removal swallows its own errors so a
+ * marker can never change hook behavior.
+ */
+
+import { mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+/** Markers older than this are pruned when a new one is written. */
+const MARKER_RETENTION_MS = 7 * 24 * 60 * 60 * 1000;
+/** A run is unfinished once its marker outlives the timeout by this much. */
+const UNFINISHED_GRACE_MS = 30_000;
+
+export interface HookRunMarker {
+  event: string;
+  adapter: string;
+  pid: number;
+  started_at: string;
+  timeout_sec: number;
+}
+
+export function hookRunMarkerDir(coordRoot: string): string {
+  return join(coordRoot, ".harnery", "active", "hook-runs");
+}
+
+/** Write this run's marker; returns its path, or null when it could not be written. */
+export function writeHookRunMarker(
+  coordRoot: string,
+  marker: Omit<HookRunMarker, "started_at">,
+  now = new Date(),
+): string | null {
+  try {
+    const dir = hookRunMarkerDir(coordRoot);
+    mkdirSync(dir, { recursive: true });
+    pruneHookRunMarkers(dir, now.getTime());
+    const path = join(dir, `${marker.pid}-${safeName(marker.event)}.json`);
+    const body: HookRunMarker = { ...marker, started_at: now.toISOString() };
+    writeFileSync(path, `${JSON.stringify(body)}\n`);
+    return path;
+  } catch {
+    return null;
+  }
+}
+
+export function clearHookRunMarker(path: string | null): void {
+  if (!path) return;
+  try {
+    rmSync(path, { force: true });
+  } catch {
+    // Observer-only.
+  }
+}
+
+export interface UnfinishedHookRuns {
+  count: number;
+  /** Count per event name, most frequent first. */
+  events: Array<{ event: string; count: number }>;
+  latest: string | null;
+}
+
+/**
+ * Markers whose run outlived its timeout plus a grace period and whose
+ * process is gone, within the window. A live process past its timeout is
+ * still running and is not counted.
+ */
+export function findUnfinishedHookRuns(
+  coordRoot: string,
+  nowMs = Date.now(),
+  windowMs = 24 * 60 * 60 * 1000,
+  isAlive: (pid: number) => boolean = processAlive,
+): UnfinishedHookRuns {
+  const counts = new Map<string, number>();
+  let latest: string | null = null;
+  let count = 0;
+  let names: string[] = [];
+  try {
+    names = readdirSync(hookRunMarkerDir(coordRoot)).filter((n) => n.endsWith(".json"));
+  } catch {
+    return { count: 0, events: [], latest: null };
+  }
+  for (const name of names) {
+    let marker: HookRunMarker;
+    try {
+      marker = JSON.parse(
+        readFileSync(join(hookRunMarkerDir(coordRoot), name), "utf8"),
+      ) as HookRunMarker;
+    } catch {
+      continue;
+    }
+    const started = Date.parse(marker.started_at);
+    if (!Number.isFinite(started) || nowMs - started > windowMs) continue;
+    if (nowMs - started < marker.timeout_sec * 1000 + UNFINISHED_GRACE_MS) continue;
+    if (isAlive(marker.pid)) continue;
+    count++;
+    counts.set(marker.event, (counts.get(marker.event) ?? 0) + 1);
+    if (!latest || marker.started_at > latest) latest = marker.started_at;
+  }
+  const events = [...counts.entries()]
+    .map(([event, n]) => ({ event, count: n }))
+    .sort((a, b) => b.count - a.count || a.event.localeCompare(b.event));
+  return { count, events, latest };
+}
+
+function pruneHookRunMarkers(dir: string, nowMs: number): void {
+  for (const name of readdirSync(dir)) {
+    const path = join(dir, name);
+    try {
+      if (nowMs - statSync(path).mtimeMs > MARKER_RETENTION_MS) rmSync(path, { force: true });
+    } catch {
+      // Observer-only.
+    }
+  }
+}
+
+function processAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    return (err as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+function safeName(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]+/g, "-").slice(0, 64) || "unknown";
+}