@aeondave/pi-persona 1.16.3 → 1.17.1

package/AGENTS.md

@@ -10,6 +10,9 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
 
 - Typecheck (must stay clean): `npm run typecheck`  (`tsc --noEmit`, strict)
 - All tests: `npm test` · unit only: `npm run test:unit`
+- Settings SDK smoke (isolated profile, no provider/network requests):
+  `node --import tsx scripts/settings-smoke.mjs [absolute-pi-package-entry]`.
+  Omitting the argument uses the development SDK; pass an installed host entry to qualify that version.
 - One file: `node --import tsx --import ./test/setup/hermetic-env.ts --test test/unit/core/frontmatter.test.ts`
   - The second `--import` is the hermeticity choke point: it strips the whole `PI_PERSONA_*`
     namespace and pins `PI_AGENT_DIR` at a throwaway dir before any test module loads, so a
@@ -115,8 +118,9 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   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.
-  Periodic async status is a durable, expandable operator-only entry, never a model wake or context
-  message; completions, asks, unread bus messages, and newly-stalled alerts keep their actionable paths.
+  Periodic async status and each newly detected stall episode are durable, expandable operator-only
+  entries. Interactive stalls never wake the model; headless sessions get at most one stall wake per run
+  lifetime. Completions, asks, and unread bus messages keep their existing actionable paths.
   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
@@ -233,7 +237,7 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
 - `src/engine/` — `child.ts`, `inproc.ts` (default), `adapter.ts`, `async.ts` (async tracker/peek), `worktree.ts` (git-worktree isolation), `stream.ts` (event→state).
 - `src/orchestration/` — `sdk.ts` (`agent`/`parallel`/`reduce`), `strategy.ts` (registry), `strategies/*.ts`, `voting.ts`, `flow*.ts` (DAG + JSONL journal + checkpoint gates), `roster.ts` (teams + `rosterSpec`: a roster member is a bare name OR an inline `{ agent, role, model, skills }` that specialises one agent — every strategy runs members through `rosterSpec`).
 - `src/bus/` — `inproc.ts` (handle-based bus: send/ask/reply/onMessage), `contact.ts` (child `contact_supervisor` tool), `peers.ts` (child `contact_peer` sibling tool — one-way, engine-scoped), `broker/` (cross-process relay, on by default: `paths.ts`/`framing.ts`/`messages.ts` pure, `host.ts`/`client.ts` over `node:net`; `PI_PERSONA_BROKER=off` restores pre-broker spawn). `src/bridge.ts` — the child-mode-only wiring loaded when `PI_PERSONA_BUS` is set.
-- `src/persona/` — `persona.ts` (parse + `expandCouncilPreset`), `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts`.
+- `src/persona/` — `persona.ts` (parse + `expandCouncilPreset`), `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts` (pure model helpers), `settings-store.ts` (sole persistent settings owner).
 - `src/tools/` — `delegate.ts`, `intercom.ts`, `exocom.ts`. `src/ui/` — agent-tree/overlay, model-picker, `presentation.ts` (the collapsed-card compaction/sanitization helpers), `usage.ts`. `src/extension.ts` — the single ExtensionFactory (wires tools/commands/hooks/engines).
 - Bundled data-driven assets (discovery precedence builtin < user `~/.pi/agent/persona` < project `.pi/`):
   `personas/*.md`, `agents/*.md` (personas+agents share a folder, split by `persona: true` — a
@@ -249,6 +253,21 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
 
 ## Adding a new X (data-driven — usually no core change)
 
+Settings use `/persona-settings`, a full-page registry-driven UI independent of Pi's `/settings`.
+The only active preferences file is `<agentDir>/persona/settings.json` (version, sparse preferences,
+per-persona model assignments, last selection). `src/core/settings.ts` owns row metadata and validation;
+add/remove public preferences there rather than special-casing UI fields. Route every write through
+`patchPersonaSettings`; exact null patches remove overrides without erasing concurrent edits.
+The retired `config.json` and `state.json` are migration inputs only, archived as `.migrated` after
+the canonical file commits. Malformed files remain untouched; never add a truncating fallback writer.
+Scalar preferences apply after a Pi restart or native `/reload`, not `/new` (never auto-reload live workers).
+Model edits apply to future runs through the existing participant resolver. `/persona reload` only
+refreshes resources, not startup preferences. Native Pi settings and compaction are not owned here.
+Mind/Flow contribute supported current values through `pi-persona:settings:collect:v1` (`{ add(id, values) }`);
+their five preferences share the same registry/file. Do not hard-import a companion or start services
+while collecting settings. Flow port/idle changes are for the next shared-service start, never a restart
+of a service other Pi sessions are using. Skill Optimizer remains independent.
+
 1. **Strategy**: add `src/orchestration/strategies/<name>.ts` (export a `Strategy`), register it in `strategy.ts` `BUILTINS`, add a unit test.
 2. **Persona**: `personas/<name>.md` — frontmatter `persona: true` + optional `council:` / `orchestration:` / `delegation:` / `coaching: true`; runtime behavior is field-driven, never keyed to a persona name.
 3. **Agent**: `agents/<name>.md` — optional `tools`, `model`, `isolation: worktree`, `mcp: true`

package/CHANGELOG.md

@@ -6,6 +6,62 @@ used in its [GitHub releases](https://github.com/AeonDave/pi-persona/releases).
 
 ## [Unreleased]
 
+## [1.17.1](https://github.com/AeonDave/pi-persona/releases/tag/v1.17.1) - 2026-10-20
+
+### Added
+
+- Add `/persona-settings`, a dedicated TUI/RPC editor for pi-persona preferences, persona model
+  assignments, and diagnostics, plus `/persona-settings show` for a read-only headless report. The
+  full-page TUI supports filtering, resetting a saved override, and opening model settings.
+- Persist preferences, per-persona model assignments, and the remembered persona in one versioned
+  `<agentDir>/persona/settings.json`. On first migration, the retired model and state files are
+  imported and unchanged originals are archived as `.migrated` when safe; failed or unsafe
+  migration keeps the source files and reports a warning.
+- Let users select a model-settings owner and profile explicitly without activating it. Model
+  assignments affect future runs; inline pins remain read-only, and resetting removes only the
+  saved override. Public environment overrides retain startup precedence; scalar preference changes
+  wait for a Pi restart or native `/reload` (not `/new`) and are never auto-reloaded.
+- Keep persona-selection revisions separate from unrelated settings saves so companion memory scopes
+  can follow explicit re-selections without mistaking model edits for persona switches.
+- Include the loaded Mind/Flow companions in the same panel and preferences file, using optional
+  public-bus discovery rather than hard plugin dependencies. Keep Skill Optimizer separate and
+  preserve per-run `--no-flow` and the existing shared service's lifetime.
+
+### Fixed
+
+- Count streamed textual tool output as child liveness without adding tool output to the assistant
+  transcript. Queued delegates start their stall window only after concurrency admission.
+- Keep interactive stall episodes operator-only and expandable. Headless runs receive at most one
+  successfully delivered stall wake per run lifetime; real progress still re-arms operator episodes.
+- Reject malformed UTF-8 settings and migration inputs rather than silently replacing bytes during
+  a save. Preserve invalid originals and keep concurrent preference/model edits in one safe store.
+
+## [1.17.0](https://github.com/AeonDave/pi-persona/releases/tag/v1.17.0) - 2026-10-19
+
+### Added
+
+- `/persona models [council-persona]` refreshes the host catalog and reopens model selection for
+  the active caller's council participants, preserving cancelled choices, unrelated assignments,
+  and explicit inline model pins. No supervisor switch or model request is required.
+- A hermetic installed-host Pi 1.3.0 qualification script covers real command dispatch, assignment
+  persistence, custom-message starts and missing-auth council recovery without network requests.
+
+### Fixed
+
+- Publish terminal progress for single delegates before removing their tree node, preserving `done`
+  status in Flow and other telemetry consumers.
+- Preserve Exocom reply references and optional target-correlated transport IDs while keeping each
+  queued/terminal telemetry row stable; retain bounded broadcast delivery receipts.
+- Report an exact acknowledged broadcast receipt as delivered even when failures for other peers
+  exceed the retained sample; recipients without exact evidence remain conservatively unknown.
+- Classify Pi's `No API key found for <provider>` diagnostic as a provider failure in both engines,
+  allowing the existing single main-model recovery for councils/strategies/flows. Ordinary delegate
+  provider pins remain strict; aborts, timeouts, contract and agent failures remain terminal.
+- Report a refused persona model switch instead of silently recording an override when Pi rejects
+  it for missing authentication; keep the actual session model and restoration state intact.
+- Remove a timing race from the supervisor-ask telemetry test: verify the persisted timeout
+  transition history rather than polling a transient 20 ms state through asynchronous disk writes.
+
 ## [1.16.3](https://github.com/AeonDave/pi-persona/releases/tag/v1.16.3) - 2026-10-13
 
 ### Fixed

package/README.md

@@ -39,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.16.3` |
+| Pin this release | `pi install npm:@aeondave/pi-persona@1.17.1` |
 | Update an unpinned install | `pi update npm:@aeondave/pi-persona` |
-| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.16.3` |
+| Git alternative | `pi install git:github.com/AeonDave/pi-persona@v1.17.1` |
 
 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
@@ -91,9 +91,15 @@ the worker has acted on it.
 | `/peek` | Show a compact progress summary |
 | `/persona list` | List installed personas |
 | `/persona off` | Turn off the active persona |
+| `/persona models [council-persona]` | Refresh the catalog and reselect council models for the active persona |
+| `/persona-settings` | Open pi-persona's settings in the TUI or RPC UI |
+| `/persona-settings show` | Show a read-only settings report, including in headless sessions |
 | `/models <query>` | Find an available model |
 | `/doctor` | Check configuration and available capabilities |
 
+The settings panel also includes Mind and Flow when those updated companions are loaded; all three
+use one `persona/settings.json`. Skill Optimizer keeps its separate configuration.
+
 For time-based work, ask “remind me in ten minutes.” For an event, ask “let me know when this build
 finishes.” Keep Pi open while timers and monitors are running; they are not restored after a restart.
 See [timers and monitors](docs/MONITORS.md) for examples.
@@ -151,6 +157,8 @@ Strategies are not restricted to the similarly named persona: `council` can sele
 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.
+To replace old council assignments without changing supervisors, run `/persona models magi`
+(or `/persona models` for the active council). Cancel a choice to keep its previous value.
 See [the reference](docs/REFERENCE.md) for an inline council example and recovery limits.
 
 ## Make it yours
@@ -163,6 +171,12 @@ only when you intend to discard customizations to those files.
 
 For optional long-term memory, add [pi-persona-mind](https://github.com/AeonDave/pi-persona-mind).
 
+`/persona-settings` is separate from Pi's `/settings`: it edits pi-persona preferences and saved
+persona model assignments, not native Pi or compaction settings. In the TUI, `/` filters settings,
+`r` resets the selected saved override, and `m` opens model assignment editing. Scalar preference
+changes apply after restarting Pi or Pi's native `/reload`, not `/new`; `/persona reload` only
+refreshes persona definitions. Model changes apply to future runs. See [configuration and settings](docs/REFERENCE.md#configuration-and-data).
+
 ## Documentation
 
 | Guide | What's inside |
@@ -187,6 +201,8 @@ npm test
 ```
 
 Pi loads the TypeScript extension directly; there is no build step.
+To qualify a separately installed Pi 1.3.0 host without cloud calls or your profile, run
+`node --import tsx scripts/qualify-host.mjs <absolute-path-to-pi-coding-agent-package>`.
 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.

package/docs/ARCHITECTURE.md

@@ -200,7 +200,8 @@ engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain
   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),
+  `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts` (pure model helpers),
+  `settings-store.ts` (canonical preferences, per-persona models and last-selected persona),
   `spine.ts` (the shared behavioral layer's SOURCE resolution — docs/SPINE.md; composition sits in
   `persona.ts` for supervisor turns and in the engines for delegated legs).
 - **`src/tools/`** — `delegate.ts`, `intercom.ts`, `exocom.ts` (the `exocom_list`/`exocom_send`
@@ -300,6 +301,54 @@ inline model pins taking precedence. If distinct full roles share a short displa
 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.
 
+**Model assignment repair is configuration, not execution recovery.** `/persona models [profile]`
+is an explicit user edit in the Pi adapter: it reuses `resolveCouncilInvocation`,
+`collectModelParticipants` and the canonical locked settings writer, without adding another roster,
+model store or provider-routing policy. The active caller owns saved assignments even when borrowing
+another council profile. Automatic discovery stays never-nag; explicit editing may replace saved or
+agent defaults, but not inline pins. Host catalog refresh has a 20-second cooperative deadline;
+reported cancellation/errors or a caller/session change leave assignments untouched. Selection uses
+the refreshed host availability snapshot rather than treating all catalog entries as authenticated.
+Cancelled rows preserve their old choices; accepted choices merge without clearing other personas.
+Running engines retain their captured assignments. Missing credentials are classified at the engine
+adapter boundary; only the SDK decides whether a main-model recovery is admissible. This separation
+avoids a global reset or automatic repinning that could silently change billing and panel diversity.
+
+**Unified settings.** `/persona-settings` is independent of Pi's `/settings`: full-page TUI, native
+RPC dialogs, and a read-only `show` report. `core/settings.ts` is the public preference registry and
+validator; the UI and environment precedence consume it rather than maintaining duplicate field lists.
+All persistent Persona preferences live in `<agentDir>/persona/settings.json`, version 1: sparse
+`preferences`, `personas` model maps and `lastPersona`. `settings-store.ts` owns bounded validated reads,
+cross-process locked field patches and atomic replacement. Null removes an exact override; unknown
+top-level and per-persona fields survive unrelated edits. Malformed/unsupported files are never
+overwritten: activation warns and falls back, while editing fails closed. Fresh read-only inspection
+does not materialize defaults.
+
+`selectionRevision` is a non-negative counter updated only by explicit `lastPersona` patches,
+including re-selection of the same name. Model/preference saves never advance it. Companion scope
+readers must use this semantic marker, not the settings file's mtime, as evidence of a selection gesture.
+
+Legacy `config.json` and `state.json` are imported only if the canonical file is absent, then archived
+as exact independent `.migrated` copies after commit. Archive conflicts preserve the original and warn;
+an existing canonical file is never reimported. `PI_PERSONA_STATE_FILE` only selects a legacy import
+source. No active legacy writer remains. Explicit public environment values retain startup precedence;
+internal child/bus guards are not preferences. Definitions, credentials and native Pi settings remain
+with their existing owners.
+
+Scalar preferences are activation-scoped: saving marks differences pending until a Pi restart or
+Pi's native `/reload`, not `/new`; the panel never reloads automatically. `/persona reload` only refreshes resources.
+The Models section selects the assignment owner independently of the viewed council/orchestration
+profile, supports exact-key resets and keeps inline pins immutable. It patches the same file and updates
+the resolver cache for future runs, never changing an already-running worker. Native compaction is untouched.
+
+Mind/Flow settings use optional synchronous discovery on Pi's public event bus
+(`pi-persona:settings:collect:v1`). The owning companion reports its current startup values; the same
+central registry validates owner/type and renders only supported fields. Persona alone writes their
+preferences in the canonical file; companions independently read their known fields, retaining
+standalone operation with no hard runtime dependency on Persona. No collection call performs I/O,
+starts services or wakes a model. Flow's desired port and idle grace apply to the next shared-service
+startup, never to a daemon other sessions are already using. Skill Optimizer is outside this contract.
+
 ### 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
@@ -644,12 +693,14 @@ a local process able to modify that directory is already inside the trust bounda
   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 can start a model turn
-  only for actionable events: 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); messages to the supervisor also wake it. The **slow routine status card**
-  (`PI_PERSONA_CHECKIN_MS`, ~5 min, `0` disables) is a durable, expandable operator-only session entry
-  with the compact ProgressView digest — never full transcripts — and does not start a model turn. Live supervisor asks
+  there is something to act on — a healthy background run should not interrupt. Every newly detected stall
+  episode (`STALL_FLAG_MS`, 90s) appends a durable, expandable operator-only warning entry, including while
+  the supervisor is busy. Interactive stalls never wake the model. In headless sessions, the first stall
+  episode may produce one focused patience-first model wake per run lifetime (ask the leg, don't probe its
+  environment); later stall episodes for that run do not re-arm the model-wake budget. Unread messages to the
+  supervisor retain their existing wake path. The **slow routine status card** (`PI_PERSONA_CHECKIN_MS`,
+  ~5 min, `0` disables) is a durable, expandable operator-only session entry with the compact ProgressView
+  digest — never full transcripts — and does not start a model turn. 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

package/docs/REFERENCE.md

@@ -188,6 +188,106 @@ files are seed sources. A fresh install has no installed personas until `/person
 | Contract | `contracts/*.contract.json` | structured output fields requested by name and pinned per run |
 | Preset | `presets/*.preset.json` | reusable council strategy, roster, and parameter bundle |
 
+### Unified pi-persona settings
+
+`/persona-settings` opens pi-persona's own settings editor in the TUI or RPC UI. It is a separate
+extension command; it does not replace Pi's native `/settings` or edit native Pi preferences such
+as compaction. The TUI is a full-page, filterable panel (`/` to search, `r` to reset the selected
+saved override, `m` for model assignments, `d` for diagnostics); the RPC UI offers the same
+settings, model, and diagnostics flows. `/persona-settings show` emits a read-only report and is
+available in headless sessions.
+
+The sole active settings file is `<agentDir>/persona/settings.json` (normally
+`~/.pi/agent/persona/settings.json`). Its version-1 top-level shape is:
+
+```json
+{
+  "version": 1,
+  "preferences": { "engine": "inproc", "nudge": true },
+  "personas": { "dev": { "models": { "reviewer": "provider/model-id" } } },
+  "lastPersona": "dev"
+}
+```
+
+`preferences` contains the public extension settings; `personas.<name>.models` preserves
+provider-qualified model assignments, and `lastPersona` remembers the selection when
+`PI_PERSONA_PERSIST` is enabled. The preference registry groups all editable scalar settings as:
+
+| Group | Preference IDs |
+|---|---|
+| Discovery | `extraDirs`, `seed` |
+| Startup | `defaultPersona`, `persist` |
+| Interface | `keybinding` |
+| Delegation | `delegateDefaultAllow`, `childThinking`, `engine`, `peekEveryMs`, `checkInEveryMs`, `agentHardTimeoutMs`, `agentStartupTimeoutMs`, `nudge`, `asyncRetain`, `ledgerV2`, `changeReport` |
+| Collaboration | `broker`, `exocom` |
+| Prompt | `spine`, `spineLegs` |
+| Mind (when loaded) | `mindCapture` (`auto`/`prompt`/`off`), `mindNudge` |
+| Flow (when loaded) | `flowEnabled`, `flowPort`, `flowIdleMs` |
+
+`disabled` and the storage path are not editable preferences. Model assignments remain scoped by
+persona owner, rather than being promoted into global preferences.
+`selectionRevision` is internal metadata in the same file: explicit persona-selection gestures
+increment it, while model/preference edits leave it unchanged. Companion readers can therefore
+distinguish a re-selection from an unrelated settings save without following whole-file timestamps.
+The editor never reloads Pi automatically. Scalar preferences load after a Pi restart or Pi's native
+`/reload`; `/new` alone does not reactivate Persona's extension factory. `/persona reload` reloads
+persona definitions and does not apply preference changes. The panel shows when a saved value is
+pending reload. Model assignments are read by the
+existing resolver for future runs, so they do not alter workers already running.
+
+Mind and Flow report their supported settings through Pi's public event bus; the panel does not import
+or require either plugin. Their preferences live in the same `preferences` object above, not in new
+plugin configuration files. Skill Optimizer remains independent. Absent companions do not expose
+nonfunctional controls. Updated companion versions are needed to contribute settings to this panel.
+
+`flowEnabled` controls default dashboard attachment; `--no-flow` still opts out for one run.
+`flowPort` is the desired port for the next shared service start, not a command to move an existing
+service. `flowIdleMs` is the advanced shared-service idle grace (50–60000 ms): it applies only with
+no Pi registrations **and** no browser SSE clients. Saving it never restarts another Pi's service.
+
+Explicit public `PI_PERSONA_*` environment values retain startup precedence over saved preferences.
+The panel marks an environment-controlled setting as locked; resetting its saved value only removes
+that saved override and does not defeat the environment. `PI_PERSONA_DISABLE` is an internal
+process guard and is not an editable setting.
+
+When no canonical `settings.json` exists, startup imports the retired `config.json` model store and
+`state.json` persona state (or the path supplied by `PI_PERSONA_STATE_FILE`) once. Successfully
+migrated, unchanged legacy files are archived as `<file>.migrated`; if validation, safe archival, or
+concurrency checks fail, the legacy source is kept and a warning is reported. Once `settings.json`
+exists, it is the only active store: legacy files are not dual-read. An invalid or unsafe canonical
+file is reported rather than overwritten. `PI_PERSONA_STATE_FILE` now only selects a legacy state
+file to import when the canonical file does not yet exist; it does not move or redirect active
+settings storage.
+
+The model editor asks you to choose an owner persona and then its current or a named council
+profile; it never activates that persona. It lists the roster and strategy-declared auxiliary
+participants using the runtime model precedence described below. The searchable model picker uses
+Pi's currently available provider-qualified models; opening the editor does not refresh provider
+catalogs, and refresh is an explicit action. Saving or removing an assignment affects future runs.
+Reset removes only that saved key (`null` in a settings patch), revealing lower-precedence sources
+such as a bare agent assignment; inline model pins remain read-only. “Other saved assignments” lets
+you remove keys outside the selected profile without exposing unsafe legacy key text.
+
+The existing `/persona models [council-persona]` shortcut remains available for the active caller.
+It refreshes the model catalog before editing, and a named council profile does not change which
+persona owns the saved assignments. Use the Models action in `/persona-settings` when you need to
+choose the owner explicitly.
+
+#### Companion settings adapter contract
+
+The optional synchronous bus channel `pi-persona:settings:collect:v1` receives
+`{ add(id, values) }`. A loaded supervisor companion responds with `add("mind", { mindCapture,
+mindNudge })` or `add("flow", { flowEnabled, flowPort, flowIdleMs })`, using its current startup
+snapshot. Each may report a supported subset. Persona validates ownership/types against the same
+registry used by the editor and displays only reported fields; an unrelated plugin cannot contribute
+an optimizer or native Pi setting through this channel. Contributors must not read credentials,
+refresh providers, write files, wake the model or start a service in response to collection.
+
+Persona alone patches the canonical settings file; companions read their own known fields and
+preserve their standalone operation and environment overrides. They must release/re-arm their
+listener with the owning extension lifecycle. Add a new control by updating registry metadata,
+validation, the owning consumer and contract tests—not by adding another settings writer.
+
 `tools` accepts an allowlist such as `[read, grep]`, an `allow`/`deny` object, or `[]` for no tools.
 Entries are plain tool names or `*` patterns; Pi's `+name`/`-name` default-tool modifier
 syntax is not an allowlist and is rejected. Use the `deny` field to remove tools. Omit `tools` to
@@ -303,10 +403,28 @@ With an active persona, UI, and at least two configured models, unassigned parti
 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.
+
+Run `/persona models` to explicitly reselect the active council's models, or `/persona models magi`
+to edit the MAGI panel while keeping another supervisor active. The optional name selects an
+installed council persona, not a strategy or team. The command refreshes the host catalog first,
+then offers each editable participant, including previously dismissed choices and saved or agent
+defaults. One available model is enough for this explicit edit. Choices are saved under the **active
+caller's** persona, just as for `council({ persona: "magi" })`; it never activates the borrowed
+profile. Cancelled choices, unrelated assignments and other personas remain unchanged. Inline
+`members[].model` pins still win and are not editable here. TUI/RPC UI is required; no model call
+is made. Changes apply to future runs, not workers already running. `/persona magi` still switches
+the supervisor; `/persona reload` reloads definitions without resetting saved models.
+Refresh is bounded to 20 seconds cooperatively; provider errors, cancellation, or a persona/session
+change cancel the edit without replacing assignments. The list uses the host's refreshed availability,
+not every model in its catalog.
+
 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.
+The exact Pi diagnostic `No API key found for <provider>` counts as a provider failure in both
+engines, so it can use this same bounded recovery. If the main model is the failing model too,
+recovery cannot help: use `/login` or change `/model`, then reselect with `/persona models`.
 
 **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
@@ -420,8 +538,9 @@ test; the data-driven definitions above require no core change.
 **Keys** — `f8` cycles persona; `f9` or `/agents` opens the agent overlay: ↑↓ navigate, ⏎ open, `x`
 stop, `s` steer, and Esc close.
 
-**Commands** — `/persona [name|off|list|reload|seed|restore]` · `/models [query]` ·
-`/orchestrate <task>` · `/flow <name> <task>` · `/peek [id]` · `/exocom` · `/doctor`.
+**Commands** — `/persona [name|off|list|reload|seed|restore|models [council-persona]]` ·
+`/persona-settings [show]` · `/models [query]` · `/orchestrate <task>` · `/flow <name> <task>` ·
+`/peek [id]` · `/exocom` · `/doctor`.
 
 `/doctor` reports the cross-process broker's lifecycle on one line: `broker: on — endpoint …` once
 the host is listening, `broker: on — (starting…)` mid-attempt, or
@@ -462,11 +581,14 @@ from a different cwd. Pi owns `--model <provider/id>`, `--thinking
 | `PI_PERSONA_KEY` | `f8` | keybinding that cycles installed personas |
 | `PI_PERSONA_PERSIST` | on | `off` stops remembering the last-selected persona across sessions |
 | `PI_PERSONA_DELEGATE_DEFAULT` | allow | `deny` (or an off-word) makes an unlisted delegate target default-deny instead of default-allow |
-| `PI_PERSONA_STATE_FILE` | a global default path | overrides where the last-selected-persona state is stored |
 | `PI_PERSONA_ASYNC_RETAIN` | 25 | how many settled-but-uncollected async runs are retained before FIFO-evicting the oldest |
 | `PI_PERSONA_LEDGER_V2` | off | `on` widens the delegation-ledger retry-veto key to also include role/tools/isolation, not just agent+model+task |
 | `PI_PERSONA_LEG_CHANGE_REPORT` | on | `off` disables the non-worktree files-changed report (two `git status` spawns per leg) |
 
+`PI_PERSONA_STATE_FILE` is only a migration input for the retired standalone state file; it no
+longer selects an active persistence path. The canonical store is always
+`<agentDir>/persona/settings.json`.
+
 ## Development
 
 ```bash

package/docs/TELEMETRY.md

@@ -8,6 +8,14 @@ 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.
 
+Message payload `id` is the stable lifecycle-row key: queued and terminal updates keep it unchanged.
+Optional `wireId` identifies the actual transport message, and `replyTo` references that transport's
+original ID. Exocom sends attach `wireId` only after an exact target-correlated successful receipt;
+broadcast receipts are bounded and omitted mappings remain unknown. Do not replace the queued row's
+`id` with a wire ID, infer a mapping by timestamp/alias, or merge observations from different streams.
+Single delegates publish their terminal progress before tree removal, so a completed worker remains
+`done` in the telemetry instead of being mistaken for a stopped in-flight leg.
+
 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.16.3",
+  "version": "1.17.1",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -104,7 +104,7 @@
     "typescript": "^7.0.2"
   },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.16.3/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.1/assets/banner.png",
     "video": "https://cdn.jsdelivr.net/gh/AeonDave/pi-persona@6655d281ce7965a75303dd704bd29db73db04070/assets/demo1.mp4",
     "extensions": [
       "./src/extension.ts"

package/src/core/config.ts

@@ -15,7 +15,7 @@ export interface PiPersonaConfig {
 	persist: boolean;
 	delegateDefaultAllow: boolean;
 	seed: boolean;
-	/** Explicit override for the persisted-state file (else a global default). */
+	/** Legacy selection-file import path; ongoing persistence uses persona/settings.json. */
 	stateFile?: string;
 	/** Thinking level forced on delegated children (else the supervisor's level).
 	 *  Spawned children must carry an *explicit* level or they fall into the model's