@aeondave/pi-persona 1.17.1 → 1.17.4

package/AGENTS.md

@@ -20,7 +20,11 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
     A test that exercises a variable sets it for itself, after that has run. Drop the flag and you
     are testing your shell, not the code.
 - Live end-to-end (REAL model calls, spends tokens): `npm run drive -- --persona <name> --model <provider/id> "<prompt>"`
+  - `drive.ts` exits non-zero and prints `[persona] ...` when the requested persona is not installed.
   - Control ops: `LIVE_MODEL=<provider/id> node --import tsx scripts/control-test.mjs` (STEER/STOP/RESUME)
+  - Interactive wake contract (manual, spends tokens, refuses without `LIVE_MODEL`):
+    `LIVE_MODEL=<provider/id> npm run smoke:wake` — RPC session, 3-leg `delegate` fan-out, asserts ONE
+    wake carrying all results and no peek/timer/sleep polling before it. Run it before a release.
   - Models must be **provider-qualified**, e.g. `claude-pro-max-native/claude-opus-4-8` or `.../claude-haiku-4-5`.
 
 ## Conventions
@@ -33,8 +37,13 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   `@earendil-works/pi-*`; never bundle copies.
 - npm publishes as `@aeondave/pi-persona`. Pi supplies the four `@earendil-works/pi-*` packages
   and `typebox`: keep them as `peerDependencies: "*"` with development-only copies, never runtime
-  dependencies. The supported host floor is Pi ≥ 1.0.0 (`MIN_PI_VERSION` and the README); Node.js
-  must be ≥ 22.19 to match that host. Keep the npm
+  dependencies. Target the latest stable Pi only (currently 1.4.0, aligned with `MIN_PI_VERSION`,
+  the four development pins and README); do not maintain historical-host compatibility branches.
+  **No legacy or deferred cleanup:** remove dead code, obsolete options, superseded implementations
+  and compatibility-only aliases with their replacement. Update every caller, fixture and document
+  in the same change. A completed feature must not leave temporary scaffolding or cleanup debt.
+  Keep a path only when it serves the current host/runtime or a demonstrated current data contract.
+  Node.js must be ≥ 22.19 to match that host. Keep the npm
   `files` allowlist explicit for docs/artwork, inspect `npm pack --dry-run`, and never publish drafts.
 - Supply-chain controls: pin every GitHub Action to a verified full commit SHA; keep top-level
   token permissions read-only, grant write permissions only to the reporting job that needs them,
@@ -51,7 +60,7 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   `createAgentSession`, DEFAULT) and **ChildProcessEngine** (`engine/child`, spawns `pi --mode json -p`,
   the correctness baseline + the path worktree isolation uses). Opt out with `PI_PERSONA_ENGINE=child`.
   BOTH enforce `RUN_LIMITS.timeoutMs` as an **idle window** (no events/output ⇒ abort; the inproc
-  watchdog is disabled for coaching children that may legitimately block on a supervisor reply) AND
+  watchdog is armed for every child; a live pending ask from that child re-arms it) AND
   `PI_PERSONA_AGENT_MAX_MS` as an **opt-in hard wall-clock cap** (lifetime ceiling armed once, never
   reset — catches a busy loop the idle window never does; OFF by default (0 = unlimited) so a healthy,
   progressing child runs to completion, set `<ms>` to arm it) AND
@@ -62,9 +71,14 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   notably a headless `mcp: true` leg whose `pi-mcp-adapter` hangs on interactive OAuth; `adapter.ts`
   turns that (turns===0 + `spec.mcp`) into a clear pre-auth remedy instead of an opaque timeout.
   The child engine delivers the task over **stdin** (`pi -p` prepends piped stdin) — never argv,
-  which would hit Windows' ~32 KiB command-line cap on flow-phase tasks. Async delegate launches
-  share one `maxConcurrency` semaphore (`Semaphore` in `orchestration/parallel.ts`), so an async
-  fan-out can't open more concurrent sessions than a sync one.
+  which would hit Windows' ~32 KiB command-line cap on flow-phase tasks. Every delegate leg, and every
+  tracked `council`/`flow` run (one slot for the whole run), headless included, shares one
+  `maxConcurrency` launch pool (`Semaphore` in `orchestration/parallel.ts`), so a fan-out can't open more
+  concurrent sessions than that; the strategy SDK's own semaphore gates the legs INSIDE a run.
+  Any event re-arms the idle window (a chatty tool is never killed), but stall credit follows one rule,
+  `madeHeadway` (`engine/async.ts`): raw tool-output chunks earn none, so a leg whose tool streams forever
+  raises only the operator-only stall card (nothing is killed, the model is not woken). The idle-timeout
+  failure text names the `timeoutMs` remedy.
   Each strategy SDK also gates every `agent()` call through one semaphore, including direct
   `Promise.all` calls; `parallel` overrides cannot raise its concurrency ceiling. Token budgets
   gate admission using completed usage, so already-running legs can overshoot the threshold.
@@ -111,16 +125,27 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   blind retry loops are stopped by the runtime `DelegationLedger` (an identical agent+model+task
   delegation that failed twice is vetoed before it spawns).
 - Dynamic sub-agents: `delegate` shapes an on-the-fly specialist with `role` (extra system prompt,
-  appended to the agent's own) + `skills` — prompt-level only, capabilities stay the gate. Intercom
-  `wait` snapshots already-settled reports by default in interactive/RPC sessions; `sync: true` opts
-  into a bounded join (≤ the bus-ask timeout). Headless waits default to joining; `sync: false` takes
-  a snapshot. Collected reports are discarded from the pending completion follow-up so they are
-  never double-reported; snapshots leave running children active. In interactive sessions `delegate`
-  is background-by-default (`sync: true` opts a call out; headless `pi -p` defaults to sync so the
-  single turn carries the result). An explicit `async` flag takes precedence over `sync` and the default.
+  appended to the agent's own) + `skills` — prompt-level only, capabilities stay the gate.
+  `delegate` has NO `sync`/`async` parameter and `intercom` has NO `wait`: interactive sessions
+  (`ctx.hasUI`, TUI and RPC) ALWAYS run `delegate` in the background (each result an idle-gated
+  completion follow-up; a `tasks` fan-out is ONE follow-up when its last member settles), headless
+  `pi -p` ALWAYS blocks and returns results inline (nothing drains a follow-up after the single turn).
+  A finished child wakes the supervisor by itself, so any in-turn wait (a sleep, a peek loop, a
+  `timer`/`monitor` used as a wait) blocks the wake it waits for. The prompt layer says to end the
+  turn; the call-time guards (`PollGuard` on repeated `peek`/`result`, the long-`sleep` block) live
+  under `config.nudge` (`PI_PERSONA_NUDGE=off`). `council` and `flow` follow the same rule through
+  `tools/background-run.ts` (`createBackgroundRuns`): interactive, ONE tracker run rooted at
+  `async:<runId>` (receipt now, one completion follow-up); headless, the same run joined inline. A
+  persona's `council:` defaults resolve exactly as before when the call omits strategy/roster/params; the
+  mandated `orchestration:` path stays pre-turn and inline, and `/orchestrate`, `/flow` and that path
+  register their own abort under their root row (`visibleRoot`). A rejected `gate: true` returns
+  `stoppedAtGate` (`ok` stays false, so mandatory flows still fail closed; a tracker run settles
+  `stopped`). Stop-all, checkpoint waits, operator-result hand-off, run ids, restore honesty, flow journal
+  identity (`flowRunHash`) and retention are in
+  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#supervision--the-waiting-model).
   Periodic async status and each newly detected stall episode are durable, expandable operator-only
-  entries. Interactive stalls never wake the model; headless sessions get at most one stall wake per run
-  lifetime. Completions, asks, and unread bus messages keep their existing actionable paths.
+  entries; stalls never wake the model. Completions, asks, and unread bus messages keep their
+  existing actionable paths.
   Message ids and run ids are separate: `intercom message { messageId }` retrieves retained bus
   text, `intercom result { to: runId }` retrieves a settled run. Both explicit and automatic inbox
   drains retain bounded history (256 messages / 256,000 body characters). Ask settlement clears
@@ -129,7 +154,7 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   reaches the supervisor as a follow-up or tool result (prompt-injection defense).
 - **Delegation nudges** (`core/nudge.ts`, on by default): 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),
+  last `delegate`/`council`/`flow` crosses a threshold),
   APPENDS a compact labelled checkpoint to that command's result for the model AND emits the same
   checkpoint as a durable, expandable `pi-persona-nudge` TUI-only entry for the operator. It is never
   hidden/context-only: tool renderers may suppress their own `content`, but cannot suppress the
@@ -137,10 +162,11 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   directive has decayed. Pure state machine (`DelegationNudge`); gated to
   personas holding the `delegate` tool; sub-agents run in separate sessions so the hook only sees the
   supervisor. Its counterweight is **`PersistenceNudge`** — a leg that comes back `[BLOCKED]`/`FLAG:
-  UNKNOWN` gets a "don't bank it yet" reminder on each of the three delivery paths (sync result,
-  background completion, `intercom wait` — the last two via `engine/async.ts`'s `renderCompletion`), but
-  they do not scan the same text: `observe` scans the whole sync tool result (which `aggregateResults`
-  fills with every leg's body, failures included), while `renderCompletion` scans only `status: "done"`
+  UNKNOWN` gets a "don't bank it yet" reminder on each of its three delivery paths (the inline
+  `delegate`/`council`/`flow` result — headless only; the background completion
+  via `engine/async.ts`'s `renderCompletion`; and an explicit `intercom result` of a done run), but
+  they do not scan the same text: `observe` scans the whole sync tool result (every leg's body,
+  failures included; a headless `delegate` returns it unclipped), while `renderCompletion` scans only `status: "done"`
   runs. A background leg that FAILED while emitting `[BLOCKED]` therefore gets the failure block but no
   persistence note — deliberate (see the `renderCompletion` doc comment), not a bug to "fix" silently.
   Nested reports from codemode's `ctx.executeTool` retain bounded provenance through Pi's explicit
@@ -148,12 +174,13 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   the surrender marker gets the note/card. Nested programmatic data is never patched with a reminder,
   and discarded reports never generate an invisible one. Relay state clears at turn/session settlement.
   `config.nudge` (`PI_PERSONA_NUDGE=off`) silences all of it: the `tool_result` hook (the by-hand
-  reminder and the sync-result persistence one) and both `renderCompletion` call sites, which take
-  their `scan` through the same gate — so a background/`intercom wait` report carries no note either.
+  reminder and the sync-result persistence one) and the `renderCompletion` / `intercom result` paths,
+  which take their `scan` through the same gate — so a collected report carries no note either.
   Its standing counterpart is the **delegation brief** (`core/brief.ts`): `before_agent_start` appends
-  a live, capability-filtered roster (agents/teams/flows) + a hand-off default to the
-  system-prompt TAIL every turn — discovery that survives context burn.
-- **Sibling peer comm (in-process)**: a strategy can opt a run into direct sibling messaging
+  a live, capability-filtered roster (agents, teams and flows, with descriptions and gated flows tagged in
+  headless sessions) + a hand-off default (with one decision-class → method line, checked against the
+  registry) to the system-prompt TAIL every turn — discovery that survives context burn.
+- **Sibling peer comm**: a strategy can opt a run into direct sibling messaging
   (`AgentRunSpec.peers` — the `debate` strategy does). The child gets a `contact_peer` tool
   (`bus/peers.ts`): `list`/`send`, ONE-WAY only (blocking stays supervisor-only, so peers can
   never deadlock), peer list scoped per engine instance (never the whole bus), send budget 20,
@@ -161,7 +188,11 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   Delivery: the in-process engine's bridge steers incoming bus messages into the child session,
   fenced with the sender attributed OUTSIDE the fence — the same bridge delivers the supervisor's
   `intercom send` (previously a dead letter). Gated by `EffectiveCapabilities.canUseBus` (OFF iff
-  the persona explicitly denies `intercom`). The child engine ignores `peers`.
+  the persona explicitly denies `intercom`). Child-process legs use the broker's engine-scoped
+  peer roster; `contact_peer` is installed only when that run opts in and the bus is allowed.
+  Granted communication tools join a nonempty child tool allowlist; explicit empty lists and
+  tool exclusions still win. In-process supervisor contact additionally requires `coaching`;
+  broker-connected children expose it when the bus is allowed.
   Design: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#the-comm-plane-in-practice) + [`docs/STRATEGIES.md`](docs/STRATEGIES.md).
   On the peer plane: `debate` and `pair` always; `map`/`synthesize` opt-in via `params.peers`.
   `magi`/`judge`/`fanout` stay peer-less BY DESIGN — independence is their bias guard
@@ -169,38 +200,37 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   this. `compete` runs its competitors with `isolation: worktree` (REQUIRES a clean git repo; missing
   repo/dirty checkout/worktree failure fails closed and never falls back to the real tree) and returns
   the winning diff for the SUPERVISOR to apply.
-- **exocom** (`src/exocom/*`, `src/tools/exocom*.ts`; opt-in `PI_PERSONA_EXOCOM=1` / `--exocom`,
-  capability-gated): a plane apart from everything above — those are all INTERNAL to one supervisor's
-  own run (hierarchical, session-keyed children); exocom is FLAT and EXTERNAL, between independent
-  top-level pi instances sharing one selected scope, no parent/child relationship. Bare `--exocom`
-  keeps the current workspace scope; exact `--exocom=Ab0T` joins that existing workspace's scope from
-  another cwd through a persistent, collision-aware, case-sensitive four-character Base62 alias.
-  The scope selects registry/transport/ledger/artifacts, while every peer advertises its actual home
-  workspace id/code/safe label so external file sets are explicit. A foreign peer is advisory for
-  writes: it can inspect its own files and use postcards/ask/answer/wait/progress/release, but
-  `exocom_claim` is inactive and rejected because the ledger's paths are repository-relative to the
-  scope workspace. The code is a same-host/same-agent-dir join reference, not authentication.
-  Postcards remain one-way and non-blocking: `exocom_list`/`exocom_send`
-  plus `exocom_name` (a reply is a send with `in_reply_to` set). The separate shared JSONL work
-  ledger adds `claim`/`ask`/`answer`/`decline`/non-blocking `wait`/`progress`/`release`: overlapping
-  open write sets NACK atomically, and a pending targeted ask gates that participant to answer/decline,
-  read-only tools, and `exocom_name` identity metadata. Semantic frames are signed immediate-wake signals; the ledger is authoritative
-  if delivery is deferred. This is cooperative runtime coordination, not OS authorization. All ten
-  tools remain in `EXOCOM_TOOL_NAMES` (with `claim` withheld for a foreign member), targeted denies win independently, and joining requires
-  `canUseBus` plus at least one callable closer (`answer` or `decline`) so a published peer cannot be
-  wedged by an obligation it has no way to settle. If `exocom_name` is permitted, an unnamed top-level
-  Pi is prompted to invent a task-derived call-sign on its first user or inbound peer turn
-  (no catalog or extra model call). Naming is metadata permitted during pending asks, without
-  settling them; a targeted deny suppresses the prompt. Session identity is shared with standalone
-  `agent_name` and persisted across resume/persona changes. Until a handle is chosen, its actionable
-  naming bootstrap is delivered through the `context` hook because custom Exocom wakes can bypass
-  `before_agent_start`; after selection the hook stays silent. The session-hash suffix of a qualified target survives renames and telemetry resolves the
-  same canonical session.
-  Reuses the broker's wire framing
-  (`bus/broker/framing.ts`) and the
-  core fence (`fenceUntrusted`/`attributeInbound`) — no new trust-sensitive code path; inbound
-  attribution is resolved from the registry, never the envelope's self-reported `from_name`.
-  Design: [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#exocom--the-external-plane).
+- **Exocom** (`src/exocom/*`, `src/tools/exocom*.ts`; opt-in `PI_PERSONA_EXOCOM=1` / `--exocom`;
+  see [the collaboration guide](docs/COLLABORATION.md)): a flat external plane between independent,
+  top-level Pi sessions, separate from one supervisor's internal workers. Bare `--exocom` selects the
+  current workspace; exact `--exocom=Ab0T` joins that existing scope from another cwd through a
+  persistent, case-sensitive four-character Base62 alias. The scope selects registry, transport,
+  ledger and artifacts; each member still advertises its actual home workspace. The code is a
+  same-host/same-agent-dir join reference, not authentication.
+  `EXOCOM_TOOL_NAMES` contains 15 call-time-gated tools: `exocom_list`, `exocom_send`, `exocom_name`,
+  `exocom_claim`, `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait`, `exocom_release`,
+  `exocom_progress`, `exocom_status`, `exocom_task`, `exocom_offer`, `exocom_publish`, and
+  `exocom_profile`. A joined foreign-workspace peer cannot use `exocom_claim`; write-set task create
+  and pickup also require local scope and callable claim permission. Ledger paths are advisory
+  coordination, never filesystem authorization.
+  `exocom_task create` declares a voluntary task but does not start work or reserve files. The
+  immutable `task_id` is the creation frame's `msg_id`; carry it with `work_key` for take, progress,
+  finish, offer and publish so a reused work key cannot select another generation. Write-set pickup
+  and its claim are one locked ledger transaction; read-only tasks may be taken from a foreign scope.
+  An optional `exocom_offer` expires in at most 24 hours (one hour by default) and creates no answer
+  obligation. Use `exocom_ask` for an explicit blocking question. `exocom_publish` shares a bounded,
+  explicitly written excerpt, not another session's terminal-result archive. Peer prose is fenced and
+  attributed using the registry identity.
+  Tasks, offers and evidence are each capped at 64 records and 128 KiB aggregate. Terminal or stale
+  task facts and expired offers are retained for up to one hour; evidence is retained for up to one
+  hour. `exocom_profile` reports self-described capabilities (up to 8 tags, 48 characters each) and
+  optional `available`/`busy`/`away` status; absent status is unknown, and profiles confer no access.
+  During a pending ask, only settlement, `exocom_name`, status, explicit collaboration reads and
+  read-only filesystem tools remain available: profile `get` is allowed, but `set` and `clear` are not.
+  Naming remains metadata and does not answer the ask. Joining requires `canUseBus` plus at least one
+  callable ask closer (`exocom_answer` or `exocom_decline`) and is rechecked on persona changes.
+  Design: [architecture](docs/ARCHITECTURE.md#exocom--the-external-plane) and
+  [collaboration guide](docs/COLLABORATION.md).
 
 ## Testing
 
@@ -232,13 +262,18 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   (`output`) or jobs (`exit`), with both `monitor` and `bash` permissions. Pure lifecycle is in
   `src/core/monitor.ts`, process/delivery adapters in `src/monitor/`; use the existing idle notifier
   and process-tree cleanup. Session-scoped, no restoration on restart. See [`docs/MONITORS.md`](docs/MONITORS.md).
+  Armed timers and active monitors also show as agent-tree rows (`monitor:<id>` / `timer:<id>`, never
+  agents): `src/ui/wake-rows.ts` is the pure projection, fed by the core seams `TimerScheduler`
+  `onArmed`/`onCancelled`, `MonitorManager` `onArmed`/`onRemoved` and `createMonitorSession`'s `observe`
+  option (a terminal event is observed before the permission gate). A countdown replaces the stall clock; `x`
+  cancels one via the stop registry; `X`, the `N agents` count and telemetry exclude them.
 
-- `src/core/` — pure kernel: frontmatter, permissions, contract (+`parseContract`), config, discovery, fence (`fenceUntrusted`), brief (`buildDelegationBrief` — the per-turn roster + standing hand-off default; `buildExocomBrief` — the per-turn exocom peer roster, the peer-vs-sub-agent split, and the relevance bound on a peer exchange), timer (`TimerScheduler` — the alarm engine behind the `timer` tool), types.
+- `src/core/` — pure kernel: frontmatter, permissions, contract (+`parseContract`), config, discovery, fence (`fenceUntrusted`), brief (`buildDelegationBrief` — the per-turn roster + standing hand-off default; `buildExocomBrief` — the per-turn exocom peer roster, the peer-vs-sub-agent split, and the relevance bound on a peer exchange), timer (`TimerScheduler` — the alarm engine behind the `timer` tool), session-runs (pure restore-notice helper: what a reload/resume lost + the run-id counter), types.
 - `src/engine/` — `child.ts`, `inproc.ts` (default), `adapter.ts`, `async.ts` (async tracker/peek), `worktree.ts` (git-worktree isolation), `stream.ts` (event→state).
 - `src/orchestration/` — `sdk.ts` (`agent`/`parallel`/`reduce`), `strategy.ts` (registry), `strategies/*.ts`, `voting.ts`, `flow*.ts` (DAG + JSONL journal + checkpoint gates), `roster.ts` (teams + `rosterSpec`: a roster member is a bare name OR an inline `{ agent, role, model, skills }` that specialises one agent — every strategy runs members through `rosterSpec`).
 - `src/bus/` — `inproc.ts` (handle-based bus: send/ask/reply/onMessage), `contact.ts` (child `contact_supervisor` tool), `peers.ts` (child `contact_peer` sibling tool — one-way, engine-scoped), `broker/` (cross-process relay, on by default: `paths.ts`/`framing.ts`/`messages.ts` pure, `host.ts`/`client.ts` over `node:net`; `PI_PERSONA_BROKER=off` restores pre-broker spawn). `src/bridge.ts` — the child-mode-only wiring loaded when `PI_PERSONA_BUS` is set.
 - `src/persona/` — `persona.ts` (parse + `expandCouncilPreset`), `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts` (pure model helpers), `settings-store.ts` (sole persistent settings owner).
-- `src/tools/` — `delegate.ts`, `intercom.ts`, `exocom.ts`. `src/ui/` — agent-tree/overlay, model-picker, `presentation.ts` (the collapsed-card compaction/sanitization helpers), `usage.ts`. `src/extension.ts` — the single ExtensionFactory (wires tools/commands/hooks/engines).
+- `src/tools/` — `delegate.ts`, `intercom.ts`, `exocom.ts`, `background-run.ts` (tracked background council/flow runs: `launch`/`settle`, `TrackedRun`). `src/ui/` — agent-tree/overlay, model-picker, `presentation.ts` (the collapsed-card compaction/sanitization helpers), `wake-rows.ts` (the monitor/timer → tree-row projection), `usage.ts`. `src/extension.ts` — the single ExtensionFactory (wires tools/commands/hooks/engines).
 - Bundled data-driven assets (discovery precedence builtin < user `~/.pi/agent/persona` < project `.pi/`):
   `personas/*.md`, `agents/*.md` (personas+agents share a folder, split by `persona: true` — a
   persona and an agent must NOT share a name; e.g. `researcher` is the persona, `research` the agent),
@@ -248,7 +283,9 @@ the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
   install shows NO personas until the user installs them. `/persona seed` copies missing defaults
   in, `/persona restore` force-restores originals (`src/core/seed.ts`). First-run auto-install is
   **opt-in**: off by default, enable with `PI_PERSONA_SEED=on` (guarded once by marker
-  `.pi-persona-seeded`). Contracts/presets/teams keep a builtin layer (they aren't personas).
+  `.pi-persona-seeded`). Release prep: add the previous tag's digest
+  to `LEGACY_SEEDED_DEFAULTS` for every changed persona/agent (the guard test in `seed.test.ts` prints the row).
+  F8 and `/doctor` point to `/persona seed` when no personas are installed. Contracts/presets/teams keep a builtin layer (they aren't personas).
 - `scripts/` — `drive.ts` (headless `pi -p` log) + `drive-status.ts` (its pure exit-code/status projection), `control-test.mjs`, `flow-test.ts`, `live-suite.mjs` (every strategy/mode against a real model), `exocom-smoke.mjs` (real socket/pipe round-trip, chat + semantic claim; run via `npm run smoke:exocom`). `test/` — unit + integration.
 
 ## Adding a new X (data-driven — usually no core change)
@@ -268,14 +305,16 @@ their five preferences share the same registry/file. Do not hard-import a compan
 while collecting settings. Flow port/idle changes are for the next shared-service start, never a restart
 of a service other Pi sessions are using. Skill Optimizer remains independent.
 
-1. **Strategy**: add `src/orchestration/strategies/<name>.ts` (export a `Strategy`), register it in `strategy.ts` `BUILTINS`, add a unit test.
+1. **Strategy**: add `src/orchestration/strategies/<name>.ts` (export a `Strategy`), register it in `strategy.ts` `BUILTINS`, add a unit test. Declare `when` (one line), `roster` (positional roles, only where position matters) and `required` (param keys a call must carry) — the `council` tool description is generated from them (`strategyCatalog`) and refuses a missing required param up front; never hand-write a strategy list.
 2. **Persona**: `personas/<name>.md` — frontmatter `persona: true` + optional `council:` / `orchestration:` / `delegation:` / `coaching: true`; runtime behavior is field-driven, never keyed to a persona name.
-3. **Agent**: `agents/<name>.md` — optional `tools`, `model`, `isolation: worktree`, `mcp: true`
+3. **Agent**: `agents/<name>.md` — optional `tools`, `model`, `writeSet` (repository-relative paths the
+   agent alone writes, e.g. `research` → `[.research/]`; inherited by a write-capable `delegate` leg that gives none, so
+   the ownership gate sees a declared owner — declarative, never enforced), `isolation: worktree`, `mcp: true`
    (routes the leg through the child engine so `pi-mcp-adapter` initializes and its `mcp*`/direct
    tools work — the default in-process engine leaves them "not initialized"; also settable per-leg
    via `delegate`'s `mcp: true` / `AgentRunSpec.mcp`. Pass a server session id in the task to share
    an HTTP backend's state).
-4. **Team**: one line in `teams.yaml` (`name: [agent, ...]`), or per-member `- { agent, role, model?, skills? }` to build an ensemble of perspectives from ONE agent (e.g. `review` is one `reviewer` × 3 lens roles). Same-agent members are disambiguated in the live tree by a role hint (`reviewer · SECURITY`) via `rosterNodeKeys`/`roleHint` (`roster.ts`) + the SDK's per-run key (`sdk.ts`), so three lenses show as three steerable nodes — keep the seeding loops and the SDK key derivation in lockstep if you touch either.
+4. **Team**: one line in `teams.yaml` (`name: [agent, ...]`), or per-member `- { agent, role, model?, skills? }` to build an ensemble of perspectives from ONE agent (e.g. `review` is one `reviewer` × 4 lens roles; `design` pairs `architect` + `reviewer` for `critic-loop`). Same-agent members are disambiguated in the live tree by a role hint (`reviewer · SECURITY`) via `rosterNodeKeys`/`roleHint` (`roster.ts`) + the SDK's per-run key (`sdk.ts`), so four lenses show as four steerable nodes — keep the seeding loops and the SDK key derivation in lockstep if you touch either.
 5. **Flow**: `flows/<name>.flow.json` — phases + `needs`, optional `gate: true` (checkpoint).
 6. **Contract**: `contracts/<name>.contract.json` (request via `outputContract`). **Preset**: `presets/<name>.preset.json`.