@aeondave/pi-persona 1.17.1 → 1.17.4

package/docs/ARCHITECTURE.md

@@ -33,12 +33,17 @@ Persona names are data, never dispatch keys. Optional `delegation:` fields apply
 builtin, user, or project persona: `requireBrief`, `outputContract`, `requireDisjointWrites`,
 `requireFreshVerification`, and `verificationAgents`. Council behavior remains independently
 declarative through `council: { strategy, roster, params }`; a custom persona can compose any installed
-strategy/team without a core change. The gates use effective agent/tool capabilities, conservatively
+strategy/team without a core change. Ownership intent follows the agent, not the caller: an agent definition
+can declare the area it alone writes (`writeSet`, e.g. `research` → `.research/`), and a write-capable delegate leg that
+names no `writeSet` inherits it before the gates run, so the disjoint-ownership and overlap checks see a
+declared owner; a leg's own set wins, and the field stays declarative (nothing enforces paths at runtime).
+Legs restricted to read-only tools do not inherit ownership defaults, so parallel readers do not conflict.
+The gates use effective agent/tool capabilities, conservatively
 treat shell-capable, MCP-enabled, or unknown tools as potential writers, and enforce the requested fan-out
-concurrency in both synchronous and background execution. A serialized verifier is accepted only
+concurrency on the single launch path (interactive background or headless inline). A serialized verifier is accepted only
 after every material writer in that batch; otherwise the call fails before a child starts. The rule
 also holds ACROSS calls: a verifier launched while a material-writer background run is still live is
-rejected with the run id to wait on, so a later call cannot slip past the in-batch ordering.
+rejected, naming the mutating run ids, so a later call cannot slip past the in-batch ordering.
 
 ### The effort ladder (make the simple case simple; complexity is opt-in)
 
@@ -56,7 +61,9 @@ rejected with the run id to wait on, so a later call cannot slip past the in-bat
 You climb only when you want determinism, structure, or reuse. Nothing forces the higher tiers.
 The `council` tool is a gateway to all installed strategies, not a universal instruction to vote on
 routine work. Choose a strategy when its topology adds value; MAGI and Judge retain their specialized
-persona focus. A caller can supply ephemeral `members` with inline roles/models/skills instead of a
+persona focus. The tool description lists every strategy with its `when`, positional roster and required
+params, generated from the registry (`strategyCatalog`), and a call missing a required param is refused
+before any run exists. A caller can supply ephemeral `members` with inline roles/models/skills instead of a
 named team, without persisting a team or switching personas.
 
 ## Binding invariants (I1–I7)
@@ -74,9 +81,10 @@ These are the guardrails a contributor must not violate. They are enforced in co
   by the SDK on every `agent()` call and by the engine per child. Concurrency is shared across all
   calls in one SDK instance; token admission uses completed usage and is rechecked after queueing, so
   active legs can overshoot it. Nesting depth is not one of these numeric knobs — it is structural,
-  capped at 1: a child's whole pi-persona extension activation short-circuits under
-  `PI_PERSONA_DISABLE=1` (the **fork-bomb guard**), so it registers NO tools at all —
-  `delegate`/`council`/`orchestrate`/`flow` included. On the child engine this is a one-shot env var
+  capped at 1: full pi-persona activation short-circuits under `PI_PERSONA_DISABLE=1` (the
+  **fork-bomb guard**), so no supervisor orchestration tools (`delegate`/`council`/`flow`) are
+  registered. A broker-enabled child instead loads the minimal bridge, which registers only
+  granted communication and scoped result-reader tools. On the child engine this is a one-shot env var
   set on each spawned process; the in-process engine instead shares one Node process across
   concurrently-building sub-sessions, so it ref-counts the guard (`inproc.ts`) to keep it set until the
   LAST one finishes. The in-process engine also excludes `ORCHESTRATION_TOOLS` from the child session
@@ -100,7 +108,10 @@ These are the guardrails a contributor must not violate. They are enforced in co
 - **I5 — Flows are the top tier.** A declarative DAG (statically verified: acyclicity, references
   resolve, join reducers valid) above strategies. The flow engine stays thin — parse, verify,
   schedule, persist, resume — and a flow node may call any strategy. Journaled: finished nodes replay
-  from disk with no re-spend.
+  from disk with no re-spend. A resume matches only the same flow, the same task and the same project
+  (`flowRunHash` = flow + task + cwd); another task starts from scratch. A `gate: true` phase shows its
+  output and its dependents to the operator; a rejection returns `stoppedAtGate` (not a failure, though
+  `ok` stays false so mandatory orchestration still fails closed).
 - **I6 — Spawning is opportunistic by default; mandatory only when the persona declares it.** Two
   first-class cases: *opportunistic* (`mode: solo` / no block — the supervisor MAY delegate by its own
   judgement; never forced) and *mandatory* (`mode: strategy|flow|parallel|pipeline` with a roster —
@@ -141,6 +152,12 @@ These are the guardrails a contributor must not violate. They are enforced in co
 
 ## Module layout
 
+The supported host is the latest stable Pi (currently 1.4.0). Runtime code uses its public APIs
+directly; obsolete host facades, ignored SDK options and compatibility-only aliases are removed
+with their callers. Genuine host failures remain explicit rather than fabricating session identity
+or model availability. One-way user-data migrations and retained-history readers are separate data
+contracts: they remain only while serving stored user data, not to support an older Pi runtime.
+
 Domain dependencies remain downward-only and acyclic: `core ← all`; `engine`/`bus → core`;
 `orchestration → engine + bus + core`; `persona → orchestration + core`; the Exocom transport and
 ledger → `core + bus`; `tools`/`ui → lower layers`. `src/exocom/install.ts` is deliberately the
@@ -161,8 +178,9 @@ engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain
   `peerDependencies`, `/doctor`'s `pi:` line, and the README's stated floor trace back to this
   constant), `models`, `brief` (`buildDelegationBrief` — the per-turn delegation brief: live roster +
   standing hand-off default; and `buildExocomBrief` — the per-turn peer brief: live peers, the
-  peer-vs-sub-agent split, and the relevance bound on an exchange), `nudge` (the two
-  runtime-reinforcement state machines, `DelegationNudge` + `PersistenceNudge`), `display-label`
+  peer-vs-sub-agent split, and the relevance bound on an exchange), `nudge` (the
+  runtime-reinforcement state machines `DelegationNudge` + `PersistenceNudge`, and the call-time wake
+  guards `PollGuard` + `longWaitSeconds`), `display-label`
   (`sanitizeDisplayLabel` — an untrusted name reduced to bounded metadata before interpolation
   outside a fence), `timer` (`TimerScheduler` — the pure alarm engine behind the `timer` tool), `time`
   (`formatDuration` / `peerSentLabel` / `sessionElapsedLabel` / `buildSessionAnchor` — the elapsed-time
@@ -205,7 +223,7 @@ engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain
   `spine.ts` (the shared behavioral layer's SOURCE resolution — docs/SPINE.md; composition sits in
   `persona.ts` for supervisor turns and in the engines for delegated legs).
 - **`src/tools/`** — `delegate.ts`, `intercom.ts`, `exocom.ts` (the `exocom_list`/`exocom_send`
-  tools), `exocom-work.ts` (claim/ask/answer/decline/wait/release/progress). **`src/ui/`** — agent tree/overlay, model picker, `presentation.ts` (the shared
+  tools), `exocom-work.ts` (claim/ask/answer/decline/wait/release/progress). **`src/ui/`** — agent tree/overlay, model picker, `wake-rows.ts` (the monitor/timer → tree-row projection), `presentation.ts` (the shared
   card-compaction/sanitization helpers behind the projection rules below), `usage.ts`
   (token/usage formatting, `ChildUsageLedger` / `toToolUsage` — sub-agent spend is
   attached as Pi `toolResult.usage` so the footer and pi-theme-1337's frame count it;
@@ -271,9 +289,12 @@ up to 16 names. Same idea, two layers, two caps — see docs/REFERENCE.md's exam
 `isolation: worktree` is fail-closed. It requires a clean Git checkout so the detached `HEAD` view
 cannot silently omit staged/unstaged/untracked supervisor work; a non-repository, dirty checkout,
 worktree creation failure, missing diff artifact, or an artifact over the return limit fails the leg —
-the base engine is never invoked against the real tree as a fallback. The diff returns to the
-supervisor before the temporary tree is removed, and every git call is asynchronous so the extension
-host keeps rendering, ticking timers, and serving broker sockets while a large checkout runs.
+the base engine is never invoked against the real tree as a fallback. The created worktree's initial
+commit is pinned before the worker starts. Export compares the final file state against that immutable
+commit, so worker commits, later unstaged changes and new files are included together. The diff is
+captured before the temporary tree is removed and then returned to the supervisor; commit history is
+not applied to the main checkout. Every git call is asynchronous so the extension host keeps rendering,
+ticking timers, and serving broker sockets while a large checkout runs.
 
 Transient retries inside one agent session belong to the host **Pi runtime**'s `retry.*` settings, not
 a persona contract — pi-persona neither parses retry notation nor schedules its own backoff. Both
@@ -314,6 +335,14 @@ Running engines retain their captured assignments. Missing credentials are class
 adapter boundary; only the SDK decides whether a main-model recovery is admissible. This separation
 avoids a global reset or automatic repinning that could silently change billing and panel diversity.
 
+The extension owns the derived candidate cache, keyed by session and base provider/model. Ordinary
+turns reuse it; explicit catalog refresh invalidates the initiating key even after partial provider
+failure. The settings UI supplies the refresh deadline and reporting, while the extension's refresh
+adapter captures the key before awaiting the host. Briefs and nudges share the same callable-`models`
+gate. Automatic model setup for tools, commands and mandated orchestration shares the checkpoint
+dialog queue; each run registers its stop handle before entering that queue. Aborting setup discards
+its unsaved choices and removes only prompt markers created by that attempt, so it can be retried.
+
 **Unified settings.** `/persona-settings` is independent of Pi's `/settings`: full-page TUI, native
 RPC dialogs, and a read-only `show` report. `core/settings.ts` is the public preference registry and
 validator; the UI and environment precedence consume it rather than maintaining duplicate field lists.
@@ -435,8 +464,9 @@ decides how precise each may be is a **prompt-cache** rule, not a taste one:
 - **Tail surfaces are free.** A tool result or a delivered message is written once and never re-sent
   as the cached prefix, so precision costs nothing there. An inbound peer delivery dates itself
   (`[rune] — reply · sent 20m ago`), and every settled leg reports its wall time on every
-  tracker-backed path — the done/failed/stopped report, the join, `intercom result`, and each
-  settled line of a peek digest.
+  tracker-backed path — the done/failed/stopped report, `intercom result`, and each
+  settled line of a peek digest; a running line ends its turns/tokens parenthesis with
+  `· running for <duration>` (not shown while queued).
 - **The system prompt is not.** It is re-composed and re-sent every turn and IS the cached prefix,
   so a minute-granular value there rewrites it every minute and throws away the provider's cache of
   everything before it. The **session anchor** therefore reads on a deliberately coarse ladder —
@@ -471,7 +501,7 @@ never simultaneously a telemetry event, a routed message, and a UI source of tru
   a source of truth. The `f9` agent tree and `peek` digest are ProgressViews.
 
 Steering is a supervisor-to-child control action, distinct from semantic Bus messages; requesting
-steering does not establish that an active blocking join has been interrupted. The peek digest is
+steering does not establish that a blocking headless delegate call has been interrupted. The peek digest is
 always a read-only ProgressView.
 
 External telemetry is not a fourth communication plane: it is a generic observer/export contract that
@@ -481,12 +511,17 @@ events and cannot route, reply, steer, or otherwise control agents.
 ## The comm plane in practice
 
 - **In-process bus** (`bus/inproc.ts`) — a handle-based mailbox: `send` (one-way), `ask` (blocks for a
-  reply), `reply`, `onMessage`. `contact_supervisor` (child→supervisor, gated by `coaching: on`) and
+  reply), `reply`, `onMessage`. `contact_supervisor` (child→supervisor, gated by `canUseBus` and,
+  for in-process children, `coaching: on`) and
   `contact_peer` (sibling→sibling) are the child-side tools bound onto it. Each unread inbox holds at
   most 200 messages; overflow evicts an old one-way note first, and an inbox full of live asks rejects
   new delivery rather than stranding a sender. Ask settlement (reply, timeout, abort, departure, or
   failed delivery) releases its timer/listener and unread entry; a previously retained question stays
   readable with `expectsReply: false`, so old questions never advertise an active reply id.
+  Tool outcomes distinguish `answered` from unavailable, timed-out, cancelled and failed requests;
+  delivery evidence is never approval. Headless questions remain nonblocking and unresolved, allowing
+  only independent already-authorized work or a blocked/partial handoff. Pre-aborted calls perform no
+  bus action, and replies racing cancellation are not reported as answers.
 - **Sibling peer comm** — a strategy opts a run in via `AgentRunSpec.peers` (gated by `canUseBus`). The
   child gets `contact_peer` (`list`/`send`, ONE-WAY so peers can never deadlock; per-engine-instance
   scoping; a 20-send budget and an 8,000-character body limit, enforced before consuming a send). The
@@ -509,6 +544,10 @@ events and cannot route, reply, steer, or otherwise control agents.
   spawn without a bus endpoint, so they never burn connect backoff against a dead socket), and the next
   build retries; `/doctor` surfaces its state on one line. A dropped client connection flips the
   child-side bridge to `⇄ offline` and fails a fresh ask fast rather than hanging.
+  A connected child exposes `contact_supervisor` when `canUseBus` is allowed; `contact_peer` also
+  requires the run's peer opt-in. Granted custom tool names join a nonempty plain allowlist so Pi's
+  host filter does not hide them. Explicit `tools: []` and exclusions remain restrictive. A denied
+  semantic bus does not remove supervisor runtime steering or an independently scoped result reader.
 
 ### Presentation is a projection, not another comm plane
 
@@ -524,36 +563,103 @@ for the supervisor and for explicit retrieval; the default TUI projection is del
   Oversized or evicted messages return an unavailable diagnostic — retention is not durable evidence
   storage;
 - collapsed delegate/intercom/council/flow cards show state, identity, a short sanitized preview, and
-  Pi's expand-key hint, each surfacing failure at the top in its own shape: the delegate card **sorts**
-  failed legs first, a failed council/flow card leads with the cause in its title, and an
-  `intercom wait` card leads with the `N settled — X done, Y failed` tally (per-leg causes sit in the
-  body, below the preview cut, so `wait`'s own success doesn't get a `failed` prefix);
+  Pi's expand-key hint, each surfacing failure at the top in its own shape: the delegate card
+  names each failed leg on its own line, and a failed council/flow card leads with the cause in its title;
 - async launch cards and targeted Intercom call headers use the worker's canonical alias/model,
   matching the tree rather than promoting its routing ID to display identity. Launch/control receipts
   persist identity snapshots for history rendering; aliases never become routing keys. Colliding
   aliases carry a secondary ID, and legacy receipts without a recoverable name retain their ID fallback.
   Accepted steering receipts retain the exact sent message: collapsed cards preview it, expansion
   shows all sanitized text and the diagnostic ID. A queued receipt does not prove the worker acted;
+- async failures append a `pi-persona-run-failure` entry in TUI mode, with alias, agent/model,
+  elapsed time and a concise cause. The entry stores the original diagnostic for expanded history
+  rendering; it is operator-only and adds no model context or wake. Other modes, or an append
+  failure, retain a bounded notification. The semantic completion follows its existing single-wake path;
 - follow-up cards (`pi-persona`, exocom) retain their complete semantic content but render a bounded
   preview until expanded; terminal escape/control sequences are removed from the visible projection;
-- the sticky agent and exocom widgets have fixed row budgets — F9/`/agents` and paginated
+- custom follow-ups and operator-only entries share `ui/session-cards.ts`: glyph-free generated
+  headings, explicit textual state, one width-aware layout and semantic theme backgrounds. Neutral
+  information/unknown state uses `customMessageBg`, verified completion `toolSuccessBg`, attention
+  (nudge/stall/stopped) `toolPendingBg`, and verified failure `toolErrorBg`. Only runtime-owned status
+  evidence selects chrome, never peer/child prose. Colors are resolved from the active theme at render
+  time (including pi-theme-1337); normal tools keep Pi's own shell rather than gaining a duplicate box.
+  Expanded prose reports use the native Markdown projection in `ui/report-body.ts` (including visible
+  trust blockquotes); receipts, live output, monitor/timer notices and raw diagnostics stay literal.
+  Source payloads and fences remain intact. The native Markdown component is retained per report and
+  invalidated for theme/layout changes, without a global transcript cache. Rendering never rewrites
+  stored or model-facing payloads, nor creates a wake;
+- literal control receipts and fallback errors share `ui/literal-tool-result.ts`: bounded collapsed
+  text, an expansion hint only when detail is hidden, and full sanitized expansion. Tool errors use
+  the host's `ToolRenderContext.isError`, not a presumed result field; semantic negative peer answers
+  remain successful retrievals. Retained `exocom_wait` answers are prose reports and render Markdown
+  when expanded. Native tool shells remain host-owned;
+- the sticky agent and exocom widgets have fixed physical-row budgets: the shared width-aware
+  `ui/compact-widget.ts` clips each already-budgeted row instead of letting native Text wrap it.
+  F9/`/agents` and paginated
   `exocom_list({ offset, limit })` are the explicit detail surfaces, so a wide fan-out cannot push the
   editor off screen or dump an entire peer registry into model context. Agent-tree deltas share one
   16 ms widget composition per terminal frame; identical lines/status are not republished, hierarchy
   rendering uses one adjacency index, and the F9 overlay rebuilds lazily when Pi paints rather than
   once per streamed token;
-- `/flow` and `/orchestrate` append durable, TUI-only expandable result entries rather than dumping a
-  large notification or a second copy into the model context;
+- `/flow` and `/orchestrate` append a durable, TUI-only expandable result card rather than a large
+  notification; the supervisor gets the same text (fenced, 12k-bounded) once, as a passive next-turn message;
+- an interactive `tasks` fan-out of two or more legs gets one container row, `delegate · N legs`
+  (`k/N settled`), that never counts as an in-flight agent and leaves with its last leg;
+- `X` is not a directed key: it acts on the whole stoppable set of leaf rows after a confirmation that
+  states how many agents it covers, and a changed set is re-confirmed. The set is every agent leaf (wake
+  rows excepted) plus any run root with a stop handle (council/flow/mandated runs), and `x` on such a
+  root stops the whole run.
+  `intercom stop` / `stop { to: "all" }` also cover tracker runs, `council` and `flow` included;
 - the F9 overlay's *directed* keys (`x` stop, `s` steer) act only on the agent the ▸ marker still
   shows; if that agent settles and is pruned mid-keystroke, the selection re-anchors visibly and the
   keypress is spent re-aiming instead of aborting an agent the user never chose. ↑↓, ⏎, and the scroll
   keys never refuse;
 - every agent-tree node carries `startedAt`/`lastAdvanceAt`; `LiveClock` (`src/ui/live-clock.ts`)
   repaints the sticky widget and the F9 overlay once a second while any node is running and stops
-  itself once nothing is. A running row shows elapsed time until it goes `STALL_FLAG_MS` (90s) quiet,
+  itself once nothing is. Running/completed usage shares `formatUsage`: `↑` input and `↓` output,
+  using copied existing cumulative usage snapshots, never context occupancy. A legacy progress source
+  providing only an aggregate shows a neutral compact count without `tok` or a fabricated direction. A running row shows elapsed time until it goes `STALL_FLAG_MS` (90s) quiet,
   then the same `⚠ stalled <duration>` badge the async peek watchdog uses. `x` marks the target
   `stopping…` at once and is offered only when a live stop handle exists; a refusal (no handle,
-  already settled) surfaces as a one-line notice instead of silently no-op'ing.
+  already settled) surfaces as a one-line notice instead of silently no-op'ing;
+- armed timers and active monitors are **wake rows** in the same tree (`src/ui/wake-rows.ts`, ids
+  `monitor:<id>` / `timer:<id>`): rows, not agents. The countdown replaces the stall clock: a timer
+  shows `fires in <d>` only, a monitor keeps its elapsed time (`<elapsed> · deadline in <d>`), so
+  neither carries the `⚠ stalled` badge or `waiting for supervisor`. `x` cancels
+  one through the same stop registry as an agent (the `monitor cancel` / `timer cancel` effect); `s` steer
+  is never offered. They are excluded from the `X` stop-all count, confirmation and bulk stop, from the
+  `N agents` in-flight status, and from telemetry (`agent.*` events are agents only). They settle and
+  leave like an async row: the final ✓/✗/■ goes to the tree change stream (telemetry excluded), not to
+  the screen, because the update and the removal are synchronous and the widget frame is coalesced. They
+  live only in the arming session, never restored. Raw monitor stdout/stderr has a separate passive
+  observer: raw chunks feed bounded sanitized tails immediately, but full row/preview projection is
+  coalesced per dirty monitor into the existing 16 ms widget frame, before its tree snapshot. Terminal
+  events and cancellation publish the pending final tail synchronously; teardown clears pending state.
+  This updates the widget and F9 without semantic events, model wakes, event-budget consumption or
+  stall-clock credit. The same observer feeds a bounded session-native log
+  archive (`src/monitor/archive.ts`): one plain custom entry per terminal/cancelled run, no sidecars or
+  per-chunk writes. `monitor result` retrieves retained captures across reload/resume from the whole
+  session tree, including sibling conversation branches: this archive is session-wide, deliberately
+  not a projection of the active branch. Branch navigation changes neither visibility nor the shared
+  lifetime budget. Restored logs never restore processes. Activation-unique monitor ids avoid historical result collisions. A finite
+  lifetime serialized-byte/count budget includes all previous entries of the archive type, even
+  unreadable versions. Session-file deletion owns log deletion; ordinary shutdown saves diagnostics,
+  not deletes them. Operator-only expandable log entries do not create model context or extra wakes.
+
+**Terminal result archive** (`src/results/`, `src/extension/results.ts`) applies the same
+ownership model to settled agent work: every terminal delegate/council/flow outcome (and each final
+SDK leg result, after any model recovery) is projected — once, idempotently by immutable origin —
+into a versioned session entry with an opaque `result:<UUID>` reference, independent from runtime
+run ids. Budgets: 128 entries, 8 MiB cumulative serialized payload per owning session file, 512 KiB
+per record; bodies cap at 262,144 UTF-16 units with honest truncation metadata. Unknown, malformed
+and duplicate history still consumes quota; unaccountable history disables new persistence instead
+of resetting it. A fork/copy is a new owning file charged only for the entries it actually carries.
+`storage: "session-entry"` means the host accepted the entry — never an fsync guarantee; memory-only
+retention is labelled as such. Retrieval is read-only: `intercom results` lists, `intercom result
+{ ref, offset, limit }` pages (8,000 default / 16,000 max units, surrogate-safe), with no respawn,
+rebilling, collection or extra wake; reading a page never returns the whole run hidden in metadata.
+A saved result is not a live worker: the restore notice says runtime handles are gone while retained
+reports remain readable.
 
 This is a UI invariant only: truncating a collapsed card must never be confused with truncating the
 underlying result or changing a strategy's contract.
@@ -568,17 +674,22 @@ and message peer-to-peer, with no parent/child relationship. (intercom = interna
 external comm.)
 
 Exocom supplies fenced one-way postcards and presence; chat `message` never mutates shared work
-state. Separately, a workspace work ledger (`ledger.ts`, tools in `tools/exocom-work.ts`) records
-claims/asks/answers/progress/releases. `exocom_ask` canonicalizes its target through
-`plane.resolvePeer` (raw session ids on the ledger, never the display name); registry display name is
-keyed by `from_session`, never the envelope's self-reported `from_name`. A pending ask constrains the
-turn (`gate.ts`: answer/decline plus read-only tools) behind a bounded `pendingAskPrompt`.
-`exocom_wait` is non-blocking. Clean shutdown releases this session's claims/asks; if that best-effort
-write fails, the vanished owner is pruned on the next ledger transaction (live registry sessions are
-the lease), and `expireWaiters` wakes any waiter left behind instead of leaving `exocom_wait` armed
-forever. This gate is cooperative coordination for participating local Pi processes — not filesystem
-authorization, not isolation from another same-user process, and not a delegate/council or task/run
-replacement.
+state. `src/exocom/ledger.ts` stores claims, questions, answers and progress; `src/exocom/collaboration.ts`
+adds voluntary tasks, optional offers and explicit evidence excerpts. Tool adapters live in
+`src/tools/exocom.ts`, `src/tools/exocom-collaboration.ts`, and `src/tools/exocom-profile.ts`.
+`exocom_ask` resolves its target through the live registry to a raw session id, never a display name.
+Attribution is resolved by `from_session`, never the envelope's self-reported `from_name`.
+
+A pending ask gates the participant to `exocom_answer`/`exocom_decline`, `exocom_name` identity
+metadata, `exocom_status`, explicit collaboration reads (`exocom_task` list/get, `exocom_publish`
+read, `exocom_profile` get), and read-only filesystem tools. Profile `set`/`clear` and all other
+mutations remain unavailable until the ask is settled. Naming does not settle an ask. The bounded
+`pendingAskPrompt` explains the outstanding obligation. `exocom_wait` is non-blocking. Clean shutdown
+releases this session's claims/asks; if that best-effort write fails, the vanished owner is pruned on
+the next ledger transaction (live registry sessions are the lease), and `expireWaiters` wakes any
+waiter left behind instead of leaving `exocom_wait` armed forever. This gate is cooperative
+coordination for participating local Pi processes — not filesystem authorization, not isolation from
+another same-user process, and not a delegate/council or task/run replacement.
 
 - **Opt-in, OFF by default.** `PI_PERSONA_EXOCOM=1` or bare `--exocom` joins the current workspace;
   `--exocom=Ab0T` joins an existing scope by its exact, case-sensitive four-character Base62 alias
@@ -605,18 +716,31 @@ replacement.
   standing brief, and `/exocom` label a peer as same-workspace or external without exposing its
   absolute `cwd`. External peers are full Pi instances that can inspect files in their own workspace;
   paths are never implicitly shared.
-- **Postcards plus a durable, non-blocking join.** `exocom_send` returns a `msg_id` immediately; a
-  reply is another `exocom_send` with `in_reply_to` set. `target: "*"` broadcasts postcards
-  best-effort (one unreachable peer doesn't fail the rest). Work coordination is separate:
-  `exocom_ask` commits an obligation to the ledger, `answer`/`decline` settles it, and `exocom_wait`
-  arms a bounded idle wake rather than blocking. The signed frame is a wake signal; the ledger remains
-  the source of truth if delivery is deferred.
+- **Postcards, asks and offers have different obligations.** `exocom_send` returns a `msg_id`
+  immediately; a reply is another `exocom_send` with `in_reply_to` set. `target: "*"` broadcasts
+  postcards best-effort. `exocom_ask` commits a targeted question that must be answered or declined;
+  `exocom_wait` arms a bounded idle wake rather than blocking. `exocom_offer` is an optional,
+  expiring invitation to consider an open task, targeted to one peer or the pool; it creates no ask,
+  no answer obligation and no work authorization. Its default lifetime is one hour, capped at 24 hours.
+  Signed immediate-wake frames are signals; the ledger remains authoritative when delivery is deferred.
+- **Task generations and atomic pickup.** `exocom_task create` records a voluntary objective and
+  declared write set; creation neither launches work nor claims paths. The task's immutable
+  `task_id` is its creation frame's `msg_id`; later take/progress/finish, offer and publish actions
+  carry both `work_key` and `task_id`, so reusing a key cannot attach a delayed action to a newer
+  task. A write-set task's pickup and overlapping write claim commit together under the ledger lock;
+  competing overlapping pickups are rejected. Read-only tasks can be taken by a peer in another
+  workspace scope. A task whose owning registry lease disappears becomes stale and cannot be taken
+  over automatically. `exocom_task list` is paginated; `get` returns the complete bounded task detail,
+  including the exact write set. `exocom_publish` attaches an explicitly authored bounded excerpt to
+  one task generation; discovery pages titles and message ids, and the full excerpt is read by id.
+  These excerpts do not grant access to a peer's terminal-result archive.
 - **Cross-workspace writes are advisory-only in v1.** A repository-relative claim path has meaning
   only in the workspace that owns the selected scope, so a member whose home workspace differs from
-  the scope cannot `exocom_claim` (the tool and the signed-frame receiver both reject a foreign
-  claim) — it can still send, inspect its own files, ask, answer/decline, wait, and release its own
-  asks. Multi-repository write coordination would need a versioned resource namespace; paths from
-  unrelated repositories are never compared as if they named the same files.
+  the scope cannot `exocom_claim` or create/pick up a write-set task (the tool and signed-frame
+  transaction both enforce the scope). It can still read shared tasks/evidence, take read-only tasks,
+  send postcards, ask, answer/decline, and release its own asks. Multi-repository write coordination
+  would need a versioned resource namespace; paths from unrelated repositories are never compared as
+  if they named the same files.
 - **Reply routing is session-stable.** `exocom_list` shows human display names (`name`/`name#2`);
   sends and inbound reply hints use `name@<96-bit session hash>`, so a retained qualified target
   stays valid after a rename. Ambiguous suffix matches fail closed rather than guess. The
@@ -655,15 +779,23 @@ replacement.
   double-trigger a turn. An exchange's LENGTH is instead bounded prompt-side: the per-turn peer brief
   (`core/brief.ts`) carries a relevance bound — send only what changes what someone does — deliberately
   not a round count, since a counter can't see whether a round still serves the work.
-- **Tools are lazy and fail closed.** `exocom_list({ offset?, limit? })` exposes bounded, paginated
-  presence; `exocom_send({ target, message, in_reply_to? })` sends one-way (a session-qualified-looking
-  target resolves only as one, never falling back to a display name, since names are self-chosen);
-  `exocom_name({ name })` rebrands the display call-sign without moving any state. The ledger tools —
-  `exocom_claim`, `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait`, `exocom_progress`,
-  `exocom_release` — are capability-gated with the postcard tools; the live accessor, capability gate,
-  and active-tool set all deny them once the plane stops, since Pi has no dynamic tool-unregister API.
-  Admission requires at least one obligation closer, because every published peer may receive a
-  durable ask and must retain a way to settle it.
+- **Fifteen tools are lazy and fail closed.** `EXOCOM_TOOL_NAMES` lists `exocom_list`, `exocom_send`,
+  `exocom_name`, `exocom_claim`, `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait`,
+  `exocom_release`, `exocom_progress`, `exocom_status`, `exocom_task`, `exocom_offer`,
+  `exocom_publish`, and `exocom_profile`. Each tool rechecks effective persona capabilities at call
+  time; the live accessor and active-tool set also deny calls once the plane stops, since Pi has no
+  dynamic tool-unregister API. A joined foreign-scope peer has no `exocom_claim`. Admission requires
+  `canUseBus` and at least one callable ask closer, because every published peer may receive a durable
+  ask and must retain a way to settle it.
+- **Collaboration and profile retention are bounded.** The ledger retains at most 64 tasks, 64 offers,
+  and 64 evidence excerpts with a 128 KiB aggregate collaboration-state budget. Task descriptions cap
+  at 2,048 characters; write sets at 64 paths of 256 characters each; progress/finish notes at 4,096.
+  Evidence titles cap at 160 characters and excerpts at 4,096 characters / 8,192 UTF-8 bytes. Finished
+  or stale tasks remain for up to one hour; expired offers remain for up to one hour after expiry, and
+  evidence for up to one hour after publication. Active tasks remain while their owner lease is live.
+  `exocom_profile` contains up to eight self-described capability labels (48 characters each) and
+  optional `available`, `busy` or `away` status. Missing status is unknown. Profiles exist only for
+  their live Exocom session and never prove skills, permission or availability.
 - **Inbound delivery is bounded without loss.** Each message is injected under the same byte cap
   whether plain text or an artifact descriptor. Bursts stay FIFO-queued; each rate-limited wake drains
   as many whole messages as fit, leaving the rest queued. A presentation cap on the collapsed card
@@ -679,38 +811,72 @@ a local process able to modify that directory is already inside the trust bounda
 
 ## Supervision & the waiting model
 
-- **sync** — the supervisor actively blocks on the delegate/strategy call (results still stream); no
-  idle/peek/steer.
-- **async** — interactive delegation is background-first; headless execution remains synchronous
-  by default. The prompt/runtime guidance is to continue independent work and, when only background
-  children remain, end the turn for automatic completion follow-ups rather than monitor or join the
-  whole batch. `intercom wait` collects a snapshot without blocking by default in interactive/RPC
-  sessions; settled results are reported and running children continue. Use `sync: true` for an
-  intentional bounded join. Headless sessions preserve the blocking default; `sync: false` requests a
-  snapshot. A snapshot does not wait, start timers/input hooks, or cancel children. Queued steering
-  does not release an explicitly active join. Input-triggered join interruption is
-  deliberately not implemented: a real Pi 1.0 SDK characterization shows steering can remain dormant
-  if delayed input hooks outlast the active run; no supported post-admission ordering guarantee
-  has been established. The supervisor otherwise returns control and
-  goes idle until a wake; the **peek watchdog** fires while async children run but stays SILENT unless
-  there is something to act on — a healthy background run should not interrupt. Every newly detected stall
-  episode (`STALL_FLAG_MS`, 90s) appends a durable, expandable operator-only warning entry, including while
-  the supervisor is busy. Interactive stalls never wake the model. In headless sessions, the first stall
-  episode may produce one focused patience-first model wake per run lifetime (ask the leg, don't probe its
-  environment); later stall episodes for that run do not re-arm the model-wake budget. Unread messages to the
-  supervisor retain their existing wake path. The **slow routine status card** (`PI_PERSONA_CHECKIN_MS`,
+There is no `sync`/`async` switch on `delegate` and no `intercom wait`; the mode follows the session.
+
+- **Headless (`ctx.hasUI !== true`, e.g. `pi -p`)** — the supervisor blocks on the delegate, council or
+  flow call and gets results inline (returned once, unclipped; progress is only a `k/N done` counter), because nothing drains a follow-up after the
+  single turn exits. A runtime constraint, not a model-facing choice. The legs are still tracked, but
+  the status monitor stays off: the model is parked in the call and nobody reads a card.
+- **Interactive (TUI and RPC)** — delegation is ALWAYS background: the call returns run ids at once
+  and each result returns as an idle-gated completion follow-up (`intercom result { to: runId }`
+  retrieves a settled run; `peek`/`steer`/`stop` stay available, which a blocking call could never
+  offer). With only background children left, the supervisor ends its turn and goes idle until a wake;
+  it never sleeps, polls, or arms a `timer` to wait for a child or a monitor. The **peek watchdog**
+  fires while async children run but stays SILENT unless there is something to act on. A newly
+  detected stall (`STALL_FLAG_MS`, 90s) appends a durable, expandable operator-only card, even while
+  the supervisor is busy, and never wakes the model; unread messages to the supervisor keep their
+  wake path. The **slow routine status card** (`PI_PERSONA_CHECKIN_MS`,
   ~5 min, `0` disables) is a durable, expandable operator-only session entry with the compact ProgressView
   digest — never full transcripts — and does not start a model turn. Live supervisor asks
   are derived from the exact engine handle's optional `isWaitingForSupervisor` predicate: tree/F9/peek
   show waiting, and the watchdog suppresses false stalls until the ask settles. Parent clocks advance
   with child engine events (liveness, not proof of useful work); parents are waiting only when every
-  live descendant branch is waiting.
-  Stall alerts and live messages let an idle supervisor steer/stop a wedged child even with NO completion
-  fired; the enforcing backstop is the engines' hard wall-clock cap (above). The full digest is also on demand
-  via `/peek`.
+  live descendant branch is waiting. The peek watchdog's clock is stricter (`madeHeadway` in
+  `engine/async.ts`): a run advances only when assistant output, tokens or turns grew or a tool call
+  completed, and raw tool-output chunks earn nothing, so a leg whose tool streams forever (`npm run dev`,
+  `tail -f`) raises the operator-only stall card. A false advisory on a legitimately noisy long tool is
+  accepted; nothing is killed and the model is not woken. A council or flow run is credited per leg. The
+  tree/F9 clocks stay event-based.
+  The operator (or a manual `/peek`) can steer/stop a silent child. The supervisor's net for one is the
+  engine idle window (`RUN_LIMITS.timeoutMs`, 180s; startup deadline 300s), which kills it and returns a
+  failed completion follow-up whose text says to raise the leg's `timeoutMs`; the opt-in hard wall-clock cap (`PI_PERSONA_AGENT_MAX_MS`, off by
+  default) catches a busy non-converging leg.
+  Two call-time guards (under `config.nudge`, `PI_PERSONA_NUDGE=off` disables both) stop the in-turn
+  waits that would block those wakes: a repeated `intercom peek`/`result` whose answer has not changed
+  (per scope; `steer`/`stop` reset it) is refused, then asks Pi to end the turn (`terminate` is a hint
+  Pi honours when the peek is the batch's only call); a leading long `sleep`/`Start-Sleep` (>= 20s) is
+  stopped while background children run or are being launched (interactive only; a sleep prepared
+  before a same-batch `delegate` is an accepted false negative). A `delegate` fan-out (`tasks`) is
+  held and delivered as ONE completion follow-up when its last member settles, with every failed leg
+  named and clipped on its own line; single legs and separate calls are unchanged. Held reports are
+  dropped at session shutdown or reload, like the running legs, and the `PI_PERSONA_ASYNC_RETAIN`
+  default (64, the `tasks` cap) covers one whole call so early finishers stay fetchable. In headless `pi -p` the
+  `timer`/`monitor` arm text says the process exits when the turn settles, so such a wake lands only
+  if it fires before then.
+  **`council` and `flow` are the same kind of run** (`tools/background-run.ts`, `createBackgroundRuns`).
+  Interactive, each is ONE tracker run rooted at `async:<runId>`: a receipt now, ONE completion follow-up
+  (`intercom result { to: runId }` for the full payload), and the same `peek`/`stop`/`stop all`/f9 reach
+  as a delegate leg. Headless, the same run is launched and joined inside the tool call. Esc no longer aborts
+  one; stop it by key. Ownership of the limits: a run holds ONE slot of the delegate `maxConcurrency` launch
+  pool for its whole life (`queued` until granted; a flow keeps it while parked at a checkpoint); the strategy
+  SDK's per-run semaphore gates the legs INSIDE it, so members never compete with delegate legs for pool
+  slots; token budgets, the child limit, the delegation ledger and the fork-bomb guard stay in the SDK and
+  engine. A flow parked at a checkpoint is blocked on the OPERATOR: the run carries `awaiting`, peek reads
+  `waiting for operator at checkpoint <id>`, the stall watchdog skips it and nothing wakes the model; a
+  rejected checkpoint settles the run `stopped` and the plan reaches the model as its partial output. A
+  persona's `council:` defaults resolve unchanged when the call omits strategy, roster and params. The
+  mandated `orchestration:` path stays PRE-turn and inline (its result is the supervisor's first answer),
+  as do the `/orchestrate` and `/flow` slash commands; those runs register their own abort under their root
+  row, so shutdown ends the whole run. Operator-run results also reach the supervisor's next turn as a
+  passive, fenced, 12k-bounded message.
   Progress tokens are labelled **cumulative input/output**, not context occupancy; cache-read/write
   accounting is separate. Do not infer a full context window from that counter. File age or line-count
   changes alone likewise do not establish a stall, a passing test or completed work.
+  **Restore honesty:** `session_shutdown` records lost run ids, timers, monitors and the run-id counter
+  in a `pi-persona:runs` session entry (`core/session-runs.ts`). The next `session_start` (reload,
+  in-session resume, `pi -c`; not fork or `/new`) tells the supervisor once through a passive `nextTurn`
+  message, acknowledges it, and continues run ids so they never restart at `run-1` within a session.
+  Only ids matching a strict shape and capped counts are ever read back.
   Async failures are ALWAYS reported; the runtime `DelegationLedger` vetoes a blind retry loop (an
   identical agent+model+task delegation that failed twice is stopped before it spawns). Coaching is
   gated by `coaching: on` AND `canUseBus`.
@@ -718,26 +884,42 @@ a local process able to modify that directory is already inside the trust bounda
 **Runtime reinforcement of the hand-off default** comes as a standing part and a reactive part, because
 a persona directive lives at the TOP of the prompt and its pull decays as recent tool output balloons:
 
-- The **delegation brief** (`core/brief.ts`) is the STANDING half: live roster (agents + teams + flows)
-  and the hand-off default, appended to the system-prompt TAIL every turn, where recency wins the
+- The **delegation brief** (`core/brief.ts`) is the STANDING half: live roster (agents + teams + flows, with descriptions;
+  gated flows are tagged in headless sessions) and the hand-off default (the supervisor's role: it holds the
+  objective, the plan and the judgement, normally handing bounded independent work to supervised legs;
+  quick, trivial or tightly coupled work can stay inline when hand-off overhead would outweigh the benefit; one decision-class →
+  method line that a test checks against the strategy registry; model-sizing guidance and a cached provider
+  candidate list), appended to the system-prompt TAIL every turn, where recency wins the
   tug-of-war a top-of-prompt line loses. It regenerates from the live registry (so it can't desync) and
-  filters to the active persona's `delegate` allowlist. It never dictates how MANY sub-agents or which
-  shape — that is each persona's own method.
+  filters to the active persona's `delegate` allowlist. It never dictates how MANY sub-agents; beyond the one class line,
+  the shape is each persona's own method.
+  The model snapshot is acquired once per session/base-model reference, refreshed on a base-model change
+  or explicit `models` call, and reused across turns. Recommendations first stay near the current
+  model's provider, textual name root and numbered major generation, then order distinct variants by
+  relative cost band and numeric version. They do not fill spare slots with older or unrelated models.
+  This affects discovery only; exact assignment and search retain the full eligible catalog.
+  Relative cost hints use host prices against an uncapped recent-provider reference, never a
+  model-name-to-tier table, and leave missing or zero-price metadata unknown. The LLM chooses task fit.
 - The **nudges** (`core/nudge.ts`, on by default) are the REACTIVE half, landing in RECENT context on
   the event that warrants them:
   - **DelegationNudge** — a `tool_result` hook watches the supervisor's own tool stream and, when a
-    delegating persona grinds heavy work by hand (output burn since the last `delegate`/`council`
-    crosses a threshold), appends a compact labelled checkpoint (`Trigger` / `Scope` / `Action`) to
+    delegating persona grinds heavy work by hand (output burn since the last `delegate`/`council`/`flow`
+    crosses a threshold: 3 substantive calls and ~1k tokens), appends a compact labelled checkpoint
+    (`Trigger` / `Scope` / `Action`, with four delegate targets named in the action, those the persona's own prompt mentions first, and a
+    `Model candidates` line for the session provider) to
     that command's result for the model and mirrors it into a durable, expandable
     `pi-persona-nudge` custom entry for the operator. The entry is TUI-only (no duplicate model
     context or turn) and guarantees visibility even when a built-in/custom tool renderer suppresses
     result `content`. A successful hand-off resets the streak; a failed one keeps it and returns the
     same visible re-dispatch checkpoint.
+  - `flow` is a hand-off beside `delegate`/`council`: a successful flow resets the by-hand streak and a
+    failed one gets no re-dispatch checkpoint (its failure text is self-describing).
   - **PersistenceNudge** — the counterweight to premature surrender: a delegated leg's report carrying
-    `[BLOCKED]`/`FLAG: UNKNOWN` gets a "don't bank it yet" reminder. All three delivery paths carry it
-    (sync `delegate`/`council`, background completion, `intercom wait`), but coverage isn't identical:
+    `[BLOCKED]`/`FLAG: UNKNOWN` gets a "don't bank it yet" reminder. Three delivery paths carry it
+    (the inline `delegate`/`council`/`flow` result — headless only — background
+    completion, and an explicit `intercom result` of a done run), but coverage isn't identical:
     the sync path scans the WHOLE tool result including failed legs, while `renderCompletion` scans
-    only `status === "done"` runs by design — a failed background/`wait` leg already gets a failure
+    only `status === "done"` runs by design — a failed background leg already gets a failure
     block, so a `[BLOCKED]` marker there doesn't also get the persistence note. Same marker, same leg,
     different counterweight depending on how it was collected.
     Nested calls through codemode's `ctx.executeTool` leave their programmatic result untouched.
@@ -745,8 +927,9 @@ a persona directive lives at the TOP of the prompt and its pull decays as recent
     used to infer nesting. A bounded set of parent call ids carries report provenance through wrappers
     only while their output relays a surrender marker; the outer model-visible result alone gets the
     note/card. Suppressed reports produce neither, and turn/session settlement clears abandoned relay state.
-  - **The off switch covers every path.** `PI_PERSONA_NUDGE=off` silences DelegationNudge entirely and
-    PersistenceNudge on every collection path (sync result, background notifier, `intercom wait`).
+  - **The off switch covers every path.** `PI_PERSONA_NUDGE=off` silences DelegationNudge entirely,
+    PersistenceNudge on all three delivery paths (inline result, background completion, `intercom result`),
+    and both call-time wake guards (`PollGuard`, the long-sleep block).
 
 ## Discovery & seeding
 
@@ -763,6 +946,11 @@ a persona directive lives at the TOP of the prompt and its pull decays as recent
   pristine prior copy and preserves edited, linked, or unknown files. A migration can declare a bundled
   agent dependency; that missing file is installed first with no-clobber atomic creation, or the parent
   remains on its old bytes. Upgrades, dependency installs, and warnings are exposed in `/doctor`.
+  The legacy digest table (`LEGACY_SEEDED_DEFAULTS`) holds the LF-checkout bytes of every shipped
+  elite/swarm/MAGI-core version from v1.11.0, plus the v1.17.1 copies of every bundled persona. Release prep must add the
+  previous tag's digest for each changed persona/agent; the guard test in `seed.test.ts` prints the
+  row (and skips in CI's depth-1 checkout). With zero personas installed, F8 and `/doctor` point to
+  `/persona seed`, like `/persona list`.
   Contracts/presets/teams keep a builtin layer (they aren't personas).
 
 ## Cross-OS constructs