@aeondave/pi-persona 1.17.0 → 1.17.3

package/docs/ARCHITECTURE.md

@@ -33,12 +33,17 @@ Persona names are data, never dispatch keys. Optional `delegation:` fields apply
 builtin, user, or project persona: `requireBrief`, `outputContract`, `requireDisjointWrites`,
 `requireFreshVerification`, and `verificationAgents`. Council behavior remains independently
 declarative through `council: { strategy, roster, params }`; a custom persona can compose any installed
-strategy/team without a core change. The gates use effective agent/tool capabilities, conservatively
+strategy/team without a core change. Ownership intent follows the agent, not the caller: an agent definition
+can declare the area it alone writes (`writeSet`, e.g. `research` → `.research/`), and a write-capable delegate leg that
+names no `writeSet` inherits it before the gates run, so the disjoint-ownership and overlap checks see a
+declared owner; a leg's own set wins, and the field stays declarative (nothing enforces paths at runtime).
+Legs restricted to read-only tools do not inherit ownership defaults, so parallel readers do not conflict.
+The gates use effective agent/tool capabilities, conservatively
 treat shell-capable, MCP-enabled, or unknown tools as potential writers, and enforce the requested fan-out
-concurrency in both synchronous and background execution. A serialized verifier is accepted only
+concurrency on the single launch path (interactive background or headless inline). A serialized verifier is accepted only
 after every material writer in that batch; otherwise the call fails before a child starts. The rule
 also holds ACROSS calls: a verifier launched while a material-writer background run is still live is
-rejected with the run id to wait on, so a later call cannot slip past the in-batch ordering.
+rejected, naming the mutating run ids, so a later call cannot slip past the in-batch ordering.
 
 ### The effort ladder (make the simple case simple; complexity is opt-in)
 
@@ -56,7 +61,9 @@ rejected with the run id to wait on, so a later call cannot slip past the in-bat
 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
+persona focus. The tool description lists every strategy with its `when`, positional roster and required
+params, generated from the registry (`strategyCatalog`), and a call missing a required param is refused
+before any run exists. 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)
@@ -100,7 +107,10 @@ These are the guardrails a contributor must not violate. They are enforced in co
 - **I5 — Flows are the top tier.** A declarative DAG (statically verified: acyclicity, references
   resolve, join reducers valid) above strategies. The flow engine stays thin — parse, verify,
   schedule, persist, resume — and a flow node may call any strategy. Journaled: finished nodes replay
-  from disk with no re-spend.
+  from disk with no re-spend. A resume matches only the same flow, the same task and the same project
+  (`flowRunHash` = flow + task + cwd); another task starts from scratch. A `gate: true` phase shows its
+  output and its dependents to the operator; a rejection returns `stoppedAtGate` (not a failure, though
+  `ok` stays false so mandatory orchestration still fails closed).
 - **I6 — Spawning is opportunistic by default; mandatory only when the persona declares it.** Two
   first-class cases: *opportunistic* (`mode: solo` / no block — the supervisor MAY delegate by its own
   judgement; never forced) and *mandatory* (`mode: strategy|flow|parallel|pipeline` with a roster —
@@ -161,8 +171,9 @@ engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain
   `peerDependencies`, `/doctor`'s `pi:` line, and the README's stated floor trace back to this
   constant), `models`, `brief` (`buildDelegationBrief` — the per-turn delegation brief: live roster +
   standing hand-off default; and `buildExocomBrief` — the per-turn peer brief: live peers, the
-  peer-vs-sub-agent split, and the relevance bound on an exchange), `nudge` (the two
-  runtime-reinforcement state machines, `DelegationNudge` + `PersistenceNudge`), `display-label`
+  peer-vs-sub-agent split, and the relevance bound on an exchange), `nudge` (the
+  runtime-reinforcement state machines `DelegationNudge` + `PersistenceNudge`, and the call-time wake
+  guards `PollGuard` + `longWaitSeconds`), `display-label`
   (`sanitizeDisplayLabel` — an untrusted name reduced to bounded metadata before interpolation
   outside a fence), `timer` (`TimerScheduler` — the pure alarm engine behind the `timer` tool), `time`
   (`formatDuration` / `peerSentLabel` / `sessionElapsedLabel` / `buildSessionAnchor` — the elapsed-time
@@ -200,11 +211,12 @@ 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`
-  tools), `exocom-work.ts` (claim/ask/answer/decline/wait/release/progress). **`src/ui/`** — agent tree/overlay, model picker, `presentation.ts` (the shared
+  tools), `exocom-work.ts` (claim/ask/answer/decline/wait/release/progress). **`src/ui/`** — agent tree/overlay, model picker, `wake-rows.ts` (the monitor/timer → tree-row projection), `presentation.ts` (the shared
   card-compaction/sanitization helpers behind the projection rules below), `usage.ts`
   (token/usage formatting, `ChildUsageLedger` / `toToolUsage` — sub-agent spend is
   attached as Pi `toolResult.usage` so the footer and pi-theme-1337's frame count it;
@@ -302,7 +314,7 @@ than borrowing another role's choice. Routing still resolves the full role key,
 
 **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 existing locked config writer, without adding another roster,
+`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;
@@ -313,6 +325,49 @@ Running engines retain their captured assignments. Missing credentials are class
 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.
 
+The extension owns the derived candidate cache, keyed by session and base provider/model. Ordinary
+turns reuse it; explicit catalog refresh invalidates the initiating key even after partial provider
+failure. The settings UI supplies the refresh deadline and reporting, while the extension's refresh
+adapter captures the key before awaiting the host. Briefs and nudges share the same callable-`models`
+gate. Automatic model setup for tools, commands and mandated orchestration shares the checkpoint
+dialog queue; each run registers its stop handle before entering that queue. Aborting setup discards
+its unsaved choices and removes only prompt markers created by that attempt, so it can be retried.
+
+**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
@@ -399,8 +454,9 @@ decides how precise each may be is a **prompt-cache** rule, not a taste one:
 - **Tail surfaces are free.** A tool result or a delivered message is written once and never re-sent
   as the cached prefix, so precision costs nothing there. An inbound peer delivery dates itself
   (`[rune] — reply · sent 20m ago`), and every settled leg reports its wall time on every
-  tracker-backed path — the done/failed/stopped report, the join, `intercom result`, and each
-  settled line of a peek digest.
+  tracker-backed path — the done/failed/stopped report, `intercom result`, and each
+  settled line of a peek digest; a running line ends its turns/tokens parenthesis with
+  `· running for <duration>` (not shown while queued).
 - **The system prompt is not.** It is re-composed and re-sent every turn and IS the cached prefix,
   so a minute-granular value there rewrites it every minute and throws away the provider's cache of
   everything before it. The **session anchor** therefore reads on a deliberately coarse ladder —
@@ -435,7 +491,7 @@ never simultaneously a telemetry event, a routed message, and a UI source of tru
   a source of truth. The `f9` agent tree and `peek` digest are ProgressViews.
 
 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
+steering does not establish that a blocking headless delegate call 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
@@ -488,36 +544,88 @@ for the supervisor and for explicit retrieval; the default TUI projection is del
   Oversized or evicted messages return an unavailable diagnostic — retention is not durable evidence
   storage;
 - collapsed delegate/intercom/council/flow cards show state, identity, a short sanitized preview, and
-  Pi's expand-key hint, each surfacing failure at the top in its own shape: the delegate card **sorts**
-  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);
+  Pi's expand-key hint, each surfacing failure at the top in its own shape: the delegate card
+  names each failed leg on its own line, and a failed council/flow card leads with the cause in its title;
 - 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;
+- async failures append a `pi-persona-run-failure` entry in TUI mode, with alias, agent/model,
+  elapsed time and a concise cause. The entry stores the original diagnostic for expanded history
+  rendering; it is operator-only and adds no model context or wake. Other modes, or an append
+  failure, retain a bounded notification. The semantic completion follows its existing single-wake path;
 - 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
+- custom follow-ups and operator-only entries share `ui/session-cards.ts`: glyph-free generated
+  headings, explicit textual state, one width-aware layout and semantic theme backgrounds. Neutral
+  information/unknown state uses `customMessageBg`, verified completion `toolSuccessBg`, attention
+  (nudge/stall/stopped) `toolPendingBg`, and verified failure `toolErrorBg`. Only runtime-owned status
+  evidence selects chrome, never peer/child prose. Colors are resolved from the active theme at render
+  time (including pi-theme-1337); normal tools keep Pi's own shell rather than gaining a duplicate box.
+  Expanded prose reports use the native Markdown projection in `ui/report-body.ts` (including visible
+  trust blockquotes); receipts, live output, monitor/timer notices and raw diagnostics stay literal.
+  Source payloads and fences remain intact. The native Markdown component is retained per report and
+  invalidated for theme/layout changes, without a global transcript cache. Rendering never rewrites
+  stored or model-facing payloads, nor creates a wake;
+- literal control receipts and fallback errors share `ui/literal-tool-result.ts`: bounded collapsed
+  text, an expansion hint only when detail is hidden, and full sanitized expansion. Tool errors use
+  the host's `ToolRenderContext.isError`, not a presumed result field; semantic negative peer answers
+  remain successful retrievals. Retained `exocom_wait` answers are prose reports and render Markdown
+  when expanded. Native tool shells remain host-owned;
+- the sticky agent and exocom widgets have fixed physical-row budgets: the shared width-aware
+  `ui/compact-widget.ts` clips each already-budgeted row instead of letting native Text wrap it.
+  F9/`/agents` and paginated
   `exocom_list({ offset, limit })` are the explicit detail surfaces, so a wide fan-out cannot push the
   editor off screen or dump an entire peer registry into model context. Agent-tree deltas share one
   16 ms widget composition per terminal frame; identical lines/status are not republished, hierarchy
   rendering uses one adjacency index, and the F9 overlay rebuilds lazily when Pi paints rather than
   once per streamed token;
-- `/flow` and `/orchestrate` append durable, TUI-only expandable result entries rather than dumping a
-  large notification or a second copy into the model context;
+- `/flow` and `/orchestrate` append a durable, TUI-only expandable result card rather than a large
+  notification; the supervisor gets the same text (fenced, 12k-bounded) once, as a passive next-turn message;
+- an interactive `tasks` fan-out of two or more legs gets one container row, `delegate · N legs`
+  (`k/N settled`), that never counts as an in-flight agent and leaves with its last leg;
+- `X` is not a directed key: it acts on the whole stoppable set of leaf rows after a confirmation that
+  states how many agents it covers, and a changed set is re-confirmed. The set is every agent leaf (wake
+  rows excepted) plus any run root with a stop handle (council/flow/mandated runs), and `x` on such a
+  root stops the whole run.
+  `intercom stop` / `stop { to: "all" }` also cover tracker runs, `council` and `flow` included;
 - the F9 overlay's *directed* keys (`x` stop, `s` steer) act only on the agent the ▸ marker still
   shows; if that agent settles and is pruned mid-keystroke, the selection re-anchors visibly and the
   keypress is spent re-aiming instead of aborting an agent the user never chose. ↑↓, ⏎, and the scroll
   keys never refuse;
 - every agent-tree node carries `startedAt`/`lastAdvanceAt`; `LiveClock` (`src/ui/live-clock.ts`)
   repaints the sticky widget and the F9 overlay once a second while any node is running and stops
-  itself once nothing is. A running row shows elapsed time until it goes `STALL_FLAG_MS` (90s) quiet,
+  itself once nothing is. Running/completed usage shares `formatUsage`: `↑` input and `↓` output,
+  using copied existing cumulative usage snapshots, never context occupancy. A legacy progress source
+  providing only an aggregate shows a neutral compact count without `tok` or a fabricated direction. A running row shows elapsed time until it goes `STALL_FLAG_MS` (90s) quiet,
   then the same `⚠ stalled <duration>` badge the async peek watchdog uses. `x` marks the target
   `stopping…` at once and is offered only when a live stop handle exists; a refusal (no handle,
-  already settled) surfaces as a one-line notice instead of silently no-op'ing.
+  already settled) surfaces as a one-line notice instead of silently no-op'ing;
+- armed timers and active monitors are **wake rows** in the same tree (`src/ui/wake-rows.ts`, ids
+  `monitor:<id>` / `timer:<id>`): rows, not agents. The countdown replaces the stall clock: a timer
+  shows `fires in <d>` only, a monitor keeps its elapsed time (`<elapsed> · deadline in <d>`), so
+  neither carries the `⚠ stalled` badge or `waiting for supervisor`. `x` cancels
+  one through the same stop registry as an agent (the `monitor cancel` / `timer cancel` effect); `s` steer
+  is never offered. They are excluded from the `X` stop-all count, confirmation and bulk stop, from the
+  `N agents` in-flight status, and from telemetry (`agent.*` events are agents only). They settle and
+  leave like an async row: the final ✓/✗/■ goes to the tree change stream (telemetry excluded), not to
+  the screen, because the update and the removal are synchronous and the widget frame is coalesced. They
+  live only in the arming session, never restored. Raw monitor stdout/stderr has a separate passive
+  observer: raw chunks feed bounded sanitized tails immediately, but full row/preview projection is
+  coalesced per dirty monitor into the existing 16 ms widget frame, before its tree snapshot. Terminal
+  events and cancellation publish the pending final tail synchronously; teardown clears pending state.
+  This updates the widget and F9 without semantic events, model wakes, event-budget consumption or
+  stall-clock credit. The same observer feeds a bounded session-native log
+  archive (`src/monitor/archive.ts`): one plain custom entry per terminal/cancelled run, no sidecars or
+  per-chunk writes. `monitor result` retrieves retained captures across reload/resume from the whole
+  session tree, including sibling conversation branches: this archive is session-wide, deliberately
+  not a projection of the active branch. Branch navigation changes neither visibility nor the shared
+  lifetime budget. Restored logs never restore processes. Activation-unique monitor ids avoid historical result collisions. A finite
+  lifetime serialized-byte/count budget includes all previous entries of the archive type, even
+  unreadable versions. Session-file deletion owns log deletion; ordinary shutdown saves diagnostics,
+  not deletes them. Operator-only expandable log entries do not create model context or extra wakes.
 
 This is a UI invariant only: truncating a collapsed card must never be confused with truncating the
 underlying result or changing a strategy's contract.
@@ -643,36 +751,72 @@ a local process able to modify that directory is already inside the trust bounda
 
 ## Supervision & the waiting model
 
-- **sync** — the supervisor actively blocks on the delegate/strategy call (results still stream); no
-  idle/peek/steer.
-- **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 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 no `sync`/`async` switch on `delegate` and no `intercom wait`; the mode follows the session.
+
+- **Headless (`ctx.hasUI !== true`, e.g. `pi -p`)** — the supervisor blocks on the delegate, council or
+  flow call and gets results inline (returned once, unclipped; progress is only a `k/N done` counter), because nothing drains a follow-up after the
+  single turn exits. A runtime constraint, not a model-facing choice. The legs are still tracked, but
+  the status monitor stays off: the model is parked in the call and nobody reads a card.
+- **Interactive (TUI and RPC)** — delegation is ALWAYS background: the call returns run ids at once
+  and each result returns as an idle-gated completion follow-up (`intercom result { to: runId }`
+  retrieves a settled run; `peek`/`steer`/`stop` stay available, which a blocking call could never
+  offer). With only background children left, the supervisor ends its turn and goes idle until a wake;
+  it never sleeps, polls, or arms a `timer` to wait for a child or a monitor. The **peek watchdog**
+  fires while async children run but stays SILENT unless there is something to act on. A newly
+  detected stall (`STALL_FLAG_MS`, 90s) appends a durable, expandable operator-only card, even while
+  the supervisor is busy, and never wakes the model; unread messages to the supervisor keep their
+  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
-  live descendant branch is waiting.
-  Stall alerts and live messages let an idle supervisor steer/stop a wedged 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`.
+  live descendant branch is waiting. The peek watchdog's clock is stricter (`madeHeadway` in
+  `engine/async.ts`): a run advances only when assistant output, tokens or turns grew or a tool call
+  completed, and raw tool-output chunks earn nothing, so a leg whose tool streams forever (`npm run dev`,
+  `tail -f`) raises the operator-only stall card. A false advisory on a legitimately noisy long tool is
+  accepted; nothing is killed and the model is not woken. A council or flow run is credited per leg. The
+  tree/F9 clocks stay event-based.
+  The operator (or a manual `/peek`) can steer/stop a silent child. The supervisor's net for one is the
+  engine idle window (`RUN_LIMITS.timeoutMs`, 180s; startup deadline 300s), which kills it and returns a
+  failed completion follow-up whose text says to raise the leg's `timeoutMs`; the opt-in hard wall-clock cap (`PI_PERSONA_AGENT_MAX_MS`, off by
+  default) catches a busy non-converging leg.
+  Two call-time guards (under `config.nudge`, `PI_PERSONA_NUDGE=off` disables both) stop the in-turn
+  waits that would block those wakes: a repeated `intercom peek`/`result` whose answer has not changed
+  (per scope; `steer`/`stop` reset it) is refused, then asks Pi to end the turn (`terminate` is a hint
+  Pi honours when the peek is the batch's only call); a leading long `sleep`/`Start-Sleep` (>= 20s) is
+  stopped while background children run or are being launched (interactive only; a sleep prepared
+  before a same-batch `delegate` is an accepted false negative). A `delegate` fan-out (`tasks`) is
+  held and delivered as ONE completion follow-up when its last member settles, with every failed leg
+  named and clipped on its own line; single legs and separate calls are unchanged. Held reports are
+  dropped at session shutdown or reload, like the running legs, and the `PI_PERSONA_ASYNC_RETAIN`
+  default (64, the `tasks` cap) covers one whole call so early finishers stay fetchable. In headless `pi -p` the
+  `timer`/`monitor` arm text says the process exits when the turn settles, so such a wake lands only
+  if it fires before then.
+  **`council` and `flow` are the same kind of run** (`tools/background-run.ts`, `createBackgroundRuns`).
+  Interactive, each is ONE tracker run rooted at `async:<runId>`: a receipt now, ONE completion follow-up
+  (`intercom result { to: runId }` for the full payload), and the same `peek`/`stop`/`stop all`/f9 reach
+  as a delegate leg. Headless, the same run is launched and joined inside the tool call. Esc no longer aborts
+  one; stop it by key. Ownership of the limits: a run holds ONE slot of the delegate `maxConcurrency` launch
+  pool for its whole life (`queued` until granted; a flow keeps it while parked at a checkpoint); the strategy
+  SDK's per-run semaphore gates the legs INSIDE it, so members never compete with delegate legs for pool
+  slots; token budgets, the child limit, the delegation ledger and the fork-bomb guard stay in the SDK and
+  engine. A flow parked at a checkpoint is blocked on the OPERATOR: the run carries `awaiting`, peek reads
+  `waiting for operator at checkpoint <id>`, the stall watchdog skips it and nothing wakes the model; a
+  rejected checkpoint settles the run `stopped` and the plan reaches the model as its partial output. A
+  persona's `council:` defaults resolve unchanged when the call omits strategy, roster and params. The
+  mandated `orchestration:` path stays PRE-turn and inline (its result is the supervisor's first answer),
+  as do the `/orchestrate` and `/flow` slash commands; those runs register their own abort under their root
+  row, so shutdown ends the whole run. Operator-run results also reach the supervisor's next turn as a
+  passive, fenced, 12k-bounded message.
   Progress tokens are labelled **cumulative input/output**, not context occupancy; cache-read/write
   accounting is separate. Do not infer a full context window from that counter. File age or line-count
   changes alone likewise do not establish a stall, a passing test or completed work.
+  **Restore honesty:** `session_shutdown` records lost run ids, timers, monitors and the run-id counter
+  in a `pi-persona:runs` session entry (`core/session-runs.ts`). The next `session_start` (reload,
+  in-session resume, `pi -c`; not fork or `/new`) tells the supervisor once through a passive `nextTurn`
+  message, acknowledges it, and continues run ids so they never restart at `run-1` within a session.
+  Only ids matching a strict shape and capped counts are ever read back.
   Async failures are ALWAYS reported; the runtime `DelegationLedger` vetoes a blind retry loop (an
   identical agent+model+task delegation that failed twice is stopped before it spawns). Coaching is
   gated by `coaching: on` AND `canUseBus`.
@@ -680,26 +824,42 @@ a local process able to modify that directory is already inside the trust bounda
 **Runtime reinforcement of the hand-off default** comes as a standing part and a reactive part, because
 a persona directive lives at the TOP of the prompt and its pull decays as recent tool output balloons:
 
-- The **delegation brief** (`core/brief.ts`) is the STANDING half: live roster (agents + teams + flows)
-  and the hand-off default, appended to the system-prompt TAIL every turn, where recency wins the
+- The **delegation brief** (`core/brief.ts`) is the STANDING half: live roster (agents + teams + flows, with descriptions;
+  gated flows are tagged in headless sessions) and the hand-off default (the supervisor's role: it holds the
+  objective, the plan and the judgement, normally handing bounded independent work to supervised legs;
+  quick, trivial or tightly coupled work can stay inline when hand-off overhead would outweigh the benefit; one decision-class →
+  method line that a test checks against the strategy registry; model-sizing guidance and a cached provider
+  candidate list), appended to the system-prompt TAIL every turn, where recency wins the
   tug-of-war a top-of-prompt line loses. It regenerates from the live registry (so it can't desync) and
-  filters to the active persona's `delegate` allowlist. It never dictates how MANY sub-agents or which
-  shape — that is each persona's own method.
+  filters to the active persona's `delegate` allowlist. It never dictates how MANY sub-agents; beyond the one class line,
+  the shape is each persona's own method.
+  The model snapshot is acquired once per session/base-model reference, refreshed on a base-model change
+  or explicit `models` call, and reused across turns. Recommendations first stay near the current
+  model's provider, textual name root and numbered major generation, then order distinct variants by
+  relative cost band and numeric version. They do not fill spare slots with older or unrelated models.
+  This affects discovery only; exact assignment and search retain the full eligible catalog.
+  Relative cost hints use host prices against an uncapped recent-provider reference, never a
+  model-name-to-tier table, and leave missing or zero-price metadata unknown. The LLM chooses task fit.
 - The **nudges** (`core/nudge.ts`, on by default) are the REACTIVE half, landing in RECENT context on
   the event that warrants them:
   - **DelegationNudge** — a `tool_result` hook watches the supervisor's own tool stream and, when a
-    delegating persona grinds heavy work by hand (output burn since the last `delegate`/`council`
-    crosses a threshold), appends a compact labelled checkpoint (`Trigger` / `Scope` / `Action`) to
+    delegating persona grinds heavy work by hand (output burn since the last `delegate`/`council`/`flow`
+    crosses a threshold: 3 substantive calls and ~1k tokens), appends a compact labelled checkpoint
+    (`Trigger` / `Scope` / `Action`, with four delegate targets named in the action, those the persona's own prompt mentions first, and a
+    `Model candidates` line for the session provider) to
     that command's result for the model and mirrors it into a durable, expandable
     `pi-persona-nudge` custom entry for the operator. The entry is TUI-only (no duplicate model
     context or turn) and guarantees visibility even when a built-in/custom tool renderer suppresses
     result `content`. A successful hand-off resets the streak; a failed one keeps it and returns the
     same visible re-dispatch checkpoint.
+  - `flow` is a hand-off beside `delegate`/`council`: a successful flow resets the by-hand streak and a
+    failed one gets no re-dispatch checkpoint (its failure text is self-describing).
   - **PersistenceNudge** — the counterweight to premature surrender: a delegated leg's report carrying
-    `[BLOCKED]`/`FLAG: UNKNOWN` gets a "don't bank it yet" reminder. All three delivery paths carry it
-    (sync `delegate`/`council`, background completion, `intercom wait`), but coverage isn't identical:
+    `[BLOCKED]`/`FLAG: UNKNOWN` gets a "don't bank it yet" reminder. Three delivery paths carry it
+    (the inline `delegate`/`council`/`flow` result — headless only — background
+    completion, and an explicit `intercom result` of a done run), but coverage isn't identical:
     the sync path scans the WHOLE tool result including failed legs, while `renderCompletion` scans
-    only `status === "done"` runs by design — a failed background/`wait` leg already gets a failure
+    only `status === "done"` runs by design — a failed background 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.
@@ -707,8 +867,9 @@ a persona directive lives at the TOP of the prompt and its pull decays as recent
     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`).
+  - **The off switch covers every path.** `PI_PERSONA_NUDGE=off` silences DelegationNudge entirely,
+    PersistenceNudge on all three delivery paths (inline result, background completion, `intercom result`),
+    and both call-time wake guards (`PollGuard`, the long-sleep block).
 
 ## Discovery & seeding
 
@@ -725,6 +886,11 @@ a persona directive lives at the TOP of the prompt and its pull decays as recent
   pristine prior copy and preserves edited, linked, or unknown files. A migration can declare a bundled
   agent dependency; that missing file is installed first with no-clobber atomic creation, or the parent
   remains on its old bytes. Upgrades, dependency installs, and warnings are exposed in `/doctor`.
+  The legacy digest table (`LEGACY_SEEDED_DEFAULTS`) holds the LF-checkout bytes of every shipped
+  elite/swarm/MAGI-core version from v1.11.0, plus the v1.17.1 copies of every bundled persona. Release prep must add the
+  previous tag's digest for each changed persona/agent; the guard test in `seed.test.ts` prints the
+  row (and skips in CI's depth-1 checkout). With zero personas installed, F8 and `/doctor` point to
+  `/persona seed`, like `/persona list`.
   Contracts/presets/teams keep a builtin layer (they aren't personas).
 
 ## Cross-OS constructs

package/docs/EXPERIENCE.md

@@ -43,27 +43,37 @@ supervisor is free. Keep the session open, and cancel a watch when its purpose e
 - **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.
+  Council parent clocks refresh on child engine events; that indicates liveness, not useful work. For the
+  stall card and `/peek`, "stalled" is stricter: 90 seconds with no assistant output, tokens, turns or
+  completed tool call, so a tool that only streams output (`npm run dev`, `tail -f`) is flagged too. It is
+  advice only: nothing is killed.
   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.
+- **`/flow <name> <task>`** runs a flow (`/flow` alone lists them with descriptions; a `gate: true`
+  phase pauses for your approval, showing its output and what runs next). `/orchestrate <task>` runs
+  the active persona's `orchestration:` block (bundled personas declare `council:` instead, used via the
+  `council` tool); both run inline and their result also reaches the
+  supervisor's next turn. In the F9 list, `X` stops every running leaf agent after a
+  second press that states how many.
 - **Background results arrive automatically.** A supervisor can continue independent work while
   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
+  their results; never sleep, poll, or arm a timer to wait for healthy workers (or monitors) - a
+  finished worker wakes the supervisor by itself. `intercom result { to: runId }` retrieves a settled
+  run. Interactive `delegate`, `council` and `flow` always run in the background (a receipt now, one
+  follow-up with the outcome; a flow checkpoint waits for you, not the supervisor; Esc does not abort
+  them: stop legs from F9 with `x`/`X`, or have the supervisor `intercom stop` the run); headless `pi -p` always blocks for the
+  turn and returns results inline, since nothing drains a follow-up after the process exits.
+- **Answer a waiting worker promptly.** 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. 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.
+  steering is not a substitute for ending the turn. After requesting cancellation, the stopped report
+  arrives as a completion follow-up; 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

package/docs/MONITORS.md

@@ -6,7 +6,8 @@ preserving the cached system prefix. During a long run it can call `timer` with
 to refresh the clock. This is sampled wall-clock time, not a continuously updated model sense.
 
 Use `timer arm` for a known time. Use `monitor arm` when a program can report the event you care
-about. Sub-agent completions and Exocom messages already wake the supervisor automatically.
+about, never one whose only job is to elapse time. Sub-agent completions and Exocom messages already
+wake the supervisor automatically, so neither tool should wait on them.
 
 ## Background programs
 
@@ -36,13 +37,70 @@ Adapters can use native file/system subscriptions, a program's streaming API, or
 polling inside the program when no subscription exists. The model does not run a polling loop.
 Print one short event per line to stdout; send diagnostic chatter to stderr. Flush output promptly
 (for Python, use `-u` or `flush=True`). Repeated identical lines are ignored for that watch.
-Keep complete logs in the program's normal log file if they are needed later.
+Monitor stdout and stderr are captured automatically within fixed limits. For a complete, unlimited
+transcript, keep using the program's own log file; monitor capture is bounded diagnostic evidence.
 
 The model can continue independent work while a monitor runs. Events wait while it is busy and
 arrive together at an idle boundary. When only the event remains, it should end its turn. Natural
 requests such as “let me know when this build finishes” are enough; tool parameters are for the
 model or an integration, not something the user needs to manage.
 
+## Visibility
+
+An armed timer or active monitor shows as a row in the agent widget and the F9 / `/agents` overlay,
+beside the sub-agents: `◉ <label>  <id> · <mode> · <elapsed> · deadline in <remaining>` for a monitor
+(`<id> · output · k/N events` as events arrive), `⏰ <label>  <id> · fires in <remaining>` for a timer
+(just `⏰ <id>  fires in <remaining>` when the timer has no label).
+The countdown replaces the stall clock, so a quiet watch is never `⚠ stalled`. While a process runs,
+its latest useful stdout/stderr progress is displayed on its row, including partial lines and carriage-return
+progress updates. Tails ingest every chunk immediately; their display is updated at the existing UI
+frame cadence instead of rebuilding the full row for every chunk. Terminal events and cancellation
+include the final tail immediately. This is a bounded, sanitized UI projection: it does not create a
+model wake or consume an output-event allowance. `⏎` opens the command, cwd, times, bounded live output tails and last 40 event
+lines (monitor), or the fire time and message (timer); `x` cancels that
+one watch like `monitor cancel` / `timer cancel`. These are rows, not agents: no steer, `X` stop-all
+skips them (`intercom stop { to: "all" }` likewise leaves them alone; cancel with `monitor cancel` /
+`timer cancel` or `x`), and they never count in `N agents` or reach telemetry. A finished row settles
+and leaves like an async run: its final ✓/✗/■ goes to the tree change stream (telemetry excluded), not
+to the screen.
+
+## Session-owned logs and results
+
+`monitor { action: "result" }` lists retained captures, including completed jobs; add `id` to read one.
+The default read shows a short tail; `full: true` reads the complete **retained** capture, not bytes
+already discarded by the capture limit. This is retrieval, not a wait: do not poll it for completion.
+`list` still lists only active watches. IDs are activation-unique so reload cannot confuse an old log
+with a newly launched process.
+
+The archive belongs to the **whole session tree**, not only the active conversation branch.
+`result` can therefore list or retrieve a log from a sibling branch that is absent from the current
+transcript. Branch navigation changes the transcript, not archive visibility or ownership. Both
+retention budgets below are shared across all branches and remain shared after reload.
+
+A terminal event or cancellation saves one bounded stdout/stderr snapshot and outcome as a custom
+entry in the owning Pi session. An expandable operator-only log card exposes it without adding the
+raw log to model context or triggering another turn. No per-chunk session entries or sidecar files
+are written. Shutdown/reload stops processes and saves their available diagnostics; resume can read
+the snapshots but never restarts the processes. A hard crash can lose a running job's not-yet-saved
+capture. In a non-persistent session, logs remain in memory only.
+
+Deleting the owning session file removes its stored logs with it. Reload, ordinary shutdown and
+context compaction are not deletion. Forking/copying a session can copy its historical log entries;
+each copy then owns its own data, with no shared external file to orphan or delete accidentally.
+Backups and exports may also retain copies; deleting the original session is not secure erasure
+of those copies. Treat captured stdout/stderr as session data: printed credentials, signed URLs
+and other secrets can be stored in the JSONL. Sanitize/redact sensitive output in the producing
+program before capture. Display sanitization is not secret redaction; requesting `result` returns
+the selected retained text to the model, even when it originated on a sibling branch.
+
+Each capture retains the last 16,384 UTF-16 code units of stdout and stderr independently, plus at
+most 16,384 code units of status text. Live F9 tails retain 4,000 code units per stream. The journal
+admits at most 64 terminal records and a conservative 2 MiB cumulative serialized-data budget per
+session (JSON escaping, metadata and envelope allowance included). Historical entries, even unknown
+formats, consume that budget; reload does not reset it. Once exhausted, new captures remain only in
+the bounded runtime history, and `result` explicitly reports the storage limitation. Truncation and
+persistence failures never claim a complete or durable log.
+
 ## Lifetime and limits
 
 - `list` shows active watches; `cancel` with the returned `id` stops the owned process tree and
@@ -56,7 +114,8 @@ model or an integration, not something the user needs to manage.
   to four per batch, and reports omitted older events if a busy model cannot keep up.
 - Keep Pi open. Watches are in memory and stop on shutdown, reload, or session replacement;
   they are not restored on resume. A headless `pi -p` invocation that exits after its answer is
-  not a persistent monitoring service.
+  not a persistent monitoring service: an alarm or event wakes it only if it lands before the single
+  turn settles, and the arm result says so instead of inviting the model to end its turn.
 
 ## Permissions and architecture