@sgtbeatdown/pi-tasks 0.1.14 → 0.1.16

package/src/task-errors.ts

@@ -0,0 +1,111 @@
+// The single error-code registry. It imports nothing from task-protocol so that module can re-export from here.
+
+export type TaskErrorClass = "transport" | "capacity" | "protocol" | "state" | "auth" | "delivery";
+
+/** Class for a code missing from the registry, e.g. a newer server's. */
+export const UNKNOWN_TASK_ERROR_CLASS = "error";
+
+interface TaskErrorSpec {
+	readonly class: TaskErrorClass;
+	/** Default for throwers without better information; an explicit per-throw `retryable` always wins. */
+	readonly retryable: boolean;
+	readonly message: string;
+	/** A transport rejection with this code is retryable whatever the server flag says. */
+	readonly forceRetry?: true;
+	/** The volatile binding behind this response is gone; the session retires it. */
+	readonly resetsBinding?: true;
+	/** Relay task state was lost; the extension rebinds automatically. */
+	readonly relayLoss?: true;
+	/** A non-retryable send outcome that quarantines the envelope as blocked delivery. */
+	readonly blocksDelivery?: true;
+}
+
+export const TASK_ERRORS: Readonly<Record<string, TaskErrorSpec>> = {
+	// transport
+	RELAY_UNAVAILABLE: { class: "transport", retryable: true, forceRetry: true, message: "relay is unavailable" },
+	PEER_UNREACHABLE: { class: "transport", retryable: true, forceRetry: true, message: "peer relay is unreachable" },
+	RELAY_TIMEOUT: { class: "transport", retryable: true, message: "relay request timed out" },
+	RELAY_BUSY: { class: "transport", retryable: true, message: "relay handshake is already in progress" },
+	ABORTED: { class: "transport", retryable: true, message: "request was aborted" },
+	INVALID_RESPONSE: { class: "transport", retryable: true, message: "relay response is malformed" },
+	// capacity
+	RELAY_CAPACITY: { class: "capacity", retryable: true, forceRetry: true, message: "relay is at capacity" },
+	TASK_CAPACITY: { class: "capacity", retryable: false, message: "active task state is full" },
+	PAYLOAD_TOO_LARGE: { class: "capacity", retryable: false, message: "task payload is too large" },
+	TASK_DELIVERY_DEFERRED: { class: "capacity", retryable: true, message: "task delivery deferred by the local work budget or retry cooldown" },
+	// auth and policy
+	RELAY_AUTH_REQUIRED: { class: "auth", retryable: false, message: "Wolfpack authentication required" },
+	PEER_POLICY_REQUIRED: { class: "auth", retryable: false, message: "peer relay policy does not allow this request" },
+	UNAUTHORIZED_INTENT: { class: "auth", retryable: false, message: "intent is not authorized for this task" },
+	PI_TASK_WORKER_ASSIGNMENT_REQUIRED: { class: "auth", retryable: false, message: "worker tools require an active assignment" },
+	PI_TASK_WORKER_COORDINATION_FORBIDDEN: { class: "auth", retryable: false, message: "workers cannot coordinate other tasks" },
+	// relay and task state
+	RELAY_RESET: { class: "state", retryable: false, resetsBinding: true, relayLoss: true, message: "relay lifetime was reset" },
+	RELAY_REBIND_REQUIRED: { class: "state", retryable: false, relayLoss: true, message: "relay binding must be replaced" },
+	RELAY_STATE_LOST: { class: "state", retryable: false, message: "relay task state was lost" },
+	REGISTRATION_EXPIRED: { class: "state", retryable: false, resetsBinding: true, message: "relay registration expired" },
+	SOURCE_MISMATCH: { class: "state", retryable: false, resetsBinding: true, message: "relay source does not match the binding" },
+	CALLER_DEAD: { class: "state", retryable: false, resetsBinding: true, message: "calling session is gone" },
+	CALLER_NOT_FOUND: { class: "state", retryable: false, resetsBinding: true, message: "calling session is not found" },
+	RELAY_CLOSED: { class: "state", retryable: false, message: "task lifetime is closed" },
+	UNKNOWN_TASK: { class: "state", retryable: false, message: "unknown task" },
+	TASK_NOT_FOUND: { class: "state", retryable: false, message: "task is not active in this endpoint lifetime" },
+	TASK_NOT_TERMINAL: { class: "state", retryable: false, message: "only a terminal task may be acknowledged" },
+	TERMINAL_INTENT_CONFLICT: { class: "state", retryable: false, message: "a different terminal intent was already submitted" },
+	NOT_ORIGIN: { class: "state", retryable: false, message: "only the origin may perform this operation" },
+	NOT_PARTICIPANT: { class: "state", retryable: false, message: "endpoint is not a task participant" },
+	REASSIGNMENT_REFUSED: { class: "state", retryable: false, message: "task cannot be reassigned" },
+	TASK_ERROR: { class: "state", retryable: true, message: "task operation failed" },
+	// delivery
+	TARGET_NOT_REGISTERED: { class: "delivery", retryable: false, blocksDelivery: true, message: "target is not registered" },
+	INVALID_RELAY_METADATA: { class: "delivery", retryable: false, blocksDelivery: true, message: "relay metadata is invalid" },
+	DELIVERY_UNCONFIRMED: { class: "delivery", retryable: false, blocksDelivery: true, message: "peer delivery outcome is unknown" },
+	ENVELOPE_EXPIRED: { class: "delivery", retryable: false, blocksDelivery: true, message: "envelope expired before delivery" },
+	ENVELOPE_CONFLICT: { class: "delivery", retryable: false, blocksDelivery: true, message: "envelope id was reused with different content" },
+	CROSS_RELAY_ENDPOINT: { class: "delivery", retryable: false, blocksDelivery: true, message: "endpoint belongs to another relay" },
+	UNREGISTERED_TARGET: { class: "delivery", retryable: true, message: "target is not registered for this protocol" },
+	UNREGISTERED_SOURCE: { class: "delivery", retryable: true, message: "source is not registered for this protocol" },
+	UNKNOWN_RELAY: { class: "delivery", retryable: true, message: "target belongs to another relay" },
+	// protocol
+	RELAY_PROFILE_REQUIRED: { class: "protocol", retryable: false, message: "compatible memory-owned relay required" },
+	INCOMPATIBLE_PROTOCOL: { class: "protocol", retryable: false, message: "incompatible task protocol" },
+	INVALID_REQUEST: { class: "protocol", retryable: false, message: "relay rejected the request as invalid" },
+	INVALID_CONNECTION: { class: "protocol", retryable: true, message: "relay connected a different endpoint" },
+	INVALID_ACCEPTANCE: { class: "protocol", retryable: true, message: "relay acceptance is malformed" },
+	INVALID_INBOX: { class: "protocol", retryable: true, message: "relay inbox page is malformed" },
+	INVALID_DELIVERY: { class: "protocol", retryable: true, message: "relay returned an invalid or unordered delivery" },
+	INVALID_CURSOR: { class: "protocol", retryable: true, message: "relay cursor is invalid" },
+	INVALID_ENVELOPE: { class: "protocol", retryable: true, message: "relay envelope is malformed" },
+	INVALID_PAYLOAD: { class: "protocol", retryable: true, message: "relay envelope payload is invalid" },
+	INVALID_TARGET: { class: "protocol", retryable: true, message: "target is invalid" },
+	INVALID_ENDPOINT: { class: "protocol", retryable: true, message: "endpoint is invalid" },
+	INVALID_ENDPOINT_REFERENCE: { class: "protocol", retryable: true, message: "endpoint reference is invalid" },
+	INVALID_TASK: { class: "protocol", retryable: true, message: "task and a positive timeout are required" },
+	INVALID_ASSIGNMENT: { class: "protocol", retryable: true, message: "assignment is invalid" },
+	INVALID_INTENT: { class: "protocol", retryable: true, message: "task intent is invalid" },
+	INVALID_EVENT: { class: "protocol", retryable: true, message: "task event is invalid" },
+	INVALID_INBOX_EVENT: { class: "protocol", retryable: true, message: "relay envelope does not contain a valid model event" },
+	UNKNOWN_EVENT: { class: "protocol", retryable: true, message: "unknown task event type" },
+};
+
+function codes(flag: (spec: TaskErrorSpec) => boolean | undefined): ReadonlySet<string> {
+	return new Set(Object.entries(TASK_ERRORS).flatMap(([code, spec]) => flag(spec) ? [code] : []));
+}
+
+export const RETRY_CODES = codes(spec => spec.forceRetry);
+export const RESET_CODES = codes(spec => spec.resetsBinding);
+export const RELAY_LOSS_CODES = codes(spec => spec.relayLoss);
+const BLOCKED_OUTBOX_DELIVERY_CODES = codes(spec => spec.blocksDelivery);
+
+export function isBlockedOutboxDeliveryCode(code: string): boolean {
+	return BLOCKED_OUTBOX_DELIVERY_CODES.has(code);
+}
+
+export function taskErrorClass(code: string): TaskErrorClass | typeof UNKNOWN_TASK_ERROR_CLASS {
+	return TASK_ERRORS[code]?.class ?? UNKNOWN_TASK_ERROR_CLASS;
+}
+
+/** The registry message, or the code itself for an unregistered code. */
+export function taskErrorMessage(code: string): string {
+	return TASK_ERRORS[code]?.message ?? code;
+}

package/src/task-inbox.ts

@@ -1,12 +1,13 @@
 import type { TaskCore } from "./task-core";
-import { TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
+import { createTaskWorkScope } from "./task-work-scope";
+import type { TaskShipment, TaskWorkScope } from "./task-work-scope";
+import { TASK_EVENT_TYPES, TaskDeliveryEvidenceState, TaskDeliveryStage, TaskEnvelopeKind, TaskOutboxDeliveryError, TaskProtocolError, isBlockedOutboxDeliveryCode } from "./task-protocol";
 import type { RelayDelivery, TaskEvent } from "./task-protocol";
 
 const TASK_EVENT_CUSTOM_TYPE = "pi-tasks-event";
 const TASK_WAKE_CUSTOM_TYPE = "pi-tasks-wake";
 const TASK_CURSOR_CUSTOM_TYPE = "pi-tasks-relay-cursor";
 const TASK_RECORD_CUSTOM_TYPE = "pi-tasks-event-record";
-const TERMINAL_EVENT_TYPES = new Set(["task.completed", "task.failed", "task.cancelled", "task.timed_out"]);
 
 interface InboxContext {
 	readonly isIdle: () => boolean;
@@ -30,92 +31,157 @@ export interface TaskEventDetails {
 }
 
 type DeliveryEvidencePayload =
-	| { readonly stage: typeof TaskDeliveryStage.receiverRecorded | typeof TaskDeliveryStage.wakeRequested | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
+	| { readonly stage: typeof TaskDeliveryStage.receiverRecorded | typeof TaskDeliveryStage.wakeAccepted; readonly state: typeof TaskDeliveryEvidenceState.confirmed }
 	| { 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<TaskOutboxDeliveryError | undefined> {
-	const deliveries = await core.receive(signal);
+/** Relay items carry delivery receipts; origin-local items never emit receipts, insertion records or ACKs. */
+interface RelayReceipts {
+	readonly signal: AbortSignal;
+	readonly work: TaskWorkScope;
+}
+
+/** Persists model-visible Pi evidence before advancing the relay cursor or retiring a local item, then starts one separate turn. */
+export async function deliverTaskInbox(pi: InboxPi, core: TaskCore, context: InboxContext, signal?: AbortSignal, work = createTaskWorkScope(signal, "phased")): Promise<TaskOutboxDeliveryError | undefined> {
+	// Explicit phases: intake, presentation, required sends, ACKs, then old-work retry.
+	if (!work.phased) throw new TypeError("inbox delivery requires a phased work scope");
+	signal = work.signal;
 	let outboxError: TaskOutboxDeliveryError | undefined;
-	for (const delivery of deliveries) {
-		if (delivery.envelope.kind === TaskEnvelopeKind.intent) {
-			await core.acknowledgeRelayDelivery(delivery.cursor, signal);
-			pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
-			continue;
-		}
-		const event = inboxEvent(delivery);
-		if (!isKnownEvent(event.type)) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
-		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)) {
-			// Archive receipts/parent ACK/late-terminal facts without waking the model.
-			// This is evidence only: no task state or delivery queue is reconstructed.
-			pi.appendEntry(TASK_RECORD_CUSTOM_TYPE, { ...eventDetails, event });
+	let failure: unknown;
+	const receipts: RelayReceipts = { signal, work };
+	try {
+		// Intake persists and canonicalizes without sending; earlier required sends of this pass are already queued.
+		const items = await core.intakeInbox(signal, work);
+		// Presentation persists Pi evidence only. Each relay item ends in an ACK, so stop at the remaining budget.
+		const budget = work.remainingAcknowledgements();
+		const presented: { readonly cursor: string; readonly shipments: readonly TaskShipment[] }[] = [];
+		// Shipments queued from here on are this presentation's delivery receipts.
+		const receiptsFrom = work.shipments.length;
+		try {
+			// The first held model-visible item holds every later visible item, so none overtakes it;
+			// later control facts and self-authored copies are still archived and ACKed.
+			let held = false;
+			for (const item of items) {
+				if (item.kind === "local") {
+					if (held && isPresentedToModel(core, item.event)) continue;
+					if (!await presentEvent(pi, core, context, item.event, undefined)) { held = true; continue; }
+					core.completeLocalPresentation(item.event.eventId);
+					continue;
+				}
+				if (presented.length >= budget) break;
+				const delivery = item.delivery;
+				const mark = work.shipments.length;
+				if (delivery.envelope.kind !== TaskEnvelopeKind.intent) {
+					const event = inboxEvent(delivery);
+					if (held && isPresentedToModel(core, event)) continue;
+					if (!await presentEvent(pi, core, context, event, receipts)) { held = true; continue; }
+				}
+				presented.push({ cursor: delivery.cursor, shipments: work.shipments.slice(mark) });
+			}
+		} catch (error) {
+			// Items presented before the failure still ship and ACK; the failure surfaces at the end.
+			if (work.signal.aborted) throw error;
+			failure = error;
 		}
-		if (event.type === "task.created") {
-			const evidenceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, signal);
-			outboxError ??= evidenceError;
+		// Required sends in persist order. A receipt blocked for good is reported and does not hold its ACK.
+		await core.shipRequired(signal, work);
+		for (const [index, shipment] of work.shipments.entries()) {
+			if (shipment.failure === undefined) continue;
+			if (index >= receiptsFrom && isBlockedDeliveryFailure(shipment.failure)) outboxError ??= shipment.failure;
+			else failure ??= shipment.failure;
 		}
-		let incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
-		if (!incorporated && isModelVisible(event.type)) {
-			if (!context.isIdle()) return outboxError;
-			pi.sendMessage({
-				customType: TASK_EVENT_CUSTOM_TYPE,
-				content: renderTaskEvent(event),
-				display: true,
-				details: { ...eventDetails, event },
-			}, { triggerTurn: false });
-			incorporated = incorporatedEvents(context.sessionManager.getEntries()).has(eventKey);
-			if (!incorporated) {
-				const evidenceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, signal);
-				outboxError ??= evidenceError;
-				return outboxError;
+		// ACK only items whose receipts were accepted or blocked for good.
+		try {
+			for (const { cursor, shipments } of presented) {
+				if (shipments.some(shipment => !shipment.shipped || (shipment.failure !== undefined && !isBlockedDeliveryFailure(shipment.failure)))) continue;
+				await core.acknowledgeRelayDelivery(cursor, signal, work);
+				pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor });
 			}
+			await core.repairAcknowledgements(signal, work);
+		} catch (error) {
+			if (work.signal.aborted) throw error;
+			failure ??= error;
 		}
-		if (isModelVisible(event.type)) {
-			const insertionError = await settleDeliveryEvidence(() => core.recordInsertion(eventDetails, signal));
-			outboxError ??= insertionError;
-			let wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
-			const wakeSuppressed = !wakeAccepted && hasAcknowledgedLocalOriginTerminal(core, event);
-			if (!wakeAccepted && !wakeSuppressed) {
-				if (!context.isIdle()) return outboxError;
-				// This synchronous local write closes the ACK/wake race; do not await relay I/O before Pi emits the wake.
-				const wakeRequest = core.recordWakeRequest(eventDetails);
-				pi.sendMessage({
-					customType: TASK_WAKE_CUSTOM_TYPE,
-					content: "Process the pending Pi task event.",
-					display: false,
-					details: eventDetails,
-				}, { triggerTurn: true, deliverAs: "followUp" });
-				wakeAccepted = taskMessageKeys(context.sessionManager.getEntries(), TASK_WAKE_CUSTOM_TYPE).has(eventKey);
-				if (!wakeAccepted) return outboxError;
-				const wakeRequestError = await settleDeliveryEvidence(() => wakeRequest.flush(signal));
-				outboxError ??= wakeRequestError;
-			}
-			if (wakeAccepted) {
-				const wakeAcceptanceError = await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, signal);
-				outboxError ??= wakeAcceptanceError;
-			}
+	} finally {
+		// Completed, held or failed delivery yields the remaining bounded share to old work.
+		if (!work.signal.aborted) try { await core.flushOutbox(work.signal, work); } catch (error) {
+			if (!(error instanceof TaskOutboxDeliveryError)) throw error;
+			outboxError ??= error;
 		}
-		await core.acknowledgeRelayDelivery(delivery.cursor, signal);
-		pi.appendEntry(TASK_CURSOR_CUSTOM_TYPE, { cursor: delivery.cursor });
 	}
+	// Collected failures surface only after presentation, ACKs and the bounded flush had their share.
+	if (failure !== undefined) throw failure;
 	return outboxError;
 }
 
-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> {
+/**
+ * Idle gate, insertion, rescan, wake and wake evidence for one event. Returns false when presentation is held.
+ * Receipts collapse to the highest stage reached in this refresh (the origin derives the stages it implies),
+ * plus `pi_insertion` blocked when insertion was not observed.
+ */
+async function presentEvent(pi: InboxPi, core: TaskCore, context: InboxContext, event: TaskEvent, receipts: RelayReceipts | undefined): Promise<boolean> {
+	const eventDetails = { taskId: event.taskId, eventId: event.eventId };
+	const eventKey = key(event.taskId, event.eventId);
+	if (!isPresentedToModel(core, event)) {
+		// Archive control facts and confirmed self-authored conversations without model insertion or wake,
+		// even while Pi is busy. This is evidence only: no task state or delivery queue is reconstructed.
+		if (!taskEntryEvidence(context.sessionManager).recorded.has(eventKey)) pi.appendEntry(TASK_RECORD_CUSTOM_TYPE, { ...eventDetails, event });
+		return true;
+	}
+	if (context.hasPendingMessages()) return false;
+	const recordReceiver = async () => {
+		if (receipts && (event.type === "task.created" || event.type === "task.reassigned")) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.receiverRecorded, state: TaskDeliveryEvidenceState.confirmed }, receipts);
+	};
+	const recordInsertion = async () => {
+		if (receipts) await core.recordInsertion(eventDetails, receipts.signal, receipts.work);
+	};
+	const incorporated = () => taskEntryEvidence(context.sessionManager).incorporated.get(event.taskId)?.has(event.eventId) === true;
+	if (!incorporated()) {
+		if (!context.isIdle()) { await recordReceiver(); return false; }
+		pi.sendMessage({
+			customType: TASK_EVENT_CUSTOM_TYPE,
+			content: renderTaskEvent(event),
+			display: true,
+			details: { ...eventDetails, event },
+		}, { triggerTurn: false });
+		if (!incorporated()) {
+			await recordReceiver();
+			if (receipts) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.piInsertion, state: TaskDeliveryEvidenceState.blocked, retryable: true }, receipts);
+			return false;
+		}
+	}
+	if (taskEntryEvidence(context.sessionManager).wakes.has(eventKey)) {
+		if (receipts) await recordDeliveryEvidence(core, eventDetails, { stage: TaskDeliveryStage.wakeAccepted, state: TaskDeliveryEvidenceState.confirmed }, receipts);
+		return true;
+	}
+	if (hasAcknowledgedLocalOriginTerminal(core, event)) { await recordInsertion(); return true; }
+	if (!context.isIdle()) { await recordInsertion(); return false; }
+	// This synchronous local write closes the ACK/wake race; do not await relay I/O before Pi emits the wake.
+	const wakeRequest = receipts && core.recordWakeRequest(eventDetails, receipts.work);
+	let wakeAccepted = false;
 	try {
-		await operation();
-		return undefined;
-	} catch (error) {
-		if (error instanceof TaskOutboxDeliveryError && !error.retryable && isBlockedOutboxDeliveryCode(error.code)) return error;
-		throw error;
+		pi.sendMessage({
+			customType: TASK_WAKE_CUSTOM_TYPE,
+			content: "Process the pending Pi task event.",
+			display: false,
+			details: eventDetails,
+		}, { triggerTurn: true, deliverAs: "followUp" });
+		wakeAccepted = taskEntryEvidence(context.sessionManager).wakes.has(eventKey);
+	} finally {
+		// An unaccepted or throwing wake must not leave a wake_accepted record for the outbox flush.
+		if (!wakeAccepted) wakeRequest?.discard();
 	}
+	if (!wakeAccepted) { await recordInsertion(); return false; }
+	if (receipts && wakeRequest) await wakeRequest.flush(receipts.signal);
+	return true;
+}
+
+/** Persists the receipt; the phased pass ships it before the item's ACK. */
+async function recordDeliveryEvidence(core: TaskCore, event: TaskEventDetails, evidence: DeliveryEvidencePayload, receipts: RelayReceipts): Promise<void> {
+	await core.submitIntent({ taskId: event.taskId, type: "task.delivery_receipt", payload: { eventId: event.eventId, ...evidence } }, receipts.signal, receipts.work);
+}
+
+function isBlockedDeliveryFailure(error: unknown): error is TaskOutboxDeliveryError {
+	return error instanceof TaskOutboxDeliveryError && !error.retryable && isBlockedOutboxDeliveryCode(error.code);
 }
 
 function inboxEvent(delivery: RelayDelivery): TaskEvent {
@@ -128,16 +194,15 @@ function inboxEvent(delivery: RelayDelivery): TaskEvent {
 	throw new TaskProtocolError("INVALID_INBOX_EVENT", "relay envelope does not contain a valid model event");
 }
 
-function isKnownEvent(type: string): boolean {
-	return ["task.created", "task.completed", "task.failed", "task.cancelled", "task.timed_out", "task.information", "task.question", "task.answer", "task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
-}
-
-function isModelVisible(type: string): boolean {
-	return !["task.delivery_receipt", "task.parent_acknowledged", "task.late_terminal"].includes(type);
+/** Model insertion and wake apply; otherwise the event is archived. Throws for an unknown event type. */
+function isPresentedToModel(core: TaskCore, event: TaskEvent): boolean {
+	const type = TASK_EVENT_TYPES[event.type];
+	if (type === undefined) throw new TaskProtocolError("UNKNOWN_EVENT", `unknown task inbox event type: ${event.type}`);
+	return type.visible && !core.isSelfAuthoredConversation(event);
 }
 
 function hasAcknowledgedLocalOriginTerminal(core: TaskCore, event: TaskEvent): boolean {
-	if (!TERMINAL_EVENT_TYPES.has(event.type)) return false;
+	if (TASK_EVENT_TYPES[event.type]?.terminal !== true) return false;
 	const task = core.getTask(event.taskId);
 	if (task === undefined || task.origin.relay !== core.endpoint.relay || task.origin.id !== core.endpoint.id) return false;
 	const terminalIndex = task.events.findIndex((candidate) => candidate.eventId === event.eventId && candidate.type === event.type);
@@ -146,6 +211,8 @@ function hasAcknowledgedLocalOriginTerminal(core: TaskCore, event: TaskEvent): b
 
 function renderTaskEvent(event: TaskEvent): string {
 	if (event.type === "task.created") return `## task assignment\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`\n\n${String(event.payload.task ?? "")}`;
+	// The successor sees the task itself; earlier history stays in the task record (agent_task_status).
+	if (event.type === "task.reassigned") return `## task assignment (reassigned)\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`\n\nthe previous target was lost; earlier task history is in agent_task_status.\n\n${String(event.payload.task ?? "")}`;
 	const body = typeof event.payload.message === "string" ? `\n\n${event.payload.message}` : "";
 	const summary = typeof event.payload.summary === "string" ? `\n\n**summary:** ${event.payload.summary}` : "";
 	return `## task ${event.type.replace(/^task\./, "").replaceAll("_", " ")}\ntask: \`${event.taskId}\` · event: \`${event.eventId}\`${body}${summary}`;
@@ -164,18 +231,52 @@ function taskMessageDetails(entries: readonly unknown[], customType: string): re
 	return events;
 }
 
-function recordedEventKeys(entries: readonly unknown[]): Set<string> {
-	return new Set(entries.flatMap(entry => isRecord(entry) && entry.type === "custom" && entry.customType === TASK_RECORD_CUSTOM_TYPE
-		&& isRecord(entry.data) && typeof entry.data.taskId === "string" && typeof entry.data.eventId === "string"
-		? [key(entry.data.taskId, entry.data.eventId)] : []));
+/** Session evidence keys, derived from entries only; never task state. */
+export interface TaskEntryEvidence {
+	/** Incorporated `pi-tasks-event` event ids by task id. */
+	readonly incorporated: ReadonlyMap<string, ReadonlySet<string>>;
+	/** `pi-tasks-event-record` keys. */
+	readonly recorded: ReadonlySet<string>;
+	/** `pi-tasks-wake` keys. */
+	readonly wakes: ReadonlySet<string>;
+}
+
+interface EntryMemo extends TaskEntryEvidence {
+	readonly incorporated: Map<string, Set<string>>;
+	readonly recorded: Set<string>;
+	readonly wakes: Set<string>;
+	length: number;
+	last: unknown;
 }
 
-function taskMessageKeys(entries: readonly unknown[], customType: string): Set<string> {
-	return new Set(taskMessageDetails(entries, customType).map((event) => key(event.taskId, event.eventId)));
+const entryMemos = new WeakMap<object, EntryMemo>();
+
+/**
+ * Evidence for this session manager, extended with appended entries only. Pi entries are immutable and appended,
+ * so an unchanged entry at the last indexed position means nothing before it changed; anything else rescans.
+ */
+export function taskEntryEvidence(sessionManager: InboxContext["sessionManager"]): TaskEntryEvidence {
+	const entries = sessionManager.getEntries();
+	let memo = entryMemos.get(sessionManager);
+	if (!memo || entries.length < memo.length || (memo.length > 0 && entries[memo.length - 1] !== memo.last)) {
+		memo = { incorporated: new Map(), recorded: new Set(), wakes: new Set(), length: 0, last: undefined };
+		entryMemos.set(sessionManager, memo);
+	}
+	for (let index = memo.length; index < entries.length; index++) indexEntry(memo, entries[index]);
+	if (entries.length > memo.length) { memo.length = entries.length; memo.last = entries[entries.length - 1]; }
+	return memo;
 }
 
-function incorporatedEvents(entries: readonly unknown[]): Set<string> {
-	return taskMessageKeys(entries, TASK_EVENT_CUSTOM_TYPE);
+function indexEntry(memo: EntryMemo, entry: unknown): void {
+	if (!isRecord(entry)) return;
+	const details = entry.type === "custom" ? entry.data : entry.type === "custom_message" ? entry.details : undefined;
+	if (!isRecord(details) || typeof details.taskId !== "string" || typeof details.eventId !== "string") return;
+	if (entry.type === "custom" && entry.customType === TASK_RECORD_CUSTOM_TYPE) memo.recorded.add(key(details.taskId, details.eventId));
+	else if (entry.type === "custom_message" && entry.customType === TASK_WAKE_CUSTOM_TYPE) memo.wakes.add(key(details.taskId, details.eventId));
+	else if (entry.type === "custom_message" && entry.customType === TASK_EVENT_CUSTOM_TYPE) {
+		const events = memo.incorporated.get(details.taskId) ?? new Set<string>();
+		events.add(details.eventId); memo.incorporated.set(details.taskId, events);
+	}
 }
 
 function isTaskEvent(value: unknown): value is TaskEvent {

package/src/task-protocol.ts

@@ -5,19 +5,50 @@ 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 { isBlockedOutboxDeliveryCode } from "./task-errors";
+
+export interface TaskEventTypeSpec {
+	/** Inserted into the model and woken; otherwise archived as evidence only. */
+	readonly visible: boolean;
+	/** Ends the task; `status` is the task status it sets. */
+	readonly terminal: boolean;
+	readonly status?: Exclude<TaskRecord["status"], "active">;
+	/** Peer conversation that carries the sender's intent identity. */
+	readonly conversational: boolean;
+	/** Origin-local delivery evidence, never forwarded to the worker. */
+	readonly evidence: boolean;
+	/** A receiver may submit it as a raw intent. */
+	readonly intent: boolean;
+}
+
+const eventType = (flags: Partial<TaskEventTypeSpec>): TaskEventTypeSpec => ({ visible: true, terminal: false, conversational: false, evidence: false, intent: false, ...flags });
+
+/** Every canonical task event type this protocol version accepts, with its handling. */
+export const TASK_EVENT_TYPES: Readonly<Record<string, TaskEventTypeSpec>> = {
+	"task.created": eventType({}),
+	/** Origin moved an active task to its lost target's successor; travels as an assignment carrying the history. */
+	"task.reassigned": eventType({}),
+	"task.completed": eventType({ terminal: true, status: "completed", intent: true }),
+	"task.failed": eventType({ terminal: true, status: "failed", intent: true }),
+	"task.cancelled": eventType({ terminal: true, status: "cancelled", intent: true }),
+	"task.timed_out": eventType({ terminal: true, status: "timed_out" }),
+	"task.information": eventType({ conversational: true, intent: true }),
+	"task.question": eventType({ conversational: true, intent: true }),
+	"task.answer": eventType({ conversational: true, intent: true }),
+	"task.delivery_receipt": eventType({ visible: false, evidence: true, intent: true }),
+	"task.parent_acknowledged": eventType({ visible: false }),
+	"task.late_terminal": eventType({ visible: false }),
+};
+
+export function taskEventTypes(predicate: (type: TaskEventTypeSpec) => boolean): ReadonlySet<string> {
+	return new Set(Object.entries(TASK_EVENT_TYPES).flatMap(([type, spec]) => predicate(spec) ? [type] : []));
+}
+
+/**
+ * Ordered receiver_recorded < pi_inserted < wake_accepted; a later stage implies the earlier ones.
+ * Receivers emit the highest stage reached per refresh plus pi_insertion blocked. wake_requested is
+ * accepted from 0.1.15 receivers but no longer emitted.
+ */
 export const TaskDeliveryStage = {
 	receiverRecorded: "receiver_recorded",
 	piInsertion: "pi_insertion",