@caupulican/pi-adaptative 0.81.39 → 0.81.40

package/docs/process-matrix.md

@@ -15,20 +15,49 @@ process breaks.
 
 Every `pi` process registers exactly one entry in the matrix, keyed by `<role>-<sessionId>`, under
 `state/process-matrix/` (see `agent-paths.ts` -- durable, survives `/reload` and crashes, not the
-transient `work/` tree).
+transient `work/` tree). The session ID is derived from the entry's single `AgentIdentityContract`;
+process entries and resumable payloads do not carry parallel agent/session/lane context fields. All
+post-registration transitions use the same per-entry lock and replace/delete only the exact process
+generation they observed. An older same-session process therefore loses write ownership as soon as a
+newer process registers; its late heartbeat, reconciliation, or exit hook cannot overwrite the newer
+entry.
 
 - **Master** (no declared parent): writes its own entry once at startup, heartbeats it on an
   interval, and -- once, at startup -- scans the matrix for **orphaned workers**: worker entries
-  whose recorded parent pid is dead.
+  whose recorded parent pid is dead. `/new`, `/resume`, and `/fork` replace this session-owned
+  runtime, so its identity, notifications, and scan always follow the active session.
 - **Worker** (launched with `PI_PARENT_PID` / `--parent-pid` set): self-registers its own entry
   (the only writer of that entry during normal operation) and watches its parent's liveness on a
   poll interval.
 
 ### Resume: a master never auto-kills what it finds
 
-On startup, a master's orphan scan finds worker entries whose parent is dead. It never assumes
-those workers are also dead -- a worker can outlive a crashed parent -- so it never kills or
-silently repurposes anything. Instead, for each orphan, **interactively**:
+On startup or in-process session resume, a master's orphan scan finds worker entries whose parent
+is dead. It never assumes those workers are also dead -- a worker can outlive a crashed parent --
+so it never kills anything. Recovery is identity-fenced:
+
+- If the worker's recorded `parentSessionId` and `taskRef` exactly match the active session and its
+  active goal/task identity, resume restores that existing ownership without another approval. A
+  live worker is re-adopted; a dead worker with a complete resumable Pi context is relaunched as the
+  same logical agent. Terminal or still-blocked goals disable automatic recovery. This works in
+  interactive, print, and RPC modes and is the process-level counterpart to `/resume` restoring the
+  goal before supervisors start.
+- Every foreign orphan remains owner-gated. Interactive mode offers resume/adopt/cleanup; headless
+  modes report it without writes or process actions.
+
+When a foreign worker's own process is dead and its resumable payload contains a Pi session
+context, the first prompt offers to resume that same logical agent. Acceptance launches the exact
+persisted session file with its agent ID, cwd, worktree, orchestration profile, resource pointers,
+and bounded wake task. The direct-argv launch prefers the exact persisted `sessionFile` over an ID
+lookup, carries the stable logical-agent ID in `PI_ORCHESTRATION_AGENT_ID`, and names the latest
+checkpoint plus bounded context pointers in the wake prompt instead of copying a second transcript.
+The resumed process overwrites the same `<role>-<sessionId>` matrix entry. The launcher publishes its
+PID before self-registration, and terminal persistence plus delivery acknowledgement conditionally
+replace only the process generation they observed. A stale completion can therefore never close a
+newer replacement. The terminal event is first persisted as an undelivered matrix handoff, then
+delivered to the owning parent session and marked delivered. If that owner switched sessions before
+the event arrived, the bounded handoff survives and replays on its next resume instead of being
+injected into the wrong transcript. A still-live foreign orphan follows the adopt/cleanup flow below.
 
 1. Ask: *"adopt worker `<entryId>` (lane `<laneKey>`)?"* Yes → this session becomes the worker's
    new parent (an adoption grant is written into the worker's own entry).
@@ -37,16 +66,17 @@ silently repurposes anything. Instead, for each orphan, **interactively**:
    killed).
 3. If both declined: leave the entry untouched.
 
-**Non-interactively** (print/RPC mode, or no TTY), the scan is report-only: it logs what it found
-and writes nothing, kills nothing. The one-time startup scan is the only place a master ever
-touches another session's entry, and only with explicit owner confirmation each time.
+**Non-interactively** (print/RPC mode, or no TTY), foreign orphans are report-only: the scan logs
+what it found and writes nothing. Exact-session recovery remains active because it restores an
+already-recorded authority relationship rather than claiming another session's worker.
 
 ### A worker on parent death: wind down, never vanish
 
 A worker polls its parent's pid on `watcherPollMs`. The moment that pid is no longer alive, it:
 
 1. Marks its own entry `winding_down` (reason `parent_lost`), then `resumable` with a payload
-   (its worktree-sync lane key, if bound) describing how the task could be picked back up.
+   containing one clone of its logical-agent identity (exact Pi session/cwd/profile/lane context),
+   its stable task reference, and a bounded task summary.
 2. Emits one steer notice into its own session.
 3. Starts a bounded grace window (`adoptionGraceMs`), polling its own entry every
    `watcherPollMs` for a directive a new master may have written (see above):
@@ -67,10 +97,13 @@ Cross-process, like `PI_WORKTREE_LANE`/`--worktree-lane`:
 |---|---|---|
 | `PI_PARENT_PID` | `--parent-pid <pid>` | Declares this process as a worker of `<pid>`. A malformed or non-positive value is ignored (never a crash on bad env) -- the process falls back to acting as a master. |
 | `PI_PARENT_SESSION` | `--parent-session <id>` | The parent's sessionId, recorded alongside the pid for diagnostics/adoption. |
+| `PI_ORCHESTRATION_AGENT_ID` | launch-only | Pins the logical agent identity across the initial process and exact-session resumes. |
+| `PI_TASK_REF` | `--task-ref <id>` | Pins the goal/task identity used to fence automatic recovery across process generations. |
 
-`tmux_agent_manager`'s `fire_task` sets both automatically on every `pi`-provider child it
-launches (its own pid/sessionId), the same way it threads `--worktree-lane` for a lane-first
-dispatch -- see `dispatch-grant.ts`'s `LaunchProfileSource.parentPid`/`parentSession`.
+`tmux_agent_manager`'s `fire_task` sets the parent pid/session and logical agent ID automatically on
+every `pi`-provider child it launches. Goal-bound launches also set `PI_TASK_REF` from `goalId`, the
+same way lane-first dispatch threads `--worktree-lane` -- see `dispatch-grant.ts`'s
+`LaunchProfileSource`.
 
 ## Settings
 
@@ -91,12 +124,11 @@ process-matrix entry are a sanctioned artifact, exactly like its own session tra
 ceiling is untouched, and this is not a new escalation surface. A worker never writes any *other*
 session's entry.
 
-The one narrow exception on the master side: during the ask-gated startup orphan scan, a master
-that the owner explicitly told to adopt or clean up a specific orphan writes that grant directly
-into the *orphan's* own entry (never anywhere else, never without that confirmation). This mirrors
-`worktree-sync`'s integration-lock takeover of a provably dead owner's resource -- a new owner may
-claim what a dead owner left behind, audited (here, by the interactive confirmation itself) rather
-than assumed. Outside that one handshake, a master never writes another session's entry.
+The narrow exceptions on the master side are identity-fenced exact-session recovery and the
+ask-gated foreign-orphan scan. Exact recovery may restore the same recorded parent session without
+another prompt. Claiming or cleaning up a foreign orphan still requires explicit owner approval and
+writes only that orphan's entry. Outside those handshakes, a master never writes another session's
+entry.
 
 ## Foreign-CLI limitation
 
@@ -110,11 +142,12 @@ cooperative boundary this system cannot structurally enforce across an arbitrary
 
 - It never kills a process. Every termination is either the process's own cooperative self-exit or
   an owner-confirmed grant the process itself later notices and applies.
-- It does not re-attach a tmux pane or re-dispatch a lane on adoption -- adoption changes who a
-  worker considers its parent, nothing about its tmux session or worktree-sync lane state.
-- Correctness never depends on a heartbeat or a watcher tick arriving -- a crashed process just
-  leaves a stale entry behind. `supervisor.ts`'s `reconcileMatrix` (prune `closed` and any
-  `running`/`winding_down` entry whose own pid is dead; keep `resumable`/`adopted` until they age
-  past a TTL) is the building block for cleaning those up; nothing in this build wires it into an
-  automatic sweep yet -- the matrix directory is left to grow with stale entries until a future
-  caller (a manual command, or a periodic sweep) invokes it.
+- It does not re-attach a tmux pane or re-dispatch a lane when adopting a still-live worker --
+  adoption changes who that worker considers its parent. Relaunch is reserved for a dead worker
+  with a complete persisted Pi resume context. Exact session+task recovery is automatic; every
+  mismatched or foreign identity remains owner-gated.
+- Correctness never depends on a heartbeat or watcher tick arriving. Each master activation runs
+  the pure reconciliation pass once: a Pi worker interrupted before its own resumable write is
+  repaired from its durable logical-agent identity, closed and unrecoverable records are removed,
+  undelivered terminal handoffs are retained, and resumable/adopted/pending-terminal records remain
+  recoverable for at most 30 days before expiry.

package/docs/rpc.md

@@ -1063,7 +1063,7 @@ Extensions can request user interaction via `ctx.ui.select()`, `ctx.ui.confirm()
 
 There are two categories of extension UI methods:
 
-- **Dialog methods** (`select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
+- **Dialog methods** (`questions`, `select`, `confirm`, `input`, `editor`): emit an `extension_ui_request` on stdout and block until the client sends back an `extension_ui_response` on stdin with the matching `id`.
 - **Fire-and-forget methods** (`notify`, `setStatus`, `setWidget`, `setTitle`, `set_editor_text`): emit an `extension_ui_request` on stdout but do not expect a response. The client can display the information or ignore it.
 
 If a dialog method includes a `timeout` field, the agent-side will auto-resolve with a default value when the timeout expires. The client does not need to track timeouts.
@@ -1084,6 +1084,33 @@ Note: `ctx.hasUI` is `true` in RPC mode because the dialog and fire-and-forget m
 
 All requests have `type: "extension_ui_request"`, a unique `id`, and a `method` field.
 
+#### questions
+
+Present the native structured owner-input contract. `request.questions` contains one to four questions, each with a stable `id`, heading, prompt, two to four options, and optional `multiSelect`. `acceptsImages` reports whether the routed model can receive image answer blocks.
+
+```json
+{
+  "type": "extension_ui_request",
+  "id": "uuid-q",
+  "method": "questions",
+  "request": {
+    "requestId": "human-input:call-1",
+    "acceptsImages": true,
+    "questions": [{
+      "id": "scope",
+      "header": "Scope",
+      "question": "How broad should this be?",
+      "options": [
+        {"label": "Focused", "description": "Change only the failing workflow."},
+        {"label": "Complete", "description": "Cover the full related surface."}
+      ]
+    }]
+  }
+}
+```
+
+Expected response: `extension_ui_response` with an `answers` array and optional `images` array, or `cancelled: true`. Free-form answer text is not length-clamped by the protocol; Pi externalizes large values before they enter model context. Clients must not send `customArtifact`: artifact references are harness-owned. Submitted images are validated and retained in the bounded session image store before the answer checkpoint so `/resume` can restore them.
+
 #### select
 
 Prompt the user to choose from a list. Dialog methods with a `timeout` field include the timeout in milliseconds; the agent auto-resolves with `undefined` if the client doesn't respond in time.
@@ -1227,7 +1254,23 @@ Set the text in the input editor. Fire-and-forget.
 
 ### Extension UI Responses (stdin)
 
-Responses are sent for dialog methods only (`select`, `confirm`, `input`, `editor`). The `id` must match the request.
+Responses are sent for dialog methods only (`questions`, `select`, `confirm`, `input`, `editor`). The `id` must match the request. Malformed, ambiguous, unknown, or expired responses fail closed with an `extension_ui_response` error instead of settling another request.
+
+#### Structured question response
+
+```json
+{
+  "type": "extension_ui_response",
+  "id": "uuid-q",
+  "answers": [{
+    "id": "scope",
+    "header": "Scope",
+    "question": "How broad should this be?",
+    "selected": ["Focused"],
+    "skipped": false
+  }]
+}
+```
 
 #### Value response (select, input, editor)
 

package/docs/sessions.md

@@ -38,6 +38,18 @@ For the JSONL file format and SessionManager API, see [Session Format](session-f
 
 `/resume` opens an interactive session picker for the current project. `pi -r` opens the same picker at startup.
 
+If the selected session contains a blocked durable goal, Pi applies the same transition as
+`/goal resume` before restarting that session's worker and process supervisors. `pi -c`, `pi -r`, and
+`--session` use the same startup rule. Active goals remain active; completed or cancelled goals are
+never reopened automatically.
+
+Session replacement has an explicit recovery boundary. Preparation failure leaves the current runtime
+untouched. If retiring the current runtime, rebinding, or starting supervision fails, Pi completes every
+cleanup step, cleans the candidate, and reconstructs the previous session from its durable manager. A
+failure in an extension's post-replacement `withSession` callback is reported separately because the
+replacement is already valid and remains active. Process shutdown uses the same draining teardown and
+waits for an already-admitted replacement before disposing the runtime it leaves active.
+
 In the picker you can:
 
 - search by typing
@@ -49,6 +61,9 @@ In the picker you can:
 
 When available, pi uses the `trash` CLI for deletion instead of permanently removing files.
 
+Use `/goal resume` when you want to resume the blocked goal in the current session without switching
+sessions.
+
 ## Naming Sessions
 
 Use `/name <name>` to set a human-readable session name:

package/docs/settings.md

@@ -6,7 +6,7 @@ Pi uses JSON settings files with project settings overriding global settings. Pi
 |----------|-------|
 | `~/.pi/agent/settings.json` | Global (all projects) |
 | `.pi/settings.json` | Project (current directory) |
-| `~/.pi/agent/resource-profiles/<hash>/settings.json` | User-level per repo/directory overlay; no repo files written |
+| `~/.pi/agent/profiles/directories/<hash>/settings.json` | User-level per repo/directory overlay; no repo files written |
 | `~/.pi/agent/profiles/*.json` | Reusable named profile definitions |
 
 Edit directly or use `/settings` for common options.
@@ -148,22 +148,123 @@ Fitness applicability is intentionally split by autonomy level:
 
 ### Worker Delegation
 
-Delegation is available by default when the active model and UAC tool surface support it. Ultra reinforces proactive use but does not own or unlock the capability. Each worker gets a fresh classified tool surface (`read`, `grep`, `find`, and `ls`); its shipped profile filters those names with the same glob semantics as foreground UAC. `delegate`, shell, foreground memory/lifecycle tools, and opaque extension tools are never inherited into the child. The orchestrator may set `memoryRead: true` for a relevant task; if global memory retrieval remains enabled and the lane profile also grants `memory`, the worker receives a separate bounded query-only memory tool. Generic file tools cannot bypass that decision by reading private memory/auth/settings files. Memory writes remain unavailable. Workers are otherwise read-only unless the write toggle, a non-empty path scope, and the shipped profile all grant `write` or `edit`.
+Delegation requires an owner-authored orchestration profile. Global profiles live at `~/.pi/agent/profiles/orchestration/<id>.json`; project profiles live at `.pi/profiles/orchestration/<id>.json` and override a global profile with the same ID. Select the foreground architect with `--orchestration-profile <id>` or `activeOrchestrationProfile`. Select a default worker with `workerDelegation.orchestrationProfile`.
 
-The worker model is provider-independent: when `workerDelegation.model` is unset it inherits the active model; an explicit pattern may select any authenticated, capability-eligible model, including subscription, API-key, or local providers. The isolated worker resolves auth and text-tool fallback from that selected model rather than inheriting the foreground model's protocol. Local workers that contend with a local foreground are queued and drained at the configured running concurrency. `delegate_status` preserves bounded non-JSON read-only results and labels output that ended at a provider limit as incomplete instead of discarding it as unparseable.
+The profile fixes the role, provider/model, exact thinking level, tools, resource profiles, semantic capabilities, budgets, concurrency, lease duration, and independent-verification requirement. Fixed profiles contain one model. Ordered fallback profiles contain an owner-ordered candidate list; runtime health may advance through that list but cannot invent another model or reasoning level. An architect uses role `orchestrator`, grants only `workflow.delegate`, and lists the exact worker profile IDs it may select in `dispatchProfileIds`. A dispatch outside that list is rejected before creating a model call.
 
-**Confirmed behavior:** `delegate` returns a lane id immediately instead of waiting for the worker. `delegate_status` shows queued, running, and terminal workers and retrieves bounded terminal output by lane id. Completion emits a session notification with the completed lane id and status; the interactive footer shows running/queued counts or the latest terminal lane. Late worker output is stored separately and is never injected into an active foreground transcript.
+```json
+{
+  "schemaVersion": 1,
+  "profileId": "architect",
+  "description": "Routing-only architect",
+  "role": "orchestrator",
+  "modelPolicy": {
+    "mode": "fixed",
+    "candidates": [
+      { "provider": "openai-codex", "modelId": "gpt-5.5", "thinkingLevel": "high" }
+    ]
+  },
+  "capabilityCeiling": ["workflow.delegate"],
+  "toolNames": ["delegate", "delegate_status"],
+  "resourceProfileNames": ["architect-minimal"],
+  "dispatchProfileIds": ["worker-fast", "verifier"],
+  "budget": { "maxTokens": 16000, "maxWallClockMs": 600000, "maxCostUsd": 2, "maxToolCalls": 20 },
+  "maxConcurrent": 1,
+  "leaseTtlMs": 660000,
+  "requireIndependentVerification": false,
+  "createdAt": "2026-07-23T00:00:00.000Z",
+  "updatedAt": "2026-07-23T00:00:00.000Z"
+}
+```
+
+```json
+{
+  "schemaVersion": 1,
+  "profileId": "worker-fast",
+  "description": "Pinned implementation worker",
+  "role": "implementer",
+  "modelPolicy": {
+    "mode": "fixed",
+    "candidates": [
+      { "provider": "openai", "modelId": "gpt-5-mini", "thinkingLevel": "minimal" }
+    ]
+  },
+  "capabilityCeiling": ["filesystem.read", "filesystem.write", "worktree.read", "worktree.mutate"],
+  "toolNames": ["read", "grep", "find", "ls", "write", "edit"],
+  "resourceProfileNames": ["worker-minimal"],
+  "dispatchProfileIds": [],
+  "budget": { "maxTokens": 8000, "maxWallClockMs": 180000, "maxCostUsd": 0.25, "maxAttempts": 2, "maxToolCalls": 12 },
+  "maxConcurrent": 3,
+  "leaseTtlMs": 240000,
+  "requireIndependentVerification": true,
+  "verificationProfileId": "verifier",
+  "createdAt": "2026-07-23T00:00:00.000Z",
+  "updatedAt": "2026-07-23T00:00:00.000Z"
+}
+```
+
+A profile with `requireIndependentVerification: true` must name an owner-authored
+`verificationProfileId`. That target must have role `verifier`, cannot require another verifier, and
+must also appear in the active architect's `dispatchProfileIds`. After a successful implementation,
+the runtime automatically creates a separate durable verifier task. The implementation remains
+blocked and sends no terminal parent handoff until the verifier returns a typed accepted or rejected
+decision; only an accepted decision backed by trusted criterion-linked review evidence completes it.
 
-Worker writes use **review-after-apply** semantics: a gate-authorized direct `write`/`edit` call or an envelope/path-validated structured action may mutate the scoped workspace before the parent reviews the result. The parent review is therefore a post-mutation acceptance step and receives changed files, blockers, the usage report id, and `parent_review_required` for an in-scope changed result. Denied or out-of-scope actions are refused before filesystem mutation; partial application is reported as `blocked`, never clean success.
+```json
+{
+  "schemaVersion": 1,
+  "profileId": "verifier",
+  "description": "Pinned independent test verifier",
+  "role": "verifier",
+  "modelPolicy": {
+    "mode": "fixed",
+    "candidates": [
+      { "provider": "openai", "modelId": "gpt-5-mini", "thinkingLevel": "low" }
+    ]
+  },
+  "capabilityCeiling": ["filesystem.read", "process.exec", "tests.execute"],
+  "toolNames": ["read", "grep", "find", "ls", "run_process"],
+  "resourceProfileNames": ["verifier-minimal"],
+  "dispatchProfileIds": [],
+  "executionPolicy": {
+    "allowedExecutables": ["node", "npm", "git"],
+    "allowedEnvironmentVariables": ["CI"],
+    "maxOutputBytes": 65536
+  },
+  "budget": { "maxTokens": 8000, "maxWallClockMs": 180000, "maxCostUsd": 0.25, "maxToolCalls": 12 },
+  "maxConcurrent": 2,
+  "leaseTtlMs": 240000,
+  "requireIndependentVerification": false,
+  "createdAt": "2026-07-23T00:00:00.000Z",
+  "updatedAt": "2026-07-23T00:00:00.000Z"
+}
+```
+
+Operator and verifier profiles that grant `process.exec` or `tests.execute` must also declare `executionPolicy`. `run_process` accepts only those exact executables, passes arguments directly without a shell, exposes only baseline plus owner-listed environment variables, terminates on timeout/output overflow, and always waits for a terminal process event.
+
+```json
+"executionPolicy": {
+  "allowedExecutables": ["node", "npm", "git"],
+  "allowedEnvironmentVariables": ["CI"],
+  "maxOutputBytes": 65536
+}
+```
+
+Each isolated worker gets a fresh classified surface. `delegate`, unrestricted shell, foreground memory/lifecycle tools, and opaque extension tools are not inherited. Read-only memory exists only when the selected profile grants `memory.query`, exposes `memory`, and global memory retrieval is enabled; a delegate call cannot add it. Workers are otherwise read-only unless the global write switch, non-empty path scope, profile capabilities, and profile tool list all grant `write` or `edit`.
+
+Profiles are provider-independent: every candidate resolves through the model registry, exact model authentication, capability metadata, and the selected model's native or calibrated text-tool protocol. Worker concurrency is counted per profile under the global worker ceiling; every capacity-bound worker is durably queued and drained under both limits, while local workers also queue when they contend with a local foreground. Worker model, thinking, resource, prompt, memory, and tool authority exist only in the selected orchestration profile; delegate calls and worker settings have no parallel override fields.
+
+**Confirmed behavior:** `delegate` returns a lane id immediately instead of waiting for the worker. `delegate_status` shows queued, running, and terminal workers and retrieves bounded terminal output by lane id. Completion records a durable terminal notification before waking the parent; undelivered in-process notifications replay after session resume. The interactive footer shows running/queued counts or the latest terminal lane. Late worker output is stored separately and is never injected into an active foreground transcript.
+
+Worker writes use **review-after-apply** semantics: a grant-authorized direct `write`/`edit` call or structured-action fallback may mutate the scoped workspace before the parent reviews the result. Both routes pass through the same compiled execution grant, path policy, and cumulative tool budget. The parent review is therefore a post-mutation acceptance step and receives changed files, blockers, the usage report id, and `parent_review_required` for an in-scope changed result. Denied or out-of-scope actions are refused before filesystem mutation; partial application is reported as `blocked`, never clean success.
 
 | Setting | Type | Default | Description |
 |---------|------|---------|-------------|
 | `workerDelegation.enabled` | boolean | `true` | Enable bounded delegation on capability-eligible models; explicit `false` is a hard off-switch |
-| `workerDelegation.model` | string | active model | Optional worker model pattern |
-| `workerDelegation.profile` | string | - | Complete situation profile shipped with the worker; named and workspace-relative (`./`/`../`) references are supported |
-| `workerDelegation.maxUsd` | number | `0.5` | Maximum estimated USD per worker, clamped to 0-5 and to the parent envelope |
-| `workerDelegation.maxWallClockMs` | number | `120000` | Per-worker wall-clock budget; `0` disables this bound |
-| `workerDelegation.maxConcurrent` | number | `1` | Concurrent worker limit, clamped to 1-3 |
+| `workerDelegation.orchestrationProfile` | string | - | Owner-selected default worker profile; an active architect may use only IDs in its `dispatchProfileIds` |
+| `workerDelegation.maxUsd` | number | `0.5` | Global safety ceiling intersected with profile/foreground limits; `0` disables only this settings-level ceiling |
+| `workerDelegation.maxWallClockMs` | number | `120000` | Global safety ceiling intersected with the profile limit; `0` disables only this settings-level ceiling |
+| `workerDelegation.maxConcurrent` | number | `1` | Global concurrency ceiling combined with profile `maxConcurrent` |
 | `workerDelegation.writeEnabled` | boolean | `false` | Make `write`/`edit` eligible only when `writePaths` is non-empty and the lane profile grants them |
 | `workerDelegation.writePaths` | string[] | `[]` | Relative or absolute path roots enforced for direct child tools and structured-action fallback writes |
 
@@ -368,6 +469,19 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `terminal.clearOnShrink` | boolean | `false` | Clear empty rows when content shrinks (can cause flicker) |
 | `images.autoResize` | boolean | `true` | Resize images to 2000x2000 max |
 | `images.blockImages` | boolean | `false` | Block all images from being sent to LLM |
+| `images.clipboardDirectory` | string | `~/.pi/agent/state/attachments` | Store clipboard image attachments here; relative paths resolve from the active working directory |
+
+Clipboard images use stable session numbers such as `[Image #3]`. A later prompt can refer to that number or say “look at the image” to attach the latest image from the current session again. The default directory is created only after an image is pasted, never inside the working repository. Pi recognizes and prunes only its own integrity-tagged files, with fixed 30-day, 512-file, and 512 MiB ceilings; unrelated files in a configured directory are untouched. `--no-session` keeps attachments in memory unless `images.clipboardDirectory` explicitly requests persistence.
+
+To keep captures in an explicit location:
+
+```json
+{
+  "images": {
+    "clipboardDirectory": "~/Pictures/pi-captures"
+  }
+}
+```
 
 ### Shell
 
@@ -522,7 +636,7 @@ Reusable profile files live under `~/.pi/agent/profiles/<name>.json`. They use a
 
 `resources` uses the same allow/block filter shape as `resourceProfiles`. Relative paths that start with `./` or `../` resolve from the profile file directory.
 
-Zero-footprint repo/directory overlays live under `~/.pi/agent/resource-profiles/<hash>/settings.json`, where `<hash>` is derived from the nearest VCS root (or current directory when no VCS root exists). These files are user-level settings; Pi does not write `.pi/settings.json` just to remember directory profiles.
+Zero-footprint repo/directory overlays live under `~/.pi/agent/profiles/directories/<hash>/settings.json`, where `<hash>` is derived from the nearest VCS root (or current directory when no VCS root exists). These files are user-level settings; Pi does not write `.pi/settings.json` just to remember directory profiles. Startup migrates the former root-level `resource-profiles/` layout without overwriting canonical data.
 
 ## Example
 

package/docs/task-steps.md

@@ -83,6 +83,14 @@ The old user-level task-steps extension also implemented detached jobs, teams, a
 
 Native worker lanes emit terminal handoff notifications and retain bounded results for explicit retrieval; task steps do not poll worker processes or inspect logs to detect completion.
 
+## Native orchestration UI
+
+Interactive sessions render task steps, worker dispatch, and worker status through one shared orchestration panel. The compact tool result shows status and counts first; expanding tool output reveals bounded notes, evidence, changed files, blockers, and untrusted worker claims. Checklist IDs stay out of the collapsed task view.
+
+While work is open, a host-owned panel below the editor combines the active checklist with queued or running `worker` and `tmux-worker` lanes. It updates from session and terminal-lane events, never by polling output. It disappears when no checklist item or worker is active and survives extension reloads without becoming extension-owned state.
+
+The visual contract is deliberately restrained for a keyboard-first terminal: semantic theme colors, status glyphs that remain meaningful without color, no animation, no hard frame, bounded rows, and width-safe truncation. Extension widgets still render independently; reloading or clearing them does not remove the native orchestration panel.
+
 ## Persistence and isolation
 
 Task state is stored only as custom entries in the active `SessionManager`. It follows normal session persistence, resume, and lifecycle behavior. Separate sessions cannot read or mutate each other's checklists, and malformed or future-version snapshots are ignored during restore.

package/docs/telemetry.md

@@ -0,0 +1,19 @@
+# Telemetry and durable event storage
+
+Pi keeps authoritative state separate from diagnostic telemetry. They do not share a schema or
+retention policy:
+
+| Data | Location | Contract |
+|---|---|---|
+| Install/update ping | `https://pi.dev/api/report-install` | Anonymous version ping only when enabled. `PI_TELEMETRY=0` or offline mode disables it. |
+| Autonomy diagnostics | Active session JSONL as redacted `autonomy-telemetry` custom entries | Bounded payloads for routes, gates, worker lifecycle, evidence, and learning decisions. Local only. |
+| Orchestration events | `<agentDir>/state/orchestration/<session>/events/*.json` | Lossless authoritative task/runtime history with ordinals and idempotency markers. Never rotated as telemetry. |
+| Tool recovery | `<agentDir>/state/tool-recovery-events.jsonl` | Local bounded diagnostic log: 4 MiB high-water, 3 MiB rotation target, at most 5,000 retained records. |
+| Failure corpus | `<agentDir>/state/failure-corpus.jsonl` | Local redacted replay evidence: 512 KiB high-water, 384 KiB rotation target, at most 1,000 retained records. |
+| Learning observations | `<agentDir>/state/learning-observations.json` | Compact counters used by the learning gate, capped at 500 keys. |
+| Worktree audit | `<git-common-dir>/pi-worktree-sync/events.jsonl` | Repository-local bounded coordination audit: 4 MiB high-water, 3 MiB rotation target, at most 10,000 retained records. |
+
+The three bounded JSONL logs use one lock-safe append/rotation implementation. Rotation retains the
+newest records to a low-water byte target so a log is not rewritten on every subsequent append.
+The orchestration event store is intentionally separate because it is durable task truth used for
+replay and resume, not expendable telemetry.

package/docs/tmux-agent-manager.md

@@ -64,6 +64,10 @@ actions manage that persistence:
 An idle worker (no turn currently dispatched) does not hold this session's reload-quiesce; `/reload` is
 never blocked merely because a persistent tmux worker exists between turns.
 
+Running managed lanes are checkpointed at dispatch and rehydrated with the same lane identity after
+`/reload`. A later terminal event therefore completes the existing goal binding instead of minting a
+replacement lane or risking a duplicate dispatch.
+
 ## Approval-gated dispatch: the standing grant
 
 A real (non-dry-run) `fire_task` or `send_followup` launch requires either a **standing grant** or a
@@ -73,7 +77,9 @@ one-shot interactive approval — never a silent launch:
   (required), and optionally `goalId` (an unscoped grant covers any goal), `allowedTools`,
   `resourceProfile`, `writePaths`, and `expiresInMinutes`. Requires interactive confirmation when a UI is
   attached; in print/rpc/non-interactive mode, requires the `--allow-tmux-dispatch` CLI flag instead.
-  Once granted, matching launches proceed unattended and consume one unit of `maxLaunches` for each child process launched.
+  Once granted, matching launches proceed unattended. Team launches validate every child against the
+  grant and consume one unit of `maxLaunches` for each child process launched; a single-provider grant
+  cannot authorize a mixed-provider team.
 - **`revoke_grant`** ends a standing grant early (defaults to whichever grant is currently active).
 - With **no covering grant**: an interactive session is prompted for a one-shot approval; a
   non-interactive session (no UI, no grant) is **refused** with a clear error — never launched silently.
@@ -118,8 +124,9 @@ When no worker was dispatched, the tool response's `dispatchSkipReason` explains
 - `requirement_already_bound` — the requirement is already bound to a lane that is still queued/running;
   no duplicate dispatch was attempted.
 - `bound_lane_indeterminate` — the requirement is bound to a lane whose liveness/outcome cannot be
-  determined (e.g. after `/reload`); dispatch is refused rather than risking a duplicate worker. A bound
-  lane with a confirmed terminal outcome allows a fresh dispatch normally.
+  determined because its durable record is missing or malformed; dispatch is refused rather than
+  risking a duplicate worker. Normal `/reload` rehydrates running managed lanes. A bound lane with a
+  confirmed terminal outcome allows a fresh dispatch normally.
 
 ## Safety
 

package/docs/ui-reference/README.md

@@ -0,0 +1,9 @@
+# Orchestration UI reference frames
+
+Sanitized text frames used for the native orchestration UI remediation. They contain no session, repository, credential, or model data.
+
+- `orchestration-before.txt`: prior generic tool-output hierarchy.
+- `orchestration-reference.txt`: interaction mechanics extracted from the owner's Pi Teams/task-steps extensions: quiet idle state, compact active summary, status-first rows, and detail on demand. This is a mechanics reference, not copied source or visual identity.
+- `orchestration-after.txt`: packaged native panel target shared by task and worker tools.
+
+These are terminal frames, so the acceptance instrument is cell width, text hierarchy, status identity without color, and behavior under expansion. Semantic colors remain owned by Pi's dark/light theme tokens.

package/docs/ui-reference/orchestration-after.txt

@@ -0,0 +1,7 @@
+[orchestration] active  3 open · 1 worker · 1 queued
+  ● Implement the native panel  high priority · @implementer
+  ! Verify worker review state
+  ○ Run focused tests
+  ● worker-2  worker
+  ◌ tmux-worker-3  tmux worker
+  ! Completed work still needs attached evidence.

package/docs/ui-reference/orchestration-before.txt

@@ -0,0 +1,7 @@
+[task_steps] success
+task_steps update recorded.
+Task steps (3 visible, 3 tracked):
+- [>] step-1 Implement the native panel (high, implementer)
+- [ ] step-2 Run focused tests
+- [!] step-3 Verify worker review state
+Reminder: a completed step has no evidence attached; attach evidence via update before treating it as verified.

package/docs/ui-reference/orchestration-reference.txt

@@ -0,0 +1,6 @@
+[task steps]  1 working · 2 open · 4 done
+  ● Implement the native panel  high priority · @implementer
+  ○ Run focused tests
+  ! Verify worker review state
+
+π teams  ● implementer  ·  ◌ verifier  ·  /teams

package/docs/usage.md

@@ -30,13 +30,21 @@ The editor can be replaced temporarily by built-in UI such as `/settings` or by
 | File reference | Type `@` to fuzzy-search project files |
 | Path completion | Press Tab to complete paths |
 | Multi-line input | Shift+Enter, or Ctrl+Enter on Windows Terminal |
-| Images | Paste with Ctrl+V, Alt+V on Windows, or drag into the terminal |
+| Images | Paste with Ctrl+V on Unix/macOS, Alt+V on Windows, or either on WSL; the same action pastes text when no image is present |
 | Platform shell command | `!command` runs in PowerShell on Windows or Bash elsewhere and sends output to the model |
 | Hidden platform shell command | `!!command` runs without sending output to the model |
 | External editor | Ctrl+G opens `$VISUAL` or `$EDITOR` |
 
 See [Keybindings](keybindings.md) for all shortcuts and customization.
 
+Pasted images are stored under `~/.pi/agent/state/attachments` by default and attached to the current prompt as numbered markers. Later prompts can say `look at image #2` or `look at the image` for the latest current-session attachment. Set `images.clipboardDirectory` to use another folder; a relative folder is an explicit workspace-relative choice. Storage is bounded and Pi never writes an attachment folder into the workspace by default.
+
+### Questions, Steps, and Workers
+
+When an owner choice materially changes the result, the built-in `ask_question` interaction presents up to four questions together. It supports single choice, multi-select, an unrestricted multi-line custom **Other** answer, clipboard text or image paste, explicit **Skip**, configurable keyboard navigation, cancellation, and a final review before a multi-question answer is submitted. The request is checkpointed before display; `/resume` restores the original tool call, and large answers remain exact in a retrievable artifact while only a bounded projection enters prompt context. TUI and RPC hosts use the same fail-closed typed request. Image paste is refused with a visible explanation when the routed model cannot accept images instead of silently replacing it with a placeholder. Non-interactive sessions fail closed instead of inventing an answer, and worker sessions do not construct the question tool.
+
+Native task steps and worker lanes share the same compact work panel. Steps and agents are grouped separately; durable worker task labels and owner-authored profile ids remain visible after `/resume`. Completed worker output remains untrusted until the parent verifies it through the existing result and review contracts.
+
 ## Slash Commands
 
 Type `/` in the editor to open command completion. Extensions can register custom commands, skills are available as `/skill:name`, and prompt templates expand via `/templatename`.
@@ -64,6 +72,8 @@ Type `/` in the editor to open command completion. Extensions can register custo
 | `/toolhealth` | Show tool repair diagnostics and learned standing rules |
 | `/toolprobe [provider/model]` | Probe native/text tool-call support and persist a host-local verdict |
 | `/toolrule-remove <model> <mode>` | Remove one learned tool repair standing rule |
+| `/goal [status\|resume\|complete\|close\|reopen <requirement-id>\|override <text>]` | Inspect or control the durable session goal |
+| `/goal-continue [maxTurns] [maxStallTurns] [maxMinutes]` | Continue the active goal within explicit bounds |
 | `/task`, `/steps` | Manage the native session checklist; see [Task steps](task-steps.md) |
 | `/quit` | Quit pi |
 
@@ -96,6 +106,8 @@ pi --fork <path|id>    # Fork a session into a new session file
 Useful session commands:
 
 - `/session` shows the current session file and ID.
+- `/resume` also resumes a blocked durable goal before that session's worker/process supervision starts;
+  `/goal resume` applies the same persisted transition in place.
 - `/tree` navigates the in-file session tree and can summarize abandoned branches.
 - `/fork` creates a new session from an earlier user message.
 - `/clone` duplicates the current active branch into a new session file.
@@ -202,7 +214,7 @@ cat README.md | pi -p "Summarize this text"
 | `--no-builtin-tools`, `-nbt` | Disable built-in tools but keep extension/custom tools enabled |
 | `--no-tools`, `-nt` | Disable all tools |
 
-Built-in tools include `read`, `edit`, `write`, `grep`, `find`, `ls`, and the uv-managed `python` tool. The agent always sees one stable `bash` tool contract. On Windows, Pi parses its supported simple-command grammar and converts it deterministically to PowerShell; unsupported shell constructs fail closed. Agent, interactive, and RPC shell calls have a 120-second wall-clock default, and Python calls default to 30 seconds. Native goal, task-step, delegation, context, and toolkit tools are activated when their capability/profile gates allow them.
+Built-in tools include `read`, `edit`, `write`, `grep`, `find`, `ls`, `ask_question`, and the uv-managed `python` tool. The agent always sees one stable `bash` tool contract. On Windows, Pi parses its supported simple-command grammar and converts it deterministically to PowerShell; unsupported shell constructs fail closed. Agent, interactive, and RPC shell calls have a 120-second wall-clock default, and Python calls default to 30 seconds. Native goal, task-step, human-question, delegation, context, and toolkit tools are activated when their capability/profile gates allow them.
 
 ### Resource Options