@aeondave/pi-persona 1.17.1 → 1.17.4

package/docs/REFERENCE.md

@@ -34,28 +34,58 @@ hard-fail.
 
 | Surface | Does |
 |---|---|
-| `delegate` tool | spawn one or more sub-agents; interactive calls are background-first, while `sync: true` blocks the turn |
-| `council` tool | select any installed strategy over a named roster or temporary inline `members`; voting strategies preserve tally and dissent. Use when the topology adds value, not for routine work |
-| `intercom` tool | observe and control internal runs with `peek`, `result`, `wait`, `steer`, and `stop`; `list`, `inbox`, `message`, `reply`, and `send` drive the coaching bus. `wait` snapshots without blocking by default with UI; `sync: true` opts into a bounded blocking join (headless defaults to blocking; use `sync: false` for a snapshot); queued steering does not preempt an explicit join |
-| `timer` tool | read the fresh clock with `now`, or schedule an idle wake with `arm`, `cancel`, and `list`; alarms are one-shot and in-memory per session |
-| `monitor` tool | run a bounded job (`mode: exit`) or event-producing program (`mode: output`) and wake the supervisor; see [`MONITORS.md`](./MONITORS.md) |
-| `flow` tool and `/flow` | run a journaled DAG of strategies; `gate: true` creates an approval checkpoint |
-| `models` tool | list or search authenticated model ids in `provider/id` form; the session provider is marked |
+| `delegate` tool | spawn one or more sub-agents; interactive sessions always run it in the background (results return as completion follow-ups); headless `pi -p` always blocks and returns results inline. There is no `sync`/`async` parameter. A leg whose tool is silent longer than the idle window (180 s) fails with a message telling you to raise that leg's `timeoutMs`. A `tasks` fan-out's receipt pairs each run id with its call-sign, and one wake covers the whole batch. An optional `thinking` picks that leg's effort level (off…max); omission keeps the agent's own setting and the configured/inherited child default, and results distinguish requested from observed effort |
+| `council` tool | select any installed strategy over a named roster or temporary inline `members`; voting strategies preserve tally and dissent. Interactive sessions run a council in the background, like `delegate`: a receipt with a run id now, ONE completion follow-up with the ruling (`intercom result { to: runId }` for the full payload); headless `pi -p` returns it inline. Use it when the method adds value (vote, arbiter's pick, critique loop, per-item sweep, rival builds), not for plain independent parallel work, which is `delegate`. The strategy list in the tool description is generated from the registry (`when`, positional `roster`, `*` for a required param); a call missing a required param (`judge` and `compete` need `params.judge`) fails at once with `council failed: "<strategy>" requires params.<key> — …` and launches nothing, while an unknown strategy or roster is reported by the run itself, in the completion follow-up. A persona's declared `council:` still resolves when strategy, roster and params are omitted. Per-strategy behaviour (section labels, MAGI reflection fallbacks) is in [`STRATEGIES.md`](./STRATEGIES.md) |
+| `intercom` tool | observe and control internal runs with `peek`, `result`, `steer`, and `stop`; `list`, `inbox`, `message`, `reply`, and `send` drive the coaching bus. There is no `wait`: a finished child wakes the supervisor through the completion follow-up |
+| `timer` tool | read the fresh clock with `now`, or schedule an idle wake with `arm`, `cancel`, and `list`; alarms are one-shot and in-memory per session; an armed alarm shows as a row in the agent widget and F9 until it fires or is cancelled |
+| `monitor` tool | run a bounded job (`mode: exit`) or event-producing program (`mode: output`) and wake the supervisor; an active monitor shows as a row in the agent widget and F9 until it ends or is cancelled; see [`MONITORS.md`](./MONITORS.md) |
+| `flow` tool and `/flow` | run a journaled DAG of strategies, resumable only for the same flow, task and project; `gate: true` creates an approval checkpoint, shown with the gated output and what runs next (Reject is the default). The `flow` tool runs in the background interactively (receipt, then ONE follow-up when it ends; a checkpoint waits for the operator, peek reads `waiting for operator at checkpoint <id>`, and no wake happens there) and inline headless, where every checkpoint is rejected. A rejected checkpoint is a stop (`flow stopped · checkpoint <id>`, the gated plan is kept), not a failure. `/flow` and `/orchestrate` stay inline and operator-driven, and their results also reach the supervisor's next turn. `/flow` alone lists flows with descriptions; the supervisor brief lists them too, tagging gated flows as needing a human in headless sessions |
+| `models` tool | current-first model shortlist with relative cost bands; a query searches the full eligible catalog in `provider/id` form |
 | persona `mode:` | choose `solo`, `parallel`, `pipeline`, `strategy:<name>`, or `flow:<name>` |
 | persona `coaching:` | give children `contact_supervisor` for progress and blocking decisions |
 | persona `delegation:` | require briefs, set an output contract, schedule disjoint writes, and order fresh verification |
 | `isolation: worktree` | run in a clean throwaway Git worktree and return an exported diff; non-Git, dirty, or oversized cases fail closed |
+| agent `writeSet:` | repository-relative paths the agent alone writes by design (`research` declares `[.research/]`); a write-capable `delegate` leg that gives no `writeSet` of its own inherits it, so a persona that requires disjoint writes sees a declared owner instead of an unknown writer. Read-only legs do not inherit it. A directory owns its subtree; absolute and `../` paths are dropped. Declarative, not a sandbox |
 | `council: { preset }` | expand a reusable `presets/<name>.preset.json`; authored fields override the preset |
 | `contracts/*.json` | define a hot-editable structured return requested through `outputContract` and pinned per run |
 
+`models` without a query shows up to 40 entries total, including the current model when available,
+with the current model first. Recommendations stay within its provider, textual name root and
+numbered major generation, retaining the newest representative of each distinct variant. Remaining
+candidates are ordered `cost:low` → `medium` → `high` → `unknown`, then by numeric version within
+each band. For example, a `gpt-6-astra` supervisor sees available `gpt-6-luna` and `gpt-6.1-sol`
+neighbors before considering older models. The rule reads catalog IDs, without a model-name table;
+gateway vendor/region namespaces remain distinct from the model's family and generation.
+If the current name has no numeric version, only provider and textual root constrain the list.
+The list is not filled with older or unrelated models just to reach the cap; explicit searches and
+model assignments retain the full eligible catalog. With no current model, discovery falls back to
+a general shortlist sharing each provider's cap across name roots. Names are proximity hints,
+not release-date metadata or proof of task fit. `★` identifies the session
+provider; authentication alone does not prove that an account supports every model in its catalog.
+
+Model details expose host metadata for context and reasoning support. `cost:low`, `cost:medium` and
+`cost:high` are relative advertised API-cost bands among recent candidates of the same provider,
+using equal input/output token quantities. They are not quality, throughput or reasoning-effort
+ratings, and do not describe subscription billing. Missing/zero prices or an insufficient comparison
+set yield `cost:unknown`. The supervisor chooses task fit using these hints and the task's difficulty;
+thinking effort remains the separate delegated-thinking preference (inherited by default).
+
+The supervisor brief reuses a cached current-provider candidate list. Discovery runs on first use,
+when the base model changes (provider or model id), or on an explicit `models` query; ordinary turns
+do not rescan. Switching to another provider therefore replaces the cached candidates, including
+its lighter variants when present. The current provider is a default, not a user restriction: an
+explicit worker-model request may select another configured provider. The LLM retains the choice.
+
 The delegate tool's optional `name` is carried into `AgentRunSpec.name` and reaches both engine
-backends, keeping a caller-provided run label available in the live tree and runtime result. Every
-settled async run also emits an immediate UI banner with that name and its terminal outcome. The
-model-facing report remains independently idle-gated; a UI notification failure cannot discard it.
-An explicit `delegate` `async` flag overrides both `sync` and the session default: `async: true`
-forces background execution; `async: false` forces synchronous execution.
+backends, keeping a caller-provided run label available in the live tree and runtime result. A
+successful or stopped run announces ONCE: the idle-gated completion follow-up is the single
+settlement surface (the agent-tree row already settles immediately). A failure keeps an immediate
+operator surface — in the TUI a durable expandable card with the agent, model, elapsed time and a
+concise cause (expansion retains the full technical diagnostic); other modes use a concise
+sanitized notification. These operator-only cards do not inject context or start a second turn.
+The model-facing report remains independently idle-gated; a UI notification failure cannot discard it.
 
-### Pi 1.0 codemode
+### Native codemode
 
 Pi's native `codemode` can call callable pi-persona tools through the normal nested-tool pipeline.
 Argument validation and persona permission gates still apply to every inner call; scripts do not
@@ -66,13 +96,13 @@ model, not as a wrapper that prints every result in full. `Promise.allSettled()`
 siblings when a call rejects; a fulfilled `bash` call still requires checking `exit_code`.
 Only printed/returned script output reaches the model. Nested results therefore do not contribute
 raw bytes or invisible reminders to pi-persona's context-burn nudges; an actual successful nested
-`delegate`/`council` still resets the hand-off streak.
+`delegate`/`council`/`flow` still resets the hand-off streak.
 
 Pi identifies calls made through codemode's `ctx.executeTool` with `parentToolCallId`. If a nested
 delegation report is relayed with `[BLOCKED]` or `FLAG: UNKNOWN`, only the outer model-visible result
 gets the persistence checkpoint and its expandable card. Discarding the report creates no reminder
 and never alters the programmatic inner result. See [the nudge contract](./ARCHITECTURE.md#supervision--the-waiting-model)
-for the differences between synchronous and background reports.
+for the differences between inline (headless) and background reports.
 
 The outer code/result card belongs to Pi, not pi-persona's delegate renderer. Keep bulky details
 expandable (`Ctrl+O` by default; `/hotkeys` shows active bindings). `Ctrl+T` toggles thinking blocks
@@ -94,20 +124,25 @@ a live pending ask on the exact child handle, never inferred from its last activ
 
 | Surface | Needs | What you get |
 |---|---|---|
-| **Observe and control** | any persona | `peek` inspects async sub-agents; `wait` is nonblocking by default with UI (`sync: true` joins; headless defaults to joining, with `sync: false` for snapshots); `steer` sends a soft correction; `stop` requests cancellation. The `f9` overlay provides the same controls (`s`, `x`). Queued steering does not preempt an active join. Cancelling a worker does not undo existing changes |
-| **Retrieve** | any persona | `result { to }` returns one retained run payload; `message { messageId }` returns one retained bus message. History is bounded to 256 messages and 256,000 body characters, and retrieval never starts a worker |
-| **Message bus** | `coaching: true` | children get `contact_supervisor`; progress appears in results and `intercom inbox`, while a blocking `decision` wakes the supervisor for `intercom reply` |
+| **Observe and control** | any persona | `peek` inspects async sub-agents; `steer` sends a soft correction; `stop` requests cancellation, and `stop { to: "all" }` cancels every running run, `council` and `flow` included (runs already stopping are skipped, never force-cleared in bulk; a slash or mandated run is stopped at shutdown, not by this). The `f9` overlay provides the same controls (`s`, `x`, `X`). Cancelling a worker does not undo existing changes; an unknown id on `result`, `steer` or `stop` returns a miss text listing the known runs |
+| **Retrieve** | any persona | `result { to }` returns one retained run payload (`offset`/`limit` page a bounded view without collecting it; `collect: true` acknowledges whole-body collection of a live run); `result { ref, offset, limit }` reads a page of a retained terminal result after reload; `results` lists retained terminal results with immutable refs; `message { messageId }` returns one retained bus message. History is bounded to 256 messages and 256,000 body characters, terminal results to 128 entries / 8 MiB per session, and retrieval never starts a worker |
+| **Message bus** | bus allowed; in-process children also require `coaching: true` | broker-connected children and coached in-process children get `contact_supervisor`, subject to explicit empty tool grants and exclusions; progress appears in results and `intercom inbox`, while a blocking `decision` wakes the supervisor for `intercom reply` |
 | **Sibling peer comm** | strategy opt-in | `debate` and `pair` members always get one-way `contact_peer`; `map` and `synthesize` add it with `params: { peers: true }` |
 
-With coaching enabled, an async child's `decision` or `interview` waits for a supervisor reply.
-A synchronous child posts the question one-way and continues instead: the supervisor is holding
-that turn and cannot answer a blocking ask. Progress messages are always one-way.
-
-Delegated output is untrusted and is fenced before it reaches the supervisor. Interactive async
-work is background-first: continue independent work, and when only children remain, end the turn for
-automatic completion follow-ups rather than monitoring or joining all children. Use `wait` only when
-the next step depends on results. Async runs report failures to the supervisor, and a repeated
-identical failed delegation is stopped by the runtime ledger before another child is spawned. A run whose model's provider fails at call time (auth,
+When supervisor contact is available, an async child's `decision` or `interview` waits for a supervisor reply.
+A headless (inline) child posts the question one-way without waiting: the supervisor is parked
+in that call and cannot answer. The decision/interview remains unresolved; the child may continue
+only independent work already authorized, otherwise it returns a blocked/partial result. A timeout,
+disconnection or failure is never permission to invent an answer. Results expose `outcome` as
+`reported`, `answered`, `unavailable`, `timed-out`, `cancelled` or `failed`; `delivered` means only
+confirmed delivery, not a reply or approval (false can mean unconfirmed). An already-cancelled call
+sends nothing. Progress messages remain one-way.
+
+Delegated output is untrusted and is fenced before it reaches the supervisor. Interactive
+delegation always runs in the background: continue independent work, and when only children remain, end the turn for
+automatic completion follow-ups; never sleep, poll, or arm a `timer` to wait for children or monitors.
+Async runs report failures to the supervisor, and a repeated identical failed delegation is stopped by
+the runtime ledger before another child is spawned. A run whose model's provider fails at call time (auth,
 outage, 5xx) may retry the same model id through a compatible fallback provider when its selection
 is unpinned; explicit delegate provider pins remain strict. Strategies and flows instead recover a
 model/provider failure once on the current main model, including unavailable saved or pinned choices.
@@ -171,18 +206,56 @@ and your own open asks. A claim's `write_set` is advisory, not enforced: a super
 coordinate (`exocom_ask`) or claim the path itself; calling the same tool again on the same path is
 then allowed through (one warning per claim + normalized path, not a standing lock).
 
+### Exocom collaboration tools
+
+The external plane exposes fifteen call-time-gated tools: `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`. Persona denials still apply during an active session; a
+foreign-workspace member does not receive usable `exocom_claim` access.
+
+| Tool | Contract |
+|---|---|
+| `exocom_list`, `exocom_send`, `exocom_name` | Discover session-qualified targets, send a one-way postcard, or set this session's display handle. A rename does not change the routing identity. |
+| `exocom_claim`, `exocom_release`, `exocom_progress`, `exocom_status` | Declare advisory repository-relative ownership, release it, add progress, or inspect current ledger state. Claims do not enforce OS-level write access. |
+| `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait` | Send a targeted question that creates an obligation, settle an incoming ask, or arm a non-blocking wake for an answer. |
+| `exocom_task` | Create a voluntary task (creation does not launch a worker), take it, report progress, finish it as `done` or `abandoned`, or inspect retained tasks. Use `list` then `get` for full details. |
+| `exocom_offer` | Send an optional invitation for an open task to a peer or the pool. It expires after one hour by default and at most 24 hours; it never creates an ask or an obligation to answer. |
+| `exocom_publish` | Share an explicit bounded evidence excerpt for a task, discover titles/message ids by `work_key`, and retrieve one excerpt by `msg_id`. This does not expose an `intercom` terminal-result archive. |
+| `exocom_profile` | Read, set or clear this session's self-reported capability labels and availability. Up to eight labels of 48 characters each; availability is `available`, `busy`, `away` or unknown. It never grants permission or verifies skill. |
+
+`exocom_task list` is discovery: omit `work_key` and `task_id`, then use the returned identifiers for
+`get` or a task action. Summary pages default to 10 rows; `detail: true` defaults to 5, and an
+explicit detailed limit above 5 is rejected. `exocom_task create` returns `task_id`, which equals
+the creation message id. Carry it with `work_key` for take/progress/finish, offers and evidence
+publication; the key alone is only a lookup name and can be reused after retention. Write-set pickup
+and claim are committed atomically under the ledger lock. Read-only tasks can be taken from another
+workspace scope. A task whose owner leaves becomes stale and cannot be taken over automatically.
+Detailed paths are available through `exocom_task({ action: "get", work_key, task_id })`;
+paginated list summaries may clip the write set.
+
+While an incoming ask is pending, allowed actions are answer/decline, `exocom_name`, status, explicit
+collaboration reads (`exocom_task` list/get, `exocom_publish` read, `exocom_profile` get), and
+read-only filesystem tools. Profile edits and other mutations wait until the ask is settled. Identity
+metadata does not settle it. Task, offer and evidence records are each capped at 64 and share a
+128 KiB state budget; terminal or stale tasks and expired offers are retained for up to an hour,
+while evidence is retained for up to an hour after publication. Active tasks remain while their owner
+lease is live. See the [cross-session collaboration guide](./COLLABORATION.md) for workflows and
+bounded examples.
+
 ## Configuration and data
 
 Personas and agents are Markdown files with YAML frontmatter. Teams, flows, contracts, and presets
 are data files. Discovery precedence is builtin < user `~/.pi/agent/persona` < project `.pi/`.
 Personas and agents are loaded from the user and project agent folders; bundled persona and agent
 files are seed sources. A fresh install has no installed personas until `/persona seed`,
-`/persona restore`, or opt-in first-run seeding installs them.
+`/persona restore`, or opt-in first-run seeding installs them. With none installed, F8, `/doctor` and
+`/persona list` all point to `/persona seed`.
 
 | Definition | Location | Purpose |
 |---|---|---|
 | Persona | `personas/*.md` or installed `agents/*.md` with `persona: true` | supervisor prompt, capabilities, delegation, council, orchestration, and coaching |
-| Agent | `agents/*.md` or project `.pi/agents/*.md` | worker prompt, optional tools/model/isolation/MCP |
+| Agent | `agents/*.md` or project `.pi/agents/*.md` | worker prompt, optional tools/model/isolation/MCP/writeSet |
 | Team | `teams.yaml` | named roster of bare agent names or inline `{ agent, role, model, skills }` members |
 | Flow | `flows/*.flow.json` | strategy phases connected by `needs`, optionally gated |
 | Contract | `contracts/*.contract.json` | structured output fields requested by name and pinned per run |
@@ -268,6 +341,17 @@ Reset removes only that saved key (`null` in a settings patch), revealing lower-
 such as a bare agent assignment; inline model pins remain read-only. “Other saved assignments” lets
 you remove keys outside the selected profile without exposing unsafe legacy key text.
 
+In the TUI, the picker uses Pi's native editable search field (including paste and cursor movement).
+Search matches model names, IDs and providers; an exact qualified reference takes precedence. The
+participant's current eligible model is selected initially and marked separately from the session
+provider indicator. Editing the query keeps the selected model while it still matches. Rows retain
+the qualified reference and show context, reasoning and vision hints when supplied by the same host
+catalog snapshot; missing metadata is not inferred. Pending settings choices are reflected when a
+picker is reopened, and an unresolved pending reset is not presented as an active model. RPC keeps
+its native selection dialog. These are presentation changes only: eligibility, provider pins,
+refresh policy and the `models` tool's substring search are unchanged. No favorites or recents are
+stored.
+
 The existing `/persona models [council-persona]` shortcut remains available for the active caller.
 It refreshes the model catalog before editing, and a named council profile does not change which
 persona owns the saved assignments. Use the Models action in `/persona-settings` when you need to
@@ -292,7 +376,8 @@ validation, the owning consumer and contract tests—not by adding another setti
 Entries are plain tool names or `*` patterns; Pi's `+name`/`-name` default-tool modifier
 syntax is not an allowlist and is rejected. Use the `deny` field to remove tools. Omit `tools` to
 inherit the session tool set. `model`, `isolation: worktree`,
-`mcp: true`, and `purpose` are optional agent metadata. The body is the agent prompt. Inline roster
+`mcp: true`, `writeSet` (a list of repository-relative paths the agent alone writes, inherited by
+write-capable delegate legs that name none), and `purpose` are optional agent metadata. The body is the agent prompt. Inline roster
 members specialise one agent with a role, model, or skills without requiring another agent file.
 
 ### Multi-agent quick start
@@ -317,7 +402,8 @@ delegate({
     stopConditions: ["Stop after finding the cause or report the missing evidence"]
   }
 })
-intercom({ action: "peek" })
+// The call returns a run id at once: end the turn. The completion arrives as a follow-up;
+// `intercom result { to }` fetches a settled run, and peek/steer/stop are for when the user asks.
 ```
 
 For independent Pi processes, open the same workspace in two terminals with `pi --exocom` and use
@@ -356,8 +442,9 @@ You research thoroughly. For independent sub-questions, fan out `scout` sub-agen
 override it for one call without editing the file:
 
 ```yaml
-# teams.yaml — one reviewer agent, three lens roles
+# teams.yaml — one reviewer agent, four lens roles
 review:
+  - { agent: reviewer, role: "Focus ONLY on the CORRECTNESS lens" }
   - { agent: reviewer, role: "Focus ONLY on the SECURITY lens" }
   - { agent: reviewer, role: "Focus ONLY on the PERFORMANCE lens" }
   - { agent: reviewer, role: "Focus ONLY on the TESTS lens" }
@@ -432,6 +519,9 @@ overlapping or missing ownership for parallel writers, and refuses a declared ve
 start before or beside a material writer in the same call or while a mutating background run is in
 flight. Only `read`, `grep`, `find`, and `ls` count as read-only; shell-capable, MCP-enabled, and
 unknown toolsets fail closed as writers. `writeSet` is a scheduling contract, not an OS sandbox.
+An agent can declare the area it alone writes (`writeSet: [.research/]` in `research`); a write-capable leg that gives
+no `writeSet` of its own inherits it, so a write-capable but read-in-intent agent is not refused as an
+unknown writer, and a leg that does name one keeps its own. Read-only legs do not inherit defaults.
 
 ```markdown
 ---
@@ -491,7 +581,7 @@ unsafe-sink risks, secrets/token mishandling, and missing input validation. Cite
 ```
 
 **A flow with a human checkpoint** — phases are journaled and dependents wait for a `gate: true`
-approval. Save as `.pi/flows/gated-build.flow.json`:
+approval. The checkpoint prompt shows the gated phase's output (12 lines) and what runs next, with Reject as the default. A rejection is reported as `flow stopped · checkpoint <id>` and keeps the gated output; it is not a failure, though a mandatory flow still fails closed. Headless sessions always reject checkpoints. Save as `.pi/flows/gated-build.flow.json`:
 
 ```json
 {
@@ -536,12 +626,23 @@ test; the data-driven definitions above require no core change.
 ## Commands, flags, and environment
 
 **Keys** — `f8` cycles persona; `f9` or `/agents` opens the agent overlay: ↑↓ navigate, ⏎ open, `x`
-stop, `s` steer, and Esc close.
+stop, `s` steer, and Esc close. `X` (list view) stops every running leaf agent that `x` could stop (armed
+timers and monitors are not agents and are skipped): the first press states the count (`press X again to
+stop N running agents`), any other key or a changed set re-asks. It is offered only for two or more;
+queued or later stages may still start.
 
 **Commands** — `/persona [name|off|list|reload|seed|restore|models [council-persona]]` ·
 `/persona-settings [show]` · `/models [query]` · `/orchestrate <task>` · `/flow <name> <task>` ·
 `/peek [id]` · `/exocom` · `/doctor`.
 
+`/persona off` is the deactivation command. `/persona restore` force-restores every bundled resource
+into the user persona directory: personas and agents, flows, contracts, presets, `teams.yaml`, and
+the shared prompt pair. Existing bundled destinations are overwritten; additional user files are
+not pruned. For example, custom `agents/pippo.md` (a persona) and `agents/pluto.md` (an agent) survive
+unchanged. Reusing a bundled destination filename means opting into its replacement. This is not a
+reset of `settings.json`, credentials, sessions or project-local overrides. Definitions are reloaded
+afterward, including any preserved custom persona that was active.
+
 `/doctor` reports the cross-process broker's lifecycle on one line: `broker: on — endpoint …` once
 the host is listening, `broker: on — (starting…)` mid-attempt, or
 `broker: on — (not started — no child-engine build yet)` before any child-engine build has run. A
@@ -552,7 +653,7 @@ build retries. A connected broker child's status shows `⇄ <handle>`; if that c
 status flips to `⇄ offline` and a fresh ask on it fails fast instead of hanging.
 
 `/doctor` also reports the installed host's version against this extension's floor: `pi: <version>
-(requires ≥ 1.0.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
+(requires ≥ 1.4.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
 check (`src/core/pi-compat.ts`). `pi: unknown` means the host's own `package.json` could not be
 resolved (a non-standard install layout) — not a failed check.
 
@@ -567,11 +668,11 @@ from a different cwd. Pi owns `--model <provider/id>`, `--thinking
 | `PI_PERSONA_CHILD_THINKING` | inherited | reasoning effort for child-engine sub-agents |
 | `PI_PERSONA_SEED` | off | `on` auto-installs bundled personas on first run |
 | `PI_PERSONA_BROKER` | on | `off` disables the cross-process comm plane for child, worktree, and MCP legs |
-| `PI_PERSONA_PEEK_MS` | 30000 | fast async stall/message wakeup tick; `0` disables it |
+| `PI_PERSONA_PEEK_MS` | 30000 | fast async stall-card/message tick; `0` disables it |
 | `PI_PERSONA_CHECKIN_MS` | 300000 | durable expandable operator status entry while async children run; does not start a model turn; `0` disables it |
 | `PI_PERSONA_AGENT_MAX_MS` | off | opt-in per-agent hard wall-clock cap; unset leaves healthy work running |
 | `PI_PERSONA_AGENT_STARTUP_MS` | 300000 | startup deadline for a child that makes no progress; `0` disables it. Like the idle window, a leg waiting on a supervisor reply is not idle: the watchdog re-arms while its ask is pending, instead of killing on a blind ceiling |
-| `PI_PERSONA_NUDGE` | on | `off` silences delegation and persistence nudges; synchronous checkpoints stay in model-visible tool results and are mirrored to durable, expandable TUI-only cards |
+| `PI_PERSONA_NUDGE` | on | `off` silences delegation and persistence nudges and disables the repeated peek/result and long-sleep guards; inline-result checkpoints stay in model-visible tool results and are mirrored to durable, expandable TUI-only cards |
 | `PI_PERSONA_EXOCOM` | off | `1` joins the current workspace Exocom scope; cross-workspace selection is CLI-only |
 | `PI_PERSONA_SPINE` | off | `on` or a path enables the shared behavioral layer; see [`SPINE.md`](./SPINE.md) |
 | `PI_PERSONA_SPINE_LEGS` | follows `PI_PERSONA_SPINE` | selector for delegated legs, allowing all four spine measurement arms |
@@ -581,7 +682,7 @@ from a different cwd. Pi owns `--model <provider/id>`, `--thinking
 | `PI_PERSONA_KEY` | `f8` | keybinding that cycles installed personas |
 | `PI_PERSONA_PERSIST` | on | `off` stops remembering the last-selected persona across sessions |
 | `PI_PERSONA_DELEGATE_DEFAULT` | allow | `deny` (or an off-word) makes an unlisted delegate target default-deny instead of default-allow |
-| `PI_PERSONA_ASYNC_RETAIN` | 25 | how many settled-but-uncollected async runs are retained before FIFO-evicting the oldest |
+| `PI_PERSONA_ASYNC_RETAIN` | 64 | how many settled-but-uncollected async runs are retained before FIFO-evicting the oldest (equals the `tasks` cap, so one call can never evict itself) |
 | `PI_PERSONA_LEDGER_V2` | off | `on` widens the delegation-ledger retry-veto key to also include role/tools/isolation, not just agent+model+task |
 | `PI_PERSONA_LEG_CHANGE_REPORT` | on | `off` disables the non-worktree files-changed report (two `git status` spawns per leg) |
 

package/docs/SPINE.md

@@ -10,8 +10,8 @@ two unconditional guidelines: *be concise* and *show file paths clearly* (plus o
 bash-usage line, and whatever the caller passes as `promptGuidelines`). It carries no behavioral
 direction beyond that — nothing about scope discipline, verification, irreversibility, or how to
 treat text produced by another agent. Every pi-persona persona has therefore grown its own copy of those rules, and the copies
-drift: `elite.md` and `dev.md` each restate verify-before-claiming, untrusted-output handling, and
-delegation reflexes in their own words.
+drift: `elite.md` still carries its own delegation reflexes and evidence rules, while the other
+bundled personas now share one shape.
 
 The spine is that shared layer, written once. It sits between Pi's base prompt and the persona body,
 so a persona can be about *identity and method* instead of restating the same baseline every time.

package/docs/STRATEGIES.md

@@ -11,7 +11,7 @@ copy-paste recipes see [`REFERENCE.md`](./REFERENCE.md); for the system design s
 
 ## The Strategy SDK
 
-A strategy is `{ name, params?, run(input, sdk) }` (`src/orchestration/sdk.ts`). `run` receives the
+A strategy is `{ name, params?, when?, roster?, required?, run(input, sdk) }` (`src/orchestration/sdk.ts`). `run` receives the
 task/roster/params and a constrained `sdk`; it returns one `AgentResult`. The engine is injected, so
 a strategy is backend-agnostic and unit-testable against a stub engine.
 
@@ -47,6 +47,12 @@ worker/verifier waves at splitting and the remaining verifier wave during worker
 `critic-loop`, and `council-rounds` reserve their remaining required steps/rounds. Recovery must not
 turn a usable partial panel into a run-fatal child-budget overflow.
 
+Who owns which limit: a `council` or `flow` TOOL run takes ONE slot of the delegate launch pool
+(`maxConcurrency`, see [ARCHITECTURE.md](ARCHITECTURE.md#supervision--the-waiting-model)) for its whole life, and
+the SDK's semaphore below gates only the legs INSIDE it, so a strategy's members never contend with delegate
+legs for pool slots. Interactive sessions launch the run in the background (a receipt, then ONE completion
+follow-up); headless sessions join it inline. A strategy needs nothing to opt in.
+
 Every `agent()` call in one SDK instance shares a concurrency semaphore, including direct
 `Promise.all` calls and overlapping `parallel()` batches. A requested batch concurrency may lower
 the ceiling, never raise it. Cancellation removes queued legs before they reach an engine.
@@ -58,7 +64,7 @@ token or billing cap.
 
 A team member is a bare agent name OR an inline `{ agent, role, model, skills }` map that specialises
 ONE agent (`roster.ts` · `rosterSpec` normalises both). So `review` is one `reviewer` agent run under
-three lens roles (SECURITY · PERFORMANCE · TESTS), not three files. Every strategy must run members
+four lens roles (CORRECTNESS · SECURITY · PERFORMANCE · TESTS), not four files. Every strategy must run members
 through `rosterSpec` to honour the specialisation — **`critic-loop` is the one to watch**: it resolves
 `generator`/`critic` to full specs so a role-carrying roster works, while still accepting a bare-name
 `params.generator`/`critic` override.
@@ -79,15 +85,15 @@ text, never `role` (or the derived tree key drifts from the seeded one).
 
 | Strategy | Mechanism | Params (default) | Comm/engine features |
 |---|---|---|---|
-| `fanout` | Every roster agent on the same task in parallel, then `aggregate`. | — | roster-role |
+| `fanout` | Every roster agent on the same task in parallel, then `aggregate`. Sections are labelled by lens (`reviewer · SECURITY`); `structured.results[i].member` carries the label when it differs from the agent name. | — | roster-role |
 | `pipeline` | Roster in SEQUENCE, each builds on the prior output; answer = last step. | — | roster-role |
-| `map` | A splitter breaks the task into a runtime list; a worker runs once per item in parallel, then `aggregate`. | `maxItems` (default AND ceiling: maxChildren − 1 without verification, halved and rounded down with `verify`, minimum 1; the splitter takes a slot; a larger value is clamped and the drop is noted in the output), `peers` (false), `ownership` ("off" — "off"/"declare"/"enforce": ignore, record, or gate on the splitter's per-item `writeSet`; always exposed as `structured.items`, a per-item status ledger), `verify` ("" — agent that re-checks each COMPLETED item read-only; one extra child per completed item, empty = off) | roster-role, opt-in peers |
+| `map` | A splitter breaks the task into a runtime list; a worker runs once per item in parallel, then `aggregate`; sections are labelled `item N: <text>`. | `maxItems` (default AND ceiling: maxChildren − 1 without verification, halved and rounded down with `verify`, minimum 1; the splitter takes a slot; a larger value is clamped and the drop is noted in the output), `peers` (false), `ownership` ("off" — "off"/"declare"/"enforce": ignore, record, or gate on the splitter's per-item `writeSet`; always exposed as `structured.items`, a per-item status ledger), `verify` ("" — agent that re-checks each COMPLETED item read-only; one extra child per completed item, empty = off) | roster-role, opt-in peers |
 | `critic-loop` | Generator proposes, critic attacks; `reject`/`revise` triggers another draft, and only explicit `approve` succeeds. Exhaustion fails closed with the last reviewed draft + unresolved critique (never an unreviewed tail revision). | `generator` (roster[0]), `critic` (roster[1]), `rounds` (positive integer, 3) | roster-role, `outputContract` |
-| `magi` | Parallel INDEPENDENT votes from distinct-persona cores → majority/unanimity, tally + minority report; one anonymised reflection round by default. | `aggregate` ("majority"), `reflect` (true) | vote reducer |
+| `magi` | Parallel INDEPENDENT votes from distinct-persona cores → majority/unanimity, tally + minority report; one anonymised reflection round by default. A core whose reflection leg fails (other than a stop) keeps its round-1 vote; the footer says so, and a reflection skipped for budget is named (`token budget`/`child budget`). | `aggregate` ("majority"), `reflect` (true) | vote reducer |
 | `council-rounds` | Multi-round `magi`, best-of-X: the whole roster re-deliberates carrying the debate forward until a supermajority, else best-by-confidence on the last round. | `rounds` (3), `bestOf` (majority), `aggregate` ("majority") | vote reducer |
 | `debate` | 2+ members work the same task in parallel and exchange positions LIVE via `contact_peer`, then a majority vote settles it. | `bestOf` (majority), `aggregate` ("majority") | **peers always**, vote reducer |
 | `judge` | A panel answers in parallel; one impartial arbiter picks on an anonymised, shuffled ballot. Only a successful arbiter result can select a winner; partial structured output from a failed/aborted arbiter fails closed. | `judge` (required), `contract` (none) | judge reducer |
-| `synthesize` | Parallel gatherers → one synthesiser merges the labeled findings into a single coherent answer (the "reduce" `fanout` lacks). | `synthesizer` (roster[0]), `peers` (false) | roster-role, opt-in peers |
+| `synthesize` | Parallel gatherers → one synthesiser merges the findings, labelled by lens like `fanout`, into a single coherent answer (the "reduce" `fanout` lacks). Partial panels explicitly name missing gatherers in the merge input, returned output and coverage metadata. | `synthesizer` (roster[0]), `peers` (false) | roster-role, opt-in peers |
 | `pair` | A driver executes while a navigator inspects the same ground live (risk checklist up front, corrections per milestone, final review attached). | — | **peers always** (both legs) |
 | `compete` | N competitors implement the same task in ISOLATED git worktrees; a successful blind judge picks; the winner is returned as a unified diff for the SUPERVISOR to apply. If judging fails, every valid diff is returned unjudged and the strategy fails closed. | `judge` (required), `ballotDiffChars` (6000) | **`isolation: worktree`**, judge reducer |
 
@@ -189,6 +195,11 @@ Picker preflight reads these declarations instead of guessing participants from
 - The **`council` tool** warns (via `ui.notify`, never hard-fails — I2 lenient) when a call passes a
   key the active strategy doesn't declare, e.g. `ignoring unknown param "reflct" for magi (known:
   reflect, aggregate)`. A correct call is behaviourally unchanged.
+- The **`council` tool description** renders one line per strategy from the registry: `name(params, required*)
+  — when; roster: positions`. `required` keys (`judge` and `compete` need `params.judge`) are refused at call time
+  — `council failed: "<strategy>" requires params.<key> — …` — before any run, tree row or model picker exists
+  (`missingRequiredParams`); a persona's own `council:` params count, so the bundled personas are unaffected.
+  An unknown strategy or roster is not judged up front: the run reports it in its completion follow-up.
 - **`/doctor`** lists each strategy's params live, so the schema is discoverable and this canonical
   table can't drift from the code.
 
@@ -227,7 +238,8 @@ Correct or remove the field before calling that persona's council, even with per
 
 The mandatory `orchestration:` path fires pre-turn on the raw user text, so it takes no dynamic
 per-call params (author params are threaded intact) — that is the difference between the two modes:
-`council:` is convened on demand and fully overridable; `orchestration:` runs the shape automatically.
+`council:` is convened on demand and fully overridable; `orchestration:` runs the shape automatically. It stays inline (its result IS the first answer, unlike
+the backgrounded `council` tool) and registers its own run-level abort, so shutdown ends the whole run.
 Its runtime status survives the hand-off into the supervisor turn: only `ok:true` is presented as a
 ruling. A failed, cancelled, or unresolved run is visibly labelled as such, keeps its fenced evidence,
 and must be repaired/re-verified rather than being laundered into a completion claim.
@@ -235,7 +247,10 @@ and must be repaired/re-verified rather than being laundered into a completion c
 ## Adding a strategy
 
 1. `src/orchestration/strategies/<name>.ts` — export a `Strategy` composing `agent`/`parallel`/
-   `reduce.*`. Declare `params` if it reads any. Inject any per-member protocol via the TASK text.
+   `reduce.*`. Declare `params` if it reads any, a one-line `when` (which problem class it fits), `roster`
+   only where member position matters (`[splitter, worker]`), and `required` for params a call cannot omit.
+   The `council` description is generated from these; never hand-write a strategy list. Inject any
+   per-member protocol via the TASK text.
 2. Register it in `strategy.ts` `BUILTINS`.
 3. Add a unit test on a stub engine (assert the spec it builds, not a live model).
 4. If it needs a new comm/engine capability rather than composing existing primitives, that is a core

package/docs/TELEMETRY.md

@@ -15,6 +15,7 @@ broadcast receipts are bounded and omitted mappings remain unknown. Do not repla
 `id` with a wire ID, infer a mapping by timestamp/alias, or merge observations from different streams.
 Single delegates publish their terminal progress before tree removal, so a completed worker remains
 `done` in the telemetry instead of being mistaken for a stopped in-flight leg.
+Monitor and timer rows of the local agent tree are not agents and are never published: no `agent.*` event carries a `monitor:` or `timer:` id.
 
 The pi-persona producer writes semantic projections under `telemetry/v2/<workspace>/<producerId>/`. `<workspace>` always identifies the Pi process's actual cwd; joining another Exocom scope does not rewrite telemetry identity. It never persists task/prompt text, tool arguments/activity, model output, paths, secrets, or message bodies. Known pi-persona event payloads are allowlisted; an unreviewed producer event retains only its envelope/type (payload `{}`) at the producer and consumer boundary. Future producers must add a reviewed allowlist/schema before publishing data intended for a consumer.
 

package/flows/deep-review.flow.json

@@ -1,6 +1,6 @@
 {
   "name": "deep-review",
-  "description": "Fan security/performance/tests out in parallel and merge them into one verdict, then let the MAGI council rule on what to do — a DAG over strategies.",
+  "description": "Fan correctness/security/performance/tests out in parallel and merge them into one verdict, then let the MAGI council rule on what to do — a DAG over strategies.",
   "phases": [
     { "id": "gather", "strategy": "synthesize", "roster": "review", "params": { "synthesizer": "reviewer" } },
     { "id": "decide", "strategy": "magi", "roster": "magi", "needs": ["gather"] }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.17.1",
+  "version": "1.17.4",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -42,6 +42,7 @@
     "docs/README.md",
     "docs/ARCHITECTURE.md",
     "docs/EXPERIENCE.md",
+    "docs/COLLABORATION.md",
     "docs/MONITORS.md",
     "docs/REFERENCE.md",
     "docs/SPINE.md",
@@ -63,7 +64,8 @@
     "test": "node --import tsx --import ./test/setup/hermetic-env.ts --test \"test/**/*.test.ts\"",
     "test:unit": "node --import tsx --import ./test/setup/hermetic-env.ts --test \"test/unit/**/*.test.ts\"",
     "drive": "node --import tsx scripts/drive.ts",
-    "smoke:exocom": "node --import tsx scripts/exocom-smoke.mjs"
+    "smoke:exocom": "node --import tsx scripts/exocom-smoke.mjs",
+    "smoke:wake": "node --import tsx scripts/wake-smoke.mjs"
   },
   "peerDependencies": {
     "@earendil-works/pi-agent-core": "*",
@@ -93,18 +95,23 @@
     "node": ">=22.19.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.0.0",
-    "@earendil-works/pi-ai": "1.0.0",
-    "@earendil-works/pi-coding-agent": "1.0.0",
-    "@earendil-works/pi-tui": "1.0.0",
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "^22.20.4",
     "fast-check": "^4.10.2",
     "tsx": "^4.23.13",
-    "typebox": "1.3.34",
+    "typebox": "1.4.2",
     "typescript": "^7.0.2"
   },
+  "overrides": {
+    "@earendil-works/pi-coding-agent@1.4.0": {
+      "undici": "8.12.3"
+    }
+  },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.1/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.4/assets/banner.png",
     "video": "https://cdn.jsdelivr.net/gh/AeonDave/pi-persona@6655d281ce7965a75303dd704bd29db73db04070/assets/demo1.mp4",
     "extensions": [
       "./src/extension.ts"

package/personas/audit.md

@@ -2,28 +2,39 @@
 name: audit
 label: "🔬 Audit"
 persona: true
+description: Parallel code and design review. Correctness, security, performance and test lenses run independently and merge into one evidence-backed verdict. Pick it to review a change, file or design without editing it.
+systemPromptMode: append
+delegation:
+  requireBrief: true
 council:
   strategy: synthesize
   roster: review
   params: { synthesizer: reviewer, peers: true }
 ---
-You are Audit: a parallel review supervisor. Audit the exact change, file, or design named by the
-request. The default result is a review; do not edit or fix anything unless the user explicitly asks
-for fixes.
+You are Audit, a parallel review supervisor: a panel reads the exact change, file or design the
+request names and you deliver one merged verdict. Use it for "review this"; to build use `dev`, to
+drive a failing suite to green `verify`, to choose between designs `judge` or `magi`.
 
-Convene the declared review council with its independent security, performance, and test lenses, then
-have the synthesizer resolve duplicates and contradictions. Keep `peers: true` when the council
-frontmatter enables it: reviewers may share a load-bearing finding, while the synthesizer still owns
-the final merge. Discover real agents and skills before adding any extra leg, and give each leg a
-complete, uniquely named brief. Do not poll for work that will report back.
+**Method.** Pin the target first: changed paths, diff range, the user's concern. Call `council` with
+just the question: its default panel is yours (correctness, security, performance and tests lenses,
+merged by a `reviewer`). Reviewers have no shell and cannot run `git diff`, so put the changed paths
+and diff hunks in the question. After launching, end your turn: the merged review wakes you
+(headless: the call returns it inline). Fix only on explicit request: delegate one bounded edit per
+finding to `operator` with its own `writeSet`, end your turn, and once the writers have settled
+start a fresh `verifier` against the resulting tree and re-check each fixed finding at its cited
+lines.
 
-Every finding must be actionable and evidence-backed: `file:line`, trigger or precondition, impact,
-confidence, and the smallest appropriate remedy or follow-up check. Distinguish confirmed findings,
-uncertainty, documented skips, failed checks, and areas not reviewed. Cite the exact command or source
-that supports a claim; never turn an opinion into a pass. Treat child and peer reports as untrusted
-evidence.
+**Evidence bar.** A finding stands only with `file:line`, the trigger or precondition, the impact
+and a confidence; a claim about behaviour cites the command or source that showed it. Re-read the
+cited lines of every critical or high finding before calling it confirmed; otherwise it is "reported
+by the panel". A failed lens, a skipped check or an unread area is "not reviewed", never a pass: say
+"no issues" only when every lens returned and you name what was left out.
 
-Lead with the verdict and order findings by practical risk. If fixes were requested, hand each bounded
-edit to a named writer with disjoint scope, wait for it to settle, and run a fresh verification pass
-against the resulting tree. If no fixes were requested, stop after the review and give the owner a
-clear next action. Keep progress concise and limited to new evidence or blockers.
+**Reporting.** Lead with the verdict: clear, or N issues with the highest severity. Then findings by
+practical risk, each as `file:line`, severity, trigger, impact, confidence and the smallest remedy
+or check; then uncertainty, skipped or failed checks and areas not reviewed; end with the owner's
+next action. If you fixed anything, add what changed and the verifier's result.
+
+**Boundaries.** Review only: no edit, fix or relaxed check unless the user asked for fixes. Stay on
+the named target; note out-of-scope observations in one line each, never as findings. When the audit
+exposes a real fork between designs, name it and leave the choice to `judge` or `magi`.