harnery 0.34.1 → 0.35.0

package/src/core/hooks/cli.ts

@@ -36,10 +36,14 @@ import {
   isSessionNameRemediationCommand,
   sessionNameDisplayInstruction,
   sessionNameDisplayPending,
+  sessionNameDisplayRecoveryInstruction,
   toolResponseMintedSessionName,
 } from "../agents/session-name-display.ts";
 import { stampSessionNameSeen } from "../agents/state/heartbeat-writer.ts";
-import { readLiveCoordinationRow } from "../agents/state/live-coordination-view.ts";
+import {
+  ensureLiveCoordinationHeartbeat,
+  readLiveCoordinationRow,
+} from "../agents/state/live-coordination-view.ts";
 import { writePidmapRow } from "../agents/state/pidmap.ts";
 import { agentsRequireGitFinalization, resolveBinName } from "../config.ts";
 import {
@@ -54,6 +58,8 @@ import {
 } from "../context/index.ts";
 import { tryWriteLiveDisplayV3 } from "../events/v3/live-feed.ts";
 import {
+  liveHookSignalDefersDrainV3,
+  recordLiveDelegatedChildSessionV3,
   recordLiveHookSignalV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
@@ -69,6 +75,7 @@ import {
   type ParsedPayload,
   parsePayload,
 } from "./adapter/parse.ts";
+import { discoverCodexSessionTranscript } from "./adapter/runtime-telemetry.ts";
 import {
   codexWslFileLinkTelemetry,
   inspectCodexWslBridge,
@@ -99,7 +106,7 @@ import {
   scanAssistantTextIncludes,
   scanSessionNameDisplayedImmediately,
   scanStatusBoxPresent,
-  scanTranscriptModel,
+  scanTranscriptRuntime,
 } from "./resolve/transcript.ts";
 import { sessionNamePresence } from "./session-name-presence.ts";
 import { unsafeCrossShellReason } from "./unsafe-cross-shell.ts";
@@ -312,7 +319,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 +386,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,15 +401,13 @@ 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.
+        // detection). The Stop verdict enforces this field; the loose field is
+        // retained as diagnostic telemetry for the measured detector divergence.
         status_box_present_strict:
           scanAssistantTextIncludes(p?.transcript_path, "┌─ agent-") ||
           lastAssistantMessage.includes("┌─ agent-"),
@@ -412,7 +417,12 @@ function buildEventData(
         // 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 +438,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 +448,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,
       };
@@ -599,13 +610,24 @@ async function main(): Promise<number> {
       const repoRoot = findCoordRoot(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);
+        }
       }
     }
   }
@@ -706,6 +728,10 @@ async function main(): Promise<number> {
     }
   }
 
+  const deferV3Drain = liveHookSignalDefersDrainV3(
+    eventName,
+    coordEnv("EXPERIMENT_DEFER_V3_DRAIN"),
+  );
   const v3Result = recordLiveHookSignalV3({
     coordRoot,
     route: ledgerRoute,
@@ -728,7 +754,7 @@ 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 v3EventId =
     v3Result && "event" in v3Result
@@ -737,6 +763,36 @@ 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);
@@ -889,11 +945,12 @@ async function main(): Promise<number> {
     }
   }
 
-  // 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 +962,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 +978,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" });
     }
@@ -1013,12 +1073,30 @@ async function main(): Promise<number> {
       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 { remediationCapExceeded } = await import("./remediation-cap.ts");
+      if (remediationCapExceeded(sessionId, payload?.stop_hook_active === true)) {
+        appendDebug(coordRoot, {
+          ...debugBase,
+          skipped: "stop-remediation-cap-exhausted",
+          blocked_rule: verdict.rule,
+          session_id: sessionId,
+        });
+      } 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
@@ -1160,14 +1238,21 @@ async function enforcePendingSessionNameDisplay(
   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),
         }
       : 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,17 +1262,16 @@ 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;
 }
 

package/src/core/hooks/remediation-cap.ts

@@ -0,0 +1,77 @@
+/**
+ * Per-session cap on consecutive blocked Stop remediations.
+ *
+ * The Stop verdict re-blocks until the ledger shows the end-of-turn evidence,
+ * which assumes the agent CAN produce it. A session whose evidence can never
+ * land (e.g. a headless child whose status command resolves to a different
+ * owner) bounces forever: every retry replays the stop cycle until the budget
+ * or the operator kills it. This counter is the backstop: once a single stop
+ * cycle has been blocked `cap` times in a row, the verdict is allowed through
+ * so the session can terminate.
+ *
+ * A "stop cycle" is delimited by the adapter's continuation flag (Claude
+ * Code's `stop_hook_active`): a stop without the flag starts a fresh cycle and
+ * resets the count. Adapters that never set the flag (Cursor) reset on every
+ * stop, so the cap never engages there and behavior is unchanged.
+ *
+ * State is a tmpdir counter file keyed by session id — deliberately outside
+ * the ledger, because remediation stops do not land fresh `turn.completed`
+ * events (the turn span is already closed), so ledger evidence cannot count
+ * them.
+ */
+
+import { readFileSync, rmSync, writeFileSync } from "node:fs";
+import os from "node:os";
+import { join } from "node:path";
+
+export const DEFAULT_STOP_REMEDIATION_CAP = 5;
+
+function counterPath(sessionId: string): string {
+  const key = (sessionId || "default").replace(/[^A-Za-z0-9_-]/g, "_");
+  return join(os.tmpdir(), `harnery-stop-remediation-${key}.count`);
+}
+
+/**
+ * Record one blocked stop and report whether the cap is exhausted.
+ *
+ * Call only when the Stop verdict blocked. `continuation` is the adapter's
+ * "this stop follows a stop-hook block" flag; false starts a fresh cycle.
+ * Returns true when this cycle has already been blocked `cap` times, meaning
+ * the caller should allow the stop instead of blocking again.
+ */
+export function remediationCapExceeded(
+  sessionId: string,
+  continuation: boolean,
+  cap = DEFAULT_STOP_REMEDIATION_CAP,
+): boolean {
+  const path = counterPath(sessionId);
+  let count = 1;
+  if (continuation) {
+    let prior = 0;
+    try {
+      prior = Number.parseInt(readFileSync(path, "utf8"), 10);
+    } catch {
+      // No counter yet (cycle started before the counter existed): treat the
+      // continuation itself as evidence of one earlier blocked stop, so an
+      // already-running loop still converges on the cap.
+      prior = 1;
+    }
+    count = Number.isFinite(prior) && prior >= 0 ? prior + 1 : 1;
+  }
+  try {
+    writeFileSync(path, String(count), "utf8");
+  } catch {
+    // Counter IO must never turn into a block or a crash; fail open (no cap).
+    return false;
+  }
+  return count > cap;
+}
+
+/** Clear the cycle counter after an allowed stop. */
+export function clearRemediationCount(sessionId: string): void {
+  try {
+    rmSync(counterPath(sessionId), { force: true });
+  } catch {
+    // best-effort
+  }
+}

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

@@ -225,19 +225,38 @@ function textFromContent(content: unknown): string {
   return parts.join("\n");
 }
 
+/** Runtime identity read from one transcript row: the model plus the tuning
+ * values that row reported alongside it. */
+export interface TranscriptRuntimeScan {
+  model: string;
+  /** CC stamps the effective effort level on each assistant row; absent when
+   * the model has no effort dial (verified: haiku rows omit it entirely). */
+  effort?: string;
+  /** CC reports the response speed tier inside `message.usage`. */
+  speed?: string;
+}
+
 /**
- * Resolve the agent's model from a CC-style JSONL transcript by reading the
- * most-recent assistant message's `message.model`. Claude Code's SessionStart
- * payload omits `model` (Codex + Cursor supply it directly), so this is the
- * fallback that lets `session.started` / `turn.completed` populate the cache's
- * model field once the transcript has at least one assistant turn.
+ * Resolve the agent's runtime identity from a CC-style JSONL transcript by
+ * reading the most-recent assistant row. Claude Code's SessionStart payload
+ * omits `model` and `effort` (Codex + Cursor supply model directly), so this
+ * is the fallback that lets `session.started` / `turn.completed` populate
+ * model and tuning once the transcript has at least one assistant turn.
+ *
+ * Model, effort, and speed are read from the SAME row, never independently:
+ * effort varies with model inside one transcript (a mid-session model swap
+ * changes both), so pairing the newest model with a separately scanned newest
+ * effort can mislabel the session.
  *
  * Tail-reads the same 256KB window as the status-box scan and walks lines from
- * the end, returning the first real model id found. Synthetic placeholders
- * (`<synthetic>`) and empty values are skipped. Returns undefined when the
- * transcript is missing/empty (e.g. a fresh session's first SessionStart).
+ * the end, returning the first row with a real model id. Synthetic
+ * placeholders (`<synthetic>`) and empty values are skipped. Returns undefined
+ * when the transcript is missing/empty (e.g. a fresh session's first
+ * SessionStart).
  */
-export function scanTranscriptModel(transcriptPath: string | undefined): string | undefined {
+export function scanTranscriptRuntime(
+  transcriptPath: string | undefined,
+): TranscriptRuntimeScan | undefined {
   const readablePath = resolveTranscriptPath(transcriptPath);
   if (!readablePath) return undefined;
   const text = tailText(readablePath);
@@ -248,12 +267,19 @@ export function scanTranscriptModel(transcriptPath: string | undefined): string
     if (!line?.includes('"model"')) continue;
     try {
       const obj = JSON.parse(line) as {
-        message?: { model?: unknown };
+        effort?: unknown;
+        message?: { model?: unknown; usage?: { speed?: unknown } };
         model?: unknown;
       };
       const model = obj.message?.model ?? obj.model;
       if (typeof model === "string" && model.length > 0 && !model.startsWith("<")) {
-        return model;
+        const effort = obj.effort;
+        const speed = obj.message?.usage?.speed;
+        return {
+          model,
+          ...(typeof effort === "string" && effort.length > 0 ? { effort } : {}),
+          ...(typeof speed === "string" && speed.length > 0 ? { speed } : {}),
+        };
       }
     } catch {
       // Partial/truncated first line of the tail window; skip it.