harnery 0.46.1 → 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/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"}

package/dist/core/agents/state/proc-start.js

@@ -52,10 +52,11 @@ let cachedBootId;
  */
 export function startTokenProbe() {
     const override = coordEnv("PID_PROBE");
-    if (override === "procfs" || override === "ps")
+    if (override === "procfs" || override === "ps" || override === "windows")
         return override;
     if (cachedProbe === undefined) {
-        cachedProbe = existsSync("/proc/self/stat") ? "procfs" : "ps";
+        cachedProbe =
+            process.platform === "win32" ? "windows" : existsSync("/proc/self/stat") ? "procfs" : "ps";
     }
     return cachedProbe;
 }
@@ -147,9 +148,30 @@ function defaultPsRun(pid) {
  * will not say.
  */
 export function processStartToken(pid) {
-    if (!Number.isFinite(pid) || pid <= 0)
+    if (!Number.isSafeInteger(pid) || pid <= 0)
         return null;
-    return startTokenProbe() === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
+    const probe = startTokenProbe();
+    if (probe === "windows")
+        return windowsStartToken(pid);
+    return probe === "procfs" ? procfsStartToken(pid) : psStartToken(pid);
+}
+/** Windows process creation time in invariant UTC ticks, independent of locale. */
+export function windowsStartToken(pid) {
+    if (!Number.isSafeInteger(pid) || pid <= 0)
+        return null;
+    try {
+        const out = spawnSync("powershell.exe", [
+            "-NoProfile",
+            "-NonInteractive",
+            "-Command",
+            `try { (Get-Process -Id ${pid} -ErrorAction Stop).StartTime.ToUniversalTime().Ticks } catch { exit 1 }`,
+        ], { encoding: "utf8", timeout: 4_000, windowsHide: true });
+        const ticks = out.stdout?.trim();
+        return out.status === 0 && ticks && /^\d+$/.test(ticks) ? `w${ticks}` : null;
+    }
+    catch {
+        return null;
+    }
 }
 /**
  * Does `pid` still name the run that wrote `recordedToken`?

package/dist/core/autoupdate/engine.d.ts

@@ -0,0 +1,97 @@
+/**
+ * Project self-update engine (ADR 0229).
+ *
+ * `autoUpdateTick` is the hot path every prompt, session start, and host CLI
+ * command calls: one stat of the throttle stamp when nothing is due. When the
+ * stamp is stale it claims the stamp and launches a detached
+ * `<harn> autoupdate run --background`, which decides with `checkForUpdate`
+ * and, only when needed, runs the host's configured steps under a lock.
+ */
+import { type GitRunner } from "./git.js";
+import { type LockInspection, type LockOwner } from "./state.js";
+import { type AutoUpdateConfig, type AutoUpdateNotice, type AutoUpdateState, type CheckDecision, type RunOutcome, type RunRecord, type TickResult } from "./types.js";
+/** Set on the detached runner and every step so nested CLI calls never tick. */
+export declare const AUTOUPDATE_CHILD_ENV = "HARNERY_AUTOUPDATE_CHILD";
+export interface StepRunResult {
+    exitCode: number | null;
+    timedOut: boolean;
+    output: string;
+    ms: number;
+}
+export type StepRunner = (argv: string[], opts: {
+    cwd: string;
+    timeoutMs: number;
+    env: NodeJS.ProcessEnv;
+    onChunk?: (chunk: string, stream: "stdout" | "stderr") => void;
+}) => Promise<StepRunResult>;
+export interface AutoUpdateDeps {
+    now?: () => number;
+    env?: NodeJS.ProcessEnv;
+    readConfig?: (coordRoot: string) => AutoUpdateConfig | null;
+    git?: GitRunner;
+    /** Launch the detached runner (tick). */
+    spawnRunner?: (coordRoot: string) => void;
+    runStep?: StepRunner;
+    /** Expired-artifact cleanup; best effort. */
+    runCleanup?: (coordRoot: string) => void;
+    binName?: string;
+}
+/** The CLI entry the detached runner executes with `process.execPath`. */
+export declare function harnCliEntry(): string;
+/** Set the throttle stamp's mtime (creating it), which is all the tick reads. */
+export declare function setStamp(coordRoot: string, atMs: number): void;
+/** Keep the log bounded: past 256 KB, keep only its last 64 KB. */
+export declare function rotateLog(path: string): void;
+export declare function isInstructionPath(path: string): boolean;
+export declare function isHookConfigPath(path: string): boolean;
+/** `harnery-notice:` lines in step output. */
+export declare function parseNoticeLines(output: string): string[];
+/**
+ * Activity hook. Never throws. When throttled it reads the config and stats
+ * one file; it runs no Git and parses no state.
+ */
+export declare function autoUpdateTick(coordRoot: string, deps?: AutoUpdateDeps): TickResult;
+export declare function checkForUpdate(coordRoot: string, cfg: AutoUpdateConfig, state: AutoUpdateState, deps?: AutoUpdateDeps & {
+    force?: boolean;
+}): CheckDecision;
+/**
+ * Resolve a step's argv for the current platform. On Windows a bare command
+ * name such as `bun` or `git` is looked up on PATH with PATHEXT, because
+ * spawning without a shell does not try `.cmd` shims; a `.cmd` or `.bat`
+ * match runs through `cmd.exe`. Elsewhere the argv is used as is.
+ */
+export declare function resolveStepCommand(cmd: string, args: string[], env: NodeJS.ProcessEnv, platform?: NodeJS.Platform, exists?: (path: string) => boolean): {
+    cmd: string;
+    args: string[];
+    verbatim: boolean;
+};
+export declare const defaultStepRunner: StepRunner;
+export interface RunAutoUpdateOptions {
+    force?: boolean;
+    /** Detached runner: output goes to the log only. */
+    background?: boolean;
+    /** Foreground streaming of step output (in addition to the log). */
+    onOutput?: (chunk: string, stream: "stdout" | "stderr") => void;
+    deps?: AutoUpdateDeps;
+}
+export interface RunAutoUpdateResult {
+    outcome: RunOutcome;
+    decision: CheckDecision | null;
+    record: RunRecord | null;
+    /** Notices recorded by this run. */
+    notices: AutoUpdateNotice[];
+    /** Holder of the lock when `skipped-locked`. */
+    lockOwner?: LockOwner | null;
+}
+export declare function runAutoUpdate(coordRootRaw: string, opts?: RunAutoUpdateOptions): Promise<RunAutoUpdateResult>;
+export interface AutoUpdateStatus {
+    config: AutoUpdateConfig | null;
+    state: AutoUpdateState;
+    /** Milliseconds since the throttle stamp (negative while backing off); null when never checked. */
+    stampAge: number | null;
+    /** Milliseconds until a tick would launch a check; 0 when due. */
+    nextCheckMs: number | null;
+    locked: LockInspection;
+}
+export declare function autoUpdateStatus(coordRootRaw: string, deps?: AutoUpdateDeps): AutoUpdateStatus;
+//# sourceMappingURL=engine.d.ts.map

package/dist/core/autoupdate/engine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../../../src/core/autoupdate/engine.ts"],"names":[],"mappings":"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"}