@sgtbeatdown/pi-tasks 0.1.10 → 0.1.12

package/README.md

@@ -30,13 +30,13 @@ The `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`.
 - Active tasks, outbox intentions, individual ACK checkpoints, deduplication and delivery-blocked evidence are RAM-owned. Each endpoint has lower-only limits of16,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.
 - 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. Prior outcomes can be unknown; do not label them delivered, failed or recovered without evidence.
+- 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.
 
-A live endpoint detecting relay reset stops. `/task-relay-rebind` explains the loss boundary; only `/task-relay-rebind --accept-relay-loss` explicitly discards old state and binds a fresh scope. Automatic polling never invokes rebind. Session history remains untouched, but no historical task becomes active again.
+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.
 
 `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.
 
@@ -98,4 +98,4 @@ PI_TASKS_WOLFPACK_REVISION=<full-commit-id> \
 bun test tests/volatile-real-worker.test.ts tests/volatile-extension-worker.test.ts
 ```
 
-Wolfpack worker tests require its supported Bun runtime (currently stable>=1.4.2). Optional source-selected checks use private HTTP/workers, not installed services. They test same-lifetime retry/ACK, explicit reset/rebind, fresh endpoint state and history-only evidence. `createInMemoryTaskRelay` is a deterministic conformance fixture, never the default runtime transport. Physical two-machine qualification, final-path performance, release packaging and live activation remain separate gates.
+Wolfpack worker tests require its supported Bun runtime (currently stable>=1.4.2). Optional source-selected checks use private HTTP/workers, not installed services. They test same-lifetime retry/ACK, automatic default-extension reset recovery, explicit lower-level session replacement, fresh endpoint state and history-only evidence. `createInMemoryTaskRelay` is a deterministic conformance fixture, never the default runtime transport. Physical two-machine qualification, final-path performance, release packaging and live activation remain separate gates.

package/package.json

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

package/skills/wolfpack-pi-task-delegation/SKILL.md

@@ -82,7 +82,7 @@ Assignment completion ends the assigned task, not the reusable role session. Whe
 
 Wolfpack is a memory-only, content-blind relay; each Pi endpoint keeps active task state, event order, retries and receipts in RAM. There is no SQLite task database. Relay acceptance is not execution; receiver receipt is not durable persistence. Model-visible `pi-tasks-event` entries include the complete structured event in session history; task wakes use Pi's safe `deliverAs: "followUp"` queue. Non-waking receipts, parent ACKs and late-terminal facts are archived as `pi-tasks-event-record` custom entries, not replayed. History is for inspection, never reconstruction/replay or worker authorization after restart. A relay restart can lose even accepted mail; a Pi restart loses its active task state and starts a fresh endpoint.
 
-A live endpoint detecting relay reset requires explicit owner action. `/task-relay-rebind` explains the loss boundary; `/task-relay-rebind --accept-relay-loss` discards old RAM state and binds a fresh endpoint. Session history stays untouched, but historical tasks are not adopted. Never invoke rebind as an automatic retry, claim recovery or silently reassign possibly delivered work. Old database files are not read, migrated or deleted; no backward-compatible durable mode is supported.
+The default extension automatically replaces its endpoint lifetime only after structured `RELAY_RESET` or `RELAY_REBIND_REQUIRED` evidence. It fences and discards old RAM state, records every active old-lifetime task in Pi session history as locally failed with `RELAY_STATE_LOST` and an explicitly unknown remote outcome, then binds a fresh empty endpoint. This local loss record is not a canonical remote terminal event and does not wake the model by itself. Historical tasks are never adopted or silently reassigned. Transient availability, authentication, capacity, abort, profile and malformed-response failures do not rotate the lifetime. Old database files are not read, migrated or deleted; no backward-compatible durable mode is supported.
 
 Receiver terminal submission has one task-wide logical identity. Same-status retries reuse it; a conflicting terminal status fails closed. Canonical status remains origin-owned, while `terminalDelivery` separately exposes `not_submitted`, `pending`, `accepted`, or `delivery_blocked`. Parent acknowledgment is terminal-only and retries reuse one logical event and stable envelope identities.
 

package/src/configured-task-core.ts

@@ -13,7 +13,7 @@ export interface ConfiguredTaskCoreOptions {
   readonly baseUrl?: string;
   readonly fetch?: typeof fetch;
   readonly requestTimeoutMs?: number;
-  /** Explicit operator acceptance of loss/unknown outcomes; never set on automatic retry. */
+  /** Fresh-lifetime registration after accepted state loss; the extension uses it only for structured relay-loss evidence. */
   readonly rebind?: boolean;
 }
 

package/src/extension.ts

@@ -5,7 +5,7 @@ import { Type } from "typebox";
 
 import { abortableSleep } from "./abortable-sleep";
 import { deliverTaskInbox, incorporatedTaskEvents } from "./task-inbox";
-import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskOutboxDeliveryError, TaskProtocolError } from "./task-protocol";
+import { 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";
@@ -16,6 +16,9 @@ const MIN_TASK_TIMEOUT_MS = 1_000;
 const MAX_TASK_TIMEOUT_MS = 86_400_000;
 const BACKGROUND_POLL_MS = 5_000;
 const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
+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 SUMMARY_MAX_CHARS = 1_200;
 const PRE_ASSIGNMENT_TOOLS = new Set(["agent_task_inbox", "agent_task_status", "agent_task_wait"]);
@@ -103,6 +106,8 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 	const workerGateEnabled = process.env.PI_TASK_WORKER === "1";
 	const ownedLoader = core === undefined ? createConfiguredCoreLoader(createCore) : undefined;
 	const configuredCore: ConfiguredCoreFactory = ownedLoader ?? (async (): Promise<TaskCore> => core!);
+	let relayLossRecovery: Promise<void> | undefined;
+	let pendingRelayLossCount: number | undefined;
 	const refreshInbox = createSingleFlightInboxRefresh(async (signal) => {
 		const context = inboxContext;
 		const epoch = lifecycleEpoch;
@@ -114,12 +119,14 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		try {
 			await activeCore.flushOutbox(signal);
 		} catch (error) {
+			if (isRelayLoss(error)) return error;
 			outboxError = error;
 		}
 		if (!isCurrent()) return undefined;
 		try {
 			await activeCore.evaluateTimeouts(signal);
 		} catch (error) {
+			if (isRelayLoss(error)) return error;
 			outboxError ??= error;
 		}
 		if (!isCurrent()) return undefined;
@@ -136,7 +143,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal);
 			},
 		};
-		await deliverTaskInbox({
+		const inboxOutboxError = await deliverTaskInbox({
 			sendMessage(message, options) { if (isCurrent()) pi.sendMessage(message, options); },
 			appendEntry(customType, data) { if (isCurrent()) pi.appendEntry(customType, data); },
 		}, guardedCore, {
@@ -144,12 +151,66 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 			hasPendingMessages: (): boolean => !isCurrent() || context.hasPendingMessages(),
 			sessionManager: context.sessionManager,
 		}, signal);
-		return outboxError;
+		return outboxError ?? inboxOutboxError;
 	});
+	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);
+	};
+	const announceFreshBinding = (context: ExtensionContext): void => {
+		if (pendingRelayLossCount === undefined) return;
+		const count = pendingRelayLossCount;
+		pendingRelayLossCount = undefined;
+		const taskSummary = count === 0 ? "No active tasks required local failure records." : `${count} active ${count === 1 ? "task was" : "tasks were"} marked locally failed with unknown remote outcome.`;
+		context.ui.notify(`Relay state was lost; automatically bound a fresh endpoint. ${taskSummary}`, "warning");
+	};
+	const recoverRelayLoss = async (context: ExtensionContext, epoch: number, activeCore: TaskCore | undefined): Promise<boolean> => {
+		if (!ownedLoader || lifecycleEpoch !== epoch || inboxContext !== context) return false;
+		if (relayLossRecovery) { await relayLossRecovery; return true; }
+		const pending = (async (): Promise<void> => {
+			const recoveryEpoch = ++lifecycleEpoch;
+			const activeTasks = activeCore?.listTasks().filter((task) => task.status === "active") ?? [];
+			inboxContext = undefined;
+			if (backgroundTimer) clearInterval(backgroundTimer);
+			backgroundTimer = undefined;
+			await ownedLoader.close();
+			if (recoveryEpoch !== lifecycleEpoch) return;
+			for (const task of activeTasks) {
+				pi.sendMessage({
+					customType: RELAY_LOSS_CUSTOM_TYPE,
+					content: `## task failed locally\ntask: \`${task.taskId}\`\n\nRelay state was lost; the remote outcome is unknown.`,
+					display: true,
+					details: { taskId: task.taskId, status: "failed", error: { code: RELAY_STATE_LOST_CODE, message: "relay state was lost; remote outcome is unknown", retryable: false }, remoteOutcome: "unknown" },
+				}, { triggerTurn: false });
+			}
+			pendingRelayLossCount = (pendingRelayLossCount ?? 0) + activeTasks.length;
+			closingTaskIds.clear();
+			try {
+				await ownedLoader.start();
+				if (recoveryEpoch !== lifecycleEpoch) return;
+				await ownedLoader(undefined, true);
+				if (recoveryEpoch !== lifecycleEpoch) return;
+				announceFreshBinding(context);
+				context.ui.setStatus("pi-tasks", undefined);
+			} catch (error) {
+				if (recoveryEpoch !== lifecycleEpoch) return;
+				context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", outboxFailureStatus(error)));
+			}
+			if (recoveryEpoch === lifecycleEpoch) startBackgroundRefresh(context, recoveryEpoch);
+		})();
+		relayLossRecovery = pending;
+		try { await pending; } finally { if (relayLossRecovery === pending) relayLossRecovery = undefined; }
+		return true;
+	};
 	const refreshLifecycle = async (context: ExtensionContext, epoch: number): Promise<void> => {
 		const isCurrent = (): boolean => lifecycleEpoch === epoch && inboxContext === context;
+		let activeCore: (TaskCore & Partial<Pick<OwnedTaskCore, "close">>) | undefined;
 		try {
-			const activeCore = await configuredCore();
+			activeCore = await configuredCore();
 			let connectionError: unknown;
 			try {
 				await activeCore.connect();
@@ -157,12 +218,16 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 				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 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)));
 		}
 	};
@@ -198,12 +263,7 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		const epoch = ++lifecycleEpoch;
 		await ownedLoader?.start();
 		if (epoch !== lifecycleEpoch) return;
-		inboxContext = context;
-		if (backgroundTimer) clearInterval(backgroundTimer);
-		backgroundTimer = setInterval(() => {
-			const currentContext = inboxContext;
-			if (currentContext) void refreshLifecycle(currentContext, epoch);
-		}, BACKGROUND_POLL_MS);
+		startBackgroundRefresh(context, epoch);
 		await refreshLifecycle(context, epoch);
 	});
 	pi.on("agent_end", async (_event, context) => {
@@ -224,39 +284,10 @@ export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefi
 		if (backgroundTimer) clearInterval(backgroundTimer);
 		backgroundTimer = undefined;
 		inboxContext = undefined;
+		pendingRelayLossCount = undefined;
 		await ownedLoader?.close();
 	});
 
-	if (ownedLoader && createCore === defaultCoreFactory) pi.registerCommand("task-relay-rebind", {
-		description: "Accept relay loss, discard active task state and bind a fresh endpoint",
-		async handler(args, context) {
-			if (args.trim() !== "--accept-relay-loss") {
-				context.ui.notify("Relay restart can lose accepted mail. Rebind discards this lifetime's task state; Pi session history remains, but is never replayed. Run /task-relay-rebind --accept-relay-loss to continue with a fresh endpoint.", "warning");
-				return;
-			}
-			const epoch = ++lifecycleEpoch;
-			inboxContext = undefined;
-			if (backgroundTimer) clearInterval(backgroundTimer);
-			backgroundTimer = undefined;
-			await ownedLoader.close();
-			if (epoch !== lifecycleEpoch) return;
-			try {
-				await ownedLoader.start();
-				if (epoch !== lifecycleEpoch) return;
-				await ownedLoader(undefined, true);
-				if (epoch !== lifecycleEpoch) return;
-				closingTaskIds.clear();
-				context.ui.notify("Fresh task endpoint bound with empty state. Prior tasks remain only in session history.", "info");
-			} catch (error) {
-				if (epoch === lifecycleEpoch) context.ui.notify(outboxFailureStatus(error), "error");
-			}
-			if (epoch !== lifecycleEpoch) return;
-			inboxContext = context;
-			backgroundTimer = setInterval(() => { if (inboxContext) void refreshLifecycle(inboxContext, epoch); }, BACKGROUND_POLL_MS);
-			await refreshLifecycle(context, epoch);
-		},
-	});
-
 	pi.registerTool({
 		name: "agent_task_send", label: "Send Agent Task", description: "Create a task in this endpoint's RAM and submit its assignment; restart loses active state.", parameters: SendParams,
 		async execute(_id, params, signal) {
@@ -467,11 +498,15 @@ function blockedDeliveryWarning(error: TaskOutboxDeliveryError, target: TaskEndp
 
 function outboxFailureStatus(error: unknown): string {
 	if (error instanceof TaskProtocolError) {
-		if (["RELAY_RESET", "RELAY_REBIND_REQUIRED"].includes(error.code)) return "tasks: relay reset; /task-relay-rebind";
+		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";
 	}
-	return error instanceof TaskOutboxDeliveryError && error.code === TARGET_NOT_REGISTERED_CODE ? "tasks: outbox degraded" : "tasks: relay unavailable";
+	return error instanceof TaskOutboxDeliveryError && isBlockedOutboxDeliveryCode(error.code) ? "tasks: outbox degraded" : "tasks: relay unavailable";
+}
+
+function isRelayLoss(error: unknown): error is TaskProtocolError {
+	return error instanceof TaskProtocolError && RELAY_LOSS_CODES.has(error.code);
 }
 
 function terminal(status: string): boolean {

package/src/task-core.ts

@@ -1,6 +1,5 @@
 import {
 	MAX_RELAY_PAYLOAD_BYTES,
-	INVALID_RELAY_METADATA,
 	ORIGIN_CANCELLATION_OPERATION,
 	PARENT_ACKNOWLEDGMENT_OPERATION,
 	TASK_PROTOCOL_VERSION,
@@ -10,6 +9,7 @@ import {
 	TaskEnvelopeKind,
 	TaskOutboxDeliveryError,
 	TaskProtocolError,
+	isBlockedOutboxDeliveryCode,
 } from "./task-protocol";
 import type {
 	RelayDelivery,
@@ -25,7 +25,6 @@ import type { TaskStore } from "./task-store";
 
 const RECEIVE_PAGE_SIZE = 100;
 const DELIVERY_EVIDENCE_OPERATION = "delivery_evidence";
-const TERMINAL_DELIVERY_CODES = new Set(["TARGET_NOT_REGISTERED", INVALID_RELAY_METADATA, "DELIVERY_UNCONFIRMED", "ENVELOPE_EXPIRED", "ENVELOPE_CONFLICT", "CROSS_RELAY_ENDPOINT"]);
 const TERMINAL_STATUSES = new Set<TaskRecord["status"]>(["completed", "failed", "cancelled", "timed_out"]);
 const TERMINAL_EVENTS = new Set(["task.completed", "task.failed", "task.cancelled", "task.timed_out"]);
 const CANONICAL_EVENTS = new Set([
@@ -401,7 +400,7 @@ async function flush(options: TaskCoreOptions, signal: AbortSignal | undefined,
 			options.store.transaction(() => { options.store.markOutboxAccepted(record.envelope.envelopeId); });
 		} catch (error) {
 			if (signal?.aborted || (error instanceof TaskProtocolError && error.code === "ABORTED")) throw error;
-			if (error instanceof TaskProtocolError && TERMINAL_DELIVERY_CODES.has(error.code) && !error.retryable) {
+			if (error instanceof TaskProtocolError && isBlockedOutboxDeliveryCode(error.code) && !error.retryable) {
 				options.store.transaction(() => {
 					options.store.quarantineOutbox(record.envelope.envelopeId, {
 						errorCode: error.code,

package/src/task-inbox.ts

@@ -1,5 +1,5 @@
 import type { TaskCore } from "./task-core";
-import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskProtocolError } from "./task-protocol";
+import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
 import type { RelayDelivery, TaskEvent } from "./task-protocol";
 
 const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
@@ -33,9 +33,10 @@ type DeliveryEvidencePayload =
 	| { readonly stage: typeof TaskDeliveryStage.piInsertion; readonly state: typeof TaskDeliveryEvidenceState.blocked; readonly retryable: true };
 
 /** Persists model-visible Pi evidence before advancing the relay cursor, then starts one separate turn. */
-export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, signal?: AbortSignal): Promise<void> {
-	if (context.hasPendingMessages()) return;
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, signal?: AbortSignal): Promise<TaskOutboxDeliveryError | undefined> {
+	if (context.hasPendingMessages()) return undefined;
 	const deliveries = await core.receive(signal);
+	let outboxError: TaskOutboxDeliveryError | undefined;
 	for (const delivery of deliveries) {
 		if (delivery.envelope.kind === TaskEnvelopeKind.intent) {
 			await core.acknowledgeRelayDelivery(delivery.cursor, signal);
@@ -44,7 +45,7 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 		}
 		const event = inboxEvent(delivery);
 		if (!isKnownEvent(event.type)) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
-		if (context.hasPendingMessages()) return;
+		if (context.hasPendingMessages()) return outboxError;
 		const eventDetails = { taskId: event.taskId, eventId: event.eventId };
 		const eventKey = key(event.taskId, event.eventId);
 		if (!isModelVisible(event.type) && !recordedEventKeys(context.sessionManager.getEntries()).has(eventKey)) {
@@ -53,11 +54,12 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 			pi.appendEntry(TASK_RECORD_CUSTOM_TYPE, { ...eventDetails, event });
 		}
 		if (event.type === "task.created") {
-			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, signal);
+			const evidenceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, signal);
+			outboxError ??= evidenceError;
 		}
 		let incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
 		if (!incorporated && isModelVisible(event.type)) {
-			if (!context.isIdle()) return;
+			if (!context.isIdle()) return outboxError;
 			pi.sendMessage({
 				customType: TASK_EVENT_CUSTOM_TYPE,
 				content: renderTaskEvent(event),
@@ -66,16 +68,19 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 			}, { triggerTurn: false });
 			incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
 			if (!incorporated) {
-				await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, signal);
-				return;
+				const evidenceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, signal);
+				outboxError ??= evidenceError;
+				return outboxError;
 			}
 		}
 		if (isModelVisible(event.type)) {
-			await core.recordInsertion(eventDetails, signal);
+			const insertionError = await settleDeliveryEvidence(() => core.recordInsertion(eventDetails, signal));
+			outboxError ??= insertionError;
 			let wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
 			if (!wakeAccepted) {
-				if (!context.isIdle()) return;
-				await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeRequested, state: TaskDeliveryEvidenceState.confirmed }, signal);
+				if (!context.isIdle()) return outboxError;
+				const wakeRequestError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeRequested, state: TaskDeliveryEvidenceState.confirmed }, signal);
+				outboxError ??= wakeRequestError;
 				pi.sendMessage({
 					customType: TASK_WAKE_CUSTOM_TYPE,
 					content: "Process the pending Pi task event.",
@@ -83,17 +88,29 @@ export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: Inb
 					details: eventDetails,
 				}, { triggerTurn: true, deliverAs: "followUp" });
 				wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
-				if (!wakeAccepted) return;
+				if (!wakeAccepted) return outboxError;
 			}
-			await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
+			const wakeAcceptanceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
+			outboxError ??= wakeAcceptanceError;
 		}
 		await core.acknowledgeRelayDelivery(delivery.cursor, signal);
 		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
 	}
+	return outboxError;
 }
 
-async function recordDeliveryEvidence(core: TaskCore, event: TaskEventDetails, evidence: DeliveryEvidencePayload, signal?: AbortSignal): Promise<void> {
-	await core.submitIntent({ taskId: event.taskId, type: "task.delivery_receipt", payload: { eventId: event.eventId, ...evidence } }, signal);
+async function recordDeliveryEvidence(core: TaskCore, event: TaskEventDetails, evidence: DeliveryEvidencePayload, signal?: AbortSignal): Promise<TaskOutboxDeliveryError | undefined> {
+	return settleDeliveryEvidence(() => core.submitIntent({ taskId: event.taskId, type: "task.delivery_receipt", payload: { eventId: event.eventId, ...evidence } }, signal));
+}
+
+async function settleDeliveryEvidence(operation: () => Promise<void>): Promise<TaskOutboxDeliveryError | undefined> {
+	try {
+		await operation();
+		return undefined;
+	} catch (error) {
+		if (error instanceof TaskOutboxDeliveryError && !error.retryable && isBlockedOutboxDeliveryCode(error.code)) return error;
+		throw error;
+	}
 }
 
 function inboxEvent(delivery: RelayDelivery): TaskEvent {

package/src/task-protocol.ts

@@ -5,6 +5,19 @@ export const ORIGIN_CANCELLATION_OPERATION = "origin_cancellation";
 export const PARENT_ACKNOWLEDGMENT_OPERATION = "parent_acknowledgment";
 export const TERMINAL_INTENT_OPERATION = "terminal_intent";
 
+const BLOCKED_OUTBOX_DELIVERY_CODES: ReadonlySet<string> = new Set([
+	"TARGET_NOT_REGISTERED",
+	INVALID_RELAY_METADATA,
+	"DELIVERY_UNCONFIRMED",
+	"ENVELOPE_EXPIRED",
+	"ENVELOPE_CONFLICT",
+	"CROSS_RELAY_ENDPOINT",
+]);
+
+export function isBlockedOutboxDeliveryCode(code: string): boolean {
+	return BLOCKED_OUTBOX_DELIVERY_CODES.has(code);
+}
+
 export const TaskDeliveryStage = {
 	receiverRecorded: "receiver_recorded",
 	piInsertion: "pi_insertion",

package/src/volatile-task-session.ts

@@ -223,7 +223,12 @@ class Transport {
         if (controller.signal.aborted) throw abortError();
         const response = await this.fetcher(this.url, { method: "POST", headers: { "content-type": "application/json" }, body: encoded, redirect: "error", signal: controller.signal });
         if (controller.signal.aborted) { void response.body?.cancel().catch(() => undefined); throw abortError(); }
-        if (response.status === 401) { void response.body?.cancel().catch(() => undefined); throw failure("RELAY_AUTH_REQUIRED", false); }
+        const rateLimited = response.status === 429;
+        if (response.status === 401 || rateLimited) {
+          // Admission failures need no relay profile. Best-effort cleanup must not mask their status.
+          void response.body?.cancel().catch(() => undefined);
+          throw failure(rateLimited ? "RELAY_CAPACITY" : "RELAY_AUTH_REQUIRED", rateLimited);
+        }
         const reader = response.body?.getReader();
         if (!reader) throw failure("INVALID_RESPONSE", true);
         const cancel = () => { void reader.cancel().catch(() => undefined); };