@aeondave/pi-persona 1.15.2

package/docs/EXPERIENCE.md

@@ -0,0 +1,96 @@
+# Working comfortably with Pi Persona
+
+Choose the outcome you want, describe what counts as finished, and let the supervisor coordinate
+the work. You can inspect or redirect individual workers without managing every hand-off.
+
+## Choose a starting persona
+
+| Your request | Start with | What to expect |
+|---|---|---|
+| Implement or fix something | `dev` | A scoped change, checks, and a concise explanation of the result |
+| Review a change | `audit` | Prioritized, evidence-backed findings; edits only when requested |
+| Turn an idea into an implementation plan | `planner` | Decisions, dependencies, and verifiable steps without changing application code |
+| Investigate a question | `researcher` | Sources, conclusions, uncertainty, and durable notes when the scope warrants them |
+| Apply one operation across many independent items | `swarm` | Explicit coverage of completed, failed, and remaining items |
+| Repair a failing build or verify an implementation | `verify` | Fresh checks on the actual tree; repairs only when requested, with unresolved failures stated clearly |
+
+Switch with `/persona <name>` or F8 (the default shortcut). `/persona seed` installs missing defaults. Existing customized
+persona files remain yours; `/persona restore` replaces installed defaults, so use it only when
+you intend to discard those customizations.
+
+Restart Pi after updating the extension. Known, untouched defaults upgrade automatically; customized
+copies remain unchanged and can be compared with the bundled persona before adopting individual edits.
+
+An effective request names the intended result and its constraints. For example:
+
+> Fix the cancellation bug. Preserve the public API and my existing edits. Delegate independent
+> investigations, implement the fix, and run the relevant checks. Tell me what changed and what
+> remains unverified.
+
+## Follow the work without constant polling
+
+Your persona describes a role; your session has its own personal handle. Pi chooses it on the first
+task or inbound Exocom request when the naming tool is permitted. Until then it shows a distinct
+session suffix. The name survives persona changes and resume. `agent_name` sets it in standalone
+use; `exocom_name` sets the same identity when connected to peers. The leader can assign each
+delegated worker a `name` before launch, which reaches both its display and its first prompt.
+
+For a fixed-time reminder, ask for a timer. For a build finishing or a file, log, or system event,
+ask for a monitor. Pi runs a small event-producing program and brings the result back when the
+supervisor is free. Keep the session open, and cancel a watch when its purpose ends. See
+[time and event wakes](MONITORS.md) for examples and limits.
+
+- **F9** opens the agent tree. Every running row shows its elapsed time and switches to `⚠ stalled
+  <duration>` once it has gone 90 seconds without progress — the same threshold behind the
+  supervisor's stall alert. Enter opens a selectable worker's output; `s` sends a course correction;
+  `x` requests cancellation and appears only when the run can actually be stopped, marking the row
+  `stopping…` at once; a stop that can't be applied says so instead of doing nothing. Escape goes
+  back or closes the panel.
+- **`/peek`** gives a compact progress view. A quiet worker is a reason to inspect its last
+  progress and current activity, not to launch a duplicate immediately.
+- **Background results arrive automatically.** A supervisor can continue independent work while
+  they run. `intercom wait` joins results when the next step depends on them.
+- **Answer a waiting worker before joining it.** A coaching worker may need a decision from its
+  supervisor before it can finish. An unanswered question is actionable work.
+- **Steering is a request.** Check the subsequent output to see whether the worker incorporated
+  it. Check the terminal result after requesting cancellation; changes already made are not undone.
+
+A truncated message includes a message id. The supervisor can retrieve its retained body with
+`intercom { action: "message", messageId: "m1" }`. A worker's final report has a run id instead:
+`intercom { action: "result", to: "run-1" }`. Retention is bounded and session-local, so save any
+evidence needed beyond the current session as a project artifact.
+
+For a long task, useful updates say what changed, what is blocked, and what happens next. Worker
+names help distinguish concurrent work; the final answer should use file names and concrete
+outcomes that make sense without remembering those names.
+
+## Work with another Pi through Exocom
+
+Use Intercom for this supervisor's workers and Exocom for independent Pi sessions. Ask a peer for
+a relevant second opinion or coordinate work already in progress. A bounded implementation task
+belongs in a worker brief with explicit ownership and a success criterion.
+
+When Exocom is enabled, use its listed targets to keep messages attached to the right session.
+Exchange decisions and evidence when they affect the work; acknowledgement-only conversations
+add noise. If a peer has joined from another workspace, agree which workspace owns each artifact.
+That peer's membership does not grant it a write claim in the selected workspace.
+
+`exocom_status` (or `/exocom`) shows who owns what right now: your open claims, a peer's open
+claims, and any asks waiting on either side. Claims are advisory, not a lock — if you write into a
+path a peer has claimed, that write is blocked once with a reminder to coordinate or claim it
+yourself first; asking again on the same path goes through, so the warning never repeats for work
+you've already been told about.
+
+## Read completion as an evidence statement
+
+A useful completion tells you what changed, which checks ran against the final state, and what
+still needs attention. A successful review, a passing mocked test, and a live integration check
+answer different questions. Skipped checks and partial batch coverage remain visible.
+
+A worker that did not run in its own isolated worktree has its report followed by a "files changed"
+block: every path `git status` saw move since the worker started, flagging anything outside what it
+was asked to touch. Treat it as a same-checkout approximation, not a private diff — a sibling
+running at the same time can touch the same file.
+
+The bundled persona prompts guide these habits. Tool capabilities, engine limits, and filesystem
+isolation are enforced separately by the runtime; a persona's prose does not create a sandbox.

package/docs/MONITORS.md

@@ -0,0 +1,84 @@
+# Time and event wakes
+
+The supervisor receives a UTC and local clock snapshot when a run starts, alongside the original
+session start and elapsed duration. The precise clock arrives as hidden model-visible context,
+preserving the cached system prefix. During a long run it can call `timer` with `{"action":"now"}`
+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.
+
+## Background programs
+
+`monitor` starts an executable with literal arguments in the current workspace and returns an id
+immediately. There is no implicit shell. For shell syntax, pass a script file to the appropriate
+shell. Windows `.cmd` launchers likewise need an explicit shell; a native executable or script
+interpreter avoids platform-specific quoting.
+
+| Mode | When the model wakes | Typical source |
+|---|---|---|
+| `exit` | The launched program finishes, with its exit code and bounded output tail | Build or local job |
+| `output` | A nonempty stdout line arrives | File watcher, filtered log tail, system-event subscription, service adapter |
+
+For example, start an existing build script and get its completion:
+
+```json
+{"action":"arm","command":"node","args":["scripts/build.mjs"],"label":"build finished","mode":"exit","timeoutSeconds":900}
+```
+
+Or start an existing event adapter that prints only meaningful state changes:
+
+```json
+{"action":"arm","command":"node","args":["scripts/watch-status.mjs"],"label":"status changed","mode":"output","timeoutSeconds":600,"maxEvents":3}
+```
+
+Adapters can use native file/system subscriptions, a program's streaming API, or inexpensive
+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.
+
+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.
+
+## Lifetime and limits
+
+- `list` shows active watches; `cancel` with the returned `id` stops the owned process tree and
+  removes that watch's queued events. It never stops an unrelated job merely because its status
+  is being observed by an adapter.
+- Defaults are one output event and a ten-minute deadline. Limits are eight active monitors,
+  twenty distinct output events per monitor, and twenty-four hours of lifetime.
+- Exit, launch errors and deadline expiry produce terminal notices. Reaching the output event
+  count ends the watch immediately; the notice says the watch ended, without claiming the job succeeded.
+- Lines and diagnostics are bounded. The session retains at most 64 pending events, delivers up
+  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.
+
+## Permissions and architecture
+
+Starting a command requires both `monitor` and `bash` to be active and allowed by the persona.
+Changing to a persona that removes either permission stops its monitors and discards queued
+events. Normal Exocom pending-question gates apply to monitor calls as well.
+
+This is command execution with the host user's access, not an OS sandbox or a read-only guarantee.
+An extension that enforces command-specific policy through `tool_call` must inspect `monitor`
+as well as `bash`; Pi Persona does not synthesize another extension's Bash hooks. External event
+text is fenced as untrusted data before delivery, with runtime id, time and outcome outside the fence.
+
+The pure `src/core/monitor.ts` owns limits and lifecycle. `src/monitor/process.ts` adapts a process
+using the existing process-tree cleanup helper. `src/monitor/session.ts` connects bounded events
+to the existing `IdleCoalescingNotifier` and `sendPersonaFollowUp` path. No separate wake broker,
+public listener, durable queue, or new orchestration engine is introduced.
+
+The design follows the background-program model described in the official
+[Claude Monitor documentation](https://code.claude.com/docs/en/tools-reference#monitor-tool).
+Protocol-specific integrations can be ordinary adapter programs; direct WebSocket connections
+and persistent services are outside this tool's current scope.
+
+For live verification, `scripts/monitor-smoke.mjs` runs a persistent Pi RPC session and checks an
+automatic model turn after a local event. It requires an explicit `LIVE_MODEL=provider/id` because
+it spends provider tokens. Unit and integration tests use deterministic clocks and local programs.

package/docs/README.md

@@ -0,0 +1,53 @@
+# pi-persona documentation
+
+This folder contains the long-form documentation that defines how the project is designed and run.
+
+## Canonical docs
+
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md)
+  - Core architecture, invariants, module boundaries, and design contracts.
+- [`STRATEGIES.md`](./STRATEGIES.md)
+  - Strategy SDK and built-in orchestration behavior.
+- [`SPINE.md`](./SPINE.md)
+  - Shared behavioral spine prompt layer and rollout controls.
+- [`TELEMETRY.md`](./TELEMETRY.md)
+  - Vendor-neutral observer contract, privacy boundary, persistence, and consumer conformance.
+- [`EXPERIENCE.md`](./EXPERIENCE.md)
+  - Choosing a persona, supervising background work, and collaborating through Exocom.
+- [`MONITORS.md`](./MONITORS.md)
+  - Clock snapshots, timers, and background event sources that wake the supervisor.
+- [`REFERENCE.md`](./REFERENCE.md)
+  - Canonical Core API, configuration, environment variables, commands, and data-driven recipes.
+
+## Quick map
+
+- **For users / operators:** start from [README](../README.md) and [EXPERIENCE.md](./EXPERIENCE.md); use `REFERENCE.md` for configuration and recipes.
+- **For contributors:** begin at `ARCHITECTURE.md`, then `REFERENCE.md` for runtime surfaces and `STRATEGIES.md` for implementation details.
+- **For behavior-layer changes:** consult `SPINE.md` and `src/core` / `src/persona/spine.ts` together.
+- **For telemetry producers or consumers:** start with `TELEMETRY.md` and its conformance corpus.
+
+## Documentation maintenance notes
+
+When touching this folder:
+
+- Keep names stable (`ARCHITECTURE.md`, `STRATEGIES.md`, `SPINE.md`, `REFERENCE.md`) because many docs and comments link to them directly.
+- Prefer links to this folder over copying duplicate prose into code comments.
+- Update both this map and inbound links when adding new authoritative docs.
+- A few factual claims are machine-checked by `test/unit/docs/doc-claims.test.ts`. Know its blind
+  spots before trusting it:
+  - **Env names.** It collects the whole `PI_*` identifiers `src/**/*.ts` actually reads and fails
+    when a documented name is not one of them, so a documented name that is merely a *prefix* of a
+    real one is caught. It still never reads `scripts/`, so a variable only that tree consumes
+    reads as undocumented-in-reverse: the check is one-directional (docs → source), and a source
+    variable nothing documents is not flagged at all.
+  - **Strategy table.** It fails when a registered strategy has anything other than exactly one row
+    in the canonical table in `STRATEGIES.md` (the one headed `| Strategy | … | Params …`), or when a
+    declared param is not backticked in a cell *after* the row's name. It still cannot tell whether
+    the *description* of a param or its default is correct.
+  - **Skip count.** It scans every `test/**/*.test.ts` for skip markers (an options-object `skip` key
+    or a `.skip` shorthand), and fails unless AGENTS.md's stated word, its `skipped N` on Windows and
+    its `skipped 0` elsewhere all match, every marker is gated on `process.platform === "win32"`, and
+    AGENTS.md names each file carrying one. It counts markers rather than running the runner, so a
+    marker on a suite of several skipped subtests would count once where the runner counts each.
+- Everything else here is prose a reader has to check against the code — so state behavior precisely
+  enough to be falsifiable, and cite the module that settles it.

package/docs/REFERENCE.md

@@ -0,0 +1,408 @@
+# pi-persona technical reference
+
+This is the canonical technical guide for the runtime surfaces that users configure through
+personas, agents, teams, flows, contracts, presets, and environment variables. The design contract
+lives in [`ARCHITECTURE.md`](./ARCHITECTURE.md); strategy shapes and their complete parameter table
+live in [`STRATEGIES.md`](./STRATEGIES.md). User-oriented orientation and operating examples start
+in the root [`README.md`](../README.md) and [`EXPERIENCE.md`](./EXPERIENCE.md).
+
+## Core API
+
+The runtime is composed from a small, fixed set of primitives. A strategy is a TypeScript file
+composing the **Strategy SDK**; a persona picks whether and how those run. `magi` is a `.md` persona
+plus a file that calls `parallel` and `reduce.vote`.
+
+**Strategy SDK** (`src/orchestration/sdk.ts`) — the primitives available to a strategy:
+
+| Primitive | Does |
+|---|---|
+| `agent(spec)` | run one sub-agent and return a structured `AgentResult`; `spec` may carry `name`, model, tools, skills, or `outputContract` |
+| `parallel(thunks, {concurrency})` | run many at once, bounded by the run limits; this also provides the basis of `map` |
+| `reduce.aggregate(results)` | merge N results into one, used by fan-out |
+| `reduce.vote(candidates, opts)` | tally the candidates' own votes and preserve `winner`, `tie`, `no_consensus`, `invalid_outputs`, and dissent |
+| `reduce.judge(candidates, order?)` | anonymise and label candidates for an impartial judge, then map the verdict back with `pick(label)` |
+| `roster.team(name)` | resolve the agents of a named team |
+| `signal` · `limits` · `log` | cooperative abort, admission/runtime limits, and progress reporting |
+| series and loops | plain `await` and `for`; strategies are TypeScript, so pipelines and critic loops are ordinary code |
+
+The complete built-in strategy catalog and each strategy's declared parameters are maintained in
+[`STRATEGIES.md`](./STRATEGIES.md). Parameters are declared per strategy and looked up by
+`knownParams()`; `/doctor` exposes the same schema live. Unknown parameter keys warn but do not
+hard-fail.
+
+**Supervisor surface** — the tools and persona fields that drive those primitives:
+
+| Surface | Does |
+|---|---|
+| `delegate` tool | spawn one or more sub-agents; interactive calls are background-first, while `sync: true` blocks the turn |
+| `council` tool | run the selected strategy over a roster and return its result; voting strategies preserve tally and dissent |
+| `intercom` tool | observe and control internal runs with `peek`, `result`, `wait`, `steer`, and `stop`; `list`, `inbox`, `message`, `reply`, and `send` drive the coaching bus |
+| `timer` tool | read the fresh clock with `now`, or schedule an idle wake with `arm`, `cancel`, and `list`; alarms are one-shot and in-memory per session |
+| `monitor` tool | run a bounded job (`mode: exit`) or event-producing program (`mode: output`) and wake the supervisor; see [`MONITORS.md`](./MONITORS.md) |
+| `flow` tool and `/flow` | run a journaled DAG of strategies; `gate: true` creates an approval checkpoint |
+| `models` tool | list or search authenticated model ids in `provider/id` form; the session provider is marked |
+| persona `mode:` | choose `solo`, `parallel`, `pipeline`, `strategy:<name>`, or `flow:<name>` |
+| persona `coaching:` | give children `contact_supervisor` for progress and blocking decisions |
+| persona `delegation:` | require briefs, set an output contract, schedule disjoint writes, and order fresh verification |
+| `isolation: worktree` | run in a clean throwaway Git worktree and return an exported diff; non-Git, dirty, or oversized cases fail closed |
+| `council: { preset }` | expand a reusable `presets/<name>.preset.json`; authored fields override the preset |
+| `contracts/*.json` | define a hot-editable structured return requested through `outputContract` and pinned per run |
+
+The delegate tool's optional `name` is carried into `AgentRunSpec.name` and reaches both engine
+backends, keeping a caller-provided run label available in the live tree and runtime result.
+
+`outputContract` takes a contract **name**, not an inline shape — `/doctor` lists what's installed
+(the only built-in is `default`). Naming one that isn't installed is rejected before any worker
+spawns, checked across every task in a parallel batch: `delegate: unknown output contract(s) "x" —
+nothing was spawned. Installed contracts: default, finding` (the list is capped at 16 names; a
+`, …` marker is appended only when more than 16 are installed).
+
+### Supervising running sub-agents — the `intercom` plane
+
+The supervisor's internal communication with children has three layers:
+
+| Layer | Needs | What you get |
+|---|---|---|
+| **Observe and control** | any persona | `peek` watches async sub-agents; `wait` joins them; `steer` sends a soft correction; `stop` requests cancellation. The `f9` overlay provides the same controls (`s`, `x`). Cancelling a worker does not undo existing changes |
+| **Retrieve** | any persona | `result { to }` returns one retained run payload; `message { messageId }` returns one retained bus message. History is bounded to 256 messages and 256,000 body characters, and retrieval never starts a worker |
+| **Message bus** | `coaching: true` | children get `contact_supervisor`; progress appears in results and `intercom inbox`, while a blocking `decision` wakes the supervisor for `intercom reply` |
+| **Sibling peer comm** | strategy opt-in | `debate` and `pair` members always get one-way `contact_peer`; `map` and `synthesize` add it with `params: { peers: true }` |
+
+Delegated output is untrusted and is fenced before it reaches the supervisor. Async runs report
+failures to the supervisor, and a repeated identical failed delegation is stopped by the runtime
+ledger before another child is spawned. A run whose model's provider fails at call time (auth,
+outage, 5xx) may retry the same model id through a fallback provider; each reroute surfaces to the
+supervisor as a warning toast, `<agent>: <from> failed, retrying on <to>`.
+
+Any leg that does NOT run in `isolation: worktree` shares the real checkout, so its result gets a
+"what changed" block appended: `--- FILES CHANGED DURING THIS LEG (shared checkout; parallel legs
+may overlap) ---` followed by one `- <path> (<M|A|D|R|?>)` line per path (capped at 40, `+N more`
+beyond that); a changed path outside the leg's own declared `writeSet` is flagged
+`⚠ outside declared writeSet`. This is a `git status` before/after snapshot, not a private diff — a
+parallel sibling touching the same file can appear here too — and it is skipped when there is
+nothing to report, or when the leg IS worktree-isolated (that path already returns a real unified
+diff instead).
+
+The cross-process broker is on by default for child-engine, worktree, and MCP legs. It provides the
+same supervisor communication surface over a session-scoped POSIX socket or Windows named pipe.
+`PI_PERSONA_BROKER=off` restores the pre-broker child spawn behavior. See the comm-plane contract in
+[`ARCHITECTURE.md`](./ARCHITECTURE.md#the-comm-plane-in-practice).
+
+> **MCP in sub-agents.** A normal in-process leg has no MCP connection. Set `mcp: true` in an agent
+> definition or delegation task to route it through the child engine, which initializes MCP from
+> `~/.pi/agent/mcp.json`. A fresh UI-less child cannot complete an interactive OAuth flow, so
+> authenticate the server in a normal session first. A backend that keys state by a session id must
+> receive that id in the task. A local registration, stdio process, or loopback endpoint does not
+> prove local target egress; verify source routing with the executor and canary required by the
+> engagement. This is a behavioral boundary, not a network sandbox.
+
+### Identity and Exocom
+
+An unnamed standalone session receives a provisional process/session-derived handle. On its first
+turn where `agent_name` is callable, the runtime context asks the model to invent a
+short handle and call `agent_name` before other work. The chosen handle is separate from the active
+persona and role, is persisted in the session identity entry, and remains across later turns and
+persona changes. Once chosen, it is not re-injected into every provider request; the runtime and
+session entry remain authoritative. `agent_name` is unavailable while Exocom is active; its call-time capability check
+also rejects empty, unsafe, generic, or reserved persona/agent names.
+
+Naming needs one tool action, not a recurring prose confirmation. A stable system-level runtime rule
+also distinguishes skill-prefetch and routine check-ins from new user requests; it neither hides
+updates nor rewrites conversation history. After updating extension code, use Pi's `/reload` once
+delegated work has settled (or restart/resume); `/persona reload` reloads definitions only.
+
+With Exocom active, the corresponding tool is `exocom_name`. The first incoming peer wake can be the
+first model turn in an RPC session; the context hook supplies the naming bootstrap for that custom
+wake as well as for an ordinary user turn. A chosen Exocom handle updates the live registry while
+its session-qualified routing target remains stable across renames. Naming metadata remains callable
+when a pending ask permits `exocom_name`, but it does not settle that work ask.
+
+Exocom is a flat, external plane between independent top-level Pi sessions. It provides presence,
+fenced postcards, and a durable claim/ask ledger. `--exocom` joins the current workspace; an exact
+`--exocom=Ab0T` joins an existing workspace scope from another cwd. The four-character code is a
+same-host join reference, not authentication. Foreign members advertise the workspace they can
+actually inspect and cannot claim repository-relative paths in another workspace's ledger.
+
+`exocom_status` (a tool, taking no arguments) and `/exocom` (a command, which additionally lists
+live peers) both render the same ownership view: your claims, peers' claims, asks waiting on you,
+and your own open asks. A claim's `write_set` is advisory, not enforced: a supervisor's own
+`write`/`edit` call whose path overlaps a PEER's open claim is blocked once with a reason to
+coordinate (`exocom_ask`) or claim the path itself; calling the same tool again on the same path is
+then allowed through (one warning per claim + normalized path, not a standing lock).
+
+## Configuration and data
+
+Personas and agents are Markdown files with YAML frontmatter. Teams, flows, contracts, and presets
+are data files. Discovery precedence is builtin < user `~/.pi/agent/persona` < project `.pi/`.
+Personas and agents are loaded from the user and project agent folders; bundled persona and agent
+files are seed sources. A fresh install has no installed personas until `/persona seed`,
+`/persona restore`, or opt-in first-run seeding installs them.
+
+| Definition | Location | Purpose |
+|---|---|---|
+| Persona | `personas/*.md` or installed `agents/*.md` with `persona: true` | supervisor prompt, capabilities, delegation, council, orchestration, and coaching |
+| Agent | `agents/*.md` or project `.pi/agents/*.md` | worker prompt, optional tools/model/isolation/MCP |
+| Team | `teams.yaml` | named roster of bare agent names or inline `{ agent, role, model, skills }` members |
+| Flow | `flows/*.flow.json` | strategy phases connected by `needs`, optionally gated |
+| Contract | `contracts/*.contract.json` | structured output fields requested by name and pinned per run |
+| Preset | `presets/*.preset.json` | reusable council strategy, roster, and parameter bundle |
+
+`tools` accepts an allowlist such as `[read, grep]`, an `allow`/`deny` object, or `[]` for no tools.
+Omit it to inherit the session tool set. `model`, `isolation: worktree`, `mcp: true`, and `purpose`
+are optional agent metadata. The body is the agent prompt. Inline roster members specialise one
+agent with a role, model, or skills without requiring another agent file.
+
+### Multi-agent quick start
+
+Follow the [installation instructions](../README.md#install), then start a coding supervisor:
+
+```bash
+pi --persona dev
+```
+
+Delegate a bounded task with the complete brief that Dev requires:
+
+```js
+delegate({
+  agent: "scout", name: "Login-Trace", task: "Inspect the login flow and report the root cause.",
+  brief: {
+    objective: "Explain the login failure with code evidence",
+    scopeRoe: "Read this repository only; do not contact external systems",
+    position: "Start from the current checkout and its existing tests",
+    constraints: ["Do not modify files"],
+    requiredArtifacts: ["File and line references, with a suggested minimal fix"],
+    stopConditions: ["Stop after finding the cause or report the missing evidence"]
+  }
+})
+intercom({ action: "peek" })
+```
+
+For independent Pi processes, open the same workspace in two terminals with `pi --exocom` and use
+the qualified target returned by `exocom_list`:
+
+```js
+exocom_name({ name: "<invented from the current task>" })
+exocom_list({})
+exocom_send({ target: "<qualified target from exocom_list>", message: "Review the API boundary and send back concrete risks." })
+
+exocom_claim({ work_key: "api-review", write_set: ["src/api"], slice: "Review and fix the API boundary" })
+exocom_ask({ target: "<qualified target>", work_key: "api-review", question: "Is the transport contract safe to change?" })
+exocom_wait({ work_key: "api-review", ask_id: "<ask_id returned above>" })
+exocom_answer({ work_key: "api-review", ask_id: "<received ask_id>", ok: true, evidence: "Tests and file references" })
+exocom_release({ work_key: "api-review" })
+```
+
+### Recipes
+
+Everything in these examples is data. Drop files into the discovery locations above and switch
+personas with `f8`. A brand-new strategy shape is the only case that requires a source file.
+
+**Opportunistic delegation** — a simple persona with no orchestration block:
+
+```markdown
+<!-- .pi/agents/my-researcher.md -->
+---
+name: my-researcher
+persona: true
+---
+You research thoroughly. For independent sub-questions, fan out `scout` sub-agents in ONE
+`delegate` call (`tasks: [...]`), each with a disjoint scope, then synthesise their findings.
+```
+
+**A review council and a per-call override** — `council:` is the persona default; the tool can
+override it for one call without editing the file:
+
+```yaml
+# teams.yaml — one reviewer agent, three lens roles
+review:
+  - { agent: reviewer, role: "Focus ONLY on the SECURITY lens" }
+  - { agent: reviewer, role: "Focus ONLY on the PERFORMANCE lens" }
+  - { agent: reviewer, role: "Focus ONLY on the TESTS lens" }
+```
+
+```markdown
+<!-- .pi/agents/myaudit.md -->
+---
+name: myaudit
+persona: true
+council: { strategy: synthesize, roster: review, params: { synthesizer: reviewer, peers: true } }
+---
+Convene the council before sign-off, then apply its merged findings yourself.
+```
+
+```js
+// one-off: run this decision as a debate over the same roster — no file edit
+council({ question: "cache this or recompute?", strategy: "debate", roster: "review", params: { bestOf: 2 } })
+```
+
+**A delegation policy on any persona** — fields are generic and are never keyed to a persona name.
+The runtime rejects incomplete briefs before a model call, supplies a missing contract, rejects
+overlapping or missing ownership for parallel writers, and refuses a declared verifier that would
+start before or beside a material writer in the same call or while a mutating background run is in
+flight. Only `read`, `grep`, `find`, and `ls` count as read-only; shell-capable, MCP-enabled, and
+unknown toolsets fail closed as writers. `writeSet` is a scheduling contract, not an OS sandbox.
+
+```markdown
+---
+name: my-project-lead
+persona: true
+delegation:
+  requireBrief: true
+  outputContract: finding
+  requireDisjointWrites: true
+  requireFreshVerification: true
+  verificationAgents: [my-checker]
+council: { strategy: critic-loop, roster: my-repair-team, params: { rounds: 3 } }
+---
+Delegate bounded work, then accept completion only after fresh evidence.
+```
+
+The six required `brief` fields are `objective`, `scopeRoe`, `position`, `constraints`,
+`requiredArtifacts`, and `stopConditions`. `verificationAgents` names ordinary installed agents;
+there is no built-in verifier identity.
+
+When `requireBrief` is enabled, it also applies to read-only scouts. Single-worker calls put the
+brief alongside `agent` and `task`; parallel calls put a complete brief inside **each** `tasks[]`
+entry. A top-level brief is not inherited by the batch, and prose in `task` does not replace these
+fields. A missing-brief error means the batch was rejected before any worker started: correct all
+affected entries before retrying.
+
+**A mandatory-orchestration persona** — `orchestration:` runs automatically every turn, while
+`council:` runs only when requested. Only `ok: true` is presented as a ruling; failures, cancellation,
+and unresolved output remain labelled evidence to repair and verify.
+
+```markdown
+<!-- .pi/agents/myguard.md -->
+---
+name: myguard
+persona: true
+orchestration: { mode: strategy, strategy: magi, roster: magi, params: { reflect: false } }
+---
+Every turn is decided by the MAGI triarchy first (no reflection round); present and act on it.
+```
+
+**Coaching** — add `coaching: true` to give children `contact_supervisor`, then read and answer
+progress or decisions with `intercom inbox` and `intercom reply`.
+
+**A custom agent** — the body is the worker prompt and the frontmatter sets its capabilities:
+
+```markdown
+<!-- .pi/agents/hardener.md -->
+---
+name: hardener
+description: Locks down a change's security posture — authz, input validation, secrets handling.
+tools: [read, grep, edit, bash]
+model: opus
+isolation: worktree
+---
+You are the Hardener. Given a diff or area, find and FIX authz/access-control gaps, injection and
+unsafe-sink risks, secrets/token mishandling, and missing input validation. Cite `file:line`.
+```
+
+**A flow with a human checkpoint** — phases are journaled and dependents wait for a `gate: true`
+approval. Save as `.pi/flows/gated-build.flow.json`:
+
+```json
+{
+  "name": "gated-build",
+  "phases": [
+    { "id": "plan",   "strategy": "magi",        "roster": "magi",   "gate": true },
+    { "id": "build",  "strategy": "critic-loop", "roster": "repair", "needs": ["plan"] },
+    { "id": "verify", "strategy": "fanout",      "roster": "review", "needs": ["build"] }
+  ]
+}
+```
+
+**A structured-return contract** — save as `.pi/contracts/ship-verdict.contract.json` so votes and
+judges can tally fields mechanically:
+
+```json
+{ "name": "ship-verdict",
+  "fields": {
+    "vote":       { "type": "string", "required": true },
+    "severity":   { "type": "enum",   "values": ["low", "medium", "high", "critical"] },
+    "confidence": { "type": "number", "min": 0, "max": 1 }
+  }
+}
+```
+
+**A preset keeps persona files to one line** — save as `.pi/presets/magi-rounds.preset.json`:
+
+```json
+{ "strategy": "council-rounds", "roster": "magi", "params": { "rounds": 3, "bestOf": 3 } }
+```
+
+```yaml
+# any persona's frontmatter
+council: { preset: magi-rounds }
+```
+
+For one-line strategy calls and the canonical parameter defaults, use the table in
+[`STRATEGIES.md`](./STRATEGIES.md). A new vote rule or custom loop adds
+`src/orchestration/strategies/<name>.ts`, registers it in `strategy.ts`, and gets a stub-engine unit
+test; the data-driven definitions above require no core change.
+
+## Commands, flags, and environment
+
+**Keys** — `f8` cycles persona; `f9` or `/agents` opens the agent overlay: ↑↓ navigate, ⏎ open, `x`
+stop, `s` steer, and Esc close.
+
+**Commands** — `/persona [name|off|list|reload|seed|restore]` · `/models [query]` ·
+`/orchestrate <task>` · `/flow <name> <task>` · `/peek [id]` · `/exocom` · `/doctor`.
+
+`/doctor` reports the cross-process broker's lifecycle on one line: `broker: on — endpoint …` once
+the host is listening, `broker: on — (starting…)` mid-attempt, or
+`broker: on — (not started — no child-engine build yet)` before any child-engine build has run. A
+bind failure reports on its own, without the `on —` prefix or a connected-children count (there is
+neither while down): `broker: failed — <reason>` — children built while it is down spawn without a
+bus endpoint, so they never burn connect backoff against a dead socket, and the next child-engine
+build retries. A connected broker child's status shows `⇄ <handle>`; if that connection drops, the
+status flips to `⇄ offline` and a fresh ask on it fails fast instead of hanging.
+
+`/doctor` also reports the installed host's version against this extension's floor: `pi: <version>
+(requires ≥ 0.83.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
+check (`src/core/pi-compat.ts`). `pi: unknown` means the host's own `package.json` could not be
+resolved (a non-standard install layout) — not a failed check.
+
+**CLI flags** — `--persona <name>` starts with that installed persona and errors if it is missing;
+`--exocom` joins this workspace's Exocom plane; `--exocom=Ab0T` joins another workspace's scope
+from a different cwd. Pi owns `--model <provider/id>`, `--thinking
+<off|minimal|low|medium|high|xhigh|max>`, and `--list-models`.
+
+| Variable | Default | Effect |
+|---|---|---|
+| `PI_PERSONA_ENGINE` | in-process | `child` spawns each sub-agent as an isolated `pi` process |
+| `PI_PERSONA_CHILD_THINKING` | inherited | reasoning effort for child-engine sub-agents |
+| `PI_PERSONA_SEED` | off | `on` auto-installs bundled personas on first run |
+| `PI_PERSONA_BROKER` | on | `off` disables the cross-process comm plane for child, worktree, and MCP legs |
+| `PI_PERSONA_PEEK_MS` | 30000 | fast async stall/message wakeup tick; `0` disables it |
+| `PI_PERSONA_CHECKIN_MS` | 300000 | routine direction check-in while async children run; `0` disables it |
+| `PI_PERSONA_AGENT_MAX_MS` | off | opt-in per-agent hard wall-clock cap; unset leaves healthy work running |
+| `PI_PERSONA_AGENT_STARTUP_MS` | 300000 | startup deadline for a child that makes no progress; `0` disables it. Like the idle window, a leg waiting on a supervisor reply is not idle: the watchdog re-arms while its ask is pending, instead of killing on a blind ceiling |
+| `PI_PERSONA_NUDGE` | on | `off` silences delegation and persistence nudges; synchronous checkpoints stay in model-visible tool results and are mirrored to durable, expandable TUI-only cards |
+| `PI_PERSONA_EXOCOM` | off | `1` joins the current workspace Exocom scope; cross-workspace selection is CLI-only |
+| `PI_PERSONA_SPINE` | off | `on` or a path enables the shared behavioral layer; see [`SPINE.md`](./SPINE.md) |
+| `PI_PERSONA_SPINE_LEGS` | follows `PI_PERSONA_SPINE` | selector for delegated legs, allowing all four spine measurement arms |
+| `PI_PERSONA_DISABLE` | unset | any non-empty value disables the whole extension for this process (also set internally as the fork-bomb guard on delegated legs) |
+| `PI_PERSONA_DIRS` | none | extra discovery directories (`;`/`,`-separated), searched alongside the user and project agent folders |
+| `PI_PERSONA_DEFAULT` | none | persona activated automatically when no persona is otherwise selected |
+| `PI_PERSONA_KEY` | `f8` | keybinding that cycles installed personas |
+| `PI_PERSONA_PERSIST` | on | `off` stops remembering the last-selected persona across sessions |
+| `PI_PERSONA_DELEGATE_DEFAULT` | allow | `deny` (or an off-word) makes an unlisted delegate target default-deny instead of default-allow |
+| `PI_PERSONA_STATE_FILE` | a global default path | overrides where the last-selected-persona state is stored |
+| `PI_PERSONA_ASYNC_RETAIN` | 25 | how many settled-but-uncollected async runs are retained before FIFO-evicting the oldest |
+| `PI_PERSONA_LEDGER_V2` | off | `on` widens the delegation-ledger retry-veto key to also include role/tools/isolation, not just agent+model+task |
+| `PI_PERSONA_LEG_CHANGE_REPORT` | on | `off` disables the non-worktree files-changed report (two `git status` spawns per leg) |
+
+## Development
+
+```bash
+npm install
+npm run typecheck   # strict tsc --noEmit
+npm test            # node --test
+```
+
+The architecture contract is [`ARCHITECTURE.md`](./ARCHITECTURE.md), orchestration behavior is
+[`STRATEGIES.md`](./STRATEGIES.md), the shared prompt layer is [`SPINE.md`](./SPINE.md), and the
+observer/export contract is [`TELEMETRY.md`](./TELEMETRY.md). After updating Pi packages, run
+`npm run typecheck`: it catches changes at the in-process session and `ThinkingLevel` seams.