harnery 0.40.0 → 0.42.0

package/dist/core/hooks/cli.js

@@ -21,12 +21,13 @@ import { appendFileSync, existsSync, mkdirSync, readFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { coordEnv } from "../../lib/env.js";
 import { buildInstructionBundle } from "../../lib/instructions/bundle.js";
+import { adapterFromPlatform as sharedAdapterFromPlatform } from "../adapter.js";
 import { resolveCoordRoot } from "../agents/coord-client.js";
 import { classifyWriteClaimFinalization, formatWriteClaimFinalizationDenial, } from "../agents/finalization.js";
 import { recordLiveClaimChangeV3, restoreLiveCoordinationStateAfterEpochV3, } from "../agents/live-authority-v3.js";
 import { evaluateStopHook, STOP_REMEDIATION_MARKER } from "../agents/rules/stop-hook.js";
-import { assistantTextStartsWithSessionNameBlock, isSessionNameRemediationCommand, matchSessionNameDisplay, sessionNameDisplayAcceptedNames, sessionNameDisplayInstruction, sessionNameDisplayPending, sessionNameDisplayRecoveryInstruction, toolResponseMintedSessionName, } from "../agents/session-name-display.js";
-import { readHeartbeat, setAssignedNameCache, stampSessionNameRequested, stampSessionNameSeen, } from "../agents/state/heartbeat-writer.js";
+import { assistantTextStartsWithSessionNameBlock, isSessionNameRemediationCommand, matchSessionNameDisplay, sessionNameDisplayAcceptedNames, sessionNameDisplayInstruction, sessionNameDisplayPending, sessionNameDisplayRecoveryInstruction, sessionNameDisplayReminder, sessionNameDisplayReminderDue, toolResponseMintedSessionName, } from "../agents/session-name-display.js";
+import { readHeartbeat, setAssignedNameCache, stampSessionNameReminded, stampSessionNameRequested, stampSessionNameSeen, } from "../agents/state/heartbeat-writer.js";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.js";
 import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.js";
 import { assignName } from "../agents/state/names.js";
@@ -39,11 +40,12 @@ import { captureSpanClockV3 } from "../events/v3/span-state.js";
 import { ensureRelayDaemon, fetchPresence, publishPresence } from "../presence/index.js";
 import { closeProcessLoggers, legacyLogFields, processLogger } from "../storage/logger.js";
 import { stableScopeId } from "../workflow/scope-id.js";
+import { adapterBehavior } from "./adapter/behaviors/index.js";
 import { detectAdapter, shouldSkipHookAdapter } from "./adapter/detect.js";
+import { ADAPTER_SPECS } from "./adapter/events.js";
 import { extractBashCommand, extractToolDescription, normalizeEventName, parsePayload, } from "./adapter/parse.js";
-import { discoverCodexSessionTranscript } from "./adapter/runtime-telemetry.js";
+import { hookTimeoutFor } from "./adapter/wiring.js";
 import { scheduleBackupSnapshot } from "./backup-schedule.js";
-import { codexWslFileLinkTelemetry, inspectCodexWslBridge, isWslUncPath, renderCodexWslFileLinkContext, } from "./codex-wsl-bridge.js";
 import { captureImages, detectPresence, imageJanitor, journalArchive, journalJanitor, journalRecoveryCue, playSound, recordImageArtifactsV3, resetSoundCounters, runSessionSyncExtension, soundForEvent, } from "./effects/index.js";
 import { toolInputHash, toolTargetHash } from "./events/input-hash.js";
 import { canonicalize } from "./guard-path.js";
@@ -51,10 +53,12 @@ import { beginHookHealth, observeHookDebug, observeHookError, writeHookHealthCom
 import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/anchor.js";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.js";
 import { resolveOwner } from "./resolve/owner.js";
-import { inspectSessionNameDisplayImmediately, scanAssistantStatusBoxPresent, scanSessionNameDisplayedImmediately, scanStatusBoxPresent, scanTranscriptRuntime, } from "./resolve/transcript.js";
+import { inspectSessionNameDisplayImmediately, scanAssistantStatusBoxPresent, scanStatusBoxPresent, scanTranscriptRuntime, } from "./resolve/transcript.js";
+import { clearHookRunMarker, writeHookRunMarker } from "./run-markers.js";
 import { sessionNamePresence } from "./session-name-presence.js";
-import { unsafeCrossShellReason } from "./unsafe-cross-shell.js";
+import { shellWaiterReason } from "./shell-waiter.js";
 let hookHealthState;
+let hookRunMarkerPath = null;
 function parseArgv(argv) {
     const out = { eventName: null, extra: [] };
     for (let i = 0; i < argv.length; i++) {
@@ -223,11 +227,9 @@ function buildEventData(eventType, ctx) {
     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
@@ -238,7 +240,11 @@ function buildEventData(eventType, ctx) {
             const forkedFrom = 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),
@@ -301,7 +307,8 @@ function buildEventData(eventType, ctx) {
             // 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 ?? "";
@@ -310,9 +317,7 @@ function buildEventData(eventType, ctx) {
         }
         case "turn.completed": {
             const lastAssistantMessage = p?.raw.last_assistant_message ?? "";
-            const fileLinkTelemetry = ctx.adapter === "codex"
-                ? codexWslFileLinkTelemetry(ctx.coordRoot, p?.cwd, lastAssistantMessage)
-                : null;
+            const fileLinkTelemetry = 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
@@ -343,13 +348,12 @@ function buildEventData(eventType, ctx) {
                 // and which name that refers to. Reported on every stop while a name
                 // 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.
+                ...sessionNamePresence(ctx.coordRoot, ctx.instanceId, (name) => 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), name, assistantTextStartsWithSessionNameBlock)),
+                    adapterBehavior(ctx.adapter).discoverTranscript?.(p?.session_id ?? ctx.instanceId), name, assistantTextStartsWithSessionNameBlock)),
                 ...(fileLinkTelemetry ?? {}),
                 stop_hook_active: p?.stop_hook_active,
             };
@@ -479,6 +483,24 @@ async function main() {
     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,
@@ -516,8 +538,8 @@ async function main() {
     // 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());
@@ -568,7 +590,7 @@ async function main() {
         pid: process.pid,
         ppid: process.ppid,
     };
-    if (!eventName || !adapter) {
+    if (!eventName || !adapter || !behavior) {
         appendDebug(coordRoot, { ...debugBase, skipped: "missing-event-or-adapter" });
         return 0;
     }
@@ -579,90 +601,17 @@ async function main() {
     // 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);
     if (!norm) {
@@ -670,6 +619,7 @@ async function main() {
         return 0;
     }
     const payload = parsePayload(raw, adapter);
+    const bridge = behavior.bridgeFor(payload?.cwd);
     const owner = resolveOwner({
         payload: payload?.raw ?? null,
         coordRoot,
@@ -711,8 +661,14 @@ async function main() {
             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" &&
         data.prompt_text.includes(STOP_REMEDIATION_MARKER);
@@ -726,6 +682,86 @@ async function main() {
         });
         return 0;
     }
+    const run = {
+        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) {
+    const { coordRoot, adapter, eventName, norm, payload, owner, sessionId, data, debugBase, ledgerRoute, hookStartedAt, hookClock, priorCoordination, stopRemediation, bridge, turnRitual, } = run;
     let capturedImages = [];
     if (norm.event_type === "tool.requested" ||
         (norm.event_type === "tool.completed" && eventName === "post-tool-use")) {
@@ -753,7 +789,7 @@ async function main() {
                     : {}),
             }
             : {}),
-        ...(adapter === "codex" && isWslUncPath(payload?.cwd) ? { bridge: "codex-wsl" } : {}),
+        ...(bridge ? { bridge } : {}),
         hook_name: eventName,
         hook_duration_ms: Math.max(0, Math.floor(performance.now() - hookStartedAt)),
         monotonic_ns: hookClock.monotonic_ns,
@@ -806,9 +842,7 @@ async function main() {
                 parentEvent: v3Result.event,
                 payload,
                 adapter,
-                ...(adapter === "codex" && isWslUncPath(payload.cwd)
-                    ? { bridge: "codex-wsl" }
-                    : {}),
+                ...(bridge ? { bridge } : {}),
                 monotonic_ns: hookClock.monotonic_ns,
             });
             const nativeChild = payload.subagent_id ?? payload.agent_id;
@@ -851,6 +885,12 @@ async function main() {
         ...(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) {
+    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.
@@ -902,413 +942,519 @@ async function main() {
             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.js");
-        const { autoCleanEventV3Archives } = await import("../events/v3/archive-retention.js");
-        const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import("../storage/maintenance-providers.js");
-        // 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 = 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" });
-            }
-        }
-        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" });
-        }
+}
+async function handleSessionStarted(run) {
+    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 ?? "";
     }
-    // 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" });
-        }
+    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.js");
+    const { autoCleanEventV3Archives } = await import("../events/v3/archive-retention.js");
+    const { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import("../storage/maintenance-providers.js");
+    // 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);
     }
-    // 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") {
+    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),
+        }));
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "storage-maintenance-auto" });
+    }
+    let recovery = null;
+    if (payload?.source === "compact") {
         try {
-            const childInstanceId = data.agent_id ?? owner.instance_id;
-            await emitSubagentStartContext(coordRoot, childInstanceId, sessionId, data, adapter);
+            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: "subagent-start-context" });
+            logError(coordRoot, err, { phase: "context-recovery-session-start" });
         }
     }
-    // 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.js");
-            reconcileSessionFinalizationV3(coordRoot, { archive_observations: [] });
-        }
-        catch (err) {
-            logError(coordRoot, err, { phase: "subagent-stop-cleanup" });
+    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);
         }
     }
-    // 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 ?? "";
-            if (prompt)
-                detectPresence(prompt);
-        }
-        // Presence: throttled pull of peer machines' presence refs (default 60s
-        // interval; the systemMessage below reads whatever is locally known).
+    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" });
+    }
+}
+function handleSessionEnded(run) {
+    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" });
+    }
+}
+async function handleAgentStarted(run) {
+    const { coordRoot, adapter, owner, sessionId, data } = run;
+    try {
+        const childInstanceId = data.agent_id ?? owner.instance_id;
+        await emitSubagentStartContext(coordRoot, childInstanceId, sessionId, data, adapter);
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "subagent-start-context" });
+    }
+}
+async function handleAgentCompleted(run) {
+    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.js");
+        reconcileSessionFinalizationV3(coordRoot, { archive_observations: [] });
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "subagent-stop-cleanup" });
+    }
+}
+async function handleTurnStarted(run) {
+    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 ?? "";
+        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 = 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 = 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.js");
-                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(coordRoot, owner.instance_id, sessionId, adapter, payload?.cwd, recovery?.briefing ?? "", hostPromptContext);
-            if (injected && recovery) {
-                completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
-            }
+            const { runPromptContext } = await import("./prompt-context/runner.js");
+            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: "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);
+    try {
+        const injected = await emitUserPromptSubmitSystemMessage(coordRoot, owner.instance_id, sessionId, adapter, payload?.cwd, recovery?.briefing ?? "", hostPromptContext);
+        if (injected && recovery) {
+            completeRecoveryInjection(coordRoot, owner.instance_id, sessionId, recovery);
         }
-        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,
-            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.js");
-            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.js");
-                return emitStopOutcome(adapter, { verdict }, coordRoot);
-            }
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "user-prompt-submit-systemMessage" });
+    }
+}
+async function handleStop(run) {
+    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" });
+    }
+    // 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.js");
+        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 {
-            const { clearRemediationCount } = await import("./remediation-cap.js");
-            clearRemediationCount(sessionId);
-        }
-        // 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.js");
-            if (hasPendingExplicitSessionEndV3(coordRoot)) {
-                reconcileSessionFinalizationV3(coordRoot);
-            }
-        }
-        catch (err) {
-            logError(coordRoot, err, { phase: "stop-explicit-session-finalization" });
+            // 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.js");
+            return emitStopOutcome(adapter, { verdict }, coordRoot);
         }
-        if (adapter === "codex")
-            scheduleCodexRuntimeContextRetry(coordRoot, sessionId);
     }
-    // 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" });
-        }
-        // 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 = unsafeCrossShellReason({
-            adapter,
-            cwd: payload?.cwd,
-            toolName: payload?.tool_name,
-            toolInput: payload?.tool_input,
-        });
-        if (unsafeShellReason) {
-            const { emitDeny } = await import("./adapter/output.js");
-            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" });
+    else {
+        const { clearRemediationCount } = await import("./remediation-cap.js");
+        clearRemediationCount(sessionId);
+    }
+    // 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.js");
+        if (hasPendingExplicitSessionEndV3(coordRoot)) {
+            reconcileSessionFinalizationV3(coordRoot);
         }
-        if (!guardAllowed)
+    }
+    catch (err) {
+        logError(coordRoot, err, { phase: "stop-explicit-session-finalization" });
+    }
+    if (behavior.runtimeContextRetry)
+        scheduleRuntimeContextRetry(coordRoot, adapter, sessionId);
+    return undefined;
+}
+async function handleToolRequested(run) {
+    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;
     }
-    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);
+    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,
+    }) ?? null;
+    if (unsafeShellReason) {
+        const { emitDeny } = await import("./adapter/output.js");
+        emitDeny(adapter, unsafeShellReason);
+        return 0;
+    }
+    const waiterReason = shellWaiterReason(payload?.tool_name, payload?.tool_input);
+    if (waiterReason) {
+        const { emitDeny } = await import("./adapter/output.js");
+        emitDeny(adapter, waiterReason);
+        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;
+    return undefined;
+}
+async function handlePostToolUse(run) {
+    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.js");
+            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.js");
-                emitContext(adapter, "PostToolUse", sessionNameDisplayInstruction(name));
+                emitContext(adapter, "PostToolUse", sessionNameDisplayReminder(due));
             }
         }
-        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" });
-        }
+    catch (err) {
+        logError(coordRoot, err, { phase: "post-tool-use-session-name" });
+    }
+}
+function handlePostToolUseFailure(run) {
+    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) {
+    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, nativeSessionId) {
+function scheduleRuntimeContextRetry(coordRoot, adapter, nativeSessionId) {
     const modulePath = process.argv[1];
     if (!modulePath)
         return;
     try {
-        const child = spawn(process.execPath, [modulePath, "runtime-context-retry", "--adapter", "codex", "--session-id", nativeSessionId], {
+        const child = spawn(process.execPath, [modulePath, "runtime-context-retry", "--adapter", adapter, "--session-id", nativeSessionId], {
             cwd: coordRoot,
             detached: true,
             stdio: "ignore",
@@ -1322,7 +1468,7 @@ function scheduleCodexRuntimeContextRetry(coordRoot, nativeSessionId) {
 }
 async function runRuntimeContextRetryWorker(coordRoot, adapter, extra) {
     const nativeSessionId = extraArg(extra, "--session-id");
-    if (adapter !== "codex" || !nativeSessionId)
+    if (!adapter || !adapterBehavior(adapter).runtimeContextRetry || !nativeSessionId)
         return 0;
     for (const [index, delayMs] of [400, 1_000].entries()) {
         await new Promise((resolve) => setTimeout(resolve, delayMs));
@@ -1340,7 +1486,21 @@ async function runRuntimeContextRetryWorker(coordRoot, adapter, extra) {
     }
     return 0;
 }
+function reportSessionNameObservationUnavailable(coordRoot, instanceId, adapter, eventName, reason) {
+    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, instanceId, adapter, payload, coordination) {
+    if (coordEnv("WORKFLOW_CHILD") === "1")
+        return true;
     const name = sessionNameDisplayPending(coordination);
     if (!name)
         return true;
@@ -1353,11 +1513,7 @@ async function enforcePendingSessionNameDisplay(coordRoot, instanceId, adapter,
         return true;
     }
     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;
     }
     // Record the refusal. Without this the gate was the one enforcement path
@@ -1384,19 +1540,18 @@ async function enforcePendingSessionNameDisplay(coordRoot, instanceId, adapter,
  * other opening text for every accepted title.
  */
 function inspectDisplayEvidence(instanceId, adapter, payload, coordination) {
-    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.
-    const transcriptPath = payload?.transcript_path ??
-        (adapter === "codex"
-            ? discoverCodexSessionTranscript(payload?.session_id ?? instanceId)
-            : undefined);
+    // 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 ?? behavior.discoverTranscript?.(payload?.session_id ?? instanceId);
     let verdict = { state: "absent" };
     for (const candidate of sessionNameDisplayAcceptedNames(coordination)) {
         const inspection = inspectSessionNameDisplayImmediately(transcriptPath, candidate, assistantTextStartsWithSessionNameBlock);
@@ -1671,7 +1826,7 @@ function releaseClaimOnFailure(coordRoot, instanceId, data, rawPayload) {
             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",
@@ -1707,22 +1862,23 @@ function cleanupSessionEnd(coordRoot, instanceId) {
     }
 }
 async function emitUserPromptSubmitSystemMessage(coordRoot, instanceId, sessionId, adapter, workspaceCwd, recoveryBriefing = "", hostPromptContext = "") {
+    // 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.js");
     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");
@@ -1764,18 +1920,10 @@ async function emitSubagentStartContext(coordRoot, instanceId, sessionId, data,
     emitContext(adapter, "SubagentStart", combined);
 }
 function adapterPlatform(adapter) {
-    if (adapter === "claude-code")
-        return "claude-code";
     return adapter;
 }
-function adapterFromPlatform(platform) {
-    if (platform === "cursor")
-        return "cursor";
-    if (platform === "codex")
-        return "codex";
-    return "claude-code";
-}
 async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, emittedData, adapter, recoveryBriefing = "", backupCue = "") {
+    const behavior = adapterBehavior(adapter);
     const workflowChild = coordEnv("WORKFLOW_CHILD") === "1";
     let additionalContext = "";
     // Opportunistic reconciliation makes normal session starts a failsafe for
@@ -1795,14 +1943,14 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
             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");
@@ -1813,19 +1961,14 @@ async function emitSessionStartSystemMessage(coordRoot, instanceId, sessionId, e
     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.js");
@@ -1837,6 +1980,7 @@ function completeRecoveryInjection(coordRoot, instanceId, sessionId, recovery) {
 }
 main()
     .then(async (code) => {
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
         finished_at_ms: performance.now(),
         finished_rss_bytes: process.memoryUsage().rss,
@@ -1851,6 +1995,7 @@ main()
         pid: process.pid,
         phase: "top-level",
     });
+    clearHookRunMarker(hookRunMarkerPath);
     writeHookHealthCompletion(hookHealthState, {
         finished_at_ms: performance.now(),
         finished_rss_bytes: process.memoryUsage().rss,