@sgtbeatdown/pi-tasks 0.1.14 → 0.1.16

package/README.md

@@ -140,16 +140,18 @@ try {
   });
 
   // a real application would consume the assignment and do the work here.
-  for (const delivery of await worker.receive()) {
-    await worker.acknowledgeRelayDelivery(delivery.cursor);
+  for (const item of await worker.receive()) {
+    if (item.kind === "relay") await worker.acknowledgeRelayDelivery(item.delivery.cursor);
   }
   await worker.submitIntent({
     taskId,
     type: "task.completed",
     payload: { summary: "the change adds task coordination" },
   });
-  for (const delivery of await parent.receive()) {
-    await parent.acknowledgeRelayDelivery(delivery.cursor);
+  // relay items carry peer mail; local items are the parent's own view of events it canonicalized.
+  for (const item of await parent.receive()) {
+    if (item.kind === "relay") await parent.acknowledgeRelayDelivery(item.delivery.cursor);
+    else parent.completeLocalPresentation(item.event.eventId);
   }
 
   console.log(parent.getTask(taskId)?.status); // completed
@@ -166,6 +168,10 @@ this demonstrates task coordination, not agent execution. both endpoints share o
 
 implement the exported [`TaskRelay` interface](src/task-protocol.ts) to connect endpoints, resolve targets, send envelopes, receive mail, and acknowledge individual deliveries. provide a separate `createTaskStore()` and `createTaskCore()` for each endpoint. `runTaskRelayConformance` is available to check a relay implementation.
 
+`receive()` returns items in order: `relay` items wrap a delivery you acknowledge with `acknowledgeRelayDelivery`, and `local` items carry an event the origin itself canonicalized, which you complete with `completeLocalPresentation` once presented.
+
+`createTaskCore({ timers })` accepts a `TaskTimers` clock for the delivery budget (deadline, retry slices, cooldowns), which lets tests run those bounds on virtual time; task records still use `clock`. an origin can move an active task off a target whose loss the relay reported with `reassignTask`; the [reference](docs/protocol-reference.md#memory-owned-lifecycle) covers its preconditions and why the default extension does not call it yet.
+
 your application owns polling, retries, timeout evaluation, delivery acknowledgments, and shutdown. it also owns how assignments reach an agent and how that agent runs them. the core alone does not install pi tools or wake a model.
 
 ## important limits

package/docs/protocol-reference.md

@@ -8,7 +8,7 @@ The [relay control API](https://github.com/almogdepaz/wolfpack/blob/main/docs/co
 
 ## endpoint-owned relay
 
-The default extension requires a compatible Wolfpack memory-owned server. It negotiates `volatile-v1` at `POST /api/task-relay/volatile-v1`. No transport opt-in flag is needed. The old durable relay adapter is removed, not retained as a compatibility mode.
+The default extension requires a compatible Wolfpack memory-owned server. It negotiates `volatile-v1` at `POST /api/task-relay/volatile-v1`. No transport opt-in flag is needed. The old durable relay adapter is removed, not retained as a compatibility mode. The transport keeps at most 8 requests in flight, with 2 more slots reserved for ACK/connect; further requests wait for a slot in FIFO order instead of failing locally. A waiter aborted by its caller has sent nothing and fails with a retryable `ABORTED`; `RELAY_CAPACITY` comes only from the server.
 
 Set `WOLFPACK_SESSION_NAME` for each Pi process. `WOLFPACK_PORT` defaults to `18790`; `WOLFPACK_SESSION_NAME` resolves the active Pi process to its relay endpoint. Read `taskEndpoint` from structured session creation/status and pass its opaque `{ relay, id }` unchanged. Never derive it from a name, terminal output or broker ID.
 
@@ -28,22 +28,35 @@ The `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`.
 
 ## history versus live state
 
-- Pi requests task-processing turns through its safe `deliverAs: "followUp"` queue. Pi session messages and tool calls/results preserve historical context. Non-waking receipts, parent ACKs and late-terminal facts are archived as `pi-tasks-event-record` custom entries before transport ACK, without waking the model. Received model-visible task events include the complete structured event in `pi-tasks-event` details, including results—not just a rendered summary.
+- Pi requests task-processing turns through its safe `deliverAs: "followUp"` queue. Pi session messages and tool calls/results preserve historical context. Parent ACKs, late-terminal facts and confirmed receiver-authored conversation echoes are archived as `pi-tasks-event-record` custom entries before transport ACK, without model insertion or wake. Received model-visible task events include the complete structured event in `pi-tasks-event` details, including results—not just a rendered summary.
 - Active tasks, outbox intentions, individual ACK checkpoints, deduplication and delivery-blocked evidence are RAM-owned. Each endpoint has lower-only limits of 16,384 records/32MiB encoded state. Admission fails before exceeding those bounds; they are not a process-RSS guarantee.
 - `agent_task_send` confirms relay acceptance, **not execution**. `receiver_recorded` confirms receiver RAM receipt, **not durable persistence**. Pi insertion and wake acceptance are separate evidence, never proof of model execution.
+- Delivery receipts are origin-local status. The origin records each one in its task log without presenting, archiving or forwarding it to the worker. Stages are ordered `receiver_recorded` < `pi_inserted` < `wake_accepted`, and a later stage implies the earlier ones. Per event and refresh, a receiver sends only the highest stage it reached, plus `pi_insertion` `blocked` when Pi did not record the insertion, so an assignment received, inserted and woken in one refresh costs one receipt. The `wake_accepted` record is written before Pi emits the wake, which keeps it ahead of any intent the woken model sends; it is sent only after the wake appears in Pi's entries, and an unobserved or throwing wake withdraws the never-sent record. `wake_requested` remains in `TaskDeliveryStage` and is accepted from 0.1.15 receivers (status shows wake acceptance pending) but is no longer emitted.
 - Session history is not an operational journal. A new process/lifecycle starts empty with a fresh endpoint/generation; it does not reconstruct tasks, replay envelopes, reuse old ACKs or reopen a worker gate from old history.
 - A relay restart can lose even accepted mail. A Pi restart loses that endpoint's active task state. Relay-loss evidence marks affected work failed only in the discarded local lifetime; its remote outcome remains explicitly unknown and is never presented as canonical delivery or completion evidence.
 
 ## memory-owned lifecycle
 
-`createConfiguredTaskCore()` owns its transport and `createTaskStore()` RAM state. Startup registers; polling runs every five seconds and at agent settlement. Shutdown fences new work, aborts requests, drains active calls and discards state. Late callbacks cannot mutate a successor lifetime.
+`createConfiguredTaskCore()` owns its transport and `createTaskStore()` RAM state. Startup registers; background polling is one `setTimeout` chain that re-arms after each refresh: every 1s while a task is active, the outbox is pending, or a gate-enabled worker awaits an eligible assignment, otherwise every 5s. Successful send/message/done/ack/cancel tools, `turn_end`, agent end and agent settlement request an immediate single-flight refresh; requests made during a running refresh coalesce into one trailing refresh. `agent_task_wait` requests one refresh, then re-checks local state when the RAM store commits a change or after a backoff of 250ms doubling to 2s; it issues no relay requests of its own. Shutdown fences new work, aborts requests, drains active calls and discards state. Late callbacks cannot mutate a successor lifetime.
 
-Background refresh records protocol facts in RAM even while Pi is busy or has queued messages. A valid completion within the fetched receive page can become canonical before its notification is presented. Model-visible insertion and the separate follow-up wake still wait for idle Pi with no queued messages; visible relay mail remains replayable until the required structured insertion/wake evidence is present. Intake alone does not incorporate an assignment or authorize worker tools. Parent acknowledgment before terminal presentation retains the event but suppresses its redundant wake.
+Background refresh records protocol facts in RAM even while Pi is busy or has queued messages. A valid completion within the fetched receive page can become canonical before its notification is presented. Model-visible insertion and the separate follow-up wake still wait for idle Pi with no queued messages; visible relay mail remains replayable until the required structured insertion/wake evidence is present. Intake alone does not incorporate an assignment or authorize worker tools. Parent acknowledgment before terminal presentation retains the event but suppresses its redundant wake. Origin-authored conversations do not echo to the origin. The origin's own view of other canonical events it creates, such as a completion canonicalized from a worker's raw intent, is queued in a RAM-only local presentation table instead of a self-addressed relay envelope. `receive()` merges those local items with relay mail by intake order. A held model-visible item blocks later visible items; non-visible items behind it are still archived and ACKed. A local item needs the same insertion and wake evidence before it completes, but records no relay delivery receipts. Receiver-authored conversation copies remain canonical replicas, but local outbound intent identity makes their presentation archive-only; payload author claims are not provenance. Missing or unmatched intent identity leaves peer conversations actionable. This correlation is RAM-only and is never recovered from session history.
 
-This separation does not change polling or the 100-envelope receive-page bound: a full prefix of held visible mail can still prevent intake of a newer intent beyond that page. General backlog scanning is not provided.
+The adaptive 1s/5s polling cadence does not change relay byte limits. A single-flight background refresh runs explicit phases in one work scope: lease connection, then intake (timeout canonicalization and relay receive persist and canonicalize without sending), presentation (Pi insertion/wake and receipt records, still without sending), shipping (required timeout fan-out, intake fan-out and receipts in persist order), acknowledgement (ACKs for presented items, then raw ACK repair) and finally old-work retry. The shared counts are: at most 56 scoped sends plus 8 rotating old-work sends, 48 ACK attempts and receive pages of up to 50 items while fewer than 200 relay deliveries are fetched but unacknowledged, with a 2s overall deadline. Failed attempts consume the shared counts; the same send/ACK identity is not attempted twice in that scope. Separate 250ms retry/ACK-repair slices stop admitting another attempt, not an already admitted request: each admitted request gets the remaining background window. These are scheduling bounds, not throughput guarantees. Foreground send/message/done retain the configured transport request deadline (default 12s) and caller cancellation instead of inheriting the background cutoff. Any speculative old-work retry after a foreground send uses a finite 2s background window, starting only when that share is reached.
+
+Intake first re-drives tracked, unacknowledged relay deliveries from the local RAM inbox in cursor order, then fetches after the highest tracked cursor and follows `hasMore` while the pending set has room. At 200 fetched-but-unacknowledged deliveries fetching pauses until ACKs drain it; nothing is skipped or dropped. Each delivery is tracked and persisted on its own before fan-out, so an abort mid-page loses nothing and the next fetch resumes after the last tracked cursor. Byte limits can make a page shorter than 50 items, and shared send/ACK counts can defer work. When the ship phase accepts a raw intent's required canonical fan-out, the intent stages an authorized ACK request in the existing checkpoint; the acknowledge phase's repair pass sends it, and a staged delivery is not re-driven. Failed or pending required fan-out withholds only that intent's ACK and no longer stops intake of later deliveries. A presented relay item is ACKed only after the ship phase accepted its receipts or found them blocked for good (reported as outbox degradation); a failed receipt withholds only that item's ACK, and presentation, shipping and ACKs of later items continue. Receipts to one target still leave in creation order, so a failed receipt also defers younger receipts to the same origin. Because receipts ship before ACKs, an ACK never precedes the receipt that justifies it. The repair pass uses the same ACK budget, admission slice and overall background deadline; remaining raw ACK work reports local deferral on budget/slice/cooldown exhaustion. Presentation stops at the remaining ACK budget. The first fan-out, receipt, presentation, repair or deferral failure is collected and reported after the pass, so it no longer holds back items intake already produced. Core operations in a phased pass never start old-work retry or ACK repair on their own; only the final phase retries old work, after required sends and ACKs, even on empty, held/busy or failed passes when budget remains. Ignored-abort ACK responses cannot later advance local authority. A held visible event stops presentation of later visible events but not archive and ACK of later non-visible events; an ACK budget exhaustion stops the pass. An intent whose required fan-out is quarantined is never ACKed and keeps one pending slot. General backlog scanning beyond the pending bound is not provided.
+
+Scoped operations attempt their own immutable IDs and cannot report acceptance for omitted or partial fan-out. Concurrent same-ID sends join existing delivery rather than retransmitting. Pending retry IDs rotate incrementally in RAM on attempts/actual skips, including failures and cooldown skips, without copying payloads or rotating an unattempted suffix past the retry deadline. A foreground packet's capacity refusal does not suppress smaller old packets to the same target; same-cycle target suppression starts only when speculative retry itself encounters capacity. Mail to one target leaves in creation order: an envelope is sent only after every older pending envelope to the same target is accepted, and a younger send waits for an older send already in flight. While the oldest envelope is cooling down or out of budget, younger mail to that target reports `TASK_DELIVERY_DEFERRED` (with `blockedBy`); a quarantined envelope leaves the queue and blocks nothing, and other targets are unaffected. Retry selection offers only each target's oldest pending envelope, and a reported send first offers older mail to its target from the bounded old-work share. Known capacity defers that envelope/ACK for at least 5s (or the validated longer `retryAfterMs`), without a retry timer. `TASK_DELIVERY_DEFERRED` is a retryable local budget/cooldown outcome, not relay acceptance or permanent quarantine. Raw intent replays retain their canonical fan-out reservation and are not ACKed while required sends remain pending; quarantined required sends report their blocked outcome instead of false acceptance. The exported `TaskStore` contract requires indexed lookup, fair rotation, cooldown, per-target FIFO selection (`pendingOutboxAhead`), withdrawal of a never-sent reservation (`discardUnsentOperation`), the RAM local presentation queue, post-commit `onChange` notification, the indexed `getQuarantine(envelopeId)` and `hasActiveTasks()` lookups and `setTarget(taskId, target)`, supplied by `createTaskStore()`; custom `TaskStore`/`TaskCore` implementations written against 0.1.15 must add these members (`TaskCore` also gains `hasPendingWork`, `onChange`, `completeLocalPresentation` and the phased-pass members `intakeInbox`, `shipRequired` and `repairAcknowledgements`, and its `WakeRequest` gains `discard()`; `createTaskWorkScope(signal, "phased")` makes a scope whose evidence and fan-out sends are queued for `shipRequired`, and `deliverTaskInbox` requires one); there is no legacy snapshot/fixed-prefix fallback. `TaskCore.receive()` returns an ordered array of `{ kind: "relay", delivery, order }` and `{ kind: "local", event, order }` items; a consumer ACKs relay items and completes local items with `completeLocalPresentation(eventId)`. The documented transport seam is unchanged, and origin-targeted canonical envelopes from older peers are still accepted.
+
+`createTaskStore()` keeps each row as immutable encoded text and caches its parsed value on first read; events are indexed by task and active tasks are tracked as a set, and both indexes follow transaction rollback and `clear()`. Stored values are deep-frozen and shared between reads: outbox and quarantine records, task events, payloads and endpoints throw a `TypeError` on a strict-mode write. Task snapshots and pending presentations are fresh top-level objects around those frozen values, so a write to their own fields is lost. Neither reaches the store. The store's own read-modify-write of the ACK checkpoint works on a copy. `createTaskCore({ timers })` takes an optional `TaskTimers` (`now`, `elapsed`, `timeout`) for the delivery budget: the 2s deadline, the retry/ACK-repair slices and capacity cooldowns. It defaults to system time and is separate from `clock`, which stamps task records; tests use it to run deadline and cooldown cases on virtual time.
 
 The default extension automatically replaces a lifetime only after a structured `RELAY_RESET` or `RELAY_REBIND_REQUIRED`. It fences and discards the unusable RAM state, records each active task in session history as locally failed with `RELAY_STATE_LOST` and an explicitly unknown remote outcome, then binds a fresh empty endpoint. The loss record does not wake the model by itself. Transient availability, authentication, capacity, abort, profile and malformed-response failures never trigger replacement. Historical tasks are not adopted into the successor lifetime.
 
+An origin can move an active task off a lost target with the optional `TaskCore.reassignTask(taskId)`, which `createTaskCore()` provides. It requires a quarantined send to the current target whose relay refusal was `TARGET_NOT_REGISTERED`; otherwise it fails with non-retryable `REASSIGNMENT_REFUSED` (`NOT_ORIGIN` for a non-origin caller). It resolves the lost endpoint's reference through the relay and refuses when it resolves to itself; the loss and the target are re-checked inside the commit, so one loss allows one reassignment even when calls race. It then sets the task's target, appends a `task.reassigned` event (payload `{ task, previousTarget }`), presents it locally at the origin and sends the successor an assignment envelope carrying `{ task, event, history }`. History that would exceed `MAX_RELAY_PAYLOAD_BYTES` keeps the newest events that fit and sets `historyTruncated: true`; a task too large even without history fails with `PAYLOAD_TOO_LARGE`. The receiver validates the carried history against the task and records it like an original assignment: it sends a `receiver_recorded` receipt, presents a `## task assignment (reassigned)` message and opens the worker gate for that task. A known task follows the reassignment, and carried events it already holds are skipped. A 0.1.15 receiver rejects `task.reassigned` as `INVALID_ASSIGNMENT`.
+
+The default extension does not call `reassignTask` yet. A current Wolfpack server issues a fresh random endpoint id on every rebind and answers `resolve` for a retired id with `TARGET_NOT_REGISTERED`, so the origin can detect the loss but cannot discover the successor; the client also rejects a `resolve` result whose id differs from the reference. Automatic reassignment needs the server to resolve a retired id (or a stable session-scoped reference that survives restart) to its live successor, and then a client change to accept the differing id.
+
+Error codes have one internal registry (`src/task-errors.ts`) that gives each code a class, a default message and explicit retry, rebind, relay-loss and blocked-delivery flags; a per-throw `retryable` still wins. Every failure of a `createVolatileTaskSession` relay request carries the relay operation in `details.operation`, and failures built from relay responses use the registry message for their code (server-supplied text was never shown); codes, `retryable` and other details are unchanged, and nothing new goes on the wire. The status line names a failed relay operation as `tasks: <class> (<CODE>) on <operation>`, for example `tasks: capacity (RELAY_CAPACITY) on send`; an unregistered code has class `error`. Relay loss, a missing compatible profile and required authentication keep their dedicated labels, and failures without a named operation keep `tasks: outbox degraded` or `tasks: relay unavailable`. Event handling (model-visible, terminal and its status, conversational, origin-local evidence, accepted as a receiver intent) comes from one internal `TASK_EVENT_TYPES` table in `src/task-protocol.ts`; unknown event types are still rejected.
+
 `createVolatileTaskSession({ url, callerSession, store })` is the lower-level API for a caller-owned RAM store. Transport reconnect within that same lifetime retains pending immutable retries; `rebind()` clears the store, while `close()` stops transport and the caller then closes its state. Persistence/path options are rejected. Old database files are neither read nor deleted.
 
 Full immutable content, including the original creation timestamp, is reused for retries. Destination-confirmed acceptance is required. Conflicting content, exhausted delivery and reset cannot become successful acceptance. Individual ACKs preserve sparse bigint cursors and cannot skip earlier pending mail. Bounds/deadlines apply through complete response bodies, including noncooperative injected transports.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.14",
+  "version": "0.1.16",
   "description": "Memory-only endpoint-owned Pi agent delegation through Wolfpack relay v2.",
   "module": "src/index.ts",
   "exports": {

package/src/abortable-sleep.ts

@@ -1,16 +1,25 @@
-export async function abortableSleep(milliseconds: number, signal: AbortSignal | undefined, cancellationError: () => Error): Promise<void> {
+/** Sleep until the timeout, an optional early wake, or abort; every exit path releases the timer and both subscriptions. */
+export async function abortableSleep(milliseconds: number, signal: AbortSignal | undefined, cancellationError: () => Error, subscribeWake?: (wake: () => void) => () => void): Promise<void> {
 	if (signal?.aborted) throw cancellationError();
 	await new Promise<void>((resolve, reject) => {
-		const removeAbortListener = (): void => signal?.removeEventListener("abort", abort);
+		let unsubscribeWake: (() => void) | undefined;
+		const release = (): void => {
+			clearTimeout(timeout);
+			signal?.removeEventListener("abort", abort);
+			unsubscribeWake?.();
+		};
 		const timeout = setTimeout(() => {
-			removeAbortListener();
+			release();
 			resolve();
 		}, milliseconds);
 		const abort = (): void => {
-			clearTimeout(timeout);
-			removeAbortListener();
+			release();
 			reject(cancellationError());
 		};
 		signal?.addEventListener("abort", abort, { once: true });
+		unsubscribeWake = subscribeWake?.(() => {
+			release();
+			resolve();
+		});
 	});
 }

package/src/configured-task-core.ts

@@ -50,10 +50,14 @@ export async function createConfiguredTaskCore(options: ConfiguredTaskCoreOption
         const result: unknown = value.apply(core, args);
         if (key === "recordWakeRequest") {
           const request = result as WakeRequest;
-          return { flush: (signal?: AbortSignal): Promise<void> => {
-            if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task session is closed", { retryable: false });
-            return track(request.flush(signal));
-          } };
+          return {
+            flush: (signal?: AbortSignal): Promise<void> => {
+              if (closed) throw new TaskProtocolError("RELAY_CLOSED", "task session is closed", { retryable: false });
+              return track(request.flush(signal));
+            },
+            // A closed session drops its store; there is nothing left to withdraw.
+            discard: () => { if (!closed) request.discard(); },
+          };
         }
         return result instanceof Promise ? track(result) : result;
       } });

package/src/extension.ts

@@ -4,8 +4,10 @@ import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
 import { abortableSleep } from "./abortable-sleep";
-import { deliverTaskInbox, incorporatedTaskEvents } from "./task-inbox";
-import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
+import { createTaskWorkScope } from "./task-work-scope";
+import { deliverTaskInbox, taskEntryEvidence, type TaskEntryEvidence } from "./task-inbox";
+import { RELAY_LOSS_CODES, taskErrorClass } from "./task-errors";
+import { TASK_EVENT_TYPES, TaskDeliveryEvidenceState, TaskDeliveryStage, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
 import { createConfiguredTaskCore } from "./configured-task-core";
 import type { OwnedTaskCore } from "./configured-task-core";
 import type { SubmitIntentInput, SubmitIntentOutcome, TaskCore } from "./task-core";
@@ -14,12 +16,17 @@ import type { TaskEndpoint, TaskSnapshot } from "./task-protocol";
 const DEFAULT_TASK_TIMEOUT_MS = 30 * 60 * 1_000;
 const MIN_TASK_TIMEOUT_MS = 1_000;
 const MAX_TASK_TIMEOUT_MS = 86_400_000;
-const BACKGROUND_POLL_MS = 5_000;
+/** Background cadence while work is pending (active task, pending outbox, or a worker awaiting assignment). */
+export const ACTIVE_POLL_MS = 1_000;
+/** Background cadence otherwise. */
+export const IDLE_POLL_MS = 5_000;
 const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
+/** Events that assign a task to their target: the original assignment and a reassignment to a lost target's successor. */
+const ASSIGNMENT_EVENTS: ReadonlySet<string> = new Set(["task.created", "task.reassigned"]);
 const RELAY_STATE_LOST_CODE = "RELAY_STATE_LOST";
 const RELAY_LOSS_CUSTOM_TYPE = "pi-tasks-relay-loss";
-const RELAY_LOSS_CODES = new Set(["RELAY_RESET", "RELAY_REBIND_REQUIRED"]);
-const WAIT_POLL_MS = 250;
+const WAIT_BACKOFF_INITIAL_MS = 250;
+const WAIT_BACKOFF_MAX_MS = 2_000;
 const SUMMARY_MAX_CHARS = 1_200;
 const PRE_ASSIGNMENT_TOOLS = new Set(["agent_task_inbox", "agent_task_status", "agent_task_wait"]);
 const COORDINATOR_ONLY_TASK_TOOLS = new Set(["agent_task_send", "agent_task_cancel", "agent_task_ack"]);
@@ -100,7 +107,7 @@ export function createConfiguredCoreLoader(factory: ConfiguredCoreFactory): Conf
 /** Registers endpoint-owned tools using the memory-owned Wolfpack transport by default. */
 export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefined = undefined, createCore: ConfiguredCoreFactory = defaultCoreFactory): void {
 	let inboxContext: ExtensionContext | undefined;
-	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
+	let backgroundTimer: ReturnType<typeof setTimeout> | undefined;
 	let lifecycleEpoch = 0;
 	const closingTaskIds = new Set<string>();
 	const workerGateEnabled = process.env.PI_TASK_WORKER === "1";
@@ -113,18 +120,21 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		const epoch = lifecycleEpoch;
 		const isCurrent = (): boolean => inboxContext === context && lifecycleEpoch === epoch;
 		if (!context) return undefined;
+		// Phased: intake runs ahead of speculative backlog work and ACK repair.
+		const work = createTaskWorkScope(signal, "phased");
+		signal = work.signal;
 		const activeCore = await configuredCore(signal);
 		if (!isCurrent()) return undefined;
 		let outboxError: unknown;
 		try {
-			await activeCore.flushOutbox(signal);
+			await activeCore.connect(signal, work);
 		} catch (error) {
 			if (isRelayLoss(error)) return error;
 			outboxError = error;
 		}
 		if (!isCurrent()) return undefined;
 		try {
-			await activeCore.evaluateTimeouts(signal);
+			await activeCore.evaluateTimeouts(signal, work);
 		} catch (error) {
 			if (isRelayLoss(error)) return error;
 			outboxError ??= error;
@@ -132,24 +142,48 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		if (!isCurrent()) return undefined;
 		const guardedCore: TaskCore = {
 			...activeCore,
-			async receive(receiveSignal) {
+			async receive(receiveSignal, receiveWork) {
 				if (!isCurrent()) return [];
-				const deliveries = await activeCore.receive(receiveSignal);
+				const deliveries = await activeCore.receive(receiveSignal, receiveWork);
 				return isCurrent() ? deliveries : [];
 			},
-			async acknowledgeRelayDelivery(cursor, acknowledgementSignal) {
-				if (isCurrent()) await activeCore.acknowledgeRelayDelivery(cursor, acknowledgementSignal);
+			async intakeInbox(intakeSignal, intakeWork) {
+				if (!isCurrent()) return [];
+				const items = await activeCore.intakeInbox(intakeSignal, intakeWork);
+				return isCurrent() ? items : [];
+			},
+			async shipRequired(shipSignal, shipWork) {
+				if (isCurrent()) await activeCore.shipRequired(shipSignal, shipWork);
+			},
+			async repairAcknowledgements(repairSignal, repairWork) {
+				if (isCurrent()) await activeCore.repairAcknowledgements(repairSignal, repairWork);
+			},
+			async acknowledgeRelayDelivery(cursor, acknowledgementSignal, acknowledgementWork) {
+				if (isCurrent()) await activeCore.acknowledgeRelayDelivery(cursor, acknowledgementSignal, acknowledgementWork);
+			},
+			completeLocalPresentation(eventId) {
+				if (isCurrent()) activeCore.completeLocalPresentation(eventId);
 			},
-			async recordInsertion(input, insertionSignal) {
-				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal);
+			async recordInsertion(input, insertionSignal, insertionWork) {
+				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal, insertionWork);
 			},
-			recordWakeRequest(input) {
+			async submitIntent(input, intentSignal, intentWork) {
+				if (isCurrent()) await activeCore.submitIntent(input, intentSignal, intentWork);
+			},
+			async flushOutbox(flushSignal, flushWork) {
+				if (isCurrent()) await activeCore.flushOutbox(flushSignal, flushWork);
+			},
+			recordWakeRequest(input, wakeWork) {
 				if (!isCurrent()) throw new TaskProtocolError("RELAY_CLOSED", "task lifecycle was replaced", { retryable: false });
-				const request = activeCore.recordWakeRequest(input);
-				return { flush: async (flushSignal?: AbortSignal): Promise<void> => {
-					if (!isCurrent()) throw new TaskProtocolError("RELAY_CLOSED", "task lifecycle was replaced", { retryable: false });
-					await request.flush(flushSignal);
-				} };
+				const request = activeCore.recordWakeRequest(input, wakeWork);
+				return {
+					flush: async (flushSignal?: AbortSignal): Promise<void> => {
+						if (!isCurrent()) throw new TaskProtocolError("RELAY_CLOSED", "task lifecycle was replaced", { retryable: false });
+						await request.flush(flushSignal);
+					},
+					// A replaced lifecycle discards its own state; there is nothing left to withdraw.
+					discard() { if (isCurrent()) request.discard(); },
+				};
 			},
 		};
 		const inboxOutboxError = await deliverTaskInbox({
@@ -159,16 +193,60 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 			isIdle: (): boolean => isCurrent() && context.isIdle(),
 			hasPendingMessages: (): boolean => !isCurrent() || context.hasPendingMessages(),
 			sessionManager: context.sessionManager,
-		}, signal);
+		}, signal, work);
 		return outboxError ?? inboxOutboxError;
 	});
+	const cancelBackgroundRefresh = (): void => {
+		if (backgroundTimer) clearTimeout(backgroundTimer);
+		backgroundTimer = undefined;
+	};
+	/** Keep exactly one pending background timer; each lifecycle refresh re-arms it with the next cadence. */
+	const scheduleBackgroundRefresh = (epoch: number, delayMs: number): void => {
+		cancelBackgroundRefresh();
+		backgroundTimer = setTimeout(() => {
+			backgroundTimer = undefined;
+			if (inboxContext && lifecycleEpoch === epoch) void requestRefresh();
+		}, delayMs);
+	};
+	// Active cadence while a task is active, the outbox is pending, or a gate-enabled worker lacks an eligible assignment.
+	// An eligible assignment implies an active task, so the worker clause together with the first reduces to `workerGateEnabled`.
+	const nextPollDelay = (activeCore: TaskCore | undefined): number => activeCore !== undefined && (workerGateEnabled || activeCore.hasPendingWork()) ? ACTIVE_POLL_MS : IDLE_POLL_MS;
 	const startBackgroundRefresh = (context: ExtensionContext, epoch: number): void => {
 		inboxContext = context;
-		if (backgroundTimer) clearInterval(backgroundTimer);
-		backgroundTimer = setInterval(() => {
-			const currentContext = inboxContext;
-			if (currentContext) void refreshLifecycle(currentContext, epoch);
-		}, BACKGROUND_POLL_MS);
+		scheduleBackgroundRefresh(epoch, IDLE_POLL_MS);
+	};
+	let lifecycleRefresh: Promise<void> | undefined;
+	let trailingRefresh = false;
+	/** Immediate single-flight lifecycle refresh; requests made while one runs coalesce into one trailing run. */
+	const requestRefresh = (): Promise<void> => {
+		if (lifecycleRefresh) {
+			trailingRefresh = true;
+			return lifecycleRefresh;
+		}
+		const current = (async (): Promise<void> => {
+			do {
+				trailingRefresh = false;
+				const context = inboxContext;
+				if (!context) return;
+				try {
+					await refreshLifecycle(context, lifecycleEpoch);
+				} catch (error) {
+					// Callers fire and forget, so a failure escaping refreshLifecycle (e.g. a throwing status UI) must not reject.
+					console.error("pi-tasks: lifecycle refresh failed", error);
+					if (inboxContext === context) {
+						try {
+							context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", `tasks: refresh failed: ${error instanceof Error ? error.message : String(error)}`));
+						} catch {
+							// Status is best effort; the failure is already logged above.
+						}
+					}
+				}
+			} while (trailingRefresh);
+		})().finally(() => {
+			if (lifecycleRefresh === current) lifecycleRefresh = undefined;
+		});
+		lifecycleRefresh = current;
+		return current;
 	};
 	const announceFreshBinding = (context: ExtensionContext): void => {
 		if (pendingRelayLossCount === undefined) return;
@@ -184,8 +262,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 			const recoveryEpoch = ++lifecycleEpoch;
 			const activeTasks = activeCore?.listTasks().filter((task) => task.status === "active") ?? [];
 			inboxContext = undefined;
-			if (backgroundTimer) clearInterval(backgroundTimer);
-			backgroundTimer = undefined;
+			cancelBackgroundRefresh();
 			await ownedLoader.close();
 			if (recoveryEpoch !== lifecycleEpoch) return;
 			for (const task of activeTasks) {
@@ -220,24 +297,30 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		let activeCore: (TaskCore & Partial<Pick<OwnedTaskCore, "close">>) | undefined;
 		try {
 			activeCore = await configuredCore();
-			let connectionError: unknown;
-			try {
-				await activeCore.connect();
-			} catch (error) {
-				connectionError = error;
-			}
 			if (!isCurrent()) return;
-			if (isRelayLoss(connectionError) && await recoverRelayLoss(context, epoch, activeCore)) return;
 			const outboxError = await refreshInbox();
 			if (!isCurrent()) return;
 			if (isRelayLoss(outboxError) && await recoverRelayLoss(context, epoch, activeCore)) return;
-			const lifecycleError = outboxError ?? connectionError;
+			const lifecycleError = outboxError;
 			const status = lifecycleError === undefined ? undefined : outboxFailureStatus(lifecycleError);
 			context.ui.setStatus("pi-tasks", status === undefined ? undefined : context.ui.theme.fg("warning", status));
 			if (lifecycleError === undefined) announceFreshBinding(context);
 		} catch (error) {
 			if (isCurrent() && isRelayLoss(error) && await recoverRelayLoss(context, epoch, activeCore)) return;
 			if (isCurrent()) context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", outboxFailureStatus(error)));
+		} finally {
+			if (isCurrent()) {
+				// The chain must outlive a failed cadence evaluation (e.g. an unreadable task snapshot): err toward polling and surface the fault.
+				let delay = ACTIVE_POLL_MS;
+				let delayError: unknown;
+				try {
+					delay = nextPollDelay(activeCore);
+				} catch (error) {
+					delayError = error;
+				}
+				scheduleBackgroundRefresh(epoch, delay); // Armed before the status write, which may itself throw.
+				if (delayError !== undefined) context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", `tasks: local task state unreadable: ${delayError instanceof Error ? delayError.message : String(delayError)}`));
+			}
 		}
 	};
 
@@ -246,7 +329,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		if (COORDINATOR_ONLY_TASK_TOOLS.has(event.toolName)) return { block: true, reason: WORKER_COORDINATION_FORBIDDEN_CODE };
 		try {
 			const activeCore = await configuredCore(context.signal);
-			const assignments = assignedWorkerTasks(activeCore, context.sessionManager.getEntries());
+			const assignments = assignedWorkerTasks(activeCore, taskEntryEvidence(context.sessionManager));
 			const taskId = inputTaskId(event.input);
 			if (event.toolName === "agent_task_done") {
 				const assigned = taskId === undefined ? undefined : assignments.find((task) => task.taskId === taskId);
@@ -273,25 +356,25 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		await ownedLoader?.start();
 		if (epoch !== lifecycleEpoch) return;
 		startBackgroundRefresh(context, epoch);
-		await refreshLifecycle(context, epoch);
+		await requestRefresh();
 	});
 	pi.on("agent_end", async (_event, context) => {
 		if (!inboxContext) return;
-		const epoch = lifecycleEpoch;
 		inboxContext = context;
-		await refreshLifecycle(context, epoch);
+		await requestRefresh();
 	});
 	pi.on("agent_settled", async (_event, context) => {
 		if (!inboxContext) return;
-		const epoch = lifecycleEpoch;
 		inboxContext = context;
-		await refreshLifecycle(context, epoch);
+		await requestRefresh();
+	});
+	pi.on("turn_end", async () => {
+		void requestRefresh();
 	});
 	pi.on("session_shutdown", async () => {
 		closingTaskIds.clear();
 		lifecycleEpoch += 1;
-		if (backgroundTimer) clearInterval(backgroundTimer);
-		backgroundTimer = undefined;
+		cancelBackgroundRefresh();
 		inboxContext = undefined;
 		pendingRelayLossCount = undefined;
 		await ownedLoader?.close();
@@ -302,6 +385,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		async execute(_id, params, signal) {
 			try {
 				const sent = await (await configuredCore(signal)).createTask({ target: params.to, task: params.task, timeoutMs: params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS }, signal);
+				void requestRefresh();
 				return toolResult(sent, `## task accepted\n- task: \`${sent.taskId}\`\n- target: \`${params.to.relay}/${params.to.id}\`\n- delivery: relay acceptance only`);
 			} catch (error) { return taskError(error); }
 		},
@@ -324,14 +408,17 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		async execute(_id, params, signal, onUpdate) {
 			const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS);
 			try {
-				for (;;) {
-					await refreshInbox(signal);
-					const task = (await configuredCore(signal)).getTask(params.taskId);
+				// Fetching belongs to the background cadence; the wait re-checks local state on store changes or backoff.
+				void requestRefresh();
+				for (let backoff = WAIT_BACKOFF_INITIAL_MS; ; backoff = Math.min(backoff * 2, WAIT_BACKOFF_MAX_MS)) {
+					// Resolve the core each round so a relay-loss replacement is re-subscribed.
+					const activeCore = await configuredCore(signal);
+					const task = activeCore.getTask(params.taskId);
 					if (!task) return taskError(new TaskProtocolError("UNKNOWN_TASK", `unknown task: ${params.taskId}`, { retryable: false }));
 					if (terminal(task.status)) return toolResult(task, `## task status\n- task: \`${task.taskId}\`\n- status: ${task.status}`);
 					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: task.status }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${task.status}\n- wait timed out`);
 					onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
-					await abortableSleep(Math.max(1, Math.min(WAIT_POLL_MS, deadline - Date.now())), signal, () => new Error("task wait was cancelled"));
+					await abortableSleep(Math.max(1, Math.min(backoff, deadline - Date.now())), signal, () => new Error("task wait was cancelled"), (wake) => activeCore.onChange(wake));
 				}
 			} catch (error) { return taskError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
@@ -350,7 +437,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 	});
 	pi.registerTool({
 		name: "agent_task_message", label: "Message Agent Task", description: "Record a message intent in this lifetime before relay submission.", parameters: MessageParams,
-		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.type}`, payload: { message: params.message } }, signal); return toolResult({ taskId: params.taskId }, `## task ${params.type}\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.type}`, payload: { message: params.message } }, signal); void requestRefresh(); return toolResult({ taskId: params.taskId }, `## task ${params.type}\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
 		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 	pi.registerTool({
@@ -360,6 +447,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 				const activeCore = await configuredCore(signal);
 				try {
 					await activeCore.submitIntent({ taskId: params.taskId, type: "task.cancelled", payload: {} }, signal);
+					void requestRefresh();
 					return toolResult({ taskId: params.taskId }, `## task cancellation requested\n- task: \`${params.taskId}\``);
 				} catch (error) {
 					return blockedCancellationResult(activeCore, params.taskId, error) ?? taskError(error);
@@ -370,7 +458,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 	});
 	pi.registerTool({
 		name: "agent_task_ack", label: "Acknowledge Agent Task", description: "Record parent acknowledgement as an origin-owned logical event.", parameters: TaskIdParams,
-		async execute(_id, params, signal) { try { await (await configuredCore(signal)).acknowledgeParent(params.taskId, signal); return toolResult({ taskId: params.taskId }, `## task acknowledged\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).acknowledgeParent(params.taskId, signal); void requestRefresh(); return toolResult({ taskId: params.taskId }, `## task acknowledged\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
 		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 	pi.registerTool({
@@ -386,6 +474,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 				} catch (error) {
 					return blockedDoneResult(activeCore, params.taskId, params.status, error) ?? taskError(error);
 				}
+				void requestRefresh();
 				const task = activeCore.getTask(params.taskId);
 				if (!task) return taskError(new TaskProtocolError("UNKNOWN_TASK", `unknown task: ${params.taskId}`, { retryable: false }));
 				if (submission?.authority === "origin" && submission.canonicalEvent.type === "task.late_terminal") {
@@ -435,7 +524,8 @@ function taskDeliveryEvidence(task: TaskSnapshot): TaskDeliveryEvidence {
 	let receiverReceipt: TaskDeliveryEvidence["receiverReceipt"] = "not_confirmed";
 	let piInsertion: TaskDeliveryEvidence["piInsertion"] = "not_confirmed";
 	let wakeAcceptance: TaskDeliveryEvidence["wakeAcceptance"] = "not_confirmed";
-	const assignmentEventId = task.events.find((event) => event.type === "task.created")?.eventId;
+	// After a reassignment, evidence describes the latest assignment.
+	const assignmentEventId = task.events.findLast((event) => ASSIGNMENT_EVENTS.has(event.type))?.eventId;
 	for (const event of task.events) {
 		if (event.type !== "task.delivery_receipt" || event.payload.eventId !== assignmentEventId) continue;
 		if (event.payload.stage === TaskDeliveryStage.receiverRecorded) receiverReceipt = "confirmed";
@@ -444,8 +534,13 @@ function taskDeliveryEvidence(task: TaskSnapshot): TaskDeliveryEvidence {
 			receiverReceipt = "confirmed";
 			piInsertion = "confirmed";
 		}
+		// Legacy v0.1.15 receivers still send wake_requested; current receivers send only the highest stage.
 		if (event.payload.stage === TaskDeliveryStage.wakeRequested) wakeAcceptance = "pending";
-		if (event.payload.stage === TaskDeliveryStage.wakeAccepted) wakeAcceptance = "confirmed";
+		if (event.payload.stage === TaskDeliveryStage.wakeAccepted) {
+			receiverReceipt = "confirmed";
+			piInsertion = "confirmed";
+			wakeAcceptance = "confirmed";
+		}
 	}
 	return { receiverReceipt, piInsertion, wakeAcceptance, modelExecution: "not_evidenced" };
 }
@@ -505,11 +600,17 @@ function blockedDeliveryWarning(error: TaskOutboxDeliveryError, target: TaskEndp
 	return { code: error.code, message: error.message, retryable: false, delivery: "blocked", target, details };
 }
 
-function outboxFailureStatus(error: unknown): string {
+/**
+ * Status-line text for a failed refresh. Actionable relay-state labels come first; otherwise
+ * `tasks: <class> (<CODE>) on <operation>` when the failed relay operation is known.
+ */
+export function outboxFailureStatus(error: unknown): string {
 	if (error instanceof TaskProtocolError) {
 		if (RELAY_LOSS_CODES.has(error.code)) return "tasks: relay state lost; rebinding automatically";
 		if (error.code === "RELAY_PROFILE_REQUIRED") return "tasks: compatible memory-owned relay required";
 		if (error.code === "RELAY_AUTH_REQUIRED") return "tasks: Wolfpack authentication required";
+		const operation = error.details?.operation;
+		if (typeof operation === "string") return `tasks: ${taskErrorClass(error.code)} (${error.code}) on ${operation}`;
 	}
 	return error instanceof TaskOutboxDeliveryError && isBlockedOutboxDeliveryCode(error.code) ? "tasks: outbox degraded" : "tasks: relay unavailable";
 }
@@ -519,26 +620,25 @@ function isRelayLoss(error: unknown): error is TaskProtocolError {
 }
 
 function terminal(status: string): boolean {
-	return ["completed", "failed", "cancelled", "timed_out"].includes(status);
+	return Object.values(TASK_EVENT_TYPES).some(type => type.status === status);
 }
 
 function receiverAssignment(core: TaskCore, task: TaskSnapshot, context: Pick<ExtensionContext, "sessionManager">): string {
 	if (task.status !== "active" || sameEndpoint(task.origin, core.endpoint) || !sameEndpoint(task.target, core.endpoint)) return "";
-	const created = task.events.find((event) => event.type === "task.created");
-	if (!created || !incorporatedTaskEvents(context.sessionManager.getEntries()).some((evidence) => evidence.taskId === task.taskId && evidence.eventId === created.eventId)) return "";
+	const incorporated = taskEntryEvidence(context.sessionManager).incorporated.get(task.taskId);
+	if (!task.events.some((event) => ASSIGNMENT_EVENTS.has(event.type) && sameEndpoint(event.target, core.endpoint) && incorporated?.has(event.eventId) === true)) return "";
 	return `\n\n## task assignment\n${task.task}`;
 }
 
-function assignedWorkerTasks(core: TaskCore, entries: readonly unknown[]): readonly TaskSnapshot[] {
-	const assignments = new Map<string, TaskSnapshot>();
-	for (const evidence of incorporatedTaskEvents(entries)) {
-		const task = core.getTask(evidence.taskId);
+/** Session evidence is memoized; tasks are read fresh on every call so the gate follows current task state. */
+function assignedWorkerTasks(core: TaskCore, evidence: TaskEntryEvidence): readonly TaskSnapshot[] {
+	const assignments: TaskSnapshot[] = [];
+	for (const [taskId, eventIds] of evidence.incorporated) {
+		const task = core.getTask(taskId);
 		if (!task || !sameEndpoint(task.target, core.endpoint)) continue;
-		const created = task.events.find((event) => event.eventId === evidence.eventId);
-		if (!created || created.type !== "task.created" || !sameEndpoint(created.target, core.endpoint) || !sameEndpoint(created.source, task.origin)) continue;
-		assignments.set(task.taskId, task);
+		if (task.events.some((event) => eventIds.has(event.eventId) && ASSIGNMENT_EVENTS.has(event.type) && sameEndpoint(event.target, core.endpoint) && sameEndpoint(event.source, task.origin))) assignments.push(task);
 	}
-	return [...assignments.values()];
+	return assignments;
 }
 
 function eligibleWorkerTask(task: TaskSnapshot, closingTaskIds: ReadonlySet<string>): boolean {

package/src/index.ts

@@ -30,5 +30,6 @@ export type {
 	TaskRecord,
 	TaskRelay,
 } from "./task-protocol";
-export type { SubmitIntentOutcome, TaskCore, TaskCoreOptions } from "./task-core";
-export type { TaskStore, TaskStoreOptions } from "./task-store";
+export type { SubmitIntentOutcome, TaskCore, TaskCoreOptions, TaskInboxItem } from "./task-core";
+export type { PendingPresentation, PresentationRecord, TaskStore, TaskStoreOptions } from "./task-store";
+export type { TaskTimers } from "./task-work-scope";