harnery 0.34.1 → 0.35.0

package/src/commands/semantic.ts

@@ -0,0 +1,179 @@
+import { resolve } from "node:path";
+import type { Command } from "commander";
+import type { EmitContext, HarneryProgramContext } from "../commander.ts";
+import {
+  createSemanticAdapters,
+  discoverSemanticReaders,
+  inspectSemanticDocument,
+  readSemanticManifest,
+  readSemanticServiceStatus,
+  requestSemanticServiceStop,
+  runSemanticOnce,
+  runSemanticServiceDaemon,
+  semanticPaths,
+  spawnSemanticService,
+} from "../core/semantic/index.ts";
+
+export function registerSemanticCommand(
+  program: Command,
+  emit: EmitContext,
+  context?: HarneryProgramContext,
+): void {
+  const semantic = program
+    .command("semantic")
+    .description("Build and inspect evidence-cited semantic readings of active V3 generations");
+
+  semantic
+    .command("once")
+    .description("Run one bounded semantic pass using each generation's source harness")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+    .action(async (options: { root?: string; callsPerHour?: number }) => {
+      try {
+        emit.data(
+          await runSemanticOnce({
+            coordRoot: resolve(options.root ?? coordRoot(context)),
+            callsPerHour: options.callsPerHour,
+          }),
+        );
+      } catch (error) {
+        emitFailure(emit, "semantic_once_failed", error);
+      }
+    });
+
+  const service = semantic
+    .command("service")
+    .description("Run semantic reading as a singleton service");
+
+  service
+    .command("start")
+    .description("Start or resume the detached per-root semantic reader service")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+    .action(async (options: { root?: string; callsPerHour?: number }) => {
+      try {
+        emit.data(
+          await spawnSemanticService(resolve(options.root ?? coordRoot(context)), {
+            callsPerHour: options.callsPerHour,
+          }),
+        );
+      } catch (error) {
+        emitFailure(emit, "semantic_service_start_failed", error);
+      }
+    });
+
+  service
+    .command("status")
+    .description("Show singleton liveness, pass metrics, and pending work")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        emit.data(readSemanticServiceStatus(resolve(options.root ?? coordRoot(context))));
+      } catch (error) {
+        emitFailure(emit, "semantic_service_status_failed", error);
+      }
+    });
+
+  service
+    .command("stop")
+    .description("Request a graceful stop after the current model call")
+    .option("--root <path>", "Explicit coordination root")
+    .action(async (options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        let status = requestSemanticServiceStop(root);
+        const deadline = Date.now() + 5_000;
+        while (status.running && Date.now() < deadline) {
+          await new Promise((done) => setTimeout(done, 50));
+          status = readSemanticServiceStatus(root);
+        }
+        emit.data(status);
+      } catch (error) {
+        emitFailure(emit, "semantic_service_stop_failed", error);
+      }
+    });
+
+  service
+    .command("daemon", { hidden: true })
+    .description("Internal detached semantic service entrypoint")
+    .option("--root <path>", "Explicit coordination root")
+    .option("--calls-per-hour <count>", "Configured call ceiling below the hard limit", integer)
+    .action(async (options: { root?: string; callsPerHour?: number }) => {
+      try {
+        emit.data(
+          await runSemanticServiceDaemon({
+            coordRoot: resolve(options.root ?? coordRoot(context)),
+            callsPerHour: options.callsPerHour,
+          }),
+        );
+      } catch (error) {
+        emitFailure(emit, "semantic_service_daemon_failed", error);
+      }
+    });
+
+  semantic
+    .command("inspect")
+    .description("Inspect one generation or instance semantic document")
+    .argument("<instance-or-generation>")
+    .option("--root <path>", "Explicit coordination root")
+    .action((instanceOrGeneration: string, options: { root?: string }) => {
+      try {
+        const document = inspectSemanticDocument(
+          resolve(options.root ?? coordRoot(context)),
+          instanceOrGeneration,
+        );
+        if (!document) throw new Error(`no semantic document for ${instanceOrGeneration}`);
+        emit.data(document);
+      } catch (error) {
+        emitFailure(emit, "semantic_inspect_failed", error);
+      }
+    });
+
+  semantic
+    .command("doctor")
+    .description("Inspect semantic reader availability without making a model request")
+    .option("--root <path>", "Explicit coordination root")
+    .action((options: { root?: string }) => {
+      try {
+        const root = resolve(options.root ?? coordRoot(context));
+        emit.data({
+          schema_version: 1,
+          root,
+          storage: semanticPaths(root).root,
+          readers: discoverSemanticReaders(createSemanticAdapters()),
+          manifest: readManifestSafe(root),
+        });
+      } catch (error) {
+        emitFailure(emit, "semantic_doctor_failed", error);
+      }
+    });
+}
+
+function coordRoot(context: HarneryProgramContext | undefined): string {
+  return resolve(
+    context?.resolveCoordRoot?.() ??
+      context?.repoRoot ??
+      process.env.HARNERY_COORD_ROOT ??
+      process.cwd(),
+  );
+}
+
+function integer(value: string): number {
+  const parsed = Number(value);
+  if (!Number.isSafeInteger(parsed) || parsed < 1)
+    throw new Error("count must be a positive integer");
+  return parsed;
+}
+
+function readManifestSafe(root: string) {
+  try {
+    return readSemanticManifest(root);
+  } catch {
+    return undefined;
+  }
+}
+
+function emitFailure(emit: EmitContext, code: string, error: unknown): never {
+  emit.error({ code, message: error instanceof Error ? error.message : String(error) });
+  throw error;
+}

package/src/commands/web.ts

@@ -6,6 +6,7 @@ import { fileURLToPath } from "node:url";
 import type { Command } from "commander";
 import type { EmitContext } from "../commander.ts";
 import { DEFAULT_WEB_PORT, resolveWebPort } from "../core/config.ts";
+import { ensureSemanticServiceRunning } from "../core/semantic/service.ts";
 import { lazyFetchWebRoot, webRunner } from "./web-fetch.ts";
 
 /**
@@ -69,6 +70,17 @@ export function nodeOptionsWithHeapCap(mb: number): string | undefined {
   return `${inherited} --max-old-space-size=${mb}`.trim();
 }
 
+async function startSemanticServiceWithWeb(coordRoot: string, emit: EmitContext): Promise<void> {
+  const result = await ensureSemanticServiceRunning(coordRoot);
+  if (result.state === "started") emit.log("semantic reader · started automatically", "info");
+  if (result.state === "running") emit.log("semantic reader · already running", "info");
+  if (result.state === "paused") emit.log("semantic reader · paused by operator", "info");
+  if (result.state === "inactive") emit.log("semantic reader · waiting for active V3", "info");
+  if (result.state === "unavailable") {
+    emit.log(`semantic reader · unavailable (${result.error ?? "startup failed"})`, "warn");
+  }
+}
+
 /**
  * Resolve the web app root. A local `web/` (source checkout / submodule) wins.
  * Otherwise, on an npm install, lazy-fetch it (clone + install) unless the
@@ -193,6 +205,8 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
 
       if (!(await requireAvailablePort(emit, port))) return;
 
+      await startSemanticServiceWithWeb(coordRoot, emit);
+
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       emit.log(`harn web · http://localhost:${port} (${mode})`, "info");
       emit.log(`files origin · http://harnery-files.localhost:${port}`, "info");
@@ -281,6 +295,7 @@ export function registerWebCommand(program: Command, emit: EmitContext): void {
         return;
       }
       if (!(await requireAvailablePort(emit, port))) return;
+      await startSemanticServiceWithWeb(coordRoot, emit);
       const heapMb = resolveMaxOldSpaceMb(opts.maxOldSpace);
       emit.log(`harn web · http://localhost:${port} (start)`, "info");
       emit.log(`reading .harnery/ from: ${coordRoot}`, "info");

package/src/core/agents/canonical-emit.ts

@@ -14,6 +14,7 @@ import { spawnSync } from "node:child_process";
 import type { LiveCoordinationObservationV3 } from "../events/v3/live-observation.ts";
 import { coordBinPath } from "./coord-bin.ts";
 import { resolveCoordRoot } from "./coord-client.ts";
+import type { Heartbeat } from "./state/heartbeat-reader.ts";
 
 export type EventV3EmitObservation =
   | LiveCoordinationObservationV3
@@ -96,3 +97,17 @@ export function normalizeAdapter(platform: string | undefined): "claude-code" |
   if (platform === "codex") return "codex";
   return "claude-code";
 }
+
+/** Producer joins use the private native session ID, never its V3 fingerprint. */
+export function nativeSessionIdentity(
+  row: Pick<Heartbeat, "native_session_id" | "session_id"> | null | undefined,
+  fallback: string,
+): string {
+  if (row?.native_session_id) return row.native_session_id;
+  // A projection-only row carries the privacy-safe canonical session
+  // fingerprint, not the adapter's native session ID needed to join the hook
+  // producer. Until a disposable cache exists, the resolved owner is the only
+  // native identity available to command surfaces.
+  if (row?.session_id && !/^sid_[a-f0-9]{64}$/.test(row.session_id)) return row.session_id;
+  return fallback;
+}

package/src/core/agents/claim-path.ts

@@ -0,0 +1,23 @@
+import { isAbsolute, relative, resolve, sep } from "node:path";
+
+/**
+ * Canonical identity for an authority-bearing write claim.
+ *
+ * Workspace paths stay portable and repository-relative. Approved paths
+ * outside the coordination root become resolved absolute paths so a later
+ * release matches whether the caller supplies the stored dot-dot form or the
+ * absolute target. This is lexical identity only; finalization policy owns the
+ * physical containment and symlink checks before a claim is acquired.
+ */
+export function canonicalClaimPath(coordRoot: string, value: string): string {
+  const root = resolve(coordRoot);
+  const absolute = resolve(root, value);
+  const fromRoot = relative(root, absolute);
+  const contained = fromRoot !== ".." && !fromRoot.startsWith(`..${sep}`) && !isAbsolute(fromRoot);
+  if (contained) return portable(fromRoot || ".");
+  return portable(absolute);
+}
+
+function portable(value: string): string {
+  return value.split(sep).join("/");
+}

package/src/core/agents/coord-client.ts

@@ -347,9 +347,10 @@ function readPidmapRow(pidmapDir: string, pid: number): string | null {
  * Prefer a row whose platform matches `HARNERY_AGENT_COORD_PLATFORM` (default
  * `claude-code`); otherwise return the first owner seen on the walk.
  *
- * Subagents intentionally do not write pid-map entries; a Bash-tool ppid-walk
- * from inside a subagent therefore resolves to the *parent's* pid-map entry.
- * v1 ships this behavior; a real subagent-aware bridge is out of scope.
+ * Subagents intentionally do not write pid-map entries; a bare Bash-tool
+ * ppid-walk from inside an unbridged child therefore resolves to the parent's
+ * pid-map entry. Native hook bridges supersede this fallback through the
+ * child session environment.
  */
 export function resolveOwner(): string | null {
   return resolveOwnerWithSource().owner;
@@ -381,9 +382,36 @@ export function resolveOwnerWithSource(): {
   // Every supported adapter exports its native session id into subprocesses.
   // Match it against the live V3 producer state, never a disposable cache.
   if (shouldPreferSessionEnv()) {
-    const bySession = resolveOwnerBySessionEnv(root);
+    const bySession = resolveOwnerBySessionEnvDetailed(root);
     if (bySession) {
-      return { owner: bySession, source: "session_env" };
+      // Env vars cross process boundaries that session identity does not: a
+      // nested different-adapter child inherits its spawner's exported id (a
+      // Codex session's CODEX_THREAD_ID survives into a `claude -p` child's
+      // shells untouched), and that stale statement joins the spawner's live
+      // producer. The nearest token-verified pid-map anchor names the session
+      // whose tool environment this process actually runs in, so on a
+      // CROSS-adapter conflict the anchor wins — the anchoring adapter never
+      // stamps another adapter's variable, so a foreign-adapter id here is
+      // inherited context, while the anchor row is re-healed on every tool
+      // call. A SAME-adapter conflict keeps the env: the adapter stamps its
+      // own variable fresh per tool call, and the row may lag one heal (e.g.
+      // a session id change inside one process). Only per-session-process
+      // adapters may anchor (claude-code, codex) — Cursor sessions share one
+      // terminal process, so a verified Cursor row can belong to a sibling
+      // session. Unverified rows keep losing to the env too: without a start
+      // token the row is the guess the env ordering was introduced to beat.
+      // Never for bridge-marked children: a connector crosses a process-tree
+      // boundary, so an anchor in THIS tree is someone else's by definition.
+      const anchor = bridge ? null : nearestVerifiedSessionAnchor(root);
+      if (
+        anchor &&
+        anchor.owner !== bySession.owner &&
+        !bySession.adapters.includes(anchor.platform) &&
+        (anchor.platform === "claude-code" || anchor.platform === "codex")
+      ) {
+        return { owner: anchor.owner, source: "pidmap" };
+      }
+      return { owner: bySession.owner, source: "session_env" };
     }
   }
 
@@ -410,6 +438,42 @@ export function resolveOwnerWithSource(): {
   return { owner: null, source: "none" };
 }
 
+/**
+ * The nearest pid-map anchor on our own ppid chain whose start token PROVES the
+ * row still describes the process holding that pid, or null when the nearest
+ * row is unverified, recycled, or absent.
+ *
+ * Nearest matters: in a nested-agent tree (session A spawns a headless session
+ * B whose shell runs this code), both A's and B's adapter processes are
+ * ancestors, and only the innermost one owns this process's tool environment.
+ * Exported for unit testing with an injectable root.
+ */
+export function nearestVerifiedSessionAnchor(
+  root: string,
+): { owner: string; platform: string } | null {
+  const pidmapDir = resolve(root, ".harnery", "pid-map");
+  if (!existsSync(pidmapDir)) return null;
+  let pid: number | null = process.pid;
+  for (let hop = 0; hop < 20; hop++) {
+    if (pid === null) break;
+    const row = readPidmapRow(pidmapDir, pid);
+    if (row) {
+      const owner = parsePidmapRowOwner(row);
+      if (owner && !pidWasRecycled(pid, row)) {
+        // A recycled row is about a dead process's tenure of this pid — walk
+        // past it like the owner walk does. A live row without a provable
+        // token match is the nearest anchor but not a VERIFIED one: stop and
+        // report none, so the session env keeps outranking guesses.
+        const token = parsePidmapRowStartToken(row);
+        if (!token || !pidStartToken(pid)) return null;
+        return { owner, platform: parsePidmapRowPlatform(row) };
+      }
+    }
+    pid = readPpid(pid);
+  }
+  return null;
+}
+
 /**
  * Walk our own ppid chain for a pid-map row in ONE given root.
  *
@@ -524,17 +588,37 @@ function shouldPreferSessionEnv(): boolean {
  * Exported for unit testing with an injectable root.
  */
 export function resolveOwnerBySessionEnv(root: string): string | null {
+  return resolveOwnerBySessionEnvDetailed(root)?.owner ?? null;
+}
+
+/**
+ * `resolveOwnerBySessionEnv` plus WHICH adapter's producer state the session id
+ * joined. The caller uses the adapter to tell a same-adapter conflict (the env
+ * var is stamped fresh per tool call and outranks a possibly-lagging pid-map
+ * row) from a cross-adapter one (the var is inherited context from an outer
+ * session and the verified row wins).
+ */
+export function resolveOwnerBySessionEnvDetailed(
+  root: string,
+): { owner: string; adapters: string[] } | null {
   const sessionIds = sessionIdsFromEnv();
   if (sessionIds.length === 0) return null;
   const adapters = adapterCandidatesFromEnv();
-  const matches = new Set<string>();
+  const matches = new Map<string, Set<string>>();
   for (const sessionId of sessionIds) {
     for (const adapter of adapters) {
       const state = readHookProducerStateV3(root, adapter, sessionId);
-      if (state && !state.terminal) matches.add(nativeOwnerForV3Instance(root, state.instance_id));
+      if (state && !state.terminal) {
+        const owner = nativeOwnerForV3Instance(root, state.instance_id);
+        const set = matches.get(owner) ?? new Set<string>();
+        set.add(adapter);
+        matches.set(owner, set);
+      }
     }
   }
-  return matches.size === 1 ? [...matches][0]! : null;
+  if (matches.size !== 1) return null;
+  const [owner, adapterSet] = [...matches.entries()][0]!;
+  return { owner, adapters: [...adapterSet] };
 }
 
 /**

package/src/core/agents/live-authority-v3.ts

@@ -25,6 +25,7 @@ import {
   readTerminalHookProducerStateV3,
   recordHookSignalV3,
 } from "../events/v3/producers/recorder.ts";
+import { canonicalClaimPath } from "./claim-path.ts";
 import {
   acquireClaim,
   type Heartbeat,
@@ -369,7 +370,3 @@ function authorityStateDigest(heartbeat: Heartbeat): `sha256:${string}` {
     }),
   );
 }
-
-function canonicalClaimPath(coordRoot: string, path: string): string {
-  return path.startsWith(`${coordRoot}/`) ? path.slice(coordRoot.length + 1) : path;
-}

package/src/core/agents/live-lifecycle-v3.ts

@@ -10,7 +10,7 @@ import {
   livePlatformV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
-import { readHookProducerStateV3 } from "../events/v3/producers/recorder.ts";
+import { readJoinableHookProducerStateV3 } from "../events/v3/producers/recorder.ts";
 import { writeEventV3 } from "../events/v3/writer.ts";
 import { LiveCoordinationAuthorityV3Error } from "./live-authority-v3.ts";
 import { liveCoordinationAdapterV3 } from "./state/live-coordination-view.ts";
@@ -132,8 +132,13 @@ function withAttestedAdapter<T extends LiveLifecycleObservationBaseV3>(input: T)
 }
 
 function requireHookState(input: LiveLifecycleObservationBaseV3) {
-  const hook = readHookProducerStateV3(input.coordRoot, input.adapter, input.nativeSessionId);
-  if (!hook || hook.instance_id !== liveInstanceIdV3(input.owner)) {
+  const hook = readJoinableHookProducerStateV3(
+    input.coordRoot,
+    input.adapter,
+    input.nativeSessionId,
+    liveInstanceIdV3(input.owner),
+  );
+  if (!hook) {
     throw new LiveCoordinationAuthorityV3Error("hook_generation_not_joinable");
   }
   return hook;

package/src/core/agents/live-observation-v3.ts

@@ -17,7 +17,7 @@ import {
   livePlatformV3,
   resolveLiveEventLedgerRouteV3,
 } from "../events/v3/live-routing.ts";
-import { readHookProducerStateV3 } from "../events/v3/producers/recorder.ts";
+import { readJoinableHookProducerStateV3 } from "../events/v3/producers/recorder.ts";
 import { writeEventV3 } from "../events/v3/writer.ts";
 import { LiveCoordinationAuthorityV3Error } from "./live-authority-v3.ts";
 import { liveCoordinationAdapterV3 } from "./state/live-coordination-view.ts";
@@ -54,7 +54,12 @@ export function recordLiveCoordinationObservationV3(
     throw new LiveCoordinationAuthorityV3Error("control_state_changed");
   }
   const adapter = liveCoordinationAdapterV3(input.coordRoot, input.owner) ?? input.adapter;
-  const hook = readHookProducerStateV3(input.coordRoot, adapter, input.nativeSessionId);
+  const hook = readJoinableHookProducerStateV3(
+    input.coordRoot,
+    adapter,
+    input.nativeSessionId,
+    liveInstanceIdV3(input.owner),
+  );
   if (
     !hook ||
     hook.terminal ||

package/src/core/agents/render/prompt-context.ts

@@ -224,7 +224,7 @@ function computeFocusNudgeIfChanged(
     // Keyed on "a name was ever produced", not task_updated_at: a bare clear
     // as the first declaration must not end the naming window.
     needsNudge = true;
-    nudgeKind = "session-name";
+    nudgeKind = pendingSessionName ? "session-name-pending" : "session-name-unminted";
     message = pendingSessionName
       ? `This session name is still pending display. Before any prose or another tool call, send this exact block as your next assistant text:\n\n${sessionNameDisplayBlock(pendingSessionName)}`
       : `This session has no name yet: run \`${bin} agents set-task "<2-5 word session topic>"\` as your first tool call. ` +
@@ -254,19 +254,22 @@ function computeFocusNudgeIfChanged(
     return "";
   }
 
-  // The session-name reminder is deliberately NOT deduped: it re-emits on
-  // every prompt until a name is produced, because the "still unnamed" state
-  // is the failure state — deduping it erases the only reminder after one
-  // ignored prompt (the miss mode operators reported). Bounded in practice:
-  // Stop rule 3/3 forces a set-task on the first tool-using turn.
-  if (nudgeKind === "session-name") {
+  // An unminted session still gets a fresh reminder on every prompt until its
+  // first focus declaration. Once a name exists, the exact pending-name prompt
+  // is delivered once per minted value. Repeating it on every prompt creates
+  // an unbounded loop on adapters that cannot verify assistant reply text.
+  if (nudgeKind === "session-name-unminted") {
     clearHashFile(hashFile);
     return message;
   }
 
-  // Dedup the task-unset/stale reminders on kind + task state so a repeat
-  // prompt in the same state stays quiet.
-  const state = `${nudgeKind}|task=${taskValue}|updated=${hb.task_updated_at ?? ""}|threshold=${threshold}`;
+  // A pending reminder is keyed only to the minted name: changing the task
+  // must not reconstruct or re-request that older title. Task reminders retain
+  // their own task-state key.
+  const state =
+    nudgeKind === "session-name-pending"
+      ? `${nudgeKind}|name=${pendingSessionName ?? ""}`
+      : `${nudgeKind}|task=${taskValue}|updated=${hb.task_updated_at ?? ""}|threshold=${threshold}`;
   const newHash = sha256Hex16(state);
   const oldHash = safeRead(hashFile);
   if (oldHash && oldHash === newHash) return "";

package/src/core/agents/rules/stop-hook.ts

@@ -138,16 +138,18 @@ export function evaluateStopHookV3Events(
       event.event_type === "turn.completed",
   );
   const latestTerminal = turnTerminals.at(-1);
-  const latestBox = observedBoolean(latestTerminal?.payload.ritual?.status_box_present);
+  const latestBox = observedBoolean(latestTerminal?.payload.ritual?.status_box_present_strict);
   if (req.adapter !== "cursor" && latestBox === undefined) {
     return evidenceUnavailable(
-      "turn.completed has no observed V3 status-box result; Stop remains fail-open",
+      "turn.completed has no observed V3 assistant-text status-box result; Stop remains fail-open",
     );
   }
 
   const ackPresent = req.adapter === "cursor" ? requiredStatusChecked : latestBox === true;
   const ackBlock =
-    req.adapter === "cursor" ? () => rule13Block(coordRoot) : () => rule23Block(coordRoot);
+    req.adapter === "cursor"
+      ? () => rule13Block(coordRoot, req.session_id)
+      : () => rule23Block(coordRoot, req.session_id);
 
   // Pure prose turns keep the human-visible acknowledgement but do not require
   // task or final-status mutations. This preserves the pre-V3 policy exactly.
@@ -161,9 +163,9 @@ export function evaluateStopHookV3Events(
     };
   }
 
-  if (!requiredStatusChecked) return rule13Block(coordRoot);
+  if (!requiredStatusChecked) return rule13Block(coordRoot, req.session_id);
   if (!ackPresent) return ackBlock();
-  if (!taskSet) return rule33Block(coordRoot);
+  if (!taskSet) return rule33Block(coordRoot, req.session_id);
 
   // Claude Code can prove session-name presentation from assistant-only text.
   // Cursor cannot expose that text and Codex returned observe-only above.
@@ -271,7 +273,18 @@ function evidenceUnavailable(reason: string): VerdictResult {
   };
 }
 
-function rule13Block(coordRoot?: string): VerdictResult {
+/**
+ * Remediation commands carry `--session-id` when the session id is known: the
+ * remediating tool call may not descend from a pid-map-registered anchor
+ * (headless children, Cursor shells), and a ppid-walk that resolves to a
+ * DIFFERENT owner records evidence this verdict will never see — the block
+ * then repeats forever while the agent complies every time.
+ */
+function sessionIdSuffix(sessionId?: string): string {
+  return sessionId ? ` --session-id ${sessionId}` : "";
+}
+
+function rule13Block(coordRoot?: string, sessionId?: string): VerdictResult {
   const missingEvidence = agentsRequireGitFinalization(coordRoot)
     ? "no end_turn_checked coord.status_observed event found in this turn"
     : "no coord.status_observed event found in this turn";
@@ -279,16 +292,16 @@ function rule13Block(coordRoot?: string): VerdictResult {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_1_3",
-    reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}\` as your last tool call.`,
+    reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}${sessionIdSuffix(sessionId)}\` as your last tool call.`,
   };
 }
 
-function rule23Block(coordRoot?: string): VerdictResult {
+function rule23Block(coordRoot?: string, sessionId?: string): VerdictResult {
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_2_3",
-    reason: `End-of-turn rule (2/3): turn.completed did not observe the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+    reason: `End-of-turn rule (2/3): turn.completed did not observe the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}${sessionIdSuffix(sessionId)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
   };
 }
 
@@ -335,11 +348,11 @@ function sessionNameBlock(coordRoot: string, instanceId: string): VerdictResult
   };
 }
 
-function rule33Block(coordRoot?: string): VerdictResult {
+function rule33Block(coordRoot?: string, sessionId?: string): VerdictResult {
   return {
     allow: false,
     exit_code: 2,
     rule: "stop-hook.rule_3_3",
-    reason: `End-of-turn rule (3/3): no coord.task_changed event found in this turn; run \`${resolveBinName(coordRoot)} agents set-task "<short focus>"\` to declare what you're working on. Pass an empty string if the turn was purely conversational.`,
+    reason: `End-of-turn rule (3/3): no coord.task_changed event found in this turn; run \`${resolveBinName(coordRoot)} agents set-task${sessionIdSuffix(sessionId)} "<short focus>"\` to declare what you're working on. Pass an empty string if the turn was purely conversational.`,
   };
 }

package/src/core/agents/session-name-display.ts

@@ -36,6 +36,14 @@ export function sessionNameDisplayInstruction(name: string): string {
   ].join("\n");
 }
 
+export function sessionNameDisplayRecoveryInstruction(name: string, binName: string): string {
+  return [
+    sessionNameDisplayInstruction(name),
+    "",
+    `If that exact block was already shown but the gate still rejects tools, run \`${binName} agents suggest-name --json\` as the only tool call. That read-only command is exempt and creates a fresh verification boundary.`,
+  ].join("\n");
+}
+
 /**
  * A PostToolUse result should announce the display protocol only when that
  * exact tool call minted or retried the current suggestion. The coordination row keeps
@@ -143,7 +151,7 @@ export function isSessionNameRemediationCommand(
   if (!body || /[\n;&|<>`$]/.test(body)) return false;
   const escapedBin = binName.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
   const pattern = new RegExp(
-    `^(?:codex-wsl\\s+--\\s+)?${escapedBin}\\s+agents\\s+(?:set-task|status)(?:\\s+.*)?$`,
+    `^(?:codex-wsl\\s+--\\s+)?${escapedBin}\\s+agents\\s+(?:set-task|status|suggest-name)(?:\\s+.*)?$`,
   );
   return pattern.test(body);
 }