harnery 0.34.1 → 0.36.0

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

@@ -62,13 +62,21 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
     const ownerEvents = events.filter((event) => event.scope.instance_id === owner &&
         "generation_id" in event.scope &&
         event.scope.generation_id === generationId);
+    const fallbackStartMs = Math.max(0, endMs - 5 * 60 * 1000);
+    const claudeContinuation = req.adapter === "claude-code" && req.stop_hook_active === true;
+    const resolvedStart = resolveTurnStart(ownerEvents, endMs, claudeContinuation);
+    const resolvedStartMs = eventTimeMs(resolvedStart);
     const startMs = req.turn_window?.start_ms ??
-        resolveTurnStartMs(ownerEvents, endMs, Math.max(0, endMs - 5 * 60 * 1000));
+        (Number.isFinite(resolvedStartMs) ? resolvedStartMs : fallbackStartMs);
     const inTurn = ownerEvents.filter((event) => {
         const time = eventTimeMs(event);
         return Number.isFinite(time) && time >= startMs && time <= endMs;
     });
-    const usedTool = inTurn.some((event) => event.event_type === "tool.requested");
+    const policyEvents = claudeContinuation && resolvedStart
+        ? originalTurnEvents(ownerEvents, resolvedStart, endMs)
+        : inTurn;
+    const usedTool = policyEvents.some((event) => event.event_type === "tool.requested");
+    const cycleAnchor = remediationCycleAnchor(resolvedStart, startMs);
     const statusEvents = inTurn.filter((event) => event.event_type === "coord.status_observed" && event.payload.subject_instance_id === owner);
     const statusChecked = statusEvents.length > 0;
     const requiredStatusChecked = agentsRequireGitFinalization(coordRoot)
@@ -78,17 +86,27 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
     const taskSet = inTurn.some((event) => event.event_type === "coord.task_changed" && event.payload.subject_instance_id === owner);
     const turnTerminals = inTurn.filter((event) => event.event_type === "turn.completed");
     const latestTerminal = turnTerminals.at(-1);
-    const latestBox = observedBoolean(latestTerminal?.payload.ritual?.status_box_present);
-    if (req.adapter !== "cursor" && latestBox === undefined) {
-        return evidenceUnavailable("turn.completed has no observed V3 status-box result; Stop remains fail-open");
+    const latestBox = observedBoolean(latestTerminal?.payload.ritual?.status_box_present_strict);
+    const strictBoxObservations = turnTerminals
+        .map((event) => observedBoolean(event.payload.ritual?.status_box_present_strict))
+        .filter((value) => value !== undefined);
+    const currentStrictBox = claudeContinuation ? req.status_box_present_strict : undefined;
+    if (req.adapter !== "cursor" && 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 : latestBox === true;
-    const ackBlock = req.adapter === "cursor" ? () => rule13Block(coordRoot) : () => rule23Block(coordRoot);
+    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);
     // 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)
-            return ackBlock();
+            return withCycleAnchor(ackBlock(), cycleAnchor);
         return {
             allow: true,
             exit_code: 0,
@@ -96,12 +114,17 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
             reason: "no tool calls this turn; task and final-status mutations were not required",
         };
     }
+    // Collect EVERY missing signal before returning. Reporting them one at a
+    // time made each additional missing signal cost a whole continuation, and
+    // every continuation forks a fresh hook process: on a busy multi-agent host
+    // the ritual's own enforcement became part of the hook load it polices.
+    const pending = [];
     if (!requiredStatusChecked)
-        return rule13Block(coordRoot);
+        pending.push(rule13Block(coordRoot, req.session_id));
     if (!ackPresent)
-        return ackBlock();
+        pending.push(ackBlock());
     if (!taskSet)
-        return rule33Block(coordRoot);
+        pending.push(rule33Block(coordRoot, req.session_id));
     // Claude Code can prove session-name presentation from assistant-only text.
     // Cursor cannot expose that text and Codex returned observe-only above.
     if (req.adapter !== "cursor") {
@@ -111,9 +134,12 @@ export function evaluateStopHookV3Events(coordRoot, req, events) {
         if (naming.some(({ required }) => required) &&
             !naming.some(({ present }) => present) &&
             !sessionNameSeenStamped(coordRoot, req.instance_id)) {
-            return sessionNameBlock(coordRoot, req.instance_id);
+            pending.push(sessionNameBlock(coordRoot, req.instance_id));
         }
     }
+    const blocked = mergeStopBlocks(pending);
+    if (blocked)
+        return withCycleAnchor(blocked, cycleAnchor);
     return { allow: true, exit_code: 0, rule: "stop-hook.pass" };
 }
 function unconditionalVerdict(req) {
@@ -143,22 +169,48 @@ function unconditionalVerdict(req) {
     }
     return undefined;
 }
-function resolveTurnStartMs(ownerEvents, nowMs, fallbackMs) {
+function resolveTurnStart(ownerEvents, nowMs, claudeContinuation) {
     const turns = ownerEvents.filter((event) => event.event_type === "turn.started" && eventTimeMs(event) <= nowMs);
     if (turns.length === 0)
-        return fallbackMs;
+        return undefined;
     let index = turns.length - 1;
     let hops = 0;
     while (index > 0 && hops < MAX_REMEDIATION_WALK_BACK) {
         const turn = turns[index];
-        if (!turn?.payload.stop_remediation)
+        const continuesCycle = claudeContinuation
+            ? turn?.provenance.source_event === "claude-code.recovery" &&
+                turn.provenance.attestation === "derived"
+            : turn?.payload.stop_remediation === true;
+        if (!continuesCycle)
             break;
         index -= 1;
         hops += 1;
     }
-    return eventTimeMs(turns[index]);
+    return turns[index];
+}
+function originalTurnEvents(ownerEvents, turnStart, endMs) {
+    if (!turnStart)
+        return [];
+    const startMs = eventTimeMs(turnStart);
+    const terminal = ownerEvents.find((event) => event.event_type === "turn.completed" && eventTimeMs(event) >= startMs);
+    const policyEndMs = terminal ? eventTimeMs(terminal) : endMs;
+    return ownerEvents.filter((event) => {
+        const time = eventTimeMs(event);
+        return time >= startMs && time <= policyEndMs;
+    });
+}
+function remediationCycleAnchor(turnStart, startMs) {
+    if (turnStart && "turn_id" in turnStart.scope && turnStart.scope.turn_id) {
+        return turnStart.scope.turn_id;
+    }
+    return new Date(startMs).toISOString();
+}
+function withCycleAnchor(verdict, anchor) {
+    return { ...verdict, remediation_cycle_anchor: anchor };
 }
 function eventTimeMs(event) {
+    if (!event)
+        return Number.NaN;
     return Date.parse(event.time.observed_at);
 }
 function observedBoolean(value) {
@@ -192,7 +244,48 @@ function evidenceUnavailable(reason) {
         reason,
     };
 }
-function rule13Block(coordRoot) {
+/**
+ * Remediation commands carry `--session-id` when the session id is known: the
+ * remediating tool call may not descend from a pid-map-registered anchor
+ * (headless children, Cursor shells), and a ppid-walk that resolves to a
+ * DIFFERENT owner records evidence this verdict will never see — the block
+ * then repeats forever while the agent complies every time.
+ */
+function sessionIdSuffix(sessionId) {
+    return sessionId ? ` --session-id ${sessionId}` : "";
+}
+/**
+ * Fold every failing end-of-turn signal into ONE verdict.
+ *
+ * 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.
+ */
+function mergeStopBlocks(blocks) {
+    let primary;
+    const seen = new Set();
+    const reasons = [];
+    for (const block of blocks) {
+        if (seen.has(block.rule))
+            continue;
+        seen.add(block.rule);
+        if (!primary)
+            primary = block;
+        if (block.reason)
+            reasons.push(block.reason);
+    }
+    if (!primary)
+        return undefined;
+    if (reasons.length < 2)
+        return primary;
+    const numbered = reasons.map((reason, index) => `${index + 1}. ${reason}`).join("\n");
+    return {
+        ...primary,
+        reason: `End-of-turn ritual: ${reasons.length} signals are missing from this turn. Repair ALL of them in this continuation, then stop.\n${numbered}`,
+    };
+}
+function rule13Block(coordRoot, sessionId) {
     const missingEvidence = agentsRequireGitFinalization(coordRoot)
         ? "no end_turn_checked coord.status_observed event found in this turn"
         : "no coord.status_observed event found in this turn";
@@ -200,15 +293,15 @@ function rule13Block(coordRoot) {
         allow: false,
         exit_code: 2,
         rule: "stop-hook.rule_1_3",
-        reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}\` as your last tool call.`,
+        reason: `End-of-turn rule (1/3): ${missingEvidence}; run \`${endOfTurnStatusCommand(coordRoot)}${sessionIdSuffix(sessionId)}\` as your last tool call.`,
     };
 }
-function rule23Block(coordRoot) {
+function rule23Block(coordRoot, sessionId) {
     return {
         allow: false,
         exit_code: 2,
         rule: "stop-hook.rule_2_3",
-        reason: `End-of-turn rule (2/3): turn.completed did not observe the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
+        reason: `End-of-turn rule (2/3): turn.completed did not observe the agent-status box in your reply text. Paste the \`${endOfTurnStatusCommand(coordRoot)}${sessionIdSuffix(sessionId)}\` output verbatim as a fenced code block (the \`┌─ agent-\` prefix is the detection signal).`,
     };
 }
 /**
@@ -252,11 +345,11 @@ function sessionNameBlock(coordRoot, instanceId) {
         reason: `Session-naming rule: V3 observed that the current session name was required but absent. ${instruction}`,
     };
 }
-function rule33Block(coordRoot) {
+function rule33Block(coordRoot, sessionId) {
     return {
         allow: false,
         exit_code: 2,
         rule: "stop-hook.rule_3_3",
-        reason: `End-of-turn rule (3/3): no coord.task_changed event found in this turn; run \`${resolveBinName(coordRoot)} agents set-task "<short focus>"\` to declare what you're working on. Pass an empty string if the turn was purely conversational.`,
+        reason: `End-of-turn rule (3/3): no coord.task_changed event found in this turn; run \`${resolveBinName(coordRoot)} agents set-task${sessionIdSuffix(sessionId)} "<short focus>"\` to declare what you're working on. Pass an empty string if the turn was purely conversational.`,
     };
 }

package/dist/core/agents/rules/verdict.d.ts

@@ -10,5 +10,6 @@ export type VerdictResult = {
     exit_code: 0 | 2;
     rule: string;
     reason?: string;
+    remediation_cycle_anchor?: string;
 };
 //# sourceMappingURL=verdict.d.ts.map

package/dist/core/agents/rules/verdict.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC"}
+{"version":3,"file":"verdict.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/rules/verdict.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,KAAK,EAAE,OAAO,CAAC;IACf,SAAS,EAAE,CAAC,GAAG,CAAC,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,wBAAwB,CAAC,EAAE,MAAM,CAAC;CACnC,CAAC"}

package/dist/core/agents/session-events.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,yBAAyB,GAAG,mBAAmB,CAAC;AAEnG;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBjE;AAkID;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,IAAI,CAEN;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGxD"}
+{"version":3,"file":"session-events.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-events.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAkBH,mDAAmD;AACnD,MAAM,MAAM,gBAAgB,GAAG,iBAAiB,GAAG,yBAAyB,GAAG,mBAAmB,CAAC;AAEnG;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAG7C;AAED,6EAA6E;AAC7E,wBAAgB,QAAQ,IAAI,MAAM,CAEjC;AAED;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,UAAU,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAiBjE;AAsID;;;GAGG;AACH,wBAAgB,iBAAiB,CAC/B,IAAI,EAAE,gBAAgB,EACtB,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GACnC,IAAI,CAEN;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,SAAO,GAAG,MAAM,CAGxD"}

package/dist/core/agents/session-events.js

@@ -95,6 +95,10 @@ function recordCommandObservation(type, fields) {
             monotonic_ns: process.hrtime.bigint().toString(),
         });
         if (result.state === "generation_unavailable") {
+            const expectedLifecycleReopenGap = result.reason === "turn_not_started" &&
+                hook.session_start_derivation === "approved_lifecycle_reopen";
+            if (expectedLifecycleReopenGap)
+                return;
             writeProducerDiagnosticV3(coordRoot, "command_emit_unjoinable", {
                 type,
                 instance_id: instanceId,

package/dist/core/agents/session-finalization-state-v3.js

@@ -1,6 +1,6 @@
 import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
 import { join, resolve } from "node:path";
-import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/writer.js";
+import { EVENT_V3_LEDGER_RELATIVE_ROOT } from "../events/v3/reader.js";
 export const SESSION_FINALIZATION_REQUEST_FORMAT_V3 = "harnery-v3-session-finalization-request";
 export const SESSION_FINALIZATION_REQUEST_VERSION_V3 = 1;
 export function sessionFinalizationRequestDirectoryV3(coordRoot) {

package/dist/core/agents/session-finalizer-v3.js

@@ -526,7 +526,11 @@ function ensureRequest(coordRoot, record, input) {
     };
     const observation = buildObservationEvent(coordRoot, record, request, input);
     request.observation_event_id = observation.event_id;
-    writeEventV3(coordRoot, observation);
+    const durability = writeEventV3(coordRoot, observation, {
+        expectedGenesisId: input.route.genesis_id,
+    });
+    if (durability.state === "epoch_replaced")
+        return null;
     writeRequest(coordRoot, request, true);
     return request;
 }

package/dist/core/agents/session-name-display.d.ts

@@ -12,6 +12,7 @@ export declare const SESSION_NAME_DISPLAY_NOTE = "Next, before any prose or anot
 export declare function sessionNameDisplayPending(row: SessionNameDisplayState | null | undefined): string | null;
 export declare function sessionNameDisplayBlock(name: string): string;
 export declare function sessionNameDisplayInstruction(name: string): string;
+export declare function sessionNameDisplayRecoveryInstruction(name: string, binName: string): string;
 /**
  * A PostToolUse result should announce the display protocol only when that
  * exact tool call minted or retried the current suggestion. The coordination row keeps

package/dist/core/agents/session-name-display.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-name-display.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-name-display.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,uBAAuB;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,yBAAyB,wHACiF,CAAC;AAExH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC9C,MAAM,GAAG,IAAI,CAIf;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGtF;AAgDD;;;;GAIG;AACH,wBAAgB,uCAAuC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK3F;AAUD;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAmBT"}
+{"version":3,"file":"session-name-display.d.ts","sourceRoot":"","sources":["../../../src/core/agents/session-name-display.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,MAAM,WAAW,uBAAuB;IACtC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,qBAAqB,CAAC,EAAE,MAAM,CAAC;CAChC;AAED,eAAO,MAAM,yBAAyB,wHACiF,CAAC;AAExH,wBAAgB,yBAAyB,CACvC,GAAG,EAAE,uBAAuB,GAAG,IAAI,GAAG,SAAS,GAC9C,MAAM,GAAG,IAAI,CAIf;AAED,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE5D;AAED,wBAAgB,6BAA6B,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASlE;AAED,wBAAgB,qCAAqC,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,CAM3F;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,6BAA6B,CAAC,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGtF;AAgDD;;;;GAIG;AACH,wBAAgB,uCAAuC,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAK3F;AAUD;;;;GAIG;AACH,wBAAgB,+BAA+B,CAC7C,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,OAAO,EAAE,MAAM,GACd,OAAO,CAmBT"}

package/dist/core/agents/session-name-display.js

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

package/dist/core/agents/state/activity-log.d.ts

@@ -15,4 +15,7 @@
  * coord_owner_short). Returns `agent-unknown` when instanceId is null.
  */
 export declare function resolveShortName(coordRoot: string, instanceId: string | null): string;
+/** Build a collision-resistant agent label even when identity onboarding has
+ * not produced a usable display name yet. */
+export declare function agentDisplayName(instanceId: string, name?: string | null): string;
 //# sourceMappingURL=activity-log.d.ts.map

package/dist/core/agents/state/activity-log.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"activity-log.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/activity-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAKrF"}
+{"version":3,"file":"activity-log.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/activity-log.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAIH;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAIrF;AAED;6CAC6C;AAC7C,wBAAgB,gBAAgB,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,MAAM,CAEjF"}

package/dist/core/agents/state/activity-log.js

@@ -19,7 +19,10 @@ export function resolveShortName(coordRoot, instanceId) {
     if (!instanceId)
         return "agent-unknown";
     const row = readLiveCoordinationRow(coordRoot, instanceId);
-    if (row?.name)
-        return `agent-${row.name}`;
-    return `agent-${instanceId.slice(0, 8)}`;
+    return agentDisplayName(instanceId, row?.name);
+}
+/** Build a collision-resistant agent label even when identity onboarding has
+ * not produced a usable display name yet. */
+export function agentDisplayName(instanceId, name) {
+    return `agent-${name?.trim() || instanceId.slice(0, 8) || "unknown"}`;
 }

package/dist/core/agents/state/heartbeat-reader.d.ts

@@ -0,0 +1,46 @@
+/** Read-only access to the generation-bound heartbeat cache. */
+import type { AgentActivity, TaskState } from "./session-state.js";
+export interface Heartbeat {
+    schema_version?: number;
+    instance_id: string;
+    name?: string;
+    kind?: string;
+    agent_id?: string;
+    session_id: string;
+    /** Native adapter session ID retained only in a generation-bound local projection. */
+    native_session_id?: string;
+    subagent_call_id?: string;
+    model?: string;
+    platform?: string;
+    started_at?: string;
+    last_heartbeat: string;
+    files_touched: string[];
+    task?: string;
+    task_updated_at?: string | null;
+    activity?: AgentActivity;
+    activity_updated_at?: string;
+    activity_source?: string;
+    task_state?: TaskState;
+    task_state_updated_at?: string;
+    task_state_reason?: string;
+    /** Session name built on the first non-empty set-task (never rebuilt). */
+    suggested_session_name?: string;
+    /** Stamped once the suggested name is seen in assistant reply text. */
+    session_name_seen_at?: string;
+    /** The specific suggested name proven present by the sighting stamp. */
+    session_name_seen_for?: string;
+    last_status_at?: string;
+    current_turn_id?: string;
+    parent_instance_id?: string;
+    workflow_run_id?: string;
+    workflow_agent_id?: string;
+    /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */
+    v3_instance_id?: `inst_${string}`;
+    v3_generation_id?: `gen_${string}`;
+    v3_projection_event_id?: string;
+    v3_task_state?: "set" | "cleared";
+    [extra: string]: unknown;
+}
+export declare function heartbeatPath(coordRoot: string, instanceId: string): string;
+export declare function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat | null;
+//# sourceMappingURL=heartbeat-reader.d.ts.map

package/dist/core/agents/state/heartbeat-reader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"heartbeat-reader.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-reader.ts"],"names":[],"mappings":"AAAA,gEAAgE;AAIhE,OAAO,KAAK,EAAE,aAAa,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEnE,MAAM,WAAW,SAAS;IACxB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;IACnB,sFAAsF;IACtF,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,cAAc,EAAE,MAAM,CAAC;IACvB,aAAa,EAAE,MAAM,EAAE,CAAC;IACxB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,eAAe,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IAChC,QAAQ,CAAC,EAAE,aAAa,CAAC;IACzB,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,0EAA0E;IAC1E,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,uEAAuE;IACvE,oBAAoB,CAAC,EAAE,MAAM,CAAC;IAC9B,wEAAwE;IACxE,qBAAqB,CAAC,EAAE,MAAM,CAAC;IAC/B,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,uFAAuF;IACvF,cAAc,CAAC,EAAE,QAAQ,MAAM,EAAE,CAAC;IAClC,gBAAgB,CAAC,EAAE,OAAO,MAAM,EAAE,CAAC;IACnC,sBAAsB,CAAC,EAAE,MAAM,CAAC;IAChC,aAAa,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAClC,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAU3E;AAED,wBAAgB,aAAa,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAQrF"}

package/dist/core/agents/state/heartbeat-reader.js

@@ -0,0 +1,25 @@
+/** Read-only access to the generation-bound heartbeat cache. */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, resolve, sep } from "node:path";
+export function heartbeatPath(coordRoot, instanceId) {
+    if (!/^[A-Za-z0-9_-]{1,128}$/.test(instanceId)) {
+        throw new Error("instance_id must be 1-128 ASCII letters, digits, hyphens, or underscores");
+    }
+    const root = resolve(coordRoot, ".harnery", "active");
+    const candidate = resolve(root, `${instanceId}.json`);
+    if (!candidate.startsWith(`${root}${sep}`) || dirname(candidate) !== root) {
+        throw new Error("coordination filename must resolve directly beneath its root");
+    }
+    return candidate;
+}
+export function readHeartbeat(coordRoot, instanceId) {
+    const path = heartbeatPath(coordRoot, instanceId);
+    if (!existsSync(path))
+        return null;
+    try {
+        return JSON.parse(readFileSync(path, "utf8"));
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/agents/state/heartbeat-writer.d.ts

@@ -13,59 +13,20 @@
  * `.harnery/active/<instance_id>.json`; the canonical V3 ledger remains authoritative.
  * (the file IS the heartbeat). No mutations happen elsewhere.
  */
-import type { AgentActivity, TaskState } from "./session-state.js";
-export interface Heartbeat {
-    schema_version?: number;
-    instance_id: string;
-    name?: string;
-    kind?: string;
-    agent_id?: string;
-    session_id: string;
-    /** Native adapter session ID retained only in a generation-bound local projection. */
-    native_session_id?: string;
-    subagent_call_id?: string;
-    model?: string;
-    platform?: string;
-    started_at?: string;
-    last_heartbeat: string;
-    files_touched: string[];
-    task?: string;
-    task_updated_at?: string | null;
-    activity?: AgentActivity;
-    activity_updated_at?: string;
-    activity_source?: string;
-    task_state?: TaskState;
-    task_state_updated_at?: string;
-    task_state_reason?: string;
-    /** Session name built on the first non-empty set-task (never rebuilt). Its
-     * presence is the "this session has been named" signal the prompt-context
-     * nudge and the Stop-hook naming rule key on. */
-    suggested_session_name?: string;
-    /** Stamped by turn.completed once the suggested name is seen in assistant reply
-     * text, ending the per-turn transcript scan. */
-    session_name_seen_at?: string;
-    /** WHICH name that sighting was for. The scan is skipped only while this
-     * matches the current suggested name, so a re-minted name is detectable
-     * again rather than being suppressed by the earlier sighting. */
-    session_name_seen_for?: string;
-    last_status_at?: string;
-    current_turn_id?: string;
-    parent_instance_id?: string;
-    workflow_run_id?: string;
-    workflow_agent_id?: string;
-    /** Disposable-cache bindings that prove a row belongs to the current V3 generation. */
-    v3_instance_id?: `inst_${string}`;
-    v3_generation_id?: `gen_${string}`;
-    v3_projection_event_id?: string;
-    v3_task_state?: "set" | "cleared";
-    [extra: string]: unknown;
-}
-export declare function readHeartbeat(coordRoot: string, instanceId: string): Heartbeat | null;
+import { type Heartbeat } from "./heartbeat-reader.js";
+import type { TaskState } from "./session-state.js";
+export { type Heartbeat, readHeartbeat } from "./heartbeat-reader.js";
 /** Persist operator-facing lifecycle prose in the generation-bound cache only. */
 export declare function setLifecycleCache(coordRoot: string, instanceId: string, state: TaskState, reason?: string, suggestedSessionName?: string): Heartbeat | null;
 export declare function setTask(coordRoot: string, instanceId: string, task: string): Heartbeat | null;
 /** Update the disposable identity cache after a canonical V3 attestation. */
 export declare function setIdentityCache(coordRoot: string, instanceId: string, name: string, agentId: string): Heartbeat | null;
+/** Restore the pool-assigned display name on a generation that was
+ * materialized before the adapter's normal SessionStart naming path ran.
+ * The durable assignment lives in `.name-history`; this only repairs the
+ * disposable generation cache and deliberately leaves durable persona state
+ * (`agent_id`) untouched. */
+export declare function setAssignedNameCache(coordRoot: string, instanceId: string, name: string, kind?: "session" | "subagent" | "transient"): Heartbeat | null;
 /**
  * Build the copy-pasteable session name from the coord identity + the agent's
  * description parts. Pure (no coord-state reads) so it's unit-testable; collapses

package/dist/core/agents/state/heartbeat-writer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"heartbeat-writer.d.ts","sourceRoot":"","sources":["../../../../src/core/agents/state/heartbeat-writer.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAaH,OAAO,EAAE,KAAK,SAAS,EAAgC,MAAM,uBAAuB,CAAC;AACrF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,oBAAoB,CAAC;AAEpD,OAAO,EAAE,KAAK,SAAS,EAAE,aAAa,EAAE,MAAM,uBAAuB,CAAC;AAatE,kFAAkF;AAClF,wBAAgB,iBAAiB,CAC/B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,KAAK,EAAE,SAAS,EAChB,MAAM,CAAC,EAAE,MAAM,EACf,oBAAoB,CAAC,EAAE,MAAM,GAC5B,SAAS,GAAG,IAAI,CAQlB;AAeD,wBAAgB,OAAO,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,CAoB7F;AAED,6EAA6E;AAC7E,wBAAgB,gBAAgB,CAC9B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,GACd,SAAS,GAAG,IAAI,CAOlB;AAED;;;;6BAI6B;AAC7B,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,EACZ,IAAI,GAAE,SAAS,GAAG,UAAU,GAAG,WAAuB,GACrD,SAAS,GAAG,IAAI,CAelB;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,EACjB,gBAAgB,EAAE,MAAM,EAAE,GACzB;IAAE,aAAa,EAAE,MAAM,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAKvD;AAED,2EAA2E;AAC3E,wBAAgB,2BAA2B,CACzC,kBAAkB,EAAE,MAAM,GAAG,SAAS,EACtC,KAAK,EAAE,SAAS,GACf,MAAM,GAAG,IAAI,CAOf;AAED;;;;4EAI4E;AAC5E,wBAAgB,oBAAoB,CAClC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,SAAS,GAAG,IAAI,CAMlB;AAED,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAQlB;AAED,oFAAoF;AACpF,wBAAgB,YAAY,CAC1B,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,IAAI,EAAE,MAAM,GACX,SAAS,GAAG,IAAI,CAWlB;AAED,uEAAuE;AACvE,MAAM,WAAW,eAAe;IAC9B,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,eAAe,CAC7B,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,eAAe,EAAE,CA6BnB;AAED,wBAAgB,sBAAsB,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,OAAO,CASrF;AAED,wBAAgB,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,IAAI,CAiBnF"}

package/dist/core/agents/state/heartbeat-writer.js

@@ -14,16 +14,10 @@
  * (the file IS the heartbeat). No mutations happen elsewhere.
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from "node:fs";
-import { basename, dirname, join } from "node:path";
-import { assertSafeInstanceId, resolveContainedFile } from "../coord-client.js";
-function heartbeatPath(coordRoot, instanceId) {
-    assertSafeInstanceId(instanceId);
-    const safeInstanceId = basename(instanceId);
-    if (safeInstanceId !== instanceId) {
-        throw new Error("instance_id must be a direct-child coordination basename");
-    }
-    return resolveContainedFile(join(coordRoot, ".harnery", "active"), `${safeInstanceId}.json`);
-}
+import { dirname, join } from "node:path";
+import { canonicalClaimPath } from "../claim-path.js";
+import { heartbeatPath, readHeartbeat } from "./heartbeat-reader.js";
+export { readHeartbeat } from "./heartbeat-reader.js";
 function nowIsoSeconds() {
     return new Date().toISOString().replace(/\.\d{3}Z$/, "Z");
 }
@@ -33,17 +27,6 @@ function atomicWrite(path, content) {
     writeFileSync(tmp, content, "utf8");
     renameSync(tmp, path);
 }
-export function readHeartbeat(coordRoot, instanceId) {
-    const path = heartbeatPath(coordRoot, instanceId);
-    if (!existsSync(path))
-        return null;
-    try {
-        return JSON.parse(readFileSync(path, "utf8"));
-    }
-    catch {
-        return null;
-    }
-}
 /** Persist operator-facing lifecycle prose in the generation-bound cache only. */
 export function setLifecycleCache(coordRoot, instanceId, state, reason, suggestedSessionName) {
     return mutate(coordRoot, instanceId, (heartbeat) => ({
@@ -93,6 +76,24 @@ export function setIdentityCache(coordRoot, instanceId, name, agentId) {
     atomicWrite(heartbeatPath(coordRoot, instanceId), JSON.stringify(heartbeat, null, 2));
     return heartbeat;
 }
+/** Restore the pool-assigned display name on a generation that was
+ * materialized before the adapter's normal SessionStart naming path ran.
+ * The durable assignment lives in `.name-history`; this only repairs the
+ * disposable generation cache and deliberately leaves durable persona state
+ * (`agent_id`) untouched. */
+export function setAssignedNameCache(coordRoot, instanceId, name, kind = "session") {
+    return mutate(coordRoot, instanceId, (heartbeat) => {
+        const suggestedSessionName = heartbeat.suggested_session_name?.replace(/^(\[DONE\]\s+)?Agent unknown( - .+)$/, `$1Agent ${name}$2`);
+        return {
+            ...heartbeat,
+            name,
+            kind: heartbeat.kind ?? kind,
+            ...(suggestedSessionName && suggestedSessionName !== heartbeat.suggested_session_name
+                ? { suggested_session_name: suggestedSessionName }
+                : {}),
+        };
+    });
+}
 /**
  * Build the copy-pasteable session name from the coord identity + the agent's
  * description parts. Pure (no coord-state reads) so it's unit-testable; collapses
@@ -128,24 +129,23 @@ export function stampSessionNameSeen(coordRoot, instanceId, name) {
     }));
 }
 export function releaseClaim(coordRoot, instanceId, path) {
-    // files_touched can hold either absolute-under-coordRoot or canonical
-    // monorepo-relative entries; normalize both sides so release matches
-    // regardless of the form the caller passes (the old exact-string filter
-    // silently no-op'd on a form mismatch).
-    const norm = (p) => p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-    const target = norm(path);
+    const target = canonicalClaimPath(coordRoot, path);
     return mutate(coordRoot, instanceId, (hb) => ({
         ...hb,
-        files_touched: (hb.files_touched ?? []).filter((p) => norm(p) !== target),
+        files_touched: (hb.files_touched ?? []).filter((candidate) => canonicalClaimPath(coordRoot, candidate) !== target),
     }));
 }
 /** Materialize one V3 write-claim authority transition into the heartbeat cache. */
 export function acquireClaim(coordRoot, instanceId, path) {
-    const norm = (p) => p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-    const target = norm(path);
+    const target = canonicalClaimPath(coordRoot, path);
     return mutate(coordRoot, instanceId, (hb) => ({
         ...hb,
-        files_touched: [...new Set([...(hb.files_touched ?? []).map(norm), target])].sort(),
+        files_touched: [
+            ...new Set([
+                ...(hb.files_touched ?? []).map((candidate) => canonicalClaimPath(coordRoot, candidate)),
+                target,
+            ]),
+        ].sort(),
     }));
 }
 /**
@@ -172,8 +172,7 @@ export function findGroupClaims(coordRoot, groupId, path) {
     const activeDir = join(coordRoot, ".harnery", "active");
     if (!existsSync(activeDir))
         return hits;
-    const norm = (p) => p.startsWith(`${coordRoot}/`) ? p.slice(coordRoot.length + 1) : p;
-    const target = norm(path);
+    const target = canonicalClaimPath(coordRoot, path);
     for (const f of readdirSync(activeDir)) {
         if (!f.endsWith(".json"))
             continue;
@@ -189,8 +188,9 @@ export function findGroupClaims(coordRoot, groupId, path) {
         if (peerSession !== groupId)
             continue;
         const files = body.files_touched ?? [];
-        if (!files.some((candidate) => norm(candidate) === target))
+        if (!files.some((candidate) => canonicalClaimPath(coordRoot, candidate) === target)) {
             continue;
+        }
         hits.push({
             instance_id: body.instance_id ?? f.replace(/\.json$/, ""),
             session_id: body.session_id,