@sgtbeatdown/pi-tasks 0.1.8 → 0.1.9

package/README.md

@@ -24,6 +24,87 @@ The `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`.
 
 Wolfpack owns durable mailbox delivery and peer forwarding; Pi owns lifecycle, logical event order, receipts, and local SQLite state. `agent_task_send` returns after relay acceptance only, not Pi insertion or model execution. The receiver inserts model-visible events as structured `pi-tasks-event` custom messages through Pi's safe `deliverAs: "followUp"` queue and records structured `{ taskId, eventId }` insertion evidence. Replay after Pi has structurally recorded an event cannot create another logical receipt. `createInMemoryTaskRelay` remains exported solely as a deterministic conformance fixture.
 
+## retry-content stability (0.1.9)
+
+New core-originated internal `RelayEnvelope` records persist an immutable ISO
+`createdAt` alongside their outbox payload, before relay submission. Assignment,
+intent and canonical-event envelopes all use that stored value on every Wolfpack
+send, including after adapter/core/store restart. This is **not** a new
+`agent_task_send` tool argument or a change to canonical task event authority.
+The existing outbox serialization owns the metadata; no new database/schema or
+relay spool is introduced. Wolfpack still hashes the full wire envelope, including
+its timestamp: genuinely changed timestamp or payload must continue to conflict.
+
+**Upgrade caveat:** pending envelopes written by older versions have no original
+wire timestamp. The old adapter generated it on each attempt, so neither a new
+wall-clock value nor an in-memory cache can reconstruct an already accepted
+request safely. Missing/invalid metadata now fails before any relay request with
+non-retryable `INVALID_RELAY_METADATA`; the core quarantines that pending envelope
+unchanged using its existing delivery-blocked mechanism. Already accepted outbox
+records and canonical task status are not rewritten. Inspect affected work and
+its possibly-accepted outcome before choosing an explicit replacement; do not
+blindly mint a new identity or silently backfill timestamps. Existing endpoint
+rotation handling remains separate.
+
+This correction alone does not activate Wolfpack's memory-owned transport. Sparse
+cursor negotiation, live-process epoch reset and volatile forwarding outcomes
+still require coordinated changes with Wolfpack #351; old forwarding acceptance
+and cursor assumptions are not claimed fixed here.
+
+### real-relay retry regression
+
+The ordinary tests use private fixtures. An optional cross-repository test also
+runs the real core and adapter against a privately rooted real Wolfpack gateway
+over loopback HTTP, loses a response after acceptance, reopens the endpoint store
+and recreates the adapter, then verifies duplicate acceptance and genuine content
+conflicts. Select a trusted, tracked-clean Wolfpack checkout and exact revision:
+
+```bash
+PI_TASKS_WOLFPACK_SOURCE=/absolute/wolfpack-checkout \
+PI_TASKS_WOLFPACK_REVISION=<full-commit-id> \
+bun test tests/wolfpack-real-relay-retry.test.ts
+```
+
+Without that explicit source selection the cross-repository test is skipped.
+It does not contact an installed server, live broker or Tailnet peer, and is not
+an end-to-end Pi/model execution, two-host, or volatile-profile test.
+
+## endpoint-view and delivery-checkpoint corrections (0.1.9)
+
+Peer relay aliases are local routing names, not globally portable endpoint
+identities. On receipt, the adapter projects only protocol-defined assignment and
+canonical-event references into the recipient's namespace. The transport header
+supplies the authenticated source peer route and local destination; sender-local
+source IDs, peer-target IDs, and assignment/event reference agreement must match
+before projection. Arbitrary application payloads, event IDs/order, outgoing wire
+bytes, and historical task records are unchanged. Core ownership comparisons stay
+strict. This relies on Wolfpack enforcing its trusted-peer ingress policy; the
+adapter does not authenticate a peer by trusting a payload label.
+
+Delivery ACKs acknowledge one envelope, **not** a cursor prefix. The core now
+tracks observed pending cursor→envelope bindings and a conservative checkpoint in
+endpoint-scoped `relay_state` metadata (existing SQLite schema 5, no migration).
+A later automatic intent ACK cannot advance the checkpoint past an earlier
+unacknowledged assignment. ACK intents are persisted before the request and only
+those requested ACKs are retried on connect/receive after a response loss or
+reopen. They use the durable envelope ID, not a receive-time RAM cache. Pending
+bindings are removed after confirmation; the checkpoint/high-water mark does not
+retain an individual completed-ACK history. Retired endpoint bindings are fenced.
+Existing potentially unsafe checkpoints are **not** silently rewound or repaired.
+
+The in-memory conformance fixture now models individual ACKs too. Optional
+`tests/wolfpack-real-peer-core.test.ts` uses the same explicit trusted Wolfpack
+source/revision variables as the retry test above. It exercises actual adapters,
+cores, SQLite and two current v2 gateways over private loopback HTTP, including ACK
+response loss/reopen, both-direction task messages and canonical/self fanout.
+Broker/topology are synthetic: this is not live Tailnet/auth, compiled-worker,
+physical-device or Pi/model execution proof.
+
+These corrections do **not** activate the memory-owned profile. Negotiated profile/epoch
+binding, actual sparse HTTP delivery cursors, live reset/rebind and terminal
+forwarding outcomes remain outstanding. Endpoint-scoped checkpoints are not a
+substitute for binding the future volatile adapter to its exact relay epoch.
+
 ## delegation workflow
 
 Configure Pi role models with `WOLFPACK_IMPLEMENTER_MODEL` and `WOLFPACK_REVIEWER_MODEL`; they default to `openai-codex/gpt-5.6-terra` and `openai-codex/gpt-5.6-sol`. Explicit user or project choices override those defaults.

package/package.json

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

package/src/in-memory-task-relay.ts

@@ -31,7 +31,7 @@ export class InMemoryTaskRelay implements TaskRelay {
 	private readonly endpoints = new Map<string, TaskEndpoint>();
 	private readonly mailboxes = new Map<string, MailboxItem[]>();
 	private readonly accepted = new Set<string>();
-	private readonly acknowledged = new Map<string, number>();
+	private readonly acknowledged = new Set<string>();
 	private nextDelivery = 0;
 	private sendFailure = false;
 
@@ -72,11 +72,10 @@ export class InMemoryTaskRelay implements TaskRelay {
 		this.assertEndpoint(input.endpoint);
 		const mailbox = this.mailboxes.get(input.endpoint.id);
 		if (!mailbox) throw new TaskProtocolError("UNREGISTERED_TARGET", "endpoint is not registered for this protocol");
-		const acknowledged = this.acknowledged.get(input.endpoint.id) ?? 0;
 		const cursor = Number(input.cursor);
 		if (!Number.isSafeInteger(cursor) || cursor < 0) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
-		const start = Math.max(acknowledged, cursor);
-		const pending = mailbox.filter((item) => Number(item.cursor) > start);
+		const start = cursor;
+		const pending = mailbox.filter((item) => Number(item.cursor) > start && !this.acknowledged.has(item.envelope.envelopeId));
 		const deliveries = pending.slice(0, input.limit);
 		return {
 			deliveries,
@@ -89,7 +88,9 @@ export class InMemoryTaskRelay implements TaskRelay {
 		this.assertEndpoint(input.endpoint);
 		const cursor = Number(input.cursor);
 		if (!Number.isSafeInteger(cursor) || cursor < 0) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
-		this.acknowledged.set(input.endpoint.id, Math.max(this.acknowledged.get(input.endpoint.id) ?? 0, cursor));
+		const item = this.mailboxes.get(input.endpoint.id)?.find(item => item.cursor === input.cursor);
+		if (!item) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not in this endpoint mailbox");
+		this.acknowledged.add(item.envelope.envelopeId);
 	}
 
 	failNextSend(): void {

package/src/task-core.ts

@@ -1,5 +1,6 @@
 import {
 	MAX_RELAY_PAYLOAD_BYTES,
+	INVALID_RELAY_METADATA,
 	ORIGIN_CANCELLATION_OPERATION,
 	PARENT_ACKNOWLEDGMENT_OPERATION,
 	TASK_PROTOCOL_VERSION,
@@ -84,6 +85,19 @@ type ReceivedEnvelope =
 export function createTaskCore(options: TaskCoreOptions): TaskCore {
 	const clock = options.clock ?? { now: (): number => Date.now() };
 	const ids = options.ids ?? (() => crypto.randomUUID());
+	const acknowledgeRelayDelivery = async (cursor: string, signal?: AbortSignal): Promise<void> => {
+		if (!decimal(cursor)) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
+		const envelopeId = options.store.pendingRelayEnvelopeId(options.endpoint, cursor);
+		if (envelopeId === undefined) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not pending in this endpoint scope");
+		options.store.transaction(() => options.store.requestRelayAcknowledgement(options.endpoint, cursor));
+		await options.relay.acknowledgeDelivery({ endpoint: options.endpoint, cursor, envelopeId }, signal);
+		options.store.transaction(() => options.store.acknowledgeRelayCursor(options.endpoint, cursor));
+	};
+	const retryRequestedAcknowledgements = async (signal?: AbortSignal): Promise<void> => {
+		for (const cursor of options.store.requestedRelayAcknowledgements(options.endpoint)) {
+			if (options.store.pendingRelayEnvelopeId(options.endpoint, cursor) !== undefined) await acknowledgeRelayDelivery(cursor, signal);
+		}
+	};
 	const submitIntentWithOutcome = async (input: SubmitIntentInput, signal?: AbortSignal): Promise<SubmitIntentOutcome> => {
 		if (!RECEIVER_INTENT_TYPES.has(input.type) || !isRecord(input.payload)) throw new TaskProtocolError("INVALID_INTENT", "intent type or payload is invalid");
 		let persistedEnvelopeIds: readonly string[] = [];
@@ -121,6 +135,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			const connection = await options.relay.connect({ endpoint: options.endpoint, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: options.store.getReceiveCursor() }, signal);
 			if (!sameEndpoint(connection.endpoint, options.endpoint)) throw new TaskProtocolError("INVALID_CONNECTION", "relay connected a different endpoint");
 			throwIfAborted(signal);
+			await retryRequestedAcknowledgements(signal);
 		},
 		async createTask(input, signal) {
 			if (input.task.length === 0 || !Number.isInteger(input.timeoutMs) || input.timeoutMs < 1) throw new TaskProtocolError("INVALID_TASK", "task and a positive timeout are required");
@@ -133,7 +148,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 				createdAt: now, expiresAt: now + input.timeoutMs, status: "active",
 			};
 			const created = event(task, ids(), "task.created", "1", options.endpoint, target, now, { task: input.task });
-			const assignment = envelope(ids(), options.endpoint, target, taskId, TaskEnvelopeKind.assignment, { task, event: created });
+			const assignment = envelope(ids(), options.endpoint, target, taskId, TaskEnvelopeKind.assignment, { task, event: created }, now);
 			options.store.transaction(() => {
 				options.store.putTask(task);
 				options.store.appendEvent(created);
@@ -150,12 +165,23 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 		listTasks() { return options.store.listTasks(); },
 		async flushOutbox(signal) { await flush(options, signal); },
 		async receive(signal) {
+			await retryRequestedAcknowledgements(signal);
 			await flush(options, signal, IGNORE_OUTBOX_FAILURES);
-			const page = await options.relay.receive({ endpoint: options.endpoint, cursor: options.store.getReceiveCursor(), limit: RECEIVE_PAGE_SIZE }, signal);
+			const cursor = options.store.getReceiveCursor();
+			const page = await options.relay.receive({ endpoint: options.endpoint, cursor, limit: RECEIVE_PAGE_SIZE }, signal);
 			if (!isInboxPage(page)) throw new TaskProtocolError("INVALID_INBOX", "relay returned an invalid inbox page");
+			let previous = BigInt(cursor);
+			for (const delivery of page.deliveries) {
+				if (!isDelivery(delivery) || !sameEndpoint(delivery.envelope.target, options.endpoint) || BigInt(delivery.cursor) <= previous) throw new TaskProtocolError("INVALID_DELIVERY", "relay returned an invalid or unordered delivery");
+				previous = BigInt(delivery.cursor);
+			}
+			if (BigInt(page.nextCursor) < previous) throw new TaskProtocolError("INVALID_INBOX", "relay page cursor precedes its deliveries");
+			// Track the entire observed prefix before an intent can ACK a later
+			// delivery. Keep only pending IDs plus a high-water mark, durably.
+			options.store.transaction(() => options.store.trackRelayDeliveries(options.endpoint, page.deliveries.map(delivery => ({ cursor: delivery.cursor, envelopeId: delivery.envelope.envelopeId }))));
 			const visibleDeliveries: RelayDelivery[] = [];
 			for (const delivery of page.deliveries) {
-				if (!isDelivery(delivery)) throw new TaskProtocolError("INVALID_DELIVERY", "relay returned an invalid delivery");
+				if (options.store.pendingRelayEnvelopeId(options.endpoint, delivery.cursor) === undefined) continue;
 				const received = validateReceivedEnvelope(options, delivery.envelope);
 				let persistedEnvelopeIds: readonly string[] = [];
 				options.store.transaction(() => {
@@ -171,11 +197,7 @@ export function createTaskCore(options: TaskCoreOptions): TaskCore {
 			}
 			return visibleDeliveries;
 		},
-		async acknowledgeRelayDelivery(cursor, signal) {
-			if (!decimal(cursor)) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor must be a non-negative integer");
-			await options.relay.acknowledgeDelivery({ endpoint: options.endpoint, cursor }, signal);
-			options.store.transaction(() => { options.store.setReceiveCursor(cursor); });
-		},
+		acknowledgeRelayDelivery,
 		async submitIntent(input, signal) { await submitIntentWithOutcome(input, signal); },
 		submitIntentWithOutcome,
 		async recordInsertion(input, signal) {
@@ -306,7 +328,7 @@ function persistIntent(options: TaskCoreOptions, now: () => number, ids: () => s
 		}
 	}
 	options.store.putIntent(intent.intentId, input.taskId, envelopeId);
-	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent));
+	options.store.putOutbox(envelope(envelopeId, options.endpoint, task.origin, input.taskId, TaskEnvelopeKind.intent, intent, now()));
 	return { envelopeIds: [envelopeId], outcome: { authority: "receiver" } };
 }
 
@@ -346,8 +368,8 @@ function canonicalize(options: TaskCoreOptions, now: () => number, ids: () => st
 	const type = terminal && TERMINAL_STATUSES.has(task.status) ? "task.late_terminal" : requestedType;
 	const sequence = String(task.events.length + 1);
 	const canonical = event(task, ids(), type, sequence, options.endpoint, task.target, now(), { intentId: intent.intentId, ...intent.payload });
-	const targetEnvelope = envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
-	const originEnvelope = sameEndpoint(task.origin, task.target) ? undefined : envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical);
+	const targetEnvelope = envelope(ids(), options.endpoint, task.target, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
+	const originEnvelope = sameEndpoint(task.origin, task.target) ? undefined : envelope(ids(), options.endpoint, task.origin, task.taskId, TaskEnvelopeKind.canonicalEvent, canonical, canonical.occurredAt);
 	const persistedEnvelopeIds = originEnvelope === undefined ? [targetEnvelope.envelopeId] : [targetEnvelope.envelopeId, originEnvelope.envelopeId];
 	if (operation !== undefined) {
 		const reservation = options.store.reserveTaskOperation({ taskId: task.taskId, operation, logicalId: canonical.eventId, logicalType: canonical.type, envelopeIds: persistedEnvelopeIds });
@@ -378,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 && error.code === TARGET_NOT_REGISTERED_CODE && !error.retryable) {
+			if (error instanceof TaskProtocolError && (error.code === TARGET_NOT_REGISTERED_CODE || error.code === INVALID_RELAY_METADATA) && !error.retryable) {
 				options.store.transaction(() => {
 					options.store.quarantineOutbox(record.envelope.envelopeId, {
 						errorCode: error.code,
@@ -413,8 +435,8 @@ function event(task: Omit<TaskRecord, "events">, eventId: string, type: string,
 	return { eventId, taskId: task.taskId, type, sequence, source, target, occurredAt, payload };
 }
 
-function envelope(envelopeId: string, source: TaskEndpoint, target: TaskEndpoint, taskId: string, kind: RelayEnvelope["kind"], payload: unknown): RelayEnvelope {
-	return { envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId, kind, payload: JSON.stringify(payload) };
+function envelope(envelopeId: string, source: TaskEndpoint, target: TaskEndpoint, taskId: string, kind: RelayEnvelope["kind"], payload: unknown, createdAt: number): RelayEnvelope {
+	return { envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId, kind, payload: JSON.stringify(payload), createdAt: new Date(createdAt).toISOString() };
 }
 
 function parsePayload(envelope: RelayEnvelope): unknown {

package/src/task-protocol.ts

@@ -1,5 +1,6 @@
 export const TASK_PROTOCOL_VERSION = "pi-tasks/v2" as const;
 export const MAX_RELAY_PAYLOAD_BYTES = 48 * 1024;
+export const INVALID_RELAY_METADATA = "INVALID_RELAY_METADATA";
 export const ORIGIN_CANCELLATION_OPERATION = "origin_cancellation";
 export const PARENT_ACKNOWLEDGMENT_OPERATION = "parent_acknowledgment";
 export const TERMINAL_INTENT_OPERATION = "terminal_intent";
@@ -54,6 +55,9 @@ export interface RelayEnvelope {
 	readonly target: TaskEndpoint;
 	readonly taskId: string;
 	readonly kind: TaskEnvelopeKind;
+	/** Immutable transport creation time, persisted with new outbox envelopes.
+	 * Received/legacy records may omit it; Wolfpack sends require it. */
+	readonly createdAt?: string;
 	/** Opaque to relays. The endpoint protocol defines its JSON representation. */
 	readonly payload: string;
 }
@@ -82,6 +86,8 @@ export interface RelayInboxPage {
 export interface RelayDeliveryAck {
 	readonly endpoint: TaskEndpoint;
 	readonly cursor: string;
+	/** Durable cursor-to-envelope binding, for identical ACK retry after reopen. */
+	readonly envelopeId?: string;
 }
 
 export interface TaskRelay {
@@ -90,6 +96,7 @@ export interface TaskRelay {
 	resolve(input: RelayTargetReference, signal?: AbortSignal): Promise<TaskEndpoint>;
 	send(input: RelayEnvelope, signal?: AbortSignal): Promise<RelayAcceptance>;
 	receive(input: RelayReceiveRequest, signal?: AbortSignal): Promise<RelayInboxPage>;
+	/** Acknowledge this delivery only, never an implicit cursor prefix. */
 	acknowledgeDelivery(input: RelayDeliveryAck, signal?: AbortSignal): Promise<void>;
 }
 

package/src/task-relay-conformance.ts

@@ -5,6 +5,16 @@ import type { TaskRelay } from "./task-protocol";
 
 /** Shared assertions external relay adapters can run against their implementation. */
 export function runTaskRelayConformance(createRelay: () => TaskRelay): void {
+	test("acknowledging a later delivery retains earlier unacknowledged mail", async () => {
+		const relay = createRelay();
+		const source = { relay: relay.id, id: "source" }, target = { relay: relay.id, id: "target" };
+		for (const endpoint of [source, target]) await relay.connect({ endpoint, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
+		for (const envelopeId of ["first", "second"]) await relay.send({ envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task", kind: "assignment", payload: "{}", createdAt: new Date().toISOString() });
+		const page = await relay.receive({ endpoint: target, cursor: "0", limit: 10 });
+		expect(page.deliveries).toHaveLength(2);
+		await relay.acknowledgeDelivery({ endpoint: target, cursor: page.deliveries[1]!.cursor });
+		expect((await relay.receive({ endpoint: target, cursor: "0", limit: 10 })).deliveries.map(d => d.envelope.envelopeId)).toContain("first");
+	});
 	test("enforces registration, accepts duplicate envelopes once, and retains delivery until acknowledgement", async () => {
 		const relay = createRelay();
 		const source = { relay: relay.id, id: "source" };
@@ -12,7 +22,7 @@ export function runTaskRelayConformance(createRelay: () => TaskRelay): void {
 		await relay.connect({ endpoint: source, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
 		await relay.connect({ endpoint: target, protocolVersion: TASK_PROTOCOL_VERSION, receiveCursor: "0" });
 		await expect(relay.resolve({ relay: relay.id, reference: "missing" })).rejects.toThrow("not registered");
-		const envelope = { envelopeId: "envelope-1", protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task-1", kind: "assignment" as const, payload: "{}" };
+		const envelope = { envelopeId: "envelope-1", protocolVersion: TASK_PROTOCOL_VERSION, source, target, taskId: "task-1", kind: "assignment" as const, payload: "{}", createdAt: new Date(0).toISOString() };
 		await relay.send(envelope);
 		await relay.send(envelope);
 		const page = await relay.receive({ endpoint: target, cursor: "0", limit: 10 });

package/src/task-store.ts

@@ -4,7 +4,7 @@ import { dirname, join } from "node:path";
 
 import { openSqliteDatabase } from "./sqlite-database";
 import type { SqliteDatabase } from "./sqlite-database";
-import { TERMINAL_INTENT_OPERATION } from "./task-protocol";
+import { TERMINAL_INTENT_OPERATION, TaskProtocolError } from "./task-protocol";
 import type { RelayEnvelope, TaskEndpoint, TaskEvent, TaskRecord, TaskSnapshot, TerminalDeliveryState, TerminalTaskIntentType } from "./task-protocol";
 
 const SCHEMA_VERSION = 5;
@@ -57,6 +57,11 @@ export interface TaskStore {
 	persistInbox(envelope: RelayEnvelope, cursor: string): boolean;
 	getReceiveCursor(): string;
 	setReceiveCursor(cursor: string): void;
+	trackRelayDeliveries(endpoint: TaskEndpoint, deliveries: readonly { readonly cursor: string; readonly envelopeId: string }[]): void;
+	pendingRelayEnvelopeId(endpoint: TaskEndpoint, cursor: string): string | undefined;
+	requestRelayAcknowledgement(endpoint: TaskEndpoint, cursor: string): void;
+	requestedRelayAcknowledgements(endpoint: TaskEndpoint): readonly string[];
+	acknowledgeRelayCursor(endpoint: TaskEndpoint, cursor: string): void;
 	putIntent(intentId: string, taskId: string, envelopeId: string): void;
 	putInsertionReceipt(taskId: string, eventId: string): boolean;
 	reserveTaskOperation(input: TaskOperationRecord): { readonly created: boolean; readonly record: TaskOperationRecord };
@@ -155,6 +160,39 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
 		setReceiveCursor(cursor) {
 			database.query("INSERT INTO relay_state (name, value) VALUES ('receive_cursor', ?) ON CONFLICT(name) DO UPDATE SET value = excluded.value").run(cursor);
 		},
+		trackRelayDeliveries(endpoint, deliveries) {
+			const state = deliveryCheckpoint(endpoint);
+			const priorHighWater = BigInt(state.highWater);
+			for (const delivery of deliveries) {
+				const prior = state.pending[delivery.cursor];
+				if (prior !== undefined && prior !== delivery.envelopeId) throw new TaskProtocolError("INVALID_CURSOR", "relay cursor changed envelope identity");
+				// A previously observed but no longer pending cursor was ACKed. In
+				// particular, legacy relays may still return ACKed rows on reread.
+				if (BigInt(delivery.cursor) > priorHighWater) state.pending[delivery.cursor] = delivery.envelopeId;
+				if (BigInt(delivery.cursor) > BigInt(state.highWater)) state.highWater = delivery.cursor;
+			}
+			writeDeliveryCheckpoint(endpoint, state);
+		},
+		pendingRelayEnvelopeId(endpoint, cursor) { return deliveryCheckpoint(endpoint).pending[cursor]; },
+		requestRelayAcknowledgement(endpoint, cursor) {
+			const state = deliveryCheckpoint(endpoint);
+			if (state.pending[cursor] === undefined) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery is not pending in this endpoint scope");
+			(state.requested ??= {})[cursor] = true;
+			writeDeliveryCheckpoint(endpoint, state);
+		},
+		requestedRelayAcknowledgements(endpoint) { return Object.keys(deliveryCheckpoint(endpoint).requested ?? {}); },
+		acknowledgeRelayCursor(endpoint, cursor) {
+			const state = deliveryCheckpoint(endpoint);
+			// Concurrent confirmations of the same requested ACK are harmless.
+			if (state.pending[cursor] === undefined) return;
+			delete state.pending[cursor];
+			if (state.requested) delete state.requested[cursor];
+			const pending = Object.keys(state.pending);
+			if (pending.length === 0) state.frontier = state.highWater;
+			else if (BigInt(cursor) > BigInt(state.frontier) && pending.every(value => BigInt(value) > BigInt(cursor))) state.frontier = cursor;
+			writeDeliveryCheckpoint(endpoint, state);
+			store.setReceiveCursor(state.frontier);
+		},
 		putIntent(intentId, taskId, envelopeId) {
 			database.query("INSERT INTO intents (intent_id, task_id, envelope_id) VALUES (?, ?, ?) ON CONFLICT(intent_id) DO NOTHING").run(intentId, taskId, envelopeId);
 		},
@@ -185,9 +223,30 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
 		},
 		close() { database.close(); },
 	};
+	function checkpointKey(endpoint: TaskEndpoint): string {
+		const bound = store.getEndpointBinding();
+		if (bound && (bound.relay !== endpoint.relay || bound.id !== endpoint.id)) throw new TaskProtocolError("RELAY_RESET", "delivery checkpoint belongs to a retired endpoint", { retryable: false });
+		return `delivery_checkpoint:${JSON.stringify([endpoint.relay, endpoint.id])}`;
+	}
+	function deliveryCheckpoint(endpoint: TaskEndpoint): DeliveryCheckpoint {
+		const row = database.query("SELECT value FROM relay_state WHERE name = ?").get(checkpointKey(endpoint)) as { readonly value: string } | null;
+		if (row) return JSON.parse(row.value) as DeliveryCheckpoint;
+		const frontier = store.getReceiveCursor();
+		return { frontier, highWater: frontier, pending: {} };
+	}
+	function writeDeliveryCheckpoint(endpoint: TaskEndpoint, state: DeliveryCheckpoint): void {
+		database.query("INSERT INTO relay_state (name, value) VALUES (?, ?) ON CONFLICT(name) DO UPDATE SET value = excluded.value").run(checkpointKey(endpoint), JSON.stringify(state));
+	}
 	return store;
 }
 
+interface DeliveryCheckpoint {
+	frontier: string;
+	highWater: string;
+	pending: Record<string, string>;
+	requested?: Record<string, true>;
+}
+
 interface TaskRow {
 	readonly task_id: string;
 	readonly protocol_version: string;

package/src/wolfpack-endpoint-view.ts

@@ -0,0 +1,46 @@
+import { TaskProtocolError } from "./task-protocol";
+import type { RelayEnvelope, TaskEndpoint } from "./task-protocol";
+
+export const WOLFPACK_TASK_RELAY_ID = "wolfpack-pi-tasks-v2";
+const PEER = new RegExp(`^${WOLFPACK_TASK_RELAY_ID}:peer:[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$`, "i");
+
+/**
+ * Project only protocol-defined references from the sender's local namespace
+ * into the recipient's namespace. The authenticated transport header supplies
+ * the source peer route and destination identity; payload labels cannot do so.
+ * Outgoing wire bytes, opaque application payloads and historical rows stay put.
+ */
+export function wolfpackEndpointView(source: TaskEndpoint, target: TaskEndpoint, kind: RelayEnvelope["kind"], payload: unknown): unknown {
+  if (source.relay === WOLFPACK_TASK_RELAY_ID && target.relay === WOLFPACK_TASK_RELAY_ID) return payload; // Includes origin/self canonical fanout.
+  if (!PEER.test(source.relay) || target.relay !== WOLFPACK_TASK_RELAY_ID) invalid();
+  if (kind === "intent") return payload; // Intents carry no protocol endpoint references.
+  if (!record(payload)) invalid();
+  const originalSource = { relay: WOLFPACK_TASK_RELAY_ID, id: source.id };
+  const validateSource = (value: unknown): void => {
+    if (!endpoint(value) || !same(value, originalSource)) invalid();
+  };
+  const validateTarget = (value: unknown): TaskEndpoint => {
+    if (!endpoint(value) || !PEER.test(value.relay) || value.id !== target.id) invalid();
+    return value;
+  };
+  if (kind === "canonical_event") {
+    validateSource(payload.source); validateTarget(payload.target);
+    return { ...payload, source, target };
+  }
+  if (!record(payload.task) || !record(payload.event)) invalid();
+  validateSource(payload.task.origin); validateSource(payload.event.source);
+  const originalTarget = validateTarget(payload.task.target);
+  if (!endpoint(payload.event.target) || !same(payload.event.target, originalTarget)) invalid();
+  return {
+    ...payload,
+    task: { ...payload.task, origin: source, target },
+    event: { ...payload.event, source, target },
+  };
+}
+
+function invalid(): never {
+  throw new TaskProtocolError("INVALID_ENDPOINT_REFERENCE", "peer task references do not match the transport's endpoint roles", { retryable: false });
+}
+function record(value: unknown): value is Record<string, unknown> { return value !== null && typeof value === "object" && !Array.isArray(value); }
+function endpoint(value: unknown): value is TaskEndpoint { return record(value) && typeof value.relay === "string" && typeof value.id === "string"; }
+function same(a: TaskEndpoint, b: TaskEndpoint): boolean { return a.relay === b.relay && a.id === b.id; }

package/src/wolfpack-task-relay.ts

@@ -3,8 +3,9 @@ import { homedir } from "node:os";
 import { join } from "node:path";
 
 import { createTaskCore } from "./task-core";
+import { WOLFPACK_TASK_RELAY_ID, wolfpackEndpointView } from "./wolfpack-endpoint-view";
 import { createTaskStore } from "./task-store";
-import { TASK_PROTOCOL_VERSION, TaskProtocolError } from "./task-protocol";
+import { INVALID_RELAY_METADATA, TASK_PROTOCOL_VERSION, TaskProtocolError } from "./task-protocol";
 import type {
 	RelayAcceptance,
 	RelayConnectInput,
@@ -20,7 +21,7 @@ import type {
 import type { TaskCoreOptions } from "./task-core";
 import type { TaskStore, TaskStoreOptions } from "./task-store";
 
-export const WOLFPACK_TASK_RELAY_ID = "wolfpack-pi-tasks-v2";
+export { WOLFPACK_TASK_RELAY_ID } from "./wolfpack-endpoint-view";
 export const WOLFPACK_TASK_RELAY_PROTOCOL_VERSION = 2;
 export const WOLFPACK_TASK_RELAY_LEASE_MS = 60_000;
 const DEFAULT_WOLFPACK_PORT = 18_790;
@@ -139,10 +140,13 @@ export function createWolfpackTaskRelay(options: WolfpackTaskRelayOptions = {}):
 			return response.endpoint;
 		},
 		async send(input: RelayEnvelope, signal?: AbortSignal): Promise<RelayAcceptance> {
+			// Validate/capture before registration or any send. A fresh timestamp or
+			// process-local cache cannot safely retry a previously accepted envelope.
+			const envelope = toWolfpackEnvelope(input);
 			await register(signal);
 			const response = await request<WolfpackSendResponse>(requestFetch, baseUrl, requestTimeoutMs, "POST", "/api/task-relay/v2/send", {
 				callerSession: requiredSession(callerSession),
-				envelope: toWolfpackEnvelope(input),
+				envelope,
 			}, signal);
 			if (!nonEmpty(response.acceptanceId)) throw new TaskProtocolError("INVALID_ACCEPTANCE", "Wolfpack relay returned an invalid acceptance");
 			return { envelopeId: input.envelopeId };
@@ -165,9 +169,12 @@ export function createWolfpackTaskRelay(options: WolfpackTaskRelayOptions = {}):
 			return { deliveries, nextCursor: response.nextCursor, hasMore: response.hasMore || response.envelopes.length > envelopes.length };
 		},
 		async acknowledgeDelivery(input: RelayDeliveryAck, signal?: AbortSignal): Promise<void> {
-			await register(signal);
-			const envelopeId = envelopeIds.get(input.cursor);
-			if (!envelopeId) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery cursor is not available for acknowledgement");
+			const registered = await register(signal);
+			if (!sameEndpoint(input.endpoint, registered)) throw new TaskProtocolError("INVALID_CONNECTION", "delivery acknowledgement belongs to a different endpoint");
+			const cachedId = envelopeIds.get(input.cursor);
+			if (cachedId !== undefined && input.envelopeId !== undefined && cachedId !== input.envelopeId) throw new TaskProtocolError("INVALID_CURSOR", "delivery acknowledgement conflicts with its cursor binding");
+			const envelopeId = input.envelopeId ?? cachedId;
+			if (!nonEmpty(envelopeId)) throw new TaskProtocolError("INVALID_CURSOR", "relay delivery cursor is not available for acknowledgement");
 			await request<WolfpackRelayResponse>(requestFetch, baseUrl, requestTimeoutMs, "POST", "/api/task-relay/v2/delivery-ack", { callerSession: requiredSession(callerSession), envelopeId }, signal);
 			envelopeIds.delete(input.cursor);
 		},
@@ -214,6 +221,12 @@ function bindRegisteredEndpoint(store: TaskStore, endpoint: TaskEndpoint, now: n
 }
 
 function toWolfpackEnvelope(envelope: RelayEnvelope): WolfpackRelayEnvelope {
+	const createdAt = envelope.createdAt;
+	if (!transportTimestamp(createdAt)) {
+		throw new TaskProtocolError(INVALID_RELAY_METADATA, "relay envelope requires an immutable persisted creation timestamp; legacy wire metadata cannot be reconstructed safely", {
+			retryable: false, details: { envelopeId: envelope.envelopeId, reason: createdAt === undefined ? "missing" : "invalid" },
+		});
+	}
 	let payload: unknown;
 	try {
 		payload = JSON.parse(envelope.payload) as unknown;
@@ -226,7 +239,7 @@ function toWolfpackEnvelope(envelope: RelayEnvelope): WolfpackRelayEnvelope {
 		source: envelope.source,
 		target: envelope.target,
 		payload: { taskId: envelope.taskId, kind: envelope.kind, payload },
-		createdAt: new Date().toISOString(),
+		createdAt,
 	};
 }
 
@@ -236,7 +249,7 @@ function fromWolfpackEnvelope(envelope: WolfpackRelayEnvelope): RelayEnvelope {
 	}
 	const taskId = taskIdFromPayload(envelope.payload);
 	const kind = envelopeKindFromPayload(envelope.payload);
-	const payload = JSON.stringify(relayPayload(envelope.payload));
+	const payload = JSON.stringify(wolfpackEndpointView(envelope.source, envelope.target, kind, relayPayload(envelope.payload)));
 	if (payload === undefined) throw new TaskProtocolError("INVALID_PAYLOAD", "Wolfpack relay envelope payload is not JSON-serializable");
 	return { envelopeId: envelope.envelopeId, protocolVersion: TASK_PROTOCOL_VERSION, source: envelope.source, target: envelope.target, taskId, kind, payload };
 }
@@ -313,6 +326,12 @@ function boundedRequestTimeout(value: number): number {
 	return Number.isInteger(value) && value >= 1 && value <= MAX_REQUEST_TIMEOUT_MS ? value : DEFAULT_REQUEST_TIMEOUT_MS;
 }
 
+function transportTimestamp(value: unknown): value is string {
+	if (typeof value !== "string") return false;
+	const parsed = Date.parse(value);
+	return Number.isFinite(parsed) && new Date(parsed).toISOString() === value;
+}
+
 function futureTimestamp(value: unknown): value is string {
 	return typeof value === "string" && Number.isFinite(Date.parse(value)) && Date.parse(value) > Date.now();
 }