harnery 0.36.0 → 0.38.0

package/src/core/agents/reconcile-coordination-v3.ts

@@ -0,0 +1,77 @@
+/**
+ * The canonical supervisor reconcile pass.
+ *
+ * Two things have to happen together, in this order:
+ *
+ *   1. `staleSweep` prunes the disposable coordination cache under
+ *      `.harnery/active` (plus orphaned pid-map and `.last-peer-hash` files)
+ *      and leaves a durable lifecycle observation for every deletion.
+ *   2. `reconcileSessionFinalizationV3` turns those observations, along with
+ *      archive/idle/run/host signals, into session finalization requests.
+ *
+ * Running the sweep first is what makes a single pass self-contained: the
+ * `lifecycle.sweep_observed` rows it writes are visible to the finalizer in
+ * the same pass, so a stale session is both reaped and finalized without
+ * waiting for a later invocation.
+ *
+ * ADR 0077 already specified that `agents reconcile` and session start
+ * discover stale-sweep in the same pass. Both entry points had drifted to
+ * calling only the finalizer, so the sweep never ran outside its own
+ * subcommand. This module is the single composition both now share; adding a
+ * caller means calling this, not re-composing the two halves.
+ */
+
+import {
+  type ReconcileSessionFinalizationOptionsV3,
+  type ReconcileSessionFinalizationResultV3,
+  reconcileSessionFinalizationV3,
+} from "./session-finalizer-v3.ts";
+import { staleSweep } from "./state/stale-sweep.ts";
+
+export interface ReconcileCoordinationResultV3 extends ReconcileSessionFinalizationResultV3 {
+  /** Heartbeat cache files deleted from `.harnery/active` by the sweep. */
+  swept_heartbeats: number;
+  /** Orphaned `.harnery/pid-map` entries deleted by the sweep. */
+  swept_pidmaps: number;
+  /** Dead-owner `.last-peer-hash.*` files deleted by the sweep. */
+  swept_peer_hashes: number;
+}
+
+/**
+ * Sweep the disposable coordination cache, then reconcile session
+ * finalization, and report both sets of counts.
+ *
+ * The sweep owns its own safety contract (configured coordination freshness
+ * for valid rows, an additional stale-mtime gate for malformed or missing
+ * timestamps, and a durable audit record before any deletion, failing closed
+ * when neither can be written). Nothing here loosens it, and a sweep failure
+ * never blocks finalization: the cache is a projection that heals on the
+ * owning agent's next tool call, while the V3 ledger is authoritative.
+ */
+export function reconcileCoordinationV3(
+  coordRoot: string,
+  options: ReconcileSessionFinalizationOptionsV3 = {},
+): ReconcileCoordinationResultV3 {
+  let sweptHeartbeats = 0;
+  let sweptPidmaps = 0;
+  let sweptPeerHashes = 0;
+  const sweepDiagnostics: string[] = [];
+  try {
+    const sweep = staleSweep(coordRoot);
+    sweptHeartbeats = sweep.heartbeatsRemoved.length;
+    sweptPidmaps = sweep.pidmapsRemoved;
+    sweptPeerHashes = sweep.peerHashesRemoved;
+  } catch (error) {
+    sweepDiagnostics.push(
+      `stale_sweep_failed:${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+  const result = reconcileSessionFinalizationV3(coordRoot, options);
+  return {
+    ...result,
+    diagnostics: [...sweepDiagnostics, ...result.diagnostics],
+    swept_heartbeats: sweptHeartbeats,
+    swept_pidmaps: sweptPidmaps,
+    swept_peer_hashes: sweptPeerHashes,
+  };
+}

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

@@ -46,15 +46,18 @@ import {
 import { join } from "node:path";
 
 import { coordEnv } from "../../../lib/env.ts";
+import type { Adapter } from "../../adapter.ts";
 import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.ts";
+import { canReceiveContext } from "../../hooks/adapter/output.ts";
 import { type RemoteMachine, readRemoteMachines } from "../../presence/index.ts";
+import { drainMailbox, formatMailboxDelivery } from "../mailbox.ts";
 import { sessionNameDisplayBlock, sessionNameDisplayPending } from "../session-name-display.ts";
 import {
   readLiveCoordinationRow,
   readLiveCoordinationRows,
 } from "../state/live-coordination-view.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
-import { formatPendingCouncils } from "./session-context.ts";
+import { formatPendingCouncils, recordDeliveredMessages } from "./session-context.ts";
 
 interface HeartbeatRow {
   instance_id?: string;
@@ -92,6 +95,11 @@ export interface PromptContextOpts {
   /** When true, append the non-deduplicated Codex status-footer reminder.
    * The caller enables this only for human-facing Codex sessions. */
   statusFooterNudge?: boolean;
+  /** Adapter id this prompt is being rendered for. Gates the mailbox drain:
+   * an adapter that cannot receive UserPromptSubmit context must not consume
+   * messages here, or they are removed from the queue and never shown. When
+   * omitted, delivery is attempted (the default route can receive). */
+  adapter?: string;
   /** Adapter id whose Stop hook ENFORCES the end-of-turn ritual (task_set +
    * status check). When set, append a fresh per-prompt reminder of that
    * contract so the model satisfies it before ending the turn instead of
@@ -119,20 +127,43 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     hostPromptReminder: promptReminderEnabled,
     statusFooterNudge,
     turnRitualNudge,
+    adapter,
   } = opts;
   const sections: string[] = [];
 
-  // 1. Peer table with hash dedup.
+  // The hook route does not pass --name, so resolve it from the heartbeat.
+  // Every name-addressed section below (messages, councils) is silently
+  // skipped without it.
+  const resolvedName = agentName ?? readLiveCoordinationRow(coordRoot, instanceId)?.name;
+
+  // 1. Peer messages. Drained first and never deduped: a message is delivered
+  // exactly once, and it is the one section here that carries new information
+  // from another agent rather than a reminder.
+  //
+  // Draining is gated on the adapter being able to receive this event's
+  // context. Cursor cannot, so draining there would empty the queue into output
+  // that is discarded; those sessions get their messages at SessionStart, which
+  // Cursor does deliver.
+  const canDeliverHere = !adapter || canReceiveContext(adapter as Adapter, "UserPromptSubmit");
+  if (resolvedName && canDeliverHere) {
+    const delivered = drainMailbox(coordRoot, resolvedName);
+    if (delivered.length > 0) {
+      recordDeliveredMessages(instanceId, delivered);
+      sections.push(formatMailboxDelivery(coordRoot, delivered));
+    }
+  }
+
+  // 2. Peer table with hash dedup.
   const peerTable = computePeerTableIfChanged(coordRoot, instanceId, sessionId);
   if (peerTable) sections.push(peerTable);
 
-  // 2. Council pending with hash dedup.
-  if (agentName) {
-    const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, agentName);
+  // 3. Council pending with hash dedup.
+  if (resolvedName) {
+    const councilMsg = computeCouncilPendingIfChanged(coordRoot, instanceId, resolvedName);
     if (councilMsg) sections.push(councilMsg);
   }
 
-  // 3. First-session naming for every adapter, plus unset/stale-task reminders
+  // 4. First-session naming for every adapter, plus unset/stale-task reminders
   // for Cursor/Codex. One state machine avoids a second generic "task unset"
   // reminder immediately after the first-session reminder has been deduped.
   if (sessionNameNudge || taskNudge) {
@@ -143,7 +174,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (nudgeMsg) sections.push(nudgeMsg);
   }
 
-  // 4. A supported adapter gets the host reminder on every prompt. The text is
+  // 5. A supported adapter gets the host reminder on every prompt. The text is
   // intentionally not hash-deduped or persisted into runtime state: freshness
   // is the feature, and the project config remains its only durable copy.
   if (promptReminderEnabled) {
@@ -151,7 +182,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (reminder) sections.push(reminder);
   }
 
-  // 5. Codex gets this on every prompt. It is intentionally not hash-deduped:
+  // 6. Codex gets this on every prompt. It is intentionally not hash-deduped:
   // the reminder must be fresh in the model's context when it writes the reply.
   // Missing it is harmless because Codex Stop enforcement remains observe-only.
   if (statusFooterNudge) {
@@ -159,7 +190,7 @@ export function renderPromptContext(opts: PromptContextOpts): string {
     if (statusMsg) sections.push(statusMsg);
   }
 
-  // 6. Adapters whose Stop hook ENFORCES the turn ritual get a fresh reminder
+  // 7. Adapters whose Stop hook ENFORCES the turn ritual get a fresh reminder
   // on every prompt. Reminding before the reply is drafted is far cheaper than
   // the bounce-and-retry the Stop hook otherwise forces: enforcement-only
   // compliance was measured missing on a double-digit share of turns. Not
@@ -188,10 +219,9 @@ function renderTurnRitualReminder(
 
   const bin = resolveBinName(coordRoot);
   const statusCommand = endOfTurnStatusCommand(coordRoot);
-  // Claude Code renders the status box only if the reply carries it; Cursor
-  // shows the box inline on its own, so it is never asked for a second copy.
+  // Claude Code and Cursor can both enforce completed assistant reply text.
   const paste =
-    adapter === "claude-code"
+    adapter === "claude-code" || adapter === "cursor"
       ? " and paste its output verbatim in a fenced code block at the end of your reply"
       : "";
   return (

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

@@ -12,7 +12,9 @@ import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { resolveBinName, resolveHooksSetupHint } from "../../config.ts";
 import { harneryVersion, loadAdapterWiring } from "../../hooks/adapter/wiring.ts";
+import { appendEntry } from "../../journal/index.ts";
 import { readRemoteMachines } from "../../presence/index.ts";
+import { drainMailbox, formatMailboxDelivery, type MailboxMessageV1 } from "../mailbox.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 import { readForkParent } from "../state/names.ts";
 import type { AgentActivity, TaskState } from "../state/session-state.ts";
@@ -82,13 +84,24 @@ export function renderSessionContext(opts: RenderOpts): string {
     );
   }
 
-  // 3. Council invites
+  // 3. Peer messages queued for this name while no session held it. Draining
+  // here is what makes `agents ping` safe to use on a dormant agent: the sender
+  // never has to know whether the recipient is running.
+  if (agentName) {
+    const delivered = drainMailbox(coordRoot, agentName);
+    if (delivered.length > 0) {
+      recordDeliveredMessages(instanceId, delivered);
+      messages.push(formatMailboxDelivery(coordRoot, delivered));
+    }
+  }
+
+  // 4. Council invites
   if (agentName) {
     const councilMsg = formatPendingCouncils(coordRoot, agentName);
     if (councilMsg) messages.push(councilMsg);
   }
 
-  // 4. Commit-guard wiring check
+  // 5. Commit-guard wiring check
   const wiringIssues = checkWiring(coordRoot);
   if (wiringIssues.length > 0) {
     const hint = resolveHooksSetupHint(coordRoot);
@@ -99,7 +112,7 @@ export function renderSessionContext(opts: RenderOpts): string {
     messages.push(wiringSummary);
   }
 
-  // 5. Adapter-hook drift: a harnery upgrade changed the hook set, but this
+  // 6. Adapter-hook drift: a harnery upgrade changed the hook set, but this
   // project's settings file hasn't been re-wired. Only fires for a adapter the
   // project already opted into (≥1 hook wired), so it never nags a project that
   // simply has a settings file. Remedy is always `<bin> init` (idempotent).
@@ -125,6 +138,27 @@ export function renderSessionContext(opts: RenderOpts): string {
   return messages.join("\n\n");
 }
 
+/**
+ * Write delivered peer messages into the recipient's own journal, so they
+ * survive context compaction the way any other coordination breadcrumb does.
+ * A message the sender already journaled (the recipient was live when it was
+ * sent) is skipped to avoid a duplicate entry.
+ */
+export function recordDeliveredMessages(
+  instanceId: string,
+  messages: readonly MailboxMessageV1[],
+): void {
+  for (const m of messages) {
+    if (m.journaled) continue;
+    try {
+      appendEntry(instanceId, "handoff", `from agent-${m.from_name}: ${m.body}`);
+    } catch {
+      // A journal write failure must never cost the delivery itself; the
+      // message is already in the rendered context the model reads.
+    }
+  }
+}
+
 /** One-line-per-agent view of sessions on other machines (presence refs). */
 function formatRemoteMachines(coordRoot: string): string {
   try {

package/src/core/agents/rules/commit-conflict.ts

@@ -25,6 +25,7 @@ import { appendFileSync, existsSync } from "node:fs";
 import { basename, dirname, join } from "node:path";
 import { coordFreshnessSeconds } from "../../config.ts";
 import { resolveOwner } from "../../hooks/resolve/owner.ts";
+import { recordLiveClaimChangeV3 } from "../live-authority-v3.ts";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.ts";
 import { instanceHasLivePid } from "../state/pidmap.ts";
 
@@ -34,6 +35,7 @@ interface PeerHeartbeat {
   name?: string;
   files_touched?: string[];
   last_heartbeat?: string;
+  platform?: string;
 }
 
 interface Conflict {
@@ -190,6 +192,15 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
     };
   }
 
+  // A blocked commit proves this session has work in every staged path, even
+  // when the edit hook never acquired a claim (for example, a shell edit made
+  // just before another session claimed the same file). Keep those paths on
+  // the blocked session's durable claim set. The original holder's later
+  // commit will then see the overlap instead of silently sweeping this
+  // session's working-tree hunks. A successful later commit releases clean
+  // paths through the existing post-commit hook.
+  retainBlockedStagedPaths(coordRoot, me, mySession, req.staged_paths, peers);
+
   return {
     allow: false,
     exit_code: 1,
@@ -204,6 +215,41 @@ export function evaluateCommit(coordRoot: string, req: CommitVerdictRequest): Co
   };
 }
 
+function retainBlockedStagedPaths(
+  coordRoot: string,
+  instanceId: string,
+  sessionId: string,
+  stagedPaths: readonly string[],
+  peers: readonly PeerHeartbeat[],
+): void {
+  if (instanceId === "__unattributed__") return;
+  const self = peers.find((peer) => peer.instance_id === instanceId);
+  if (!self) return;
+
+  for (const path of stagedPaths) {
+    try {
+      recordLiveClaimChangeV3({
+        coordRoot,
+        owner: instanceId,
+        nativeSessionId: self.session_id ?? sessionId,
+        adapter: adapterFromPlatform(self.platform),
+        operation: "acquired",
+        path,
+        access: "write",
+      });
+    } catch {
+      // The commit is already blocked. Coordination remains fail-open for
+      // authority-write failures so a damaged cache cannot brick Git.
+    }
+  }
+}
+
+function adapterFromPlatform(platform: unknown): "claude-code" | "cursor" | "codex" {
+  if (platform === "cursor") return "cursor";
+  if (platform === "codex") return "codex";
+  return "claude-code";
+}
+
 function findOverlap(
   staged: string,
   files: readonly string[],
@@ -269,6 +315,18 @@ function isHolderSelfAttributed(
   stagedSet: Set<string>,
   peers: readonly PeerHeartbeat[],
 ): boolean {
+  const holder = peers.find((p) => p.instance_id === holderId);
+
+  // Windows-hosted Codex sessions cross a process boundary into WSL, so they
+  // deliberately have no usable PID anchor. Their canonical V3 session row is
+  // the foreign-identity evidence instead. Treating that row as a transient
+  // self identity would suppress the symmetric claim retained after a blocked
+  // commit and reopen the working-tree sweep this guard is meant to stop.
+  if (holder?.platform === "codex" && holder.session_id) {
+    debugGate(coordRoot, { holder: holderId, gate: "B", reason: "canonical_codex_session" });
+    return false;
+  }
+
   // Gate B (cheaper): live foreign pid-map entry blocks self-attribution.
   if (holderHasLiveForeignPid(coordRoot, holderId)) {
     debugGate(coordRoot, { holder: holderId, gate: "B", reason: "live_pid_anchor" });
@@ -276,7 +334,6 @@ function isHolderSelfAttributed(
   }
 
   // Gate A: every held path is either in the staged set or already clean in HEAD.
-  const holder = peers.find((p) => p.instance_id === holderId);
   if (!holder) {
     debugGate(coordRoot, { holder: holderId, gate: "A", reason: "holder_not_found" });
     return false;

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

@@ -154,22 +154,16 @@ export function evaluateStopHookV3Events(
     .map((event) => observedBoolean(event.payload.ritual?.status_box_present_strict))
     .filter((value): value is boolean => value !== undefined);
   const currentStrictBox = claudeContinuation ? req.status_box_present_strict : undefined;
-  if (req.adapter !== "cursor" && latestBox === undefined && currentStrictBox === undefined) {
+  if (latestBox === undefined && currentStrictBox === undefined) {
     return evidenceUnavailable(
       "turn.completed has no observed V3 assistant-text status-box result; Stop remains fail-open",
     );
   }
 
-  const ackPresent =
-    req.adapter === "cursor"
-      ? requiredStatusChecked
-      : claudeContinuation
-        ? strictBoxObservations.includes(true) || currentStrictBox === true
-        : latestBox === true;
-  const ackBlock =
-    req.adapter === "cursor"
-      ? () => rule13Block(coordRoot, req.session_id)
-      : () => rule23Block(coordRoot, req.session_id);
+  const ackPresent = claudeContinuation
+    ? strictBoxObservations.includes(true) || currentStrictBox === true
+    : latestBox === true;
+  const ackBlock = () => 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.
@@ -354,7 +348,7 @@ function sessionIdSuffix(sessionId?: string): string {
  * The verdict keeps the first failure's rule id, so the `blocked_rule`
  * telemetry and the adapter's `rule=` stderr contract are unchanged; the
  * reason enumerates the rest so a single continuation can repair all of them.
- * Cursor maps the acknowledgement onto rule 1/3, so identical rules dedupe.
+ * Duplicate rules are folded so one continuation repairs every missing signal.
  */
 function mergeStopBlocks(blocks: VerdictResult[]): VerdictResult | undefined {
   let primary: VerdictResult | undefined;

package/src/core/agents/session-finalizer-v3.ts

@@ -584,7 +584,10 @@ function observeCascades(
     }
     if (
       event.event_type === "lifecycle.sweep_observed" &&
-      event.payload.observation === "stale_sweep"
+      // stale-sweep.ts emits the observation as `stale_heartbeat`; the
+      // finalization request it produces is the one named `stale_sweep`.
+      // Matching the request name here made this branch unreachable.
+      event.payload.observation === "stale_heartbeat"
     ) {
       const record = records.find(
         ({ state }) => !state.terminal && state.instance_id === event.payload.subject_instance_id,

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

@@ -8,6 +8,7 @@
 export interface SessionNameDisplayState {
   suggested_session_name?: string;
   session_name_seen_for?: string;
+  session_name_display_requested_for?: string;
 }
 
 export const SESSION_NAME_DISPLAY_NOTE =
@@ -21,6 +22,45 @@ export function sessionNameDisplayPending(
   return name;
 }
 
+/**
+ * Every title whose exact display satisfies the current latch.
+ *
+ * The pending title always counts. The title the agent was last instructed to
+ * display also counts, because the harness — not the agent — is what changed
+ * the target after asking. Accepting it costs nothing the operator can see: a
+ * clean one-line block did open that reply. Refusing it left Cursor sessions
+ * permanently latched, since no Cursor surface can re-open a missed window.
+ */
+export function sessionNameDisplayAcceptedNames(
+  row: SessionNameDisplayState | null | undefined,
+): string[] {
+  const pending = sessionNameDisplayPending(row);
+  if (!pending) return [];
+  const requested = row?.session_name_display_requested_for;
+  return requested && requested !== pending ? [pending, requested] : [pending];
+}
+
+/**
+ * Match assistant text against any accepted title and report which one closed
+ * the latch, so a drifted display can be stamped against the pending title and
+ * logged as drift rather than silently discarded.
+ */
+export function matchSessionNameDisplay(
+  row: SessionNameDisplayState | null | undefined,
+  text: string | undefined,
+  startsWithBlock: (
+    text: string,
+    expectedName: string,
+  ) => boolean = assistantTextStartsWithSessionNameBlock,
+): { pending: string; displayed: string } | null {
+  if (!text) return null;
+  const accepted = sessionNameDisplayAcceptedNames(row);
+  const pending = accepted[0];
+  if (!pending) return null;
+  const displayed = accepted.find((candidate) => startsWithBlock(text, candidate));
+  return displayed ? { pending, displayed } : null;
+}
+
 export function sessionNameDisplayBlock(name: string): string {
   return `\`\`\`\n${name}\n\`\`\``;
 }
@@ -80,10 +120,16 @@ function responseContainsSessionNameMint(
           return true;
         }
       } catch {
-        // Wrapper prose and partial JSON are not authoritative mint evidence.
+        // Fall through to the textual check below.
       }
     }
-    return false;
+    // The mint command's stdout often reaches the transcript mangled: cut
+    // short by `cut`/`head -c`, or with a tail-truncated first line. Whole-JSON
+    // parsing then fails even though the name and the mint flag are both
+    // legible, and a session that did mint can never latch. Accept the text
+    // when the exact quoted name sits under its key AND a mint flag is true;
+    // ordinary status output carries the name without any flag.
+    return textCarriesSessionNameMint(value, name);
   }
 
   if (typeof value !== "object") return false;
@@ -107,16 +153,41 @@ function responseContainsSessionNameMint(
   );
 }
 
+const MINT_FLAG_PATTERN = /"(?:first_of_session|name_reminted|session_name_retry)"\s*:\s*true\b/;
+
+function textCarriesSessionNameMint(text: string, name: string): boolean {
+  const quotedName = JSON.stringify(name);
+  const keyIndex = text.indexOf('"suggested_session_name"');
+  if (keyIndex < 0) return false;
+  const afterKey = text.slice(keyIndex + '"suggested_session_name"'.length);
+  const valueMatch = /^\s*:\s*("(?:[^"\\]|\\.)*")/.exec(afterKey);
+  if (!valueMatch || valueMatch[1] !== quotedName) return false;
+  return MINT_FLAG_PATTERN.test(text);
+}
+
 /**
- * Accept the exact unlabelled block Harnery requests. `text` and `plaintext`
- * are tolerated for older prompts, but the code block may contain only the
- * suggested name and must be the first non-whitespace user-facing content.
+ * A leading fenced block whose only line is the suggested name.
+ *
+ * What the contract protects is what the operator sees: the reply opens with a
+ * code block containing exactly the title, so it renders as one clean
+ * copy-pasteable line. The fence's info string changes none of that, so any
+ * single-word language tag passes. Restricting it to `text`/`plaintext` meant a
+ * model that wrote ```txt or ```markdown produced a display the operator could
+ * read perfectly while the latch refused to close — and since nothing else can
+ * close a Cursor latch, that mismatch stranded the whole session.
+ *
+ * Still exact in every load-bearing way: the block is the first user-facing
+ * content, holds one line, and that line equals the name. The backreference
+ * requires the closing fence to match the opening run, so a longer fence cannot
+ * be closed by a shorter one.
  */
+const LEADING_SESSION_NAME_BLOCK =
+  /^(`{3,})[ \t]*[A-Za-z0-9_.+#-]*[ \t]*\n([^\n]*)\n\1[ \t]*(?:\n|$)/;
+
 export function assistantTextStartsWithSessionNameBlock(text: string, name: string): boolean {
   if (!text || !name) return false;
   const normalized = text.replace(/\r\n?/g, "\n").trimStart();
-  const match = /^```(?:text|plaintext)?[ \t]*\n([^\n]*)\n```(?:[ \t]*(?:\n|$))/.exec(normalized);
-  return match?.[1] === name;
+  return LEADING_SESSION_NAME_BLOCK.exec(normalized)?.[2] === name;
 }
 
 /**

package/src/core/agents/state/heartbeat-reader.ts

@@ -33,6 +33,13 @@ export interface Heartbeat {
   session_name_seen_at?: string;
   /** The specific suggested name proven present by the sighting stamp. */
   session_name_seen_for?: string;
+  /**
+   * The suggested name the agent was last actually instructed to display.
+   * Usually identical to `suggested_session_name`; it differs only when the
+   * title changed after the instruction went out, and a display of it still
+   * counts so that drift cannot strand the latch.
+   */
+  session_name_display_requested_for?: string;
   last_status_at?: string;
   current_turn_id?: string;
   parent_instance_id?: string;

package/src/core/agents/state/heartbeat-writer.ts

@@ -180,6 +180,29 @@ export function stampSessionNameSeen(
   }));
 }
 
+/**
+ * Remember which title the agent was actually asked to display.
+ *
+ * The gate can only ask for a display through the PostToolUse instruction, and
+ * the title it names can change afterwards (an assigned-name rewrite of an
+ * `Agent unknown - ...` suggestion, a lifecycle re-mint, a rebuilt cache that
+ * re-minted from the current task). Without this record the agent's correct
+ * display of the title it was handed matches nothing, the latch never closes,
+ * and on Cursor no later surface can repair it.
+ */
+export function stampSessionNameRequested(
+  coordRoot: string,
+  instanceId: string,
+  name: string,
+): Heartbeat | null {
+  if (!name) return null;
+  return mutate(coordRoot, instanceId, (hb) =>
+    hb.session_name_display_requested_for === name
+      ? hb
+      : { ...hb, session_name_display_requested_for: name },
+  );
+}
+
 export function releaseClaim(
   coordRoot: string,
   instanceId: string,

package/src/core/agents/state/live-coordination-view.ts

@@ -197,6 +197,7 @@ export function projectHeartbeatV3(
     suggested_session_name: cache?.suggested_session_name,
     session_name_seen_at: cache?.session_name_seen_at,
     session_name_seen_for: cache?.session_name_seen_for,
+    session_name_display_requested_for: cache?.session_name_display_requested_for,
     workflow_run_id: generation.run_id,
     workflow_agent_id: generation.workflow_agent_id,
     parent_instance_id: parent ? nativeInstanceIdV3(parent.instance_id) : undefined,

package/src/core/agents/state/live-coordination-writer.ts

@@ -107,6 +107,11 @@ function materializeLiveCoordinationHeartbeat(
           ...(current.session_name_seen_at
             ? { session_name_seen_at: current.session_name_seen_at }
             : {}),
+          ...(current.session_name_display_requested_for
+            ? {
+                session_name_display_requested_for: current.session_name_display_requested_for,
+              }
+            : {}),
         }
       : {};
   const materialized: V3HeartbeatMaterialization = {

package/src/core/artifacts/constants.ts

@@ -1,4 +1,4 @@
 /** Read-only artifact layout constants safe for browser-side server modules. */
 export const ARTIFACTS_DIR = ".harnery/artifacts";
 export const ARTIFACT_MANIFEST = ".harnery-artifact.json";
-export const ARTIFACT_SCHEMA_VERSION = 1 as const;
+export const ARTIFACT_SCHEMA_VERSION = 2 as const;