@sgtbeatdown/pi-tasks 0.1.6 → 0.1.8

package/README.md

@@ -1,10 +1,10 @@
 # pi-tasks
 
-`pi-tasks` is a Pi extension client for Wolfpack task transports. The default v2 adapter keeps endpoint-owned Pi task state locally and uses Wolfpack as a content-blind relay; the retained v1 adapter uses Wolfpack's machine-global `~/.wolfpack/tasks` store. Neither adapter writes assignments to terminals. Wolfpack's [relay v2 control-api contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/control-api-schema.md#pi-tasks-relay-v2-boundary) is canonical for the default transport, while its [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md) documents the explicit v1 compatibility transport.
+`pi-tasks` is an endpoint-owned Pi extension for Wolfpack relay v2. It keeps task state in each Pi endpoint's local SQLite store and uses Wolfpack as a content-blind relay. It never writes assignments to terminals. Wolfpack's [relay v2 control-api contract](https://github.com/almogdepaz/wolfpack/blob/main/docs/control-api-schema.md#pi-tasks-relay-v2-boundary) is canonical for the transport boundary.
 
-## v2 endpoint-owned relay
+## 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.
+The default extension uses the configured local Wolfpack relay, never the in-memory conformance relay. It registers an opaque endpoint with `POST /api/task-relay/v2/connect`, stores 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 requires 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).
 
 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. After the target extension registers, run `wolfpack session status <session> --json` and read its `taskEndpoint`. Pass that opaque `{ relay, id }` value unchanged; do not derive it from a session name, broker ID, terminal label, output, or prose.
 
@@ -20,116 +20,42 @@ Set `WOLFPACK_SESSION_NAME` for every Pi process. The adapter uses `WOLFPACK_POR
 }
 ```
 
-The default `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`. v1-only context, role, metadata, preflight, idempotency, and completion-prompt fields are not silently accepted or translated.
+The `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`. Unsupported fields are rejected before persistence: a pre-persistence validation rejection creates no task. If creation status is uncertain after a transport failure, idempotency remains necessary; inspect the structured task ID rather than creating an unrelated replacement.
 
-Wolfpack's relay owns durable mailbox delivery and peer forwarding; Pi owns task lifecycle, logical event order, receipts, and its 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 an additional logical receipt. `createInMemoryTaskRelay` remains exported solely as a deterministic conformance fixture.
+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.
 
-### v2 delegation workflow
+## 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`, respectively. Explicit user or project choices override those defaults.
+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.
 
 ```bash
 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 task instructions. Keep working; use `agent_task_status` or `agent_task_inbox` for structured evidence, and call `agent_task_wait` only when the user explicitly asks 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.
 
-### v2 worker-only execution gate
+## worker-only execution gate
 
-Set `PI_TASK_WORKER=1` only when launching a task-only worker. The exact value enables a fail-closed model `tool_call` gate; an absent value or any other value leaves ordinary interactive Pi behavior unchanged. Before assignment, only `agent_task_inbox`, `agent_task_status`, and `agent_task_wait` are allowed. Other current and future model tools are blocked with the stable reason `PI_TASK_WORKER_ASSIGNMENT_REQUIRED`. Explicit user `!`/`!!` shell commands are outside Pi's model `tool_call` event and are not intercepted.
+Set `PI_TASK_WORKER=1` only when launching a task-only worker. The exact value enables a fail-closed model `tool_call` gate; an absent value or any other value leaves ordinary interactive Pi behavior unchanged. Before assignment, only `agent_task_inbox`, `agent_task_status`, and `agent_task_wait` are allowed. Other current and future model tools are blocked with `PI_TASK_WORKER_ASSIGNMENT_REQUIRED`. Explicit user `!`/`!!` shell commands are outside Pi's model `tool_call` event and are not intercepted.
 
-`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. `agent_task_message` is limited to the eligible incorporated assignment named by its input `taskId`. Generic role-orchestration guidance applies only to non-worker coordinators.
+`PI_TASK_WORKER=1` sessions are leaf roles. Workers cannot call `agent_task_send`, `agent_task_cancel`, or `agent_task_ack`; those attempts are blocked with `PI_TASK_WORKER_COORDINATION_FORBIDDEN`. `agent_task_message` is limited to the eligible incorporated assignment named by its input `taskId`. Generic role-orchestration guidance applies only to non-worker coordinators.
 
 The gate opens only when the current Pi session contains a structured `pi-tasks-event` entry for `task.created` and the same event belongs to a locally persisted active task targeted to the current endpoint. Rendered prompt text, terminal output, unknown events, foreign tasks, and stale terminal tasks do not authorize execution. On restart, durable session evidence reopens the gate only while the matching local task remains eligible.
 
 Preflighting `agent_task_done` marks that task as closing before sibling calls are preflighted. Ordinary tools remain blocked for a closing, pending-terminal, accepted-terminal, or `delivery_blocked` task; an idempotent `agent_task_done` retry for that same assigned task remains allowed. Another independently active assignment can still authorize work.
 
-### v2 terminal delivery and acknowledgment
+## terminal delivery and acknowledgment
 
-A receiver task snapshot reports terminal transport separately as `terminalDelivery`: `not_submitted`, `pending`, `accepted`, or `delivery_blocked`. The blocked variant includes the stable intent/envelope identities, origin endpoint, timestamp, and structured non-retryable relay error. Canonical task `status` remains origin-owned and is never changed to `delivery_blocked`. Retryable failures keep the same pending terminal intent and envelope; permanent failures remain inspectable and are not rebound to a successor endpoint without a separate authenticated Wolfpack contract.
+A receiver task snapshot reports terminal transport separately as `terminalDelivery`: `not_submitted`, `pending`, `accepted`, or `delivery_blocked`. The blocked variant includes stable intent/envelope identities, origin endpoint, timestamp, and structured non-retryable relay error. Canonical task `status` remains origin-owned and is never changed to `delivery_blocked`. Retryable failures keep the same pending terminal intent and envelope; permanent failures remain inspectable and are not rebound to a successor endpoint without a separate authenticated Wolfpack contract.
 
-`agent_task_ack` is valid only for a terminal origin-owned task. Sequential, concurrent, and restart retries reuse one durable `task.parent_acknowledged` event and the same destination envelope identities while still retrying any pending physical delivery.
-
-## 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
-
-- a reachable local Wolfpack v1 task gateway on every participating machine;
-- this package loaded in every participating Pi process;
-- `WOLFPACK_SESSION_NAME` set by Wolfpack so the local gateway can resolve the caller to a stable broker ID; and
-- `WOLFPACK_PORT` when the local control port is not the default `18790`.
-
-The boundary is trusted local processes and trusted Tailnet machines. Pi only calls its own local gateway. The gateways perform direct fetch federation; Pi never fetches a peer directly. v1 adds no task capability authentication. Normal Wolfpack global JWT behavior is not bypassed, and JWT federation is unsupported: peer delivery fails clearly when credentials would be required.
-
-## task address and send
-
-A target is always `{ machine, sessionId }`, where `sessionId` is the stable opaque broker ID returned by Wolfpack session control. Use `machine: "local"` for same-machine work. For a peer, use the receiver's canonical HTTPS Tailnet origin, for example `https://worker.example.ts.net`; do not supply a hostname label, path, query, fragment, credentials, unexpected port, or arbitrary HTTPS URL.
-
-```json
-{
-  "to": { "machine": "local", "sessionId": "receiver-broker-id" },
-  "task": "implement the narrow change and run focused tests",
-  "context": {
-    "summary": "## constraints and preferences\n- keep scope narrow\n## key decisions\n- preserve the public contract",
-    "refs": [{ "path": "src/extension.ts", "purpose": "affected tool wiring" }]
-  },
-  "metadata": { "phaseId": "phase-1", "issueId": "task-3", "verificationTier": "focused" },
-  "onCompletePrompt": "review the receiver diff before reporting completion",
-  "timeoutMs": 1800000
-}
-```
-
-### v1 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
-{ "to": { "machine": "https://worker.example.ts.net", "sessionId": "receiver-broker-id" }, "task": "review the cited diff" }
-```
-
-Context is optional, curated Markdown plus deliberately selected ref metadata. The extension renders refs but never reads or copies their contents. Relative refs resolve in the receiver project; absolute refs are same-machine only and must remain inside the authoritative parent or receiver project root. Missing refs are warnings, not copied content or transcript transfer.
-
-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 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.
-
-## tools, messages, and acknowledgment
-
-| tool | purpose |
-| --- | --- |
-| `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 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.
+`agent_task_ack` is valid only for a terminal origin-owned task. Sequential, concurrent, and restart retries reuse one durable `task.parent_acknowledged` event and the same destination envelope identities while retrying pending physical delivery.
 
 Report source modifications in `result.changedFiles`. Artifacts are receiver-project-relative regular files for a parent to inspect, not a changed-file list:
 
@@ -137,36 +63,6 @@ Report source modifications in `result.changedFiles`. Artifacts are receiver-pro
 { "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. 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 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. Spawn a disposable worker without an initial assignment prompt using `wolfpack agent spawn <project> --name <task-role> --model "$IMPLEMENTER_MODEL" --json` (or `"$REVIEWER_MODEL"` for review) 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.
-
-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.
-
-## deferred follow-up
-
-These are documented operational debt, not production TODOs: exact Pi runtime registration and heartbeat/capability leases; durable offline initial dispatch; JWT/authenticated peer federation; artifact byte transfer and retention; representative payload benchmarking; automated recovery summaries; and summary caching only after measured repeated-generation waste. v1 has no queue, scheduler, artifact transfer, or transcript transfer.
-
-## legacy historical metrics
-
-`task-metrics` and the task board remain read-only analyzers for already-existing historical `.pi/tasks` directories. They are not part of the runtime task protocol and must not create, mutate, or deliver v1 gateway tasks. Replacing or retiring that historical reporting surface requires a product decision about gateway-wide query/metrics ownership.
-
 ## development
 
 ```bash

package/package.json

@@ -1,11 +1,10 @@
 {
   "name": "@sgtbeatdown/pi-tasks",
-  "version": "0.1.6",
-  "description": "Durable Pi agent delegation through the Wolfpack task gateway.",
+  "version": "0.1.8",
+  "description": "Durable endpoint-owned Pi agent delegation through Wolfpack relay v2.",
   "module": "src/index.ts",
   "exports": {
-    ".": "./src/index.ts",
-    "./v1-compat-extension": "./src/v1-compat-extension.ts"
+    ".": "./src/index.ts"
   },
   "repository": {
     "type": "git",
@@ -50,7 +49,6 @@
   },
   "scripts": {
     "test": "bun test",
-    "task-metrics": "bun src/metrics-cli.ts",
     "typecheck": "tsc --noEmit"
   },
   "type": "module"

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
@@ -43,13 +44,13 @@ Pass `--model "$IMPLEMENTER_MODEL"` when spawning the editing implementer and `-
 }
 ```
 
-The default `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`. v1-only fields such as context, role, metadata, preflight, idempotency keys, and completion prompts are not silently accepted or translated. use at least `3600000` milliseconds for coding assignments; timeout is a failure deadline, not a progress-poll interval.
+The default `agent_task_send` schema is exactly `to`, `task`, and optional `timeoutMs`. Unsupported fields are rejected rather than translated. use at least `3600000` milliseconds for coding assignments; timeout is a failure deadline, not a progress-poll interval.
 
 ## phase roles and handoffs
 
 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.
@@ -85,21 +86,11 @@ Receiver terminal submission has one task-wide logical identity. Same-status ret
 
 Set `PI_TASK_WORKER=1` only for task-only workers. Before a valid structured assignment matches a locally owned active task, the worker gate allows only inbox/status/wait inspection and blocks other model tools with `PI_TASK_WORKER_ASSIGNMENT_REQUIRED`.
 
-## v1 compatibility
-
-The retained v1 workflow is available only through the explicit `@sgtbeatdown/pi-tasks/v1-compat-extension` entrypoint. It does not load by default, and v2 never falls back or translates its targets.
-
-v1 uses a reachable local Wolfpack task gateway and addresses targets as `to: { machine, sessionId }`. Use `machine: "local"` for same-machine work; remote work uses only the receiver's canonical HTTPS Tailnet origin. v1 trusts local processes and trusted Tailnet machines, has no JWT federation, and follows Wolfpack's [task gateway guide](https://github.com/almogdepaz/wolfpack/blob/main/docs/task-gateway.md).
-
-Before v1 remote dispatch, complete the [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. Isolated coverage is the deterministic acceptance gate, but it does not prove a specific live peer.
-
-Only v1 supports curated `context.summary`/refs, role, metadata, preflight, idempotency keys, and completion prompts. Use `context.summary` only for constraints, decisions, and recovery state. Refs are metadata, not copied files or transcript. A v1 remote initial send gets one initial attempt; later peer events get four total attempts. Retry exhaustion is surfaced; v1 has no offline queue or background dispatch promise.
-
 ## do not
 
 - do not use terminal output, rendered prompts, logs, or error prose as task state.
 - do not ask workers to complete in prose or close their own sessions.
 - 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 mix v1 and v2 target shapes or silently translate between them.
+- do not derive or transform opaque endpoint IDs.
 - do not promise JWT federation, artifact byte transfer, exactly-once model execution, or successor endpoint rebinding.

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 { PARENT_ACKNOWLEDGMENT_OPERATION, TERMINAL_INTENT_OPERATION } from "./task-protocol";
+import { TERMINAL_INTENT_OPERATION } from "./task-protocol";
 import type { RelayEnvelope, TaskEndpoint, TaskEvent, TaskRecord, TaskSnapshot, TerminalDeliveryState, TerminalTaskIntentType } from "./task-protocol";
 
 const SCHEMA_VERSION = 5;
@@ -71,8 +71,13 @@ export function createTaskStore(options: TaskStoreOptions = {}): TaskStore {
 	const path = options.path ?? join(homedir(), ".pi", "tasks", "v2", "tasks.sqlite");
 	preparePath(path);
 	const database = openSqliteDatabase(path);
-	database.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
-	migrate(database);
+	try {
+		initializeSchema(database);
+		database.exec("PRAGMA journal_mode = WAL; PRAGMA foreign_keys = ON;");
+	} catch (error) {
+		database.close();
+		throw error;
+	}
 
 	const store: TaskStore = {
 		transaction(operation) {
@@ -213,17 +218,6 @@ interface TaskOperationRow {
 	readonly envelope_ids: string;
 }
 
-interface LegacyIntentRow {
-	readonly intent_id: string;
-	readonly task_id: string;
-	readonly envelope_id: string;
-}
-
-interface LegacyEnvelopeRow {
-	readonly envelope_id: string;
-	readonly envelope: string;
-}
-
 interface EventRow {
 	readonly event_id: string;
 	readonly task_id: string;
@@ -237,10 +231,11 @@ interface EventRow {
 	readonly payload: string;
 }
 
-function migrate(database: SqliteDatabase): void {
+function initializeSchema(database: SqliteDatabase): void {
 	const version = database.query("PRAGMA user_version").get() as { readonly user_version: number };
-	if (version.user_version > SCHEMA_VERSION) throw new Error("task store schema is newer than this pi-tasks version");
-	if (version.user_version === 0) {
+	if (version.user_version === SCHEMA_VERSION) return;
+	if (version.user_version !== 0) throw new Error("task store schema version is unsupported");
+	database.transaction(() => {
 		database.exec(`
 			CREATE TABLE tasks (task_id TEXT PRIMARY KEY, protocol_version TEXT NOT NULL, origin_relay TEXT NOT NULL, origin_id TEXT NOT NULL, target_relay TEXT NOT NULL, target_id TEXT NOT NULL, task TEXT NOT NULL, created_at INTEGER NOT NULL, expires_at INTEGER NOT NULL, status TEXT NOT NULL);
 			CREATE TABLE events (event_id TEXT PRIMARY KEY, task_id TEXT NOT NULL REFERENCES tasks(task_id), type TEXT NOT NULL, sequence TEXT NOT NULL, source_relay TEXT NOT NULL, source_id TEXT NOT NULL, target_relay TEXT NOT NULL, target_id TEXT NOT NULL, occurred_at INTEGER NOT NULL, payload TEXT NOT NULL);
@@ -248,137 +243,29 @@ function migrate(database: SqliteDatabase): void {
 			CREATE TABLE inbox (envelope_id TEXT PRIMARY KEY, cursor TEXT NOT NULL, envelope TEXT NOT NULL);
 			CREATE TABLE intents (intent_id TEXT PRIMARY KEY, task_id TEXT NOT NULL, envelope_id TEXT NOT NULL);
 			CREATE TABLE relay_state (name TEXT PRIMARY KEY, value TEXT NOT NULL);
-			PRAGMA user_version = 1;
-		`);
-	}
-	if (version.user_version <= 1) {
-		database.exec(`
-			CREATE INDEX IF NOT EXISTS tasks_origin_expiry ON tasks (origin_relay, origin_id, status, expires_at);
-			CREATE INDEX IF NOT EXISTS inbox_cursor ON inbox (cursor);
-			PRAGMA user_version = 2;
-		`);
-	}
-	if (version.user_version <= 2) {
-		database.exec(`
 			CREATE TABLE insertion_receipts (task_id TEXT NOT NULL REFERENCES tasks(task_id), event_id TEXT NOT NULL, PRIMARY KEY (task_id, event_id));
-			PRAGMA user_version = 3;
-		`);
-	}
-	if (version.user_version <= 3) {
-		database.exec(`CREATE TABLE IF NOT EXISTS outbox_quarantine (
-			envelope_id TEXT PRIMARY KEY,
-			envelope TEXT NOT NULL,
-			reason TEXT NOT NULL,
-			quarantined_at INTEGER NOT NULL,
-			error_code TEXT NOT NULL DEFAULT 'UNKNOWN',
-			details TEXT NOT NULL DEFAULT '{}',
-			prior_state TEXT NOT NULL DEFAULT 'pending'
-		);`);
-		ensureColumn(database, "outbox_quarantine", "envelope", "TEXT NOT NULL DEFAULT '{}'");
-		ensureColumn(database, "outbox_quarantine", "reason", "TEXT NOT NULL DEFAULT 'operator quarantine'");
-		ensureColumn(database, "outbox_quarantine", "quarantined_at", "INTEGER NOT NULL DEFAULT 0");
-		ensureColumn(database, "outbox_quarantine", "error_code", "TEXT NOT NULL DEFAULT 'UNKNOWN'");
-		ensureColumn(database, "outbox_quarantine", "details", "TEXT NOT NULL DEFAULT '{}'");
-		ensureColumn(database, "outbox_quarantine", "prior_state", "TEXT NOT NULL DEFAULT 'pending'");
-		database.exec("PRAGMA user_version = 4;");
-	}
-	if (version.user_version <= 4) {
-		database.transaction(() => {
-			database.exec(`CREATE TABLE IF NOT EXISTS task_operations (
+			CREATE TABLE outbox_quarantine (
+				envelope_id TEXT PRIMARY KEY,
+				envelope TEXT NOT NULL,
+				reason TEXT NOT NULL,
+				quarantined_at INTEGER NOT NULL,
+				error_code TEXT NOT NULL,
+				details TEXT NOT NULL,
+				prior_state TEXT NOT NULL
+			);
+			CREATE TABLE task_operations (
 				task_id TEXT NOT NULL REFERENCES tasks(task_id),
 				operation TEXT NOT NULL,
 				logical_id TEXT NOT NULL,
 				logical_type TEXT NOT NULL,
 				envelope_ids TEXT NOT NULL,
 				PRIMARY KEY (task_id, operation)
-			);`);
-			backfillTaskOperations(database);
-			database.exec("PRAGMA user_version = 5;");
-		})();
-	}
-}
-
-function backfillTaskOperations(database: SqliteDatabase): void {
-	const envelopes = legacyEnvelopes(database);
-	const terminalTasks = new Set<string>();
-	const intents = database.query("SELECT intent_id, task_id, envelope_id FROM intents ORDER BY rowid").all() as LegacyIntentRow[];
-	for (const intent of intents) {
-		if (terminalTasks.has(intent.task_id)) continue;
-		const serializedEnvelope = envelopes.get(intent.envelope_id);
-		if (!serializedEnvelope) throw new Error(`legacy intent ${intent.intent_id} has no durable envelope`);
-		const envelope = legacyEnvelope(intent.envelope_id, serializedEnvelope);
-		const payload = legacyEnvelopePayload(envelope);
-		if (envelope.kind !== "intent" || envelope.taskId !== intent.task_id || !isRecord(payload) || payload.intentId !== intent.intent_id || payload.taskId !== intent.task_id || typeof payload.type !== "string") {
-			throw new Error(`legacy intent ${intent.intent_id} has malformed structured state`);
-		}
-		if (!isTerminalIntentType(payload.type)) continue;
-		insertTaskOperation(database, { taskId: intent.task_id, operation: TERMINAL_INTENT_OPERATION, logicalId: intent.intent_id, logicalType: payload.type, envelopeIds: [intent.envelope_id] });
-		terminalTasks.add(intent.task_id);
-	}
-
-	const acknowledgments = database.query("SELECT * FROM events WHERE type = 'task.parent_acknowledged' ORDER BY task_id, CAST(sequence AS INTEGER), rowid").all() as EventRow[];
-	const acknowledgedTasks = new Set<string>();
-	for (const acknowledgment of acknowledgments) {
-		if (acknowledgedTasks.has(acknowledgment.task_id)) continue;
-		const envelopeIds = [...envelopes]
-			.flatMap(([envelopeId, serializedEnvelope]) => {
-				const envelope = optionalLegacyEnvelope(envelopeId, serializedEnvelope);
-				return envelope?.kind === "canonical_event" && envelope.taskId === acknowledgment.task_id && eventIdFromLegacyEnvelope(envelope) === acknowledgment.event_id ? [envelopeId] : [];
-			})
-			.sort();
-		if (envelopeIds.length === 0) throw new Error(`legacy parent acknowledgment ${acknowledgment.event_id} has no durable envelope`);
-		insertTaskOperation(database, { taskId: acknowledgment.task_id, operation: PARENT_ACKNOWLEDGMENT_OPERATION, logicalId: acknowledgment.event_id, logicalType: acknowledgment.type, envelopeIds });
-		acknowledgedTasks.add(acknowledgment.task_id);
-	}
-}
-
-function legacyEnvelopes(database: SqliteDatabase): Map<string, string> {
-	const envelopes = new Map<string, string>();
-	const live = database.query("SELECT envelope_id, envelope FROM outbox ORDER BY rowid").all() as LegacyEnvelopeRow[];
-	const quarantined = database.query("SELECT envelope_id, envelope FROM outbox_quarantine ORDER BY rowid").all() as LegacyEnvelopeRow[];
-	for (const row of [...live, ...quarantined]) {
-		if (row.envelope_id.length === 0) throw new Error("legacy durable envelope identity is malformed");
-		if (!envelopes.has(row.envelope_id)) envelopes.set(row.envelope_id, row.envelope);
-	}
-	return envelopes;
-}
-
-function legacyEnvelope(envelopeId: string, serializedEnvelope: string): RelayEnvelope {
-	const envelope = parseEnvelope(serializedEnvelope);
-	if (envelope.envelopeId !== envelopeId) throw new Error(`legacy envelope ${envelopeId} identity is malformed`);
-	return envelope;
-}
-
-function optionalLegacyEnvelope(envelopeId: string, serializedEnvelope: string): RelayEnvelope | undefined {
-	try {
-		return legacyEnvelope(envelopeId, serializedEnvelope);
-	} catch {
-		// Unrelated operator quarantine rows are audit data, not lifecycle state.
-		return undefined;
-	}
-}
-
-function legacyEnvelopePayload(envelope: RelayEnvelope): unknown {
-	try {
-		return JSON.parse(envelope.payload) as unknown;
-	} catch {
-		throw new Error(`legacy envelope ${envelope.envelopeId} payload is malformed`);
-	}
-}
-
-function eventIdFromLegacyEnvelope(envelope: RelayEnvelope): string | undefined {
-	const payload = legacyEnvelopePayload(envelope);
-	return isRecord(payload) && typeof payload.eventId === "string" ? payload.eventId : undefined;
-}
-
-function insertTaskOperation(database: SqliteDatabase, input: TaskOperationRecord): void {
-	database.query(`INSERT INTO task_operations (task_id, operation, logical_id, logical_type, envelope_ids)
-		VALUES (?, ?, ?, ?, ?) ON CONFLICT(task_id, operation) DO NOTHING`).run(input.taskId, input.operation, input.logicalId, input.logicalType, JSON.stringify(input.envelopeIds));
-}
-
-function ensureColumn(database: SqliteDatabase, table: string, name: string, definition: string): void {
-	const columns = database.query(`PRAGMA table_info(${table})`).all() as Array<{ readonly name: string }>;
-	if (!columns.some((column) => column.name === name)) database.exec(`ALTER TABLE ${table} ADD COLUMN ${name} ${definition}`);
+			);
+			CREATE INDEX tasks_origin_expiry ON tasks (origin_relay, origin_id, status, expires_at);
+			CREATE INDEX inbox_cursor ON inbox (cursor);
+			PRAGMA user_version = 5;
+		`);
+	})();
 }
 
 function preparePath(path: string): void {