harnery 0.34.1 → 0.36.0

package/src/core/hooks/cli.ts

@@ -17,29 +17,34 @@
  * adapter flow.
  */
 
-import { spawnSync } from "node:child_process";
+import { spawn, spawnSync } from "node:child_process";
 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 { coordBinPath } from "../agents/coord-bin.ts";
+import { resolveCoordRoot } from "../agents/coord-client.ts";
 import {
   type ClaimFinalizationDecision,
   type ClaimFinalizationDescriptor,
   classifyWriteClaimFinalization,
   formatWriteClaimFinalizationDenial,
 } from "../agents/finalization.ts";
+import { restoreLiveCoordinationStateAfterEpochV3 } from "../agents/live-authority-v3.ts";
 import { evaluateStopHook, STOP_REMEDIATION_MARKER } from "../agents/rules/stop-hook.ts";
 import {
   assistantTextStartsWithSessionNameBlock,
   isSessionNameRemediationCommand,
   sessionNameDisplayInstruction,
   sessionNameDisplayPending,
+  sessionNameDisplayRecoveryInstruction,
   toolResponseMintedSessionName,
 } from "../agents/session-name-display.ts";
-import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
+import type { Heartbeat } from "../agents/state/heartbeat-reader.ts";
+import { readHeartbeat, stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
 import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import { ensureLiveCoordinationHeartbeat } from "../agents/state/live-coordination-writer.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import { agentsRequireGitFinalization, resolveBinName } from "../config.ts";
 import {
@@ -54,11 +59,15 @@ import {
 } from "../context/index.ts";
 import { tryWriteLiveDisplayV3 } from "../events/v3/live-feed.ts";
 import {
+  liveHookSignalDefersDrainV3,
+  reconcileLivePendingRuntimeContextV3,
+  recordLiveDelegatedChildSessionV3,
   recordLiveHookSignalV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
 import { captureSpanClockV3 } from "../events/v3/span-state.ts";
-import { fetchPresence } from "../presence/index.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 { detectAdapter, shouldSkipHookAdapter } from "./adapter/detect.ts";
 import {
@@ -69,6 +78,7 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
+import { discoverCodexSessionTranscript } from "./adapter/runtime-telemetry.ts";
 import {
   codexWslFileLinkTelemetry,
   inspectCodexWslBridge,
@@ -91,15 +101,14 @@ import {
 import { toolInputHash, toolTargetHash } from "./events/input-hash.ts";
 import { canonicalize } from "./guard-path.ts";
 import { adapterPidFromEnv, parsePsChainLine, selectAnchorPid } from "./resolve/anchor.ts";
-import { findCoordRoot } from "./resolve/coord-root.ts";
 import { extractIntentComment, resolveIntent } from "./resolve/intent.ts";
 import { resolveOwner } from "./resolve/owner.ts";
 import {
   inspectSessionNameDisplayImmediately,
-  scanAssistantTextIncludes,
+  scanAssistantStatusBoxPresent,
   scanSessionNameDisplayedImmediately,
   scanStatusBoxPresent,
-  scanTranscriptModel,
+  scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
 import { unsafeCrossShellReason } from "./unsafe-cross-shell.ts";
@@ -127,6 +136,11 @@ function parseArgv(argv: string[]): Argv {
   return out;
 }
 
+function extraArg(extra: string[], name: string): string | undefined {
+  const index = extra.indexOf(name);
+  return index >= 0 ? extra[index + 1] : undefined;
+}
+
 async function readStdin(): Promise<string> {
   if (process.stdin.isTTY) return "";
   try {
@@ -152,6 +166,14 @@ function childEnv(coordRoot: string): NodeJS.ProcessEnv {
 }
 
 function appendDebug(coordRoot: string, entry: Record<string, unknown>): void {
+  if (coordEnv("SHARED_LOGS") !== "0") {
+    try {
+      processLogger(coordRoot, "agent-hook").debug("agent_hook.diagnostic", legacyLogFields(entry));
+      return;
+    } catch {
+      /* fall through to the rollback writer */
+    }
+  }
   const path = join(coordRoot, ".harnery", "debug", "agent-hook.ndjson");
   try {
     mkdirSync(dirname(path), { recursive: true });
@@ -163,6 +185,18 @@ function appendDebug(coordRoot: string, entry: Record<string, unknown>): void {
 
 function logError(coordRoot: string | null, err: unknown, context: Record<string, unknown>): void {
   if (!coordRoot) return;
+  if (coordEnv("SHARED_LOGS") !== "0") {
+    try {
+      processLogger(coordRoot, "agent-hook").error(
+        "agent_hook.error",
+        legacyLogFields(context),
+        err,
+      );
+      return;
+    } catch {
+      /* fall through to the rollback writer */
+    }
+  }
   const path = join(coordRoot, ".harnery", "debug", "agent-hook.errors.ndjson");
   try {
     mkdirSync(dirname(path), { recursive: true });
@@ -312,7 +346,7 @@ function buildEventData(
         // Claude Code's SessionStart payload omits `model` (Codex + Cursor
         // supply it). Fall back to the transcript, populated on `resume`, and
         // backfilled later by `turn.completed` for a fresh startup session.
-        model: p?.model ?? scanTranscriptModel(p?.transcript_path),
+        model: p?.model ?? scanTranscriptRuntime(p?.transcript_path)?.model,
         pid: adapterPid,
         source: p?.source,
         platform: adapterPlatform,
@@ -379,7 +413,7 @@ function buildEventData(
         // Backfill the model for adapters that omit it at session.started
         // (Claude Code). The transcript is populated with assistant turns by
         // Stop-hook time, so this resolves even for fresh `startup` sessions.
-        model: p?.model ?? scanTranscriptModel(p?.transcript_path),
+        model: p?.model ?? scanTranscriptRuntime(p?.transcript_path)?.model,
         // Phase 2: tool_call_count + text_length aren't cheaply available
         // from the Stop payload alone (they'd require a transcript scan that
         // races with the JSONL flush). Emit `-1` / `0` sentinels and let
@@ -394,25 +428,29 @@ function buildEventData(
         // (the previous path passed those via the no-history fail-open).
         status_box_present:
           scanStatusBoxPresent(p?.transcript_path) || lastAssistantMessage.includes("┌─ agent-"),
-        // Shadow measurement for the rule-2/3 detector: the loose scan above
+        // Assistant-text evidence for the rule-2/3 detector: the loose scan above
         // matches the box prefix ANYWHERE in the transcript tail, including
         // the tool_result row the status command itself writes, so it can
         // report a paste that never happened. The strict variant counts
         // assistant text only (same window, same scanner as the session-name
-        // detection). Telemetry-only: the Stop verdict still reads
-        // status_box_present. Once the divergence rate between the two fields
-        // is known, the gate either flips to strict or the rule gets
-        // reconsidered; either way this field decides it with data.
-        status_box_present_strict:
-          scanAssistantTextIncludes(p?.transcript_path, "┌─ agent-") ||
-          lastAssistantMessage.includes("┌─ agent-"),
+        // detection). The Stop verdict enforces this field; the loose field is
+        // retained as diagnostic telemetry for the measured detector divergence.
+        status_box_present_strict: scanAssistantStatusBoxPresent(
+          p?.transcript_path,
+          lastAssistantMessage,
+        ),
         // Whether the session's suggested name is satisfied as of this turn,
         // 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(
-            p?.transcript_path,
+            // Codex stops carry no transcript_path; discover the rollout 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,
           ),
@@ -428,7 +466,8 @@ function buildEventData(
       // Subagents inherit parent's name via the resolve-name session_id path
       // (agent-coord/state/names.ts → kind=transient). Use the call ID as the
       // instance_id input; assignName falls through to transient.
-      const assigned = assignNameViaAgentCoord(ctx.coordRoot, ctx.instanceId, "subagent");
+      const childInstanceId = subagentCallId ?? ctx.instanceId;
+      const assigned = assignNameViaAgentCoord(ctx.coordRoot, childInstanceId, "subagent");
       return {
         agent_type:
           (p?.raw.agent_type as string | undefined) ??
@@ -437,7 +476,7 @@ function buildEventData(
         prompt_summary: p?.raw.prompt_summary as string | undefined,
         name: assigned?.name,
         kind: "subagent",
-        agent_id: ctx.instanceId,
+        agent_id: childInstanceId,
         subagent_call_id: subagentCallId,
         parent_session_id: p?.parent_session_id,
       };
@@ -571,7 +610,7 @@ async function main(): Promise<number> {
   // `--adapter cursor` dispatch of the same payload carries the session.
   if (shouldSkipHookAdapter(adapter, raw)) {
     if (coordEnv("AGENT_COORD_OFF") !== "1") {
-      const coordRoot = findCoordRoot(process.cwd());
+      const coordRoot = resolveCoordRoot(process.cwd());
       if (coordRoot) {
         appendDebug(coordRoot, {
           ts: new Date().toISOString(),
@@ -596,16 +635,27 @@ async function main(): Promise<number> {
   if (adapter === "claude-code" && eventName) {
     const s = soundForEvent(eventName);
     if (s) {
-      const repoRoot = findCoordRoot(process.cwd());
+      const repoRoot = resolveCoordRoot(process.cwd());
       if (repoRoot) {
         let sid = "";
+        let stopContinuation = false;
         try {
-          const j = JSON.parse(raw) as { session_id?: string; conversation_id?: string };
+          const j = JSON.parse(raw) as {
+            session_id?: string;
+            conversation_id?: string;
+            stop_hook_active?: boolean;
+          };
           sid = j.session_id ?? j.conversation_id ?? "";
+          // A stop with stop_hook_active is a remediation continuation of a
+          // turn that already chimed; replaying the sound on every bounce
+          // turns a blocked-stop loop into a repeating alarm.
+          stopContinuation = eventName === "stop" && j.stop_hook_active === true;
         } catch {
           // non-JSON payload: play unkeyed (rate-limit just won't dedup)
         }
-        playSound(repoRoot, s.sound, sid, s.maxPlays);
+        if (!stopContinuation) {
+          playSound(repoRoot, s.sound, sid, s.maxPlays);
+        }
       }
     }
   }
@@ -616,8 +666,11 @@ async function main(): Promise<number> {
   // bypass during incident triage.
   if (coordEnv("AGENT_COORD_OFF") === "1") return 0;
 
-  const coordRoot = findCoordRoot(process.cwd());
+  const coordRoot = resolveCoordRoot(process.cwd());
   if (!coordRoot) return 0;
+  if (eventName === "runtime-context-retry") {
+    return runRuntimeContextRetryWorker(coordRoot, adapter, extra);
+  }
   const ledgerRoute = resolveLiveEventLedgerRouteV3(coordRoot);
 
   // Always log a breadcrumb, useful when an event_type maps to null or owner
@@ -639,6 +692,30 @@ async function main(): Promise<number> {
     return 0;
   }
 
+  // Cursor's preToolUse `agent_message` is only the current narration before
+  // that tool. It is not a transcript and therefore cannot prove that an
+  // earlier assistant response omitted the required session-name block.
+  // afterAgentResponse is the one native boundary that carries the completed
+  // assistant text, so stamp a positive sighting here without retaining or
+  // emitting the response body into V3.
+  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 name = sessionNameDisplayPending(readLiveCoordinationRow(coordRoot, owner.instance_id));
+    const text = typeof payload?.raw.text === "string" ? payload.raw.text : "";
+    if (name && assistantTextStartsWithSessionNameBlock(text, name)) {
+      stampSessionNameSeen(coordRoot, owner.instance_id, name);
+      appendDebug(coordRoot, { ...debugBase, effect: "session-name-display-stamped" });
+    } else {
+      appendDebug(coordRoot, { ...debugBase, skipped: "no-session-name-sighting" });
+    }
+    return 0;
+  }
+
   const norm = normalizeEventName(eventName);
   if (!norm) {
     appendDebug(coordRoot, { ...debugBase, skipped: "non-canonical-event" });
@@ -660,6 +737,7 @@ async function main(): Promise<number> {
   }
 
   const sessionId = payload?.session_id ?? payload?.conversation_id ?? owner.instance_id;
+  const priorCoordination = readHeartbeat(coordRoot, owner.instance_id);
 
   const data = buildEventData(norm.event_type, {
     coordRoot,
@@ -706,6 +784,10 @@ async function main(): Promise<number> {
     }
   }
 
+  const deferV3Drain = liveHookSignalDefersDrainV3(
+    eventName,
+    coordEnv("EXPERIMENT_DEFER_V3_DRAIN"),
+  );
   const v3Result = recordLiveHookSignalV3({
     coordRoot,
     route: ledgerRoute,
@@ -728,8 +810,26 @@ async function main(): Promise<number> {
     monotonic_ns: hookClock.monotonic_ns,
     ...(stopRemediation ? { stop_remediation: true } : {}),
     ...(turnRitual ? { turn_ritual: turnRitual } : {}),
-    ...(coordEnv("EXPERIMENT_DEFER_V3_DRAIN") === "1" ? { defer_drain: true } : {}),
+    ...(deferV3Drain ? { defer_drain: true } : {}),
   });
+  const recordedGenerationId =
+    v3Result && "event" in v3Result && "generation_id" in v3Result.event.scope
+      ? (v3Result.event.scope.generation_id as `gen_${string}`)
+      : undefined;
+  if (v3Result?.state === "recorded" || v3Result?.state === "already_started") {
+    try {
+      restoreLiveCoordinationStateAfterEpochV3({
+        coordRoot,
+        owner: owner.instance_id,
+        nativeSessionId: sessionId,
+        adapter,
+        prior: priorCoordination,
+        currentGenerationId: recordedGenerationId,
+      });
+    } catch (error) {
+      logError(coordRoot, error, { phase: "epoch-coordination-restore" });
+    }
+  }
   const v3EventId =
     v3Result && "event" in v3Result
       ? v3Result.event.event_id
@@ -737,9 +837,39 @@ async function main(): Promise<number> {
         ? v3Result.event_id
         : undefined;
 
+  if (
+    norm.event_type === "agent.started" &&
+    payload &&
+    v3Result?.state === "recorded" &&
+    v3Result.event.event_type === "agent.started"
+  ) {
+    try {
+      const childResult = recordLiveDelegatedChildSessionV3({
+        coordRoot,
+        route: ledgerRoute,
+        parentEvent: v3Result.event,
+        payload,
+        adapter,
+        ...(adapter === "codex" && isWslUncPath(payload.cwd)
+          ? { bridge: "codex-wsl" as const }
+          : {}),
+        monotonic_ns: hookClock.monotonic_ns,
+      });
+      const nativeChild = payload.subagent_id ?? payload.agent_id;
+      if (
+        nativeChild &&
+        (childResult.state === "recorded" || childResult.state === "already_started")
+      ) {
+        ensureLiveCoordinationHeartbeat(coordRoot, nativeChild, sessionId, adapter, payload.model);
+      }
+    } catch (err) {
+      logError(coordRoot, err, { phase: "subagent-child-session-start" });
+    }
+  }
+
   if (v3Result?.state === "recorded" && capturedImages.length > 0) {
     try {
-      recordImageArtifactsV3(coordRoot, v3Result.event, capturedImages);
+      recordImageArtifactsV3(coordRoot, v3Result.event, capturedImages, ledgerRoute.genesis_id);
     } catch (err) {
       logError(coordRoot, err, { phase: "image-artifact-observation" });
     }
@@ -833,6 +963,36 @@ async function main(): Promise<number> {
     // 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 { createAutomaticMaintenanceComposition, runAutomaticMaintenancePass } = await import(
+      "../storage/maintenance-providers.ts"
+    );
+    // Effect: throttled daily sweep of expired artifact workspaces (guarded,
+    // managed-expired only; see autoCleanArtifacts). Best-effort like every
+    // janitor here: a failure logs and never blocks session start.
+    try {
+      autoCleanArtifacts(coordRoot);
+    } catch (err) {
+      logError(coordRoot, err, { phase: "artifact-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 {
@@ -864,10 +1024,13 @@ async function main(): Promise<number> {
     } catch (err) {
       logError(coordRoot, err, { phase: "session-start-systemMessage" });
     }
-    // Pull advisory cross-machine presence. V3 never publishes from the
-    // disposable heartbeat cache.
+    // 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" });
     }
@@ -887,13 +1050,21 @@ async function main(): Promise<number> {
       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" });
+    }
   }
 
-  // Phase 8: SubagentStart: sync-project to create the subagent heartbeat,
-  // log the lifecycle event, and emit a context message announcing the
-  // subagent (claude-code + cursor; codex doesn't fan out subagents today).
+  // 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;
       const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(agentCoordBin, ["project"], {
@@ -905,14 +1076,14 @@ async function main(): Promise<number> {
           agentCoordBin,
           [
             "log",
-            `SUBAGENT_START  agent_type=${(data.agent_type as string) ?? "unknown"} agent_id=${owner.instance_id.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
+            `SUBAGENT_START  agent_type=${(data.agent_type as string) ?? "unknown"} agent_id=${childInstanceId.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
             "--instance",
-            owner.instance_id,
+            childInstanceId,
           ],
           { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
-      emitSubagentStartContext(coordRoot, owner.instance_id, sessionId, data, adapter);
+      emitSubagentStartContext(coordRoot, childInstanceId, sessionId, data, adapter);
     } catch (err) {
       logError(coordRoot, err, { phase: "subagent-start-project" });
     }
@@ -921,20 +1092,23 @@ async function main(): Promise<number> {
   // Phase 8: SubagentStop: delete subagent heartbeat + log.
   if (norm.event_type === "agent.completed") {
     try {
-      cleanupSessionEnd(coordRoot, owner.instance_id, (data.reason as string) ?? "unknown");
+      const childInstanceId = payload?.subagent_id ?? payload?.agent_id ?? owner.instance_id;
+      cleanupSessionEnd(coordRoot, childInstanceId, (data.reason as string) ?? "unknown");
       const agentCoordBin = coordBinPath("agent-coord", coordRoot) ?? "";
       if (existsSync(agentCoordBin)) {
         spawnSync(
           agentCoordBin,
           [
             "log",
-            `SUBAGENT_STOP   agent_id=${owner.instance_id.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
+            `SUBAGENT_STOP   agent_id=${childInstanceId.slice(0, 8)} platform=${adapterPlatform(adapter)}`,
             "--instance",
-            owner.instance_id,
+            childInstanceId,
           ],
           { encoding: "utf8", timeout: 2000, env: childEnv(coordRoot) },
         );
       }
+      const { reconcileSessionFinalizationV3 } = await import("../agents/session-finalizer-v3.ts");
+      reconcileSessionFinalizationV3(coordRoot, { archive_observations: [] });
     } catch (err) {
       logError(coordRoot, err, { phase: "subagent-stop-cleanup" });
     }
@@ -1001,6 +1175,16 @@ async function main(): Promise<number> {
       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.
@@ -1009,16 +1193,39 @@ async function main(): Promise<number> {
       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) {
-      // 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. Codex returned observe-only above.
-      // emitStopBlock writes the right shape and returns the exit code to use.
-      const { emitStopBlock } = await import("./adapter/output.ts");
-      return emitStopBlock(adapter, verdict, coordRoot);
+      // 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. Codex returned observe-only above.
+        // emitStopBlock writes the right shape and returns the exit code to use.
+        const { emitStopBlock } = await import("./adapter/output.ts");
+        return emitStopBlock(adapter, verdict, coordRoot);
+      }
+    } else {
+      const { clearRemediationCount } = await import("./remediation-cap.ts");
+      clearRemediationCount(sessionId);
     }
 
     // An explicit end requested from inside this turn cannot be authoritative
@@ -1035,6 +1242,7 @@ async function main(): Promise<number> {
     } catch (err) {
       logError(coordRoot, err, { phase: "stop-explicit-session-finalization" });
     }
+    if (adapter === "codex") scheduleCodexRuntimeContextRetry(coordRoot, sessionId);
   }
 
   // Phase 7: PreToolUse: heartbeat + pid-map self-heal on every tool call.
@@ -1063,14 +1271,18 @@ async function main(): Promise<number> {
     // 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. Later commentary must not erase an already-correct
-    // display, and an unreadable transcript must not deadlock every tool.
+    // 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) {
@@ -1147,27 +1359,77 @@ async function main(): Promise<number> {
   return 0;
 }
 
+function scheduleCodexRuntimeContextRetry(coordRoot: string, 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],
+      {
+        cwd: coordRoot,
+        detached: true,
+        stdio: "ignore",
+        env: childEnv(coordRoot),
+      },
+    );
+    child.unref();
+  } catch (err) {
+    logError(coordRoot, err, { phase: "runtime-context-retry-spawn" });
+  }
+}
+
+async function runRuntimeContextRetryWorker(
+  coordRoot: string,
+  adapter: Adapter | null,
+  extra: string[],
+): Promise<number> {
+  const nativeSessionId = extraArg(extra, "--session-id");
+  if (adapter !== "codex" || !nativeSessionId) return 0;
+  for (const [index, delayMs] of [400, 1_000].entries()) {
+    await new Promise((resolve) => setTimeout(resolve, delayMs));
+    const route = resolveLiveEventLedgerRouteV3(coordRoot);
+    if (route.state !== "v3") return 0;
+    const result = reconcileLivePendingRuntimeContextV3({
+      coordRoot,
+      route,
+      nativeSessionId,
+      finalAttempt: index === 1,
+    });
+    if (result.state !== "pending" && result.state !== "busy") return 0;
+  }
+  return 0;
+}
+
 async function enforcePendingSessionNameDisplay(
   coordRoot: string,
   instanceId: string,
   adapter: Adapter,
   payload: ParsedPayload | null,
+  coordination: Heartbeat | null,
 ): Promise<boolean> {
-  const name = sessionNameDisplayPending(readLiveCoordinationRow(coordRoot, instanceId));
+  const name = sessionNameDisplayPending(coordination);
   if (!name) return true;
 
   const command = extractBashCommand(payload?.tool_name, payload?.tool_input);
   if (isSessionNameRemediationCommand(command, resolveBinName(coordRoot))) return true;
 
   const inspection =
-    payload?.agent_message !== undefined
+    adapter === "cursor" && payload?.agent_message !== undefined
       ? {
           state: assistantTextStartsWithSessionNameBlock(payload.agent_message, name)
             ? ("present" as const)
-            : ("absent" as const),
+            : ("unavailable" as const),
         }
       : inspectSessionNameDisplayImmediately(
-          payload?.transcript_path,
+          // 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.
+          payload?.transcript_path ??
+            (adapter === "codex"
+              ? discoverCodexSessionTranscript(payload?.session_id ?? instanceId)
+              : undefined),
           name,
           assistantTextStartsWithSessionNameBlock,
         );
@@ -1177,20 +1439,26 @@ async function enforcePendingSessionNameDisplay(
   }
 
   if (inspection.state === "unavailable") {
-    const { emitContext } = await import("./adapter/output.ts");
-    emitContext(
-      adapter,
-      "PreToolUse",
-      "Harnery could not verify the pending session-name display because the adapter transcript is unavailable or not flushed yet. This tool is allowed so the session cannot deadlock; display the requested block before later work. Verification remains pending.",
-    );
+    // 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.
     return true;
   }
 
   const { emitDeny } = await import("./adapter/output.ts");
-  emitDeny(adapter, sessionNameDisplayInstruction(name));
+  emitDeny(adapter, sessionNameDisplayRecoveryInstruction(name, resolveBinName(coordRoot)));
   return false;
 }
 
+function generationBoundHeartbeat(
+  heartbeat: Heartbeat | null,
+  generationId: `gen_${string}` | undefined,
+): Heartbeat | null {
+  return generationId && heartbeat?.v3_generation_id === generationId ? heartbeat : null;
+}
+
 async function runPreToolUseGuard(
   coordRoot: string,
   instanceId: string,
@@ -1538,16 +1806,22 @@ async function emitUserPromptSubmitSystemMessage(
     // Every human-facing adapter gets the first-session naming reminder from
     // the shared hook path. Cursor + Codex additionally get ongoing set-task
     // staleness nudges; Claude Code enforces those via its Stop transcript.
+    // Codex also gets the optional project-owned prompt reminder. Claude Code
+    // already has native output-style reminders, so duplicating it would add
+    // noise. Cursor's current beforeSubmitPrompt output can allow or block but
+    // cannot inject model context; an Always Apply rule is its durable carrier.
+    // Only the boolean route travels through argv, never the host's text.
+    if (adapter === "codex") args.push("--host-prompt-reminder");
     // Codex gets a fresh status-footer reminder on every prompt. Its Stop hook
     // stays observe-only, so missing the footer never replaces the answer.
-    // Claude Code + Cursor (the Stop-ENFORCING adapters) get a fresh per-turn
-    // ritual reminder: satisfying the contract up front is far cheaper than
-    // the bounce-and-retry the Stop hook otherwise forces.
+    // Claude Code gets a fresh per-turn ritual reminder: satisfying the
+    // contract up front is far cheaper than the bounce-and-retry the Stop hook
+    // otherwise forces. Cursor's beforeSubmitPrompt cannot inject context, so
+    // its Stop follow-up remains the supported enforcement channel.
     args.push("--session-name-nudge");
     if (adapter === "cursor" || adapter === "codex") args.push("--task-nudge");
     if (adapter === "codex") args.push("--status-footer-nudge");
-    if (adapter === "claude-code" || adapter === "cursor")
-      args.push("--turn-ritual-nudge", adapter);
+    if (adapter === "claude-code") args.push("--turn-ritual-nudge", adapter);
     const result = spawnSync(agentCoordBin, args, { encoding: "utf8", timeout: 3000 });
     if (result.status === 0 && result.stdout) additionalContext = result.stdout.trim();
   }
@@ -1712,11 +1986,15 @@ function completeRecoveryInjection(
 }
 
 main()
-  .then((code) => process.exit(code))
-  .catch((err) => {
-    logError(findCoordRoot(process.cwd()), err, {
+  .then(async (code) => {
+    await closeProcessLoggers();
+    process.exit(code);
+  })
+  .catch(async (err) => {
+    logError(resolveCoordRoot(process.cwd()), err, {
       argv: process.argv.slice(2),
       pid: process.pid,
     });
+    await closeProcessLoggers();
     process.exit(0);
   });