@sgtbeatdown/pi-tasks 0.1.7 → 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.
@@ -33,13 +114,13 @@ IMPLEMENTER_MODEL="${WOLFPACK_IMPLEMENTER_MODEL:-openai-codex/gpt-5.6-terra}"
 REVIEWER_MODEL="${WOLFPACK_REVIEWER_MODEL:-openai-codex/gpt-5.6-sol}"
 ```
 
-1. create or select a role session. For a disposable worker, omit an initial assignment prompt and pass the resolved role model: `wolfpack agent spawn <project> --name <task-role> --model "$IMPLEMENTER_MODEL" --json` (or `"$REVIEWER_MODEL"` for review). Put all worker instructions in `agent_task_send.task` so the new Pi process can become idle before assignment.
-2. verify structured session readiness, wait for extension registration, and read `taskEndpoint` from `wolfpack session status <session> --json`.
-3. call `agent_task_send` with that endpoint and the complete instructions. Keep working; use `agent_task_status` or `agent_task_inbox` for structured evidence, and call `agent_task_wait` only when explicitly asked to block.
+1. create or select a role session. For a new endpoint worker, use its explicit root and resolved role model without a startup assignment: `wolfpack agent spawn --project-dir /absolute/worktree --name <task-role> --model "$IMPLEMENTER_MODEL" --task-worker --readiness-timeout-ms 30000 --json` (or `"$REVIEWER_MODEL"` for review). Put all worker instructions in `agent_task_send.task`. This Pi-only mode rejects prompts/plans and `--notify-parent`.
+2. read the ready `taskEndpoint` from creation success, or verify an existing role's structured liveness, root, harness, and endpoint through `wolfpack session status <stable-session-id> --json`. `TASK_WORKER_PREFLIGHT_FAILED` precedes creation; `TASK_WORKER_NOT_READY` retains `createdSession` and `cleanup`. Inspect an `unconfirmed` cleanup by exact stable ID before retrying. Registration is not model/task execution evidence; report unsupported readiness instead of silently falling back.
+3. call `agent_task_send` with that endpoint and the complete instructions. Continue useful independent coordinator work; when none remains, yield the current turn and let structured task follow-up wake the parent. Do not poll `agent_task_status` or `agent_task_inbox` merely to wait; reserve them for concrete progress evidence or recovery, and call `agent_task_wait` only when explicitly asked to block.
 4. use `agent_task_message` for durable questions, answers, and information. The receiver calls `agent_task_done` as its final action; no completion prose follows.
 5. independently verify the result, call `agent_task_ack({ taskId })` once for that terminal task, then explicitly retain or close only the role sessions the parent spawned.
 
-Coordinator-capable agents may delegate further when justified, and the spawning coordinator owns each child's lifecycle. After terminal completion and acknowledgment, deliberately retain the child or run `wolfpack kill <stable-session-id> --json`, then verify that exact ID is absent from `wolfpack list --json`. Never use `wolfpack session send`, `/exit`, or `/quit` for cleanup; terminal input is not Wolfpack teardown.
+Coordinator-capable agents may delegate further when justified, and the spawning coordinator owns each child's lifecycle. Endpoint assignments require terminal completion and one `agent_task_ack`; full-startup children have no task ID, so use their explicit completion/block notification and parent verification instead. Then deliberately retain the child or run `wolfpack kill <stable-session-id> --json`, and verify that exact ID is absent from `wolfpack list --json`. Never use `wolfpack session send`, `/exit`, or `/quit` for cleanup; terminal input is not Wolfpack teardown.
 
 ## worker-only execution gate
 

package/package.json

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

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

@@ -31,8 +31,9 @@ Pass `--model "$IMPLEMENTER_MODEL"` when spawning the editing implementer and `-
 
 - load this package's default extension in every participating Pi process and set `WOLFPACK_SESSION_NAME`. Set `WOLFPACK_PORT` only when the local Wolfpack control port differs from `18790`.
 - address `agent_task_send` targets only as `to: { relay, id }`. For the default Wolfpack adapter, the relay is `wolfpack-pi-tasks-v2` and the ID is opaque.
-- create a disposable worker without an initial assignment prompt: `wolfpack agent spawn <project> --name <task-role> --model "$IMPLEMENTER_MODEL" --json` (or `"$REVIEWER_MODEL"` for review). Do not start a disposable worker with a blocking “wait for assignments” prompt. Put the complete instructions in `agent_task_send.task`.
-- after the target extension registers, run structured session control (`wolfpack session status <session> --json`) and read its `taskEndpoint`. Do not derive endpoint IDs from session names, broker IDs, terminal labels, output, or prose.
+- create an endpoint worker with opt-in readiness and no initial assignment prompt: `wolfpack agent spawn --project-dir /absolute/worktree --name <task-role> --model "$IMPLEMENTER_MODEL" --task-worker --readiness-timeout-ms 30000 --json` (or `"$REVIEWER_MODEL"` for review). Use the actual explicit project root. This Pi-only mode rejects prompts/plans and `--notify-parent`; do not start a blocking “wait for assignments” prompt. Put the complete instructions in `agent_task_send.task`.
+- read the returned `taskEndpoint` after exact live session/root and relay registration readiness succeeds. For a selected existing session, inspect structured status by its stable ID. Do not derive endpoint IDs from session names, broker IDs, terminal labels, output, or prose. Registration proves neither provider/model readiness nor task execution.
+- inspect typed creation errors before retrying: `TASK_WORKER_PREFLIGHT_FAILED` precedes creation; `TASK_WORKER_NOT_READY` retains `createdSession` and `cleanup`. An `unconfirmed` cleanup requires exact-ID inspection, not an assumption that the session is gone. Do not silently fall back to ordinary spawn if the installed Wolfpack lacks readiness support; report the capability gap.
 - pass the returned endpoint without translation:
 
 ```json
@@ -49,7 +50,7 @@ The default `agent_task_send` schema is exactly `to`, `task`, and optional `time
 
 For a multi-step project phase, retain one persistent implementer and one persistent read-only reviewer. Give the implementer the whole approved phase, including required commit ordering and focused verification, rather than opening one task per issue or checkpoint. Reuse a healthy role session for corrections and follow-up review; a completed task finishes one assignment, not the underlying session. Do not rotate a healthy role session for routine corrections. Rotate only for phase completion, material context degradation, harness failure, or required specialist independence. Keep at most one active assignment per role unless the user explicitly approves parallel work.
 
-A coordinator-capable agent may delegate further when the quality or throughput gain justifies it. The spawning coordinator owns each child's complete lifecycle: record the stable session ID, acknowledge its terminal task once, then deliberately retain the child or close it with `wolfpack kill <stable-session-id> --json` and verify that exact ID is absent from `wolfpack list --json`.
+A coordinator-capable agent may delegate further when the quality or throughput gain justifies it. For an endpoint assignment, the spawning coordinator owns task lifecycle: record the stable session ID, acknowledge its terminal task once, then deliberately retain the child or close it with `wolfpack kill <stable-session-id> --json` and verify that exact ID is absent from `wolfpack list --json`. Full-startup children have no endpoint task ID; use their explicit completion/block notification plus parent verification before the same retain-or-exact-ID-kill decision.
 
 `PI_TASK_WORKER=1` sessions are leaf roles. Workers cannot call `agent_task_send`; workers cannot call `agent_task_cancel`; workers cannot call `agent_task_ack`. These coordinator-tool attempts are blocked with the stable reason `PI_TASK_WORKER_COORDINATION_FORBIDDEN`, not the pre-assignment reason. They may use `agent_task_message` only for the eligible incorporated assignment named by its input `taskId`. Generic role-orchestration guidance applies only to non-worker coordinators. Task workers must not create, rotate, or close Wolfpack sessions through shell or session-control tools.
 
@@ -70,9 +71,9 @@ Assignment completion ends the assigned task, not the reusable role session. Whe
 
 ## v2 workflow
 
-1. create or select the role session, verify its structured project and terminal readiness, then obtain its registered `taskEndpoint`.
+1. create a role session through the readiness path above, or select an existing role by stable ID and verify its structured liveness, canonical project, Pi harness, and registered `taskEndpoint`. Never use terminal output as readiness evidence.
 2. call `agent_task_send` with the opaque endpoint and concise instructions in `task`. The tool returns after relay acceptance only, not Pi insertion or model execution. If submission reports a retryable delivery error after local persistence, use the structured task ID from the error and inspect it rather than creating an unrelated replacement.
-3. keep working. Use `agent_task_status` or `agent_task_inbox` only at meaningful checkpoints or when progress evidence is needed; do not turn status checks into lifecycle chatter. Call `agent_task_wait` only when the user explicitly asks to block.
+3. after `agent_task_send`, continue useful independent coordinator work. When none remains, yield the current turn and let structured task follow-up wake the parent; do not poll `agent_task_status` or `agent_task_inbox` merely to wait. Reserve those tools for concrete progress evidence or recovery, and call `agent_task_wait` only when the user explicitly asks to block.
 4. use `agent_task_message` for durable `question`, `answer`, or `information` flow. Do not use rendered text, terminal output, or logs as lifecycle evidence.
 5. assignees call `agent_task_done` as their final action with the assigned task ID, terminal status, concise summary, and optional structured result, error, and artifact declarations. Report source modifications in `result.changedFiles`; artifacts are receiver-project-relative regular files for a parent to inspect, not changed-file lists: `{ "result": { "changedFiles": ["src/extension.ts"] }, "artifacts": [{ "path": "verification/task-2.md" }] }`. No prose completion afterward.
 6. the parent independently verifies files, diff, tests, and artifacts. Then call `agent_task_ack({ taskId })` for that one terminal task and explicitly retain or close the spawned role session.

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();
 }