@dorokuma/herdsman-pi 0.14.0 → 0.14.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dorokuma/herdsman-pi",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "description": "Pi extension bridge for Herdsman agent history.",
   "type": "module",
   "keywords": [

package/src/index.ts

@@ -7,7 +7,6 @@ export { logHerdsmanPi };
 export type { HerdsmanPiLogLevel } from "./logger.js";
 
 import {
-  type AgentContextListItem,
   type AgentEventWireRecord,
   type AgentOrchestratorChanged,
   type AgentOrchestratorWireState,
@@ -105,7 +104,6 @@ type HerdsmanState = {
   launchIdentity: LaunchIdentity | undefined;
   latestContext: AgentWorkspaceContextSnapshot | undefined;
   pendingEvents: AgentEventWireRecord[];
-  pinnedContext: AgentWorkspaceContextSnapshot | undefined;
   presentedEventIds: Set<number>;
   reconnectingFromOn: boolean;
   registrationInFlight: Promise<void> | undefined;
@@ -141,8 +139,12 @@ type HerdsmanState = {
    * delivery from being written off, and it carries three guarantees at once:
    *
    * - never lost: while it is non-empty the settlement drives a continuation
-   *   (bounded by MAX_WAKE_CONTINUATION_ATTEMPTS) so a later run drains the queue
-   *   and carries the update out;
+   *   (bounded by MAX_WAKE_CONTINUATION_ATTEMPTS drives) so a later run drains
+   *   the queue and carries the update out. The bound is a real ceiling, not a
+   *   suggestion: once it is spent the ids are released from here and
+   *   acknowledged (`writeOffStrandedWakeDelivery`), because an update that no
+   *   turn will ever carry out must not keep a run loop — and the daemon's
+   *   redelivery of it — alive forever;
    * - never acknowledged unseen: these ids are excluded from the acknowledgement
    *   path, so the daemon keeps them pending and redelivers them when this
    *   session never consumes them (the only way a delivery Pi itself dropped —
@@ -203,18 +205,24 @@ type HerdsmanState = {
    */
   wakeSkipLogReasons: Map<number, string>;
   /**
-   * Continuation drives already spent on the current unconsumed delivery.
+   * Continuation drives already spent, keyed by event id.
    *
-   * Reset when a delivery is handed over and when the unconsumed set empties, so
-   * the bound applies per delivery instead of accumulating for the session.
-   */
-  wakeContinuationAttempts: number;
-  /**
-   * Event content queued for a busy orchestrator. Injected through the
-   * `context` hook so the running turn sees the update without being
-   * interrupted.
+   * The bound is per event, never per delivery and never per session: an
+   * unrelated event being injected must not hand a stuck one a fresh budget. A
+   * session that keeps receiving new updates used to reset a shared counter at
+   * every injection, so the one id no run ever drained drove on unboundedly and
+   * `MAX_WAKE_CONTINUATION_ATTEMPTS` never fired — the loop that flooded the
+   * orchestrator session with empty turns.
+   *
+   * `MAX_WAKE_CONTINUATION_ATTEMPTS` is therefore a hard ceiling per id: the
+   * drive that reaches it writes that id off
+   * (`writeOffStrandedWakeDelivery`), and an id that still has drives left keeps
+   * both its copy and its count even when a sibling is written off next to it.
+   *
+   * An entry leaves the map with the id itself: acknowledged, dead-lettered,
+   * consumed (its copy reached the transcript), or a role/scope reset.
    */
-  wakeContext: { content: string; eventIds: number[] } | undefined;
+  wakeContinuationDrives: Map<number, number>;
   wakeRequested: boolean;
   wakeRequestedThroughEventId: number;
   wakeTimer: ReturnType<typeof setTimeout> | undefined;
@@ -281,17 +289,31 @@ export const WAKE_BUSY_SPIN_MS = 100;
  */
 export const WAKE_DEFERRED_TIMEOUT_MS = 5_000;
 /**
- * Upper bound on the continuation drives spent on one unconsumed delivery.
+ * Upper bound on the continuation drives spent on **one** unconsumed wake
+ * event id.
+ *
+ * Every drive costs a full agent run, so the budget is deliberately small: three
+ * attempts already cover the drive that follows the settlement which missed Pi's
+ * follow-up queue plus two retries after intervening runs that also ended before
+ * their stop point, and five adds margin for a run that spent its stop point on
+ * a tool call. Beyond that the cause is systemic — the runs keep ending early, so
+ * starting another one could only produce another empty turn — and that id is
+ * written off instead (`writeOffStrandedWakeDelivery`): it leaves
+ * `wakeAwaitingConsumption` and is acknowledged, which stops both the
+ * continuation loop and the daemon's redelivery of the same event.
+ *
+ * The bound is per event id (`wakeContinuationDrives`) and is never reset by a
+ * later injection: a session that keeps receiving new updates must not hand an
+ * already-stuck id a fresh ceiling, or the loop it was meant to stop continues
+ * for exactly the events that are stuck.
  *
- * Every drive costs a full agent run, so three attempts cover the drive that
- * follows the settlement which missed Pi's follow-up queue plus two retries
- * after intervening runs that also ended before their stop point. Beyond that
- * the condition is systemic (Pi dropped the queue, the runs keep ending early)
- * and further attempts could only start runs without delivering anything: the
- * delivery stays unacknowledged, hence pending on the daemon, which redelivers
- * it to a later run or session.
+ * The trade-off is deliberate and asymmetric: losing one agent update is
+ * recoverable (the agent is still there and its transcript can be read
+ * directly), while an unbounded continuation loop floods the orchestrator
+ * session with empty turns and makes it unusable. A missed update is therefore
+ * strictly better than an endless one.
  */
-export const MAX_WAKE_CONTINUATION_ATTEMPTS = 3;
+export const MAX_WAKE_CONTINUATION_ATTEMPTS = 5;
 /** `customType` of the hidden wake context this extension injects. */
 const WAKE_CONTEXT_CUSTOM_TYPE = "herdsman-wake-context";
 /** `customType` of the hidden marker that drives a missed wake continuation. */
@@ -378,7 +400,6 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       launchIdentity: undefined,
       latestContext: undefined,
       pendingEvents: [],
-      pinnedContext: undefined,
       presentedEventIds: new Set(),
       reconnectingFromOn: false,
       registrationInFlight: undefined,
@@ -394,8 +415,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       wakeConsumptionObserved: new Set(),
       wakeSuppressedEventIds: new Set(),
       wakeSkipLogReasons: new Map(),
-      wakeContinuationAttempts: 0,
-      wakeContext: undefined,
+      wakeContinuationDrives: new Map(),
       wakeRequested: false,
       wakeRequestedThroughEventId: 0,
       wakeTimer: undefined,
@@ -446,15 +466,10 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       cancelWakeTimer();
       state.wakeRequested = false;
       state.wakeRequestedThroughEventId = 0;
-      // A wake queued for a busy orchestrator belongs to the role/scope that
-      // queued it: dropping it here keeps a stale event body out of the context
-      // of whatever session takes over next.
-      state.wakeContext = undefined;
     };
 
     const clearAgentContext = () => {
       state.latestContext = undefined;
-      state.pinnedContext = undefined;
       state.runActive = false;
     };
 
@@ -504,7 +519,8 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       state.wakeAwaitingConsumption.delete(eventId);
       state.wakeConsumptionObserved.delete(eventId);
       state.wakeSuppressedEventIds.delete(eventId);
-      if (state.wakeAwaitingConsumption.size === 0) state.wakeContinuationAttempts = 0;
+      // The id can no longer owe a drive, so its own budget leaves with it.
+      state.wakeContinuationDrives.delete(eventId);
     };
 
     /**
@@ -544,7 +560,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       state.wakeAwaitingConsumption.clear();
       state.wakeConsumptionObserved.clear();
       state.wakeSkipLogReasons.clear();
-      state.wakeContinuationAttempts = 0;
+      state.wakeContinuationDrives.clear();
     };
 
     const pruneAcknowledgedEvents = (ackedEventId: number | undefined) => {
@@ -935,6 +951,44 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       return { deliveryQueue, confirmablePrefix, blockedByMissingTurn, stillAwaitingConsumption };
     };
 
+    const writeOffStrandedWakeDelivery = (eventIds: number[], ctx: PiContext): void => {
+      // Release first, acknowledge second: the release is what breaks the loop
+      // synchronously, while the acknowledgement is an RPC that may fail.
+      for (const eventId of eventIds) {
+        state.wakeAwaitingConsumption.delete(eventId);
+        // This set only ever holds the id of a delivery that was already handed
+        // to Pi, so releasing it is not permission to present it again: the
+        // session-wide presented guard stays behind and keeps a daemon replay
+        // of the same id out of the transcript.
+        state.presentedEventIds.add(eventId);
+      }
+      // The written-off ids can no longer owe a drive, so their budgets leave
+      // with them. Every id that is still awaiting consumption keeps its own
+      // budget: it has not spent its own MAX_WAKE_CONTINUATION_ATTEMPTS drives
+      // yet, and resetting it here is what used to let a sibling's fresh budget
+      // cover for an unrelated stuck id.
+      for (const eventId of eventIds) state.wakeContinuationDrives.delete(eventId);
+      const stranded = eventIds
+        .map((eventId) => state.unackedDelivered.get(eventId))
+        .filter((event): event is AgentEventWireRecord => event !== undefined)
+        .sort((left, right) => left.id - right.id);
+      logHerdsmanPi(
+        "warn",
+        `[herdsman-pi] wake continuation gave up eventIds=${eventIds.join(",")} drives=${MAX_WAKE_CONTINUATION_ATTEMPTS} · released and acknowledged as consumed so the daemon stops redelivering them`,
+      );
+      ctx.ui.notify?.(
+        `Herdsman · ${eventIds.length} agent update${eventIds.length === 1 ? "" : "s"} could not be delivered by a wake turn · given up on (possibly never seen): read the agent directly for the details, or hand this workspace to another terminal so the daemon delivers it there`,
+        "warning",
+      );
+      if (stranded.length === 0) return;
+      void acknowledgeEventIds(stranded, { notify: false }, ctx).catch((error: unknown) => {
+        logHerdsmanPi(
+          "warn",
+          `[herdsman-pi] wake write-off acknowledgement failed eventIds=${stranded.map((event) => event.id).join(",")} · ${String(error)}`,
+        );
+      });
+    };
+
     /**
      * Drives one continuation that carries out a wake Pi has not drained.
      *
@@ -950,17 +1004,25 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
      *
      * Only consumption evidence writes a delivery off, so an intervening run that
      * ends before its stop point (error, user abort, a refused tool) leaves the
-     * next settlement driving again. That is bounded by
-     * MAX_WAKE_CONTINUATION_ATTEMPTS: starting runs cannot fix a cause that is
-     * not about the queue, and once the budget is spent the delivery stays
-     * unacknowledged and therefore pending on the daemon.
+     * next settlement driving again. That bound is per event id and nothing
+     * resets it: starting runs cannot fix a cause that is not about the queue, so
+     * once an id's own budget is spent the id is written off (released and
+     * acknowledged) instead of looping forever — see
+     * `writeOffStrandedWakeDelivery` for the trade-off.
      */
     const driveWakeContinuation = (ctx: PiContext) => {
       if (state.wakeAwaitingConsumption.size === 0) return;
-      if (state.wakeContinuationAttempts >= MAX_WAKE_CONTINUATION_ATTEMPTS) return;
       if (!pi.sendMessage) return;
       const eventIds = [...state.wakeAwaitingConsumption].sort((left, right) => left - right);
-      state.wakeContinuationAttempts += 1;
+      // Every id that is still waiting spends one drive of its own budget. The
+      // counters are keyed by event id and are never reset by an injection, so a
+      // delivery handed over later cannot buy an already-stuck id a fresh budget.
+      const spent: number[] = [];
+      for (const eventId of eventIds) {
+        const drives = (state.wakeContinuationDrives.get(eventId) ?? 0) + 1;
+        state.wakeContinuationDrives.set(eventId, drives);
+        spent.push(drives);
+      }
       try {
         pi.sendMessage(
           {
@@ -972,29 +1034,27 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
         );
         logHerdsmanPi(
           "info",
-          `[herdsman-pi] wake continuation driven eventIds=${eventIds[0] ?? 0}-${eventIds.at(-1) ?? 0} count=${eventIds.length} attempt=${state.wakeContinuationAttempts}`,
+          `[herdsman-pi] wake continuation driven eventIds=${eventIds[0] ?? 0}-${eventIds.at(-1) ?? 0} count=${eventIds.length} drives=${spent.join(",")}`,
         );
       } catch {
         logHerdsmanPi("warn", "[herdsman-pi] wake continuation refused by pi");
       }
-      if (state.wakeContinuationAttempts >= MAX_WAKE_CONTINUATION_ATTEMPTS) {
-        logHerdsmanPi(
-          "warn",
-          `[herdsman-pi] wake continuation limit reached awaiting=${eventIds.join(",")} attempts=${state.wakeContinuationAttempts} · delivery stays unacknowledged for daemon redelivery`,
-        );
-        // Bounded retries cannot deliver this update, and the daemon does not
-        // redeliver while this terminal still holds the scope
-        // (`nextDeliverableAfter` skips events already delivered to the same
-        // owner), so the session is where it has to be visible. The notice must
-        // not promise what the extension cannot do: a copy that Pi dropped cannot
-        // be drained by "the next turn", it is simply gone here — so it says what
-        // is true (unconfirmed, possibly dropped) and what the user can actually
-        // do about it (a later turn still drains a queued copy, and handing the
-        // workspace to another terminal makes the daemon redeliver the update).
-        ctx.ui.notify?.(
-          `Herdsman · ${eventIds.length} agent update${eventIds.length === 1 ? "" : "s"} could not be delivered by a wake turn · unconfirmed and possibly dropped: keep working here so a later turn drains a queued copy, or hand this workspace to another terminal so the daemon redelivers it`,
-          "warning",
-        );
+      // Only the ids whose own budget this drive spent are written off. A sibling
+      // that still has drives left keeps its copy in the queue and its count, so
+      // it is neither lost nor granted a fresh ceiling.
+      const exhausted = eventIds.filter(
+        (_eventId, index) => (spent[index] ?? 0) >= MAX_WAKE_CONTINUATION_ATTEMPTS,
+      );
+      if (exhausted.length > 0) {
+        // This was the last drive the id's own budget allows, and the queued copy
+        // is still undrained: the id is written off instead of being left
+        // pending forever. The ids are released from
+        // `wakeAwaitingConsumption` (no further run is started for them) and
+        // acknowledged, which is what stops the daemon from redelivering them
+        // every freshness window — the loop that used to flood the orchestrator
+        // session until manual sqlite surgery. Losing one update is the accepted
+        // cost; see `writeOffStrandedWakeDelivery`.
+        writeOffStrandedWakeDelivery(exhausted, ctx);
       }
     };
 
@@ -1193,11 +1253,17 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
           state.wakeTimer = undefined;
           state.wakeRequested = true;
           state.wakeRequestedThroughEventId = current.at(-1)?.eventId ?? 0;
-          // Dual-track injection: an idle orchestrator gets a triggered
-          // follow-up turn (immediate delivery), while a busy one is not
-          // interrupted — the same content is queued as a non-triggering
-          // follow-up and additionally exposed through the `context` hook so the
-          // running turn can already see it.
+          // Single-track injection: the wake content is handed to Pi exactly
+          // once, as the follow-up message below. An idle orchestrator gets a
+          // triggered follow-up turn (immediate delivery); a busy one is not
+          // interrupted and receives the same content as a queued,
+          // non-triggering follow-up that a later run drains out of the
+          // follow-up queue. There is deliberately no second copy on the
+          // `context` hook: a run that is busy cannot act on an early copy
+          // anyway, while a second copy is exactly what puts the same update
+          // into the session twice. So the transcript holds one entry per event
+          // id, and the continuation drive (see `driveWakeContinuation`) is what
+          // carries a queued copy that no run drained into the transcript.
           const orchestratorBusy = ctx.isIdle?.() === false;
           const wakeContent = formatAgentOutcomeUpdates(batchOutcomes);
           // Single line, injection path only: the decision that produced this
@@ -1238,17 +1304,17 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
             // `driveWakeContinuation`), and until the content is seen in the
             // transcript the delivery is neither acknowledged nor injected again.
             if (orchestratorBusy) {
+              // A freshly queued id starts its own continuation budget; an id that
+              // was already awaiting consumption (merged into this batch from an
+              // earlier injection) keeps the drives it already spent. Only a new
+              // id may get a fresh ceiling — never an unrelated one.
               for (const outcome of batchOutcomes) {
                 state.wakeAwaitingConsumption.add(outcome.eventId);
+                if (!state.wakeContinuationDrives.has(outcome.eventId)) {
+                  state.wakeContinuationDrives.set(outcome.eventId, 0);
+                }
               }
-              state.wakeContinuationAttempts = 0;
             }
-            // A queued (non-triggering) delivery keeps the content available to
-            // the current turn through the context hook until it is settled or
-            // superseded by the next injection.
-            state.wakeContext = orchestratorBusy
-              ? { content: wakeContent, eventIds: batchOutcomes.map((outcome) => outcome.eventId) }
-              : undefined;
             state.wakeForcedRelease = false;
             state.wakeDeferredSince = undefined;
             // Only expose the batch after the hidden context was accepted by pi. This
@@ -1488,7 +1554,6 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
           // already acked events are covered by the server cursor
           // (pruneAcknowledgedEvents below).
           state.deliveredBatch = undefined;
-          state.wakeContext = undefined;
         }
         // Otherwise the batch's wake turn is still in flight: keep it so the
         // settlement acknowledges it and the events are not re-presented.
@@ -1576,23 +1641,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
           state.currentScope.workspaceId === message.params.workspaceId
         ) {
           const next = message.params.context ?? undefined;
-          const retain = (snapshot: AgentWorkspaceContextSnapshot | undefined) =>
-            snapshot
-              ? {
-                  ...snapshot,
-                  agents: snapshot.agents.flatMap((agent) => {
-                    const nextAgents =
-                      next?.agents.filter((candidate) => candidate.paneId === agent.paneId) ?? [];
-                    if (nextAgents.length === 0) return [];
-                    const nextAgent = nextAgents.find(
-                      (candidate) => !agent.id || !candidate.id || agent.id === candidate.id,
-                    );
-                    return nextAgent ? [nextAgent] : [];
-                  }),
-                }
-              : undefined;
           state.latestContext = next;
-          state.pinnedContext = retain(state.pinnedContext);
         }
         return;
       }
@@ -1796,6 +1845,9 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
         }
         for (const eventId of consumedEventIds) {
           state.wakeAwaitingConsumption.delete(eventId);
+          // Its copy reached the transcript, so the id owes no drive any more and
+          // its budget leaves with it.
+          state.wakeContinuationDrives.delete(eventId);
           // The content reached the transcript, so this id counts as presented from
           // now on: a daemon redelivery of it (it is still unacknowledged whenever
           // its batch was already dropped) must not inject the same update again.
@@ -1807,7 +1859,6 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
           // Only an id the daemon can still be told about is worth remembering.
           if (state.unackedDelivered.has(eventId)) state.wakeConsumptionObserved.add(eventId);
         }
-        if (state.wakeAwaitingConsumption.size === 0) state.wakeContinuationAttempts = 0;
       }
       if (message.role !== "assistant") return;
       const stopReason = stringValue(message.stopReason);
@@ -1846,63 +1897,25 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       // the next user message.
       if (state.runActive) return;
       state.runActive = true;
-      state.pinnedContext =
-        state.isOrchestrator && !state.deliveredBatch?.herdsmanTriggered
-          ? state.latestContext
-          : undefined;
     });
 
     pi.on("context", (event: { messages: PiAgentMessage[] }) => {
+      // The wake content rides the single follow-up track and is never pinned
+      // into the context here, so this hook injects nothing at all. What it
+      // still does is drop herdsman's own context/wake entries from the
+      // incoming list: a session replayed from disk can carry an old
+      // `[HERDSMAN AGENT CONTEXT]` preview (its truncated one-line reports
+      // repeatedly read as cut-off reports, and live board state is queried
+      // through herdr), so those entries are filtered out instead of being
+      // re-served to the model. The wake message itself
+      // (`herdsman-wake-context`, the full report text) is not filtered - it is
+      // the evidence the turn acts on.
       const messages = event.messages.filter((message) => !isNormalHerdsmanContext(message));
-      const additions: PiAgentMessage[] = [];
-      const snapshot = state.pinnedContext;
-      if (snapshot && snapshot.agents.length > 0) {
-        additions.push({
-          content: formatHiddenAgentContext({
-            agents: snapshot.agents,
-            workspaceId: snapshot.workspaceId,
-          }),
-          customType: "herdsman-agent-context",
-          display: false,
-          role: "custom",
-          timestamp: Date.now(),
-        });
-      }
-      // A wake queued for a busy orchestrator is not allowed to interrupt the
-      // running tool chain, so its content is additionally pinned to the current
-      // context: the orchestrator sees the child-agent outcome in this turn
-      // without a triggered follow-up. The entry is dropped again by
-      // isNormalHerdsmanContext, so at most one copy is present per call.
-      //
-      // `eventIds` mirrors what this turn actually presents (the freshly injected
-      // outcomes): events carried over in the delivery queue were already shown
-      // to the orchestrator in the turn that presented them, so they are not
-      // re-listed here. The queued follow-up message itself keeps the wider
-      // `details.eventIds` set (everything still unconfirmed).
-      //
-      // The pin is not a second delivery of the update: it makes the same queued
-      // copy visible early to the turn that is running, it is not written to the
-      // transcript, it is never acknowledged on its own, and it is not consumption
-      // evidence — only the hidden wake message's `message_end` is. So it may not be
-      // dropped in the name of "one copy only" either: it is the only way this turn
-      // ever sees the update.
-      const queuedWake = state.wakeContext;
-      if (queuedWake) {
-        additions.push({
-          content: queuedWake.content,
-          customType: "herdsman-wake-queued",
-          details: { eventIds: queuedWake.eventIds },
-          display: false,
-          role: "custom",
-          timestamp: Date.now(),
-        });
-      }
-      return additions.length === 0 ? { messages } : { messages: [...messages, ...additions] };
+      return { messages };
     });
 
     pi.on("agent_settled", async (_event: unknown, ctx: PiContext) => {
       state.runActive = false;
-      state.pinnedContext = undefined;
       // A wake delivered as a queued follow-up is drained only when a run reaches
       // its stop point. If the run that received it settled without draining it,
       // no further run exists to carry the update out: drive a continuation (up to
@@ -1920,7 +1933,6 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
         state.wakeDeferredUntilSettled = false;
         state.wakeDeferredSince = undefined;
         state.wakeForcedRelease = false;
-        state.wakeContext = undefined;
         setHerdsmanUi(ctx);
         scheduleWake(ctx);
       };
@@ -1988,62 +2000,6 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
 
 export default createHerdsmanPiExtension();
 
-export function formatHiddenAgentContext(input: {
-  agents: AgentContextListItem[];
-  workspaceId: string;
-}): string {
-  return [
-    "[HERDSMAN AGENT CONTEXT]",
-    `Current Herdr workspace: ${input.workspaceId}`,
-    ...input.agents.map((agent) => {
-      const history = agent.history ?? {};
-      const identity = agentIdentityLabel({
-        agent: agent.agent ?? "unknown",
-        name: agent.name,
-      });
-      const paneId = agent.paneId ?? "unknown";
-      const status = agent.agentStatus ?? "unknown";
-      const prefix = `- ${identity} ${paneId} ${status}`;
-
-      const rawAgent = record(agent);
-      const tabTitleCandidate =
-        stringValue(rawAgent.terminalTitle) ?? stringValue(rawAgent.label);
-      const tabTitleCleaned =
-        tabTitleCandidate !== null ? sanitizeAndCleanContextText(tabTitleCandidate) : "";
-      const tabTitle =
-        tabTitleCleaned.length > 0 ? truncateSummary(tabTitleCleaned, 60) : null;
-
-      const rawHistory = record(history);
-      const lastAssistantRecord = record(history.lastAssistantMessage);
-      const timeCandidate =
-        lastAssistantRecord.timestamp ??
-        history.updatedAt ??
-        rawHistory.updatedAt ??
-        rawAgent.updatedAt ??
-        rawAgent.time;
-      const formattedTime = formatTimestamp(timeCandidate);
-
-      const assistantRaw = history.lastAssistantMessage?.text;
-      const assistantCleaned =
-        assistantRaw !== undefined && assistantRaw !== null
-          ? sanitizeAndCleanContextText(assistantRaw)
-          : "";
-      const assistantSummary =
-        assistantCleaned.length > 0 ? truncateSummary(assistantCleaned, 100) : null;
-
-      const segments = [
-        prefix,
-        tabTitle,
-        formattedTime,
-        assistantSummary,
-      ].filter((segment): segment is string => segment !== null && segment.length > 0);
-
-      return segments.join(" · ");
-    }),
-    "Use herdsman agent get/read if details are needed.",
-  ].join("\n");
-}
-
 export function formatHiddenAgentUpdates(events: AgentEventWireRecord[]): string {
   return [
     "[HERDSMAN AGENT UPDATES]",
@@ -2066,6 +2022,10 @@ export function formatHiddenAgentUpdates(events: AgentEventWireRecord[]): string
 function isNormalHerdsmanContext(message: PiAgentMessage): boolean {
   return (
     message.customType === "herdsman-agent-context" ||
+    // Defensive for session replay: older versions pinned a queued wake to the
+    // context hook under this customType. A replayed history may still carry
+    // those entries, and they are herdsman's own, so they are dropped from the
+    // incoming list like the agent-context ones (see the context hook).
     message.customType === "herdsman-wake-queued" ||
     contentIncludesMarker(message.content, "[HERDSMAN AGENT CONTEXT]")
   );
@@ -2119,12 +2079,22 @@ function record(value: unknown): Record<string, unknown> {
 }
 
 function cleanContextText(value: string): string {
+  // Same newline-preserving scheme as `normalizeExcerpt` in wake.ts: which byte a
+  // line break is (CRLF, CR, U+2028/U+2029, NEL) is normalised to LF, trailing
+  // whitespace is dropped per line, 3+ newlines collapse to a blank line, and
+  // leading indentation plus inline runs of whitespace are kept as they are.
+  // NEL (U+0085) is excluded from the control-character clearing regex below,
+  // which would otherwise delete it as an unprintable byte; the rest of that
+  // regex is left intact.
   return stripVTControlCharacters(value)
     .replace(
-      /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f\u00ad\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g,
+      /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u0084\u0086-\u009f\u00ad\u180e\u200b-\u200f\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g,
       "",
     )
-    .replace(/\s+/g, " ")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u2028\u2029\u0085]/g, "\n")
+    .replace(/[^\S\n]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
     .trim();
 }
 
@@ -2135,32 +2105,3 @@ function sanitizeAndCleanContextText(value: string): string {
   return cleanContextText(sanitized);
 }
 
-function truncateSummary(value: string, limit = 100): string {
-  if (value.length <= limit) return value;
-  const maxSearch = Math.min(value.length, limit + 8);
-  const searchSlice = value.slice(0, maxSearch);
-  const lastSpaceIndex = searchSlice.search(/\s[^\s]*$/);
-  if (lastSpaceIndex >= limit - 20) {
-    return `${value.slice(0, lastSpaceIndex)}…`;
-  }
-  return `${value.slice(0, limit)}…`;
-}
-
-function formatTimestamp(value: unknown): string | null {
-  if (typeof value === "string") {
-    const trimmed = value.trim();
-    if (/^\d{2}:\d{2}:\d{2}$/.test(trimmed)) return trimmed;
-    if (/^\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(trimmed)) return trimmed;
-  }
-  if (!value) return null;
-  const date = value instanceof Date ? value : new Date(value as string | number);
-  if (Number.isNaN(date.getTime())) return null;
-  const pad = (n: number) => String(n).padStart(2, "0");
-  const month = pad(date.getMonth() + 1);
-  const day = pad(date.getDate());
-  const hours = pad(date.getHours());
-  const minutes = pad(date.getMinutes());
-  const seconds = pad(date.getSeconds());
-  return `${month}-${day} ${hours}:${minutes}:${seconds}`;
-}
-

package/src/wake.ts

@@ -34,7 +34,26 @@ function asRecord(value: unknown): Record<string, unknown> {
 function stringValue(value: unknown): string | undefined { return typeof value === "string" && value.length > 0 ? value : undefined; }
 function normalizeExcerpt(value: unknown): string {
   const raw = stringValue(value) ?? "";
-  return stripVTControlCharacters(raw).replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u009f]/g, "").replace(/\s+/g, " ").trim();
+  // Line structure is evidence, not noise: a code block or a markdown heading
+  // only reads as one while its newlines survive, so this chain normalises
+  // *which byte* a line break is and where whitespace sits inside a line, and
+  // never folds a newline into a space:
+  //   - CRLF/CR and the Unicode line separators (U+2028, U+2029, NEL) become LF,
+  //     so "a line" means one thing everywhere downstream (NEL is excluded from
+  //     the control-character regex, which would otherwise delete it);
+  //   - trailing whitespace is dropped per line, so a "blank" line padded with
+  //     spaces still collapses (it would otherwise defeat the 3+ newline rule);
+  //   - three or more newlines collapse to a single blank line;
+  //   - leading indentation and inline runs of whitespace are kept as they are,
+  //     because they are what keeps a code block readable.
+  // No length cap is applied here.
+  return stripVTControlCharacters(raw)
+    .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f-\u0084\u0086-\u009f]/g, "")
+    .replace(/\r\n?/g, "\n")
+    .replace(/[\u2028\u2029\u0085]/g, "\n")
+    .replace(/[^\S\n]+$/gm, "")
+    .replace(/\n{3,}/g, "\n\n")
+    .trim();
 }
 function outcomeKind(event: AgentEventWireRecord): AgentOutcome["kind"] | undefined {
   if (!event.terminalId) return undefined;