@aeondave/pi-persona 1.15.2 → 1.16.1

package/docs/REFERENCE.md

@@ -16,7 +16,7 @@ plus a file that calls `parallel` and `reduce.vote`.
 
 | Primitive | Does |
 |---|---|
-| `agent(spec)` | run one sub-agent and return a structured `AgentResult`; `spec` may carry `name`, model, tools, skills, or `outputContract` |
+| `agent(spec, { reserveChildren? }?)` | run one sub-agent and return a structured `AgentResult`; `spec` may carry `name`, model, tools, skills, or `outputContract`; optional reservations protect mandatory later legs from model recovery |
 | `parallel(thunks, {concurrency})` | run many at once, bounded by the run limits; this also provides the basis of `map` |
 | `reduce.aggregate(results)` | merge N results into one, used by fan-out |
 | `reduce.vote(candidates, opts)` | tally the candidates' own votes and preserve `winner`, `tie`, `no_consensus`, `invalid_outputs`, and dissent |
@@ -35,8 +35,8 @@ 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 | run the selected strategy over a roster and return its result; voting strategies preserve tally and dissent |
-| `intercom` tool | observe and control internal runs with `peek`, `result`, `wait`, `steer`, and `stop`; `list`, `inbox`, `message`, `reply`, and `send` drive the coaching bus |
+| `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 |
@@ -49,30 +49,70 @@ hard-fail.
 | `contracts/*.json` | define a hot-editable structured return requested through `outputContract` and pinned per run |
 
 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.
+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.
+
+### Pi 1.0 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
+turn a denied tool into an allowed one. Native `model-only` and `hidden` tools are not callable.
+
+Use scripts for independent batches or for filtering large results before returning them to the
+model, not as a wrapper that prints every result in full. `Promise.allSettled()` preserves successful
+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.
+
+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.
+
+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
+separately. A smaller script output also reduces model context; merely collapsing its card does not.
+No replacement sandbox or renderer is required for this integration.
 
 `outputContract` takes a contract **name**, not an inline shape — `/doctor` lists what's installed
-(the only built-in is `default`). Naming one that isn't installed is rejected before any worker
+(the built-in `default` and bundled `finding` are available without custom files). Naming one that
+isn't installed is rejected before any worker
 spawns, checked across every task in a parallel batch: `delegate: unknown output contract(s) "x" —
 nothing was spawned. Installed contracts: default, finding` (the list is capped at 16 names; a
 `, …` marker is appended only when more than 16 are installed).
 
 ### Supervising running sub-agents — the `intercom` plane
 
-The supervisor's internal communication with children has three layers:
+The supervisor's internal communication with children exposes these surfaces. Tree/F9/peek distinguish
+queued, running, waiting for supervisor, suspected stalled and terminal runs. Waiting is derived from
+a live pending ask on the exact child handle, never inferred from its last activity text:
 
-| Layer | Needs | What you get |
+| Surface | Needs | What you get |
 |---|---|---|
-| **Observe and control** | any persona | `peek` watches async sub-agents; `wait` joins them; `steer` sends a soft correction; `stop` requests cancellation. The `f9` overlay provides the same controls (`s`, `x`). Cancelling a worker does not undo existing changes |
+| **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` |
 | **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 }` |
 
-Delegated output is untrusted and is fenced before it reaches the supervisor. 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 fallback provider; each reroute surfaces to the
-supervisor as a warning toast, `<agent>: <from> failed, retrying on <to>`.
+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,
+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.
+They never substitute a peer's model or search arbitrary providers. Each recovery is visible and both
+attempts consume usage/child budget; stop, timeout, contract and infrastructure failures do not retry.
 
 Any leg that does NOT run in `isolation: worktree` shares the real checkout, so its result gets a
 "what changed" block appended: `--- FILES CHANGED DURING THIS LEG (shared checkout; parallel legs
@@ -235,6 +275,36 @@ Convene the council before sign-off, then apply its merged findings yourself.
 council({ question: "cache this or recompute?", strategy: "debate", roster: "review", params: { bestOf: 2 } })
 ```
 
+A one-off group can be composed without editing a team file. The external arbiter is also an
+agent specification, independent of the panel:
+
+```js
+council({
+  question: "Choose between these designs; prioritize correctness and operational cost.",
+  strategy: "judge",
+  members: [
+    { agent: "reviewer", role: "Evaluate correctness and failure boundaries." },
+    { agent: "reviewer", role: "Evaluate operating cost and maintainability." }
+  ],
+  params: { judge: { agent: "reviewer", role: "Choose impartially from the anonymised options." } }
+})
+```
+
+`members` overrides the named roster for this invocation only. Roles/skills do not grant tools or
+bypass capability gates. Model selection covers roster members and declared auxiliary actors such
+as `judge` and `synthesizer`; supported agent-valued params accept inline member specs too. Model
+precedence is inline `model`, saved role assignment, saved agent assignment, agent frontmatter,
+then the session model (`src/persona/model-participants.ts`).
+
+With an active persona, UI, and at least two configured models, unassigned participants can be
+picked and saved for the active persona, even when borrowing another persona's council profile.
+Dismissing a picker suppresses another prompt for that participant during the session, not for
+later teams with different participants. Headless runs never prompt.
+An unavailable choice is not overwritten: a provider or unknown-model failure may recover once
+on the main model, with the switch reported and both attempts accounted. This does not relax
+ordinary delegate provider pins. The MAGI persona retains its canonical core team; the Judge
+persona retains impartial arbitration. Other personas choose whichever strategy fits the task.
+
 **A delegation policy on any persona** — fields are generic and are never keyed to a persona name.
 The runtime rejects incomplete briefs before a model call, supplies a missing contract, rejects
 overlapping or missing ownership for parallel writers, and refuses a declared verifier that would
@@ -360,7 +430,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 ≥ 0.83.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
+(requires ≥ 1.0.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.
 

package/docs/STRATEGIES.md

@@ -17,7 +17,7 @@ a strategy is backend-agnostic and unit-testable against a stub engine.
 
 | Primitive | Contract |
 |---|---|
-| `sdk.agent(spec)` | Run ONE sub-agent → `AgentResult`. `spec`: `{ agent, task, model?, tools?, skills?, role?, outputContract?, isolation?, mcp?, timeoutMs?, peers? }`. |
+| `sdk.agent(spec, { reserveChildren? }?)` | Run ONE sub-agent → `AgentResult`. `spec`: `{ agent, task, name?, model?, tools?, skills?, role?, outputContract?, isolation?, mcp?, timeoutMs?, peers? }`. Optional `reserveChildren` protects mandatory later legs from spending their slots on recovery. |
 | `sdk.parallel(thunks, {concurrency?})` | Run many at once, capped at `limits.maxConcurrency`. The basis of every fan-out (`parallel(items.map(…))`). |
 | `sdk.reduce.aggregate(results)` | Concatenate N results into one (fan-out's merge). |
 | `sdk.reduce.vote(candidates, opts)` | Tally the candidates' OWN votes → a `ReducerResult` (`voting.ts`). |
@@ -27,7 +27,8 @@ a strategy is backend-agnostic and unit-testable against a stub engine.
 | series & loops | Plain `await` / `for` — a strategy is TypeScript, so `pipeline` and `critic-loop` are just native control flow. |
 
 Run limits (`RUN_LIMITS`) are enforced inside `makeSDK` regardless of how a strategy calls `agent()`:
-`maxChildren`, `maxConcurrency`, `budgetTokens`, `timeoutMs` (idle window). Nesting depth is not a
+`maxChildren`, `maxConcurrency`, `budgetTokens`, `timeoutMs` (idle window). Model recovery attempts
+consume child slots and usage too; they are not free legs hidden outside these limits. Nesting depth is not a
 numeric knob on this list — it is structurally 1: a spawned child's whole pi-persona extension
 disables itself under `PI_PERSONA_DISABLE=1`, so it has no `delegate`/`council`/`orchestrate`/`flow`
 tool to call however a strategy or persona tries to nest it (the in-process engine additionally
@@ -39,6 +40,13 @@ indefinitely; the idle watchdog catches silence. Safety comes from these runtime
 structural depth-1 guarantee, not from sandboxing the strategy (see the I2 invariant in
 [ARCHITECTURE.md](ARCHITECTURE.md)).
 
+Optional main-model recovery leaves admission room for queued logical legs and parallel thunks.
+`agent(spec, { reserveChildren })` additionally reserves slots for a mandatory later phase;
+`judge`, `compete`, and `synthesize` protect their final arbiter/merge this way. `map` reserves the
+worker/verifier waves at splitting and the remaining verifier wave during workers; `pipeline`,
+`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.
+
 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.
@@ -55,6 +63,13 @@ through `rosterSpec` to honour the specialisation — **`critic-loop` is the one
 `generator`/`critic` to full specs so a role-carrying roster works, while still accepting a bare-name
 `params.generator`/`critic` override.
 
+The `council` tool also accepts temporary `members`, with the same member shape. These override the
+named roster for that invocation only: no team or persona file is created or changed. An empty or
+invalid list is an error, not a request to silently fall back to MAGI. External actors such as
+`params.judge`, `params.synthesizer`, `params.generator`, `params.critic`, and `map`'s `params.verify`
+accept a bare agent name
+or an inline member specification, so the arbiter can have its own role and model too.
+
 Same-agent members are disambiguated in the live `f9` tree by a role hint (`reviewer · SECURITY`) via
 `rosterNodeKeys`/`roleHint` (`roster.ts`) + the SDK's per-run key (`sdk.ts`). If you touch either, keep
 the seeding loop and the SDK key derivation in lockstep, and inject any per-run protocol via the TASK
@@ -66,7 +81,7 @@ text, never `role` (or the derived tree key drifts from the seeded one).
 |---|---|---|---|
 | `fanout` | Every roster agent on the same task in parallel, then `aggregate`. | — | 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, 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`. | `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 |
 | `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 |
@@ -82,10 +97,12 @@ text, never `role` (or the derived tree key drifts from the seeded one).
 single read-only review pass per completed unit of work, not swarm autonomy for its own sake. It
 runs one extra child per COMPLETED item (a failed item has nothing to re-check), through the same
 `sdk.parallel` wave as the workers, so `maxChildren`/`maxConcurrency`/`budgetTokens` still bound it
-— sizing `maxItems` with headroom for roughly double the child count is the caller's job when
-`verify` is set. It pays for a batch where a wrong answer is expensive and hard to eyeball after
-the fact (security-sensitive edits, long-tail correctness); it costs more than it is worth for a
-low-risk sweep a supervisor can spot-check itself. A verifier's stance is read via the SAME
+— `map` automatically reduces the item ceiling to leave one verifier slot per item. With the default
+`maxChildren: 64`, that allows 31 items (1 splitter + 31 workers + 31 verifiers); a lower `maxItems`
+can leave more room for optional model recovery. It pays for a batch where a wrong answer is
+expensive and hard to eyeball after the fact (security-sensitive edits, long-tail correctness);
+it costs more than it is worth for a low-risk sweep a supervisor can spot-check itself.
+A verifier's stance is read via the SAME
 `outputContract: "default"` machinery `critic-loop` uses for its critic (`structured.stance`):
 `"approve"` passes, anything else — an explicit reject/revise, a missing stance, or a verifier leg
 that itself failed to run — flips that item's `structured.items` ledger entry to `status: "failed"`
@@ -134,22 +151,18 @@ council. They are enforced structurally, not by convention.
   failures stay excluded) — so `magi`/`council-rounds`/`debate` degrade to the strongest single
   response rather than returning `ok: false`. The "N invalid excluded" footer counts only
   genuinely-dropped candidates, not the surfaced prose.
-- **A broken MODEL costs a member, not its vote.** A core that fails because its model broke —
-  `failureKind: "provider"` (the provider rejected or is down) or `"unknown-model"` (the ref does not
-  resolve) — is re-run ONCE on a model this same run proved works: a healthy peer's, preferring the
-  session's own when a peer used it, and falling back to the session model when the failing core is
-  the first or the only one left (`orchestration/model-retry.ts`, applied by `magi`). Every other
-  failure passes straight through: an `abort`, `timeout`, `contract` or agent error reproduces on any
-  model, and a retried abort would be a stop that does not stop. This is a roster-level complement to
-  `engine/fallback.ts`, which reroutes the SAME model id across providers and knows nothing about the
-  other members; the engine exhausts provider routes first, and only a still-broken run reaches here.
-  It is deliberately a recovery and never a preference — a council's value is UNCORRELATED errors from
-  distinct reasoners, so each recovery is named in the ruling's footer (`· 1 core recovered on
-  <model>`) and usage bills every attempt. It is also bounded by the run's own `maxChildren` and
-  observed token spend: recovery attempts run serially so each completion can close the token gate
-  before another billed leg starts, and reflection starts only when the remaining observable budget
-  can fund the whole panel. A retry or reflection it cannot afford is stated rather than silently
-  skipped.
+- **A broken MODEL recovers only on the main model.** All strategies use the same SDK rule:
+  `failureKind: "provider"` or `"unknown-model"` permits ONE recovery attempt on the supervisor's
+  current model. This is explicitly authorized even when the initial member model was pinned or
+  saved earlier. It never borrows a peer's model or searches arbitrary providers, and skips recovery
+  when the main model is absent, already failed on that leg, or cannot fit the remaining child/token
+  budget. Other failures (`abort`, `timeout`, `contract`, agent/infrastructure errors) are terminal;
+  a stopped child never restarts. Strategy/flow engine construction disables the ordinary provider
+  reroute decorator so this is the first and only model switch. Every attempt contributes its usage
+  and child count; recovery is reported through `modelRecovery` and a visible warning. MAGI discloses
+  recovered cores in its ruling and keeps the recovered model during reflection rather than sending
+  a core back to its broken assignment. Recovery is a degraded-mode safeguard, not a preference:
+  sharing the main model can reduce reasoner diversity.
 - **The contract instructs as well as validates.** An engine that receives `outputContract` appends
   the format block (`contractInstructions`, derived from the same pinned def it validates against)
   to the member's task — a bare generic agent votes as reliably as one whose `.md` spells the JSON
@@ -167,8 +180,11 @@ nothing. Vote keys are normalised (`json-first`, `JSON_First`, `json first` →
 ## Param schema (declaration · validation · discovery)
 
 Each strategy declares its params as `params?: Record<string, StrategyParam>` where `StrategyParam =
-{ type: "string" | "number" | "boolean"; default?; doc }`. `knownParams(name)` (`strategy.ts`) exposes
-them. Two consumers:
+{ type: "string" | "number" | "boolean" | "agent"; default?; rosterIndex?; inheritRoster?; doc }`.
+Agent-valued defaults name real agents; `rosterIndex` identifies an omitted selector's roster default,
+and `inheritRoster` preserves a named selector's roster specialization where that strategy uses it.
+Picker preflight reads these declarations instead of guessing participants from prose. `knownParams(name)`
+(`strategy.ts`) exposes them. Two consumers:
 
 - 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:
@@ -184,19 +200,30 @@ The schema is for discovery and typo-catching, not enforcement: a strategy still
 Options reach a strategy's `input.params` from four surfaces, all overridable by the supervisor
 per-call:
 
-1. **Author default (static)** — a persona's `council: { strategy, roster, params }` (tool-driven) or
+1. **Author default (static)** — a persona's `council: { strategy?, roster?, members?, params? }` (tool-driven) or
    mandatory `orchestration: { mode, strategy, roster, params }` both carry a `params` map
    (`persona.ts` → `orchestrate.ts`). E.g. `council: { strategy: magi, params: { reflect: false } }`.
 2. **Borrowed persona profile (dynamic)** — `council({ persona: "magi", question: … })` resolves that
    installed persona's already-expanded `council:` block. The caller remains active and retains its
-   prompt, model, tools, and capability gates; only strategy/roster/params are borrowed. An unknown
+   prompt, model, tools, and capability gates; only strategy/roster/members/params are borrowed. An unknown
    persona or one without a usable council is a hard error, never a silent MAGI fallback.
-3. **Supervisor override (dynamic)** — the `council` tool accepts a per-call `strategy`, `roster`, and
-   `params`; the params **merge OVER** the selected (or active) persona's (`extension.ts`), so the LLM can pick
-   `{ aggregate: "unanimity" }` for one invocation, or switch strategy entirely
-   (`council({ strategy: "debate", … })`), without editing the persona.
+3. **Supervisor override (dynamic)** — the `council` tool accepts a per-call `strategy`, named
+   `roster`, temporary `members`, and `params`. Params merge over the selected (or active) profile when the strategy stays the same.
+   Switching strategy starts from that strategy's own defaults; only explicitly supplied per-call
+   params carry across the switch. For example, `{ aggregate: "unanimity" }` overrides the active
+   strategy for one invocation, while `council({ strategy: "debate", … })` does not inherit unrelated
+   profile params. Explicit unknown keys still produce a warning (leniently ignored), never a hard
+   failure.
 4. **Preset (reusable bundle)** — `council: { preset: <name> }` expands `presets/<name>.preset.json`
    into `{ strategy, roster, params }`; authored fields win, params merge (`expandCouncilPreset`).
+   Strategy/roster names are trimmed, and only those three preset fields are copied. Inline `members`
+   belong in the persona's validated council declaration or the tool call, not in preset JSON.
+
+An authored members-only declaration such as `council: { members: [reviewer, research] }` is valid
+and defaults to `magi`. Its params remain in effect when a call explicitly selects that same default
+strategy. Empty or malformed authored `members` are a configuration error, not an absent roster:
+the parser retains the diagnostic and council resolution fails instead of choosing a fallback panel.
+Correct or remove the field before calling that persona's council, even with per-call overrides.
 
 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:

package/docs/TELEMETRY.md

@@ -1,9 +1,23 @@
 # Telemetry wire contract
 
+Agent `waiting` is an explicit projection of a pending supervisor ask, read through the live
+engine steer handle. Ask delivery and settlement (reply, timeout or cancellation) refresh the
+projection; overlapping asks keep it waiting until the last one settles. Queued and terminal
+statuses retain precedence. The producer deduplicates unchanged projections and never infers
+waiting from tool arguments, output text or a quiet clock.
+
 Telemetry is a vendor-neutral v2 envelope. `producerId` and `producerVersion` identify the emitting plugin; `version` identifies the wire schema. `seq` is monotonic only within `(producerId, sessionId)`, and `id` is deduplicated within that same scope.
 
 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.
 
 JSONL compaction is atomic and hysteretic. It preserves the initial `instance.started` anchor and complete records; the configured byte limit is therefore a soft bound for an anchor plus one complete event. The `.previous` backup is recovered after an interrupted swap.
 
+Producer shutdown flushes its terminal event before releasing its writer lease. It does not join the shared background retention sweep, so unrelated stale sessions cannot delay this shutdown or reload. `flushRetention()` remains the explicit await for maintenance completion; cleanup errors still reach the non-fatal diagnostic sink.
+
+The pi-persona producer also applies a default 30-day age retention to its own valid v2 session groups; `retentionMs: 0` disables cleanup only, not writer leases. Cleanup is asynchronous after successful initialization and can be awaited with the producer's retention test seam. It strictly considers regular single-link logs plus recognized `.previous`/compaction scratch files beneath valid workspace IDs and this producer directory. Legacy data, foreign producers, malformed names, links, and unknown files are retained. Orphan backups/scratch and dead-marker-only groups are considered too; empty owned lease/producer/workspace directories are removed nonrecursively. The cutoff is exclusive and cleanup runs on activation, not on a wall-clock deletion schedule.
+
+Retention and writers coordinate cooperatively on the same host using unique empty `0600` marker files in `<session>.jsonl.leases`. Writers claim before recovery/sequence reads and keep the claim through terminal publication and flush. A pruner claims before checking writers and revalidates the whole old session group before unlinking. Marker names are immutable and unique to avoid stale-lock ABA. PID liveness is conservative: only `ESRCH` proves death; current, live, permission-denied, and unknown states protect data. This protocol cannot protect against historic writers that predate leases, nor non-cooperating processes; it is not an OS-level lock. A pre-upgrade process has no marker: its log is protected only while normal writes/heartbeats keep its mtime newer than the cutoff. That incidental mtime grace is not active-writer protection; let old sessions settle before reloading/upgrading when possible.
+
+Admission fails before recovery, sequence reads or emission when a live prune claim, unknown or unsafe lease marker, linked namespace/artifact, or filesystem error prevents a safe writer claim. The host warns and continues without telemetry for that activation. A failed attempt removes only its own marker and empty directories it created, nonrecursively; pre-existing data and leases remain intact. Cleanup and writer errors reach an always-enabled, non-fatal `onError` sink: a sanitized warning in interactive/RPC sessions, or stderr headless. A failing diagnostic renderer cannot interrupt the session. Retention deletes the sequence source: resuming an expired log starts a new retained stream at sequence 1, so it does not promise continuity with previously exported expired history.
+
 The flow consumer is a compatibility reader for v1 logs, which sit under `persona/flow` on an install the storage-root consolidation has migrated and under `pi-persona/flow` on one that predates it; the consumer reads both roots, because no producer writes v1 any more and dropping either name would silently lose history. It re-implements the parser rather than importing this one, and that duplication is deliberate: a consumer that ran the producer's parser could not validate against a buggy or hostile producer, and a vendor-neutral contract cannot make every future producer depend on pi-persona. What keeps the two honest is a conformance corpus — one byte-identical block of wire cases (accept, reject, and the exact projected payload) carried by `test/unit/telemetry/parity.test.ts` here and `test/parity.test.ts` there. The flow suite enforces that identity, comparing its block against the one in a sibling pi-persona checkout (or `PI_PERSONA_REPO`) and naming the first line that differs; it lives there and not here because flow may depend on pi-persona and never the reverse, and it skips — never fails — when no such checkout resolves, so flow stays testable standalone. A divergence therefore surfaces as a named line rather than as a silently dropped event. `TELEMETRY_PRODUCER_VERSION` is asserted against `package.json` in the same test: a release bumps both or fails. Any future shared package must preserve v1 read compatibility, v2 producer/session scoping, and the corpus.

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.15.2",
+  "version": "1.16.1",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
+  "author": "AeonDave",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/AeonDave/pi-persona.git"
@@ -18,12 +19,16 @@
   "keywords": [
     "pi-package",
     "pi-extension",
+    "pi-coding-agent",
     "pi",
-    "persona",
     "subagents",
     "orchestration",
     "multi-agent",
-    "supervisor"
+    "supervisor",
+    "async-agents",
+    "live-steering",
+    "cross-session",
+    "persona"
   ],
   "license": "MIT",
   "files": [
@@ -50,6 +55,7 @@
     "README.md",
     "AGENTS.md",
     "CHANGELOG.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
@@ -84,20 +90,21 @@
     }
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.19.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "0.85.1",
-    "@earendil-works/pi-ai": "0.85.1",
-    "@earendil-works/pi-coding-agent": "0.85.1",
-    "@earendil-works/pi-tui": "0.85.1",
+    "@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",
     "@types/node": "^22.20.4",
+    "fast-check": "^4.10.2",
     "tsx": "^4.23.13",
-    "typescript": "^5.9.3",
-    "typebox": "1.3.34"
+    "typebox": "1.3.34",
+    "typescript": "^7.0.2"
   },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.15.2/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.16.1/assets/banner.png",
     "video": "https://cdn.jsdelivr.net/gh/AeonDave/pi-persona@6655d281ce7965a75303dd704bd29db73db04070/assets/demo1.mp4",
     "extensions": [
       "./src/extension.ts"

package/src/bus/broker/paths.ts

@@ -25,7 +25,8 @@ export function brokerEndpoint(sessionId: string, home: string = homedir(), plat
 	// Session ids are uuidv7 (36 chars), so an ordinary-but-longish $HOME already pushes the
 	// readable name past sun_path; a hashed one is short and still derived purely from the
 	// session id, so host and client compute the same endpoint independently. The hashed form
-	// costs `$HOME` + 41 bytes, so a $HOME past 62 bytes stays out of reach either way —
+	// costs `$HOME` + 38 bytes, so a $HOME past 65 bytes stays out of reach either way —
 	// nothing under the user's own dir would fit.
-	return join(dir, `b-${createHash("sha1").update(sid).digest("hex").slice(0, 12)}.sock`);
+	// base64url packs 72 SHA-256 bits into the same 12 path bytes as the old hex suffix.
+	return join(dir, `b-${createHash("sha256").update(sid).digest("base64url").slice(0, 12)}.sock`);
 }

package/src/core/brief.ts

@@ -148,7 +148,7 @@ export function buildDelegationBrief(input: BriefInput): string | undefined {
 
 	const example = input.agents.some((a) => a.name === "operator") ? "operator" : (listed[0]?.name ?? "operator");
 	const delivery = input.asyncDefault
-		? "they run in the background and each result returns to you automatically as a follow-up — don't watch or poll a healthy leg; you're woken if one stalls or messages you, plus an occasional check-in to catch drift"
+		? "they run in the background and each result returns to you automatically as a follow-up — do useful independent work while children run; when only children remain, end your turn and let completion wake you. Do not monitor, poll, or automatically wait for all children (don't watch or poll a healthy leg). Join intentionally only when a result is needed before your next step; you're also woken if a child stalls or messages you, plus an occasional check-in to catch drift"
 		: "the call returns when they finish";
 	const callFields = [`agent: "${example}"`, `task: "<self-contained bounded task + success signal>"`];
 	if (input.requireBrief) {

package/src/core/nudge.ts

@@ -26,7 +26,7 @@
  */
 
 /** Tools that mean "the operator handed work off" — they end (reset) a by-hand run. */
-const HANDOFF_TOOLS = new Set(["delegate", "council"]);
+export const HANDOFF_TOOL_NAMES: ReadonlySet<string> = new Set(["delegate", "council"]);
 /** Supervision glue: collecting a delegated result (`intercom wait`/`result`) or arming a
  *  `timer` is neither hands-on work nor a hand-off. Their payloads are large by nature, so
  *  counting them would punish the exact behavior the nudge exists to encourage. They neither
@@ -138,7 +138,7 @@ export class DelegationNudge {
 	 */
 	observe(toolName: string, size: number, handoffSucceeded = true, failureText?: string): string | undefined {
 		if (GLUE_TOOLS.has(toolName)) return undefined;
-		if (HANDOFF_TOOLS.has(toolName)) {
+		if (HANDOFF_TOOL_NAMES.has(toolName)) {
 			if (!handoffSucceeded) {
 				const normalizedSize = Math.max(0, Math.floor(size));
 				const identity = failureText === undefined ? `size:${normalizedSize}` : fingerprintFailure(failureText);
@@ -204,7 +204,6 @@ export class DelegationNudge {
  */
 
 /** Tools whose result is a delegated child's report (where a surrender can surface). */
-const REPORT_TOOLS = new Set(["delegate", "council"]);
 
 /** Explicit surrender/blocked markers the operator + CTF protocols emit (operator.md). */
 const SURRENDER_MARKERS: readonly RegExp[] = [/\[BLOCKED\b/i, /\bFLAG:\s*UNKNOWN\b/i];
@@ -222,7 +221,7 @@ export class PersistenceNudge {
 	 * The SYNC path (a `delegate`/`council` tool_result the supervisor sees inline).
 	 */
 	observe(toolName: string, text: string): string | undefined {
-		if (!REPORT_TOOLS.has(toolName)) return undefined;
+		if (!HANDOFF_TOOL_NAMES.has(toolName)) return undefined;
 		return this.scan(text);
 	}
 

package/src/core/pi-compat.ts

@@ -3,10 +3,10 @@ import { createRequire } from "node:module";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-/** Oldest Pi this extension is written against. 0.83 made `message_update` delta-only (src/engine/stream.ts);
- *  older hosts are feature-detected where cheap but are not supported. Keep in sync with README.md;
+/** Oldest supported Pi host. The release is qualified against Pi 1.0's SDK and tool lifecycle;
+ *  pre-1.0 hosts are unsupported. Keep in sync with README.md;
  *  npm host peers use "*" because Pi supplies them through its extension loader. */
-export const MIN_PI_VERSION = "0.83.0";
+export const MIN_PI_VERSION = "1.0.0";
 
 function parse(v: string): [number, number, number] | undefined {
 	const m = /^(\d+)\.(\d+)\.(\d+)/.exec(v.trim());

package/src/engine/adapter.ts

@@ -12,7 +12,7 @@ import { type ContractDef, contractInstructions, parseAndValidate, pinContract,
 import { sanitizeDisplayLabel } from "../core/display-label.ts";
 import { assignedIdentityPrompt } from "../core/naming.ts";
 import { roleHint } from "../orchestration/roster.ts";
-import { type AgentRunSpec, isPositiveFiniteMs, type StrategyEngine } from "../orchestration/sdk.ts";
+import { type AgentRunSpec, isPositiveFiniteMs, type SteerFn, type StrategyEngine } from "../orchestration/sdk.ts";
 import type { AgentResult } from "../orchestration/types.ts";
 import { type ChildEngineOptions, type ChildRunSpec, runChildAgent } from "./child.ts";
 import { looksLikeProviderError } from "./errors.ts";
@@ -51,8 +51,10 @@ export interface EngineAdapterDeps {
 	/** Installed output-contract names (built-in `default` + files) for the self-correcting hint. */
 	listContracts?: () => string[];
 	/** Per-agent model override (e.g. a persona's configured ensemble models).
-	 *  Precedence: explicit spec.model > modelFor(agent) > the agent's own default. */
-	modelFor?: (agent: string) => string | undefined;
+	 *  Precedence: explicit spec.model > modelFor(agent, role) > the agent's own default. `role` is
+	 *  the on-the-fly role this run carries, when it has one, so a member's own assignment key
+	 *  (`agent#hash`) resolves ahead of the bare agent's. */
+	modelFor?: (agent: string, role?: string) => string | undefined;
 	/** Explicit thinking level appended to the child model (`model:level`) so it can't
 	 *  fall into a model's default "adaptive" mode, which some models reject. */
 	childThinking?: string;
@@ -107,7 +109,7 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 			onProgress?: (p: { output: string; tokens?: number; activity?: string; toolEvent?: ToolEvent }) => void,
 			callSignal?: AbortSignal,
 			/** Called once with a steer handle when the broker is on (in-process parity). */
-			onSteerable?: (steer: (text: string) => void) => void,
+			onSteerable?: (steer: SteerFn) => void,
 		): Promise<AgentResult> {
 			const cfg = deps.resolveAgent(spec.agent);
 			if (!cfg) return unknownAgentFailure(spec.agent, deps.listAgents?.() ?? []);
@@ -125,7 +127,7 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 					: spec.task;
 			const task = contractDef ? `${withSkills}\n\n${contractInstructions(contractDef)}` : withSkills;
 			const childSpec: ChildRunSpec = { task };
-			let model = spec.model ?? deps.modelFor?.(spec.agent) ?? cfg.model;
+			let model = spec.model ?? deps.modelFor?.(spec.agent, spec.role) ?? cfg.model;
 			// Append an explicit thinking level (model:level) unless one is already present —
 			// a child without it defaults to "adaptive", which some models reject.
 			if (model && deps.childThinking && !model.includes(":")) model = `${model}:${deps.childThinking}`;
@@ -178,7 +180,10 @@ export function makeEngine(deps: EngineAdapterDeps): StrategyEngine {
 				childOptions.isBlocked = () => deps.broker!.hasPendingAskFrom(handle!);
 				const broker = deps.broker;
 				const h = handle;
-				onSteerable?.((text) => broker.steerFrame(h, text));
+				const steer: SteerFn = Object.assign((text: string) => broker.steerFrame(h, text), {
+					isWaitingForSupervisor: () => broker.hasPendingAskFrom(h),
+				});
+				onSteerable?.(steer);
 			}
 
 			let child: Awaited<ReturnType<typeof runChildAgent>>;

package/src/engine/async.ts

@@ -320,7 +320,7 @@ export function dedupeRunsById(runs: AsyncRun[]): AsyncRun[] {
 
 /** One identity everywhere a tracked run is rendered: the launcher's codename when present,
  *  otherwise the agent type, with the already-shortened model appended once. */
-function runDisplayName(run: AsyncRun): string {
+export function runDisplayName(run: Pick<AsyncRun, "agent" | "label" | "model">): string {
 	const model = run.model === undefined ? undefined : sanitizeDisplayLabel(run.model, "model", 24);
 	if (model === undefined) return sanitizeDisplayLabel(run.label ?? run.agent);
 	const suffix = ` · ${model}`;
@@ -445,7 +445,7 @@ export function clipRunOutput(text: string, id: string, maxChars: number, label
 	return `${text.slice(0, headChars)}${marker}${tailChars > 0 ? text.slice(-tailChars) : ""}`;
 }
 
-export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs?: number }): string {
+export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs?: number; waitingForSupervisor?: ReadonlySet<string> }): string {
 	if (runs.length === 0) return "No async runs.";
 	const running = runs.filter((r) => r.status === "running").length;
 	const now = opts?.now;
@@ -460,7 +460,8 @@ export function buildPeekDigest(runs: AsyncRun[], opts?: { now?: number; stallMs
 		const head = `[${r.id}] ${name} — ${r.status}`;
 		if (r.status === "running") {
 			let line = `${head} (${r.progress.turns} turns, ${compactTokens(r.progress.tokens)} cumulative input + output tokens)`;
-			if (now !== undefined && stallMs !== undefined && stallMs > 0 && r.lastAdvanceAt !== undefined) {
+			if (opts?.waitingForSupervisor?.has(r.id)) line += " · waiting for supervisor";
+			else if (now !== undefined && stallMs !== undefined && stallMs > 0 && r.lastAdvanceAt !== undefined) {
 				const stalledFor = now - r.lastAdvanceAt;
 				if (stalledFor >= stallMs) line += ` ⚠ possibly stuck (no progress for ${Math.round(stalledFor / 1000)}s)`;
 			}
@@ -493,12 +494,17 @@ export class PeekWatcher {
 	private readonly reportedAt = new Map<string, number>();
 
 	/** The running legs that have NEWLY crossed the stall window since we last reported them. */
-	poll(runs: AsyncRun[], now: number, stallMs: number): AsyncRun[] {
+	poll(runs: AsyncRun[], now: number, stallMs: number, waitingForSupervisor: ReadonlySet<string> = new Set()): AsyncRun[] {
 		const live = new Set<string>();
 		const newlyStuck: AsyncRun[] = [];
 		for (const r of runs) {
-			if (r.status !== "running" || r.lastAdvanceAt === undefined) continue;
+			if (r.status !== "running") continue;
 			live.add(r.id);
+			if (waitingForSupervisor.has(r.id)) {
+				this.reportedAt.delete(r.id); // a live ask is not a stall; re-evaluate immediately when it settles
+				continue;
+			}
+			if (r.lastAdvanceAt === undefined) continue;
 			const prev = this.reportedAt.get(r.id);
 			if (prev !== undefined && r.lastAdvanceAt > prev) this.reportedAt.delete(r.id); // advanced ⇒ re-arm
 			if (stallMs > 0 && now - r.lastAdvanceAt >= stallMs && !this.reportedAt.has(r.id)) {
@@ -548,7 +554,7 @@ export function buildPeekAlert(stuck: AsyncRun[], opts: { now: number }): string
  * fast {@link buildPeekAlert} stall signal: it catches a leg going the WRONG way (not stalled, just
  * wrong) before it burns the budget, without waking the supervisor every tick.
  */
-export function buildCheckIn(runs: AsyncRun[], opts: { now: number; stallMs: number }): string {
+export function buildCheckIn(runs: AsyncRun[], opts: { now: number; stallMs: number; waitingForSupervisor?: ReadonlySet<string> }): string {
 	return (
 		`${buildPeekDigest(runs, opts)}\n\n` +
 		"Routine check-in — internal status update, not a new task: don't reply just to acknowledge unchanged progress. Continue your current " +