@signalridge/pi-workflows 1.10.1 → 1.11.1

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # Changelog
 
+## 1.11.1
+### Patch Changes
+
+- da9ed0f: - Reject rename hardlink aliases and retargeted queue identities before writes; support all LSP newline styles and identify possibly partially modified targets on write failure.
+  - Fence pending physical Plan model mutations at cancellable navigation/replacement gates, reconcile handoffs by native selection chronology, and scope thinking-only restoration to its originating model.
+  - Compose Goal guidance through an owned structured prompt section. Resolve overflow usage against physical response models and invalidate stale size evidence after persisted context edits in each independent continuation helper.
+  - Persist queued Rules reminders/offers only at authenticated native admission, match file URL paths, and provide usable rule-file references when read_rule is unavailable.
+  - Inherit nested workers' thinking from their immediate spawning session while preserving explicit policy precedence.
+  - Refresh skill discovery for custom Analytics runs without consuming pending user attribution, and finalize successful Codex diagnostics only after UI cleanup and the final owned result fence.
+- da9ed0f: Restore workflow keyword and standing `/effort high|ultra` authorization on Pi 1.2 and later. Those hosts report the session as busy while its own run starts, so the hidden guidance that authorizes the `workflow` tool was silently dropped for every idle prompt. The idle check now applies only on hosts that do not identify the starting run, and runs started by a custom message never consume an armed prompt.
+- da9ed0f: Stop settled workflow results from waking a session whose context overflowed the model window. While the latest response on the branch is a context overflow with no compaction after it, results are still delivered and acknowledged as context but no wake is sent, and one warning per overflow episode asks to run `/compact` (or `/codex-compact` when installed) or start a new session. A compaction or a later successful response restores normal wakes. Previously each wake resent the same over-window context and failed again. The package now declares `@earendil-works/pi-ai` as a host peer dependency.
+- Updated dependencies [da9ed0f]
+  - @signalridge/pi-ui@1.4.1
+
+## 1.11.0
+### Minor Changes
+
+- c639660: Keep pending completion reminders cancellable until parent boundaries and consume deliberately read terminal results instead of replaying stale notifications.
+  
+  Subagents selectively adapt tintinweb/pi-subagents #388's completion outbox, merge eligible batches into one steering message, and retain explicit groups, attempt ownership, and Claude Code notification XML. Successful terminal result reads suppress that attempt's pending reminder; unread failures remain eligible.
+  
+  Background terminal log or explicit-ID status reads consume only exit notices, preserving unread monitor matches and future completion after running reads. Workflow get/status adds explicit `consume: true` with a branch-visible acknowledgement receipt, without consuming ordinary inspections or suppressing resumed executions. Already accepted transcript messages and historical results remain unchanged.
+  
+  Stopped workflow state retains the accepted terminal event timestamp across slow appends and restore. Background reads prepare job data before committing exit consumption, and post-commit status-rendering failures cannot turn a successful read into an error. Early smart-group completions retain finalized membership separately from immutable results, with partial-group labels rechecked at handoff.
+
 ## 1.10.1
 ### Patch Changes
 

package/README.md

@@ -269,6 +269,17 @@ The passive progress panel uses a terminal-height row budget, prioritizes live c
 
 ### Background result notifications
 
+To explicitly read and acknowledge a terminal result, call
+`workflow_control({ action: "get", run_id: "...", consume: true })` (`status`
+is an alias). A `notificationConsumed: true` receipt means an acknowledgement
+was observed on the active branch and the pending reminder was consumed.
+Ordinary `get`/`status`, `list`, running results, and cancelled/stale reads do
+not consume future completion. Consumption is scoped to that execution; a
+later resumed execution remains eligible. Identity comes from the durable terminal
+journal entry, not a runtime counter that restarts on restore. Older markers
+without that evidence are not retroactively consumed. Receipts do not delete run history
+or retract messages already handed to Pi.
+
 Completed background runs are buffered in branch-local pending-delivery markers
 (up to 256, expiring after seven days). Notifications wait for an owned, idle
 session with no queued input, input preparation, compaction, or navigation in
@@ -295,6 +306,14 @@ awaits while navigation or shutdown retires the owner, the obsolete
 extension-sourced wake is handled without starting a turn. Interactive/RPC
 input and other extensions' messages are not consumed by this guard.
 
+No wake is sent while the session's latest meaningful response overflowed the model's
+context window and no compaction followed it: that turn would resend the same
+over-window context and fail again. Results are still delivered and acknowledged
+as context, and one warning per overflow episode asks to run `/compact` (or
+`/codex-compact` when installed) or start a new session. A compaction or a later
+successful response restores normal wakes. Aborted responses and transient errors
+(including HTTP 503 and rate limits) do not prove context recovery.
+
 This is a handoff check, not a navigation lock: public hooks cannot fence an
 arbitrary later async input or preparation handler that navigates after our
 input hook has accepted the wake. Earlier transforms must preserve the private

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@signalridge/pi-workflows",
-  "version": "1.10.1",
+  "version": "1.11.1",
   "description": "Deterministic JavaScript orchestration workflows backed by pi-subagents managed spawning.",
   "type": "module",
   "license": "MIT",
@@ -15,6 +15,7 @@
     "lifecycle": "stable"
   },
   "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
     "@earendil-works/pi-coding-agent": "*",
     "@earendil-works/pi-tui": "*",
     "@signalridge/pi-subagents": ">=1.9.0",
@@ -22,7 +23,7 @@
   },
   "dependencies": {
     "@signalridge/pi-subagents-protocol": "^1.6.0",
-    "@signalridge/pi-ui": "^1.4.0",
+    "@signalridge/pi-ui": "^1.4.1",
     "acorn": "^8.16.0"
   },
   "pi": {

package/skills/workflow-authoring/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-authoring
 description: Design, write, review, and debug Pi JavaScript workflows that coordinate multiple subagents. Use when a request needs named dependencies, bounded fan-out, per-item pipelines, quality gates, saved or nested workflows, pause/resume, or workflow progress; do not use it merely to run an existing named workflow.
 metadata:
-  version: "1.10.1"
+  version: "1.11.1"
 ---
 
 # Workflow authoring

package/skills/workflow-authoring/references/capabilities.md

@@ -2,7 +2,7 @@
 # Workflow capability index
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.10.1`
+Contract content / skill / extension: `1.11.1`
 
 This compact generated index covers supported runtime globals and workflow-tool inputs. For constraints, compatibility behavior, internal boundaries, and dynamic-reference ownership, follow the [exhaustive generated facts](capability-details.md).
 

package/skills/workflow-authoring/references/capability-details.md

@@ -2,7 +2,7 @@
 # Exhaustive workflow capability facts
 
 Contract format: `2.0.0`<br>
-Contract content / skill / extension: `1.10.1`
+Contract content / skill / extension: `1.11.1`
 
 Every exact fact below is projected from the installed extension's capability contract. Explanatory judgment belongs in the hand-written references next to this file.
 

package/skills/workflow-patterns/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-patterns
 description: Choose and run one of Pi's built-in multi-agent workflows for research, adversarial review, code review, multi-perspective analysis, or codebase auditing. Use when the request matches a named pattern; use workflow-authoring instead for a new script or custom topology.
 metadata:
-  version: "1.10.1"
+  version: "1.11.1"
 ---
 
 # Built-in workflow patterns

package/skills/workflow-review/SKILL.md

@@ -2,7 +2,7 @@
 name: workflow-review
 description: Audit an existing Pi JavaScript workflow for topology, prompt/data flow, limits, failure handling, cancellation, resume safety, and publication compatibility. Use when reviewing or debugging a workflow script or saved run; do not use to run a standard named workflow.
 metadata:
-  version: "1.10.1"
+  version: "1.11.1"
 ---
 
 # Workflow review

package/src/arming.ts

@@ -235,15 +235,21 @@ export class WorkflowTurnArming {
   }
 
   consume(event: BeforeAgentStartEvent, ctx: ExtensionContext): void {
+    // Pi 1.2+ also announces idle custom-message runs; only a user prompt can
+    // carry the armed input, and earlier hosts never reached here for them.
+    if (event.messageType === "custom") return;
     const pending = this.pending;
     const ambiguous = this.ambiguous;
     this.pending = undefined; // one-use, also for mismatched/consumed prompts
     this.current = undefined;
     try {
+      // Pi 1.2+ (which reports messageType) counts the session busy while its
+      // own run prepares and queues concurrent sends into it. Earlier hosts were
+      // still idle here, so a busy session meant another run had started.
       if (
         ambiguous ||
         !pending?.content ||
-        !ctx.isIdle() ||
+        (event.messageType === undefined && !ctx.isIdle()) ||
         event.prompt !== pending.text ||
         inputKey("", event.images) !== pending.images ||
         ctx.sessionManager.getSessionId() !== pending.sessionId ||

package/src/context-overflow.ts

@@ -0,0 +1,98 @@
+/**
+ * Overflow-aware waking. After a response overflowed the model's context window and no
+ * compaction followed, a turn this extension starts resends the same over-window context and
+ * fails again, and each failure is still a billed request. Wakes are held until a compaction
+ * or a later successful response ends the episode.
+ */
+import { isContextOverflow } from "@earendil-works/pi-ai";
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+
+type EpisodeContext = Pick<ExtensionContext, "sessionManager"> & {
+  modelRegistry?: { find(provider: string, model: string): { contextWindow?: number } | undefined };
+};
+export type OverflowContext = EpisodeContext & Pick<ExtensionContext, "hasUI" | "ui">;
+
+/**
+ * The first overflowed response of the current episode: the latest meaningful response on the
+ * branch overflowed and neither compaction nor a successful response followed. Aborted and
+ * transient error responses say nothing about the context size and are skipped.
+ */
+export function overflowEpisode(ctx: EpisodeContext): string | undefined {
+  try {
+    const branch = ctx.sessionManager.getBranch();
+    const projection = ctx.sessionManager.buildSessionProjection?.();
+    const projected = projection
+      ? new Set(
+          projection.entries
+            .filter((entry) => entry.messages.some((message) => message.role === "assistant"))
+            .map((entry) => entry.sourceEntry.id),
+        )
+      : undefined;
+    let contextEdited = false;
+    let episode: string | undefined;
+    for (let index = branch.length - 1; index >= 0; index--) {
+      const entry = branch[index];
+      if (entry.type === "compaction") break;
+      if (entry.type === "context_edit") {
+        contextEdited = true;
+        continue;
+      }
+      if (entry.type !== "message" || entry.message.role !== "assistant" || entry.message.stopReason === "aborted")
+        continue;
+      const explicit = entry.message.stopReason === "error" && isContextOverflow(entry.message);
+      if (entry.message.stopReason === "error" && !explicit) continue;
+      // Pi can omit a failed recovery attempt before a cancelled compaction.
+      // That alone does not repair its oversized input; invalidate usage only.
+      if (!explicit && projected && !projected.has(entry.id)) break;
+      const contextWindow = ctx.modelRegistry?.find(entry.message.provider, entry.message.model)?.contextWindow;
+      if (!explicit && (contextEdited || !isContextOverflow(entry.message, contextWindow))) {
+        if (entry.message.stopReason === "error") continue;
+        break;
+      }
+      episode = entry.id;
+    }
+    return episode;
+  } catch {
+    // A replaced session's context is stale; never hold a wake on a guess.
+    return undefined;
+  }
+}
+
+export function overflowNotice(held: string, codexCompact: boolean): string {
+  return (
+    `Context exceeds the model's window; ${held} without starting a turn. ` +
+    `Run ${codexCompact ? "/compact or /codex-compact" : "/compact"}, or start a new session.`
+  );
+}
+
+/** One guard per extension instance, so the user sees one notice per overflow episode. */
+export class OverflowWakeGuard {
+  private noticed: string | undefined;
+  constructor(
+    private readonly pi: Pick<ExtensionAPI, "getCommands">,
+    private readonly held: string,
+  ) {}
+
+  /** True while a turn must not start; the first hold of an episode tells the user why. */
+  holds(ctx: OverflowContext | undefined): boolean {
+    const episode = ctx ? overflowEpisode(ctx) : undefined;
+    if (!ctx || episode === undefined) return false;
+    if (episode !== this.noticed) {
+      this.noticed = episode;
+      try {
+        if (ctx.hasUI) ctx.ui.notify(overflowNotice(this.held, this.hasCommand("codex-compact")), "warning");
+      } catch {
+        // A disposed UI must not block the delivery that follows.
+      }
+    }
+    return true;
+  }
+
+  private hasCommand(name: string): boolean {
+    try {
+      return this.pi.getCommands().some((command) => command.name === name);
+    } catch {
+      return false;
+    }
+  }
+}

package/src/engine.ts

@@ -2614,7 +2614,9 @@ export class WorkflowEngine {
       run.callStatus[terminal.nodeId] = "stopped";
     }
     run.status = "stopped";
-    run.updatedAt = Date.now();
+    // Publish the accepted event's identity, just like other terminal paths.
+    // A slow append must not detach the live state from its durable receipt.
+    run.updatedAt = event.timestamp;
     state.presentation.settle(run.status);
     this.notifyInspection(state);
     if (current()) this.notifyTerminal(state);

package/src/index.ts

@@ -8,6 +8,7 @@ import { Type } from "@sinclair/typebox";
 import { DEFAULT_TRIGGER_WORD, hasTriggerWord, WORKFLOW_ARMING_MESSAGE_TYPE, WorkflowTurnArming } from "./arming.js";
 import { BUILTIN_WORKFLOWS, validateBuiltinArgs } from "./builtins.js";
 import { type CommandResult, resolveCodeReviewScope } from "./code-review-scope.js";
+import { OverflowWakeGuard } from "./context-overflow.js";
 import { type ScriptStartOptions, type ScriptStartResult, WorkflowEngine, WorkflowWaitAbortedError } from "./engine.js";
 import { JOURNAL_ENTRY_TYPE, type SessionEntryLike } from "./journal.js";
 import {
@@ -94,6 +95,12 @@ const ControlSchema = Type.Object(
       { description: "Control action" },
     ),
     run_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
+    consume: Type.Optional(
+      Type.Boolean({
+        description:
+          "With get/status only: explicitly acknowledge a reviewed terminal result and suppress its pending completion reminder. Running results and ordinary inspections are not consumed.",
+      }),
+    ),
     // Accept camelCase and legacy workflow_run_id for interop with pi-dynamic-workflows docs
     runId: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
     workflow_run_id: Type.Optional(Type.String({ minLength: 1, maxLength: 128 })),
@@ -344,6 +351,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let lifecycleGeneration = 0;
   let deliveryGeneration = 0;
   const deliveryObservers = new Map<string, string>();
+  const observedExecutions = new Map<string, string>();
   let handledTreeEvent: unknown;
   let journalBranchAnchor: string | null | undefined;
   let protocolAbortController: AbortController | undefined;
@@ -354,6 +362,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   let keywordTriggerEnabled = workflowSettings.keywordTriggerEnabled;
   /** Public sends are void: acceptance is checked against the owning branch. */
   let deliveryContext: ExtensionContext | undefined;
+  const overflowWakes = new OverflowWakeGuard(pi, "workflow results are added to the conversation");
   let deliveryTimer: ReturnType<typeof setTimeout> | undefined;
   let inputPreparing = false;
   const turnArming = new WorkflowTurnArming();
@@ -370,7 +379,10 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     { generation: number; context: ExtensionContext; engine: WorkflowEngine; anchor: string | null | undefined }
   >();
   /** Pending deliveries for completed runs, including durable recovery (A10). */
-  const pendingDeliveryMarkers = new Map<string, { text: string; timestamp: number }>();
+  const pendingDeliveryMarkers = new Map<
+    string,
+    { text: string; timestamp: number; executionGeneration?: number; completionId?: string }
+  >();
   const PENDING_DELIVERY_TYPE = "pi-workflows:pending-delivery";
   const PENDING_DELIVERY_ACK_TYPE = "pi-workflows:pending-delivery-ack";
   const MAX_PENDING_DELIVERIES = 256;
@@ -426,6 +438,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     workflowUiSurfaceId = randomUUID();
     deliveryGeneration++;
     deliveryObservers.clear();
+    observedExecutions.clear();
     turnArming.retire();
     wakeAdmissions.clear();
     if (deliveryTimer) clearTimeout(deliveryTimer);
@@ -880,7 +893,7 @@ export default function piWorkflows(pi: ExtensionAPI): void {
           });
           return new Text(theme.fg("dim", expanded ? text.slice(0, 8_000) : text.slice(0, 1_000)), 0, 0);
         },
-        async execute(_toolCallId, params, _signal, _onUpdate, _ctx) {
+        async execute(_toolCallId, params, signal, _onUpdate, ctx) {
           try {
             const rawAction = params.action as string;
             const action = (rawAction === "status" ? "get" : rawAction) as
@@ -895,7 +908,22 @@ export default function piWorkflows(pi: ExtensionAPI): void {
             }
             const runId = normalizeControlRunId(params as unknown as Record<string, unknown>);
             const workflowEngine = currentEngine();
+            if (params.consume && action !== "get") throw new Error("consume is supported only with get/status.");
+            const execution = runId ? workflowEngine.getState(runId)?.executionGeneration : undefined;
+            const ownerGeneration = deliveryGeneration;
+            const completionId =
+              params.consume && action === "get" && runId ? completionReceipt(workflowEngine, runId) : undefined;
             const result = await workflowEngine.control(action, runId);
+            signal?.throwIfAborted();
+            if (params.consume) {
+              const notificationConsumed =
+                !!runId &&
+                execution !== undefined &&
+                completionId !== undefined &&
+                consumeReviewedResult(workflowEngine, runId, execution, completionId, ownerGeneration, ctx);
+              const receipt = { ...result, notificationConsumed };
+              return textResult(JSON.stringify(receipt), receipt);
+            }
             return textResult(JSON.stringify(result), result);
           } catch (error: unknown) {
             return textResult(error instanceof Error ? error.message : String(error));
@@ -1548,9 +1576,92 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     });
   };
 
-  const rememberPendingDelivery = (runId: string, text: string, timestamp = Date.now()): void => {
-    if (!runId || timestamp + PENDING_DELIVERY_TTL_MS < Date.now()) return;
-    pendingDeliveryMarkers.set(runId, { text: text.slice(0, 8_000), timestamp });
+  /** Native journal identity survives restore; runtime generation counters do not. */
+  function completionReceipt(workflowEngine: WorkflowEngine, runId: string): string | undefined {
+    const run = workflowEngine.getState(runId)?.run;
+    if (!run || !["completed", "failed", "stopped"].includes(run.status)) return;
+    try {
+      const branch = deliveryContext?.sessionManager.getBranch() ?? [];
+      for (let index = branch.length - 1; index >= 0; index--) {
+        const entry = branch[index];
+        if (entry.type !== "custom" || entry.customType !== JOURNAL_ENTRY_TYPE) continue;
+        const data = entry.data as Record<string, unknown> | undefined;
+        if (
+          data?.runId === runId &&
+          data.status === run.status &&
+          data.timestamp === run.updatedAt &&
+          (data.kind === "workflow_transition" || data.kind === "terminal_recovery")
+        )
+          return entry.id;
+      }
+    } catch {
+      // Unavailable branch evidence cannot acknowledge a result.
+    }
+  }
+
+  function consumeReviewedResult(
+    workflowEngine: WorkflowEngine,
+    runId: string,
+    execution: number,
+    completionId: string,
+    generation: number,
+    ctx: ExtensionContext,
+  ): boolean {
+    const current = () =>
+      generation === deliveryGeneration &&
+      workflowEngine === engine &&
+      ctx.sessionManager === deliveryContext?.sessionManager &&
+      ownsDeliveryBranch() &&
+      workflowEngine.getState(runId)?.executionGeneration === execution &&
+      completionReceipt(workflowEngine, runId) === completionId;
+    if (!current()) return false;
+    // An older marker without a durable receipt cannot be attributed to the
+    // reviewed execution. Preserve it rather than silently migrating history.
+    if (pendingDeliveryMarkers.has(runId) && pendingDeliveryMarkers.get(runId)?.completionId === undefined)
+      return false;
+    if (observedExecutions.get(runId) === completionId) return true;
+    try {
+      const previous = new Set(ctx.sessionManager.getBranch().map((entry) => entry.id));
+      pi.appendEntry(PENDING_DELIVERY_ACK_TYPE, {
+        runId,
+        executionGeneration: execution,
+        completionId,
+        observed: true,
+        timestamp: Date.now(),
+      });
+      if (!current()) return false;
+      const accepted = ctx.sessionManager.getBranch().some((entry) => {
+        if (previous.has(entry.id) || entry.type !== "custom" || entry.customType !== PENDING_DELIVERY_ACK_TYPE)
+          return false;
+        const data = entry.data as Record<string, unknown> | undefined;
+        return data?.runId === runId && data.completionId === completionId && data.observed === true;
+      });
+      if (!accepted) return false;
+      advanceDeliveryAnchor();
+      observedExecutions.set(runId, completionId);
+      while (observedExecutions.size > MAX_PENDING_DELIVERIES)
+        observedExecutions.delete(observedExecutions.keys().next().value as string);
+      if (pendingDeliveryMarkers.get(runId)?.completionId === completionId) pendingDeliveryMarkers.delete(runId);
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  const rememberPendingDelivery = (
+    runId: string,
+    text: string,
+    timestamp = Date.now(),
+    executionGeneration?: number,
+    completionId?: string,
+  ): void => {
+    if (
+      !runId ||
+      timestamp + PENDING_DELIVERY_TTL_MS < Date.now() ||
+      (completionId !== undefined && observedExecutions.get(runId) === completionId)
+    )
+      return;
+    pendingDeliveryMarkers.set(runId, { text: text.slice(0, 8_000), timestamp, executionGeneration, completionId });
     for (const [id, marker] of pendingDeliveryMarkers) {
       if (marker.timestamp + PENDING_DELIVERY_TTL_MS < Date.now()) pendingDeliveryMarkers.delete(id);
     }
@@ -1582,6 +1693,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       !["completed", "failed", "stopped"].includes(run.status)
     )
       return;
+    const completionId = completionReceipt(workflowEngine, runId);
+    if (completionId !== undefined && observedExecutions.get(runId) === completionId) return;
     const header = `Workflow ${run.runId} ${run.status}`;
     const state = workflowEngine.getState(runId);
     const finalResult = state?.result ?? run.finalResult;
@@ -1592,10 +1705,12 @@ export default function piWorkflows(pi: ExtensionAPI): void {
         : `result:\n${typeof finalResult === "string" ? finalResult : (JSON.stringify(finalResult, null, 2) ?? String(finalResult))}`);
     const text = `${header}: ${body}`;
     if (!ownsDeliveryBranch()) return;
-    rememberPendingDelivery(runId, text);
+    rememberPendingDelivery(runId, text, Date.now(), executionGeneration, completionId);
     try {
       pi.appendEntry(PENDING_DELIVERY_TYPE, {
         runId,
+        executionGeneration,
+        completionId,
         text: text.slice(0, 8_000),
         status: run.status,
         timestamp: Date.now(),
@@ -1633,22 +1748,37 @@ export default function piWorkflows(pi: ExtensionAPI): void {
   };
   const hydratePendingDeliveries = (entries: SessionEntryLike[]): void => {
     pendingDeliveryMarkers.clear();
+    observedExecutions.clear();
     for (const entry of entries) {
       const shaped = entry as { type?: unknown; customType?: unknown; data?: unknown };
       if (shaped.type !== "custom") continue;
       const data = shaped.data as Record<string, unknown> | undefined;
       if (typeof data?.runId !== "string") continue;
-      if (shaped.customType === PENDING_DELIVERY_ACK_TYPE) pendingDeliveryMarkers.delete(data.runId);
-      else if (shaped.customType === PENDING_DELIVERY_TYPE && typeof data.text === "string") {
+      if (shaped.customType === PENDING_DELIVERY_ACK_TYPE) {
+        // Explicit reads acknowledge exactly one durable terminal receipt.
+        // Ordinary delivery ACKs still acknowledge the actual handed-off marker.
+        if (
+          data.observed !== true ||
+          (typeof data.completionId === "string" &&
+            pendingDeliveryMarkers.get(data.runId)?.completionId === data.completionId)
+        )
+          pendingDeliveryMarkers.delete(data.runId);
+      } else if (shaped.customType === PENDING_DELIVERY_TYPE && typeof data.text === "string") {
         rememberPendingDelivery(
           data.runId,
           data.text,
           typeof data.timestamp === "number" ? data.timestamp : Date.now(),
+          typeof data.executionGeneration === "number" ? data.executionGeneration : undefined,
+          typeof data.completionId === "string" ? data.completionId : undefined,
         );
       }
     }
   };
   const flushPendingDeliveries = (): void => {
+    for (const [runId, marker] of pendingDeliveryMarkers) {
+      if (marker.completionId !== undefined && observedExecutions.get(runId) === marker.completionId)
+        pendingDeliveryMarkers.delete(runId);
+    }
     if (!canDeliver() || !deliveryContext || pendingDeliveryMarkers.size === 0) return;
     if (typeof pi.sendMessage !== "function" || typeof pi.sendUserMessage !== "function") return;
     const ctx = deliveryContext;
@@ -1680,7 +1810,8 @@ export default function piWorkflows(pi: ExtensionAPI): void {
     try {
       if (!isCurrent()) return;
       // Never use a custom-message triggerTurn: that skips input preparation
-      // and before_agent_start. The void API is NOT an acceptance promise.
+      // (and, before Pi 1.2, before_agent_start). The void API is NOT an
+      // acceptance promise.
       const missing = batch.filter(([runId]) => !persisted(runId));
       if (missing.length > 0)
         pi.sendMessage(
@@ -1714,7 +1845,9 @@ export default function piWorkflows(pi: ExtensionAPI): void {
       }
       // An earlier input hook can await while the same manager navigates. Keep
       // exact owner evidence until our input hook consumes this private wake.
-      if (isCurrent() && engine) {
+      // An overflowed parent would resend the same over-window context: the
+      // acknowledged results above wait for the next run instead.
+      if (isCurrent() && engine && !overflowWakes.holds(ctx)) {
         const wake = `${DELIVERY_WAKE_PREFIX}${randomUUID()}] ${DELIVERY_WAKE_TEXT}`;
         wakeAdmissions.set(wake, { generation, context: ctx, engine, anchor: deliveryBranchAnchor });
         while (wakeAdmissions.size > MAX_WAKE_ADMISSIONS) {