@aeondave/pi-persona 1.15.2 → 1.16.0

package/AGENTS.md

@@ -30,8 +30,18 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   `@earendil-works/pi-*`; never bundle copies.
 - npm publishes as `@aeondave/pi-persona`. Pi supplies the four `@earendil-works/pi-*` packages
   and `typebox`: keep them as `peerDependencies: "*"` with development-only copies, never runtime
-  dependencies. The supported host floor lives in `MIN_PI_VERSION` and the README. Keep the npm
+  dependencies. The supported host floor is Pi ≥ 1.0.0 (`MIN_PI_VERSION` and the README); Node.js
+  must be ≥ 22.19 to match that host. Keep the npm
   `files` allowlist explicit for docs/artwork, inspect `npm pack --dry-run`, and never publish drafts.
+- Supply-chain controls: pin every GitHub Action to a verified full commit SHA; keep top-level
+  token permissions read-only, grant write permissions only to the reporting job that needs them,
+  and disable persisted checkout credentials. Dependabot proposes updates; it does not auto-merge.
+  Keep the four Pi development packages in one update group so their APIs stay aligned.
+  Match `@types/node` to the oldest supported Node major, including in CI; upgrade them together.
+  Keep security overrides scoped to the affected development dependency and version; remove them
+  when upgrading Pi if the new dependency graph no longer needs them.
+  Run the full dependency audit (including development dependencies), tests and typecheck after
+  lockfile updates. A development override does not patch a user's installed Pi host.
 - **Cross-OS**: use Pi's spawn/kill/path/temp helpers (`getPiInvocation`, `killProcessTree`), not raw
   `child_process`. Windows kill goes straight to `taskkill /F /T`; always attach an `error` listener.
 - Two engines behind the `StrategyEngine` seam: **InProcessEngine** (`engine/inproc`,
@@ -78,6 +88,11 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   policy (OpenAI-family → OpenAI providers; Claude-family → the native Claude provider). A caller may
   explicitly opt a pinned run into cross-provider recovery. Only `failureKind === "provider"` reroutes;
   abort/timeout/contract/unknown/agent are terminal.
+  Strategy/council/flow runs disable that provider search and use SDK-level main-only recovery:
+  `provider`/`unknown-model` may retry ONCE on the current supervisor model, including a saved or
+  inline-pinned choice (explicit user-authorized exception). Never borrow a peer model, never restart
+  a stopped/timed-out/contract-failed leg, and charge each attempt to child/token limits and usage.
+  Ordinary delegate pins remain strict. Recovery must remain visible in metadata/UI and MAGI rulings.
   Engines classify the cause on the `AgentResult` (`failureKind` + resolved `modelUsed`); keep those
   set when you touch `inproc.ts`/`adapter.ts` or the fallback silently stops working.
 - **Fork-bomb guard**: children run with env `PI_PERSONA_DISABLE=1` so pi-persona self-disables inside
@@ -93,11 +108,13 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   blind retry loops are stopped by the runtime `DelegationLedger` (an identical agent+model+task
   delegation that failed twice is vetoed before it spawns).
 - Dynamic sub-agents: `delegate` shapes an on-the-fly specialist with `role` (extra system prompt,
-  appended to the agent's own) + `skills` — prompt-level only, capabilities stay the gate. Async runs
-  are joined with intercom `wait` (bounded ≤ the bus-ask timeout; collected results are discarded from
-  the pending completion follow-up so they are never double-reported). In interactive sessions
-  `delegate` is background-by-default (`sync: true` opts a call out; headless `pi -p` defaults to
-  sync so the single turn carries the result).
+  appended to the agent's own) + `skills` — prompt-level only, capabilities stay the gate. Intercom
+  `wait` snapshots already-settled reports by default in interactive/RPC sessions; `sync: true` opts
+  into a bounded join (≤ the bus-ask timeout). Headless waits default to joining; `sync: false` takes
+  a snapshot. Collected reports are discarded from the pending completion follow-up so they are
+  never double-reported; snapshots leave running children active. In interactive sessions `delegate`
+  is background-by-default (`sync: true` opts a call out; headless `pi -p` defaults to sync so the
+  single turn carries the result). An explicit `async` flag takes precedence over `sync` and the default.
   Message ids and run ids are separate: `intercom message { messageId }` retrieves retained bus
   text, `intercom result { to: runId }` retrieves a settled run. Both explicit and automatic inbox
   drains retain bounded history (256 messages / 256,000 body characters). Ask settlement clears
@@ -120,6 +137,10 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   fills with every leg's body, failures included), while `renderCompletion` scans only `status: "done"`
   runs. A background leg that FAILED while emitting `[BLOCKED]` therefore gets the failure block but no
   persistence note — deliberate (see the `renderCompletion` doc comment), not a bug to "fix" silently.
+  Nested reports from codemode's `ctx.executeTool` retain bounded provenance through Pi's explicit
+  `parentToolCallId`; never infer nesting from the call-id string. Only an outer result that relays
+  the surrender marker gets the note/card. Nested programmatic data is never patched with a reminder,
+  and discarded reports never generate an invisible one. Relay state clears at turn/session settlement.
   `config.nudge` (`PI_PERSONA_NUDGE=off`) silences all of it: the `tool_result` hook (the by-hand
   reminder and the sync-result persistence one) and both `renderCompletion` call sites, which take
   their `scan` through the same gate — so a background/`intercom wait` report carries no note either.
@@ -190,6 +211,9 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   persistence; `src/extension/identity.ts` registers `agent_name` and the pre-name context bootstrap.
   Exocom uses that same state. A delegate's optional `AgentRunSpec.name` is leader-assigned
   display identity, propagated to both engines without changing routing ids.
+  Async launch/control cards use that alias, with persisted tool-result snapshots for history.
+  Keep run IDs for routing/diagnostics, not primary display identity; disambiguate duplicate aliases.
+  Steering cards preview the accepted message and expose all of it with Pi's expand-key binding.
   Runtime metadata guidance belongs in the stable supervisor system prompt, not a new user-like
   acknowledgement message. Keep initial setup/actionable asks working, preserve user-visible history,
   and never re-inject a chosen identity. Progress `tokens` is cumulative input/output usage, not live

package/CHANGELOG.md

@@ -6,6 +6,88 @@ used in its [GitHub releases](https://github.com/AeonDave/pi-persona/releases).
 
 ## [Unreleased]
 
+## [1.16.0](https://github.com/AeonDave/pi-persona/releases/tag/v1.16.0) - 2026-10-03
+
+### Compatibility
+
+- Require Pi ≥ 1.0.0 and Node.js ≥ 22.19. Update the development cohort to Pi 1.0's four coordinated
+  host-package pins and qualify its SDK and tool lifecycle. Pre-1.0 Pi hosts are no longer supported;
+  the host packages and TypeBox remain wildcard peers supplied by Pi, not bundled runtime copies.
+- Update the live control harness to use Pi 1.0's session `modelRuntime` through the public
+  `ModelRegistry` facade instead of the removed session registry property.
+- An authored `council.members` field is now validated. Older malformed fields that were ignored
+  must be corrected or removed; council calls fail with the field diagnostic instead of selecting
+  an unrelated fallback panel.
+
+### Fixed
+
+- Reserve mandatory downstream child slots before optional model recovery in `map`, `pipeline`,
+  `critic-loop`, and `council-rounds`. Provider outages no longer spend the slots needed by later
+  workers, verifiers, steps, or rounds and turn completed work into a run-fatal admission error.
+- Pass live supervisor-ask state to the `intercom peek` tool, including untargeted peeks; a child
+  waiting for its supervisor is not reported as stuck. Collapsed steer receipts identify the run.
+- Honor members-only council profiles for active and explicitly selected personas, including their
+  params when MAGI is selected explicitly as the same default strategy. Evaluate each configured
+  agent-model lookup once.
+- Carry persistence checkpoints through nested codemode reports when their `[BLOCKED]`/`FLAG:
+  UNKNOWN` marker is relayed to the model. Suppressed nested output stays unchanged; only the outer
+  visible result receives the checkpoint and its expandable card.
+- Surface telemetry cleanup/write diagnostics without requiring debug mode; diagnostics remain
+  non-fatal. Failed admission removes only the empty directories created by that attempt.
+- Release a telemetry writer lease after its terminal writes finish without waiting for the shared
+  retention sweep over unrelated sessions; explicit maintenance joins remain available.
+- Harden the exported council-preset expansion boundary with normalized strategy names and the
+  same strategy/roster/params allowlist as the JSON loader; validated authored members remain intact.
+- Resolve live tree and telemetry model labels for auxiliary actors through the same role-specific
+  participants as the picker, including inline model pins and repeated SDK keys. Ambiguous short
+  role hints omit an uncertain model rather than attributing a different participant's choice.
+
+### Changed
+
+- Make general council guidance proportionate while preserving MAGI and Judge's specialized focus;
+  all eleven strategies remain available through the same tool. Add ephemeral inline council members
+  and specialized external actors without creating persona/team files.
+- Include role-specific members and external arbiters in model selection; respect configured models
+  and remember prompts per participant rather than suppressing later teams for the whole persona.
+- Recover model/provider failures across strategies and flows once on the supervisor's current model,
+  including unavailable saved or pinned choices. Remove MAGI's peer-model substitution; report the
+  switch, account both attempts, and preserve child/token limits and cancellation.
+- Use worker aliases in async launch cards and targeted Intercom call headers, matching the live tree.
+  Persist display identity in tool results so history remains readable after reload or tracker eviction;
+  routing still uses run IDs, with a secondary ID shown when aliases collide.
+- Show the accepted steering message as a compact preview, with Pi's expand-key hint for the full
+  message and diagnostic run ID. Replace repetitive soft-request/cancellation boilerplate with a
+  concise queued receipt; steering remains a request, not proof of execution or cancellation.
+- Make context-burn checkpoints aware of Pi's nested-tool metadata: raw inner results do not
+  consume the model-visible output budget or receive invisible reminders. Permission gates,
+  telemetry and genuine successful hand-off resets still apply inside codemode.
+- Show an immediate async completion banner with the worker's display name, including successful
+  runs. The semantic report still arrives once through the idle-gated completion path, and a failed
+  UI notification cannot swallow it.
+- Replace the child watchdog test's load-sensitive kill-latency assertion with an observed blocked →
+  released → idle-timeout barrier; preserve the two intentional Windows-only skips.
+- Clarify that automatic background completion follow-ups and end-turn guidance are the intended
+  async default: continue independent work, and do not monitor or join all workers when they are the
+  only remaining work. `intercom wait` now snapshots without blocking by default in interactive/RPC
+  sessions; `sync: true` opts into its bounded join, while headless remains blocking by default and
+  `sync: false` opts out. Snapshots collect only already-settled reports, leaving running work active.
+  Queued steering does not preempt an explicitly blocking join. A real Pi 1.0 SDK test with a local faux provider characterizes steering becoming
+  dormant when delayed input hooks outlast the active run. No unsafe input-triggered join abort ships.
+- A council call that switches strategy no longer inherits unrelated profile params; params continue
+  to merge when the selected strategy is unchanged, and unknown explicit keys still warn.
+- Show live supervisor asks as `waiting for supervisor`, rather than stalled, in the tree, F9 and
+  peek; refresh council parent clocks on child progress. A waiting worker becomes eligible for
+  stall detection again when its ask settles. Steering an already-settled run points to its result.
+- Add age-based telemetry cleanup with a 30-day default; see
+  [`docs/TELEMETRY.md`](docs/TELEMETRY.md) for the retention contract.
+- Reuse one tree snapshot per F9 list redraw for rows, selection and waiting state; remove an
+  unreachable delegate-title branch and distinguish event liveness from proof of useful progress.
+- Align the README and technical guides on async snapshots/joins, steering delivery, model-selection
+  precedence, members-only councils, and automatic `map` verifier headroom.
+
+After updating, let active workers settle and restart Pi (or use `/reload`). `/persona reload`
+refreshes definitions, not extension code. Existing custom personas and provider pins are preserved.
+
 ## [1.15.2](https://github.com/AeonDave/pi-persona/releases/tag/v1.15.2) - 2026-09-28
 
 ### Distribution

package/README.md

@@ -4,9 +4,12 @@
   <img src="assets/banner.png" alt="pi-persona — supervised multi-agent orchestration for Pi">
 </p>
 
+[![CI](https://github.com/AeonDave/pi-persona/actions/workflows/test.yml/badge.svg?branch=main)](https://github.com/AeonDave/pi-persona/actions/workflows/test.yml) [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/AeonDave/pi-persona/badge)](https://scorecard.dev/viewer/?uri=github.com/AeonDave/pi-persona) [![npm version](https://img.shields.io/npm/v/@aeondave/pi-persona?logo=npm)](https://www.npmjs.com/package/@aeondave/pi-persona) [![License](https://img.shields.io/github/license/AeonDave/pi-persona)](LICENSE)
+
 **Give Pi a supervised team.**
-`pi-persona` brings supervised multi-agent orchestration to [Pi](https://github.com/earendil-works/pi):
-async workers, live steering, cross-session collaboration, and switchable personas.
+`pi-persona` adds supervised multi-agent orchestration to [Pi](https://github.com/earendil-works/pi):
+async workers, live steering, cross-session collaboration, and switchable personas. It builds on
+Pi's native SDK and tool hooks; the extension adds worker supervision and coordination.
 Describe the outcome. A supervisor delegates work, gathers results, and checks the outcome;
 you can inspect workers, redirect them, or stop a run while it is in progress.
 
@@ -14,7 +17,7 @@ you can inspect workers, redirect them, or stop a run while it is in progress.
 
 ## Install
 
-Requires **Pi ≥ 0.83**, **Node.js 22+**, and **Git**. Configure a model provider in Pi first.
+Requires **Pi ≥ 1.0.0**, **Node.js ≥ 22.19**, and **Git**. Configure a model provider in Pi first.
 
 Run in your terminal:
 
@@ -36,9 +39,9 @@ your customizations.
 | Install option | Command |
 |---|---|
 | This project only | `pi install -l npm:@aeondave/pi-persona` |
-| Pin this release | `pi install npm:@aeondave/pi-persona@1.15.2` |
+| Pin this release | `pi install npm:@aeondave/pi-persona@1.16.0` |
 | Update an unpinned install | `pi update npm:@aeondave/pi-persona` |
-| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.15.2` |
+| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.16.0` |
 
 Restart Pi after updating. For a pinned install, install the new version or tag explicitly.
 If switching from a Git install, remove that source first with
@@ -69,8 +72,12 @@ For example, specialists can investigate code paths, tests, and the API contract
 Their findings return to the **same supervisor**, which integrates them, verifies the fix, and reports
 the outcome. This is one possible workflow, not a fixed pipeline; dependent steps run in order.
 
-Interactive delegation runs in the background by default. The supervisor gathers results and keeps
-you informed; you can inspect or redirect a worker at any point.
+Interactive delegation runs in the background by default. Results return automatically when the
+supervisor is free; you can inspect or redirect a worker at any point.
+
+Launch and control cards show the worker's name. Steering receipts preview the message sent;
+expand with `Ctrl+O` (the default binding) to read it in full. A queued message is not proof that
+the worker has acted on it.
 
 | Key or command | Action |
 |---|---|
@@ -135,6 +142,13 @@ everyday coding, or choose one for the work ahead.
 These are editable starting points. Browse the bundled [personas](personas) and [worker agents](agents),
 or read the [practical guide](docs/EXPERIENCE.md) for help choosing a workflow.
 
+Strategies are not restricted to the similarly named persona: `council` can select `judge`, `magi`,
+`debate`, `critic-loop`, or another installed shape when it adds value. Temporary `members` allow
+custom role-based groups without team files. Model selection includes external arbiters. In councils
+and flows, a provider failure or unavailable model can recover once on the supervisor's model, with
+the switch visible and both attempts accounted; ordinary delegates keep explicit provider pins strict.
+See [the reference](docs/REFERENCE.md) for an inline council example and recovery limits.
+
 ## Make it yours
 
 Edit installed personas and agents in `~/.pi/agent/persona/agents/`, or add project-specific
@@ -169,4 +183,9 @@ npm test
 ```
 
 Pi loads the TypeScript extension directly; there is no build step.
-See [AGENTS.md](AGENTS.md) for contribution conventions. Licensed under [MIT](LICENSE).
+The [CI workflow](https://github.com/AeonDave/pi-persona/actions/workflows/test.yml) runs strict
+typechecking, dependency auditing and the test suite on Linux and Windows. The OpenSSF badge links to the project's
+scored supply-chain checks; it is not a certification that the code is free of vulnerabilities.
+
+See [AGENTS.md](AGENTS.md) for contribution conventions and the [security policy](SECURITY.md)
+for private vulnerability reporting. Licensed under [MIT](LICENSE).

package/SECURITY.md

@@ -0,0 +1,42 @@
+# Security Policy
+
+## Supported versions
+
+Security fixes target the latest published version of
+[`@aeondave/pi-persona`](https://www.npmjs.com/package/@aeondave/pi-persona).
+Older versions do not have a guaranteed backport policy. Check the
+[release notes](https://github.com/AeonDave/pi-persona/releases) for fixes and
+upgrade instructions. Keep your Pi host and Node.js runtime updated as well.
+
+## Reporting a vulnerability
+
+Use [GitHub private vulnerability reporting](https://github.com/AeonDave/pi-persona/security/advisories/new).
+Do not open a public issue with exploit details, credentials, private session
+logs, or other sensitive material. Ordinary bugs can use the public issue tracker.
+
+Include the affected package version or commit, Pi and Node.js versions, operating
+system, relevant configuration, expected security boundary, actual behavior, and
+a minimal reproduction with synthetic data. Explain the impact and any safe
+workaround you have verified. Do not test against other users' sessions or systems
+without their permission.
+
+Follow-up and disclosure coordination happen in the private advisory. This is a
+maintainer-run project, with no guaranteed response or remediation deadline and
+no paid bug bounty. Agree on public disclosure after triage so users can receive
+a fix or mitigation before exploit details are published.
+
+## Security boundaries
+
+Pi extensions and installed persona/agent definitions are trusted local code and
+configuration, not an OS sandbox. Capability checks and Exocom's cooperative file
+claims do not isolate a malicious local process. A workspace join code is a
+same-host routing reference, not an authentication secret. See the
+[architecture](docs/ARCHITECTURE.md) for the actual trust boundaries.
+
+Reports of capability bypasses, broker/Exocom trust violations, unsafe handling of
+untrusted worker output, or unintended disclosure of session data are welcome.
+Use synthetic credentials and payloads in reproductions.
+
+The npm package uses Pi-provided peer dependencies rather than shipping another
+Pi runtime. Development lockfile fixes do not update an installed user's host;
+host vulnerabilities must also be addressed by updating Pi itself.

package/docs/ARCHITECTURE.md

@@ -54,6 +54,10 @@ rejected with the run id to wait on, so a later call cannot slip past the in-bat
 - **L3 — flow file.** `flows/<name>.flow.json` composes strategies into a resumable DAG.
 
 You climb only when you want determinism, structure, or reuse. Nothing forces the higher tiers.
+The `council` tool is a gateway to all installed strategies, not a universal instruction to vote on
+routine work. Choose a strategy when its topology adds value; MAGI and Judge retain their specialized
+persona focus. A caller can supply ephemeral `members` with inline roles/models/skills instead of a
+named team, without persisting a team or switching personas.
 
 ## Binding invariants (I1–I7)
 
@@ -193,7 +197,8 @@ engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain
   constrained-turn allowlist), `install.ts` (the feature's composition adapter: session-scoped plane +
   ledger + wait/tool/hook wiring).
 - **`src/telemetry/`** — a generic, versioned observer/export contract for future plugins: projected
-  lifecycle metadata only, never an agent-message router or control surface.
+  lifecycle metadata only, never an agent-message router or control surface. See
+  [`TELEMETRY.md`](./TELEMETRY.md) for privacy, retention, writer leases, and shutdown behavior.
 - **`src/persona/`** — identity: `persona.ts` (parse + `expandCouncilPreset` + `composeSystemPrompt`),
   `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts`, `state.ts` (last-selected persona),
   `spine.ts` (the shared behavioral layer's SOURCE resolution — docs/SPINE.md; composition sits in
@@ -282,6 +287,19 @@ prevents an explicitly selected OpenAI or native Claude leg from silently moving
 provider. (`"verification"` is a further terminal value that never appears on an `AgentResult` — see
 `map`'s `verify` param in [`docs/STRATEGIES.md`](./STRATEGIES.md).)
 
+Strategy/council/flow runs use a different, explicitly authorized recovery policy: the selected model
+is tried first without arbitrary provider reroutes, then `makeSDK` may retry a `provider` or
+`unknown-model` failure ONCE on the supervisor's current model. This main-only exception also applies
+to saved and inline-pinned assignments; ordinary delegate provider pins remain strict. Missing main
+models, repeated same-model attempts, stop/timeout/contract/agent/infrastructure failures, and exhausted
+child/token budgets do not recover. Both attempts are accounted, and a warning plus result metadata
+identify the switch. A per-role model assignment can supplement the legacy per-agent assignment;
+preflight model selection includes external arbiters and other declared agent-valued parameters.
+Live tree and telemetry labels use those participant identities for auxiliary actors too, with
+inline model pins taking precedence. If distinct full roles share a short display hint, the display
+keeps the hint (with `#N` suffixes for repeated node keys) but omits the uncertain model label rather
+than borrowing another role's choice. Routing still resolves the full role key, not the display hint.
+
 ### MCP (and other `session_start`-scoped extensions) in sub-agents
 
 **A sub-agent does NOT share the supervisor's MCP session, and an in-process sub-agent gets NO MCP at
@@ -403,7 +421,9 @@ never simultaneously a telemetry event, a routed message, and a UI source of tru
 - **ProgressView** — a derived, read-only UI view computed *from* EngineEvents. Never authored, never
   a source of truth. The `f9` agent tree and `peek` digest are ProgressViews.
 
-Steering is always a Bus action; the peek digest is always a read-only ProgressView.
+Steering is a supervisor-to-child control action, distinct from semantic Bus messages; requesting
+steering does not establish that an active blocking join has been interrupted. The peek digest is
+always a read-only ProgressView.
 
 External telemetry is not a fourth communication plane: it is a generic observer/export contract that
 future plugins may consume or produce, not an exclusive pi-persona protocol. It observes projected
@@ -459,6 +479,12 @@ for the supervisor and for explicit retrieval; the default TUI projection is del
   failed legs first, a failed council/flow card leads with the cause in its title, and an
   `intercom wait` card leads with the `N settled — X done, Y failed` tally (per-leg causes sit in the
   body, below the preview cut, so `wait`'s own success doesn't get a `failed` prefix);
+- async launch cards and targeted Intercom call headers use the worker's canonical alias/model,
+  matching the tree rather than promoting its routing ID to display identity. Launch/control receipts
+  persist identity snapshots for history rendering; aliases never become routing keys. Colliding
+  aliases carry a secondary ID, and legacy receipts without a recoverable name retain their ID fallback.
+  Accepted steering receipts retain the exact sent message: collapsed cards preview it, expansion
+  shows all sanitized text and the diagnostic ID. A queued receipt does not prove the worker acted;
 - follow-up cards (`pi-persona`, exocom) retain their complete semantic content but render a bounded
   preview until expanded; terminal escape/control sequences are removed from the visible projection;
 - the sticky agent and exocom widgets have fixed row budgets — F9/`/agents` and paginated
@@ -606,15 +632,29 @@ a local process able to modify that directory is already inside the trust bounda
 
 - **sync** — the supervisor actively blocks on the delegate/strategy call (results still stream); no
   idle/peek/steer.
-- **async** — the supervisor returns control and goes **idle, spending no tokens**, until woken by an
-  **event** (a child's `contact_supervisor`: a `decision`/`interview` blocks for a reply, `progress` is
-  one-way) or the **peek watchdog**, which fires while async children run but stays SILENT unless there
-  is something to act on — a healthy background run never interrupts. It surfaces on two independent
+- **async** — interactive delegation is background-first; headless execution remains synchronous
+  by default. The prompt/runtime guidance is to continue independent work and, when only background
+  children remain, end the turn for automatic completion follow-ups rather than monitor or join the
+  whole batch. `intercom wait` collects a snapshot without blocking by default in interactive/RPC
+  sessions; settled results are reported and running children continue. Use `sync: true` for an
+  intentional bounded join. Headless sessions preserve the blocking default; `sync: false` requests a
+  snapshot. A snapshot does not wait, start timers/input hooks, or cancel children. Queued steering
+  does not release an explicitly active join. Input-triggered join interruption is
+  deliberately not implemented: a real Pi 1.0 SDK characterization shows steering can remain dormant
+  if delayed input hooks outlast the active run; no supported post-admission ordering guarantee
+  has been established. The supervisor otherwise returns control and
+  goes idle until a wake; the **peek watchdog** fires while async children run but stays SILENT unless
+  there is something to act on — a healthy background run should not interrupt. It surfaces on two independent
   signals: a **fast** wakeup (`PI_PERSONA_PEEK_MS`, ~30s, `0` disables) when a child NEWLY crosses the
   `STALL_FLAG_MS` (90s) stall window (a focused *possibly stuck* alert, framed patience-first — ask the
   leg, don't probe its environment) or messages the supervisor; and a **slow routine check-in**
   (`PI_PERSONA_CHECKIN_MS`, ~5 min, `0` disables) delivering the compact ProgressView digest — never
-  full transcripts — so the supervisor can catch a leg going off-track early. Both let an idle
+  full transcripts — so the supervisor can catch a leg going off-track early. Live supervisor asks
+  are derived from the exact engine handle's optional `isWaitingForSupervisor` predicate: tree/F9/peek
+  show waiting, and the watchdog suppresses false stalls until the ask settles. Parent clocks advance
+  with child engine events (liveness, not proof of useful work); parents are waiting only when every
+  live descendant branch is waiting.
+  Both let an idle
   supervisor steer/stop a wedged or drifting child even with NO completion fired; the enforcing
   backstop is the engines' hard wall-clock cap (above). The full digest is also on demand via `/peek`.
   Progress tokens are labelled **cumulative input/output**, not context occupancy; cache-read/write
@@ -649,6 +689,11 @@ a persona directive lives at the TOP of the prompt and its pull decays as recent
     only `status === "done"` runs by design — a failed background/`wait` leg already gets a failure
     block, so a `[BLOCKED]` marker there doesn't also get the persistence note. Same marker, same leg,
     different counterweight depending on how it was collected.
+    Nested calls through codemode's `ctx.executeTool` leave their programmatic result untouched.
+    Pi's explicit `parentToolCallId` supplies the parent identity; call-id string shapes are never
+    used to infer nesting. A bounded set of parent call ids carries report provenance through wrappers
+    only while their output relays a surrender marker; the outer model-visible result alone gets the
+    note/card. Suppressed reports produce neither, and turn/session settlement clears abandoned relay state.
   - **The off switch covers every path.** `PI_PERSONA_NUDGE=off` silences DelegationNudge entirely and
     PersistenceNudge on every collection path (sync result, background notifier, `intercom wait`).
 

package/docs/EXPERIENCE.md

@@ -40,20 +40,36 @@ ask for a monitor. Pi runs a small event-producing program and brings the result
 supervisor is free. Keep the session open, and cancel a watch when its purpose ends. See
 [time and event wakes](MONITORS.md) for examples and limits.
 
-- **F9** opens the agent tree. Every running row shows its elapsed time and switches to `⚠ stalled
-  <duration>` once it has gone 90 seconds without progress — the same threshold behind the
-  supervisor's stall alert. Enter opens a selectable worker's output; `s` sends a course correction;
+- **F9** opens the agent tree. Queued rows have not started their clocks. Live supervisor asks show
+  `waiting for supervisor`, not a stall; running rows otherwise show elapsed time and switch to
+  `⚠ stalled <duration>` after 90 seconds without progress — a suspicion, not proof of a deadlock.
+  Council parent clocks refresh on child engine events; that indicates liveness, not useful work.
+  A parent is waiting only when all its live descendant branches are waiting. Enter opens a selectable worker's output; `s` sends a course correction;
   `x` requests cancellation and appears only when the run can actually be stopped, marking the row
   `stopping…` at once; a stop that can't be applied says so instead of doing nothing. Escape goes
   back or closes the panel.
 - **`/peek`** gives a compact progress view. A quiet worker is a reason to inspect its last
   progress and current activity, not to launch a duplicate immediately.
 - **Background results arrive automatically.** A supervisor can continue independent work while
-  they run. `intercom wait` joins results when the next step depends on them.
+  they run. When only background workers remain, end the turn and let completion follow-ups return
+  their results; do not monitor or poll healthy workers or automatically join the whole batch.
+  `intercom wait` snapshots immediately by default in interactive/RPC sessions; use `sync: true` for
+  an intentional bounded join when the next step depends on those results. Headless waits remain
+  blocking by default; pass `sync: false` for a snapshot.
 - **Answer a waiting worker before joining it.** A coaching worker may need a decision from its
   supervisor before it can finish. An unanswered question is actionable work.
 - **Steering is a request.** Check the subsequent output to see whether the worker incorporated
-  it. Check the terminal result after requesting cancellation; changes already made are not undone.
+  it. In-process workers can receive guidance mid-run; child-engine workers (including MCP/worktree
+  runs) receive it as a queued follow-up. Neither promises to interrupt arbitrary tool work, and
+  steering does not preempt an explicitly blocking `intercom wait`. End the supervisor turn rather
+  than join merely to idle. Check the terminal result after requesting cancellation; changes already
+  made are not undone.
+
+Launch cards and targeted Intercom calls show the same worker alias as the live tree. A steering
+receipt previews the message that was actually queued; expand it (`Ctrl+O` by default, or your
+configured key) to read the full message and diagnostic run ID. Aliases are display names, not
+addresses: tools still route by run ID, and duplicate aliases show a secondary ID to distinguish them.
+Saved launch/control receipts keep their display names even after the runtime tracker is gone.
 
 A truncated message includes a message id. The supervisor can retrieve its retained body with
 `intercom { action: "message", messageId: "m1" }`. A worker's final report has a run id instead:

package/docs/README.md

@@ -1,6 +1,8 @@
 # pi-persona documentation
 
 This folder contains the long-form documentation that defines how the project is designed and run.
+It follows the current checkout; consult the [changelog](../CHANGELOG.md) for the release that
+introduced a behavior. An `Unreleased` entry is not yet part of a published release.
 
 ## Canonical docs
 

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.