@caupulican/pi-adaptative 0.81.38 → 0.81.40

package/docs/process-matrix.md

@@ -0,0 +1,153 @@
+# process-matrix
+
+`core/process-matrix` is a durable, restart-surviving record of every `pi` process on this
+machine and how they're related: a **master** (an interactive/direct session, or the root of a
+launch chain) and its **workers** (sessions launched with a known parent -- today, tmux-dispatched
+agents). It answers one question reliably even across a crash: *if my parent is gone, what do I
+do?* -- and a companion question on resume: *did I leave orphaned children behind, and what should
+happen to them?*
+
+The matrix is an index of process identity and lifecycle status, not a scheduler: it never decides
+what work runs, only how a process winds down or gets re-parented when its relationship to another
+process breaks.
+
+## Supervision model
+
+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). 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. `/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 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).
+2. If declined: ask *"clean up worker `<entryId>` gracefully?"* Yes → a cooperative wind-down
+   request is written into the worker's entry (the worker notices and self-exits; nothing is
+   killed).
+3. If both declined: leave the entry untouched.
+
+**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
+   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):
+   - **Adopted** (entry's `parentPid` changed to a new, live pid): re-parents to the new master
+     and resumes normal watching -- no task loss.
+   - **Cooperative cleanup requested**: exits immediately.
+   - **Grace window expires** with no directive: exits, leaving the entry `resumable` for a future
+     session to notice.
+
+"No new turns" after a parent is lost is automatic and requires no separate mechanism: a dead
+parent injects no further follow-ups, so the worker simply runs out of work on its own.
+
+## Env + CLI flag contract
+
+Cross-process, like `PI_WORKTREE_LANE`/`--worktree-lane`:
+
+| Env | CLI sugar | Meaning |
+|---|---|---|
+| `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 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
+
+`processMatrix` in `settings.json`:
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master switch. Explicit `false` is the hard off-switch: no entry is ever written, no scan runs, no watcher runs -- zero behavior change once set. |
+| `heartbeatMs` | `30000` | Master heartbeat interval (bounds: 1000-600000). |
+| `adoptionGraceMs` | `300000` | How long an orphaned worker waits for an adopt/cleanup directive before self-exiting (bounds: 5000-3600000). |
+| `watcherPollMs` | `25000` | Poll cadence for parent-liveness and directive checks (bounds: 1000-600000). |
+
+## The zero-footprint sanction
+
+A worker session otherwise carries a strict UAC ceiling and a zero-footprint guarantee -- see
+`docs/worktree-sync.md`'s "Identity, UAC, and zero footprint". A worker's writes to its **own**
+process-matrix entry are a sanctioned artifact, exactly like its own session transcript: the role
+ceiling is untouched, and this is not a new escalation surface. A worker never writes any *other*
+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
+
+Only a `pi`-provider child self-registers and watches -- a non-`pi` agent launched via
+`tmux_agent_manager` (a foreign CLI) has no way to be handed `--parent-pid`/`PI_PARENT_PID` and
+act on it. Its lifecycle stays bounded only at the launch layer (agent/budget/count), the same
+documented limitation `worktree-sync` already has for foreign CLIs -- not a hidden gap, a
+cooperative boundary this system cannot structurally enforce across an arbitrary external process.
+
+## What this does not do
+
+- 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 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.
+
+```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 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.
+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
 
@@ -376,9 +490,12 @@ Keep `retry.provider.maxRetries` at `0` unless provider-level retries are explic
 | `shellPath` | string | platform default | Custom platform-shell path (`pwsh.exe`/`powershell.exe` on Windows; Bash-compatible shell elsewhere) |
 | `shellCommandPrefix` | string | - | Platform-shell snippet prepended to every command (for example, `"shopt -s expand_aliases"` on Bash) |
 | `npmCommand` | string[] | - | Command argv used for npm package lookup/install operations (e.g., `["mise", "exec", "node@24", "--", "npm"]`) |
+| `windowsShell.pythonEngine` | boolean | `true` | Windows only. Routes pipelines, redirection, expansion, chaining, and state-mutating commands (`cd`/`export`/`unset`) through the bundled Python shell engine. Explicit `false` restores the PowerShell-only, simple-command-only contract verbatim — the same fail-closed behavior for pipelines/redirection/expansion/chaining as before the engine existed. |
 
 Pi exposes one stable `bash` contract to the model on every platform. On Windows, the tool router parses a finite simple-command grammar, converts supported Bash-like forms to literal-path PowerShell, and rejects pipelines, redirection, expansion, chaining, nested shells, POSIX scripts, and unsupported builtin forms instead of guessing. Legacy `powershell` tool/profile references map to `bash`. The Windows backend prefers PowerShell 7 (`pwsh.exe`), falls back to Windows PowerShell, and runs with `-NoLogo -NoProfile -NonInteractive -Command` plus UTF-8 console output setup. `shellCommandPrefix` uses backend-native syntax because Pi applies it after routing. Agent, interactive, and RPC shell calls default to a 120-second wall-clock deadline; agent-tool overrides cap at one hour.
 
+With `windowsShell.pythonEngine` at its default (`true`), the router also sends pipelines, redirection, expansion, chaining, and `cd`/`export`/`unset` to a bundled, uv-provisioned Python 3.13 engine implementing a bounded Bash grammar and coreutils vocabulary; state persists across calls and across the PowerShell/engine tiers. If the Python runtime cannot be resolved (uv/network unavailable), the simple-command PowerShell floor keeps working and engine-only commands return a named, actionable error — never a silent downgrade. See [Windows](windows.md) for the full supported-forms table.
+
 The native `python` tool is active by default and resolves Python through pinned `uv`. Pi provisions missing uv/Python during package postinstall, `pi update`, `pi doctor`, or first tool use. Python calls default to 30 seconds and cap explicit overrides at 300 seconds. See [Native Python](python.md).
 
 ```json
@@ -519,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

@@ -37,12 +37,102 @@ Run `/tmux-agents` or call `tmux_agent_manager` with `action: "status"` to check
 2. writes one atomic terminal result when it sees the worker's `DONE` or `BLOCKED` marker, the pane closes, or its one-shot deadline expires;
 3. updates tmux status metadata and emits a display notification.
 
-The parent Pi session watches result-file events. Once every worker is terminal, it records an exactly-once notification marker and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup performs one reconciliation pass for terminal events produced while Pi was offline.
+The parent Pi session watches result-file events. Once a turn's worker is terminal, it records a per-agent notification marker (`notifiedTurn`) and sends a bounded, source-labelled untrusted handoff with `triggerTurn: true`. Startup performs one reconciliation pass for terminal events produced while Pi was offline, and also reconciles tmux **sessions**: see [Persistence](#persistence-follow-ups-reconcile-dismiss) below.
 
 Do not poll pane state, capture pane output, or inspect logs merely to detect completion. Use `job_status` or terminal artifacts after the handoff only when its bounded evidence is insufficient.
 
+## Persistence: follow-ups, reconcile, dismiss
+
+A `fire_task` pane's provider CLI stays alive and interactive after its first terminal marker. Three
+actions manage that persistence:
+
+- **`send_followup`** — re-injects a new prompt into an already-live job's pane (default: the job's
+  first/primary agent; pass `agentId` to target another). It re-arms the completion watcher for a fresh
+  turn using a unique per-turn marker pair, so it cannot be confused with an earlier turn's markers, and
+  reuses the same event-driven, exactly-once handoff. Refuses if the tmux session or pane is gone
+  (relaunch with `fire_task` instead) or if the job was `dismiss`ed.
+- **`dismiss`** — stops tracking a job (no more re-arming, no more handoffs) without killing its tmux
+  session; the pane keeps running and can still be attached to (`tmux attach -t <session>`) or stopped
+  later with `stop_job`/`stop_session`.
+- **Session reconcile** — on session start, Pi diffs live tmux sessions against its own job records for
+  jobs it started. A session that has disappeared while its job was not yet terminal is marked orphaned
+  (informational only — nothing is ever killed to produce this state, and the job directory is never
+  deleted automatically). A session that is still alive with a pending turn has its watcher re-armed so
+  the job can still complete normally. Killing a session always stays behind the explicit
+  `stop_job`/`stop_session` confirm path.
+
+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
+one-shot interactive approval — never a silent launch:
+
+- **`grant_dispatch`** authorizes repeated unattended dispatch. Set `agent` (required), `maxLaunches`
+  (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. 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.
+
+A grant-covered (or one-shot-approved) `pi` child is launched with a **restricted profile**: `--tools`
+(or a read-biased default), `--resource-profile` (or `--no-extensions --no-skills`), and a scoped
+`--append-system-prompt` naming the grant and a fixed hard-stop list (publish/push/tag/credential
+changes/destructive deletion must come back BLOCKED, never self-approved). This pushes the envelope into
+the **child's own** launch configuration — it is not an in-process sandbox, and non-`pi` agents
+(`agy`/`claude`/`codex`/`opencode`/custom) are bounded only at the launch layer; their internal tool-loop
+behavior is that CLI's own responsibility.
+
+Grant budget (`maxLaunches`, `expiresInMinutes`) is real and enforced. `maxUsdAdvisory` and any
+self-reported worker usage are **advisory** — a claim to review, never a hard cap across the process
+boundary (the child bills under its own authentication).
+
+Dispatched tmux workers appear as `tmux-worker` lanes alongside in-process worker lanes in `/autonomy`
+and `delegate_status`; a worker's self-reported changed files are re-checked against the session's active
+write scope and flagged for parent review when out of scope, exactly like an in-process worker's.
+
+## Goal-bound dispatch (`goal dispatch_worker dispatchTarget:"tmux"`)
+
+The `goal` tool's `dispatch_worker` action can bind a single open requirement to a persistent tmux worker
+instead of the default in-process one: pass `dispatchTarget: "tmux"`. Core invokes `fire_task` itself (the
+same call the model would make) with exactly one `pi` agent, so the dispatch maps 1:1 to the
+requirement's bound lane; the launch still goes through the standing-grant authorization above unchanged
+— an unattended goal/idle loop with no covering grant is honestly refused, never silently launched. The
+requirement's binding is recorded either way; a successful tmux dispatch waits and resumes through the
+same lane machinery as an in-process worker.
+
+When no worker was dispatched, the tool response's `dispatchSkipReason` explains why:
+
+- `no_standing_grant` — no covering grant, and this call had no UI to prompt (run `grant_dispatch` first).
+- `tmux_extension_not_loaded` — `tmux_agent_manager` is not loaded in this session (see Enable above).
+- `tmux_dispatch_failed` — the `fire_task` launch threw for a reason other than the grant (a bad jobId, a
+  live session-name collision, an environment failure).
+- `tmux_dispatch_incomplete` — the launch call returned without the job/agent details needed to identify
+  the new lane.
+- `lane_correlation_failed` — the new lane could not be resolved to its internal tracking id.
+- `worktree_create_failed` — worktree-sync refused the lane before any tmux pane was launched.
+- `worker_capability_insufficient` — the selected model is not eligible for a lane worker; no lane or pane was created.
+- `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 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
 
-Launch actions run directly unless `dryRun: true` is requested. Stop actions can discard active pane work, so they remain previews by default and require `confirm: "yes-tmux-stop"` for execution. Existing sessions are never replaced silently; `force: true` archives an old job directory but does not kill a live tmux session.
+Launch actions run directly unless `dryRun: true` is requested, and are approval-gated per the standing
+grant above. Stop actions can discard active pane work, so they remain previews by default and require
+`confirm: "yes-tmux-stop"` for execution. Existing sessions are never replaced silently; `force: true`
+archives an old job directory but does not kill a live tmux session.
 
 The package includes the extension README and team templates under `dist/bundled-resources/extensions/tmux-agent-manager/`; the source repository keeps them under the matching `src/bundled-resources/` path.

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