@caupulican/pi-adaptative 0.81.39 → 0.81.41

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 @@
+# Activity-lane reference frames
+
+Sanitized, source-labeled evidence for the orchestration UI remediation:
+
+- `orchestration-before.txt`: duplicated multiline transcript, footer, and loader surfaces.
+- `orchestration-reference.txt`: lifecycle mechanisms verified in current Codex and Claude Code builds plus Pi-specific constraints.
+- `orchestration-after.txt`: the merged Pi-native target immediately above the prompt editor.
+
+The acceptance instrument is terminal-cell width, state identity without color, focus preservation, bounded completion feedback, resume behavior, idle zero-height behavior, and explicit user-versus-worker audience routing.

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

@@ -0,0 +1,14 @@
+Active, directly above the editor:
+ ● Step 1/3 · Implementing status lane  ·  ● agent · verifier  ·  ● Goal 2/4 · Stabilize
+> prompt
+
+Successful transition (held briefly):
+ ● Completed · Implement status lane
+> prompt
+
+Failed transition (held briefly):
+ ● failed · verifier
+> prompt
+
+Idle after the hold:
+> prompt

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

@@ -0,0 +1,13 @@
+[task_steps] success
+  ● Implement the native panel
+  ○ Run focused tests
+
+[goal] progress
+Goal active: stabilize the harness
+
+[workers] status
+  ● implementer
+
+Working...
+delegate: 1 running
+> prompt

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

@@ -0,0 +1,16 @@
+Codex mechanism (20dafe201d91d4405eef05ecd1db0257f13a9ac8)
+- one event-owned status row adjacent to the composer
+- width-bounded label
+- absent when no task is running
+
+Claude Code mechanism (2.1.219, 7006c4c3acac98e554d3997baeda6a7fa4d1ff7c)
+- activeForm preferred for current task wording
+- bounded horizontal activity summary
+- short completion-feedback hold
+
+Pi constraints
+- canonical goal/task/lane truth
+- semantic theme tokens
+- explicit expansion for detail
+- no replay of terminal state on resume
+- no human UI routing in worker sessions

package/docs/usage.md

@@ -30,13 +30,29 @@ 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.
+
+### Secret Store
+
+In an interactive user session, ask the agent to store or adopt a project's dotenv file, for example: `Store this project's credentials in the project-dev secret profile.` The native `secret_store` tool opens a private multiline editor where the owner pastes ordinary plaintext dotenv content. Existing unmanaged dotenv content is prefilled locally for review. The editor disables history, undo, kill-ring, autocomplete, paste collapsing, and external-editor temp files, and clears its buffer on close. Only profile, variable-name, and workspace-binding metadata reaches the model; the plaintext document never enters tool arguments, results, transcripts, or telemetry. Pi collects the vault passphrase through separate masked input and encrypts the bounded profile and bindings under `~/.pi/agent/state/secrets/vault.json`. Only the derived key and explicitly activated profile environment remain cached in the current Pi process; asking the agent to lock the vault or exiting Pi clears them and resets credential-bearing shell state. Worker, print, and RPC sessions cannot use the capture path.
+
+The encrypted binding remembers the workspace and relative dotenv filename. Later, the agent can list that metadata and call `secret_store` materialization for the current workspace without asking for a destination again. Once unlocked and materialized, Pi injects the profile into Bash and Python child environments so the agent runs the consuming application normally without reading or sourcing the file. Direct read, edit, search, and shell-inspection attempts against credential files are refused across foreground and worker tool surfaces, and known values are redacted from streamed results and errors.
+
+Every materialized dotenv file is plaintext and mode `0600` on POSIX. Workspace copies must remain ignored by version control. The protection is a model-facing tool boundary, not an OS sandbox: another process running as the same OS user can read the file, and code deliberately granted network or process authority can use the injected credential. Keep execution policy and approval gates appropriate to that authority.
+
 ## 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 +80,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 +114,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 +222,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`, `secret_store`, 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, secret-store, delegation, context, and toolkit tools are activated when their capability/profile gates allow them.
 
 ### Resource Options
 

package/docs/work-directory.md

@@ -22,7 +22,7 @@ The default per-tenant retention policy is 30 days, 64 inactive runs, 512 MiB, 1
 
 ## Repository API
 
-Extensions and internal code can use the public helpers:
+Harness internals and programmatic SDK integrations can use the low-level public helpers:
 
 ```ts
 import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/pi-adaptative";
@@ -34,9 +34,11 @@ import { acquireWorkRun, getProcessWorkRun, pruneWorkTenant } from "@caupulican/
 
 Use a named run only for transient coordination that must be shared across Pi processes. Use a generated run for commands, reports, downloads, tests, benchmarks, probes, and output spills.
 
+Packaged extensions should use `pi.getStorage("extension-name").acquireWorkRun()` instead. It binds work to one extension namespace, releases leases automatically on failure/unload, and clamps extension-selected retention to the harness ceiling. Calling `getStorage()` alone creates no directories. Durable extension state and rebuildable extension cache similarly live under `state/extensions/<namespace>/` and `cache/extensions/<namespace>/`; see [extensions.md](extensions.md#pigetstoragenamespace).
+
 ## Not transient
 
-Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries.
+Configuration and durable user data stay outside `work/`: `settings.json`, `auth.json`, `models.json`, `sessions/`, `state/`, `skills/`, `extensions/`, `prompts/`, `themes/`, profiles, backups, and managed binaries. Directory overlays are contained under `profiles/directories/`; explicit configuration snapshots are contained under `state/backups/config/`.
 
 Do not put Automata memory or its graph in Pi's work directory. Automata remains an external memory system.
 
@@ -51,20 +53,29 @@ straggler:
 ```text
 ~/.pi/agent/
   auth.json settings.json models.json keybindings.json MEMORY.md USER.md SYSTEM.md …   user config/memory (root)
+  okf-memory/                                                                          authored memory (root)
   skills/ extensions/ prompts/ themes/ profiles/                                       user resources (root)
+    profiles/directories/<workspace-hash>/settings.json                                directory overlays
   state/     durable machine state: model adaptation/fitness, tool-performance,        -- stateDir/stateFile
-             learning observations, trust decisions (trust.json), failure corpus, …
+             learning observations, trust decisions, failure corpus, config backups, …
+    state/backups/config/                                                              explicit config snapshots
+    state/extensions/<namespace>/                                                      extension durable state
   cache/     rebuildable, safe to delete: tool-path probes, jiti transform cache, uv    -- cacheDir/cacheFile
+    cache/extensions/<namespace>/                                                      extension rebuildable cache
   bin/       managed executable helpers (fd, rg)                                       -- binDir (legacy getBinDir accessor)
   work/      transient/scratch (this document)                                         -- re-exported from agent-paths.ts
+    work/extensions/<namespace>/<run-id>/                                              extension leased work
   runtimes/<kind>  models/<kind>  sessions/  npm/  git/  worktrees/                    -- runtimesDir/modelsDir/sessionsDir/npmDir/gitDir/worktreesDir
 ```
 
 `state/` holds durable history — deleting it loses real data, not just cache. `cache/` is always safe
 to delete; the next run re-probes or recomputes it. A startup migration (`migrateAgentDirLayout`,
 `src/migrations.ts`, run before any store/trust read) relocates confirmed root-level stragglers into
-their canonical location — currently just `trust.json` into `state/` — idempotently and without ever
-overwriting an already-migrated target. `resource-profiles/` intentionally stays at the agent-directory
-root rather than moving under `state/`: it's surfaced in two user-visible profile-menu description
-strings, and moving it needs those updated in the same change (tracked open in the bug ledger, not a
-silent gap).
+their canonical locations: `trust.json` into `state/`, `backups/` into `state/backups/config/`, and
+`resource-profiles/` into `profiles/directories/`. Obsolete root `auto-learn/` and `tmp/` trees are
+preserved under `state/legacy-layout/`, where they cannot compete with live config/resources. Whole
+roots move atomically when possible; literal Windows `auth.json:Zone.Identifier` sidecars move there
+too. Partial migrations scan a bounded number of top-level entries and preserve collisions under
+`state/migration-conflicts/` instead of overwriting either copy.
+
+`pi doctor` performs a bounded, read-only scan of the agent directory root. It stays silent for the canonical config, memory, resource, and storage entries above and warns about external or legacy root writers. The audit never relocates or deletes unknown data.

package/examples/extensions/custom-provider-anthropic/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "pi-extension-custom-provider",
-  "version": "0.81.39",
+  "version": "0.81.41",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "pi-extension-custom-provider",
-      "version": "0.81.39",
+      "version": "0.81.41",
       "dependencies": {
         "@anthropic-ai/sdk": "^0.52.0"
       }

package/examples/extensions/custom-provider-anthropic/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-anthropic",
   "private": true,
-  "version": "0.81.39",
+  "version": "0.81.41",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",

package/examples/extensions/custom-provider-gitlab-duo/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-extension-custom-provider-gitlab-duo",
   "private": true,
-  "version": "0.81.39",
+  "version": "0.81.41",
   "type": "module",
   "scripts": {
     "clean": "echo 'nothing to clean'",