@aeondave/pi-persona 1.15.2 → 1.16.0

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

@@ -6,4 +6,12 @@ The pi-persona producer writes semantic projections under `telemetry/v2/<workspa
 
 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,6 +1,6 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.15.2",
+  "version": "1.16.0",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -50,6 +50,7 @@
     "README.md",
     "AGENTS.md",
     "CHANGELOG.md",
+    "SECURITY.md",
     "LICENSE"
   ],
   "scripts": {
@@ -84,20 +85,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.0/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 " +

package/src/engine/inproc.ts

@@ -30,7 +30,7 @@ import { assignedIdentityPrompt } from "../core/naming.ts";
 import { attributeInbound } from "../core/fence.ts";
 import { isThinkingLevel, type ThinkingLevel } from "../core/types.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 { looksLikeProviderError } from "./errors.ts";
 import { nextChildHandle } from "./handles.ts";
@@ -94,8 +94,10 @@ export interface InProcessDeps {
 	cwd: string;
 	/** Pi's global agent dir (~/.pi/agent); defaults to cwd if omitted (tests). */
 	agentDir?: string;
-	/** Per-agent model override (e.g. a persona's configured ensemble models). */
-	modelFor?: (agent: string) => string | undefined;
+	/** Per-agent model override (e.g. a persona's configured ensemble models). `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;
 	/** The session/loader model — the last-resort fallback when an agent declares none
 	 *  (the child engine gets this for free from `pi -p`'s default; inproc must pass it). */
 	defaultModel?: string;
@@ -319,10 +321,11 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 			const requestedDef = requestedContract ? pinnedDef(requestedContract) : undefined;
 			if (requestedContract && !requestedDef) return unknownContractFailure(spec.agent, requestedContract, deps.listContracts?.() ?? []);
 
-			const ref = spec.model ?? deps.modelFor?.(spec.agent) ?? cfg.model ?? deps.defaultModel;
+			const picked = spec.model ? undefined : deps.modelFor?.(spec.agent, spec.role);
+			const ref = spec.model ?? picked ?? cfg.model ?? deps.defaultModel;
 			const model = resolveModel(deps.modelRegistry, ref);
 			if (!model) {
-				const src = spec.model ? "spec" : deps.modelFor?.(spec.agent) ? "agent picker" : cfg.model ? "agent config" : "default";
+				const src = spec.model ? "spec" : picked ? "agent picker" : cfg.model ? "agent config" : "default";
 				// Make the failure self-correcting: name a few real registry refs (nearest
 				// matches first) so the supervisor's retry can pick a valid model at once.
 				const all = deps.modelRegistry.getAll().map((m) => `${m.provider}/${m.id}`);
@@ -681,7 +684,9 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 
 				// Steering: the in-process engine can inject a user message into the running
 				// agent — the v0.4 payoff the one-shot child engine can't do.
-				onSteerable?.((text) => {
+				const waitingHandle = childHandle;
+				const waitingBus = deps.bus;
+				const steer: SteerFn = Object.assign((text: string): boolean => {
 					if (!steerable) return false;
 					const trimmed = text.trim();
 					if (!trimmed) return false;
@@ -691,7 +696,10 @@ export function makeInProcessEngine(deps: InProcessDeps): StrategyEngine {
 					} catch {
 						return false;
 					}
+				}, {
+					isWaitingForSupervisor: () => waitingHandle !== undefined && waitingBus?.hasPendingAskFrom(waitingHandle) === true,
 				});
+				onSteerable?.(steer);
 
 				// Delivery bridge: bus messages addressed to this child are steered into its live
 				// session as fenced, attributed user turns — attribution stays OUTSIDE the fence so

package/src/extension/engine.ts

@@ -9,6 +9,7 @@ import type { RunLimits } from "../core/capabilities.ts";
 import type { PiPersonaConfig } from "../core/config.ts";
 import { isThinkingLevel } from "../core/types.ts";
 import { personaModels, type PersonaConfigStore } from "../persona/config-store.ts";
+import { participantKey } from "../persona/model-participants.ts";
 import type { PersonaController, PersonaHost } from "../persona/controller.ts";
 import { type EngineAdapterBroker, type EngineAdapterDeps, makeEngine } from "../engine/adapter.ts";
 import { captureStatus, diffStatus, findGitRoot, renderChangeReport } from "../engine/change-report.ts";
@@ -50,7 +51,17 @@ export interface BuildEngineDeps {
 	gitExec?: GitExec;
 }
 
-export type BuildEngine = (signal?: AbortSignal, onProgress?: (s: ProgressSnapshot) => void, engOpts?: { async?: boolean }) => StrategyEngine;
+export type BuildEngine = (
+	signal?: AbortSignal,
+	onProgress?: (s: ProgressSnapshot) => void,
+	engOpts?: {
+		async?: boolean;
+		/** Wrap the engine in `withModelFallback` (default true). Strategy/flow builds pass
+		 *  `false`: there the SDK's own main-model recovery is the ONE reroute, so an arbitrary
+		 *  provider must not be substituted underneath a member the user pinned. */
+		providerFallback?: boolean;
+	},
+) => StrategyEngine;
 
 export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 	return (signal, onProgress, engOpts) => {
@@ -63,9 +74,18 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			// A named contract file (contracts/<name>.contract.json) wins; "default" is the built-in.
 			const contracts = (n: string): ContractDef | undefined => contractDefs[n] ?? (n === "default" ? DEFAULT_CONTRACT : undefined);
 			const contractNames = (): string[] => installedContractNames(contractDefs);
-			const modelFor = (agent: string): string | undefined => {
-				const persona = controller.activePersona?.name;
-				return persona ? personaModels(personaConfigs, persona)[agent] : undefined;
+			// A per-persona model assignment. The lookup key MUST match the one the picker saved
+			// (`persona/model-participants.ts`): a role member's own key first, then the bare agent
+			// key, so assignments saved before roles existed keep applying.
+			const persona = controller.activePersona?.name;
+			const savedModels = persona ? personaModels(personaConfigs, persona) : undefined;
+			const modelFor = (agent: string, role?: string): string | undefined => {
+				const trimmed = role?.trim();
+				if (trimmed) {
+					const own = savedModels?.[participantKey(agent, trimmed)];
+					if (own) return own;
+				}
+				return savedModels?.[agent];
 			};
 			// The main model thinks adaptively (it picks effort by difficulty); a spawned child
 			// can't inherit "adaptive" if its model doesn't support it, so give children an
@@ -184,6 +204,7 @@ export function createBuildEngine(d: () => BuildEngineDeps): BuildEngine {
 			// switch on error". No ctx (no registry) ⇒ pass through. Each attempt still runs through
 			// worktree isolation + steering below.
 			const wrapFallback = (eng: StrategyEngine): StrategyEngine => {
+				if (engOpts?.providerFallback === false) return eng; // the SDK owns recovery there
 				if (!lastCtx) return eng;
 				const prefer = lastCtx.model?.provider;
 				return withModelFallback(eng, {