# Architecture

See [`docs/README.md`](./README.md) for the canonical doc set index.

The design contract for pi-persona — the model, the binding invariants, the module map, and the
runtime seams. This is the **canonical design reference**: on any conflict, this document and the
invariants below win. For the user guide see the [README](../README.md); for the orchestration layer
in depth see [STRATEGIES.md](STRATEGIES.md); for the contributor quick-reference (commands,
conventions, gotchas) see [AGENTS.md](../AGENTS.md).

pi-persona is a single Pi coding-agent extension (`@earendil-works/pi-*`, loaded via tsx/jiti — no
build step) for **supervised multi-agent orchestration**: async workers, live steering, cross-session
collaboration, and switchable personas. It fuses three concerns — delegation/engine, coordination/bus,
persona/identity — into one cohesive, cross-OS, data-driven codebase.

## The model

| Thing | Is | Lives in |
|---|---|---|
| **Persona** | the control surface: a supervisor identity (system-prompt body) + how it orchestrates | `personas/*.md` (`persona: true`) |
| **Agent** | a unit of work that gets spawned (prompt + model + enforced tool allow/deny); does not orchestrate | `agents/*.md` |
| **Strategy** | an execution shape (vote, loop, fan-out) authored as code on the SDK | `src/orchestration/strategies/*.ts` |
| **Flow** | a declarative DAG that composes strategies into phases with `needs` edges + gates | `flows/*.flow.json` |
| **Team** | a named roster of agents a strategy runs over | `teams.yaml` |
| **Contract** | the structured shape a sub-agent returns, so votes/judges tally | `contracts/*.contract.json` |

A persona binds to an orchestration mode → which selects a built-in shape or a strategy/flow → which
runs over a roster of agents → lowering to engine primitives + deterministic JS reducers. A persona
file *is* an agent file with `persona: true` plus the orchestration grammar; one frontmatter engine
parses both.

Persona names are data, never dispatch keys. Optional `delegation:` fields apply generic gates to any
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
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
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.

### The effort ladder (make the simple case simple; complexity is opt-in)

- **L0 — prompt-driven.** Just the persona body + the `delegate` tool, no orchestration block. The
  supervisor LLM fans out by its own judgement ("research X, Y, Z" → one sub-agent per item). Absent
  an orchestration block ⇒ pure L0.
- **L1 — declarative shape.** A persona `orchestration: { mode: parallel|pipeline, roster }` (or the
  `council:` tool form) runs a built-in strategy deterministically.
  A caller may borrow another installed persona's declared council with `council({ persona: "name" })`;
  this resolves configuration only and never activates or inherits authority from the target persona.
- **L2 — strategy file.** `src/orchestration/strategies/<name>.ts` on the Strategy SDK drives a
  richer shape (magi vote, critic loop, debate).
- **L3 — flow file.** `flows/<name>.flow.json` composes strategies into a resumable DAG.

You climb only when you want determinism, structure, or reuse. Nothing forces the higher tiers.
The `council` tool is a gateway to all installed strategies, not a universal instruction to vote on
routine work. Choose a strategy when its topology adds value; MAGI and Judge retain their specialized
persona focus. A caller can supply ephemeral `members` with inline roles/models/skills instead of a
named team, without persisting a team or switching personas.

## Binding invariants (I1–I7)

These are the guardrails a contributor must not violate. They are enforced in code, not by convention.

- **I1 — Child-process is the correctness baseline.** `ChildProcessEngine` (`engine/child.ts`, spawns
  `pi --mode json -p`) is the reference backend; `InProcessEngine` (`engine/inproc.ts`,
  `createAgentSession`) is the runtime **default** but a swappable optimization behind the
  `StrategyEngine` seam. Behavior must hold on the child backend first; worktree isolation always uses
  the child engine. Opt to the baseline with `PI_PERSONA_ENGINE=child`.
- **I2 — Strategies are trusted project code, NOT a security sandbox.** Gated by Pi project-trust; the
  SDK is a constrained API *by convention*. Safety comes from **runtime limits, not isolation**:
  `RUN_LIMITS` (`maxChildren`, `maxConcurrency`, `budgetTokens`, `timeoutMs` idle window) are enforced
  by the SDK on every `agent()` call and by the engine per child. Concurrency is shared across all
  calls in one SDK instance; token admission uses completed usage and is rechecked after queueing, so
  active legs can overshoot it. Nesting depth is not one of these numeric knobs — it is structural,
  capped at 1: a child's whole pi-persona extension activation short-circuits under
  `PI_PERSONA_DISABLE=1` (the **fork-bomb guard**), so it registers NO tools at all —
  `delegate`/`council`/`orchestrate`/`flow` included. On the child engine this is a one-shot env var
  set on each spawned process; the in-process engine instead shares one Node process across
  concurrently-building sub-sessions, so it ref-counts the guard (`inproc.ts`) to keep it set until the
  LAST one finishes. The in-process engine also excludes `ORCHESTRATION_TOOLS` from the child session
  directly (`engine/inproc.ts`) as a
  second line of defense, in case anything else ever left the extension active. `PI_PERSONA_LEG=1`
  rides alongside `PI_PERSONA_DISABLE` — a **dedicated** worker-leg marker, distinct from the
  user-settable `PI_PERSONA_DISABLE` kill switch, that a companion extension (e.g. pi-persona-mind)
  reads to tell a real delegated leg from a disabled supervisor. Never claim isolation from
  `fs`/`net`/`process`. The param schema and other convenience checks stay **lenient** (warn, never
  hard-fail) for the same reason.
- **I3 — Per-run pinning.** A run pins `contract@hash` at start; hot-reload affects **new runs only**;
  an active run never changes schema/logic mid-flight. `makeEngine`/`makeInProcessEngine` pin the
  contract on first use and reuse the frozen snapshot for the whole run.
- **I4 — Capabilities enforced at call time, never prompt-only.** Every tool call, delegate, and bus
  action passes one `EffectiveCapabilities` (`core/capabilities.ts`: `tools`, `delegateTargets`,
  `canUseBus`), resolved once on persona activation (deny-wins; `allow` present ⇒ allowlist; absent ⇒
  default-allow). Prompt text is advisory only. Declarative delegation gates are checked before spawn:
  required briefs, contract defaults, parallel write ownership/overlap, and stale concurrent verifier
  topology. Restricting `tools` keeps `delegate` unless explicitly denied; `canUseBus` is OFF only when
  the persona explicitly denies `intercom`.
- **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.
- **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 —
  the engine runs the shape; the LLM can't opt out, only do its part). A persona picks exactly one.
  Mandatory hand-off preserves runtime status: only `ok:true` becomes a ruling; failure/cancellation
  remains visibly unresolved and its fenced output is evidence, never an implicit success.
- **I7 — Adoption is a success criterion.** The opportunistic path must be *engineered to actually
  fire* — under-delegation is the explicit failure to avoid. The `delegate` tool description is
  compelling and model-agnostic; opportunistic persona bodies coach delegation with concrete
  heuristics; success is measured by delegations actually happening, not by the capability existing.

## Design decisions (D1–D7)

- **D1 — One engine interface, two backends.** The `StrategyEngine` seam makes strategies
  backend-agnostic; the concrete backend is an optimization/isolation choice (see I1).
- **D2 — One shared `core`.** A single frontmatter/YAML parser, one permission engine, one discovery,
  one config, one contract module, one set of env constants. `core/*` is **pure** (no Pi imports) and
  unit-tested — removing a whole class of two-parser / naming-mirror drift bugs.
- **D3 — Three authoring surfaces, data-driven.** `agents/*.md`, `strategies/*.ts` (files on a core
  SDK), `flows/*.flow.json` — all lower to engine primitives + JS reducers. Built-in strategies ship
  **as files** and double as reference examples.
- **D4 — Personas are a thin layer over orchestration.** persona = identity + optional default
  strategy/flow/council + generic delegation policy; the persona file is the control surface. Runtime
  code must not branch on a persona name.
- **D5 — Bias mitigations baked into the reducers.** Anonymise authors, shuffle order, keep-best
  fallback, preserved dissent, invalid-output quarantine — deterministic JS, safe by default (see
  [STRATEGIES.md](STRATEGIES.md#bias-guard-invariants-do-not-fix-these)).
- **D6 — Cross-OS by construction.** In-process avoids IPC entirely; only the opt-in cross-process
  bus needs OS-specific transport (Unix socket vs Windows named pipe), confined to the broker — so no
  fragile per-OS code lives in strategies.
- **D7 — Contracts are schema-defined and hot-editable.** The return contract lives in an editable
  `contracts/*.contract.json`; reducers read fields generically. Add/remove fields without
  recompiling. Hardened by I3 (hot-reload for new runs only). The contract both **instructs and
  validates**: when a spec carries `outputContract`, each engine appends `contractInstructions(def)`
  (the format, derived mechanically from the same pinned def it validates against) to the member's
  task — so ANY agent can be convened by a voting strategy, not just those whose `.md` hand-writes
  the JSON format.

## Module layout

Domain dependencies remain downward-only and acyclic: `core ← all`; `engine`/`bus → core`;
`orchestration → engine + bus + core`; `persona → orchestration + core`; the Exocom transport and
ledger → `core + bus`; `tools`/`ui → lower layers`. `src/exocom/install.ts` is deliberately the
composition adapter for that feature, colocated with Exocom but allowed to wire extension, persona,
engine, telemetry, UI, and tool surfaces; it is not part of the transport/domain layer.
`src/extension/*` contains extracted factory internals (which must not import `extension.ts`), while
`extension.ts` remains the package entry and composition root (`package.json` `pi.extensions` →
`./src/extension.ts`).

- **`src/agents/`** — the agent definition (`agent.ts`: `AgentConfig`/`parseAgent`, the
  `persona: false` sibling of the persona parser; both share one frontmatter engine).
- **`src/core/`** — pure kernel (no Pi imports, unit-tested): `frontmatter`, `permissions` +
  `capabilities`, `contract` (+`parseContract`), `config`, `discovery`, `seed`, `fence`
  (`fenceUntrusted` / `attributeInbound`), `ownership` (`findWriteSetOverlaps` /
  `validateParallelWriteSets` / `writeSetPathError` — parallel write-set overlap, shared by
  `delegate` and `map`'s `ownership` param), `pi-compat` (`MIN_PI_VERSION`, `installedPiVersion`,
  `satisfiesFloor` — the one place the supported host floor is declared; `package.json`
  `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`
  (`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
  readings and the prompt-cache rule that sets each one's granularity), `types`.
- **`src/engine/`** — "run an agent → `AgentResult`", backend-agnostic: `child.ts`, `inproc.ts`
  (default), `adapter.ts` (child-engine adapter), `fallback.ts` (provider fallback),
  `spec-preflight.ts` (the one unknown-agent/unknown-contract preflight shared by both engines),
  `change-report.ts` (`captureStatus`/`diffStatus`/`renderChangeReport` — the files-changed report
  `src/extension/engine.ts` appends to a non-worktree leg's result; pure over the injected `GitExec`
  from `worktree.ts`), `async.ts` (async tracker / peek), `worktree.ts` (git-worktree isolation),
  `stream.ts` (event → state), `handles.ts` (one bus-handle sequence shared by BOTH engines),
  `signals.ts` (`combineSignals`).
- **`src/orchestration/`** — the heart: `sdk.ts` (the Strategy SDK), `strategy.ts` (registry +
  `knownParams`), `strategies/*.ts`, `voting.ts`, `judge.ts` (anonymise-for-judge), `reducers.ts`,
  `roster.ts` (teams + `rosterSpec`), `flow*.ts` (DAG + JSONL journal + gates), `render.ts`.
- **`src/bus/`** — coordination: `inproc.ts` (handle-based mailbox: send/ask/reply/onMessage),
  `contact.ts` (child `contact_supervisor`), `peers.ts` (child `contact_peer`), `broker/` (cross-process
  relay, on by default: `paths`/`framing`/`messages` pure, `host`/`client` over `node:net`).
- **`src/exocom/`** — the external peer plane (the exocom section below): `plane.ts` (lifecycle —
  bind/join/teardown + reconnect), `activation.ts` (the exact optional-value CLI shim), `codes.ts`
  (persistent four-character alias allocation), `scope.ts` (home identity versus selected scope),
  `registry.ts` (scope-selected presence + stale pruning), `paths.ts` (pure path layout),
  `envelope.ts`/`inbound.ts` (wire format + the pure guardrailed delivery chain: hop cap, dedup,
  budgets, truncation, fence/attribute), `limits.ts` (constants), `guards.ts`
  (`SenderBudget`/`SeenMessages`), `ledger.ts` (scope JSONL work ledger), `untrusted.ts`
  (`untrusted()`/`UNTRUSTED_MAX` — the ONE sanitizer every surface rendering a peer-authored ledger
  field runs first, so a hostile peer's escapes or instruction-shaped text never reach output
  unfenced), `status.ts` (`formatLedgerStatus` — the ownership view `exocom_status`/`/exocom`
  render), `write-guard.ts` (`peerClaimFor`/`writeWarningReason`/`WriteWarnings` — the advisory,
  warn-once-then-allow guard on a `write`/`edit` overlapping a peer's open claim, built on
  `core/ownership.ts`'s path-overlap primitives), `wait.ts`/`gate.ts` (non-blocking join + inbound
  constrained-turn allowlist), `install.ts` (the feature's composition adapter: session-scoped plane +
  ledger + wait/tool/hook wiring).
- **`src/telemetry/`** — a generic, versioned observer/export contract for future plugins: projected
  lifecycle metadata only, never an agent-message router or control surface. See
  [`TELEMETRY.md`](./TELEMETRY.md) for privacy, retention, writer leases, and shutdown behavior.
- **`src/persona/`** — identity: `persona.ts` (parse + `expandCouncilPreset` + `composeSystemPrompt`),
  `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts`, `state.ts` (last-selected persona),
  `spine.ts` (the shared behavioral layer's SOURCE resolution — docs/SPINE.md; composition sits in
  `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
  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;
  leftover background-leg cost is published on the `persona-cost` status key).
- **`src/loader.ts`** — the discovery loader (`loadDefinitions`/`loadContracts`/`loadPresets`/
  `loadTeams`), the concrete read-side of the discovery precedence table.
- **`src/bridge.ts`** — the child-mode-only wiring, loaded instead of the full extension when
  `PI_PERSONA_BUS` is set (a broker child).
- **`src/extension.ts`** — the single `ExtensionFactory` (default export `piPersona`): still the
  only file `package.json` `pi.extensions` names. Tools/commands stay registered here; Pi lifecycle,
  prompt composition, the pending-ask tool gate, and engine construction were extracted to
  `src/extension/hooks.ts`, `src/extension/engine.ts`, and leaf helpers in `src/extension/shared.ts`.
  Those modules must not import the factory. Broker host state is declared before `installHooks` so
  shutdown cannot TDZ on `brokerHostPromise`.

## The two engines

Both backends sit behind the `StrategyEngine` seam (`run(spec, onProgress?, signal?, onSteerable?) →
AgentResult`) and enforce three independent deadlines, all classified as `failureKind: "timeout"`
(never a provider reroute): `RUN_LIMITS.timeoutMs`, an **idle window** (no events for that long ⇒
abort); `PI_PERSONA_AGENT_MAX_MS`, an **opt-in hard wall-clock cap** — a lifetime ceiling, armed once
and never reset, that settles a busy-but-non-converging child (a loop that keeps emitting) the idle
window never catches (OFF by default = unlimited, so a healthy child has no lifetime ceiling); and
`PI_PERSONA_AGENT_STARTUP_MS`, a **startup deadline** (default 300000, `0` disables) that kills a
child making ZERO progress — no completed turn, no tokens, no streamed output. It fast-fails the
"never started" case the generous idle window is too slow for — notably a headless `mcp: true` leg
whose `pi-mcp-adapter` hangs on interactive OAuth; the first real progress cancels it.

The idle window and startup deadline stay ARMED for every child, coaching or not — a blind exemption
that once disabled both while a child could legitimately block on a supervisor reply let a genuinely
stalled coaching leg run forever. Instead, when either fires, the source of truth is asked directly:
does this child have a live `decision`/`interview` ask outstanding right now? In-process consults the
bus (`hasPendingAskFrom`); the child-process engine consults the broker through the same shape
(`isBlocked`). A live pending ask re-arms the window; no pending ask means the silence is real and the
leg is killed. The hard wall-clock cap is the one ceiling that still applies unconditionally —
including to a coaching child blocked on a reply — so a supervisor that never answers still has a
backstop.

In-process deadlines and caller cancellation are armed **before session construction**; the bus
consult that re-arms idle/startup only matters after construction, since no ask can be pending before
a session exists. Cancellation settles the run and releases its bus handle; a session returned late is
disposed and a late factory rejection is consumed. Pi's resource loader does not expose forcible
cancellation — the recursive-extension guard stays held until that factory settles, so a loader that
never returns needs a Pi restart (and `PI_PERSONA_ENGINE=child` for process-level termination). Run
settlement does not promise that arbitrary in-process code has physically stopped.

- **InProcessEngine** (default) — a `createAgentSession` per sub-agent: cheaper, shares the host's
  auth/model registry, and **steerable** (inject a live user message into a running sub-agent).
- **ChildProcessEngine** (`PI_PERSONA_ENGINE=child`, the correctness baseline) — spawns `pi --mode
  json -p`, delivering the task over **stdin** (never argv — a flow-phase task would blow Windows'
  ~32 KiB command-line cap). Worktree isolation always uses this engine.

Tool grants have three distinct states on both engines: absent inherits Pi's session defaults, a
non-empty array is an allowlist, and an explicit empty array means no tools (`--no-tools` on the
child backend); denylists apply independently via `excludeTools`/`--exclude-tools`.

A spec naming an agent or output contract that isn't installed fails before anything spawns, on both
backends alike (`engine/spec-preflight.ts`): the message names what IS installed, capped at 12 names.
The `delegate` tool runs its own earlier check with a different cap — `unknownAgentError`/
`unknownContractError` (`src/tools/delegate.ts`) reject a typo before either engine is reached, listing
up to 16 names. Same idea, two layers, two caps — see docs/REFERENCE.md's example.

`isolation: worktree` is fail-closed. It requires a clean Git checkout so the detached `HEAD` view
cannot silently omit staged/unstaged/untracked supervisor work; a non-repository, dirty checkout,
worktree creation failure, missing diff artifact, or an artifact over the return limit fails the leg —
the base engine is never invoked against the real tree as a fallback. The diff returns to the
supervisor before the temporary tree is removed, and every git call is asynchronous so the extension
host keeps rendering, ticking timers, and serving broker sockets while a large checkout runs.

Transient retries inside one agent session belong to the host **Pi runtime**'s `retry.*` settings, not
a persona contract — pi-persona neither parses retry notation nor schedules its own backoff. Both
backends read the same resolved global agent directory (`PI_CODING_AGENT_DIR` for spawned children).

`buildEngine` wraps the chosen backend with **provider fallback** (`engine/fallback.ts`): a run whose
model's provider fails at call time (auth/outage/5xx/model-not-supported) can retry the same model id
only when the selection was unpinned/default, through the data-driven provider policy for that model
family. A provider-qualified `spec.model` is an explicit pin and stays strict by default. Only
`failureKind === "provider"` reroutes; abort/timeout/contract/unknown/agent are terminal — this
prevents an explicitly selected OpenAI or native Claude leg from silently moving to an unrelated paid
provider. (`"verification"` is a further terminal value that never appears on an `AgentResult` — see
`map`'s `verify` param in [`docs/STRATEGIES.md`](./STRATEGIES.md).)

Strategy/council/flow runs use a different, explicitly authorized recovery policy: the selected model
is tried first without arbitrary provider reroutes, then `makeSDK` may retry a `provider` or
`unknown-model` failure ONCE on the supervisor's current model. This main-only exception also applies
to saved and inline-pinned assignments; ordinary delegate provider pins remain strict. Missing main
models, repeated same-model attempts, stop/timeout/contract/agent/infrastructure failures, and exhausted
child/token budgets do not recover. Both attempts are accounted, and a warning plus result metadata
identify the switch. A per-role model assignment can supplement the legacy per-agent assignment;
preflight model selection includes external arbiters and other declared agent-valued parameters.
Live tree and telemetry labels use those participant identities for auxiliary actors too, with
inline model pins taking precedence. If distinct full roles share a short display hint, the display
keeps the hint (with `#N` suffixes for repeated node keys) but omits the uncertain model label rather
than borrowing another role's choice. Routing still resolves the full role key, not the display hint.

### MCP (and other `session_start`-scoped extensions) in sub-agents

**A sub-agent does NOT share the supervisor's MCP session, and an in-process sub-agent gets NO MCP at
all.** MCP servers are provided by a separate extension (`pi-mcp-adapter`), which opens its
connections inside a `session_start` hook:

- The **in-process engine** builds a fresh `createAgentSession` and only calls `session.prompt()` — it
  never fires `session_start` (that requires `AgentSession.bindExtensions`). `pi-mcp-adapter` registers
  its `mcp*`/direct tools at load (they *appear*) but never initializes: calls come back **"MCP not
  initialized"** — the tools are present but dead.
- The **child engine** spawns a real `pi -p`, whose normal startup DOES fire `session_start`, so
  `pi-mcp-adapter` initializes as that child's **own** connection (its own stdio/HTTP clients) — a
  *separate* MCP session that does not see the supervisor's MCP workspace/interactive-shell state.

Firing `session_start` for every in-process sub-agent is deliberately NOT done: it would spin up the
full MCP fleet N times per fan-out, and the adapter's OAuth/UI/consent machinery assumes an interactive
session. There is no cheap way to *share* one live MCP connection across sessions here.

**The `mcp: true` opt-in — a delegable MCP leg.** Because the child engine fires `session_start`, a
sub-agent that needs live MCP tools is routed there: mark the agent `mcp: true` in its frontmatter, or
pass it on a `delegate` task (`AgentRunSpec.mcp`). The engine runs that leg through `childEngineAt(root)`
— the same mechanism `isolation: worktree` uses for MCP, minus the git worktree — connecting to the
SAME servers from `~/.pi/agent/mcp.json`. Cost is one `pi` spawn per leg; for an **HTTP** server it is
just a client reconnect, not an N× stdio fleet spawn.

**Shared state via a server-keyed backend.** The child gets its own MCP session, not the supervisor's
handle — but a server that keys state (workspaces, shells, artifacts) by a **session id passed as a
tool argument** lets a child that reconnects to the same HTTP endpoint AND is handed that session id
operate on the SAME server-side state. Put the session id in the task packet. (A stdio server whose
state lives in-process is genuinely separate — `mcp: true` there gives the leg its own clean session.)

**Guidance.** Default: treat MCP as a **supervisor capability** — do MCP-dependent work up top and
hand sub-agents the resulting **artifacts** to reason over. When a leg must DRIVE MCP itself, delegate
with `mcp: true` and pass the session id. Do not over-restrict such an agent's `tools` allowlist, or
the `mcp*` tools get filtered out.

## The spine — one shared behavioral layer

An optional layer of behavioral baseline (scope discipline, verification, how to treat another
agent's text) that a persona would otherwise restate in its own words. [SPINE.md](SPINE.md) covers
the content and the A/B that gates its default; the architectural shape is:

- **Where it sits.** Between Pi's base prompt and the persona body — the stable, cacheable *prefix*,
  the opposite end of the prompt from the per-turn delegation brief. `composeSystemPrompt(base,
  persona, spine)` (`persona/persona.ts`) is the one supervisor-side composition: a persona-less turn
  still gets base + layer, and a `replace` persona (which drops Pi's base) keeps the layer as its only
  scaffolding.
- **Two texts, two selectors.** The supervisor reads `spine.md`, a delegated leg reads
  `spine.worker.md` — a leg runs headless, so "confirm irreversible actions with the user" would make
  it stall or hand the question back as its deliverable. `PI_PERSONA_SPINE` / `PI_PERSONA_SPINE_LEGS`
  (the legs' selector follows the supervisor's unless set) each take off / on / an explicit path; `on`
  resolves the user dir before the bundled `prompts/`, a path never falls back to another file.
- **Source resolution is pure, composition is per-role.** `persona/spine.ts` answers only *which file,
  if any* — over an injected reader, so the whole precedence table is unit-testable without a disk.
  The legs' text is prepended by each engine (`engine/inproc.ts`, and `--append-system-prompt` on the
  child adapter), so a leg keeps Pi's full base prompt either way.
- **Off by default, opt-out at both ends.** Unset ⇒ every composition above is byte-identical to a
  pre-spine pi-persona. Frontmatter `spine: false` opts a persona or an agent out, and a persona's
  opt-out carries to the legs it spawns. A file that is unreadable, empty, or over `MAX_SPINE_BYTES`
  (64 KiB, refused on its `stat` so the bytes never enter the process) degrades to a warning and no
  layer — a prompt file is never a hard failure.

## Runtime metadata is not a new user request

The supervisor system prompt carries one fixed runtime-context rule, after persona/spine composition
and before the time anchor and live rosters. It applies with no persona, append/replace personas and
`spine: false`: it is protocol guidance, not an activation of the optional behavioral spine. Identity,
skill-prefetch, clock and routine status metadata do not require repeated acknowledgements. Initial
setup and actionable questions still require attention; explicit user questions about metadata are
answered normally. Skill availability alone is not evidence that instructions were loaded or used.

The rule contains no interpolated handle or changing counters, creates no conversation message and
does not redact assistant history. The pre-name identity bootstrap remains actionable and disappears
once naming succeeds. An old session may contain repetitive prose; updating the extension does not
rewrite it. Reload extension code with Pi's `/reload` (when delegated work has settled), not merely
`/persona reload`, which only reloads persona data.

## Time awareness — one rule, three granularities

Pi's base prompt carries no date and no time, so from inside a turn five minutes of work and five
hours look identical. `core/time.ts` renders the three durations that fix that, and the rule that
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.
- **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 —
  one bucket for the first quarter hour, then quarter hours, then whole hours, then days — which
  steps 27 times in a full day where a minute-granular label would step 1440. `pi-persona-mind`
  makes the same trade one scale coarser for the same reason.

The anchor answers *"how long have I been on this problem"* rather than *"what turn is this"*
because it reads pi's `SessionHeader.timestamp` — the first entry of the append-only session file.
That is what makes it survive **compaction** (the system prompt is re-sent, never summarized) and
**restart** (`/resume` re-reads the original start, not the resume time). Branching mints a new
session file, so the reading restarts there — correctly: the line claims the life of *this* session.

Both readings state an elapsed time as fact, so both refuse the inputs that would make that a lie.
A timestamp is accepted only when it names exactly one moment — `Date.parse` reads a zone-less
date-time as the *receiver's* local time, so two peers would print two different ages for the same
frame — and only when it is plausible: a peer age outside a 30-day window, or a session start in
the future or older than a year, is corruption rather than a long wait, and degrades to an honest
label or to no anchor at all. A peer's timestamp stays a peer's claim; bounding the window narrows
what it can assert, it does not authenticate it.

## The three communication planes

Three planes with **disjoint vocabularies** — a concept name lives in exactly one, so "progress" is
never simultaneously a telemetry event, a routed message, and a UI source of truth.

- **EngineEvent** — runtime lifecycle/telemetry (`started · token · tool_call · completed · failed ·
  usage`). Feeds derived UI; never routed as an agent message.
- **Bus Msg** — semantic agent↔agent communication (`progress · decision · interview`, and sibling
  peer sends). `src/bus`. `progress_update` is a Bus message only, not an EngineEvent.
- **ProgressView** — a derived, read-only UI view computed *from* EngineEvents. Never authored, never
  a source of truth. The `f9` agent tree and `peek` digest are ProgressViews.

Steering is a supervisor-to-child control action, distinct from semantic Bus messages; requesting
steering does not establish that an active blocking join has been interrupted. The peek digest is
always a read-only ProgressView.

External telemetry is not a fourth communication plane: it is a generic observer/export contract that
future plugins may consume or produce, not an exclusive pi-persona protocol. It observes projected
events and cannot route, reply, steer, or otherwise control agents.

## The comm plane in practice

- **In-process bus** (`bus/inproc.ts`) — a handle-based mailbox: `send` (one-way), `ask` (blocks for a
  reply), `reply`, `onMessage`. `contact_supervisor` (child→supervisor, gated by `coaching: on`) and
  `contact_peer` (sibling→sibling) are the child-side tools bound onto it. Each unread inbox holds at
  most 200 messages; overflow evicts an old one-way note first, and an inbox full of live asks rejects
  new delivery rather than stranding a sender. Ask settlement (reply, timeout, abort, departure, or
  failed delivery) releases its timer/listener and unread entry; a previously retained question stays
  readable with `expectsReply: false`, so old questions never advertise an active reply id.
- **Sibling peer comm** — a strategy opts a run in via `AgentRunSpec.peers` (gated by `canUseBus`). The
  child gets `contact_peer` (`list`/`send`, ONE-WAY so peers can never deadlock; per-engine-instance
  scoping; a 20-send budget and an 8,000-character body limit, enforced before consuming a send). The
  engine's **delivery bridge** steers incoming bus messages into the child session, fenced with the
  sender attributed OUTSIDE the fence (`attributeInbound`, shared by both engines so the anti-spoofing
  format can't drift) — the same bridge delivers the supervisor's `intercom send`. `debate`/`pair`
  always use peers; `map`/`synthesize` opt in via `params.peers`; `magi`/`judge`/`fanout`/`compete`/
  `council-rounds` stay peer-less by design (independence is a bias guard — see
  [STRATEGIES.md](STRATEGIES.md#bias-guard-invariants-do-not-fix-these)).
- **Cross-process broker** (on by default; `PI_PERSONA_BROKER=off` restores pre-broker spawn;
  `bus/broker/`) — gives child-process runs, every `isolation: worktree` leg, and every `mcp: true` leg
  the same comm plane and **steer** the in-process ones have. It is a session-scoped (POSIX socket /
  Windows named pipe under the session id), supervisor-hosted relay into the local `InProcessBus`: a
  connected child is indistinguishable from an in-process one, so the supervisor side (intercom, idle
  notifier, f9, peek) is unchanged by construction. Off ⇒ the host never starts and the child spawns
  byte-identical to pre-broker pi-persona. Ask failures echo the originating `msgId` so the client
  rejects the right request immediately, and a client cancellation propagates only to that connection's
  own host ask. `extension/broker-host.ts`'s `SupervisorBroker` owns the lifecycle: it starts the host
  lazily on the first child-engine build, warns once on a failed bind (children built while it's down
  spawn without a bus endpoint, so they never burn connect backoff against a dead socket), and the next
  build retries; `/doctor` surfaces its state on one line. A dropped client connection flips the
  child-side bridge to `⇄ offline` and fails a fresh ask fast rather than hanging.

### Presentation is a projection, not another comm plane

The semantic payload and its human presentation have different lifetimes. A result remains complete
for the supervisor and for explicit retrieval; the default TUI projection is deliberately small:

- async completions are coalesced and bounded fairly across legs; `intercom { action: "result", to:
  "<run-id>" }` retrieves one retained result in full and consumes a still-pending duplicate
  notification;
- drained bus messages have a separate session-local retention window: at most 256 messages and
  256,000 body characters across the bus, FIFO eviction. `intercom { action: "message", messageId:
  "<message-id>" }` retrieves a retained message; it never interprets a message id as a run id.
  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);
- async launch cards and targeted Intercom call headers use the worker's canonical alias/model,
  matching the tree rather than promoting its routing ID to display identity. Launch/control receipts
  persist identity snapshots for history rendering; aliases never become routing keys. Colliding
  aliases carry a secondary ID, and legacy receipts without a recoverable name retain their ID fallback.
  Accepted steering receipts retain the exact sent message: collapsed cards preview it, expansion
  shows all sanitized text and the diagnostic ID. A queued receipt does not prove the worker acted;
- follow-up cards (`pi-persona`, exocom) retain their complete semantic content but render a bounded
  preview until expanded; terminal escape/control sequences are removed from the visible projection;
- the sticky agent and exocom widgets have fixed row budgets — F9/`/agents` and paginated
  `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;
- 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,
  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.

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.

## exocom — the external plane

`src/exocom/` is a separate plane from everything above: every plane in "the comm plane in practice"
is **internal** to one supervisor's own run — hierarchical, keyed by that session id, talking to
children *it* spawned. **exocom is flat and external**: independent, top-level Pi instances sharing
one explicit scope — normally the same workspace, or a Pi that joined by code — discover each other
and message peer-to-peer, with no parent/child relationship. (intercom = internal comm; exocom =
external comm.)

Exocom supplies fenced one-way postcards and presence; chat `message` never mutates shared work
state. Separately, a workspace work ledger (`ledger.ts`, tools in `tools/exocom-work.ts`) records
claims/asks/answers/progress/releases. `exocom_ask` canonicalizes its target through
`plane.resolvePeer` (raw session ids on the ledger, never the display name); registry display name is
keyed by `from_session`, never the envelope's self-reported `from_name`. A pending ask constrains the
turn (`gate.ts`: answer/decline plus read-only tools) behind a bounded `pendingAskPrompt`.
`exocom_wait` is non-blocking. Clean shutdown releases this session's claims/asks; if that best-effort
write fails, the vanished owner is pruned on the next ledger transaction (live registry sessions are
the lease), and `expireWaiters` wakes any waiter left behind instead of leaving `exocom_wait` armed
forever. This gate is cooperative coordination for participating local Pi processes — not filesystem
authorization, not isolation from another same-user process, and not a delegate/council or task/run
replacement.

- **Opt-in, OFF by default.** `PI_PERSONA_EXOCOM=1` or bare `--exocom` joins the current workspace;
  `--exocom=Ab0T` joins an existing scope by its exact, case-sensitive four-character Base62 alias
  from another cwd (Pi's flag API can't express an optional-value boolean, so the extension recovers
  the equals form from raw argv). Unknown/malformed/conflicting codes fail closed rather than falling
  back to the caller's workspace; selection is frozen for the session. Participation also requires
  the active persona's `canUseBus` plus at least one obligation closer
  (`exocom_answer`/`exocom_decline`), re-evaluated on every persona switch — a persona that loses
  either leaves the registry rather than advertising a peer that could be permanently wedged by an
  inbound ask, and rejoins once an admissible persona is active. OFF ⇒ no bind, no registry entry, no
  tools registered.
- **Discovery — a scope-selected file registry, not an elected hub.** A persistent alias map under
  the agent directory resolves each four-character code to its full 24-hex workspace identity
  (allocation is atomic, collision-aware, bounded); the code is a routing convenience, never the
  storage identity. Each instance binds its own socket (POSIX) / named pipe (Windows) and
  self-registers one JSON entry under `<agentDir>/persona/exocom/<workspace-hash>/agents/<session-key>.json`
  (a hash of the session id, so a read drops any entry whose filename doesn't match its own
  `session_id`), heartbeating it; discovery is just reading that directory. Dead-pid and
  stale-heartbeat entries are pruned on read — no host election, no failover. Cleanup is
  ownership-aware (`session_id` + endpoint + signing key) and atomically claims an entry before
  deletion, so a failed/replaced session cannot erase a live replacement's slot.
- **Workspace identity is the Pi's actual cwd.** The chosen scope controls registry, endpoint, ledger,
  and artifact paths but never overwrites the member's home workspace identity. Peer lists, the
  standing brief, and `/exocom` label a peer as same-workspace or external without exposing its
  absolute `cwd`. External peers are full Pi instances that can inspect files in their own workspace;
  paths are never implicitly shared.
- **Postcards plus a durable, non-blocking join.** `exocom_send` returns a `msg_id` immediately; a
  reply is another `exocom_send` with `in_reply_to` set. `target: "*"` broadcasts postcards
  best-effort (one unreachable peer doesn't fail the rest). Work coordination is separate:
  `exocom_ask` commits an obligation to the ledger, `answer`/`decline` settles it, and `exocom_wait`
  arms a bounded idle wake rather than blocking. The signed frame is a wake signal; the ledger remains
  the source of truth if delivery is deferred.
- **Cross-workspace writes are advisory-only in v1.** A repository-relative claim path has meaning
  only in the workspace that owns the selected scope, so a member whose home workspace differs from
  the scope cannot `exocom_claim` (the tool and the signed-frame receiver both reject a foreign
  claim) — it can still send, inspect its own files, ask, answer/decline, wait, and release its own
  asks. Multi-repository write coordination would need a versioned resource namespace; paths from
  unrelated repositories are never compared as if they named the same files.
- **Reply routing is session-stable.** `exocom_list` shows human display names (`name`/`name#2`);
  sends and inbound reply hints use `name@<96-bit session hash>`, so a retained qualified target
  stays valid after a rename. Ambiguous suffix matches fail closed rather than guess. The
  authenticated registry entry (endpoint + signing key) is cached with the bounded inbound context,
  so a stale/pruned sender can't be retargeted to a same-name twin. The reply hint is CONDITIONAL —
  reply only if it changes what someone does — so a settled point can keep running on agreement and
  thanks instead of a bare `Reply:` making answering the default.
- **Identity is session-stable, persona is presence metadata.** `extension/identity.ts` owns one
  handle independent of Exocom. `agent_name` names a standalone session; `exocom_name` does the same
  while Exocom is active and refreshes presence immediately. A chosen name persists in a session-bound
  entry, survives resume/reload/persona changes, and is not inherited by a fork with a new session id;
  generic persona/agent names are rejected. Before selection, the `context` hook supplies the
  actionable naming bootstrap to ordinary turns and custom Exocom wakes; after selection it injects
  no identity pseudo-turn. `exocom_name` only replaces the display label — the
  registry key stays the session, so a rename can't take over another peer's slot or its inbound
  replies, and changing persona never changes the key or grants authority over another peer. Delegated
  workers keep the leader's `delegate.name` from launch, including peer/broker display labels.
- **Fenced and attributed from the REGISTRY, never the envelope — the security core.** An inbound
  message is head-truncated and delivered under a header the RECEIVER writes, above a body quoted by
  `fencePeer` (the peer flavor of `core/fence.ts`'s `fenceUntrusted`/`attributeInbound`). Attribution
  sits OUTSIDE the fence so a payload can't spoof its sender by closing the block, and the label comes
  from the registry entry keyed by the connecting session, never the envelope's self-reported
  `from_name`. A message over the inline budget spills to a scope-selected artifact file (a small
  preview stays inline); the spill descriptor (`preview`, `path`, `size`) is verified at the
  RECEIVER's transport boundary before anything reaches its model — the path must be the selected
  scope's own `artifacts/<msg_id>.txt`, a regular unlinked file whose size matches the declared one
  and sits between the inline cap and `ARTIFACT_MAX_BYTES`. The receiver then reads through one held,
  identity-checked descriptor, rechecks the source didn't change, and writes an unpredictable
  receiver-owned snapshot with exclusive creation — only that snapshot path reaches the model.
  Anything else is NACKed rather than exposed. Received snapshots join sender spills under the same
  TTL/file-cap cleanup, and the per-sender byte window charges only what crossed the wire (not a
  spill's declared size), so a legitimate large spill is delivered rather than refused as "budget".
  Transport guardrails enforced at the boundary: a hop cap (bounds only a THREADED reply chain,
  derived from `in_reply_to`; untreaded alternating sends aren't depth-bounded by the transport), a
  per-sender rate+byte budget, and a (sender, msg_id) dedup set so an at-least-once resend can't
  double-trigger a turn. An exchange's LENGTH is instead bounded prompt-side: the per-turn peer brief
  (`core/brief.ts`) carries a relevance bound — send only what changes what someone does — deliberately
  not a round count, since a counter can't see whether a round still serves the work.
- **Tools are lazy and fail closed.** `exocom_list({ offset?, limit? })` exposes bounded, paginated
  presence; `exocom_send({ target, message, in_reply_to? })` sends one-way (a session-qualified-looking
  target resolves only as one, never falling back to a display name, since names are self-chosen);
  `exocom_name({ name })` rebrands the display call-sign without moving any state. The ledger tools —
  `exocom_claim`, `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait`, `exocom_progress`,
  `exocom_release` — are capability-gated with the postcard tools; the live accessor, capability gate,
  and active-tool set all deny them once the plane stops, since Pi has no dynamic tool-unregister API.
  Admission requires at least one obligation closer, because every published peer may receive a
  durable ask and must retain a way to settle it.
- **Inbound delivery is bounded without loss.** Each message is injected under the same byte cap
  whether plain text or an artifact descriptor. Bursts stay FIFO-queued; each rate-limited wake drains
  as many whole messages as fit, leaving the rest queued. A presentation cap on the collapsed card
  never discards the rest of the queue.

exocom never touches the delegate/council/broker path. One instance can be **both** a supervisor
(delegating its own children) **and** an exocom peer at once — the planes are independent and
independently gated. Whoever initiates a collaboration is merely the coordinator de facto: the plane
stays flat, and no peer gains stop/steer authority over another (that exists only on the hierarchical
intercom plane). The join code is not authentication: exocom is cooperative same-user, same-host
coordination between processes sharing one effective Pi agent directory, not a remote/network plane —
a local process able to modify that directory is already inside the trust boundary.

## 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
  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`.
  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.
  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`.

**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
  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.
- 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
    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.
  - **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:
    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
    block, so a `[BLOCKED]` marker there doesn't also get the persistence note. Same marker, same leg,
    different counterweight depending on how it was collected.
    Nested calls through codemode's `ctx.executeTool` leave their programmatic result untouched.
    Pi's explicit `parentToolCallId` supplies the parent identity; call-id string shapes are never
    used to infer nesting. A bounded set of parent call ids carries report provenance through wrappers
    only while their output relays a surrender marker; the outer model-visible result alone gets the
    note/card. Suppressed reports produce neither, and turn/session settlement clears abandoned relay state.
  - **The off switch covers every path.** `PI_PERSONA_NUDGE=off` silences DelegationNudge entirely and
    PersistenceNudge on every collection path (sync result, background notifier, `intercom wait`).

## Discovery & seeding

- **Precedence (all file kinds):** `builtin < user (~/.pi/agent/persona/…) < project (<root>/.pi/…)`; project
  wins collisions. Personas and agents **share a folder**, split by the `persona: true` marker (a
  persona and an agent must not share a name). The loader reports a same-name collision and omits
  both ambiguous definitions from the effective registries, so a malformed install fails closed
  instead of silently routing persona selection and delegation to different files.
- **Personas/agents load ONLY from the user and project dirs.** The bundled `personas/`+`agents/` are a
  **seed source, not a live discovery layer** — a fresh install shows NO personas until installed.
  `/persona seed` copies missing defaults, `/persona restore` force-restores originals (`core/seed.ts`);
  first-run auto-install is opt-in (`PI_PERSONA_SEED=on`, guarded by a marker). When a release changes
  a bundled default, activation may call the exact-size/hash migration helper: it upgrades only a known
  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`.
  Contracts/presets/teams keep a builtin layer (they aren't personas).

## Cross-OS constructs

Never raw `child_process` — reuse Pi's helpers: `getPiInvocation()` (resolve the current `pi` binary),
`killProcessTree` (`taskkill /F /T` on Windows vs POSIX process-group kill), temp/path helpers. Always
attach an `error` listener to every spawned process and socket/server (an unhandled `error` event
crashes the host). Cross-OS is a regression gate: Windows AND POSIX child-spawn + process-tree-kill
must pass. The broker's transport is the only OS-specific code, confined to `bus/broker/`.

## Error-handling & lose-nothing invariants

- Per-run `AbortController`; recoverable failures return `AgentResult.error` + diagnostics, never
  silently lost. A throwing ENGINE call becomes that leg's own `ok: false` result (`legFailure`,
  flagged `infrastructure: true` so failure-punishing consumers can tell it from a model-side
  failure), so one blown leg can't discard the fan-out's completed — already billed — siblings.
  A rejection that reaches `sdk.parallel` is run-fatal by construction (a limit breach, a throwing
  host callback): the batch stops pulling new items and rethrows the FIRST error immediately.
  `runPersonaStrategy` returns `null` only for "nothing to run" (a persona naming no mode) — that
  is not a failure.
- Model/thinking baseline is snapshot-once and restored on omit; tools are restored from the **full**
  registry, never the active subset ("never strip Pi power").
- The completion/mutation guard keeps child-claimed success ≠ runtime-verified; the `maxChildren` cap
  rejects an oversized fan-out **visibly** (an error before spawn), never by silently trimming it.
- Sub-agent output is UNTRUSTED — fenced (`fenceUntrusted`) before it reaches the supervisor as a
  follow-up or tool result (prompt-injection defense).
- The broker host is `unref`'d (never keeps Pi alive) with a permanent error sink; never unlink a live
  socket; teardown is idempotent.

## Reference: the core seams

Session event monitors follow the [time and event wake contract](MONITORS.md). A pure bounded
`MonitorManager` owns command-watch lifetimes; one process adapter reuses `killProcessTree`,
and a bounded session queue delivers fenced events through the existing idle follow-up path.
They are supervisor-owned resources, cancelled on shutdown or execution-permission revocation.
They do not replace engine events, the semantic bus, or Exocom, and are not an OS authorization layer.

The stable contracts other layers build on:

- **Engine:** `AgentRunSpec` → `AgentResult` (`ok`, `output`, `structured?`, `usage`, `error?`,
  `failureKind?`, `modelUsed?`) via `StrategyEngine.run`.
- **Strategy SDK:** `agent` · `parallel` · `reduce.{aggregate,vote,judge}` · `roster.team` · `signal`
  · `limits` · `log` (see [STRATEGIES.md](STRATEGIES.md#the-strategy-sdk)).
- **Strategy:** `{ name, params?, run(input, sdk) }`. **Reducer:** the `ReducerResult` status union
  (`winner | tie | no_consensus | invalid_outputs`, dissent + invalid preserved, `usedFallback`).
- **Persona:** identity + `orchestration` grammar / `council` draft. **Bus:**
  `send`/`ask`/`reply`/`onMessage`/`participants` over logical handles (resolved to a broker name only
  when a message crosses a process).

## Deliberately deferred

- **`context: fork`** — `fresh` is the right child default; fork stays deferred (fail-fast, no silent
  downgrade).
- Blocking peer asks and hard param validation are out of scope by design — see the reasons in
  [STRATEGIES.md](STRATEGIES.md) and the comm-plane section above. Inter-session comm (the broker
  endpoint stays per-session by design) is no longer a gap: **exocom** (above) is the flat, opt-in
  plane for independently-launched instances sharing a selected scope, including explicitly joined
  peers whose actual files live in another workspace.