harnery 0.46.0 → 0.47.0

package/dist/core/agents/render/prompt-context.d.ts

@@ -7,9 +7,10 @@
  * and forwards the result as the adapter-shaped additionalContext payload.
  *
  * Four subsections combined into one additionalContext payload:
- *   1. Peer table: semantically-relevant peer fields hashed; only re-emits
- *      when peers change (name + instance_id + session_id + kind + started_at
- *      + sorted(files_touched) + platform, sorted by instance_id).
+ *   1. Peer table: re-emits only when a live peer arrives or leaves, changes
+ *      lifecycle, or changes its claimed files. Activity and task text never
+ *      trigger a reprint. Peers past the heartbeat-freshness window are left
+ *      out and counted in "+N more".
  *   2. Council pending: pending open-council IDs hashed; re-emits when the
  *      ID set changes.
  *   3. Focus nudge. Until the session has displayed its current suggested
@@ -24,14 +25,37 @@
  *   5. Codex status footer: a non-deduplicated reminder to put the live status
  *      box after the substantive answer. Stop stays observe-only, so missing the
  *      footer can never trigger a replacement response.
+ *   6. Turn ritual: for adapters whose Stop hook enforces the ritual, shown on
+ *      the first prompt, after a compaction, and after a bounced turn.
  *
  * Hash files live at:
+ *   .harnery/.last-turn-ritual.<instance_id>
  *   .harnery/.last-peer-hash.<instance_id>
  *   .harnery/.last-council-hash.<instance_id>
  *   .harnery/.last-task-nudge-hash.<instance_id>
  *
  * First call always emits (hash files don't exist).
  */
+import { type RemoteMachine } from "../../presence/index.js";
+import type { AgentActivity, TaskState } from "../state/session-state.js";
+interface HeartbeatRow {
+    instance_id?: string;
+    name?: string;
+    kind?: string;
+    session_id?: string;
+    started_at?: string;
+    last_heartbeat?: string;
+    files_touched?: string[];
+    platform?: string;
+    task?: string;
+    activity?: AgentActivity;
+    task_state?: TaskState;
+    task_state_reason?: string;
+    task_updated_at?: string | null;
+    suggested_session_name?: string;
+    session_name_seen_for?: string;
+    workflow_run_id?: string;
+}
 export interface PromptContextOpts {
     coordRoot: string;
     instanceId: string;
@@ -50,10 +74,9 @@ export interface PromptContextOpts {
      * The caller enables this only for human-facing Codex sessions. */
     statusFooterNudge?: boolean;
     /** 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
-     * being bounced into a retry. Not hash-deduped, same rationale as the
-     * status footer. */
+     * status check). When set, append a reminder of that contract on the
+     * session's first prompt, after a context compaction, and after a turn the
+     * Stop hook bounced (see `markTurnRitualBounced`). */
     turnRitualNudge?: string;
     /** The emitter acknowledges exactly these IDs only after output succeeds. */
     onInboxPrepared?: (messageIds: readonly string[]) => void;
@@ -74,4 +97,29 @@ export declare function renderPromptContext(opts: PromptContextOpts): string;
  * re-emit the same advice.
  */
 export declare function resourceWarningIfChanged(coordRoot: string, instanceId: string): string;
+/**
+ * Called by the Stop hook when it blocks a turn for a missing ritual step, so
+ * the next prompt carries the reminder again.
+ */
+export declare function markTurnRitualBounced(coordRoot: string, instanceId: string): void;
+export interface PeerTableInput {
+    peers: HeartbeatRow[];
+    remote: RemoteMachine[];
+    mySessionId: string;
+    nowMs: number;
+    /** Sessions whose last heartbeat is older than this are folded into "+N more". */
+    freshnessSeconds: number;
+    relations?: Map<string, string>;
+}
+/**
+ * Pure peer-table render plus its change key. The key covers only what makes
+ * the table news: which live sessions exist, their lifecycle, and the files
+ * they claim. Activity and task text change on nearly every peer tool call, so
+ * they render in the table but never trigger a reprint by themselves.
+ */
+export declare function renderPeerTable(input: PeerTableInput): {
+    hash: string;
+    table: string;
+};
+export {};
 //# sourceMappingURL=prompt-context.d.ts.map

package/dist/core/agents/render/prompt-context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAiDH,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;kFAC8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;wBAIoB;IACpB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA8EnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA6CtF"}
+{"version":3,"file":"prompt-context.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/render/prompt-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAwBH,OAAO,EAAE,KAAK,aAAa,EAAsB,MAAM,yBAAyB,CAAC;AASjF,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAG1E,UAAU,YAAY;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;IACzB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,iBAAiB;IAChC,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;8EAC0E;IAC1E,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B;kFAC8E;IAC9E,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;kFAC8E;IAC9E,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;uEACmE;IACnE,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;0DAGsD;IACtD,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,6EAA6E;IAC7E,eAAe,CAAC,EAAE,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,KAAK,IAAI,CAAC;CAC3D;AAED;;;;;;;GAOG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,CA6EnE;AAED;;;;;GAKG;AACH,wBAAgB,wBAAwB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CA6CtF;AAsBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,CAEjF;AA0LD,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,MAAM,EAAE,aAAa,EAAE,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,KAAK,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,gBAAgB,EAAE,MAAM,CAAC;IACzB,SAAS,CAAC,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACjC;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,CA2CtF"}

package/dist/core/agents/render/prompt-context.js

@@ -7,9 +7,10 @@
  * and forwards the result as the adapter-shaped additionalContext payload.
  *
  * Four subsections combined into one additionalContext payload:
- *   1. Peer table: semantically-relevant peer fields hashed; only re-emits
- *      when peers change (name + instance_id + session_id + kind + started_at
- *      + sorted(files_touched) + platform, sorted by instance_id).
+ *   1. Peer table: re-emits only when a live peer arrives or leaves, changes
+ *      lifecycle, or changes its claimed files. Activity and task text never
+ *      trigger a reprint. Peers past the heartbeat-freshness window are left
+ *      out and counted in "+N more".
  *   2. Council pending: pending open-council IDs hashed; re-emits when the
  *      ID set changes.
  *   3. Focus nudge. Until the session has displayed its current suggested
@@ -24,8 +25,11 @@
  *   5. Codex status footer: a non-deduplicated reminder to put the live status
  *      box after the substantive answer. Stop stays observe-only, so missing the
  *      footer can never trigger a replacement response.
+ *   6. Turn ritual: for adapters whose Stop hook enforces the ritual, shown on
+ *      the first prompt, after a compaction, and after a bounced turn.
  *
  * Hash files live at:
+ *   .harnery/.last-turn-ritual.<instance_id>
  *   .harnery/.last-peer-hash.<instance_id>
  *   .harnery/.last-council-hash.<instance_id>
  *   .harnery/.last-task-nudge-hash.<instance_id>
@@ -36,7 +40,8 @@ import { createHash } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync, } from "node:fs";
 import { join } from "node:path";
 import { coordEnv } from "../../../lib/env.js";
-import { endOfTurnStatusCommand, hostPromptReminder, resolveBinName } from "../../config.js";
+import { coordFreshnessSeconds, endOfTurnStatusCommand, hostPromptReminder, resolveBinName, } from "../../config.js";
+import { readContextState } from "../../context/index.js";
 import { formatPeerInbox, peerInbox } from "../../inbox/peer-messages.js";
 import { readRemoteMachines } from "../../presence/index.js";
 import { readResourceStatus } from "../../resources/status.js";
@@ -107,13 +112,12 @@ export function renderPromptContext(opts) {
         if (statusMsg)
             sections.push(statusMsg);
     }
-    // 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
-    // hash-deduped for the same reason as the Codex footer.
+    // 7. Adapters whose Stop hook ENFORCES the turn ritual get the reminder when
+    // it is news: on the session's first prompt, after a context compaction,
+    // and after a turn the Stop hook bounced. The Stop hook keeps enforcing on
+    // every turn, so a missed ritual still costs one retry and re-arms this.
     if (turnRitualNudge) {
-        const ritualMsg = renderTurnRitualReminder(coordRoot, instanceId, turnRitualNudge);
+        const ritualMsg = renderTurnRitualReminder(coordRoot, instanceId, sessionId, turnRitualNudge);
         if (ritualMsg)
             sections.push(ritualMsg);
     }
@@ -181,17 +185,46 @@ function renderHostPromptReminder(coordRoot, selfInstanceId) {
         return "";
     return hostPromptReminder(coordRoot) ?? "";
 }
-function renderTurnRitualReminder(coordRoot, selfInstanceId, adapter) {
+function turnRitualStatePath(coordRoot, instanceId) {
+    return join(coordRoot, ".harnery", `.last-turn-ritual.${instanceId}`);
+}
+const TURN_RITUAL_BOUNCED = "bounced";
+/**
+ * Called by the Stop hook when it blocks a turn for a missing ritual step, so
+ * the next prompt carries the reminder again.
+ */
+export function markTurnRitualBounced(coordRoot, instanceId) {
+    writeHashFile(turnRitualStatePath(coordRoot, instanceId), TURN_RITUAL_BOUNCED);
+}
+function renderTurnRitualReminder(coordRoot, selfInstanceId, sessionId, adapter) {
     const hb = readLiveCoordinationRow(coordRoot, selfInstanceId);
     if (!hb || hb.kind === "subagent" || hb.kind === "transient" || hb.workflow_run_id)
         return "";
+    // The key changes when native context compaction drops the earlier reminder.
+    let generation = 0;
+    try {
+        generation = readContextState(coordRoot, sessionId)?.generation ?? 0;
+    }
+    catch {
+        /* no continuity state: treat as the first context generation */
+    }
+    const key = `context-generation=${generation}`;
+    const statePath = turnRitualStatePath(coordRoot, selfInstanceId);
+    const previous = safeRead(statePath);
+    if (previous === key)
+        return "";
+    writeHashFile(statePath, key);
+    const bounced = previous === TURN_RITUAL_BOUNCED
+        ? "Your previous turn was bounced by the Stop hook because the ritual was incomplete. "
+        : "";
     const bin = resolveBinName(coordRoot);
     const statusCommand = endOfTurnStatusCommand(coordRoot);
     // Claude Code and Cursor can both enforce completed assistant reply text.
     const paste = adapter === "claude-code" || adapter === "cursor"
         ? " and paste its output verbatim in a fenced code block at the end of your reply"
         : "";
-    return (`Turn ritual (Stop-enforced): on any turn that uses tools, run \`${bin} agents set-task "<short focus>"\` at some point during the turn (required every turn, even when the focus is unchanged; pass an empty string when there is no meaningful focus), then make \`${statusCommand}\` your final tool call${paste}. ` +
+    return (bounced +
+        `Turn ritual (Stop-enforced): on any turn that uses tools, run \`${bin} agents set-task "<short focus>"\` at some point during the turn (required every turn, even when the focus is unchanged; pass an empty string when there is no meaningful focus), then make \`${statusCommand}\` your final tool call${paste}. ` +
         "A turn that ends without these is bounced by the Stop hook and costs a retry.");
 }
 function renderStatusFooterReminder(coordRoot, selfInstanceId) {
@@ -299,8 +332,43 @@ function computePeerTableIfChanged(coordRoot, selfInstanceId, selfSessionIdFallb
     const remote = readRemoteMachinesSafe(coordRoot);
     if (peers.length === 0 && remote.length === 0)
         return "";
-    // Build hash basis: sorted-by-instance_id projection of semantically-relevant fields.
-    const basis = peers
+    const rendered = renderPeerTable({
+        peers,
+        remote,
+        mySessionId,
+        nowMs: Date.now(),
+        freshnessSeconds: coordFreshnessSeconds(coordRoot),
+        relations: forkRelationLabels(coordRoot, selfInstanceId, new Set(peers.map((p) => p.instance_id ?? ""))),
+    });
+    if (!rendered.table)
+        return "";
+    const hashFile = join(coordRoot, ".harnery", `.last-peer-hash.${selfInstanceId}`);
+    const oldHash = safeRead(hashFile);
+    if (oldHash && oldHash === rendered.hash)
+        return "";
+    // Persist hash atomically (temp + rename, same convention as other coord writes).
+    writeHashFile(hashFile, rendered.hash);
+    return rendered.table;
+}
+/**
+ * Pure peer-table render plus its change key. The key covers only what makes
+ * the table news: which live sessions exist, their lifecycle, and the files
+ * they claim. Activity and task text change on nearly every peer tool call, so
+ * they render in the table but never trigger a reprint by themselves.
+ */
+export function renderPeerTable(input) {
+    const { peers, remote, mySessionId, nowMs, freshnessSeconds } = input;
+    const cutoffMs = nowMs - freshnessSeconds * 1000;
+    const live = [];
+    const stale = [];
+    for (const peer of peers) {
+        const seenMs = Date.parse(peer.last_heartbeat ?? "");
+        if (Number.isFinite(seenMs) && seenMs >= cutoffMs)
+            live.push(peer);
+        else
+            stale.push(peer);
+    }
+    const basis = live
         .map((p) => ({
         name: p.name ?? null,
         instance_id: p.instance_id ?? null,
@@ -309,39 +377,28 @@ function computePeerTableIfChanged(coordRoot, selfInstanceId, selfSessionIdFallb
         started_at: p.started_at ?? null,
         files_touched: Array.from(p.files_touched ?? []).sort(),
         platform: p.platform ?? null,
-        activity: p.activity ?? "unknown",
         task_state: p.task_state ?? "active",
         task_state_reason: p.task_state_reason ?? null,
     }))
         .sort((a, b) => (a.instance_id ?? "").localeCompare(b.instance_id ?? ""));
-    // Remote basis: machine + per-agent identity/task/files (published_at is
-    // excluded — a keepalive re-publish alone shouldn't re-emit the table).
+    // Remote basis: machine + per-agent identity, lifecycle, and files
+    // (published_at, activity, and task are excluded for the same reason).
     const remoteBasis = remote.map((m) => ({
         machine: m.machine,
         agents: m.agents.map((a) => ({
             instance_id: a.instance_id,
             name: a.name ?? null,
-            task: a.task ?? null,
-            activity: a.activity,
             task_state: a.task_state,
             task_state_reason: a.task_state_reason ?? null,
             files_touched: Array.from(a.files_touched ?? []).sort(),
         })),
     }));
-    const newHash = sha256Hex16(JSON.stringify({ local: basis, remote: remoteBasis }));
-    const hashFile = join(coordRoot, ".harnery", `.last-peer-hash.${selfInstanceId}`);
-    const oldHash = safeRead(hashFile);
-    if (oldHash && oldHash === newHash)
-        return "";
-    // Render peer table via the same formatter used at SessionStart.
-    const local = formatPeerTable(peers, mySessionId, forkRelationLabels(coordRoot, selfInstanceId, new Set(peers.map((p) => p.instance_id ?? ""))));
-    const remoteTable = formatRemoteTable(remote);
+    const hash = sha256Hex16(JSON.stringify({ local: basis, remote: remoteBasis }));
+    const nowSec = Math.floor(nowMs / 1000);
+    const local = formatPeerTable(live, stale, mySessionId, nowSec, input.relations);
+    const remoteTable = formatRemoteTable(remote, nowSec);
     const table = [local, remoteTable].filter(Boolean).join("\n\n");
-    if (!table)
-        return "";
-    // Persist hash atomically (temp + rename, same convention as other coord writes).
-    writeHashFile(hashFile, newHash);
-    return table;
+    return { hash, table };
 }
 /** readRemoteMachines with a local failure guard (rendering must never throw). */
 function readRemoteMachinesSafe(coordRoot) {
@@ -353,10 +410,9 @@ function readRemoteMachinesSafe(coordRoot) {
     }
 }
 /** Render sessions on other machines (presence transport) as a subtable. */
-function formatRemoteTable(remote) {
+function formatRemoteTable(remote, nowSec) {
     if (remote.length === 0)
         return "";
-    const nowSec = Math.floor(Date.now() / 1000);
     const lines = [];
     for (const m of remote) {
         for (const a of m.agents.slice(0, 10)) {
@@ -451,16 +507,11 @@ function writeHashFile(path, value) {
         /* swallow */
     }
 }
-/* The peer-table formatter is a near-duplicate of session-context.ts's, but
- * intentionally co-located here so the prompt-context renderer is self-contained
- * (no cross-file imports of formatting internals). If both renderers diverge,
- * pull the shared bits into a small util module. */
-function formatPeerTable(peers, mySessionId, relations = new Map()) {
+function formatPeerTable(peers, stalePeers, mySessionId, nowSec, relations = new Map()) {
     if (peers.length === 0)
         return "";
-    const nowSec = Math.floor(Date.now() / 1000);
     const fold = {};
-    for (const p of peers) {
+    for (const p of [...peers, ...stalePeers]) {
         const kind = p.kind ?? "unknown";
         if (kind === "transient" && p.session_id) {
             fold[p.session_id] = (fold[p.session_id] ?? []).concat(p.files_touched ?? []);
@@ -474,28 +525,52 @@ function formatPeerTable(peers, mySessionId, relations = new Map()) {
         const relation = relations.get(p.instance_id ?? "");
         return { ...p, display_files: display, ...(relation ? { relation } : {}) };
     });
+    assignUniqueLabels(rows);
+    const staleRows = stalePeers.filter((p) => (p.kind ?? "unknown") !== "transient");
     // Related sessions sort first so a fork parent never hides in "+N more".
     const blocking = rows
         .filter((p) => p.session_id !== mySessionId)
         .sort((a, b) => Number(!!b.relation) - Number(!!a.relation) || byStartedAt(a, b));
     const group = rows.filter((p) => p.session_id === mySessionId).sort(byStartedAt);
+    const staleBlocking = staleRows.filter((p) => p.session_id !== mySessionId).length;
+    const staleGroup = staleRows.length - staleBlocking;
     const out = [];
-    const blk = renderSubtable(blocking, "Other agent groups active (their files block you):", nowSec);
+    const blk = renderSubtable(blocking, staleBlocking, "Other agent groups active (their files block you):", nowSec);
     if (blk)
         out.push(blk);
-    const grp = renderSubtable(group, "Your group (subagents / parent / siblings; no mutual block):", nowSec);
+    const grp = renderSubtable(group, staleGroup, "Your group (subagents / parent / siblings; no mutual block):", nowSec);
     if (grp)
         out.push(grp);
     return out.join("\n\n");
 }
+/**
+ * One full, distinct label per row. An unnamed session shows its whole
+ * instance id (an 8-character prefix collides for time-ordered ids), and a
+ * name two live rows share carries its instance id so they read as two.
+ */
+function assignUniqueLabels(rows) {
+    const base = (r) => r.name ?? r.instance_id ?? "unknown";
+    const counts = new Map();
+    for (const r of rows)
+        counts.set(base(r), (counts.get(base(r)) ?? 0) + 1);
+    for (const r of rows) {
+        const label = base(r);
+        r.label =
+            (counts.get(label) ?? 0) > 1 && r.name && r.instance_id
+                ? `${label} (${r.instance_id})`
+                : label;
+    }
+}
 function byStartedAt(a, b) {
     return (a.started_at ?? "").localeCompare(b.started_at ?? "");
 }
-function renderSubtable(rows, header, nowSec) {
+function renderSubtable(rows, staleCount, header, nowSec) {
     if (rows.length === 0)
         return "";
     const first = rows.slice(0, 10).map((r) => formatRow(r, nowSec));
-    const overflow = rows.length > 10 ? `\n  +${rows.length - 10} more` : "";
+    const more = Math.max(0, rows.length - 10) + staleCount;
+    const staleNote = staleCount > 0 ? ` (${staleCount} with no recent heartbeat)` : "";
+    const overflow = more > 0 ? `\n  +${more} more${staleNote}` : "";
     return `${header}\n${first.join("\n")}${overflow}`;
 }
 function formatRow(r, nowSec) {
@@ -506,9 +581,8 @@ function formatRow(r, nowSec) {
     const startedSec = parseIsoSec(r.started_at) ?? parseIsoSec(r.last_heartbeat);
     const ageFrom = startedSec === null ? "age unknown" : fmtAge(nowSec - startedSec);
     const filesPart = fmtFiles(r.display_files);
-    // Prefer a short instance_id over a bare "unknown" so an incomplete row is
-    // still identifiable.
-    const label = r.name ?? (r.instance_id ? r.instance_id.slice(0, 8) : "unknown");
+    // An unnamed row shows its full instance id; a prefix can collide.
+    const label = r.label ?? r.name ?? r.instance_id ?? "unknown";
     const relation = r.relation ? ` [${r.relation}]` : "";
     return `  - agent-${label}${relation}${taskPart}   (${statePart}, ${ageFrom}, ${filesPart})`;
 }

package/dist/core/agents/rules/claim-conflict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAWH,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgBlD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CA4GjF"}
+{"version":3,"file":"claim-conflict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/claim-conflict.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAgBlD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,OAAO,CAAC;IACd,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,aAAa,CAmHjF"}

package/dist/core/agents/rules/claim-conflict.js

@@ -17,7 +17,9 @@ import { spawnSync } from "node:child_process";
 import { existsSync } from "node:fs";
 import { join } from "node:path";
 import { adapterFromPlatform as sharedAdapterFromPlatform } from "../../adapter.js";
-import { recordLiveClaimChangeV3 } from "../live-authority-v3.js";
+import { resolveBinName } from "../../config.js";
+import { writeProducerDiagnosticV3 } from "../../events/v3/producers/intake.js";
+import { LiveCoordinationAuthorityV3Error, recordLiveClaimChangeV3 } from "../live-authority-v3.js";
 import { readLiveCoordinationRows } from "../state/live-coordination-view.js";
 const FRESHNESS_SECS = 600;
 /**
@@ -47,8 +49,9 @@ export function evaluateClaim(coordRoot, req) {
         // prune the claim from their heartbeat and allow the edit. Skips when the
         // file doesn't exist (intent-to-create claim); that surface IS load-bearing.
         if (isFileCommittedClean(coordRoot, req.path)) {
-            if (!releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req)) {
-                return authorityUnavailable(req.path, "release the stale claim on");
+            const refused = releaseClaimThroughLedger(coordRoot, conflict.instance_id, req.path, req);
+            if (refused) {
+                return authorityUnavailable(coordRoot, req, req.path, "release the stale claim on", refused);
             }
             // Fall through to ordering check + allow.
         }
@@ -109,8 +112,9 @@ export function evaluateClaim(coordRoot, req) {
             // Every blocker is a finished (committed-clean) edit: prune them so they
             // stop constraining future acquisitions, then fall through to allow.
             for (const p of blockers) {
-                if (!releaseClaimThroughLedger(coordRoot, req.instance_id, p, req)) {
-                    return authorityUnavailable(p, "release the completed claim on");
+                const refused = releaseClaimThroughLedger(coordRoot, req.instance_id, p, req);
+                if (refused) {
+                    return authorityUnavailable(coordRoot, req, p, "release the completed claim on", refused);
                 }
             }
         }
@@ -118,9 +122,9 @@ export function evaluateClaim(coordRoot, req) {
     // Acquire the claim: atomic check-and-set. Adds req.path to my
     // files_touched if not already present.
     if (req.mode !== "read") {
-        if (!acquireClaimThroughLedger(coordRoot, req)) {
-            return authorityUnavailable(req.path, "acquire");
-        }
+        const refused = acquireClaimThroughLedger(coordRoot, req);
+        if (refused)
+            return authorityUnavailable(coordRoot, req, req.path, "acquire", refused);
     }
     return { allow: true, exit_code: 0, rule: "claim.pass" };
 }
@@ -205,6 +209,7 @@ function isFileCommittedClean(coordRoot, relPath) {
         return false;
     }
 }
+/** Returns null when the ledger recorded the claim, else the refusal reason. */
 function acquireClaimThroughLedger(coordRoot, req) {
     const owner = readPeers(coordRoot).find((peer) => peer.instance_id === req.instance_id);
     try {
@@ -217,10 +222,10 @@ function acquireClaimThroughLedger(coordRoot, req) {
             path: req.path,
             access: "write",
         });
-        return true;
+        return null;
     }
-    catch {
-        return false;
+    catch (error) {
+        return refusalReason(error);
     }
 }
 function releaseClaimThroughLedger(coordRoot, subjectInstanceId, relPath, actor) {
@@ -236,17 +241,32 @@ function releaseClaimThroughLedger(coordRoot, subjectInstanceId, relPath, actor)
             path: relPath,
             access: "write",
         });
-        return true;
+        return null;
     }
-    catch {
-        return false;
+    catch (error) {
+        return refusalReason(error);
     }
 }
-function authorityUnavailable(path, operation) {
+function refusalReason(error) {
+    if (error instanceof LiveCoordinationAuthorityV3Error)
+        return error.reason;
+    return error instanceof Error ? error.message : String(error);
+}
+function authorityUnavailable(coordRoot, req, path, operation, refusal) {
+    // The ledger's own reason is the only evidence of why a healthy-looking
+    // session cannot claim; a generic message sent agents to diagnose the wrong
+    // layer, so keep the reason in the verdict and in a durable diagnostic.
+    writeProducerDiagnosticV3(coordRoot, "claim_authority_refused", {
+        instance_id: req.instance_id,
+        operation,
+        reason: refusal,
+    });
     return {
         allow: false,
         exit_code: 2,
         rule: "claim.authority_unavailable",
-        reason: `Cannot safely ${operation} ${path}; V3 authority is unavailable.`,
+        reason: `Cannot safely ${operation} ${path}; the coordination ledger refused the claim ` +
+            `(${refusal}). Run \`${resolveBinName(coordRoot)} agents health\` and retry; if health ` +
+            "is safe, the refusal reason above names the session state that blocked it.",
     };
 }

package/dist/core/agents/rules/stop-hook.d.ts

@@ -26,6 +26,12 @@ export interface StopHookRequest {
     session_name_observation_unavailable?: boolean;
     bypass?: boolean;
     workflow_child?: boolean;
+    /**
+     * Claude Code moved this session's foreground command into the background
+     * and has not yet reported it finished. Finalization cannot pass until it
+     * does, so status and reply-box demands wait for the notification turn.
+     */
+    pending_background_handoff?: boolean;
 }
 export declare const STOP_REMEDIATION_MARKER = "[harnery:stop-remediation";
 export declare function evaluateStopHook(coordRoot: string, req: StopHookRequest): VerdictResult;

package/dist/core/agents/rules/stop-hook.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"stop-hook.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/stop-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAM3D,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iFAAiF;IACjF,oCAAoC,CAAC,EAAE,OAAO,CAAC;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAInE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,aAAa,CA6BvF;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,aAAa,CAiIf"}
+{"version":3,"file":"stop-hook.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/stop-hook.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,6BAA6B,CAAC;AAM3D,YAAY,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,cAAc,CAAC;AAElD,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IACnD,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,yBAAyB,CAAC,EAAE,OAAO,CAAC;IACpC,iFAAiF;IACjF,oCAAoC,CAAC,EAAE,OAAO,CAAC;IAC/C,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;OAIG;IACH,0BAA0B,CAAC,EAAE,OAAO,CAAC;CACtC;AAED,eAAO,MAAM,uBAAuB,8BAA8B,CAAC;AAInE,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,EAAE,eAAe,GAAG,aAAa,CA6BvF;AAED,oFAAoF;AACpF,wBAAgB,wBAAwB,CACtC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,eAAe,EACpB,MAAM,EAAE,SAAS,OAAO,EAAE,GACzB,aAAa,CA2If"}

package/dist/core/agents/rules/stop-hook.js

@@ -101,6 +101,8 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
     // Pure prose turns keep the human-visible acknowledgement but do not require
     // task or final-status mutations. This preserves the pre-V3 policy exactly.
     if (!usedTool) {
+        if (!ackPresent && req.pending_background_handoff)
+            return backgroundHandoffDeferred();
         if (!ackPresent)
             return withCycleAnchor(ackBlock(), cycleAnchor);
         return {
@@ -133,11 +135,28 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
             pending.push(sessionNameBlock(coordRoot, req.instance_id));
         }
     }
-    const blocked = mergeStopBlocks(pending);
+    // A status check run now would refuse on the in-flight commit and a box
+    // cannot be issued without it, so bouncing only loops until the task ends.
+    // Task and naming evidence do not depend on the task and stay enforced.
+    const enforced = req.pending_background_handoff
+        ? pending.filter((block) => block.rule !== "stop-hook.rule_1_3" && block.rule !== "stop-hook.rule_2_3")
+        : pending;
+    const blocked = mergeStopBlocks(enforced);
     if (blocked)
         return withCycleAnchor(blocked, cycleAnchor);
+    if (enforced.length < pending.length)
+        return backgroundHandoffDeferred();
     return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
+function backgroundHandoffDeferred() {
+    return {
+        allow: true,
+        exit_code: 0,
+        rule: "stop-hook.background_handoff_deferred",
+        reason: "a command Claude Code moved to the background is still running; status and reply-box " +
+            "evidence are required on the turn its completion notification starts",
+    };
+}
 function unconditionalVerdict(req) {
     if (req.bypass) {
         return {

package/dist/core/agents/state/proc-start.d.ts

@@ -31,7 +31,7 @@
  *    two callers reading the same live process disagree.
  */
 /** Which probe answers "when did this process start?" on this machine. */
-export type StartTokenProbe = "procfs" | "ps";
+export type StartTokenProbe = "procfs" | "ps" | "windows";
 /**
  * Which probe this machine uses, decided once.
  *
@@ -68,6 +68,8 @@ export declare function psStartToken(pid: number, run?: (pid: number) => {
  * will not say.
  */
 export declare function processStartToken(pid: number): string | null;
+/** Windows process creation time in invariant UTC ticks, independent of locale. */
+export declare function windowsStartToken(pid: number): string | null;
 export type ProcessGenerationVerdict = "same" | "different" | "unknown";
 type ReadProcessStartToken = (pid: number) => string | null;
 /**

package/dist/core/agents/state/proc-start.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"proc-start.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/proc-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,IAAI,CAAC;AAc9C;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAOjD;AAyBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAiB,GAC7E,MAAM,GAAG,IAAI,CAUf;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAG5D;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAExE,KAAK,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,GAAE,qBAAyC,GACnD,wBAAwB,CAuB1B;AAOD,MAAM,WAAW,mCAAmC;IAClD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAC/B,YAAY,GAAE,mCAAwC,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,CAUtD"}
+{"version":3,"file":"proc-start.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/proc-start.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AAMH,0EAA0E;AAC1E,MAAM,MAAM,eAAe,GAAG,QAAQ,GAAG,IAAI,GAAG,SAAS,CAAC;AAc1D;;;;;;GAMG;AACH,wBAAgB,eAAe,IAAI,eAAe,CAQjD;AAyBD,uDAAuD;AACvD,wBAAgB,qBAAqB,IAAI,IAAI,CAG5C;AAED;;;;;;;;GAQG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAc3D;AAED;;;;;;GAMG;AACH,wBAAgB,YAAY,CAC1B,GAAG,EAAE,MAAM,EACX,GAAG,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK;IAAE,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAiB,GAC7E,MAAM,GAAG,IAAI,CAUf;AAWD;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAK5D;AAED,mFAAmF;AACnF,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAkB5D;AAED,MAAM,MAAM,wBAAwB,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,CAAC;AAExE,KAAK,qBAAqB,GAAG,CAAC,GAAG,EAAE,MAAM,KAAK,MAAM,GAAG,IAAI,CAAC;AAE5D;;;;;;;;;;;;GAYG;AACH,wBAAgB,uBAAuB,CACrC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,SAAS,GAAE,qBAAyC,GACnD,wBAAwB,CAuB1B;AAOD,MAAM,WAAW,mCAAmC;IAClD,SAAS,CAAC,EAAE,qBAAqB,CAAC;IAClC,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,KAAK,OAAO,CAAC;CAClE;AAED;;;;;GAKG;AACH,wBAAgB,sBAAsB,CACpC,GAAG,EAAE,MAAM,EACX,aAAa,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACxC,MAAM,EAAE,MAAM,CAAC,OAAO,GAAG,MAAM,EAC/B,YAAY,GAAE,mCAAwC,GACrD;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,OAAO,EAAE,wBAAwB,CAAA;CAAE,CAUtD"}