@sgtbeatdown/pi-tasks 0.1.1 → 0.1.2

package/README.md

@@ -1,6 +1,25 @@
 # pi-tasks
 
-`pi-tasks` is a Pi extension client for the Wolfpack task gateway. Wolfpack owns task state in its machine-global `~/.wolfpack/tasks` store; this package does not create task files or write assignments to terminals. Read Wolfpack's [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) for the canonical route and operational contract.
+`pi-tasks` is a Pi extension client for Wolfpack task transports. The retained v1 adapter uses Wolfpack's machine-global `~/.wolfpack/tasks` store; v2 keeps endpoint-owned Pi task state locally and uses Wolfpack as a content-blind relay. Neither adapter writes assignments to terminals. Read Wolfpack's [harness-neutral task adapter contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-adapter-contract.md) for canonical adapter behavior and its [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) for routes and operations.
+
+## v2 endpoint-owned relay
+
+The default extension uses the configured local Wolfpack relay v2 adapter, never the in-memory conformance relay. It registers an opaque endpoint with `POST /api/task-relay/v2/connect`, stores endpoint-owned task state at the deterministic per-session path `~/.pi/tasks/v2/sessions/<sha256(WOLFPACK_SESSION_NAME)>/tasks.sqlite`, and exchanges opaque relay envelopes through Wolfpack. The adapter needs a Wolfpack release exposing the stable [relay v2 control-api contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/control-api-schema.md#pi-tasks-relay-v2-boundary); a v1-only gateway is incompatible and does not silently fall back.
+
+Set `WOLFPACK_SESSION_NAME` for every Pi process. The adapter uses `WOLFPACK_PORT` when the local control port differs from `18790`; `WOLFPACK_SESSION_NAME` resolves the active Pi process to its relay endpoint. On startup, obtain a target's opaque `{ relay, id }` endpoint from its Wolfpack session-status projection after that target has registered, then send it through the endpoint-owned tool shape:
+
+```json
+{
+  "to": { "relay": "wolfpack-pi-tasks-v2", "id": "target-opaque-endpoint-id" },
+  "task": "implement the narrow change and run focused tests"
+}
+```
+
+Wolfpack's relay owns durable mailbox delivery and peer forwarding; Pi owns task lifecycle, logical event order, receipts, and its local SQLite state. Insertion receipts are idempotent by `{ taskId, eventId }`, so replay after Pi has structurally recorded an event cannot create an additional logical receipt. `createInMemoryTaskRelay` remains exported solely as a deterministic conformance fixture.
+
+## v1 gateway adapter (retained)
+
+The v1 gateway client is available only through the published `@sgtbeatdown/pi-tasks/v1-compat-extension` entry. This is an explicit opt-in: after resolving the installed package root, add `src/v1-compat-extension.ts` as an extension path in Pi settings instead of loading the package default. The package manifest loads only `src/extension.ts` (v2); v2 does not fall back to v1 when its relay is unavailable or incompatible. Its v1 behavior and operational requirements are documented below.
 
 ## requirements and trust boundary
 
@@ -29,6 +48,20 @@ A target is always `{ machine, sessionId }`, where `sessionId` is the stable opa
 }
 ```
 
+### minimal valid send envelope
+
+```json
+{
+  "to": {
+    "machine": "local",
+    "sessionId": "receiver-broker-id"
+  },
+  "task": "implement the narrow change and run focused tests"
+}
+```
+
+`INVALID_REQUEST.error.path` is an optional RFC 6901 JSON Pointer to the rejected send field, for example `/preflight/requiredProject`; use it rather than parsing error prose. A pre-persistence validation rejection creates no task, so correct the field and retry. If creation status is uncertain, idempotency remains necessary.
+
 Remote addressing changes only `to.machine`:
 
 ```json
@@ -39,7 +72,7 @@ Context is optional, curated Markdown plus deliberately selected ref metadata. T
 
 Initial limits are 16 KiB UTF-8 each for task instructions and context summary, 48 KiB for the assignment envelope, and 64 KiB for an HTTP request body. The initial size limits require representative payload benchmarking before adjustment.
 
-`agent_task_send` waits for durable gateway receipt, not task execution. A remote initial send has one initial attempt: the receiver persists a provisional receipt, then receives sender confirmation before Pi can see the assignment. Later peer confirmation, messages, terminal updates, cancellation, delivery notices, and parent acknowledgment have four total attempts: the initial attempt plus retries around 1, 2, and 4 seconds with jitter. Exhaustion is a visible local delivery failure, not a background queue or offline dispatch promise.
+`agent_task_send` waits for durable gateway acceptance, not adapter insertion or task execution; delivery remains pending until `task.delivered`. A remote initial send has one initial attempt: the receiver persists a provisional receipt, then receives sender confirmation before Pi can see the assignment. Later peer confirmation, messages, terminal updates, cancellation, delivery notices, and parent acknowledgment have four total attempts: the initial attempt plus retries around 1, 2, and 4 seconds with jitter. Exhaustion is a visible local delivery failure, not a background queue or offline dispatch promise.
 
 Normal delegation is fire-and-forget. Use `agent_task_wait` only when the user explicitly asks to block.
 
@@ -50,30 +83,39 @@ Normal delegation is fire-and-forget. Use `agent_task_wait` only when the user e
 | `agent_task_send` | create a durable gateway assignment |
 | `agent_task_status` | read task state, history, result, and warnings |
 | `agent_task_wait` | explicitly poll a task until terminal or timeout |
-| `agent_task_inbox` | read task events; `ack: true` starts terminal parent acknowledgment |
+| `agent_task_inbox` | read task events without acknowledgment |
+| `agent_task_ack` | acknowledge one independently verified terminal task |
 | `agent_task_message` | send a durable `question`, `answer`, or `information` event |
 | `agent_task_cancel` | request cancellation |
 | `agent_task_done` | receiver-only terminal completion; terminates the tool turn |
 
 Use `agent_task_message` for clarification instead of terminal prose. Only one question can be unresolved per task; answers link to that question. Information is durable and does not change task state. An accepted receiver question terminates that receiver turn; a parent question does not.
 
-The sender gateway owns canonical event order, timeout, and terminal state. The first accepted terminal event wins. Sender timeout triggers best-effort remote cancellation; late terminals remain diagnostics. After independently verifying a terminal result, call `agent_task_inbox({ ack: true })`. Remote acknowledgment is two-phase: the receiver durably confirms pending acknowledgment before the sender records final parent acknowledgment. If that delivery fails, the task remains visible and a later explicit acknowledgment repairs it with the same event ID.
+Report source modifications in `result.changedFiles`. Artifacts are receiver-project-relative regular files for a parent to inspect, not a changed-file list:
+
+```json
+{ "result": { "changedFiles": ["src/extension.ts"] }, "artifacts": [{ "path": "verification/task-2.md" }] }
+```
+
+See the canonical Wolfpack artifact contract for provenance, containment, and warning behavior.
+
+The sender gateway owns canonical event order, timeout, and terminal state. The first accepted terminal event wins. Sender timeout triggers best-effort remote cancellation; late terminals remain diagnostics. After independently verifying one terminal result, call `agent_task_ack({ taskId })`. Remote acknowledgment is two-phase: the receiver durably confirms pending acknowledgment before the sender records final parent acknowledgment. If that delivery fails, the task remains visible and a later explicit acknowledgment repairs it with the same event ID.
 
 ## structured delivery and replay
 
-The extension polls the local gateway every five seconds and only injects events when Pi is idle with no pending messages. It uses Pi structured custom messages with `{ taskId, eventId }` details, so task context participates in the session without parsing prose.
+The extension polls the local gateway every five seconds. With no pending message, it submits each visible event as a structured custom message using Pi's safe `deliverAs: "followUp"` mode: idle Pi starts immediately, while an active turn finishes before the queued event starts the next turn. It never steers or interrupts active work. Delivery remains pending until `task.delivered`. The `{ taskId, eventId }` details let task context participate in the session without parsing prose.
 
-On start or resume it rebuilds incorporated IDs from those custom-message details. A session gets only missing events; a new Pi session in the same Wolfpack PTY gets complete active history. The receiver records gateway delivery only after the structured insertion exists. A restart after insertion and before acknowledgment therefore acknowledges the existing entry without duplicate injection. Gateway delivery is at-least-once; this does not claim exactly-once model execution.
+On start or resume it rebuilds incorporated IDs from the full durable session entry set, not only active prompt context. A session gets only missing events; a new Pi session in the same Wolfpack PTY gets complete active history. The receiver records gateway delivery only after the structured insertion exists. A restart after insertion and before acknowledgment therefore acknowledges the existing entry without duplicate injection. Unknown model-visible events fail closed without advancing the cursor. Gateway delivery is at-least-once; this does not claim exactly-once model execution.
 
 ## parent workflow
 
-1. create or select a Wolfpack Pi session with the canonical session-control workflow and retain its stable broker ID.
-2. check the target's local gateway/package requirements, then send compact instructions with curated context and selected refs only when they save receiver investigation.
+1. create or select a Wolfpack Pi session with the canonical session-control workflow and retain its stable broker ID. Spawn a disposable worker without an initial model prompt so it reaches idle before assignment; put worker instructions in `agent_task_send.task`.
+2. before remote dispatch, complete Wolfpack's [Live-peer readiness checklist](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md#live-peer-readiness-checklist) and retain operator-recorded package/reload evidence; only then check the target's local requirements and send compact instructions with curated context and selected refs when they save receiver investigation.
 3. keep working; use `agent_task_status` or `agent_task_inbox` for structured follow-up, and `agent_task_message` for questions, answers, and decisions.
 4. verify cited files, diffs, tests, and paths-only artifact metadata independently before reporting success.
 5. acknowledge the accepted terminal result, then clean up only sessions this parent spawned. Keep a reusable implementer alive while review or correction remains possible; never make workers close their own sessions.
 
-A real second peer is not currently available for live operational verification. The protocol has isolated two-server coverage, but that does not prove a particular remote Wolfpack deployment is reachable. Do not overstate remote availability or use direct peer URLs from Pi.
+Isolated coverage is the deterministic acceptance gate, but a specific live peer still requires current readiness at the time of use. If the checklist cannot pass, stop before task creation and report fixture-only verification. Do not use direct peer URLs from Pi.
 
 See `skills/wolfpack-pi-task-delegation/SKILL.md` for the operational workflow and `skills/task-context-summary/SKILL.md` for recovery/reuse summaries.
 

package/package.json

@@ -1,8 +1,12 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Durable Pi agent delegation through the Wolfpack task gateway.",
-  "module": "src/extension.ts",
+  "module": "src/index.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./v1-compat-extension": "./src/v1-compat-extension.ts"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/almogdepaz/pi-tasks.git"

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

@@ -5,7 +5,7 @@ description: Use when opening, selecting, delegating to, checking, or cleaning u
 
 # wolfpack pi task delegation
 
-use `wolfpack-tailnet-control` for session control. this skill covers gateway task lifecycle, curated context, and parent verification. Wolfpack's [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) is the canonical route, trust, retention, and federation reference.
+use `wolfpack-tailnet-control` for session control. this skill covers gateway task lifecycle, curated context, and parent verification. Pi is one conforming adapter. Wolfpack's [harness-neutral task adapter contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-adapter-contract.md) is the canonical adapter reference; its [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) covers routes, trust, retention, and federation.
 
 ## gateway requirements and addressing
 
@@ -15,30 +15,39 @@ use `wolfpack-tailnet-control` for session control. this skill covers gateway ta
 - use `machine: "local"` for same-machine work. For remote work, use only the receiver's canonical HTTPS Tailnet origin, such as `https://worker.example.ts.net`; never a terminal name, arbitrary URL, path, query, fragment, credentials, or unexpected port.
 - v1 trusts local processes and trusted Tailnet machines. Pi calls only its local gateway; gateways use direct fetch federation. JWT federation is unsupported, so do not promise remote delivery where Wolfpack global JWT requires credentials.
 
+## phase roles and handoffs
+
+For a multi-step project phase, retain one persistent implementer and one persistent read-only reviewer. Reuse a healthy role session for corrections and follow-up review; a completed task is an assignment result, not a reason to replace its session. Do not rotate a healthy role session for routine corrections. Rotate only for explicit phase completion, material context saturation, harness failure, or a required independent specialist. Keep at most one active assignment per role unless the user explicitly asks for parallel work.
+
+Persistence is a parent decision, not a default. After every verified and acknowledged terminal task, the parent must explicitly choose whether to retain or close a session it spawned. Retain it only when the parent expects concrete follow-up work; close it when the parent does not expect to use it again. Do not leave the cleanup decision implicit.
+
+Use gateway task tools for assignments, questions, decisions, completion, and acknowledgment. terminal `send` is only for explicit human steering; it is not task state, a completion channel, or a substitute for `agent_task_message`.
+
 ## workflow
 
-1. create or select an existing Pi session with canonical Wolfpack session control. Read its structured response and retain the stable broker `sessionId`.
-2. send concise opaque task instructions with `agent_task_send`. Parent normally authors optional Markdown `context.summary` and deliberately selects `context.refs` with `path`, optional `selector`, and `purpose`; refs are metadata, not copied files or transcript. Use `task-context-summary` only for recovery/reuse.
+1. create or select an existing Pi session with canonical Wolfpack session control. Reuse the phase role session when it is healthy. For a disposable worker, omit `--prompt`: `wolfpack agent spawn <project> --name <task-role> --json`. Put all worker instructions in `agent_task_send.task` so the fresh Pi process can reach idle before assignment. Do not start a disposable worker with a blocking “wait for assignments” model prompt. Read the structured spawn response and retain the stable broker `sessionId`. Before remote dispatch, complete Wolfpack's [Live-peer readiness checklist](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md#live-peer-readiness-checklist), including operator-recorded package/reload evidence; if it cannot pass, stop before task creation and report fixture-only verification.
+2. send concise opaque task instructions with `agent_task_send`. Use `context.summary` only for constraints, decisions, and recovery state, and deliberately select `context.refs` with `path`, optional `selector`, and `purpose`; refs are metadata, not copied files or transcript. Use `task-context-summary` only for recovery/reuse.
 3. include `role`, `metadata`, enforceable `preflight.requiredProject`, bounded timeout, idempotency key, and `onCompletePrompt` only when they apply. Timeout is 1000ms through 24h; default is 30 minutes. Task/context limits are 16 KiB each, assignment envelope 48 KiB, and request body 64 KiB.
 4. after durable receipt, keep working. Do not call `agent_task_wait` unless the user explicitly asks to block. Use `agent_task_status` or `agent_task_inbox` for structured follow-up.
 5. use `agent_task_message` for durable `question`, `answer`, or `information` flow. One question may be unresolved globally; answers link to it. A receiver question accepted by the sender ends the receiver turn; a parent question does not end the parent turn.
-6. assignees call `agent_task_done` exactly once as their final action with `completed`, `failed`, or `cancelled`, concise summary, and optional structured result/error/paths-only artifact metadata. No prose completion afterward.
-7. parent independently verifies files, diff, tests, and artifacts before reporting success. Then use `agent_task_inbox({ ack: true })`; remote acknowledgment is two-phase and failed propagation leaves the task visible for explicit repair. Cleanup applies only to sessions this parent spawned and only after result verification and acknowledgment. Retain reusable sessions while review or correction is pending.
+6. assignees call `agent_task_done` exactly once as their final action with `completed`, `failed`, or `cancelled`, concise summary, and optional structured result/error/artifact metadata. 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" }] }`. Follow the canonical Wolfpack artifact contract for provenance, containment, and warning behavior. No prose completion afterward.
+7. parent independently verifies files, diff, tests, and artifacts before reporting success. Then use `agent_task_ack({ taskId })` for that one verified terminal task; remote acknowledgment is two-phase and failed propagation leaves the task visible for explicit repair. After acknowledgment, explicitly decide whether the spawned session has a likely next assignment. Retain it while review, correction, or another concrete assignment is expected; otherwise close it through canonical Wolfpack session control. Cleanup applies only to sessions this parent spawned and only after result verification and acknowledgment.
 
 ## delivery and recovery
 
-`agent_task_send` returns after durable receiver-gateway receipt, not model execution. A remote initial send gets one initial attempt. The receiver stores a provisional receipt, and Pi sees the assignment only after sender receipt confirmation. Later peer events get four total attempts: initial plus retries around 1, 2, and 4 seconds with jitter. Retry exhaustion is a surfaced local delivery failure; v1 has no queue, scheduler, or offline dispatch.
+`agent_task_send` returns after durable receiver-gateway acceptance, not adapter insertion or model execution; delivery remains pending until `task.delivered`. A remote initial send gets one initial attempt. The receiver stores a provisional receipt, and Pi sees the assignment only after sender receipt confirmation. Later peer events get four total attempts: initial plus retries around 1, 2, and 4 seconds with jitter. Retry exhaustion is a surfaced local delivery failure; v1 has no gateway queue, scheduler, or offline dispatch.
 
-The sender gateway owns canonical order, expiry, and terminal choice; the first accepted terminal event wins. Sender timeout causes best-effort remote cancellation. The local extension polls every five seconds and injects only while idle with no pending messages. It stores `{ taskId, eventId }` in structured custom messages, replays missing events after restart, and records delivery only after structural insertion. Do not call that exactly-once execution.
+The sender gateway owns canonical order, expiry, and terminal choice; the first accepted terminal event wins. Sender timeout causes best-effort remote cancellation. The local extension polls every five seconds. With no pending message, it submits visible events through Pi's safe `deliverAs: "followUp"` queue: idle sessions start immediately, active turns finish first, and task delivery never steers or interrupts them. It stores `{ taskId, eventId }` in structured custom messages, replays missing events after restart, and records delivery only after structural insertion. Do not call that exactly-once execution.
 
-A real second peer is not currently available for live operational verification. Isolated two-server tests cover the direct peer protocol, but do not claim that a particular remote deployment is reachable.
+Isolated coverage is the deterministic acceptance gate, but a specific live peer still requires current readiness at the time of use. Do not claim that a particular remote deployment is reachable without the checklist evidence.
 
 ## do not
 
 - do not use terminal output as task state or completion evidence.
 - do not ask workers to complete in prose.
-- do not inject task context while Pi is busy or has pending messages.
-- do not copy whole plans, ref contents, or transcripts into task context.
+- do not steer or interrupt an active Pi turn with task context; use the adapter's follow-up queue.
+- Do not copy plans, source contents, or transcripts into task context.
 - do not use filesystem task storage or retain old `mustReturn`, `rejected`, or semantic completion contracts.
 - do not promise JWT federation, artifact byte transfer, or background retry/offline dispatch.
 - do not make workers close their own sessions.
+- do not leave a parent-spawned session open after acknowledgment when the parent does not expect further work from it.

package/src/extension.ts

@@ -3,205 +3,253 @@ import type { AgentToolResult, ExtensionAPI, ExtensionContext } from "@earendil-
 import { Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
 
-import {
-	DEFAULT_TASK_TIMEOUT_MS,
-	GatewayClientError,
-	MAX_TASK_TIMEOUT_MS,
-	MIN_TASK_TIMEOUT_MS,
-	createWolfpackGatewayClient,
-	type TaskCompletionInput,
-	type TaskStatus,
-	type WolfpackGatewayClient,
-} from "./gateway-client";
-import { deliverTaskInbox, restoredInboxCursor } from "./task-inbox";
+import { deliverTaskInbox } from "./task-inbox";
+import { TaskOutboxDeliveryError, TaskProtocolError } from "./task-protocol";
+import { createWolfpackTaskCore } from "./wolfpack-task-relay";
+import type { TaskCore } from "./task-core";
 
+const DEFAULT_TASK_TIMEOUT_MS = 30 * 60 * 1_000;
+const MIN_TASK_TIMEOUT_MS = 1_000;
+const MAX_TASK_TIMEOUT_MS = 86_400_000;
 const BACKGROUND_POLL_MS = 5_000;
+const TARGET_NOT_REGISTERED_CODE = "TARGET_NOT_REGISTERED";
 const WAIT_POLL_MS = 250;
 const SUMMARY_MAX_CHARS = 1_200;
 
-const AddressParams = Type.Object({
-	machine: Type.String({ minLength: 1, description: "local or a canonical Wolfpack machine identity" }),
-	sessionId: Type.String({ minLength: 1, description: "Stable opaque Wolfpack broker session id" }),
+const EndpointParams = Type.Object({
+	relay: Type.String({ minLength: 1, description: "relay identifier" }),
+	id: Type.String({ minLength: 1, description: "opaque endpoint identifier" }),
 });
-
-const ContextRefParams = Type.Object({
-	path: Type.String({ minLength: 1 }),
-	selector: Type.Optional(Type.String()),
-	purpose: Type.Optional(Type.String()),
-});
-
 const SendParams = Type.Object({
-	to: AddressParams,
+	to: EndpointParams,
 	task: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
-	context: Type.Optional(Type.Object({
-		summary: Type.Optional(Type.String({ minLength: 1, maxLength: 16 * 1024 })),
-		refs: Type.Optional(Type.Array(ContextRefParams)),
-	})),
-	role: Type.Optional(Type.String()),
-	preflight: Type.Optional(Type.Object({ requiredProject: Type.Optional(Type.String()) })),
-	metadata: Type.Optional(Type.Object({
-		phaseId: Type.Optional(Type.String()),
-		issueId: Type.Optional(Type.String()),
-		verificationTier: Type.Optional(Type.String()),
-		rootCause: Type.Optional(Type.String()),
-	})),
-	onCompletePrompt: Type.Optional(Type.String({ maxLength: 4_000 })),
 	timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })),
-	idempotencyKey: Type.Optional(Type.String({ minLength: 1 })),
 });
-
 const TaskIdParams = Type.Object({ taskId: Type.String({ minLength: 1 }) });
 const WaitParams = Type.Object({ taskId: Type.String({ minLength: 1 }), timeoutMs: Type.Optional(Type.Integer({ minimum: MIN_TASK_TIMEOUT_MS, maximum: MAX_TASK_TIMEOUT_MS })) });
-const InboxParams = Type.Object({ ack: Type.Optional(Type.Boolean({ default: false })), includeAcknowledged: Type.Optional(Type.Boolean({ default: false })) });
-const MessageParams = Type.Object({
-	taskId: Type.String({ minLength: 1 }),
-	type: StringEnum(["question", "answer", "information"] as const),
-	message: Type.String({ minLength: 1, maxLength: 16 * 1024 }),
-	replyToMessageId: Type.Optional(Type.String({ minLength: 1 })),
-});
+const MessageParams = Type.Object({ taskId: Type.String({ minLength: 1 }), type: StringEnum(["question", "answer", "information"] as const), message: Type.String({ minLength: 1, maxLength: 16 * 1024 }) });
 const DoneParams = Type.Object({
-	taskId: Type.String({ minLength: 1 }),
-	status: StringEnum(["completed", "failed", "cancelled"] as const),
-	summary: Type.String({ minLength: 1, maxLength: SUMMARY_MAX_CHARS }),
+	taskId: Type.String({ minLength: 1 }), status: StringEnum(["completed", "failed", "cancelled"] as const), summary: Type.String({ minLength: 1, maxLength: SUMMARY_MAX_CHARS }),
 	result: Type.Optional(Type.Record(Type.String(), Type.Unknown())),
 	error: Type.Optional(Type.Object({ code: Type.String(), message: Type.String(), retryable: Type.Boolean() })),
-	artifacts: Type.Optional(Type.Array(Type.Object({ path: Type.String({ minLength: 1 }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
+	artifacts: Type.Optional(Type.Array(Type.Object({ path: Type.String({ minLength: 1, description: "artifact paths are receiver-project-relative regular files" }), mimeType: Type.Optional(Type.String()), description: Type.Optional(Type.String()) }))),
 });
 
-export function registerAgentTaskTools(pi: ExtensionAPI, client: WolfpackGatewayClient = createWolfpackGatewayClient()): void {
-	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
+export type ConfiguredCoreFactory = (signal?: AbortSignal) => Promise<TaskCore>;
+
+/** Reuses a successful configured core while allowing the next lifecycle operation to retry a failed setup. */
+export function createConfiguredCoreLoader(factory: ConfiguredCoreFactory): ConfiguredCoreFactory {
+	let corePromise: Promise<TaskCore> | undefined;
+	return async (signal?: AbortSignal): Promise<TaskCore> => {
+		if (corePromise) return corePromise;
+		const candidate = Promise.resolve().then(() => factory(signal));
+		corePromise = candidate;
+		try {
+			return await candidate;
+		} catch (error) {
+			if (corePromise === candidate) corePromise = undefined;
+			throw error;
+		}
+	};
+}
 
-	const refreshInbox = async (ctx: ExtensionContext): Promise<void> => {
-		const cursor = restoredInboxCursor(ctx.sessionManager.getEntries());
-		await deliverTaskInbox(pi, client, ctx, cursor);
+/** Registers v2 endpoint-owned tools using a configured durable Wolfpack relay by default. */
+export function registerAgentTaskTools(pi: ExtensionAPI, core: TaskCore | undefined = undefined, createCore: ConfiguredCoreFactory = (signal) => createWolfpackTaskCore({}, signal)): void {
+	let inboxContext: ExtensionContext | undefined;
+	let backgroundTimer: ReturnType<typeof setInterval> | undefined;
+	let lifecycleEpoch = 0;
+	const configuredCore: ConfiguredCoreFactory = core === undefined ? createConfiguredCoreLoader(createCore) : async (): Promise<TaskCore> => core;
+	const refreshInbox = createSingleFlightInboxRefresh(async (signal) => {
+		const context = inboxContext;
+		if (!context) return undefined;
+		const activeCore = await configuredCore(signal);
+		if (inboxContext !== context) return undefined;
+		let outboxError: unknown;
+		try {
+			await activeCore.flushOutbox(signal);
+		} catch (error) {
+			outboxError = error;
+		}
+		if (inboxContext !== context) return undefined;
+		try {
+			await activeCore.evaluateTimeouts(signal);
+		} catch (error) {
+			outboxError ??= error;
+		}
+		if (inboxContext !== context) return undefined;
+		const isCurrent = (): boolean => inboxContext === context;
+		const guardedCore: TaskCore = {
+			...activeCore,
+			async receive(receiveSignal) {
+				const deliveries = await activeCore.receive(receiveSignal);
+				return isCurrent() ? deliveries : [];
+			},
+			async acknowledgeRelayDelivery(cursor, acknowledgementSignal) {
+				if (isCurrent()) await activeCore.acknowledgeRelayDelivery(cursor, acknowledgementSignal);
+			},
+			async recordInsertion(input, insertionSignal) {
+				if (isCurrent()) await activeCore.recordInsertion(input, insertionSignal);
+			},
+		};
+		await deliverTaskInbox({
+			sendMessage(message, options) { if (isCurrent()) pi.sendMessage(message, options); },
+			appendEntry(customType, data) { if (isCurrent()) pi.appendEntry(customType, data); },
+		}, guardedCore, {
+			hasPendingMessages: (): boolean => !isCurrent() || context.hasPendingMessages(),
+			sessionManager: context.sessionManager,
+		}, signal);
+		return outboxError;
+	});
+	const refreshLifecycle = async (context: ExtensionContext, epoch: number): Promise<void> => {
+		const isCurrent = (): boolean => lifecycleEpoch === epoch && inboxContext === context;
+		try {
+			const activeCore = await configuredCore();
+			let connectionError: unknown;
+			try {
+				await activeCore.connect();
+			} catch (error) {
+				connectionError = error;
+			}
+			if (!isCurrent()) return;
+			const outboxError = await refreshInbox();
+			if (!isCurrent()) return;
+			const lifecycleError = outboxError ?? connectionError;
+			const status = lifecycleError === undefined ? undefined : outboxFailureStatus(lifecycleError);
+			context.ui.setStatus("pi-tasks", status === undefined ? undefined : context.ui.theme.fg("warning", status));
+		} catch (error) {
+			if (isCurrent()) context.ui.setStatus("pi-tasks", context.ui.theme.fg("warning", outboxFailureStatus(error)));
+		}
 	};
 
-	pi.on("session_start", async (_event, ctx) => {
-		ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("dim", `tasks: ${client.callerSession}`));
+	pi.on("session_start", async (_event, context) => {
+		const epoch = ++lifecycleEpoch;
+		inboxContext = context;
+		if (backgroundTimer) clearInterval(backgroundTimer);
 		backgroundTimer = setInterval(() => {
-			void refreshInbox(ctx).catch(() => ctx.ui.setStatus("wolfpack-tasks", ctx.ui.theme.fg("warning", "tasks: unavailable")));
+			const currentContext = inboxContext;
+			if (currentContext) void refreshLifecycle(currentContext, epoch);
 		}, BACKGROUND_POLL_MS);
-		await refreshInbox(ctx).catch(() => undefined);
+		await refreshLifecycle(context, epoch);
 	});
-	pi.on("agent_end", async (_event, ctx) => {
-		setTimeout(() => { void refreshInbox(ctx).catch(() => undefined); }, 0);
+	pi.on("agent_end", async (_event, context) => {
+		const epoch = lifecycleEpoch;
+		inboxContext = context;
+		await refreshLifecycle(context, epoch);
 	});
 	pi.on("session_shutdown", () => {
+		lifecycleEpoch += 1;
 		if (backgroundTimer) clearInterval(backgroundTimer);
 		backgroundTimer = undefined;
+		inboxContext = undefined;
 	});
 
 	pi.registerTool({
-		name: "agent_task_send", label: "Send Agent Task", description: "Durably send a bounded task to an existing Wolfpack Pi session.",
-		promptSnippet: "Send nonblocking structured tasks through the local Wolfpack gateway",
-		promptGuidelines: ["Use agent_task_send for normal nonblocking delegation; do not wait unless the user explicitly asks."],
-		parameters: SendParams,
-		async execute(_toolCallId, params, signal) {
+		name: "agent_task_send", label: "Send Agent Task", description: "Persist an endpoint-owned task and submit its opaque assignment envelope to a relay.", parameters: SendParams,
+		async execute(_id, params, signal) {
 			try {
-				const receipt = await client.send(params, signal);
-				return toolResult(receipt, `## task received\n- task: \`${receipt.taskId}\`\n- target: \`${params.to.machine}/${params.to.sessionId}\`\n${warnings(receipt.warnings)}`);
-			} catch (error) { return clientError(error); }
-		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+				const sent = await (await configuredCore(signal)).createTask({ target: params.to, task: params.task, timeoutMs: params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS }, signal);
+				return toolResult(sent, `## task accepted\n- task: \`${sent.taskId}\`\n- target: \`${params.to.relay}/${params.to.id}\`\n- delivery: relay acceptance only`);
+			} catch (error) { return taskError(error); }
+		},
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_status", label: "Task Status", description: "Read compact structured task status from Wolfpack.", parameters: TaskIdParams,
-		async execute(_toolCallId, params, signal) {
-			try { const status = await client.status(params.taskId, signal); return statusResult(status); } catch (error) { return clientError(error); }
+		name: "agent_task_status", label: "Task Status", description: "Read local endpoint-owned task state; status is unavailable while its origin is offline.", parameters: TaskIdParams,
+		async execute(_id, params, signal) {
+			try {
+				const task = (await configuredCore(signal)).getTask(params.taskId);
+				return task ? toolResult(task, `## task status\n- task: \`${task.taskId}\`\n- status: ${task.status}`) : taskError(new Error("unknown local task"));
+			} catch (error) { return taskError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_wait", label: "Wait Agent Task", description: "Block only when explicitly invoked until a task reaches a terminal state or this wait times out.", parameters: WaitParams,
-		async execute(_toolCallId, params, signal, onUpdate) {
+		name: "agent_task_wait", label: "Wait Agent Task", description: "Wait for a locally-known endpoint-owned task to reach a terminal state.", parameters: WaitParams,
+		async execute(_id, params, signal, onUpdate) {
 			const deadline = Date.now() + (params.timeoutMs ?? DEFAULT_TASK_TIMEOUT_MS);
 			try {
 				for (;;) {
-					throwIfAborted(signal);
-					const status = await client.status(params.taskId, signal);
-					if (terminal(status.status)) return statusResult(status);
-					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: status.status, error: { code: "WAIT_TIMEOUT", retryable: true } }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${status.status}\n- wait timed out`);
+					await refreshInbox(signal);
+					const task = (await configuredCore(signal)).getTask(params.taskId);
+					if (!task) return taskError(new Error("unknown local task"));
+					if (terminal(task.status)) return toolResult(task, `## task status\n- task: \`${task.taskId}\`\n- status: ${task.status}`);
+					if (Date.now() >= deadline) return toolResult({ taskId: params.taskId, status: task.status }, `## task wait\n- task: \`${params.taskId}\`\n- status: ${task.status}\n- wait timed out`);
 					onUpdate?.({ content: [{ type: "text", text: `waiting for ${params.taskId}...` }], details: {} });
-					await sleep(Math.min(WAIT_POLL_MS, Math.max(1, deadline - Date.now())), signal);
+					await sleep(Math.min(WAIT_POLL_MS, deadline - Date.now()), signal);
 				}
-			} catch (error) { return clientError(error); }
+			} catch (error) { return taskError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_inbox", label: "Task Inbox", description: "Read inbox task events and optionally acknowledge terminal parent tasks.", parameters: InboxParams,
-		async execute(_toolCallId, params, signal) {
+		name: "agent_task_inbox", label: "Task Inbox", description: "Read local task records after processing relay deliveries without acknowledging task lifecycle.", parameters: Type.Object({}),
+		async execute(_id, _params, signal) {
 			try {
-				let cursor = "0";
-				const taskIds = new Set<string>();
-				for (;;) {
-					const page = await client.inbox(cursor, params.includeAcknowledged ?? false, signal);
-					for (const event of page.events) taskIds.add(event.taskId);
-					if (!page.hasMore) break;
-					cursor = page.nextCursor;
-				}
-				const tasks = await Promise.all([...taskIds].map((taskId) => client.status(taskId, signal)));
-				if (params.ack) await Promise.all(tasks.filter((task) => terminal(task.status)).map((task) => client.ack(task.task.taskId, signal)));
-				return toolResult({ tasks }, `## task inbox\n${tasks.length === 0 ? "- empty" : tasks.map((task) => `- \`${task.task.taskId}\`: ${task.status}${task.completion ? ` — ${task.completion.summary}` : ""}`).join("\n")}`);
-			} catch (error) { return clientError(error); }
-		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+				await refreshInbox(signal);
+				const tasks = (await configuredCore(signal)).listTasks();
+				return toolResult({ tasks }, `## task inbox\n${tasks.map((task) => `- \`${task.taskId}\`: ${task.status}`).join("\n") || "- empty"}`);
+			} catch (error) { return taskError(error); }
+		},
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_message", label: "Message Agent Task", description: "Durably send a question, answer, or information event for a task.", parameters: MessageParams,
-		async execute(_toolCallId, params, signal) {
-			try {
-				const [identity, status] = await Promise.all([client.sessionStatus(signal), client.status(params.taskId, signal)]);
-				const receipt = await client.message(params, signal);
-				const receiverQuestion = params.type === "question" && identity.sessionId === status.task.target.sessionId;
-				return { ...toolResult(receipt, `## task ${params.type}\n- task: \`${params.taskId}\`\n${params.message}`), ...(receiverQuestion ? { terminate: true } : {}) };
-			} catch (error) { return clientError(error); }
-		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+		name: "agent_task_message", label: "Message Agent Task", description: "Persist a message intent before relay submission.", parameters: MessageParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.type}`, payload: { message: params.message } }, signal); return toolResult({ taskId: params.taskId }, `## task ${params.type}\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_cancel", label: "Cancel Agent Task", description: "Request cancellation for a non-terminal task through Wolfpack.", parameters: TaskIdParams,
-		async execute(_toolCallId, params, signal) {
-			try { const receipt = await client.cancel(params.taskId, signal); return toolResult(receipt, `## task cancellation requested\n- task: \`${params.taskId}\`${warnings(receipt.warnings)}`); } catch (error) { return clientError(error); }
-		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+		name: "agent_task_cancel", label: "Cancel Agent Task", description: "Persist cancellation before relay submission.", parameters: TaskIdParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: "task.cancelled", payload: {} }, signal); return toolResult({ taskId: params.taskId }, `## task cancellation requested\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
-
 	pi.registerTool({
-		name: "agent_task_done", label: "Complete Agent Task", description: "Finish an assigned task with a structured terminal result. Use exactly once as the final action.",
-		promptSnippet: "Complete an assigned task with a terminating structured result", promptGuidelines: ["Use agent_task_done exactly once as the final action for an assigned task."], parameters: DoneParams,
-		async execute(_toolCallId, params, signal) {
+		name: "agent_task_ack", label: "Acknowledge Agent Task", description: "Record parent acknowledgement as an origin-owned logical event.", parameters: TaskIdParams,
+		async execute(_id, params, signal) { try { await (await configuredCore(signal)).acknowledgeParent(params.taskId, signal); return toolResult({ taskId: params.taskId }, `## task acknowledged\n- task: \`${params.taskId}\``); } catch (error) { return taskError(error); } },
+		renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
+	});
+	pi.registerTool({
+		name: "agent_task_done", label: "Complete Agent Task", description: "Persist a terminal task intent before relay submission.", parameters: DoneParams,
+		async execute(_id, params, signal) {
 			try {
-				const result: TaskCompletionInput = { summary: params.summary, ...(params.result && { result: params.result }), ...(params.error && { error: params.error }), ...(params.artifacts && { artifacts: params.artifacts }) };
-				const receipt = await client.complete({ taskId: params.taskId, status: params.status, result }, signal);
-				return { ...toolResult(receipt, `## task ${params.status}\n- task: \`${params.taskId}\`\n- ${params.summary}${warnings(receipt.warnings)}`), terminate: true };
-			} catch (error) { return clientError(error); }
+				await (await configuredCore(signal)).submitIntent({ taskId: params.taskId, type: `task.${params.status}`, payload: { summary: params.summary, ...(params.result === undefined ? {} : { result: params.result }), ...(params.error === undefined ? {} : { error: params.error }), ...(params.artifacts === undefined ? {} : { artifacts: params.artifacts }) } }, signal);
+				return { ...toolResult({ taskId: params.taskId }, `## task ${params.status}\n- task: \`${params.taskId}\`\n- ${params.summary}`), terminate: true };
+			} catch (error) { return taskError(error); }
 		}, renderResult(result, _options, theme) { return new Text(theme.fg("accent", text(result))); },
 	});
 }
 
-export default function piTasks(pi: ExtensionAPI): void {
-	registerAgentTaskTools(pi);
+export function createSingleFlightInboxRefresh<TValue>(refresh: (signal?: AbortSignal) => Promise<TValue>): (signal?: AbortSignal) => Promise<TValue> {
+	let inFlight: Promise<TValue> | undefined;
+	return (signal): Promise<TValue> => {
+		if (inFlight) return inFlight;
+		const current = refresh(signal).finally(() => {
+			if (inFlight === current) inFlight = undefined;
+		});
+		inFlight = current;
+		return current;
+	};
 }
 
-function statusResult(status: TaskStatus): AgentToolResult<unknown> {
-	return toolResult(status, `## task status\n- task: \`${status.task.taskId}\`\n- status: ${status.status}${status.completion ? `\n- summary: ${status.completion.summary}` : ""}${warnings(status.warnings)}`);
+export default function piTasks(pi: ExtensionAPI): void {
+	registerAgentTaskTools(pi);
 }
 
 function toolResult(details: unknown, markdown: string): AgentToolResult<unknown> {
 	return { content: [{ type: "text", text: markdown }], details };
 }
 
-function clientError(error: unknown): AgentToolResult<unknown> {
-	const gateway = error instanceof GatewayClientError ? error : new GatewayClientError("CLIENT_ERROR", error instanceof Error ? error.message : "task gateway request failed", true);
-	return toolResult({ error: { code: gateway.code, message: gateway.message, retryable: gateway.retryable } }, `## task gateway error\n- ${gateway.code}: ${gateway.message}`);
+function taskError(error: unknown): AgentToolResult<unknown> {
+	const message = error instanceof Error ? error.message : "task operation failed";
+	if (error instanceof TaskProtocolError) {
+		return toolResult({ ...error.details, error: { code: error.code, message, retryable: error.retryable } }, `## task error\n- ${message}`);
+	}
+	return toolResult({ error: { code: "TASK_ERROR", message, retryable: true } }, `## task error\n- ${message}`);
 }
 
-function warnings(values: readonly { readonly code: string; readonly message: string }[]): string {
-	return values.length === 0 ? "" : `\n## gateway warnings\n${values.map((value) => `- ${value.code}: ${value.message}`).join("\n")}`;
+function outboxFailureStatus(error: unknown): "tasks: relay unavailable" | "tasks: outbox degraded" {
+	return error instanceof TaskOutboxDeliveryError && error.code === TARGET_NOT_REGISTERED_CODE ? "tasks: outbox degraded" : "tasks: relay unavailable";
 }
 
 function terminal(status: string): boolean {
-	return status === "completed" || status === "failed" || status === "cancelled" || status === "timed_out";
+	return ["completed", "failed", "cancelled", "timed_out"].includes(status);
 }
 
 function text(result: { readonly content?: readonly unknown[] }): string {
@@ -209,14 +257,10 @@ function text(result: { readonly content?: readonly unknown[] }): string {
 	return first && typeof first === "object" && "type" in first && first.type === "text" && "text" in first && typeof first.text === "string" ? first.text : "";
 }
 
-function throwIfAborted(signal: AbortSignal | undefined): void {
-	if (signal?.aborted) throw new GatewayClientError("ABORTED", "task wait was cancelled", true);
-}
-
 async function sleep(milliseconds: number, signal: AbortSignal | undefined): Promise<void> {
+	if (signal?.aborted) throw new Error("task wait was cancelled");
 	await new Promise<void>((resolve, reject) => {
-		const timeout = setTimeout(resolve, milliseconds);
-		const abort = (): void => { clearTimeout(timeout); reject(new GatewayClientError("ABORTED", "task wait was cancelled", true)); };
-		signal?.addEventListener("abort", abort, { once: true });
+		const timer = setTimeout(resolve, Math.max(1, milliseconds));
+		signal?.addEventListener("abort", () => { clearTimeout(timer); reject(new Error("task wait was cancelled")); }, { once: true });
 	});
 }