@dorokuma/herdsman-pi 0.11.6 → 0.13.2

package/src/index.ts

@@ -1,25 +1,10 @@
 import { agentIdentityLabel } from "./agent-display.js";
-import { sanitizeText } from "./sanitize-text.js";
-import { appendFileSync, mkdirSync } from "node:fs";
-import { homedir } from "node:os";
-import { dirname, isAbsolute, join } from "node:path";
+import { sanitizeText, textFromContent } from "./sanitize-text.js";
 import { stripVTControlCharacters } from "node:util";
+import { logHerdsmanPi } from "./logger.js";
 
-export type HerdsmanPiLogLevel = "info" | "warn" | "error";
-
-export function logHerdsmanPi(level: HerdsmanPiLogLevel, message: string): void {
-  try {
-    const configuredHome = process.env.HERDSMAN_HOME?.trim();
-    const home = configuredHome && isAbsolute(configuredHome) ? configuredHome : join(homedir(), ".herdsman");
-    const now = new Date();
-    const date = now.toISOString().slice(0, 10).replaceAll("-", "");
-    const file = join(home, "logs", `herdsman-pi-${date}.log`);
-    mkdirSync(dirname(file), { recursive: true });
-    appendFileSync(file, `${now.toISOString()} [${level}] ${message}\n`, "utf8");
-  } catch {
-    // Diagnostics must never write to the terminal or interrupt the extension.
-  }
-}
+export { logHerdsmanPi };
+export type { HerdsmanPiLogLevel } from "./logger.js";
 
 import {
   type AgentContextListItem,
@@ -41,6 +26,8 @@ import {
   formatAgentOutcomeUpdates,
   WAKE_SETTLE_MS,
 } from "./wake.js";
+import { loadWakeFilterConfig } from "./wake-filter-config.js";
+import type { WakeFilterConfig } from "./upstream-error.js";
 import { confirmSessionWrite } from "./turn-signal.js";
 
 type PiAgentMessage = {
@@ -126,7 +113,29 @@ type HerdsmanState = {
   roleMutationInFlight: boolean;
   sessionRef: AgentSessionRef | undefined;
   subscriberId: string | undefined;
+  /**
+   * Delivery queue: events handed to Pi whose acknowledgement is still
+   * outstanding. Id-keyed so a repeated id is stored exactly once (deliver
+   * once), and every consumer sorts by id. Entries are only removed by an
+   * acknowledgement (success or dead-letter) or by a role/scope reset that also
+   * clears `presentedEventIds`, so releasing a deferred wake can never lose an
+   * unconfirmed event.
+   */
+  unackedDelivered: Map<number, AgentEventWireRecord>;
   wakeDeferredUntilSettled: boolean;
+  /** Wall-clock start of the current bounded wake deferral, if any. */
+  wakeDeferredSince: number | undefined;
+  /**
+   * Set once the hard deferral budget elapsed: the next pass injects the batch
+   * from the current state instead of deferring again.
+   */
+  wakeForcedRelease: boolean;
+  /**
+   * Event content queued for a busy orchestrator. Injected through the
+   * `context` hook so the running turn sees the update without being
+   * interrupted.
+   */
+  wakeContext: { content: string; eventIds: number[] } | undefined;
   wakeRequested: boolean;
   wakeRequestedThroughEventId: number;
   wakeTimer: ReturnType<typeof setTimeout> | undefined;
@@ -173,6 +182,7 @@ type ExtensionOptions = {
   clientFactory?: () => HerdsmanDaemonClient;
   onTurnCompletionSignal?: (completion: Promise<void>) => void;
   onStateExposed?: (state: HerdsmanState) => void;
+  wakeFilter?: WakeFilterConfig;
 };
 
 const DEFAULT_HOME_NAME = ".herdsman";
@@ -182,6 +192,15 @@ const RECONNECTING_MESSAGE = "Herdsman is reconnecting · try again shortly";
 export const MAX_ACK_ATTEMPTS = 5;
 export const ACK_BACKOFF_CAP_MS = 30_000;
 const KEEPALIVE_INTERVAL_MS = 30_000;
+/** Retry interval used while a wake cannot be injected (busy orchestrator). */
+export const WAKE_BUSY_SPIN_MS = 100;
+/**
+ * Hard upper bound for every deferred wake. Once it elapses the scheduler stops
+ * waiting for the orchestrator to become idle or for a settlement to arrive and
+ * forces the injection decision from the current state, so a wake can never be
+ * parked forever.
+ */
+export const WAKE_DEFERRED_TIMEOUT_MS = 5_000;
 
 type AckFailureClass = "terminal" | "resync" | "transient";
 
@@ -242,6 +261,9 @@ export function defaultSocketPath() {
 export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
   return function herdsmanPiExtension(pi: PiApi): void {
     pi.registerMessageRenderer?.("herdsman-wake", renderAgentUpdateMessage);
+    // Read once per extension instance: config.yaml changes require a Pi restart,
+    // matching the daemon's startup-time config model.
+    const wakeFilter = options.wakeFilter ?? loadWakeFilterConfig();
 
     const state: HerdsmanState = {
       client: undefined,
@@ -261,7 +283,11 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       runActive: false,
       sessionRef: undefined,
       subscriberId: undefined,
+      unackedDelivered: new Map(),
       wakeDeferredUntilSettled: false,
+      wakeDeferredSince: undefined,
+      wakeForcedRelease: false,
+      wakeContext: undefined,
       wakeRequested: false,
       wakeRequestedThroughEventId: 0,
       wakeTimer: undefined,
@@ -293,7 +319,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
         : state.isOrchestrator
           ? {
               kind: "on",
-              updateCount: projectAgentOutcomes(state.pendingEvents).outcomes.length,
+              updateCount: projectAgentOutcomes(state.pendingEvents, wakeFilter).outcomes.length,
             }
           : { kind: "off" };
       ctx.ui.setStatus?.("herdsman", formatHerdsmanFooterStatus(footerState));
@@ -304,12 +330,18 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       if (state.wakeTimer) clearTimeout(state.wakeTimer);
       state.wakeTimer = undefined;
       state.wakeDeferredUntilSettled = false;
+      state.wakeDeferredSince = undefined;
+      state.wakeForcedRelease = false;
     };
 
     const cancelWake = () => {
       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 = () => {
@@ -318,6 +350,41 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       state.runActive = false;
     };
 
+    const unackedDeliveredAscending = (): AgentEventWireRecord[] =>
+      [...state.unackedDelivered.values()].sort((left, right) => left.id - right.id);
+
+    /**
+     * Merges freshly injected events into the delivery queue.
+     *
+     * Invariants (Phase 1 completeness fix):
+     *  - a new batch is merged into the queue, never substituted for it, so an
+     *    unconfirmed batch keeps riding along with the next delivery instead of
+     *    being stranded;
+     *  - the result is id-ascending and id-deduped, so the same id is never
+     *    delivered (or acknowledged) twice;
+     *  - entries are only ever removed by `dropUnackedDelivered` (acknowledged or
+     *    dead-lettered) or by a role/scope reset, so releasing the deferred wake
+     *    cannot drop an unconfirmed event.
+     */
+    const mergeUnackedDelivered = (
+      incoming: readonly AgentEventWireRecord[],
+    ): AgentEventWireRecord[] => {
+      for (const event of incoming) {
+        if (!state.unackedDelivered.has(event.id)) state.unackedDelivered.set(event.id, event);
+      }
+      return unackedDeliveredAscending();
+    };
+
+    /**
+     * Drops one event from the delivery queue. The only callers are the two
+     * acknowledgement outcomes (accepted, or terminally refused by the daemon)
+     * and the role/scope reset, which clears the whole stream together with
+     * `presentedEventIds`.
+     */
+    const dropUnackedDelivered = (eventId: number): void => {
+      state.unackedDelivered.delete(eventId);
+    };
+
     const pruneAcknowledgedEvents = (ackedEventId: number | undefined) => {
       if (ackedEventId === undefined) return;
       // Acknowledged events leave the pending projection but intentionally stay
@@ -329,6 +396,13 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       // set is bounded by the number of events presented per session and is
       // cleared on role loss, scope change, and shutdown.
       state.pendingEvents = state.pendingEvents.filter((event) => event.id > ackedEventId);
+      // The delivery queue follows the same watermark: an event covered by the
+      // advanced acknowledgement cursor is confirmed even when its own ack was
+      // superseded (the daemon acknowledges by watermark), so it leaves the
+      // queue and is never re-acknowledged.
+      for (const eventId of [...state.unackedDelivered.keys()]) {
+        if (eventId <= ackedEventId) state.unackedDelivered.delete(eventId);
+      }
     };
 
     const isWakeableEvent = (event: AgentEventWireRecord | undefined) =>
@@ -338,34 +412,290 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       state.latestContext = isLocalOwner(response) ? response.context ?? undefined : undefined;
     };
 
+    const acknowledgeEventIds = async (
+      events: readonly AgentEventWireRecord[],
+      options: { notify: boolean },
+      ctx: PiContext,
+    ): Promise<void> => {
+      for (const event of [...events].sort((left, right) => left.id - right.id)) {
+        try {
+          // A missing client (disconnect) must never be treated as a successful
+          // acknowledgement: route it through the same failure path as a
+          // transient RPC error so the id keeps its backoff and stays pending.
+          if (!state.client) {
+            throw new Error("Herdsman Pi is not connected; cannot acknowledge notifications");
+          }
+          const ackResponse = (await state.client.request("agent.notifications.ack", {
+            eventId: event.id,
+          })) as { ackedEventId?: number; state?: { ackedEventId?: number } } | undefined;
+          pruneAcknowledgedEvents(ackResponse?.ackedEventId ?? ackResponse?.state?.ackedEventId);
+          state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
+          // The event is confirmed: it leaves the delivery queue for good, which
+          // is what keeps the acknowledgement watermark monotonic (ids are acked
+          // in ascending order and never re-issued).
+          dropUnackedDelivered(event.id);
+          // The id intentionally stays in presentedEventIds: the event was
+          // already presented this session and must not be injected again even
+          // if the daemon replays it (for example after a reconnect
+          // redelivery). The set is cleared only on role loss, scope change,
+          // or shutdown.
+          state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
+          setHerdsmanUi(ctx);
+        } catch (error) {
+          const failureCode = ackFailureCode(error);
+          const classification = classifyAckFailure(error);
+          // The attempt counter is read from the live projection, not from the
+          // delivery-queue snapshot the caller iterated over: a stale base would
+          // pin the counter at 1 for good and make the MAX_ACK_ATTEMPTS
+          // dead-letter branch unreachable for every event retried here.
+          const attempts =
+            (state.pendingEvents.find((pending) => pending.id === event.id)?.attempts ??
+              event.attempts ??
+              0) + 1;
+          const attemptedAt = Date.now();
+          const updatedEvent = {
+            ...event,
+            attempts,
+            lastAttemptAt: attemptedAt,
+            lastFailureCode: failureCode,
+          };
+          state.pendingEvents = state.pendingEvents.map((pending) =>
+            pending.id === event.id ? updatedEvent : pending,
+          );
+          // Keep the delivery-queue entry in step with the live accounting: the
+          // same event may be retried later (another settlement, or a redelivery
+          // that re-attaches it to a new batch), and that attempt must resume
+          // from this counter instead of restarting at 1.
+          if (state.unackedDelivered.has(event.id)) {
+            state.unackedDelivered.set(event.id, updatedEvent);
+          }
+
+          if (classification === "terminal") {
+            state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
+            // A terminally refused event is dead-lettered by the daemon
+            // (failedWakeThroughEventId is the dead-letter barrier), so it can
+            // never be confirmed later; it leaves the delivery queue as well.
+            dropUnackedDelivered(event.id);
+            state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
+            if (/Only the current orchestrator can acknowledge notifications/i.test(failureCode)) {
+              state.isOrchestrator = false;
+              logHerdsmanPi(
+                "warn",
+                `[herdsman-pi] lost orchestrator ownership while acknowledging event ${event.id}`,
+              );
+            } else {
+              logHerdsmanPi(
+                "warn",
+                `[herdsman-pi] terminal acknowledgement failure eventId=${event.id} attempts=${attempts} code=${failureCode}`,
+              );
+            }
+            setHerdsmanUi(ctx);
+            continue;
+          }
+
+          if (attempts >= MAX_ACK_ATTEMPTS) {
+            state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
+            // Dead-lettered by this client: the id is behind the dead-letter
+            // barrier from now on, so it can never be confirmed later and leaves
+            // the delivery queue with the pending projection.
+            dropUnackedDelivered(event.id);
+            state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
+            logHerdsmanPi(
+              "warn",
+              `[herdsman-pi] acknowledgement moved to dead-letter eventId=${event.id} attempts=${attempts} code=${failureCode}`,
+            );
+            setHerdsmanUi(ctx);
+            continue;
+          }
+
+          if (classification === "resync") {
+            const resyncEvent = {
+              ...updatedEvent,
+              nextAttemptAt: attemptedAt + ackBackoffMs(attempts),
+            };
+            state.pendingEvents = state.pendingEvents.map((pending) =>
+              pending.id === event.id ? resyncEvent : pending,
+            );
+            try {
+              const response = (await state.client?.request(
+                "agent.orchestrator.get",
+                {},
+              )) as ConnectionStateResponse | undefined;
+              // Refresh pending data without applying the full connection response: that
+              // helper schedules a new wake, which would make this failed batch race
+              // with the current settlement and can replay an earlier event. The
+              // failed event remains pending and the next wake is scheduled by
+              // finishBatch(), so this round performs no additional acknowledgements.
+              if (response) addPendingEvents(response.events ?? [], ctx);
+              pruneAcknowledgedEvents(response?.state?.ackedEventId ?? response?.ackedEventId);
+              setHerdsmanUi(ctx);
+            } catch (resyncError) {
+              logHerdsmanPi(
+                "warn",
+                `[herdsman-pi] acknowledgement resync failed eventId=${event.id} attempts=${attempts} code=${ackFailureCode(resyncError)}`,
+              );
+            }
+            // The event stays pending with a backoff so the ack cursor can
+            // sweep it later, but it was already presented this session and is
+            // not re-presented: presentedEventIds keeps the guard until scope
+            // reset. Continue so one failed event does not block the rest of
+            // the batch.
+            continue;
+          }
+
+          state.pendingEvents = state.pendingEvents.map((pending) =>
+            pending.id === event.id
+              ? { ...pending, nextAttemptAt: attemptedAt + ackBackoffMs(attempts) }
+              : pending,
+          );
+          if (options.notify) {
+            ctx.ui.notify?.(
+              "Herdsman couldn’t acknowledge agent updates · updates remain pending",
+              "warning",
+            );
+          }
+          setHerdsmanUi(ctx);
+          // The event stays pending with a backoff so the ack cursor can sweep
+          // it later, but it was already presented this session and is not
+          // re-presented: presentedEventIds keeps the guard until scope reset.
+          continue;
+        }
+      }
+    };
+
+    // Upstream model errors wake nobody, but they still have to leave the
+    // daemon's pending queue or it never converges. The silent path therefore
+    // acknowledges them without sendMessage, without notify, and without
+    // touching presentedEventIds (reserved for genuinely presented outcomes).
+    const scheduleSilentUpstreamErrorAck = (
+      ctx: PiContext,
+      events: readonly AgentEventWireRecord[],
+    ) => {
+      if (state.wakeTimer || state.wakeRequested) return;
+      const scope = state.currentScope;
+      if (!state.isOrchestrator || !scope) return;
+      const generation = wakeGeneration;
+      const ownerHerdrSessionName = scope.herdrSessionName;
+      const ownerTerminalId = scope.terminalId;
+      const ownerWorkspaceId = scope.workspaceId;
+      state.wakeTimer = setTimeout(() => {
+        state.wakeTimer = undefined;
+        void (async () => {
+          if (
+            generation !== wakeGeneration ||
+            !state.isOrchestrator ||
+            state.currentScope?.herdrSessionName !== ownerHerdrSessionName ||
+            state.currentScope?.terminalId !== ownerTerminalId ||
+            state.currentScope?.workspaceId !== ownerWorkspaceId
+          ) {
+            return;
+          }
+          // A delivered batch or an in-flight ack owns the cursor; its
+          // settlement schedules the next sweep instead of racing this one.
+          if (state.deliveredBatch || state.ackInFlight) return;
+          if (!state.client || !state.connected) return;
+          state.ackInFlight = true;
+          setHerdsmanUi(ctx);
+          try {
+            await acknowledgeEventIds(events, { notify: false }, ctx);
+          } finally {
+            state.ackInFlight = false;
+            setHerdsmanUi(ctx);
+          }
+          scheduleWake(ctx);
+        })();
+      }, WAKE_SETTLE_MS);
+    };
+
+    /**
+     * Arms the bounded deferral for a wake that cannot be injected right now.
+     *
+     * The retry spins every `WAKE_BUSY_SPIN_MS` while the orchestrator is busy
+     * and flips `wakeForcedRelease` once `WAKE_DEFERRED_TIMEOUT_MS` has elapsed,
+     * so the next pass injects the batch from the current state (as a queued,
+     * non-triggering follow-up) instead of waiting for an idle signal or a
+     * settlement that may never arrive.
+     */
+    const scheduleDeferredWake = (ctx: PiContext) => {
+      state.wakeDeferredUntilSettled = true;
+      const since = state.wakeDeferredSince ?? Date.now();
+      state.wakeDeferredSince = since;
+      const remaining = WAKE_DEFERRED_TIMEOUT_MS - (Date.now() - since);
+      if (remaining <= 0) state.wakeForcedRelease = true;
+      if (state.wakeTimer) return;
+      state.wakeTimer = setTimeout(() => {
+        state.wakeTimer = undefined;
+        if (state.wakeForcedRelease && state.deliveredBatch && ctx.isIdle?.() !== false) {
+          // The hard deadline only releases the delivery — it never discards an
+          // unconfirmed event. The batch record is dropped so a wake turn that
+          // is no longer running cannot gate later wakes, but its events stay in
+          // the delivery queue (`unackedDelivered`) and are re-attached to the
+          // batch injected right below, which acknowledges them once it settles.
+          state.deliveredBatch = undefined;
+        }
+        scheduleWake(ctx);
+      }, Math.max(0, Math.min(WAKE_BUSY_SPIN_MS, remaining)));
+    };
+
     const scheduleWake = (ctx: PiContext | undefined) => {
       if (!ctx || !state.isOrchestrator || !state.currentScope || !pi.sendMessage) return;
       if (state.wakeTimer || state.wakeRequested) return;
-      const outcomes = projectAgentOutcomes(state.pendingEvents).outcomes.filter(
+      const projection = projectAgentOutcomes(state.pendingEvents, wakeFilter);
+      const outcomes = projection.outcomes.filter(
         (outcome) =>
           outcome.eventId > state.failedWakeThroughEventId &&
           !state.presentedEventIds.has(outcome.eventId),
       );
+      const suppressedEvents = projection.suppressedUpstreamErrorEventIds
+        .filter(
+          (eventId) =>
+            eventId > state.failedWakeThroughEventId && !state.presentedEventIds.has(eventId),
+        )
+        .map((eventId) => state.pendingEvents.find((pending) => pending.id === eventId))
+        .filter((event): event is AgentEventWireRecord => event !== undefined)
+        .sort((left, right) => left.id - right.id);
 
       const wakeable = outcomes.filter((outcome) =>
         isWakeableEvent(state.pendingEvents.find((pending) => pending.id === outcome.eventId)),
       );
       if (wakeable.length === 0) {
-        const nextAttemptAt = outcomes
-          .map((outcome) => state.pendingEvents.find((event) => event.id === outcome.eventId)?.nextAttemptAt)
-          .filter((value): value is number => value !== undefined)
+        // A suppressed upstream error that is now due must be silently
+        // acknowledged before any backoff timer is planted: planting the timer
+        // first would make scheduleSilentUpstreamErrorAck's entry guard
+        // (`if (state.wakeTimer || state.wakeRequested) return`) bounce the ack
+        // off its own timer and, once the backoff window has elapsed, the
+        // 0ms-timer + blocked-ack loop never converges the queue.
+        const dueSuppressed = suppressedEvents.filter(isWakeableEvent);
+        if (dueSuppressed.length > 0) {
+          scheduleSilentUpstreamErrorAck(ctx, dueSuppressed);
+          return;
+        }
+        // No suppressed event is due, so plant a backoff timer for the next
+        // future `nextAttemptAt`. Expired timestamps are excluded (strictly
+        // greater than now) so an already-past window does not produce a
+        // zero-delay spin.
+        const nextAttemptAt = [
+          ...outcomes.map((outcome) => outcome.eventId),
+          ...suppressedEvents.map((event) => event.id),
+        ]
+          .map((eventId) => state.pendingEvents.find((event) => event.id === eventId)?.nextAttemptAt)
+          .filter((value): value is number => value !== undefined && value > Date.now())
           .sort((left, right) => left - right)[0];
         if (nextAttemptAt !== undefined) {
           state.wakeTimer = setTimeout(() => {
             state.wakeTimer = undefined;
             scheduleWake(ctx);
-          }, Math.max(0, nextAttemptAt - Date.now()));
+          }, nextAttemptAt - Date.now());
         }
         return;
       }
 
-      if (state.deliveredBatch || state.ackInFlight || ctx.isIdle?.() === false) {
-        state.wakeDeferredUntilSettled = true;
+      // An in-flight batch owns the ack cursor and a busy orchestrator must not
+      // be interrupted, so neither is woken immediately — but both are deferred
+      // on a bounded spin (never parked until an event that may never come).
+      const inFlight = state.deliveredBatch !== undefined || state.ackInFlight;
+      if (!state.wakeForcedRelease && (inFlight || ctx.isIdle?.() === false)) {
+        scheduleDeferredWake(ctx);
         return;
       }
       const generation = wakeGeneration;
@@ -384,9 +714,9 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
             state.wakeTimer = undefined;
             return;
           }
-          if (ctx.isIdle?.() === false) {
+          if (ctx.isIdle?.() === false && !state.wakeForcedRelease) {
             state.wakeTimer = undefined;
-            state.wakeDeferredUntilSettled = true;
+            scheduleDeferredWake(ctx);
             return;
           }
 
@@ -421,14 +751,16 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
             state.wakeTimer = undefined;
             return;
           }
-          if (ctx.isIdle?.() === false) {
+          if (ctx.isIdle?.() === false && !state.wakeForcedRelease) {
             state.wakeTimer = undefined;
-            state.wakeDeferredUntilSettled = true;
+            scheduleDeferredWake(ctx);
             return;
           }
 
           const batchEvents = [...state.pendingEvents].sort((left, right) => left.id - right.id);
-          const batchOutcomes = projectAgentOutcomes(batchEvents).outcomes.filter(
+          const batchProjection = projectAgentOutcomes(batchEvents, wakeFilter);
+          const batchSuppressedIds = new Set(batchProjection.suppressedUpstreamErrorEventIds);
+          const batchOutcomes = batchProjection.outcomes.filter(
             (outcome) =>
               outcome.eventId > state.failedWakeThroughEventId &&
               !state.presentedEventIds.has(outcome.eventId) &&
@@ -439,33 +771,73 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
             return;
           }
           const current = batchOutcomes;
-          const deliveredBatch: DeliveredBatch = {
-            abortedByUser: false,
-            assistantFinalSucceeded: false,
-            events: batchEvents.filter((event) =>
-              batchOutcomes.some((outcome) => outcome.eventId === event.id),
-            ),
-            hasSubstantiveWork: false,
-            invalidated: false,
-            ownerTerminalId,
-            herdsmanTriggered: true,
-          };
+          const incomingEvents = batchEvents.filter((event) =>
+            batchOutcomes.some((outcome) => outcome.eventId === event.id),
+          );
+          const previousBatch = state.deliveredBatch;
           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.
+          const orchestratorBusy = ctx.isIdle?.() === false;
+          const wakeContent = formatAgentOutcomeUpdates(batchOutcomes);
           try {
             pi.sendMessage?.(
               {
-                content: formatAgentOutcomeUpdates(batchOutcomes),
+                content: wakeContent,
                 customType: "herdsman-wake-context",
-                details: { eventIds: batchEvents.map((event) => event.id) },
+                // Suppressed upstream errors are dropped from the injected
+                // context, but every other pending id stays listed so the
+                // evidence trail for the decision still names what was pending.
+                details: {
+                  eventIds: batchEvents
+                    .filter((event) => !batchSuppressedIds.has(event.id))
+                    .map((event) => event.id),
+                },
                 display: false,
               },
-              { deliverAs: "followUp", triggerTurn: true },
+              orchestratorBusy
+                ? { deliverAs: "followUp", triggerTurn: false }
+                : { deliverAs: "followUp", triggerTurn: true },
             );
+            // 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
             // keeps an injection failure eligible for daemon redelivery.
-            state.deliveredBatch = deliveredBatch;
+            //
+            // The batch is the delivery queue plus this injection: previously
+            // unconfirmed events are merged (never replaced) so that a forced
+            // release always leaves both the old and the new events deliverable
+            // and acknowledgeable in id order. The turn-consumption flags of a
+            // still-running previous batch are carried over, because they
+            // describe whether the content already reached the orchestrator.
+            //
+            // `hasSubstantiveWork` is the sole gate that decides whether an
+            // ownership/scope change may abort the in-flight turn (see loseRole
+            // and resetForScopeChange), and aborting is only ever allowed for a
+            // *pure* Herdsman wake turn. A busy orchestrator gets the batch as a
+            // non-triggering queued follow-up, which rides the user's own turn:
+            // that turn is not a Herdsman wake turn, so it must never be aborted
+            // on our behalf and the flag is set here.
+            state.deliveredBatch = {
+              abortedByUser: previousBatch?.abortedByUser ?? false,
+              assistantFinalSucceeded: previousBatch?.assistantFinalSucceeded ?? false,
+              events: mergeUnackedDelivered(incomingEvents),
+              hasSubstantiveWork: orchestratorBusy || (previousBatch?.hasSubstantiveWork ?? false),
+              invalidated: false,
+              ownerTerminalId,
+              herdsmanTriggered: true,
+            };
             state.wakeRequested = false;
             state.wakeRequestedThroughEventId = 0;
             // Record the presentation so a reclaim redelivery of the same id is
@@ -522,7 +894,13 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       // A transient disconnect (reconnect) keeps the presentation guard so an
       // event already presented in this scope session is not presented again;
       // only a genuine role/scope loss or shutdown resets it.
-      if (!options.preservePresented) state.presentedEventIds.clear();
+      if (!options.preservePresented) {
+        state.presentedEventIds.clear();
+        // The delivery queue dies with the presentation guard: once the guard is
+        // gone the daemon's pending events can be presented (and acknowledged)
+        // again, so keeping the old queue would only risk a stale id.
+        state.unackedDelivered.clear();
+      }
       state.reconnectingFromOn = false;
       setHerdsmanUi(ctx);
     };
@@ -553,6 +931,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       state.failedWakeThroughEventId = 0;
       state.pendingEvents = [];
       state.presentedEventIds.clear();
+      state.unackedDelivered.clear();
       setHerdsmanUi(ctx);
     };
 
@@ -670,6 +1049,7 @@ 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.
@@ -911,25 +1291,16 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       loseRole(activeContext);
       state.deliveredBatch = undefined;
       state.presentedEventIds.clear();
+      state.unackedDelivered.clear();
       state.client?.close();
       state.client = undefined;
       activeContext = undefined;
     });
 
     const assistantMessageText = (message: Record<string, unknown>): string => {
-      const content = message.content;
-      if (typeof content === "string") return content;
-      if (!Array.isArray(content)) return "";
-      const parts: string[] = [];
-      for (const block of content) {
-        if (typeof block === "string") {
-          if (block.length > 0) parts.push(block);
-          continue;
-        }
-        const value = record(block);
-        if (typeof value.text === "string" && value.text.length > 0) parts.push(value.text);
-      }
-      return parts.join("\n");
+      const text = textFromContent(message.content);
+      if (text === null) return "";
+      return sanitizeText(text).text;
     };
 
     // Turn completion signal: after Pi's own final assistant message has been
@@ -945,13 +1316,15 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       const completion = (async () => {
         const check = await confirmSessionWrite({ expectedText, path: sessionPath });
         try {
-          await client.request("agent.turn.completed", {
+          const params: Record<string, unknown> = {
             confirmed: check.confirmed,
             herdrSessionName: scope.herdrSessionName,
             paneId: scope.paneId,
             terminalId: scope.terminalId,
             workspaceId: scope.workspaceId,
-          });
+          };
+          if (expectedText) params.expectedText = expectedText;
+          await client.request("agent.turn.completed", params);
         } catch (error) {
           logHerdsmanPi(
             "warn",
@@ -1002,23 +1375,43 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
 
     pi.on("context", (event: { messages: PiAgentMessage[] }) => {
       const messages = event.messages.filter((message) => !isNormalHerdsmanContext(message));
+      const additions: PiAgentMessage[] = [];
       const snapshot = state.pinnedContext;
-      if (!snapshot || snapshot.agents.length === 0) return { messages };
-      return {
-        messages: [
-          ...messages,
-          {
-            content: formatHiddenAgentContext({
-              agents: snapshot.agents,
-              workspaceId: snapshot.workspaceId,
-            }),
-            customType: "herdsman-agent-context",
-            display: false,
-            role: "custom",
-            timestamp: Date.now(),
-          },
-        ],
-      };
+      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).
+      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] };
     });
 
     pi.on("agent_settled", async (_event: unknown, ctx: PiContext) => {
@@ -1043,10 +1436,41 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
       const finishBatch = () => {
         state.ackInFlight = false;
         state.wakeDeferredUntilSettled = false;
+        state.wakeDeferredSince = undefined;
+        state.wakeForcedRelease = false;
+        state.wakeContext = undefined;
         setHerdsmanUi(ctx);
         scheduleWake(ctx);
       };
 
+      // The delivery queue — not the injection snapshot — is what gets
+      // acknowledged: it holds every event handed to Pi that is still
+      // unconfirmed (a release merges batches instead of replacing them), is
+      // id-ascending, and an id leaves it only when the daemon accepts it.
+      //
+      // An event whose own acknowledgement already failed is left out here: it is
+      // never retried by this path (the daemon's cursor advance sweeps it, and a
+      // retry would reset its attempt/backoff accounting), but it stays in the
+      // queue until that cursor or a scope reset confirms it. A failed or
+      // dead-lettered acknowledgement thus never depends on the timing of the
+      // release to stay recoverable.
+      //
+      // Restricting to a *live* row with `attempts === 0` has two holes on
+      // purpose. `?? 0` covers an event the live projection no longer holds at
+      // all (the server stopped listing it, or `failedWakeThroughEventId`
+      // filters it out): the projection cannot tell us it already failed, so the
+      // event gets one more attempt — a deliberate self-healing opportunity that
+      // then accumulates on the queue copy's counter and can reach
+      // MAX_ACK_ATTEMPTS instead of restarting at 1 every round.
+      const ackable = unackedDeliveredAscending().filter(
+        (event) =>
+          (state.pendingEvents.find((pending) => pending.id === event.id)?.attempts ?? 0) === 0,
+      );
+      if (ackable.length === 0) {
+        finishBatch();
+        return;
+      }
+
       if (
         (!batch.assistantFinalSucceeded && !batch.abortedByUser) ||
         batch.invalidated ||
@@ -1059,116 +1483,7 @@ export function createHerdsmanPiExtension(options: ExtensionOptions = {}) {
         return;
       }
 
-      for (const event of batch.events) {
-        try {
-          const ackResponse = (await state.client.request("agent.notifications.ack", {
-            eventId: event.id,
-          })) as { ackedEventId?: number; state?: { ackedEventId?: number } };
-          pruneAcknowledgedEvents(ackResponse?.ackedEventId ?? ackResponse?.state?.ackedEventId);
-          state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
-          // The id intentionally stays in presentedEventIds: the event was
-          // already presented this session and must not be injected again even
-          // if the daemon replays it (for example after a reconnect
-          // redelivery). The set is cleared only on role loss, scope change,
-          // or shutdown.
-          state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
-          setHerdsmanUi(ctx);
-        } catch (error) {
-          const failureCode = ackFailureCode(error);
-          const classification = classifyAckFailure(error);
-          const attempts = (event.attempts ?? 0) + 1;
-          const attemptedAt = Date.now();
-          const updatedEvent = {
-            ...event,
-            attempts,
-            lastAttemptAt: attemptedAt,
-            lastFailureCode: failureCode,
-          };
-          state.pendingEvents = state.pendingEvents.map((pending) =>
-            pending.id === event.id ? updatedEvent : pending,
-          );
-
-          if (classification === "terminal") {
-            state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
-            state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
-            if (/Only the current orchestrator can acknowledge notifications/i.test(failureCode)) {
-              state.isOrchestrator = false;
-              logHerdsmanPi(
-                "warn",
-                `[herdsman-pi] lost orchestrator ownership while acknowledging event ${event.id}`,
-              );
-            } else {
-              logHerdsmanPi(
-                "warn",
-                `[herdsman-pi] terminal acknowledgement failure eventId=${event.id} attempts=${attempts} code=${failureCode}`,
-              );
-            }
-            setHerdsmanUi(ctx);
-            continue;
-          }
-
-          if (attempts >= MAX_ACK_ATTEMPTS) {
-            state.pendingEvents = state.pendingEvents.filter((pending) => pending.id !== event.id);
-            state.failedWakeThroughEventId = Math.max(state.failedWakeThroughEventId, event.id);
-            logHerdsmanPi(
-              "warn",
-              `[herdsman-pi] acknowledgement moved to dead-letter eventId=${event.id} attempts=${attempts} code=${failureCode}`,
-            );
-            setHerdsmanUi(ctx);
-            continue;
-          }
-
-          if (classification === "resync") {
-            const resyncEvent = {
-              ...updatedEvent,
-              nextAttemptAt: attemptedAt + ackBackoffMs(attempts),
-            };
-            state.pendingEvents = state.pendingEvents.map((pending) =>
-              pending.id === event.id ? resyncEvent : pending,
-            );
-            try {
-              const response = (await state.client.request(
-                "agent.orchestrator.get",
-                {},
-              )) as ConnectionStateResponse;
-              // Refresh pending data without applying the full connection response: that
-              // helper schedules a new wake, which would make this failed batch race
-              // with the current settlement and can replay an earlier event. The
-              // failed event remains pending and the next wake is scheduled by
-              // finishBatch(), so this round performs no additional acknowledgements.
-              addPendingEvents(response.events ?? [], ctx);
-              pruneAcknowledgedEvents(response.state?.ackedEventId ?? response.ackedEventId);
-              setHerdsmanUi(ctx);
-            } catch (resyncError) {
-              logHerdsmanPi(
-                "warn",
-                `[herdsman-pi] acknowledgement resync failed eventId=${event.id} attempts=${attempts} code=${ackFailureCode(resyncError)}`,
-              );
-            }
-            // The event stays pending with a backoff so the ack cursor can
-            // sweep it later, but it was already presented this session and is
-            // not re-presented: presentedEventIds keeps the guard until scope
-            // reset. Continue so one failed event does not block the rest of
-            // the batch.
-            continue;
-          }
-
-          state.pendingEvents = state.pendingEvents.map((pending) =>
-            pending.id === event.id
-              ? { ...pending, nextAttemptAt: attemptedAt + ackBackoffMs(attempts) }
-              : pending,
-          );
-          ctx.ui.notify?.(
-            "Herdsman couldn’t acknowledge agent updates · updates remain pending",
-            "warning",
-          );
-          setHerdsmanUi(ctx);
-          // The event stays pending with a backoff so the ack cursor can sweep
-          // it later, but it was already presented this session and is not
-          // re-presented: presentedEventIds keeps the guard until scope reset.
-          continue;
-        }
-      }
+      await acknowledgeEventIds(ackable, { notify: true }, ctx);
       finishBatch();
     });
 
@@ -1255,6 +1570,7 @@ export function formatHiddenAgentUpdates(events: AgentEventWireRecord[]): string
 function isNormalHerdsmanContext(message: PiAgentMessage): boolean {
   return (
     message.customType === "herdsman-agent-context" ||
+    message.customType === "herdsman-wake-queued" ||
     contentIncludesMarker(message.content, "[HERDSMAN AGENT CONTEXT]")
   );
 }