@caupulican/pi-adaptative 0.81.39 → 0.81.41

package/docs/extensions.md

@@ -13,6 +13,7 @@ Extensions are TypeScript modules that extend pi's behavior. They can subscribe
 - **Custom UI components** - Full TUI components with keyboard input via `ctx.ui.custom()` for complex interactions
 - **Custom commands** - Register commands like `/mycommand` via `pi.registerCommand()`
 - **Session persistence** - Store state that survives restarts via `pi.appendEntry()`
+- **Owned storage** - Keep durable state, rebuildable cache, and bounded work in one extension namespace
 - **Custom rendering** - Control how tool calls/results and messages appear in TUI
 
 **Example use cases:**
@@ -1268,6 +1269,49 @@ export default function (pi: ExtensionAPI) {
 
 ## ExtensionAPI Methods
 
+### pi.getStorage(namespace)
+
+Bind one portable storage namespace to the current extension generation:
+
+```typescript
+import { mkdir, writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+export default function (pi: ExtensionAPI) {
+  const storage = pi.getStorage("my-extension");
+
+  pi.registerCommand("save-extension-state", {
+    handler: async (_args, ctx) => {
+      await mkdir(storage.stateDir, { recursive: true });
+      await writeFile(join(storage.stateDir, "state.json"), JSON.stringify({ cwd: ctx.cwd }), "utf8");
+    },
+  });
+}
+```
+
+The returned paths have separate lifecycles:
+
+- `stateDir` → `~/.pi/agent/state/extensions/<namespace>/`: durable machine state. Deleting it loses history.
+- `cacheDir` → `~/.pi/agent/cache/extensions/<namespace>/`: rebuildable data. It must be safe to delete.
+- `acquireWorkRun()` → `~/.pi/agent/work/extensions/<namespace>/<run-id>/`: transient output with an ownership manifest, active lease, and hard retention ceilings.
+
+Calling `getStorage()` is zero-write. It validates the namespace and only returns paths; create `stateDir` or `cacheDir` when the extension actually writes. A generation may bind only one namespace, repeated calls with that namespace return the same view, and unrelated loaded extensions cannot claim the same namespace. Names are lowercase portable path segments of at most 64 characters; traversal, separators, uppercase ambiguity, trailing dots, and Windows-reserved names are rejected.
+
+Work leases are released automatically if the factory fails and when the extension unloads or reloads. Release a lease sooner when the operation is finished; release is idempotent and does not immediately delete its artifacts:
+
+```typescript
+const run = storage.acquireWorkRun({ runId: "export-1", retention: { maxRuns: 8 } });
+try {
+  await writeFile(join(run.path, "report.json"), JSON.stringify(report), "utf8");
+} finally {
+  run.release();
+}
+```
+
+Extension-selected retention can only reduce the harness defaults. It cannot exceed 30 days, 64 inactive runs, 512 MiB, 10,000 scanned runs, or 100,000 recursively scanned entries, and it cannot be disabled through this API. Do not create extension-specific directories directly beside `auth.json` and `settings.json`. Do not store credentials in extension state or cache; use Pi authentication configuration, environment-backed references, or an external credential manager.
+
+Extensions are trusted process code, so Pi cannot prevent one from bypassing this API and writing an arbitrary filesystem path. The enforceable package contract is: bundled/packaged extensions use `getStorage()`, transient artifacts go through bounded leases, and `pi doctor` makes nonconforming root writers visible. Durable state must compact its own history; rebuildable cache must impose its own file/byte policy. Neither directory is an unbounded artifact sink.
+
 ### pi.on(event, handler)
 
 Subscribe to events. See [Events](#events) for event types and return values.
@@ -1684,6 +1728,15 @@ pi.registerCommand("my-setup-teardown", {
 
 ## State Management
 
+Use the storage class that matches the data:
+
+- Branch/session state that must follow conversation history belongs in tool result `details` or `pi.appendEntry()`.
+- Durable extension-global machine state belongs in `pi.getStorage(...).stateDir`.
+- Recomputable indexes and downloaded derivatives belong in `cacheDir`.
+- Reports, downloads, subprocess output, and scratch files belong in a leased `acquireWorkRun()` directory.
+
+Never place extension artifacts directly under `~/.pi/agent/`; `pi doctor` reports unexpected root entries without moving or deleting them.
+
 Extensions with state should store it in tool result `details` for proper branching support:
 
 ```typescript
@@ -2011,6 +2064,10 @@ import {
   DEFAULT_MAX_BYTES, // 50KB
   DEFAULT_MAX_LINES, // 2000
 } from "@caupulican/pi-adaptative";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+
+const storage = pi.getStorage("my-extension");
 
 async execute(toolCallId, params, signal, onUpdate, ctx) {
   const output = await runCommand();
@@ -2024,8 +2081,11 @@ async execute(toolCallId, params, signal, onUpdate, ctx) {
   let result = truncation.content;
 
   if (truncation.truncated) {
-    // Write full output to temp file
-    const tempFile = writeTempFile(output);
+    // Write full output into this extension's bounded work area
+    const run = storage.acquireWorkRun();
+    const tempFile = join(run.path, "full-output.txt");
+    await writeFile(tempFile, output, "utf8");
+    run.release();
 
     // Inform the LLM where to find complete output
     result += `\n\n[Output truncated: ${truncation.outputLines} of ${truncation.totalLines} lines`;

package/docs/harness-architecture.md

@@ -0,0 +1,156 @@
+# Harness architecture
+
+Pi Adaptative has one production harness. `AgentSession` is its public facade and composition root;
+the low-level agent loop and provider transports remain separate packages. The deleted
+`packages/agent` `AgentHarness` was a competing implementation and must not be restored.
+
+## Package boundaries
+
+```text
+coding-agent/AgentSession
+  ├─ runtime + resource policy       RuntimeBuilder, ResourceLoader, ProfileFilterController
+  ├─ model execution policy         ModelSelection, ModelRouter, LocalRuntime, ToolProtocolController
+  ├─ foreground turn coordination   ContextPipeline, CompactionController, ForegroundRecoveryController
+  └─ child work coordination        WorkerDelegation, BackgroundLane, Reflection, managed-lane bridge
+                 │
+                 ▼
+agent                         ai
+agent loop + session tree     model metadata + provider transports + wire-format repair
+```
+
+Provider-specific request and response behavior belongs in `packages/ai`. Provider-neutral choices
+about which model, reasoning level, tools, resources, or lane to use belong in `packages/coding-agent`.
+`packages/agent` owns the reusable loop, session tree, retry primitives, and compaction mechanics; it
+does not own a second application harness.
+
+## Model execution contract
+
+Every foreground or child request resolves the same four facts before transport:
+
+1. Model identity and metadata come from `ModelRegistry` as `Model<Api>`.
+2. Authentication and headers come from the registry for that exact model.
+3. `resolveModelThinkingLevel()` applies explicit intent, model defaults, harness fallback, and
+   capability clamping.
+4. `resolveModelToolProtocol()` selects native calls, a forced text fallback, or the exact calibrated
+   text dialect. Foreground and isolated tool loops use the same result.
+
+Provider adapters may translate those facts to their wire protocol, but must not make orchestration
+policy. Tool names that collide with a provider-reserved namespace are mapped only at the provider
+boundary and mapped back for local execution and history.
+
+## UAC is construction-time omission
+
+UAC's primary guarantee is that a withheld capability is not materialized. Runtime checks remain a
+second line of defense, not the main implementation.
+
+- `RuntimeBuilder` resolves one access policy before invoking built-in or override tool factories.
+  The same policy governs registration and activation, preventing construction/activation drift.
+- `ResourceLoader` filters extension paths before module import and filters skill, prompt, theme, and
+  context paths before content loading. Live extension loading repeats the profile check before
+  import.
+- Isolated research and worker lanes create fresh tools only for their expanded lane grant. They do
+  not copy the foreground registry, extensions, skills, shell, or mutable memory surface.
+- Worker orchestration state is lazily materialized only when the active surface grants `delegate`
+  (or a managed-lane terminal report requires the shared notifier); worker-role sessions allocate no
+  worker scheduler, lifecycle store, or notification coordinator.
+- Managed children carry parent identity. A valid parent PID classifies the process as a worker before
+  settings, stores, resources, or tools are built, so the hard worker ceiling cannot be re-granted by
+  a permissive profile.
+- Per-call path/capability gates still validate every isolated lane tool invocation. Worktree-bound
+  workers additionally run behind the lane mutation gate.
+
+An extension is the unit of module loading. If a profile grants an extension, its module code may
+register several definitions before tool-level filtering. Profiles that need zero extension
+footprint must omit that extension at the resource layer, not merely block one of its tools.
+
+## Child work contracts
+
+Owner-authored orchestration profiles are the routing authority. A profile fixes role, ordered model
+policy, exact thinking level, tool names, resource profiles, semantic capability ceiling, budgets,
+concurrency, lease duration, and verification policy. An architect profile additionally declares the
+only worker profile IDs it may dispatch. The model-facing dispatch request contains a task, profile
+ID, instructions, and resource pointers; it has no model, thinking, tool, budget, or concurrency
+override fields.
+
+The durable control plane is an append-only session event store projected into objectives, DAG
+tasks, attempts, leases, checkpoints, logical agent bindings, typed results, and a notification
+outbox. Every result carries its attempt lease and fencing token. A stale worker therefore cannot
+win a race after retry or resume. In-process isolated completions have no resumable transcript: an
+interrupted lease is fenced and its persisted dispatch is re-queued as a new attempt. A process-backed
+Pi worker instead retains its logical agent ID and resume context and is woken with `/resume` against
+the same session, worktree, orchestration profile, and checkpoint pointers when present.
+
+Policy is a mandatory pre-lease gate. An attempt cannot lease without a compiled execution grant.
+When compilation crosses owner authority or budget, the gate persists a typed approval request and
+an owner notification; approval and rejection replay as durable human decisions. Approval alone is
+never authority: an approved attempt remains unleaseable until policy compiles and binds a new grant
+under the expanded owner authorization. Pausing an objective blocks lease, start, and agent resume;
+cancellation remains a replayable terminal transition across its open tasks and attempts.
+
+Acceptance is a runtime invariant, not a worker claim. Task criterion IDs must refer to their
+objective, a completed criterion-bound result must carry trusted evidence for every linked criterion,
+and an objective cannot close until all required criteria have trusted evidence in its task results.
+
+In-process workers are bounded child loops with fresh context, a synthetic cache-affinity key, a
+profile-pinned model and exact reasoning level, a construction-filtered tool surface,
+turn/time/token/tool/cost bounds, and parent validation of the result. Process-capable profiles may
+expose `run_process`, which uses an exact executable allowlist, direct argv, a scoped environment,
+bounded output, and process-tree termination; unrestricted shell is not inherited. Worker output is
+untrusted; the parent retrieves it through `delegate_status` after a terminal lane event. A profile
+that requires independent verification names a separate owner-pinned verifier profile. The runtime
+automatically dispatches that verifier as a durable task, withholds the implementation's terminal
+handoff, and reconciles the typed verdict before the implementation can become accepted. Restart
+recovery closes both persistence gaps: an implementation awaiting a not-yet-created verifier is
+re-dispatched, while a persisted verifier result awaiting reconciliation is applied exactly once.
+
+Out-of-process managed workers use the same lifecycle shape:
+
+```text
+queued → running → terminal signal → bounded persisted handoff → parent notification → explicit retrieval
+```
+
+Completion discovery is event-driven. A parent never polls pane output to learn whether work ended,
+and a late worker result is never injected into an active foreground transcript. Every managed
+process must emit a terminal signal even on failure, persist a bounded handoff, and wake its owner.
+
+## Runtime generations and reload
+
+A runtime generation consists of the selected resource profile, loaded resources, base tool
+definitions, extension runner, wrapped registry, active tool request, and derived system prompt.
+Reload constructs and doctors a candidate generation, then commits it or restores the complete prior
+snapshot. Model/profile changes are re-applied only after extension providers are bound. In-flight
+turns, compaction, and child work register with the shared quiescence gate, so live mutation never
+races an active execution unit.
+
+## Ownership rules for further growth
+
+- Keep `AgentSession` as facade and composition root; move coherent state machines into controllers
+  with narrow dependencies instead of adding another facade with overlapping state.
+- Add a capability decision to the shared model/resource contract first, then consume it everywhere.
+  Do not add provider-name branches to orchestration code when model metadata can express the fact.
+- Decide resource and tool authority before loading or construction. Keep execution gates for path,
+  argument, and race-sensitive checks.
+- A background process is incomplete until its terminal event, durable bounded handoff, and owner
+  notification all succeed or are reported failed.
+- Persist only serializable facts and stable identities. Runtime tools, extension functions, streams,
+  and credentials are reconstructed dependencies, never session payloads.
+- New harness behavior requires a focused faux-provider regression. Provider APIs and paid tokens are
+  not used by the coding-agent suite.
+
+Worker lifecycle, scheduling, execution, verification, recovery, and notification are owned by
+`WorkerDelegationController`. `ResearchLaneController`, `ModelFitnessController`, and
+`GoalAutoContinueController` own their respective timers, guards, cancellation, accounting, and
+persistence; research and fitness share only the provider-neutral `LaneModelResolver`.
+`BackgroundLaneController` only coordinates these owners and their shared lane read model;
+`ManagedLaneController` owns the distinct out-of-process managed-lane bridge. `ToolProtocolController` owns model protocol selection, probing, calibration,
+circuit breaking, repair teaching, and its per-turn state. `CompactionController` owns manual and
+automatic detection, execution, retries, cancellation, persistence, and extension notification;
+`CompactionSupport` is its provider-neutral model/auth/settings policy.
+`ForegroundRecoveryController` owns the terminal-response latch and ordered retry, quota failover,
+retry closeout, compaction, and queued-continuation decisions. Foreground prompt submission remains
+an `AgentSession` transaction because it composes those independent owners and the public event
+surface; extracting it today would create a callback-heavy proxy rather than a new state owner. Its
+contract is balanced routing events, commit-on-success `nextTurn` consumption, stable per-turn cost
+accounting, and bounded early-message identity cleanup.
+`HostStateStore` owns validated versioned host partitions, lock-scoped mutations, atomic replacement,
+and worker-role zero-write behavior for fitness, model adaptation, and tool-selection evidence.

package/docs/keybindings.md

@@ -87,7 +87,17 @@ Modifier combinations: `ctrl+shift+x`, `alt+ctrl+x`, `ctrl+shift+alt+x`, `ctrl+1
 | `app.exit` | `ctrl+d` | Exit (when editor empty) |
 | `app.suspend` | `ctrl+z` (none on Windows) | Suspend to background |
 | `app.editor.external` | `ctrl+g` | Open in external editor (`$VISUAL` or `$EDITOR`) |
-| `app.clipboard.pasteImage` | `alt+v` | Paste image from clipboard |
+| `app.clipboard.pasteImage` | `ctrl+v` (Unix/macOS), `alt+v` (Windows), both (WSL) | Paste image or clipboard text |
+
+### Native Questions
+
+These actions apply while the built-in `ask_question` interaction has focus. The dialog also uses the configurable `tui.select.*` and `tui.input.*` actions above, plus `app.clipboard.pasteImage` while entering a custom **Other** answer.
+
+| Keybinding id | Default | Description |
+|--------|---------|-------------|
+| `app.question.next` | `tab`, `right` | Move to the next question or review |
+| `app.question.previous` | `shift+tab`, `left` | Move to the previous question |
+| `app.question.toggle` | `space` | Toggle a multi-select answer |
 
 ### Sessions
 

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/providers.md

@@ -202,7 +202,7 @@ export AZURE_OPENAI_DEPLOYMENT_NAME_MAP=gpt-4=my-gpt4,gpt-4o=my-gpt4o
 ### Amazon Bedrock
 
 ```bash
-# Option 1: AWS Profile
+# Option 1: AWS Profile (recommended for IAM Identity Center / SSO)
 export AWS_PROFILE=your-profile
 
 # Option 2: IAM Keys
@@ -216,6 +216,14 @@ export AWS_BEARER_TOKEN_BEDROCK=...
 export AWS_REGION=us-west-2
 ```
 
+For an SSO profile, AWS CLI v2 is required and the modern `sso-session` profile format is recommended.
+Start Pi with `AWS_PROFILE` set, or run `/login amazon-bedrock` and enter the profile name for the
+current Pi process. Pi runs `aws sso login --profile <profile>` without a shell. The AWS SDK refreshes
+ordinary role credentials; if the underlying SSO session later expires, Pi performs one foreground
+login and replays the Bedrock request once, only before a response has started. Background and worker
+requests never open a browser and instead return an authentication-required error to the owning
+session.
+
 Also supports ECS task roles (`AWS_CONTAINER_CREDENTIALS_*`) and IRSA (`AWS_WEB_IDENTITY_TOKEN_FILE`).
 
 ```bash

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: