@aeondave/pi-persona 1.17.0 → 1.17.3

package/docs/REFERENCE.md

@@ -34,26 +34,55 @@ 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 |
+| `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.
+settled async run also emits immediate UI feedback with that name and its terminal outcome. TUI
+failures persist an expandable card with the agent, model, elapsed time and a concise cause; expansion
+retains the full technical diagnostic. Other modes use a concise 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
 
@@ -66,13 +95,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 +123,20 @@ 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 |
+| **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; `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` |
 | **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,
+A headless (inline) child posts the question one-way and continues instead: the supervisor is
+parked in that call 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
+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.
@@ -177,22 +206,135 @@ Personas and agents are Markdown files with YAML frontmatter. Teams, flows, cont
 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 |
 | Preset | `presets/*.preset.json` | reusable council strategy, roster, and parameter bundle |
 
+### Unified pi-persona settings
+
+`/persona-settings` opens pi-persona's own settings editor in the TUI or RPC UI. It is a separate
+extension command; it does not replace Pi's native `/settings` or edit native Pi preferences such
+as compaction. The TUI is a full-page, filterable panel (`/` to search, `r` to reset the selected
+saved override, `m` for model assignments, `d` for diagnostics); the RPC UI offers the same
+settings, model, and diagnostics flows. `/persona-settings show` emits a read-only report and is
+available in headless sessions.
+
+The sole active settings file is `<agentDir>/persona/settings.json` (normally
+`~/.pi/agent/persona/settings.json`). Its version-1 top-level shape is:
+
+```json
+{
+  "version": 1,
+  "preferences": { "engine": "inproc", "nudge": true },
+  "personas": { "dev": { "models": { "reviewer": "provider/model-id" } } },
+  "lastPersona": "dev"
+}
+```
+
+`preferences` contains the public extension settings; `personas.<name>.models` preserves
+provider-qualified model assignments, and `lastPersona` remembers the selection when
+`PI_PERSONA_PERSIST` is enabled. The preference registry groups all editable scalar settings as:
+
+| Group | Preference IDs |
+|---|---|
+| Discovery | `extraDirs`, `seed` |
+| Startup | `defaultPersona`, `persist` |
+| Interface | `keybinding` |
+| Delegation | `delegateDefaultAllow`, `childThinking`, `engine`, `peekEveryMs`, `checkInEveryMs`, `agentHardTimeoutMs`, `agentStartupTimeoutMs`, `nudge`, `asyncRetain`, `ledgerV2`, `changeReport` |
+| Collaboration | `broker`, `exocom` |
+| Prompt | `spine`, `spineLegs` |
+| Mind (when loaded) | `mindCapture` (`auto`/`prompt`/`off`), `mindNudge` |
+| Flow (when loaded) | `flowEnabled`, `flowPort`, `flowIdleMs` |
+
+`disabled` and the storage path are not editable preferences. Model assignments remain scoped by
+persona owner, rather than being promoted into global preferences.
+`selectionRevision` is internal metadata in the same file: explicit persona-selection gestures
+increment it, while model/preference edits leave it unchanged. Companion readers can therefore
+distinguish a re-selection from an unrelated settings save without following whole-file timestamps.
+The editor never reloads Pi automatically. Scalar preferences load after a Pi restart or Pi's native
+`/reload`; `/new` alone does not reactivate Persona's extension factory. `/persona reload` reloads
+persona definitions and does not apply preference changes. The panel shows when a saved value is
+pending reload. Model assignments are read by the
+existing resolver for future runs, so they do not alter workers already running.
+
+Mind and Flow report their supported settings through Pi's public event bus; the panel does not import
+or require either plugin. Their preferences live in the same `preferences` object above, not in new
+plugin configuration files. Skill Optimizer remains independent. Absent companions do not expose
+nonfunctional controls. Updated companion versions are needed to contribute settings to this panel.
+
+`flowEnabled` controls default dashboard attachment; `--no-flow` still opts out for one run.
+`flowPort` is the desired port for the next shared service start, not a command to move an existing
+service. `flowIdleMs` is the advanced shared-service idle grace (50–60000 ms): it applies only with
+no Pi registrations **and** no browser SSE clients. Saving it never restarts another Pi's service.
+
+Explicit public `PI_PERSONA_*` environment values retain startup precedence over saved preferences.
+The panel marks an environment-controlled setting as locked; resetting its saved value only removes
+that saved override and does not defeat the environment. `PI_PERSONA_DISABLE` is an internal
+process guard and is not an editable setting.
+
+When no canonical `settings.json` exists, startup imports the retired `config.json` model store and
+`state.json` persona state (or the path supplied by `PI_PERSONA_STATE_FILE`) once. Successfully
+migrated, unchanged legacy files are archived as `<file>.migrated`; if validation, safe archival, or
+concurrency checks fail, the legacy source is kept and a warning is reported. Once `settings.json`
+exists, it is the only active store: legacy files are not dual-read. An invalid or unsafe canonical
+file is reported rather than overwritten. `PI_PERSONA_STATE_FILE` now only selects a legacy state
+file to import when the canonical file does not yet exist; it does not move or redirect active
+settings storage.
+
+The model editor asks you to choose an owner persona and then its current or a named council
+profile; it never activates that persona. It lists the roster and strategy-declared auxiliary
+participants using the runtime model precedence described below. The searchable model picker uses
+Pi's currently available provider-qualified models; opening the editor does not refresh provider
+catalogs, and refresh is an explicit action. Saving or removing an assignment affects future runs.
+Reset removes only that saved key (`null` in a settings patch), revealing lower-precedence sources
+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
+choose the owner explicitly.
+
+#### Companion settings adapter contract
+
+The optional synchronous bus channel `pi-persona:settings:collect:v1` receives
+`{ add(id, values) }`. A loaded supervisor companion responds with `add("mind", { mindCapture,
+mindNudge })` or `add("flow", { flowEnabled, flowPort, flowIdleMs })`, using its current startup
+snapshot. Each may report a supported subset. Persona validates ownership/types against the same
+registry used by the editor and displays only reported fields; an unrelated plugin cannot contribute
+an optimizer or native Pi setting through this channel. Contributors must not read credentials,
+refresh providers, write files, wake the model or start a service in response to collection.
+
+Persona alone patches the canonical settings file; companions read their own known fields and
+preserve their standalone operation and environment overrides. They must release/re-arm their
+listener with the owning extension lifecycle. Add a new control by updating registry metadata,
+validation, the owning consumer and contract tests—not by adding another settings writer.
+
 `tools` accepts an allowlist such as `[read, grep]`, an `allow`/`deny` object, or `[]` for no tools.
 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
@@ -217,7 +359,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
@@ -256,8 +399,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" }
@@ -332,6 +476,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
 ---
@@ -391,7 +538,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
 {
@@ -436,10 +583,14 @@ 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 [query]` ·
-`/orchestrate <task>` · `/flow <name> <task>` · `/peek [id]` · `/exocom` · `/doctor`.
+**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`.
 
 `/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
@@ -466,11 +617,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 |
@@ -480,11 +631,14 @@ 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_STATE_FILE` | a global default path | overrides where the last-selected-persona state is stored |
-| `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) |
 
+`PI_PERSONA_STATE_FILE` is only a migration input for the retired standalone state file; it no
+longer selects an active persistence path. The canonical store is always
+`<agentDir>/persona/settings.json`.
+
 ## Development
 
 ```bash

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.0",
+  "version": "1.17.3",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -63,7 +63,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 +94,18 @@
     "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.3.0",
+    "@earendil-works/pi-ai": "1.3.0",
+    "@earendil-works/pi-coding-agent": "1.3.0",
+    "@earendil-works/pi-tui": "1.3.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"
   },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.0/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.3/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`.