@aeondave/pi-persona 1.15.2

package/AGENTS.md

@@ -0,0 +1,249 @@
+# AGENTS.md — pi-persona
+
+A single Pi coding-agent extension for **supervised multi-agent orchestration**: async workers,
+live steering, cross-session collaboration, and switchable personas. Loaded by Pi via tsx/jiti —
+no build step. Design contract (binding on any conflict): [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md);
+the orchestration layer in depth: [`docs/STRATEGIES.md`](docs/STRATEGIES.md);
+the shared behavioral prompt layer: [`docs/SPINE.md`](docs/SPINE.md).
+
+## Commands
+
+- Typecheck (must stay clean): `npm run typecheck`  (`tsc --noEmit`, strict)
+- All tests: `npm test` · unit only: `npm run test:unit`
+- One file: `node --import tsx --import ./test/setup/hermetic-env.ts --test test/unit/core/frontmatter.test.ts`
+  - The second `--import` is the hermeticity choke point: it strips the whole `PI_PERSONA_*`
+    namespace and pins `PI_AGENT_DIR` at a throwaway dir before any test module loads, so a
+    variable exported in your shell (or by CI) cannot reconfigure the extension under the suite.
+    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>"`
+  - Control ops: `LIVE_MODEL=<provider/id> node --import tsx scripts/control-test.mjs` (STEER/STOP/RESUME)
+  - Models must be **provider-qualified**, e.g. `claude-pro-max-native/claude-opus-4-8` or `.../claude-haiku-4-5`.
+
+## Conventions
+
+- **Erasable-syntax-only** TS (no enums / namespaces / parameter-properties) — runs under
+  strip-types, tsx, jiti, Bun. `erasableSyntaxOnly` is on; keep it that way.
+- tsconfig is strict + `exactOptionalPropertyTypes` + `noUncheckedIndexedAccess` +
+  `noUnusedLocals` + `noUnusedParameters`. Keep `tsc` clean before moving on.
+- `src/core/*` is **pure** (no Pi imports) and unit-tested. Import host packages from
+  `@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 lives in `MIN_PI_VERSION` and the README. Keep the npm
+  `files` allowlist explicit for docs/artwork, inspect `npm pack --dry-run`, and never publish drafts.
+- **Cross-OS**: use Pi's spawn/kill/path/temp helpers (`getPiInvocation`, `killProcessTree`), not raw
+  `child_process`. Windows kill goes straight to `taskkill /F /T`; always attach an `error` listener.
+- Two engines behind the `StrategyEngine` seam: **InProcessEngine** (`engine/inproc`,
+  `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
+  `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
+  `PI_PERSONA_AGENT_STARTUP_MS` as a **startup deadline** (a child that makes ZERO progress — no
+  completed turn / tokens / streamed output — within the window is killed as a stalled start; the
+  first real progress cancels it, so a slow-but-streaming turn is never touched; default 300000,
+  `0` disables). 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; `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.
+  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.
+  In-process cancellation and deadlines cover session construction; coaching exemptions apply
+  after it finishes. A cancelled factory's late session is disposed, but its ref-counted guard
+  stays held until the factory settles because Pi's loader itself cannot be forcibly cancelled.
+- **Cross-process broker** (`src/bus/broker/{paths,framing,messages,host,client}.ts`, on by default,
+  spec B1-B7; `PI_PERSONA_BROKER=off` restores pre-broker spawn): session-scoped (POSIX socket /
+  Windows named pipe under the session id), supervisor-hosted, lazily started on the FIRST actual
+  child-engine build (a `PI_PERSONA_ENGINE=child` run, any `isolation: worktree` leg, or an
+  `mcp: true` leg — those ALWAYS use the child engine). It is a 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. It gives child-process runs
+  `contact_supervisor`/`contact_peer` AND **steer** (closing the child-engine steer gap —
+  `intercom steer`/f9 `s` work on both engines; a child's steer is follow-up-queued, not mid-turn
+  injection). Off ⇒ `deps.broker` is never built, the host never starts, and the child spawns
+  byte-identical to pre-broker pi-persona — see
+  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md#the-comm-plane-in-practice).
+- **Provider fallback**: `buildEngine` wraps the engine in `withModelFallback` (`engine/fallback.ts`).
+  A provider-qualified `spec.model` is an explicit provider/billing pin and is strict by default:
+  a failed `openai-codex/...` leg never silently moves to OpenCode, and a failed
+  `claude-pro-max-native/...` leg never silently moves to a metered third-party route. Unpinned/default
+  selections may retry the SAME model id only through the data-driven, family-compatible provider
+  policy (OpenAI-family → OpenAI providers; Claude-family → the native Claude provider). A caller may
+  explicitly opt a pinned run into cross-provider recovery. Only `failureKind === "provider"` reroutes;
+  abort/timeout/contract/unknown/agent are terminal.
+  Engines classify the cause on the `AgentResult` (`failureKind` + resolved `modelUsed`); keep those
+  set when you touch `inproc.ts`/`adapter.ts` or the fallback silently stops working.
+- **Fork-bomb guard**: children run with env `PI_PERSONA_DISABLE=1` so pi-persona self-disables inside
+  them. NEVER pass `noExtensions` (it blocks the pi-claude auth provider). The guard is **ref-counted**
+  in `inproc.ts` — keep it concurrency-safe (parallel strategies build several sessions at once). Both
+  engines also export `PI_PERSONA_LEG=1` for a delegated leg — a **dedicated** marker (unlike the
+  user-settable `PI_PERSONA_DISABLE`) so a companion extension can tell a real leg from a disabled
+  supervisor; set it in lockstep with the disable guard (in-process guard + child `spawn` env).
+- Three disjoint comm planes: **EngineEvent** (runtime) / **Bus Msg** (semantic, `src/bus`) /
+  **ProgressView** (derived UI, never a source of truth). Capabilities are enforced at call time via
+  one `EffectiveCapabilities`, never prompt-only. Per-run pinning: `contract@hash` is frozen at start.
+  Same principle for retries: async failures are ALWAYS reported to the supervisor (never suppressed);
+  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. Async runs
+  are joined with intercom `wait` (bounded ≤ the bus-ask timeout; collected results are discarded from
+  the pending completion follow-up so they are never double-reported). 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).
+  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
+  unread and buffered prompts; broker errors/cancellation remain correlated to the original request.
+- **Sub-agent output is untrusted** — wrap it with `fenceUntrusted` (in `extension.ts`) before it
+  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),
+  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
+  separate card. This is runtime reinforcement in recent context, where a top-of-prompt persona
+  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"`
+  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.
+  `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.
+  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
+  (`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,
+  message body limit 8,000 characters (oversized sends do not consume the budget).
+  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`.
+  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
+  (uncorrelated errors; an anonymised ballot cannot survive members who talked) — do not "fix"
+  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).
+
+## Testing
+
+- TDD: write the failing test first for `core/*` and any behavior change; watch it fail, then fix.
+- Done = `npm run typecheck` clean **and** full suite green. The suite has **two** intentional skips,
+  both Windows-only — the runner reports `skipped 2` on Windows and `skipped 0` elsewhere (see
+  Accepted diagnostics).
+- When touching engines / strategies / the comm plane, also verify with a live `scripts/drive.ts`
+  run (concurrency, steer, worktree, and contact_supervisor are not fully provable from unit tests).
+
+## Project structure
+
+- Session identity: `src/core/session-identity.ts` defines validated names and session-bound
+  persistence; `src/extension/identity.ts` registers `agent_name` and the pre-name context bootstrap.
+  Exocom uses that same state. A delegate's optional `AgentRunSpec.name` is leader-assigned
+  display identity, propagated to both engines without changing routing ids.
+  Runtime metadata guidance belongs in the stable supervisor system prompt, not a new user-like
+  acknowledgement message. Keep initial setup/actionable asks working, preserve user-visible history,
+  and never re-inject a chosen identity. Progress `tokens` is cumulative input/output usage, not live
+  context occupancy; labels must make that distinction explicit.
+
+- Session clock and event wakes: `timer now` refreshes the run-start clock snapshot; timer alarms
+  require an explicit timezone for absolute times. `monitor` runs bounded event-producing programs
+  (`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).
+
+- `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/engine/` — `child.ts`, `inproc.ts` (default), `adapter.ts`, `async.ts` (async tracker/peek), `worktree.ts` (git-worktree isolation), `stream.ts` (event→state).
+- `src/orchestration/` — `sdk.ts` (`agent`/`parallel`/`reduce`), `strategy.ts` (registry), `strategies/*.ts`, `voting.ts`, `flow*.ts` (DAG + JSONL journal + checkpoint gates), `roster.ts` (teams + `rosterSpec`: a roster member is a bare name OR an inline `{ agent, role, model, skills }` that specialises one agent — every strategy runs members through `rosterSpec`).
+- `src/bus/` — `inproc.ts` (handle-based bus: send/ask/reply/onMessage), `contact.ts` (child `contact_supervisor` tool), `peers.ts` (child `contact_peer` sibling tool — one-way, engine-scoped), `broker/` (cross-process relay, on by default: `paths.ts`/`framing.ts`/`messages.ts` pure, `host.ts`/`client.ts` over `node:net`; `PI_PERSONA_BROKER=off` restores pre-broker spawn). `src/bridge.ts` — the child-mode-only wiring loaded when `PI_PERSONA_BUS` is set.
+- `src/persona/` — `persona.ts` (parse + `expandCouncilPreset`), `controller.ts`, `gating.ts`, `orchestrate.ts`, `config-store.ts`.
+- `src/tools/` — `delegate.ts`, `intercom.ts`, `exocom.ts`. `src/ui/` — agent-tree/overlay, model-picker, `presentation.ts` (the collapsed-card compaction/sanitization helpers), `usage.ts`. `src/extension.ts` — the single ExtensionFactory (wires tools/commands/hooks/engines).
+- Bundled data-driven assets (discovery precedence builtin < user `~/.pi/agent/persona` < project `.pi/`):
+  `personas/*.md`, `agents/*.md` (personas+agents share a folder, split by `persona: true` — a
+  persona and an agent must NOT share a name; e.g. `researcher` is the persona, `research` the agent),
+  `teams.yaml`, `flows/*.flow.json`, `contracts/*.contract.json`, `presets/*.preset.json`.
+- Personas/agents load ONLY from the user dir (`~/.pi/agent/persona/agents`) and project `.pi/agents` —
+  the bundled `personas/`+`agents/` are a **seed source, not a live discovery layer**, so a fresh
+  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).
+- `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)
+
+1. **Strategy**: add `src/orchestration/strategies/<name>.ts` (export a `Strategy`), register it in `strategy.ts` `BUILTINS`, add a unit test.
+2. **Persona**: `personas/<name>.md` — frontmatter `persona: true` + optional `council:` / `orchestration:` / `delegation:` / `coaching: true`; runtime behavior is field-driven, never keyed to a persona name.
+3. **Agent**: `agents/<name>.md` — optional `tools`, `model`, `isolation: worktree`, `mcp: true`
+   (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.
+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`.
+
+## Boundaries / deferred (do NOT rebuild as "missing")
+
+- **`context: fork`** is deliberately deferred: `fresh` is the right child default. The
+  **cross-process bus broker** is NO LONGER deferred — see the engine/broker bullet above and
+  [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md).
+- This repo is `D:\Sources\pi-persona`. The separate `D:\Sources\pi-subagents-persona` (flat
+  `src/index.ts`, `VALID_THINKING`, …) is a **legacy** package — different project. Always use
+  explicit `pi-persona` paths in shells and sub-agent prompts (the env default cwd is the legacy one).
+
+## Accepted diagnostics
+
+- Two skipped Windows-only cases in `test/integration/child-engine.test.ts` (force tree-kill and external-signal handling) — intentional, do not "fix".
+- `test/integration/broker.test.ts` (real socket/pipe round-trip) runs UNGATED on every platform,
+  Windows named pipes included — it proved reliable across repeated runs; do not add a skip to it
+  without first confirming genuine flakiness (see the v0.5 broker task report).

package/CHANGELOG.md

@@ -0,0 +1,260 @@
+# Changelog
+
+All notable changes to this project are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/); this project follows the version scheme
+used in its [GitHub releases](https://github.com/AeonDave/pi-persona/releases).
+
+## [Unreleased]
+
+## [1.15.2](https://github.com/AeonDave/pi-persona/releases/tag/v1.15.2) - 2026-09-28
+
+### Distribution
+
+- First npm publication on 2026-09-29 as `@aeondave/pi-persona@1.15.2`, with the same runtime
+  version. The existing GitHub tag is unchanged; npm adds scoped package metadata and installation
+  instructions. The registry's `gitHead` identifies the packaging commit.
+- Declare Pi-provided packages and TypeBox as wildcard peers, with pinned development copies only.
+  Explicitly allowlist public documentation and selected artwork; exclude drafts and development
+  harnesses from the npm tarball. Add the gallery banner and F8 persona-switching video preview.
+- Lead the README and package description with supervised multi-agent orchestration, live steering,
+  and cross-session collaboration; personas configure that workflow.
+
+### Fixed
+
+- Add stable supervisor-side runtime guidance against repeated identity/prefetch acknowledgements,
+  including resumed sessions and custom/replace personas without the optional spine. The naming
+  bootstrap now explicitly ends at the successful tool action. No extra corrective turns are injected,
+  no history is rewritten, and explicit user questions or unresolved actions remain actionable.
+- Replace conversational naming confirmations with a neutral saved/unchanged handle receipt, shared
+  by the model-facing result and the visible renderer.
+- Label async progress token counts as cumulative input/output rather than leaving them open to
+  interpretation as current context usage. Routine updates distinguish status from a new user task.
+
+### Changed
+
+- Delegation, failed-hand-off, and persistence nudges are now compact labelled checkpoints with an
+  explicit trigger and action. Token counts are identified as estimates, session-bound work is
+  separated from delegable work, and each synchronous checkpoint is mirrored from its semantic tool
+  result into a durable, expandable TUI-only card. This keeps it visible even when a tool renderer
+  suppresses result content without duplicating it into model context or triggering another turn.
+- Refresh the README with a clearer installation guide, the Prism banner, and an illustrated
+  supervisor/worker workflow.
+
+After updating, let active delegated runs settle, then restart Pi or use `/reload` before the next
+user turn. `/persona reload` refreshes persona definitions, not extension code. Existing chat
+history is preserved; the runtime guidance discourages repetition without filtering model output.
+
+## [1.15.1](https://github.com/AeonDave/pi-persona/releases/tag/v1.15.1) - 2026-09-20
+
+### Changed
+
+- Development validation now uses the current Pi `0.85.1` packages, TypeBox `1.3.34`, and the
+  current Node 22 tooling line while retaining the supported Pi `>=0.83.0` runtime floor.
+- Release metadata is now guarded as one version set across the package manifest, lockfile,
+  telemetry producer, changelog, and README install pin.
+
+### Fixed
+
+- A chosen session identity is no longer re-injected as a hidden user-like message before every
+  provider request. The context hook now emits only the actionable, pre-name bootstrap, preventing
+  tool-loop continuations from narrating repeated identity confirmations.
+- Repeating `agent_name` with the active handle reports it as unchanged instead of announcing a
+  fresh identity again.
+
+## [1.15.0](https://github.com/AeonDave/pi-persona/releases/tag/v1.15.0) - 2026-09-18
+
+### Added
+
+- Live elapsed-time clock and a stall badge (`⚠ stalled <duration>`) on every running row in the
+  agent tree and the F9 overlay; cancelling a worker now marks its row `stopping…` immediately, and
+  a stop that cannot be applied says so instead of doing nothing. A row that is only queued (not yet
+  running) no longer shows the stall badge.
+- A warning toast announces a provider-fallback reroute (`<agent>: <from> failed, retrying on
+  <to>`) instead of switching silently.
+- A non-worktree leg's result now gets a "files changed" report appended: every path `git status`
+  saw change while the leg ran, flagging anything outside the leg's own declared `writeSet`. Costs
+  two `git status` spawns per leg (down from four — the repository root is resolved once and
+  reused, skipping a redundant `rev-parse` gate); `PI_PERSONA_LEG_CHANGE_REPORT=off` disables it.
+- A supported Pi host version floor (0.83) is declared once and enforced consistently:
+  `peerDependencies`, `/doctor`'s new `pi: <version> (requires ≥ 0.83.0)` line, and the README.
+- `exocom_status` (tool) and `/exocom` (command) now show who owns what in the current Exocom
+  scope: your claims, peers' claims, and asks waiting on either side.
+- A `write`/`edit` whose path lands inside a peer's open Exocom claim is now blocked once with a
+  reminder to coordinate (`exocom_ask`) or claim the path first; the identical retry is allowed
+  through.
+- The `map` strategy gains two declared params: `ownership` (`"off"`/`"declare"`/`"enforce"` —
+  ignore, record, or gate on the splitter's per-item write-set before any worker spawns) and
+  `verify` (an opt-in, read-only reviewer pass per completed item), plus an always-on per-item
+  status ledger (`structured.items`: `completed`/`failed`/`not-run`) both params report into.
+- `npm run smoke:exocom` runs the Exocom comm-plane smoke script, now checked against
+  `InboundDeps` and carrying a semantic-frame check.
+
+### Changed
+
+- Agent-tree UI work is now bounded to the terminal's 16 ms frame cadence: structural fan-out and
+  streamed progress share one sticky-widget composition, unchanged widget/status publications are
+  suppressed, the F9 overlay rebuilds lazily on the next paint, and tree rendering indexes the
+  hierarchy once instead of rescanning the whole fan-out for every row. Explicit stop feedback and
+  shutdown clearing remain synchronous.
+- The idle and startup watchdogs now stay armed for every child, coaching or not, and consult the
+  bus (in-process) or the broker (child-process) for a live pending ask before closing a silent
+  leg — re-arming while a supervisor reply is genuinely pending, closing it once the silence is
+  real. The hard wall-clock cap (`PI_PERSONA_AGENT_MAX_MS`) remains the one unconditional backstop.
+- `SupervisorBroker` consolidates the supervisor host's lifecycle into one class: a failure now
+  warns once instead of repeatedly, children spawn bus-less while the broker is down rather than
+  failing outright, and `/doctor` reports the broker's real state.
+- Every Exocom surface that renders a peer-authored field (the status view, the write-guard
+  warning) now goes through one shared sanitizer; the write guard also matches an absolute path
+  against a claim correctly and bounds how many paths a single warning names.
+- Internal deduplication with no behavior change: `delegate`'s unknown-agent/contract error text,
+  the broker client's ask/list reason text, `SupervisorBroker`'s state reads, `AgentTree`'s
+  add/update field copy, `spec-preflight`'s failure-result skeleton, the agent overlay's
+  hint/notice rendering, and every capped-list rendering now share one helper each; a few dead
+  exports and some `/doctor` wording were tidied along the way.
+
+### Fixed
+
+- The engine's unknown-agent/unknown-contract preflight is now one shared module; a
+  contract-not-found error names the installed contracts, and `delegate` rejects an unknown
+  `outputContract` before spawning anything, checked across a whole parallel batch.
+- Worktree git operations now run asynchronously, so an isolated leg can no longer freeze the host
+  session; worktree cleanup is also guarded so a cleanup failure cannot take the run down with it.
+- A dropped broker connection now fails fast, and the bridge reports `⇄ offline` instead of hanging
+  on the next ask.
+- `exocom_wait` now wakes a waiting supervisor as soon as the peer it was waiting on leaves the
+  pool, instead of waiting out the full timeout.
+
+### Removed
+
+- `RunLimits.maxDepth` had no runtime reader — nesting depth is actually enforced structurally (a
+  child registers no `delegate`/`council`/`orchestrate`/`flow` tool and self-disables under
+  `PI_PERSONA_DISABLE`); the docs now state that mechanism directly instead of a limit nothing
+  enforced.
+- Dead code: the unread Exocom ledger wake, `waitMatches`, and the `displayNameFor` alias.
+
+## [1.14.2](https://github.com/AeonDave/pi-persona/releases/tag/v1.14.2) - 2026-09-08
+
+Pi Persona now prompts sessions to choose a personal name before their first task or incoming
+Exocom request, instead of displaying the persona role as their identity. The README puts
+installation and everyday use first.
+
+- Persist session names across persona switches and resume, with distinct provisional handles
+  before a name is chosen. Standalone sessions use `agent_name`; Exocom sessions share the same
+  identity through `exocom_name`.
+- Cover first-message Exocom wakes, refresh peer presence and outgoing names after renaming, and
+  allow identity metadata updates while a work question is pending. Existing tool denials and work
+  obligations still apply.
+- Pass supervisor-assigned worker names into the first prompt and peer labels on both in-process
+  and child-process engines.
+- Reject an unknown explicit `critic-loop` roster with an actionable error instead of silently
+  selecting a different team.
+- Clarify data-preservation, service-impact, and confirmation requirements in the bundled
+  assessment and evidence-review prompts.
+- Upgrade exact, untouched 1.14.1 copies of those two prompts on restart, including LF and CRLF
+  installations; customized copies remain unchanged.
+- Shorten the README from 488 to 159 lines, add Git URL installation and release pinning, and move
+  APIs, configuration, and recipes into `docs/REFERENCE.md`.
+
+## [1.14.1](https://github.com/AeonDave/pi-persona/tree/v1.14.1) - 2026-09-06
+
+*No GitHub release was published for this tag; summarized from `git log v1.14.0..v1.14.1` instead
+of `gh release view` (see the task report for detail).*
+
+- Rewrote the runtime prompts of the security chain (`elite`, `operator`, `evidence-verifier`,
+  `reviewer`, `research`, `scout`) in plain professional language — the method, delegation
+  grammar, evidence discipline, target-egress invariant, and verification loop are unchanged, only
+  the vocabulary is.
+- Renamed the elite council roster `offensive-assurance` → `evidence-assurance` across the persona,
+  `teams.yaml`, the README, and its unit test.
+- Kept the constraints the vocabulary rewrite had softened: authorization/scope statements, the
+  named-skills-only public-reference-code rule, the auth-material reuse check across every
+  reachable service and principal, and the reviewer's standard injection/SSRF vocabulary. Routing
+  targets that had become unresolvable are named again.
+- MAGI cores: rewrapped `melchior`, gave `casper` the same closing rationale as its siblings, and
+  clarified that confidence is the core's own 0.0–1.0 certainty rather than a template placeholder.
+- Shortened the README from 604 to 488 lines, table-first, pointing at `docs/` for the long form.
+
+## [1.14.0](https://github.com/AeonDave/pi-persona/releases/tag/v1.14.0) - 2026-09-06
+
+Pi Persona can now wake a supervisor when a background job finishes or a program reports an event.
+This release also strengthens delegation cancellation, bounded messaging, and the everyday persona
+experience.
+
+### Event monitoring and time awareness
+
+- New `monitor` tool: `exit` mode reports job completion; `output` mode consumes event lines from
+  file, log, system, or service adapters. Events are fenced, bounded, coalesced, and delivered at
+  an idle turn boundary.
+- Monitor defaults: one event and a ten-minute deadline; limits of eight active watches, twenty
+  events per watch, and twenty-four hours. Cancellation stops the owned process tree and removes
+  queued wakes. Both `monitor` and `bash` permissions are required.
+- Fresh UTC/local clock context on every run without continually rewriting the cached system
+  prefix; `timer now` refreshes the clock during a long run.
+- Timer date-times without a timezone are rejected. Alarm confirmations use the scheduler clock,
+  and wake notices distinguish due and observed times.
+
+### Delegation and communication reliability
+
+- In-process startup is covered by cancellation and deadlines, including delayed session creation
+  and cleanup. The concurrent child guard stays held until outstanding initialization settles.
+- The SDK enforces concurrency admission for every agent call, including direct parallel launches;
+  queued and active work respects cancellation and budget checks.
+- Intercom distinguishes retained messages from settled run results. Inbox and retention bounds
+  protect outstanding questions; timeout, disconnect, cancellation, and broker ask settlement
+  release their resources.
+- Late asks and cancelled waits no longer leave stale notifications. Peer messages have explicit
+  size bounds, and communication failures retain useful diagnostics.
+- Overlay regression checks bound the amount of text reprocessed during streaming, keeping the real
+  rendering and output checks while removing dependence on CI hardware speed.
+
+### Persona experience
+
+- Refined `dev`, `planner`, `researcher`, `swarm`, `audit`, and `verify` defaults, with clearer
+  hand-offs, verification, progress reporting, and proportionate scope.
+- Exocom prompt guidance follows each permitted action and distinguishes external workspace
+  membership from a denied claim permission.
+- Research workers create durable artifacts when requested or useful for reuse. Exact-pristine seed
+  migrations preserve customized persona files.
+- Added the experience and monitor guides, plus a persistent RPC monitor smoke harness.
+
+## [1.13.4](https://github.com/AeonDave/pi-persona/releases/tag/v1.13.4) - 2026-09-05
+
+- Opened the tool-start status vocabulary: `tool.started` no longer requires the literal word
+  `running` — the wire contract's allowlist became a denylist, so a start event may name its own
+  in-flight state, but may not claim to already be over. `tool.finished` stays closed so the
+  consumer can always close the call.
+- The shared conformance corpus stays byte-identical with pi-persona-flow; both new cases were
+  proven RED against the previous predicate in both repos.
+
+## [1.13.3](https://github.com/AeonDave/pi-persona/releases/tag/v1.13.3) - 2026-09-05
+
+Patch release hardening the data-root migration 1.13.2 introduced, after an adversarial pass
+reproduced four defects by running the migration against constructed filesystem states.
+
+- The destination side is now `lstat`'d after `mkdirSync`, so a planted or stale link below the
+  current root can no longer carry files through it and delete the legacy original.
+- Fixed a false "could not remove" warning per migrated file under concurrency: the source itself
+  is asked whether it is still there, instead of trusting an ambiguous Windows errno.
+- The "this is not data loss" branch no longer leaves a silent Exocom outage: a link this run
+  created is now undone and the entry reported `kept`, restoring the exact pre-run state.
+- `docs/TELEMETRY.md` now names both roots for v1 flow logs, since the migration relocates that
+  subtree with everything else.
+
+## [1.13.2](https://github.com/AeonDave/pi-persona/releases/tag/v1.13.2) - 2026-09-04
+
+Patch release that consolidates the agent-dir storage on a single root — Exocom and the broker
+still wrote `<agentDir>/pi-persona` while persona data had long since moved to
+`<agentDir>/persona`.
+
+- Moves Exocom's workspace rendezvous (registry, ledger, `agents/`) under
+  `<agentDir>/persona/exocom/<workspace-hash>/`, the durable `exocom/codes/` join-code aliases and
+  their `.used` reservations, and the POSIX broker socket directory (the Windows named pipe is a
+  pipe name, not a path, and is unchanged). Folds an existing `pi-persona` root in once at
+  activation, before anything opens the rendezvous or the socket, and reports the result through
+  `ui.notify` and a `/doctor` line.
+- Migration is atomic, no-clobber, and resumable per file (link then unlink); a name the new root
+  already owns keeps that copy and leaves the legacy copy on disk; non-regular entries (a stale
+  socket, a symlink) are never followed, copied, or removed; a filesystem without hard links falls
+  back to copy-then-unlink; every failure is a per-entry warning, never a startup throw.
+- Upgrade note: Exocom has no dual-read, so restart every live Pi as part of the upgrade, or old and
+  new sessions form two disjoint rendezvous.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dave
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.