harnery 0.40.0 → 0.42.0

package/src/core/hooks/cli.ts

@@ -22,7 +22,7 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.ts";
 import { buildInstructionBundle } from "../../lib/instructions/bundle.ts";
-import type { Adapter } from "../adapter.ts";
+import { type Adapter, adapterFromPlatform as sharedAdapterFromPlatform } from "../adapter.ts";
 import { resolveCoordRoot } from "../agents/coord-client.ts";
 import {
   type ClaimFinalizationDecision,
@@ -43,12 +43,15 @@ import {
   sessionNameDisplayInstruction,
   sessionNameDisplayPending,
   sessionNameDisplayRecoveryInstruction,
+  sessionNameDisplayReminder,
+  sessionNameDisplayReminderDue,
   toolResponseMintedSessionName,
 } from "../agents/session-name-display.ts";
 import type { Heartbeat } from "../agents/state/heartbeat-reader.ts";
 import {
   readHeartbeat,
   setAssignedNameCache,
+  stampSessionNameReminded,
   stampSessionNameRequested,
   stampSessionNameSeen,
 } from "../agents/state/heartbeat-writer.ts";
@@ -80,11 +83,14 @@ import {
   recordLiveHookSignalV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
+import type { TurnRitualEvidenceV3 } from "../events/v3/producers/hook-base.ts";
 import { captureSpanClockV3 } from "../events/v3/span-state.ts";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.ts";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.ts";
 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,
@@ -93,14 +99,8 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
-import { discoverCodexSessionTranscript } from "./adapter/runtime-telemetry.ts";
+import { hookTimeoutFor } from "./adapter/wiring.ts";
 import { scheduleBackupSnapshot } from "./backup-schedule.ts";
-import {
-  codexWslFileLinkTelemetry,
-  inspectCodexWslBridge,
-  isWslUncPath,
-  renderCodexWslFileLinkContext,
-} from "./codex-wsl-bridge.ts";
 import {
   captureImages,
   detectPresence,
@@ -130,12 +130,12 @@ import type { SessionNameDisplayInspection } from "./resolve/transcript.ts";
 import {
   inspectSessionNameDisplayImmediately,
   scanAssistantStatusBoxPresent,
-  scanSessionNameDisplayedImmediately,
   scanStatusBoxPresent,
   scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
+import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
-import { unsafeCrossShellReason } from "./unsafe-cross-shell.ts";
+import { shellWaiterReason } from "./shell-waiter.ts";
 
 interface Argv {
   eventName: string | null;
@@ -143,6 +143,7 @@ interface Argv {
 }
 
 let hookHealthState: HookHealthState | undefined;
+let hookRunMarkerPath: string | null = null;
 
 function parseArgv(argv: string[]): Argv {
   const out: Argv = { eventName: null, extra: [] };
@@ -341,12 +342,9 @@ function buildEventData(
   const p = ctx.payload;
   switch (eventType) {
     case "session.started": {
-      const adapterPlatform =
-        ctx.adapter === "claude-code"
-          ? "claude-code"
-          : ctx.adapter === "cursor"
-            ? "cursor"
-            : "codex";
+      // 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
@@ -357,7 +355,12 @@ function buildEventData(
       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);
+      // 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
+          : assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session", forkedFrom);
       // 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),
@@ -422,7 +425,10 @@ 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) {
+      if (
+        coordEnv("WORKFLOW_CHILD") !== "1" &&
+        !readLiveCoordinationRow(ctx.coordRoot, ctx.instanceId)?.name
+      ) {
         assignNameInProcess(ctx.coordRoot, ctx.instanceId, "session");
       }
       const prompt = p?.prompt ?? "";
@@ -433,9 +439,11 @@ function buildEventData(
     case "turn.completed": {
       const lastAssistantMessage = (p?.raw.last_assistant_message as string | undefined) ?? "";
       const fileLinkTelemetry =
-        ctx.adapter === "codex"
-          ? codexWslFileLinkTelemetry(ctx.coordRoot, p?.cwd, lastAssistantMessage)
-          : null;
+        adapterBehavior(ctx.adapter).fileLinkTelemetry?.(
+          ctx.coordRoot,
+          p?.cwd,
+          lastAssistantMessage,
+        ) ?? null;
       return {
         // Backfill the model for adapters that omit it at session.started
         // (Claude Code). The transcript is populated with assistant turns by
@@ -471,13 +479,12 @@ function buildEventData(
         // exists (the stop-hook.session_name verdict reads it per turn); the
         // transcript scan itself stops once the name has been sighted.
         ...sessionNamePresence(ctx.coordRoot, ctx.instanceId, (name) =>
-          scanSessionNameDisplayedImmediately(
-            // Codex stops carry no transcript_path; discover the rollout by
-            // session id so the naming ritual can verify and stamp there too.
+          inspectSessionNameDisplayImmediately(
+            // Some adapters omit transcript_path on stop; the behavior may
+            // discover the transcript by session id so the naming ritual can
+            // verify and stamp there too.
             p?.transcript_path ??
-              (ctx.adapter === "codex"
-                ? discoverCodexSessionTranscript(p?.session_id ?? ctx.instanceId)
-                : undefined),
+              adapterBehavior(ctx.adapter).discoverTranscript?.(p?.session_id ?? ctx.instanceId),
             name,
             assistantTextStartsWithSessionNameBlock,
           ),
@@ -622,12 +629,70 @@ function numberField(value: unknown): number | undefined {
   return typeof value === "number" && Number.isFinite(value) && value >= 0 ? value : undefined;
 }
 
+/** Everything one hook invocation resolved before its event handlers run. */
+interface HookRun {
+  coordRoot: string;
+  adapter: Adapter;
+  behavior: AdapterBehavior;
+  eventName: string;
+  norm: NonNullable<ReturnType<typeof normalizeEventName>>;
+  payload: ParsedPayload | null;
+  raw: string;
+  owner: NonNullable<ReturnType<typeof resolveOwner>>;
+  sessionId: string;
+  data: Record<string, unknown>;
+  debugBase: Record<string, unknown>;
+  ledgerRoute: Exclude<ReturnType<typeof resolveLiveEventLedgerRouteV3>, { state: "blocked" }>;
+  hookStartedAt: number;
+  hookClock: ReturnType<typeof captureSpanClockV3>;
+  priorCoordination: Heartbeat | null;
+  topLevelSession: boolean;
+  stopRemediation: boolean;
+  bridge: ReturnType<AdapterBehavior["bridgeFor"]>;
+  turnRitual: TurnRitualEvidenceV3 | undefined;
+  /** Set by recordSignal once the canonical V3 event has landed. */
+  v3Result?: ReturnType<typeof recordLiveHookSignalV3>;
+  v3EventId?: string;
+  recordedGenerationId?: `gen_${string}`;
+}
+
+/** The completed-reply ritual path runs before event normalization and owner resolution. */
+interface CompletedResponseRun {
+  coordRoot: string;
+  adapter: Adapter;
+  eventName: string;
+  raw: string;
+  debugBase: Record<string, unknown>;
+  ledgerRoute: ReturnType<typeof resolveLiveEventLedgerRouteV3>;
+  hookStartedAt: number;
+  hookClock: ReturnType<typeof captureSpanClockV3>;
+}
+
 async function main(): Promise<number> {
   const hookStartedAt = performance.now();
   const hookStartedRss = process.memoryUsage().rss;
   const hookClock = captureSpanClockV3();
   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,
@@ -667,8 +732,8 @@ async function main(): Promise<number> {
   // Kill-switch-INDEPENDENT effects: notification sounds fire BEFORE the
   // HARNERY_AGENT_COORD_OFF gate so audible feedback survives incident-triage
   // bypass: sound playback happens before the kill-switch bailout.
-  // Claude-Code-only; stop-failure → error, sub-agent-start → subagent-start.
-  if (adapter === "claude-code" && eventName) {
+  // Behavior-gated; stop-failure → error, sub-agent-start → subagent-start.
+  if (behavior?.soundEffects && eventName) {
     const s = soundForEvent(eventName);
     if (s) {
       const repoRoot = resolveCoordRoot(process.cwd());
@@ -724,7 +789,7 @@ async function main(): Promise<number> {
     ppid: process.ppid,
   };
 
-  if (!eventName || !adapter) {
+  if (!eventName || !adapter || !behavior) {
     appendDebug(coordRoot, { ...debugBase, skipped: "missing-event-or-adapter" });
     return 0;
   }
@@ -736,88 +801,17 @@ async function main(): Promise<number> {
   // assistant text. Preserve only privacy-safe ritual booleans in the V3
   // producer's open-turn state; Stop consumes them into the authoritative
   // turn.completed event. The response body never enters V3 or heartbeat.
-  if (adapter === "cursor" && eventName === "after-agent-response") {
-    const payload = parsePayload(raw, adapter);
-    const owner = resolveOwner({ payload: payload?.raw ?? null, coordRoot });
-    if (!owner) {
-      appendDebug(coordRoot, { ...debugBase, skipped: "no-owner-resolved" });
-      return 0;
-    }
-    const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
-    const name = sessionNameDisplayPending(row);
-    const text = typeof payload?.raw.text === "string" ? payload.raw.text : "";
-    const sighting = matchSessionNameDisplay(row, text);
-    if (sighting) {
-      stampSessionNameSeen(coordRoot, owner.instance_id, sighting.pending);
-      appendDebug(coordRoot, {
-        ...debugBase,
-        effect: "session-name-display-stamped",
-        session_name_pending: sighting.pending,
-        ...(sighting.displayed === sighting.pending
-          ? {}
-          : { session_name_displayed: sighting.displayed, session_name_drift: true }),
-      });
-    } else if (!name) {
-      // Nothing was owed. Distinct from a miss: conflating the two is what made
-      // a latched Cursor session undiagnosable from this log.
-      appendDebug(coordRoot, { ...debugBase, skipped: "no-pending-session-name" });
-    } else {
-      appendDebug(coordRoot, {
-        ...debugBase,
-        skipped: "session-name-block-absent",
-        session_name_pending: name,
-        reply_bytes: text.length,
-        reply_leads_with_fence: /^\s*`{3,}/.test(text),
-      });
-    }
-    if (ledgerRoute.state === "blocked") {
-      appendDebug(coordRoot, {
-        ...debugBase,
-        skipped: "v3-control-blocked",
-        reason: ledgerRoute.reason,
-        owner_source: owner.source,
-      });
-      return 0;
-    }
-    const statusBoxPresentStrict = scanAssistantStatusBoxPresent(undefined, text);
-    // The hook parser needs the completed reply long enough to scan it, but
-    // durable hook intake must never retain that body. Keep every other native
-    // field so turn correlation remains available to the producer.
-    const { text: _completedReply, ...privacySafeRaw } = payload?.raw ?? {};
-    const privacySafePayload = payload ? { ...payload, raw: privacySafeRaw } : null;
-    const v3Result = recordLiveHookSignalV3({
+  if (behavior && eventName && eventName === behavior.completedResponseEvent) {
+    return handleCompletedResponse({
       coordRoot,
-      route: ledgerRoute,
-      eventName,
-      payload: privacySafePayload,
       adapter,
-      instanceId: owner.instance_id,
-      hook_name: eventName,
-      hook_duration_ms: Math.max(0, Math.floor(performance.now() - hookStartedAt)),
-      monotonic_ns: hookClock.monotonic_ns,
-      turn_ritual: {
-        status_box_present: statusBoxPresentStrict,
-        status_box_present_strict: statusBoxPresentStrict,
-        session_name_required: name !== undefined,
-        session_name_present: name ? assistantTextStartsWithSessionNameBlock(text, name) : false,
-      },
-    });
-    observeHookDebug(hookHealthState, { event_v3_state: v3Result.state });
-    appendDebug(coordRoot, {
-      ...debugBase,
-      effect: "cursor-response-ritual-observed",
-      owner_source: owner.source,
-      event_v3_state: v3Result.state,
-      ...(v3Result.state === "observed"
-        ? {
-            generation_id: v3Result.generation_id,
-            turn_id: v3Result.turn_id,
-            response_observed_at: v3Result.observed_at,
-            status_box_present_strict: statusBoxPresentStrict,
-          }
-        : {}),
+      eventName,
+      raw,
+      debugBase,
+      ledgerRoute,
+      hookStartedAt,
+      hookClock,
     });
-    return 0;
   }
 
   const norm = normalizeEventName(eventName);
@@ -827,6 +821,7 @@ async function main(): Promise<number> {
   }
 
   const payload = parsePayload(raw, adapter);
+  const bridge = behavior.bridgeFor(payload?.cwd);
   const owner = resolveOwner({
     payload: payload?.raw ?? null,
     coordRoot,
@@ -874,8 +869,20 @@ async function main(): Promise<number> {
           status_box_present_strict: data.status_box_present_strict === true,
           session_name_required: typeof data.session_name_present_for === "string",
           session_name_present: data.session_name_present === true,
+          ...(typeof data.session_name_unavailable_reason === "string"
+            ? { session_name_unavailable_reason: data.session_name_unavailable_reason }
+            : {}),
         }
       : undefined;
+  if (typeof data.session_name_unavailable_reason === "string") {
+    reportSessionNameObservationUnavailable(
+      coordRoot,
+      owner.instance_id,
+      adapter,
+      eventName,
+      data.session_name_unavailable_reason,
+    );
+  }
   const stopRemediation =
     norm.event_type === "turn.started" &&
     typeof data.prompt_text === "string" &&
@@ -892,6 +899,107 @@ async function main(): Promise<number> {
     return 0;
   }
 
+  const run: HookRun = {
+    coordRoot,
+    adapter,
+    behavior,
+    eventName,
+    norm,
+    payload,
+    raw,
+    owner,
+    sessionId,
+    data,
+    debugBase,
+    ledgerRoute,
+    hookStartedAt,
+    hookClock,
+    priorCoordination,
+    topLevelSession,
+    stopRemediation,
+    bridge,
+    turnRitual,
+  };
+  recordSignal(run);
+  recordContextTelemetry(run);
+
+  // Phase 8: SessionStart post-emit: project the event so the heartbeat
+  // lands synchronously, run stale-sweep, and emit the adapter-shaped
+  // systemMessage JSON (peer table + wiring check + council invites).
+  // Adapter-agnostic since v0.5.0; replaces the previous bash UX layer
+  // and the equivalent per-adapter bash session_start handlers.
+  if (norm.event_type === "session.started") await handleSessionStarted(run);
+
+  // Phase 8: SessionEnd cleanup: delete heartbeat + pid-map rows. Adapter-
+  // agnostic since v0.5.0.
+  if (norm.event_type === "session.ended") handleSessionEnded(run);
+
+  // Phase 8: SubagentStart: the child generation was opened above from the
+  // native delegation identity. Refresh its disposable projection, log the
+  // lifecycle event, and emit a context message announcing the subagent.
+  if (norm.event_type === "agent.started") await handleAgentStarted(run);
+
+  // Phase 8: SubagentStop: delete subagent heartbeat + log.
+  if (norm.event_type === "agent.completed") await handleAgentCompleted(run);
+
+  // Phase 8: UserPromptSubmit: render dedup'd peer table + council pending
+  // and emit the adapter-shaped systemMessage JSON. Adapter-agnostic since v0.5.0.
+  if (norm.event_type === "turn.started") await handleTurnStarted(run);
+
+  // turn.completed: telemetry, then the stop verdict. The
+  // verdict + codex-replay previously lived in the per-adapter shell adapters;
+  // agent-hook owns them now. Runs on the normal "stop" event only;
+  // "stop-failure" (API error) gets no gate, matching the previous
+  // stop vs stop-failure split.
+  if (norm.event_type === "turn.completed" && eventName === "stop") {
+    const exit = await handleStop(run);
+    if (exit !== undefined) return exit;
+  }
+
+  // Phase 7: PreToolUse: heartbeat + pid-map self-heal on every tool call.
+  // Adapter-agnostic: both writes have the same shape regardless of who fired.
+  // Cursor/Codex bash dispatchers still fire their own G-guard logic, but the
+  // heals here keep the agent-coord layer's view of liveness fresh.
+  //
+  // The heartbeat + pid-map heals are paired by design; they were wired
+  // side-by-side in the previous pre-tool-use adapter. The Phase 4-6 refactor
+  // preserved the heartbeat half but dropped the pid-map half; the pid-map
+  // call was restored here afterward.
+  if (norm.event_type === "tool.requested") {
+    const exit = await handleToolRequested(run);
+    if (exit !== undefined) return exit;
+  }
+
+  if (norm.event_type === "tool.completed" && eventName === "post-tool-use")
+    await handlePostToolUse(run);
+
+  // Phase 7: PostToolUseFailure: release claim on failed Edit (the file
+  // never landed; the claim is stale). Adapter-agnostic.
+  if (norm.event_type === "tool.completed" && eventName === "post-tool-use-failure")
+    handlePostToolUseFailure(run);
+
+  return 0;
+}
+
+function recordSignal(run: HookRun): void {
+  const {
+    coordRoot,
+    adapter,
+    eventName,
+    norm,
+    payload,
+    owner,
+    sessionId,
+    data,
+    debugBase,
+    ledgerRoute,
+    hookStartedAt,
+    hookClock,
+    priorCoordination,
+    stopRemediation,
+    bridge,
+    turnRitual,
+  } = run;
   let capturedImages: ReturnType<typeof captureImages> = [];
   if (
     norm.event_type === "tool.requested" ||
@@ -924,7 +1032,7 @@ async function main(): Promise<number> {
             : {}),
         }
       : {}),
-    ...(adapter === "codex" && isWslUncPath(payload?.cwd) ? { bridge: "codex-wsl" as const } : {}),
+    ...(bridge ? { bridge } : {}),
     hook_name: eventName,
     hook_duration_ms: Math.max(0, Math.floor(performance.now() - hookStartedAt)),
     monotonic_ns: hookClock.monotonic_ns,
@@ -980,9 +1088,7 @@ async function main(): Promise<number> {
         parentEvent: v3Result.event,
         payload,
         adapter,
-        ...(adapter === "codex" && isWslUncPath(payload.cwd)
-          ? { bridge: "codex-wsl" as const }
-          : {}),
+        ...(bridge ? { bridge } : {}),
         monotonic_ns: hookClock.monotonic_ns,
       });
       const nativeChild = payload.subagent_id ?? payload.agent_id;
@@ -1030,7 +1136,13 @@ async function main(): Promise<number> {
     ...(v3Result ? { event_v3_state: v3Result.state } : {}),
     ...(v3Result && "reason" in v3Result ? { event_v3_reason: v3Result.reason } : {}),
   });
+  run.v3Result = v3Result;
+  run.v3EventId = v3EventId;
+  run.recordedGenerationId = recordedGenerationId;
+}
 
+function recordContextTelemetry(run: HookRun): void {
+  const { coordRoot, adapter, norm, payload, owner, sessionId } = run;
   // Context telemetry is opportunistic and truthful: only persist a sample
   // when the adapter payload actually exposes usage/window data. Identical
   // measurements are de-duplicated before they reach the canonical stream.
@@ -1081,437 +1193,549 @@ async function main(): Promise<number> {
       logError(coordRoot, err, { phase: "context-compaction-completed" });
     }
   }
+}
 
-  // Phase 8: SessionStart post-emit: project the event so the heartbeat
-  // lands synchronously, run stale-sweep, and emit the adapter-shaped
-  // systemMessage JSON (peer table + wiring check + council invites).
-  // Adapter-agnostic since v0.5.0; replaces the previous bash UX layer
-  // and the equivalent per-adapter bash session_start handlers.
-  if (norm.event_type === "session.started") {
-    // A configured backup runs out of process and is freshness-gated per host.
-    // Startup never waits for restic or a remote provider; the child owns no
-    // hook stdio, so the harness is not held open until it finishes. A failed
-    // previous run surfaces as one line in this session's context.
-    let backupCue = "";
-    try {
-      backupCue = scheduleBackupSnapshot(coordRoot).cue ?? "";
-    } catch (err) {
-      logError(coordRoot, err, { phase: "backup-schedule" });
-    }
-    // Effect (claude-code): prune stale journal archives + sweep orphans.
-    // The recovery-cue is merged into the
-    // session-start additionalContext inside emitSessionStartSystemMessage.
-    if (adapter === "claude-code") journalJanitor(coordRoot);
-    imageJanitor(coordRoot);
-    // Session start is the only caller of the artifact janitor and the storage
-    // maintenance pass, so both load here instead of on every tool call.
-    const { autoCleanArtifacts } = await import("../artifacts/index.ts");
-    const { autoCleanEventV3Archives } = await import("../events/v3/archive-retention.ts");
-    const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import(
-      "../storage/maintenance-providers.ts"
+async function handleSessionStarted(run: HookRun): Promise<void> {
+  const { coordRoot, adapter, behavior, payload, owner, sessionId, data } = run;
+  // A configured backup runs out of process and is freshness-gated per host.
+  // Startup never waits for restic or a remote provider; the child owns no
+  // hook stdio, so the harness is not held open until it finishes. A failed
+  // previous run surfaces as one line in this session's context.
+  let backupCue = "";
+  try {
+    backupCue = scheduleBackupSnapshot(coordRoot).cue ?? "";
+  } catch (err) {
+    logError(coordRoot, err, { phase: "backup-schedule" });
+  }
+  // Effect (journal-maintaining adapters): prune stale journal archives +
+  // sweep orphans. The recovery-cue is merged into the session-start
+  // additionalContext inside emitSessionStartSystemMessage.
+  if (behavior.journalMaintenance) journalJanitor(coordRoot);
+  imageJanitor(coordRoot);
+  // Session start is the only caller of the artifact janitor and the storage
+  // maintenance pass, so both load here instead of on every tool call.
+  const { autoCleanArtifacts } = await import("../artifacts/index.ts");
+  const { autoCleanEventV3Archives } = await import("../events/v3/archive-retention.ts");
+  const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import(
+    "../storage/maintenance-providers.ts"
+  );
+  // 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) {
+    logError(coordRoot, err, { phase: "artifact-auto-clean" });
+  }
+  // Effect: apply the same daily throttle to closed V3 epochs. The newest
+  // recovery epochs remain protected by the archive retention policy.
+  try {
+    autoCleanEventV3Archives(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "event-v3-archive-auto-clean" });
+  }
+  // Plan one bounded, claim-first global slice from cached pressure only.
+  // Existing owner janitors above remain the only active executors until
+  // each provider receives a separate production activation.
+  try {
+    await runAutomaticMaintenancePass(
+      createAutomaticMaintenanceComposition(coordRoot, {
+        journal: () => {
+          if (behavior.journalMaintenance) journalJanitor(coordRoot);
+        },
+        images: () => imageJanitor(coordRoot),
+        artifacts: () => autoCleanArtifacts(coordRoot),
+      }),
     );
-    // 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.
-    try {
-      autoCleanArtifacts(coordRoot);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "artifact-auto-clean" });
-    }
-    // Effect: apply the same daily throttle to closed V3 epochs. The newest
-    // recovery epochs remain protected by the archive retention policy.
-    try {
-      autoCleanEventV3Archives(coordRoot);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "event-v3-archive-auto-clean" });
-    }
-    // Plan one bounded, claim-first global slice from cached pressure only.
-    // Existing owner janitors above remain the only active executors until
-    // each provider receives a separate production activation.
-    try {
-      await runAutomaticMaintenancePass(
-        createAutomaticMaintenanceComposition(coordRoot, {
-          journal: () => {
-            if (adapter === "claude-code") journalJanitor(coordRoot);
-          },
-          images: () => imageJanitor(coordRoot),
-          artifacts: () => autoCleanArtifacts(coordRoot),
-        }),
-      );
-    } catch (err) {
-      logError(coordRoot, err, { phase: "storage-maintenance-auto" });
-    }
-    let recovery: PreparedContextRecovery | null = null;
-    if (payload?.source === "compact") {
-      try {
-        markContextCompactionCompleted(coordRoot, {
-          sessionId,
-          instanceId: owner.instance_id,
-        });
-        recovery = prepareContextRecovery(coordRoot, {
-          instanceId: owner.instance_id,
-          sessionId,
-          cwd: payload?.cwd ?? process.cwd(),
-        });
-      } catch (err) {
-        logError(coordRoot, err, { phase: "context-recovery-session-start" });
-      }
-    }
+  } catch (err) {
+    logError(coordRoot, err, { phase: "storage-maintenance-auto" });
+  }
+  let recovery: PreparedContextRecovery | null = null;
+  if (payload?.source === "compact") {
     try {
-      const injected = await emitSessionStartSystemMessage(
-        coordRoot,
-        owner.instance_id,
+      markContextCompactionCompleted(coordRoot, {
         sessionId,
-        data,
-        adapter,
-        recovery?.briefing ?? "",
-        backupCue,
-      );
-      if (injected && recovery) {
-        completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
-      }
+        instanceId: owner.instance_id,
+      });
+      recovery = prepareContextRecovery(coordRoot, {
+        instanceId: owner.instance_id,
+        sessionId,
+        cwd: payload?.cwd ?? process.cwd(),
+      });
     } catch (err) {
-      logError(coordRoot, err, { phase: "session-start-systemMessage" });
+      logError(coordRoot, err, { phase: "context-recovery-session-start" });
     }
-    // Cross-machine presence is derived from the authority-safe V3 projection,
-    // not the disposable heartbeat cache. Announce this session, pull peers,
-    // and keep the optional live relay connected.
-    try {
-      publishPresence(coordRoot);
-      fetchPresence(coordRoot);
-      ensureRelayDaemon(coordRoot);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "session-start-presence" });
+  }
+  try {
+    const injected = await emitSessionStartSystemMessage(
+      coordRoot,
+      owner.instance_id,
+      sessionId,
+      data,
+      adapter,
+      recovery?.briefing ?? "",
+      backupCue,
+    );
+    if (injected && recovery) {
+      completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
     }
+  } catch (err) {
+    logError(coordRoot, err, { phase: "session-start-systemMessage" });
   }
+  // Cross-machine presence is derived from the authority-safe V3 projection,
+  // not the disposable heartbeat cache. Announce this session, pull peers,
+  // and keep the optional live relay connected.
+  try {
+    publishPresence(coordRoot);
+    fetchPresence(coordRoot);
+    ensureRelayDaemon(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "session-start-presence" });
+  }
+}
 
-  // Phase 8: SessionEnd cleanup: delete heartbeat + pid-map rows. Adapter-
-  // agnostic since v0.5.0.
-  if (norm.event_type === "session.ended") {
-    try {
-      cleanupSessionEnd(coordRoot, owner.instance_id);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "session-end-cleanup" });
-    }
-    // Effects (claude-code): archive the ending agent's journal + force a
-    // session-telemetry sync (via HARNERY_CLAUDE_SESSIONS_FORCE=1).
-    if (adapter === "claude-code") {
-      journalArchive(coordRoot, owner.instance_id);
-      runSessionSyncExtension(coordRoot, true);
-    }
-    // Publish the post-cleanup V3 projection so remote machines see this
-    // session disappear without waiting for the stale window.
-    try {
-      publishPresence(coordRoot);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "session-end-presence" });
-    }
+function handleSessionEnded(run: HookRun): void {
+  const { coordRoot, behavior, owner } = run;
+  try {
+    cleanupSessionEnd(coordRoot, owner.instance_id);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "session-end-cleanup" });
+  }
+  // Effects: archive the ending agent's journal + force a session-telemetry
+  // sync (via HARNERY_CLAUDE_SESSIONS_FORCE=1), each gated by the behavior.
+  if (behavior.journalMaintenance) journalArchive(coordRoot, owner.instance_id);
+  if (behavior.sessionTelemetrySync) runSessionSyncExtension(coordRoot, true);
+  // Publish the post-cleanup V3 projection so remote machines see this
+  // session disappear without waiting for the stale window.
+  try {
+    publishPresence(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "session-end-presence" });
   }
+}
 
-  // Phase 8: SubagentStart: the child generation was opened above from the
-  // native delegation identity. Refresh its disposable projection, log the
-  // lifecycle event, and emit a context message announcing the subagent.
-  if (norm.event_type === "agent.started") {
-    try {
-      const childInstanceId = (data.agent_id as string | undefined) ?? owner.instance_id;
-      await emitSubagentStartContext(coordRoot, childInstanceId, sessionId, data, adapter);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "subagent-start-context" });
-    }
+async function handleAgentStarted(run: HookRun): Promise<void> {
+  const { coordRoot, adapter, owner, sessionId, data } = run;
+  try {
+    const childInstanceId = (data.agent_id as string | undefined) ?? owner.instance_id;
+    await emitSubagentStartContext(coordRoot, childInstanceId, sessionId, data, adapter);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "subagent-start-context" });
   }
+}
 
-  // Phase 8: SubagentStop: delete subagent heartbeat + log.
-  if (norm.event_type === "agent.completed") {
-    try {
-      const childInstanceId = payload?.subagent_id ?? payload?.agent_id ?? owner.instance_id;
-      cleanupSessionEnd(coordRoot, childInstanceId);
-      const { reconcileSessionFinalizationV3 } = await import("../agents/session-finalizer-v3.ts");
-      reconcileSessionFinalizationV3(coordRoot, { archive_observations: [] });
-    } catch (err) {
-      logError(coordRoot, err, { phase: "subagent-stop-cleanup" });
-    }
+async function handleAgentCompleted(run: HookRun): Promise<void> {
+  const { coordRoot, payload, owner } = run;
+  try {
+    const childInstanceId = payload?.subagent_id ?? payload?.agent_id ?? owner.instance_id;
+    cleanupSessionEnd(coordRoot, childInstanceId);
+    const { reconcileSessionFinalizationV3 } = await import("../agents/session-finalizer-v3.ts");
+    reconcileSessionFinalizationV3(coordRoot, { archive_observations: [] });
+  } catch (err) {
+    logError(coordRoot, err, { phase: "subagent-stop-cleanup" });
   }
+}
 
-  // Phase 8: UserPromptSubmit: render dedup'd peer table + council pending
-  // and emit the adapter-shaped systemMessage JSON. Adapter-agnostic since v0.5.0.
-  if (norm.event_type === "turn.started") {
-    // Effects (claude-code): reset per-turn sound rate-limit counters + run
-    // presence detection on the prompt.
-    if (adapter === "claude-code") {
-      resetSoundCounters(sessionId);
-      const prompt = (payload?.raw?.prompt as string | undefined) ?? "";
-      if (prompt) detectPresence(prompt);
-    }
-    // Presence: throttled pull of peer machines' presence refs (default 60s
-    // interval; the systemMessage below reads whatever is locally known).
+async function handleTurnStarted(run: HookRun): Promise<void> {
+  const {
+    coordRoot,
+    adapter,
+    behavior,
+    payload,
+    owner,
+    sessionId,
+    debugBase,
+    topLevelSession,
+    stopRemediation,
+    v3EventId,
+  } = run;
+  // Effects: reset per-turn sound rate-limit counters + run presence
+  // detection on the prompt, each gated by the behavior.
+  if (behavior.soundEffects) resetSoundCounters(sessionId);
+  if (behavior.promptPresenceDetection) {
+    const prompt = (payload?.raw?.prompt as string | undefined) ?? "";
+    if (prompt) detectPresence(prompt);
+  }
+  // Presence: throttled pull of peer machines' presence refs (default 60s
+  // interval; the systemMessage below reads whatever is locally known).
+  try {
+    fetchPresence(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "user-prompt-submit-presence" });
+  }
+  let recovery: PreparedContextRecovery | null = null;
+  const continuityState = readContextState(coordRoot, sessionId);
+  if (
+    continuityState?.phase === "checkpointed" &&
+    continuityState.compaction_completed_at !== undefined
+  ) {
     try {
-      fetchPresence(coordRoot);
+      recovery = prepareContextRecovery(coordRoot, {
+        instanceId: owner.instance_id,
+        sessionId,
+        cwd: payload?.cwd ?? process.cwd(),
+      });
     } catch (err) {
-      logError(coordRoot, err, { phase: "user-prompt-submit-presence" });
-    }
-    let recovery: PreparedContextRecovery | null = null;
-    const continuityState = readContextState(coordRoot, sessionId);
-    if (
-      continuityState?.phase === "checkpointed" &&
-      continuityState.compaction_completed_at !== undefined
-    ) {
-      try {
-        recovery = prepareContextRecovery(coordRoot, {
-          instanceId: owner.instance_id,
-          sessionId,
-          cwd: payload?.cwd ?? process.cwd(),
-        });
-      } catch (err) {
-        logError(coordRoot, err, { phase: "context-recovery-user-prompt" });
-      }
-    }
-    let hostPromptContext = "";
-    const hostPromptEnabled = hostPromptContextConfig(coordRoot)?.enabled === true;
-    if (hostPromptEnabled && topLevelSession && !stopRemediation) {
-      try {
-        const { runPromptContext } = await import("./prompt-context/runner.ts");
-        const result = await runPromptContext({
-          coordRoot,
-          adapter,
-          sessionId,
-          turnId: payload?.turn_id ?? v3EventId ?? sessionId,
-          cwd: payload?.cwd ?? process.cwd(),
-          prompt: payload?.prompt ?? "",
-        });
-        appendDebug(coordRoot, {
-          ...debugBase,
-          effect: "prompt-context",
-          ...result.audit,
-        });
-        hostPromptContext = result.context ?? "";
-      } catch (err) {
-        logError(coordRoot, err, { phase: "prompt-context-user-prompt" });
-      }
+      logError(coordRoot, err, { phase: "context-recovery-user-prompt" });
     }
+  }
+  let hostPromptContext = "";
+  const hostPromptEnabled = hostPromptContextConfig(coordRoot)?.enabled === true;
+  if (hostPromptEnabled && topLevelSession && !stopRemediation) {
     try {
-      const injected = await emitUserPromptSubmitSystemMessage(
+      const { runPromptContext } = await import("./prompt-context/runner.ts");
+      const result = await runPromptContext({
         coordRoot,
-        owner.instance_id,
-        sessionId,
         adapter,
-        payload?.cwd,
-        recovery?.briefing ?? "",
-        hostPromptContext,
-      );
-      if (injected && recovery) {
-        completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
-      }
+        sessionId,
+        turnId: payload?.turn_id ?? v3EventId ?? sessionId,
+        cwd: payload?.cwd ?? process.cwd(),
+        prompt: payload?.prompt ?? "",
+      });
+      appendDebug(coordRoot, {
+        ...debugBase,
+        effect: "prompt-context",
+        ...result.audit,
+      });
+      hostPromptContext = result.context ?? "";
     } catch (err) {
-      logError(coordRoot, err, { phase: "user-prompt-submit-systemMessage" });
+      logError(coordRoot, err, { phase: "prompt-context-user-prompt" });
     }
   }
-
-  // turn.completed: telemetry, then the stop verdict. The
-  // verdict + codex-replay previously lived in the per-adapter shell adapters;
-  // agent-hook owns them now. Runs on the normal "stop" event only;
-  // "stop-failure" (API error) gets no gate, matching the previous
-  // stop vs stop-failure split.
-  if (norm.event_type === "turn.completed" && eventName === "stop") {
-    // Claude Code session telemetry sync remains an independent side effect.
-    if (adapter === "claude-code") {
-      runSessionSyncExtension(coordRoot, false);
-    }
-
-    // Publish after the canonical turn event has landed so the blob carries
-    // current task, activity, and claim state. Re-ensure the relay here because
-    // its daemon intentionally exits when a machine has no live sessions.
-    try {
-      publishPresence(coordRoot);
-      ensureRelayDaemon(coordRoot);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "stop-presence" });
-    }
-
-    // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
-    // rule lives in Harnery. agent-hook already emitted this turn.completed
-    // with privacy-safe ritual observations, so the evidence is in the stream.
-    const verdict = evaluateStopHook(coordRoot, {
-      rule: "stop-hook",
-      instance_id: owner.instance_id,
-      session_id: sessionId,
+  try {
+    const injected = await emitUserPromptSubmitSystemMessage(
+      coordRoot,
+      owner.instance_id,
+      sessionId,
       adapter,
-      stop_hook_active: payload?.stop_hook_active === true,
-      status_box_present_strict: data.status_box_present_strict === true,
-      bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
-      workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
-    });
-    if (!verdict.allow) {
-      // Backstop for sessions whose evidence can never land (e.g. a headless
-      // child whose status command resolves to a different owner): after
-      // `cap` consecutive blocked stops in one cycle, allow the stop instead
-      // of bouncing the model forever. Cycle boundaries come from the
-      // adapter's continuation flag, so adapters without one are unaffected.
-      const { recordRemediationBlock } = await import("./remediation-cap.ts");
-      const remediation = recordRemediationBlock(sessionId, payload?.stop_hook_active === true);
-      if (remediation.exceeded) {
-        appendDebug(coordRoot, {
-          ...debugBase,
-          skipped: "stop-remediation-cap-exhausted",
-          blocked_rule: verdict.rule,
-          blocked_count: remediation.count,
-          session_id: sessionId,
-          remediation_cycle_anchor: verdict.remediation_cycle_anchor,
-        });
-      } else {
-        // Adapter-aware enforcement channel: Claude Code honors exit-2 + stderr
-        // as a turn block; Cursor ignores exit codes and re-prompts only via a
-        // `followup_message` it auto-submits.
-        const { emitStopOutcome } = await import("./adapter/output.ts");
-        return emitStopOutcome(adapter, { verdict }, coordRoot);
-      }
-    } else {
-      const { clearRemediationCount } = await import("./remediation-cap.ts");
-      clearRemediationCount(sessionId);
+      payload?.cwd,
+      recovery?.briefing ?? "",
+      hostPromptContext,
+    );
+    if (injected && recovery) {
+      completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
     }
+  } catch (err) {
+    logError(coordRoot, err, { phase: "user-prompt-submit-systemMessage" });
+  }
+}
 
-    // An explicit end requested from inside this turn cannot be authoritative
-    // until the adapter has committed turn.completed above. Reconcile only
-    // when such a request exists; any later real work cancels it in the
-    // finalizer instead of being terminated underneath the agent.
-    try {
-      const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import(
-        "../agents/session-finalizer-v3.ts"
-      );
-      if (hasPendingExplicitSessionEndV3(coordRoot)) {
-        reconcileSessionFinalizationV3(coordRoot);
-      }
-    } catch (err) {
-      logError(coordRoot, err, { phase: "stop-explicit-session-finalization" });
-    }
-    if (adapter === "codex") scheduleCodexRuntimeContextRetry(coordRoot, sessionId);
+async function handleStop(run: HookRun): Promise<number | undefined> {
+  const { coordRoot, adapter, behavior, payload, owner, sessionId, data, debugBase } = run;
+  // Session telemetry sync remains an independent side effect.
+  if (behavior.sessionTelemetrySync) runSessionSyncExtension(coordRoot, false);
+
+  // Publish after the canonical turn event has landed so the blob carries
+  // current task, activity, and claim state. Re-ensure the relay here because
+  // its daemon intentionally exits when a machine has no live sessions.
+  try {
+    publishPresence(coordRoot);
+    ensureRelayDaemon(coordRoot);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "stop-presence" });
   }
 
-  // Phase 7: PreToolUse: heartbeat + pid-map self-heal on every tool call.
-  // Adapter-agnostic: both writes have the same shape regardless of who fired.
-  // Cursor/Codex bash dispatchers still fire their own G-guard logic, but the
-  // heals here keep the agent-coord layer's view of liveness fresh.
-  //
-  // The heartbeat + pid-map heals are paired by design; they were wired
-  // side-by-side in the previous pre-tool-use adapter. The Phase 4-6 refactor
-  // preserved the heartbeat half but dropped the pid-map half; the pid-map
-  // call was restored here afterward.
-  if (norm.event_type === "tool.requested") {
-    try {
-      // Recorded fork lineage, heal-path flavor. A forked CC conversation
-      // never fires its own session.started (SessionStart fires under the
-      // PARENT's session id with source=resume, before the fork id is
-      // minted; verified 2026-08-05), so the fork's new instance first
-      // materializes right here. Gate detection on "no heartbeat yet" so the
-      // transcript scan runs once per instance lifetime, not per tool call.
-      refreshPidmap(coordRoot, owner.instance_id, adapter, payload?.pid);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "pre-tool-use-heal" });
+  // Stop verdict (V3 ritual + task/status gate). Direct in-process call: the
+  // rule lives in Harnery. agent-hook already emitted this turn.completed
+  // with privacy-safe ritual observations, so the evidence is in the stream.
+  const verdict = evaluateStopHook(coordRoot, {
+    rule: "stop-hook",
+    instance_id: owner.instance_id,
+    session_id: sessionId,
+    adapter,
+    stop_hook_active: payload?.stop_hook_active === true,
+    status_box_present_strict: data.status_box_present_strict === true,
+    session_name_observation_unavailable: typeof data.session_name_unavailable_reason === "string",
+    bypass: coordEnv("AGENT_COORD_BYPASS_STOP") === "1",
+    workflow_child: coordEnv("WORKFLOW_CHILD") === "1",
+  });
+  if (!verdict.allow) {
+    // Backstop for sessions whose evidence can never land (e.g. a headless
+    // child whose status command resolves to a different owner): after
+    // `cap` consecutive blocked stops in one cycle, allow the stop instead
+    // of bouncing the model forever. Cycle boundaries come from the
+    // adapter's continuation flag, so adapters without one are unaffected.
+    const { recordRemediationBlock } = await import("./remediation-cap.ts");
+    const remediation = recordRemediationBlock(sessionId, payload?.stop_hook_active === true);
+    if (remediation.exceeded) {
+      appendDebug(coordRoot, {
+        ...debugBase,
+        skipped: "stop-remediation-cap-exhausted",
+        blocked_rule: verdict.rule,
+        blocked_count: remediation.count,
+        session_id: sessionId,
+        remediation_cycle_anchor: verdict.remediation_cycle_anchor,
+      });
+    } else {
+      // Adapter-aware enforcement channel: Claude Code honors exit-2 + stderr
+      // as a turn block; Cursor ignores exit codes and re-prompts only via a
+      // `followup_message` it auto-submits.
+      const { emitStopOutcome } = await import("./adapter/output.ts");
+      return emitStopOutcome(adapter, { verdict }, coordRoot);
     }
+  } else {
+    const { clearRemediationCount } = await import("./remediation-cap.ts");
+    clearRemediationCount(sessionId);
+  }
 
-    // The suggested name is a pending display latch. The set-task call itself
-    // runs before a name exists; every later tool waits until the exact block
-    // is the first assistant text after the mint result. Cursor supplies
-    // agent_message directly; Claude Code and Codex are resolved from their
-    // JSONL transcripts. Cursor's current narration can provide positive
-    // evidence, but cannot disprove an earlier response; afterAgentResponse
-    // stamps that durable sighting. Later commentary must not erase an
-    // already-correct display, and unavailable evidence must not deadlock
-    // every tool.
-    try {
-      const displayAllowed = await enforcePendingSessionNameDisplay(
-        coordRoot,
-        owner.instance_id,
-        adapter,
-        payload,
-        generationBoundHeartbeat(readHeartbeat(coordRoot, owner.instance_id), recordedGenerationId),
-      );
-      if (!displayAllowed) return 0;
-    } catch (err) {
-      logError(coordRoot, err, { phase: "pre-tool-use-session-name" });
+  // An explicit end requested from inside this turn cannot be authoritative
+  // until the adapter has committed turn.completed above. Reconcile only
+  // when such a request exists; any later real work cancels it in the
+  // finalizer instead of being terminated underneath the agent.
+  try {
+    const { hasPendingExplicitSessionEndV3, reconcileSessionFinalizationV3 } = await import(
+      "../agents/session-finalizer-v3.ts"
+    );
+    if (hasPendingExplicitSessionEndV3(coordRoot)) {
+      reconcileSessionFinalizationV3(coordRoot);
     }
+  } catch (err) {
+    logError(coordRoot, err, { phase: "stop-explicit-session-finalization" });
+  }
+  if (behavior.runtimeContextRetry) scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+  return undefined;
+}
 
-    // Windows-native Codex + WSL UNC only: block the one cross-shell shape
-    // proven to corrupt argument boundaries. Normal WSL argv calls, literal
-    // bash -s scripts, native Linux/macOS sessions, and every other adapter
-    // pass through. The host instructions name its concrete safe bridge.
-    const unsafeShellReason = unsafeCrossShellReason({
+async function handleToolRequested(run: HookRun): Promise<number | undefined> {
+  const { coordRoot, adapter, behavior, payload, owner, sessionId, data, recordedGenerationId } =
+    run;
+  try {
+    // Recorded fork lineage, heal-path flavor. A forked CC conversation
+    // never fires its own session.started (SessionStart fires under the
+    // PARENT's session id with source=resume, before the fork id is
+    // minted; verified 2026-08-05), so the fork's new instance first
+    // materializes right here. Gate detection on "no heartbeat yet" so the
+    // transcript scan runs once per instance lifetime, not per tool call.
+    refreshPidmap(coordRoot, owner.instance_id, adapter, payload?.pid);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "pre-tool-use-heal" });
+  }
+
+  // The suggested name is a pending display latch. The set-task call itself
+  // runs before a name exists; every later tool waits until the exact block
+  // is the first assistant text after the mint result. Cursor supplies
+  // agent_message directly; Claude Code and Codex are resolved from their
+  // JSONL transcripts. Cursor's current narration can provide positive
+  // evidence, but cannot disprove an earlier response; afterAgentResponse
+  // stamps that durable sighting. Later commentary must not erase an
+  // already-correct display, and unavailable evidence must not deadlock
+  // every tool.
+  try {
+    const displayAllowed = await enforcePendingSessionNameDisplay(
+      coordRoot,
+      owner.instance_id,
       adapter,
+      payload,
+      generationBoundHeartbeat(readHeartbeat(coordRoot, owner.instance_id), recordedGenerationId),
+    );
+    if (!displayAllowed) return 0;
+  } catch (err) {
+    logError(coordRoot, err, { phase: "pre-tool-use-session-name" });
+  }
+
+  // Windows-native Codex + WSL UNC only: block the one cross-shell shape
+  // proven to corrupt argument boundaries. Normal WSL argv calls, literal
+  // bash -s scripts, native Linux/macOS sessions, and every other adapter
+  // pass through. The host instructions name its concrete safe bridge.
+  const unsafeShellReason =
+    behavior.unsafeCrossShellReason?.({
       cwd: payload?.cwd,
       toolName: payload?.tool_name,
       toolInput: payload?.tool_input,
-    });
-    if (unsafeShellReason) {
-      const { emitDeny } = await import("./adapter/output.ts");
-      emitDeny(adapter, unsafeShellReason);
-      return 0;
-    }
+    }) ?? null;
+  if (unsafeShellReason) {
+    const { emitDeny } = await import("./adapter/output.ts");
+    emitDeny(adapter, unsafeShellReason);
+    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.
-    // emitDeny() inside emits the adapter-shaped permission JSON (claude-code +
-    // codex use hookSpecificOutput.permissionDecision; cursor uses .permission).
-    // apply_patch (codex) parses paths from the patch body and runs verdict
-    // per-path; Edit/Write/NotebookEdit resolve a single target. Non-write tools
-    // (incl. Agent) yield no targets and pass through with no deny.
-    let guardAllowed = true;
-    try {
-      guardAllowed = await runPreToolUseGuard(
-        coordRoot,
-        owner.instance_id,
-        sessionId,
-        data,
-        adapter,
-      );
-    } catch (err) {
-      logError(coordRoot, err, { phase: "pre-tool-use-guard" });
-    }
-    if (!guardAllowed) return 0;
+  const waiterReason = shellWaiterReason(payload?.tool_name, payload?.tool_input);
+  if (waiterReason) {
+    const { emitDeny } = await import("./adapter/output.ts");
+    emitDeny(adapter, waiterReason);
+    return 0;
   }
 
-  if (norm.event_type === "tool.completed" && eventName === "post-tool-use") {
-    // Inject only at the successful tool boundary that actually minted or
-    // retried a name: the first non-empty set-task, a pending-name set-task
-    // retry, or the transition to lifecycle done. The
-    // coordination row intentionally remains pending until transcript evidence
-    // catches up; reading that latch alone here would re-inject after every
-    // later tool and make the agent print the same block repeatedly.
-    try {
-      const name = sessionNameDisplayPending(readLiveCoordinationRow(coordRoot, owner.instance_id));
-      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
-        // rebuilt cache), and the agent must not be stranded for displaying
-        // exactly what it was handed.
-        stampSessionNameRequested(coordRoot, owner.instance_id, name);
+  // 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.
+  // emitDeny() inside emits the adapter-shaped permission JSON (claude-code +
+  // codex use hookSpecificOutput.permissionDecision; cursor uses .permission).
+  // apply_patch (codex) parses paths from the patch body and runs verdict
+  // per-path; Edit/Write/NotebookEdit resolve a single target. Non-write tools
+  // (incl. Agent) yield no targets and pass through with no deny.
+  let guardAllowed = true;
+  try {
+    guardAllowed = await runPreToolUseGuard(coordRoot, owner.instance_id, sessionId, data, adapter);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "pre-tool-use-guard" });
+  }
+  if (!guardAllowed) return 0;
+  return undefined;
+}
+
+async function handlePostToolUse(run: HookRun): Promise<void> {
+  const { coordRoot, adapter, eventName, payload, owner } = run;
+  // Inject the full instruction only at the successful tool boundary that
+  // actually minted or retried a name: the first non-empty set-task, a
+  // pending-name set-task retry, or the transition to lifecycle done. The
+  // coordination row intentionally remains pending until transcript evidence
+  // catches up, so the latch alone cannot drive injection: that would print
+  // the same block after every later tool.
+  //
+  // Between those two extremes sits a bounded reminder. Since ADR 0182 the
+  // PreToolUse gate allows a tool when transcript evidence is unavailable
+  // and says so only on stderr, which the model never reads. A model that
+  // skipped the block after the mint was therefore never asked again
+  // (ADR 0183). While the requested title is still pending, ordinary tool
+  // results carry an idempotent reminder up to a fixed count; coordination
+  // chores (set-task, status, suggest-name) are skipped because a mint or
+  // retry response already carries the full instruction and an end-turn
+  // status is the wrong place to ask.
+  try {
+    const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
+    // 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
+      // rebuilt cache), and the agent must not be stranded for displaying
+      // exactly what it was handed.
+      stampSessionNameRequested(coordRoot, owner.instance_id, name);
+      const { emitContext } = await import("./adapter/output.ts");
+      emitContext(adapter, "PostToolUse", sessionNameDisplayInstruction(name));
+    } else if (name) {
+      const due = sessionNameDisplayReminderDue(row);
+      const command = extractBashCommand(payload?.tool_name, payload?.tool_input);
+      if (due && !isSessionNameRemediationCommand(command, resolveBinName(coordRoot))) {
+        stampSessionNameReminded(coordRoot, owner.instance_id, due);
+        appendDebug(coordRoot, {
+          ts: new Date().toISOString(),
+          event_name: eventName,
+          adapter,
+          instance_id: owner.instance_id,
+          effect: "session-name-display-reminded",
+          session_name_pending: due,
+          reminders: (row?.session_name_display_reminders ?? 0) + 1,
+        });
         const { emitContext } = await import("./adapter/output.ts");
-        emitContext(adapter, "PostToolUse", sessionNameDisplayInstruction(name));
+        emitContext(adapter, "PostToolUse", sessionNameDisplayReminder(due));
       }
-    } catch (err) {
-      logError(coordRoot, err, { phase: "post-tool-use-session-name" });
     }
+  } catch (err) {
+    logError(coordRoot, err, { phase: "post-tool-use-session-name" });
   }
+}
 
-  // Phase 7: PostToolUseFailure: release claim on failed Edit (the file
-  // never landed; the claim is stale). Adapter-agnostic.
-  if (norm.event_type === "tool.completed" && eventName === "post-tool-use-failure") {
-    try {
-      releaseClaimOnFailure(coordRoot, owner.instance_id, data, payload?.raw);
-    } catch (err) {
-      logError(coordRoot, err, { phase: "post-tool-use-failure-release" });
-    }
+function handlePostToolUseFailure(run: HookRun): void {
+  const { coordRoot, payload, owner, data } = run;
+  try {
+    releaseClaimOnFailure(coordRoot, owner.instance_id, data, payload?.raw);
+  } catch (err) {
+    logError(coordRoot, err, { phase: "post-tool-use-failure-release" });
   }
+}
 
+async function handleCompletedResponse(run: CompletedResponseRun): Promise<number> {
+  const { coordRoot, adapter, eventName, raw, debugBase, ledgerRoute, hookStartedAt, hookClock } =
+    run;
+  const payload = parsePayload(raw, adapter);
+  const owner = resolveOwner({ payload: payload?.raw ?? null, coordRoot });
+  if (!owner) {
+    appendDebug(coordRoot, { ...debugBase, skipped: "no-owner-resolved" });
+    return 0;
+  }
+  const row = readLiveCoordinationRow(coordRoot, owner.instance_id);
+  const name = sessionNameDisplayPending(row);
+  const text = typeof payload?.raw.text === "string" ? payload.raw.text : "";
+  const sighting = matchSessionNameDisplay(row, text);
+  if (sighting) {
+    stampSessionNameSeen(coordRoot, owner.instance_id, sighting.pending);
+    appendDebug(coordRoot, {
+      ...debugBase,
+      effect: "session-name-display-stamped",
+      session_name_pending: sighting.pending,
+      ...(sighting.displayed === sighting.pending
+        ? {}
+        : { session_name_displayed: sighting.displayed, session_name_drift: true }),
+    });
+  } else if (!name) {
+    // Nothing was owed. Distinct from a miss: conflating the two is what made
+    // a latched Cursor session undiagnosable from this log.
+    appendDebug(coordRoot, { ...debugBase, skipped: "no-pending-session-name" });
+  } else {
+    appendDebug(coordRoot, {
+      ...debugBase,
+      skipped: "session-name-block-absent",
+      session_name_pending: name,
+      reply_bytes: text.length,
+      reply_leads_with_fence: /^\s*`{3,}/.test(text),
+    });
+  }
+  if (ledgerRoute.state === "blocked") {
+    appendDebug(coordRoot, {
+      ...debugBase,
+      skipped: "v3-control-blocked",
+      reason: ledgerRoute.reason,
+      owner_source: owner.source,
+    });
+    return 0;
+  }
+  const statusBoxPresentStrict = scanAssistantStatusBoxPresent(undefined, text);
+  // The hook parser needs the completed reply long enough to scan it, but
+  // durable hook intake must never retain that body. Keep every other native
+  // field so turn correlation remains available to the producer.
+  const { text: _completedReply, ...privacySafeRaw } = payload?.raw ?? {};
+  const privacySafePayload = payload ? { ...payload, raw: privacySafeRaw } : null;
+  const v3Result = recordLiveHookSignalV3({
+    coordRoot,
+    route: ledgerRoute,
+    eventName,
+    payload: privacySafePayload,
+    adapter,
+    instanceId: owner.instance_id,
+    hook_name: eventName,
+    hook_duration_ms: Math.max(0, Math.floor(performance.now() - hookStartedAt)),
+    monotonic_ns: hookClock.monotonic_ns,
+    turn_ritual: {
+      status_box_present: statusBoxPresentStrict,
+      status_box_present_strict: statusBoxPresentStrict,
+      session_name_required: name !== undefined,
+      session_name_present: name ? assistantTextStartsWithSessionNameBlock(text, name) : false,
+    },
+  });
+  observeHookDebug(hookHealthState, { event_v3_state: v3Result.state });
+  appendDebug(coordRoot, {
+    ...debugBase,
+    effect: "cursor-response-ritual-observed",
+    owner_source: owner.source,
+    event_v3_state: v3Result.state,
+    status_box_present_strict: statusBoxPresentStrict,
+    ...(v3Result.state === "observed"
+      ? {
+          generation_id: v3Result.generation_id,
+          turn_id: v3Result.turn_id,
+          response_observed_at: v3Result.observed_at,
+        }
+      : {}),
+  });
   return 0;
 }
 
-function scheduleCodexRuntimeContextRetry(coordRoot: string, nativeSessionId: string): void {
+function scheduleRuntimeContextRetry(
+  coordRoot: string,
+  adapter: Adapter,
+  nativeSessionId: string,
+): void {
   const modulePath = process.argv[1];
   if (!modulePath) return;
   try {
     const child = spawn(
       process.execPath,
-      [modulePath, "runtime-context-retry", "--adapter", "codex", "--session-id", nativeSessionId],
+      [modulePath, "runtime-context-retry", "--adapter", adapter, "--session-id", nativeSessionId],
       {
         cwd: coordRoot,
         detached: true,
@@ -1531,7 +1755,7 @@ async function runRuntimeContextRetryWorker(
   extra: string[],
 ): Promise<number> {
   const nativeSessionId = extraArg(extra, "--session-id");
-  if (adapter !== "codex" || !nativeSessionId) return 0;
+  if (!adapter || !adapterBehavior(adapter).runtimeContextRetry || !nativeSessionId) return 0;
   for (const [index, delayMs] of [400, 1_000].entries()) {
     await new Promise((resolve) => setTimeout(resolve, delayMs));
     const route = resolveLiveEventLedgerRouteV3(coordRoot);
@@ -1547,6 +1771,27 @@ async function runRuntimeContextRetryWorker(
   return 0;
 }
 
+function reportSessionNameObservationUnavailable(
+  coordRoot: string,
+  instanceId: string,
+  adapter: Adapter,
+  eventName: string,
+  reason: string,
+): void {
+  appendDebug(coordRoot, {
+    ts: new Date().toISOString(),
+    event_name: eventName,
+    adapter,
+    instance_id: instanceId,
+    effect: "session-name-observation-unavailable",
+    reason,
+    action: "fail-open",
+  });
+  process.stderr.write(
+    `Harnery: session-name observation unavailable (${reason}); allowing this ${eventName} without display enforcement. The name remains pending.\n`,
+  );
+}
+
 async function enforcePendingSessionNameDisplay(
   coordRoot: string,
   instanceId: string,
@@ -1554,6 +1799,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;
 
@@ -1567,11 +1813,13 @@ async function enforcePendingSessionNameDisplay(
   }
 
   if (inspection.state === "unavailable") {
-    // PostToolUse already delivered the exact block for this mint. An
-    // unavailable transcript cannot become evidence, and repeating a generic
-    // reminder on every tool creates an unbounded Codex loop. Keep the latch
-    // honestly pending and fail open without another instruction. A later
-    // readable transcript can still verify it.
+    reportSessionNameObservationUnavailable(
+      coordRoot,
+      instanceId,
+      adapter,
+      "pre-tool-use",
+      inspection.reason,
+    );
     return true;
   }
 
@@ -1605,21 +1853,20 @@ function inspectDisplayEvidence(
   payload: ParsedPayload | null,
   coordination: Heartbeat | null,
 ): SessionNameDisplayInspection {
-  if (adapter === "cursor" && payload?.agent_message !== undefined) {
-    return matchSessionNameDisplay(coordination, payload.agent_message)
+  const behavior = adapterBehavior(adapter);
+  const inlineText = behavior.inlineAssistantText?.(payload);
+  if (inlineText !== undefined) {
+    return matchSessionNameDisplay(coordination, inlineText)
       ? { state: "present" }
       : { state: "unavailable", reason: "transcript_not_ready" };
   }
 
-  // Codex hook payloads omit transcript_path on every event, which left this
-  // inspection permanently unavailable and the latch never stamped. Discover
-  // the rollout by session id; the scan only runs while a name is pending, so
-  // the latch closes after one success.
+  // Some adapters omit transcript_path on every event, which left this
+  // inspection permanently unavailable and the latch never stamped. The
+  // behavior may discover the transcript by session id; the scan only runs
+  // while a name is pending, so the latch closes after one success.
   const transcriptPath =
-    payload?.transcript_path ??
-    (adapter === "codex"
-      ? discoverCodexSessionTranscript(payload?.session_id ?? instanceId)
-      : undefined);
+    payload?.transcript_path ?? behavior.discoverTranscript?.(payload?.session_id ?? instanceId);
 
   let verdict: SessionNameDisplayInspection = { state: "absent" };
   for (const candidate of sessionNameDisplayAcceptedNames(coordination)) {
@@ -1913,7 +2160,7 @@ function releaseClaimOnFailure(
       coordRoot,
       owner: instanceId,
       nativeSessionId: before?.session_id ?? instanceId,
-      adapter: adapterFromPlatform(before?.platform),
+      adapter: sharedAdapterFromPlatform(before?.platform, { context: "hook-claim-release" }),
       operation: "released",
       path: canonical,
       access: "write",
@@ -1956,22 +2203,22 @@ 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({
     coordRoot,
     instanceId,
     sessionId,
     sessionNameNudge: true,
-    taskNudge: adapter === "cursor" || adapter === "codex",
-    hostPromptReminder: adapter === "codex" || adapter === "cursor",
-    statusFooterNudge: adapter === "codex",
-    turnRitualNudge: adapter === "claude-code" ? adapter : undefined,
+    ...behavior.promptContextNudges,
   }).trim();
-  if (adapter === "codex") {
-    const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, workspaceCwd);
-    if (fileLinkContext) {
-      additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
-    }
+  const fileLinkContext = behavior.fileLinkContext?.(coordRoot, workspaceCwd) ?? "";
+  if (fileLinkContext) {
+    additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
   }
   if (recoveryBriefing) {
     additionalContext = [additionalContext, recoveryBriefing].filter(Boolean).join("\n\n");
@@ -2022,16 +2269,9 @@ async function emitSubagentStartContext(
 }
 
 function adapterPlatform(adapter: Adapter): string {
-  if (adapter === "claude-code") return "claude-code";
   return adapter;
 }
 
-function adapterFromPlatform(platform: unknown): Adapter {
-  if (platform === "cursor") return "cursor";
-  if (platform === "codex") return "codex";
-  return "claude-code";
-}
-
 async function emitSessionStartSystemMessage(
   coordRoot: string,
   instanceId: string,
@@ -2041,6 +2281,7 @@ async function emitSessionStartSystemMessage(
   recoveryBriefing = "",
   backupCue = "",
 ): Promise<boolean> {
+  const behavior = adapterBehavior(adapter);
   const workflowChild = coordEnv("WORKFLOW_CHILD") === "1";
   let additionalContext = "";
   // Opportunistic reconciliation makes normal session starts a failsafe for
@@ -2061,16 +2302,15 @@ async function emitSessionStartSystemMessage(
       instanceId,
       sessionId,
       agentName: agentName || undefined,
-      platformLabel:
-        adapter === "claude-code" ? undefined : adapter === "cursor" ? "Cursor" : "Codex",
+      platformLabel: behavior.sessionStartPlatformLabel,
     }).trim();
   }
 
-  // Effect (claude-code): merge the journal recovery cue into the session-start
-  // context. Was a standalone additionalContext emission from the previous
-  // journal-on-start adapter; now that agent-hook is the single SessionStart
-  // entry, it folds in here.
-  if (adapter === "claude-code" && !workflowChild) {
+  // Effect (journal-maintaining adapters): merge the journal recovery cue into
+  // the session-start context. Was a standalone additionalContext emission
+  // from the previous journal-on-start adapter; now that agent-hook is the
+  // single SessionStart entry, it folds in here.
+  if (behavior.journalMaintenance && !workflowChild) {
     const cue = journalRecoveryCue(coordRoot);
     if (cue) additionalContext = [additionalContext, cue].filter(Boolean).join("\n\n");
   }
@@ -2080,19 +2320,14 @@ async function emitSessionStartSystemMessage(
   if (backupCue && !workflowChild) {
     additionalContext = [additionalContext, backupCue].filter(Boolean).join("\n\n");
   }
-  if (adapter === "codex" && !workflowChild && isWslUncPath(emittedData.cwd)) {
-    const fileLinkContext = renderCodexWslFileLinkContext(coordRoot, emittedData.cwd);
+  if (!workflowChild && behavior.bridgeFor(emittedData.cwd)) {
+    const fileLinkContext = behavior.fileLinkContext?.(coordRoot, emittedData.cwd) ?? "";
     if (fileLinkContext) {
       additionalContext = [additionalContext, fileLinkContext].filter(Boolean).join("\n\n");
     }
-    const bridge = inspectCodexWslBridge(process.env, { expected: true });
-    if (bridge && !bridge.ok) {
-      additionalContext = [
-        additionalContext,
-        `Harnery hybrid warning: ${bridge.detail}. Run \`${resolveBinName(coordRoot)} doctor\` for the repair hint.`,
-      ]
-        .filter(Boolean)
-        .join("\n\n");
+    const warning = behavior.bridgeWarning?.(coordRoot, emittedData.cwd);
+    if (warning) {
+      additionalContext = [additionalContext, warning].filter(Boolean).join("\n\n");
     }
   }
   const { emitContext } = await import("./adapter/output.ts");
@@ -2111,6 +2346,7 @@ function completeRecoveryInjection(
 
 main()
   .then(async (code) => {
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,
@@ -2125,6 +2361,7 @@ main()
       pid: process.pid,
       phase: "top-level",
     });
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
       finished_at_ms: performance.now(),
       finished_rss_bytes: process.memoryUsage().rss,