@aeondave/pi-persona 1.17.3 → 1.17.5

package/docs/ARCHITECTURE.md

@@ -81,9 +81,10 @@ These are the guardrails a contributor must not violate. They are enforced in co
   by the SDK on every `agent()` call and by the engine per child. Concurrency is shared across all
   calls in one SDK instance; token admission uses completed usage and is rechecked after queueing, so
   active legs can overshoot it. Nesting depth is not one of these numeric knobs — it is structural,
-  capped at 1: a child's whole pi-persona extension activation short-circuits under
-  `PI_PERSONA_DISABLE=1` (the **fork-bomb guard**), so it registers NO tools at all —
-  `delegate`/`council`/`orchestrate`/`flow` included. On the child engine this is a one-shot env var
+  capped at 1: full pi-persona activation short-circuits under `PI_PERSONA_DISABLE=1` (the
+  **fork-bomb guard**), so no supervisor orchestration tools (`delegate`/`council`/`flow`) are
+  registered. A broker-enabled child instead loads the minimal bridge, which registers only
+  granted communication and scoped result-reader tools. On the child engine this is a one-shot env var
   set on each spawned process; the in-process engine instead shares one Node process across
   concurrently-building sub-sessions, so it ref-counts the guard (`inproc.ts`) to keep it set until the
   LAST one finishes. The in-process engine also excludes `ORCHESTRATION_TOOLS` from the child session
@@ -151,6 +152,12 @@ These are the guardrails a contributor must not violate. They are enforced in co
 
 ## Module layout
 
+The supported host is the latest stable Pi (currently 1.4.0). Runtime code uses its public APIs
+directly; obsolete host facades, ignored SDK options and compatibility-only aliases are removed
+with their callers. Genuine host failures remain explicit rather than fabricating session identity
+or model availability. One-way user-data migrations and retained-history readers are separate data
+contracts: they remain only while serving stored user data, not to support an older Pi runtime.
+
 Domain dependencies remain downward-only and acyclic: `core ← all`; `engine`/`bus → core`;
 `orchestration → engine + bus + core`; `persona → orchestration + core`; the Exocom transport and
 ledger → `core + bus`; `tools`/`ui → lower layers`. `src/exocom/install.ts` is deliberately the
@@ -281,10 +288,18 @@ up to 16 names. Same idea, two layers, two caps — see docs/REFERENCE.md's exam
 
 `isolation: worktree` is fail-closed. It requires a clean Git checkout so the detached `HEAD` view
 cannot silently omit staged/unstaged/untracked supervisor work; a non-repository, dirty checkout,
-worktree creation failure, missing diff artifact, or an artifact over the return limit fails the leg —
-the base engine is never invoked against the real tree as a fallback. The diff returns to the
-supervisor before the temporary tree is removed, and every git call is asynchronous so the extension
-host keeps rendering, ticking timers, and serving broker sockets while a large checkout runs.
+worktree creation failure, or a successful leg with neither a captured diff nor a returned unified
+patch fails the leg — the base engine is never invoked against the real tree as a fallback. The
+created worktree starts from the committed `HEAD` only: local ignored files are not copied into it,
+and untracked ignored outputs are not exported. The original checkout's ignored files remain
+untouched; tasks that need local-only inputs must recreate or provide them explicitly. The
+worktree's initial commit is pinned before the worker starts. Export compares the final file state
+against that immutable commit, so worker commits, later unstaged changes and new files are included
+together. The diff is captured before the temporary tree is removed, then returned to the supervisor;
+commit history is not applied to the main checkout. If Git cannot capture the diff but the worker
+returned a unified patch, that patch is retained with a warning that it was worker-provided and not
+verified against the worktree state. Every git call is asynchronous so the extension host keeps
+rendering, ticking timers, and serving broker sockets while a large checkout runs.
 
 Transient retries inside one agent session belong to the host **Pi runtime**'s `retry.*` settings, not
 a persona contract — pi-persona neither parses retry notation nor schedules its own backoff. Both
@@ -307,10 +322,19 @@ models, repeated same-model attempts, stop/timeout/contract/agent/infrastructure
 child/token budgets do not recover. Both attempts are accounted, and a warning plus result metadata
 identify the switch. A per-role model assignment can supplement the legacy per-agent assignment;
 preflight model selection includes external arbiters and other declared agent-valued parameters.
-Live tree and telemetry labels use those participant identities for auxiliary actors too, with
-inline model pins taking precedence. If distinct full roles share a short display hint, the display
-keeps the hint (with `#N` suffixes for repeated node keys) but omits the uncertain model label rather
-than borrowing another role's choice. Routing still resolves the full role key, not the display hint.
+Live tree and telemetry labels resolve auxiliary actors and every repeated roster occurrence from
+the SDK's exact, immutable attempt identity (`agent`, full `role`, explicit `model` and `thinking`),
+alongside its unique node key. Short role hints and `#N` suffixes are presentation only: colliding
+hints never discard a known model or borrow another occurrence's inline pins. Model assignments
+and agent defaults are copied after setup when the engine is constructed, so a queued leg's display
+cannot change with later persona/settings edits. Seeds use each actual roster member; lifecycle
+updates use the actual attempt, including custom strategy calls and auxiliary actors in any order.
+A recovery keeps the node key, changes its requested model, and clears the preceding attempt's Pi
+effort observation. Terminal `modelUsed` and validated effort observations override intent only when
+reported; an absent observation retains the current attempt's intent. Initial effort remains the
+explicit spec request, never inferred provider cognition. Clearing an unknown model emits an empty
+`model` string in a telemetry update, preserving the existing string patch contract without leaving
+a stale previous model in consumers.
 
 **Model assignment repair is configuration, not execution recovery.** `/persona models [profile]`
 is an explicit user edit in the Pi adapter: it reuses `resolveCouncilInvocation`,
@@ -487,8 +511,9 @@ never simultaneously a telemetry event, a routed message, and a UI source of tru
   usage`). Feeds derived UI; never routed as an agent message.
 - **Bus Msg** — semantic agent↔agent communication (`progress · decision · interview`, and sibling
   peer sends). `src/bus`. `progress_update` is a Bus message only, not an EngineEvent.
-- **ProgressView** — a derived, read-only UI view computed *from* EngineEvents. Never authored, never
-  a source of truth. The `f9` agent tree and `peek` digest are ProgressViews.
+- **ProgressView** — a derived, read-only UI view computed from observed runtime lifecycles:
+  EngineEvents, wake-source lifecycles, or the bounded local companion lifecycle below. Never a
+  source of truth. The `f9` agent tree and `peek` digest are ProgressViews.
 
 Steering is a supervisor-to-child control action, distinct from semantic Bus messages; requesting
 steering does not establish that a blocking headless delegate call has been interrupted. The peek digest is
@@ -498,15 +523,83 @@ External telemetry is not a fourth communication plane: it is a generic observer
 future plugins may consume or produce, not an exclusive pi-persona protocol. It observes projected
 events and cannot route, reply, steer, or otherwise control agents.
 
+### Loaded companions and local activity
+
+The local EventBus request `pi-persona:companion:v1` accepts `{ version: 1, respond }` and calls
+`respond` synchronously with `{ version: 1, provider: "pi-persona", role, capabilities }`.
+`role` is `supervisor`, `leg`, or `disabled`; `capabilities.memory` is `1` for a loaded supervisor or
+delegated leg and `false` for a disabled supervisor. `capabilities.activity` is `1` only for an enabled
+supervisor. Persona registers this responder before its bridge and disable guards. Pi owns the
+subscription lifetime and revokes it on disposal/reload. Companions query the loaded extension;
+settings files, package installation, and environment flags cannot establish its presence. This is
+a cooperative local extension contract, not authentication or an OS permission boundary. The
+contract is available from Persona 1.17.5, paired with Mind 0.8.4 or later; qualify both together.
+
+Memory ownership is queried through `pi-persona:memory-owner:v1` with
+`{ version: 1, sessionId, respond }`. Its synchronous response is
+`{ version: 1, provider: "pi-persona", sessionId, ready, persona }`, where `persona` is the actual
+live selection or `null` for Persona off. The native manager/id/file must still match, and `ready`
+remains false until Persona's session startup finishes. `pi-persona:memory-owner-changed:v1`
+broadcasts that same descriptor on readiness, selection and shutdown. A companion loaded first
+must not wait inside its startup hook for a later extension's hook; it can activate on the readiness
+broadcast or its next fresh query. Canonical settings retain startup preferences, not live ownership:
+`persist: false` selections still change this descriptor. Unavailable ownership never authorizes a
+fallback to another persona's saved selection.
+
+Each engine freezes the parent's memory persona when it is built. In-process children receive a
+private ResourceLoader factory and their own native manager/EventBus responder; child processes
+receive the versioned `PI_PERSONA_MEMORY_PERSONA` record only in that spawn's environment. Inherited
+values are scrubbed before spawning. Neither route mutates a shared process-wide persona value.
+Delegated legs expose this frozen owner while retaining their lean memory-only role, including an
+explicit `null` owner when the parent had Persona off.
+
+`pi-persona:activity:v1` contributes operator-only local-work rows through a closed record:
+`{ version: 1, producerId: "pi-persona-mind", activityId, sessionId, phase, state, target }`.
+`phase` is `inspect|stage|apply`, `state` is `running|staged|done|failed`, and `target` is
+`project|persona|shared`; `staged` is valid only for `stage`. No memory text, paths, models, token
+counts, or free-form output are accepted. Ingress matches the active native session and checks its
+manager's current id/file. The producer also captures its native owner and scope across awaits.
+The resulting `Mind` row uses `kind: "activity"`: it has no agent count, steer/stop handle, wake,
+stall badge, or `agent.*` telemetry. The F9 drill-in explains the local phase. Up to eight rows are
+retained, with completed/staged rows evicted before live work; teardown and explicit persona
+selection revoke old rows without cancelling workers. A staged row states that a proposal was
+prepared and requires explicit apply; it does not claim that the plan remains valid indefinitely or
+that model review is running.
+Receipts remain in Mind's session-native cards; local activity events are not replayed on restart.
+
+Mind may request one real async maintenance worker through `pi-persona:mind-worker:v1` with
+the closed record `{ version: 1, sessionId, persona, task, respond }` (task at most 48,000 characters).
+Persona checks the current native session and ready memory owner, actual persona, delegation and
+memory permissions, the persona's raw delegate target rules for `mind`, and idle/no-pending-message
+state. A strict target allowlist must include `mind`; explicit memory/delegate/target denies win.
+No installed agent is required. Accepted
+responses are synchronous `{ ok: true, runId, model, thinking, completion, cancel }`; rejection is
+`{ ok: false, reason }`. `completion` resolves with `{ ok, output, error?, resultRef?, model?, thinking? }`.
+Output remains untrusted data for Mind's bounded proposal parser, never executable code.
+
+This is an ordinary tracked `Mind` sub-agent in the tree and F9, sharing the launch pool, usage,
+progress, stop/steer controls and terminal-result archive. Its private definition has an explicit empty
+tool allowlist and no worker spine. Provider/model and thinking are pinned to the accepting session;
+provider fallback is disabled. The worker has a 180-second cancellation ceiling; owner readiness or
+selection changes cancel it. Mind can also cancel through its accepted handle. Settlement returns
+to the requesting companion and retains operator failure reporting, but never wakes a supervisor
+model turn. Native session teardown cancels it through the ordinary stop registry. Local inspect,
+stage and apply operations continue to use activity rows; model work uses the real agent view.
+
 ## The comm plane in practice
 
 - **In-process bus** (`bus/inproc.ts`) — a handle-based mailbox: `send` (one-way), `ask` (blocks for a
-  reply), `reply`, `onMessage`. `contact_supervisor` (child→supervisor, gated by `coaching: on`) and
+  reply), `reply`, `onMessage`. `contact_supervisor` (child→supervisor, gated by `canUseBus` and,
+  for in-process children, `coaching: on`) and
   `contact_peer` (sibling→sibling) are the child-side tools bound onto it. Each unread inbox holds at
   most 200 messages; overflow evicts an old one-way note first, and an inbox full of live asks rejects
   new delivery rather than stranding a sender. Ask settlement (reply, timeout, abort, departure, or
   failed delivery) releases its timer/listener and unread entry; a previously retained question stays
   readable with `expectsReply: false`, so old questions never advertise an active reply id.
+  Tool outcomes distinguish `answered` from unavailable, timed-out, cancelled and failed requests;
+  delivery evidence is never approval. Headless questions remain nonblocking and unresolved, allowing
+  only independent already-authorized work or a blocked/partial handoff. Pre-aborted calls perform no
+  bus action, and replies racing cancellation are not reported as answers.
 - **Sibling peer comm** — a strategy opts a run in via `AgentRunSpec.peers` (gated by `canUseBus`). The
   child gets `contact_peer` (`list`/`send`, ONE-WAY so peers can never deadlock; per-engine-instance
   scoping; a 20-send budget and an 8,000-character body limit, enforced before consuming a send). The
@@ -524,11 +617,19 @@ events and cannot route, reply, steer, or otherwise control agents.
   notifier, f9, peek) is unchanged by construction. Off ⇒ the host never starts and the child spawns
   byte-identical to pre-broker pi-persona. Ask failures echo the originating `msgId` so the client
   rejects the right request immediately, and a client cancellation propagates only to that connection's
-  own host ask. `extension/broker-host.ts`'s `SupervisorBroker` owns the lifecycle: it starts the host
-  lazily on the first child-engine build, warns once on a failed bind (children built while it's down
-  spawn without a bus endpoint, so they never burn connect backoff against a dead socket), and the next
-  build retries; `/doctor` surfaces its state on one line. A dropped client connection flips the
+  own host ask. A one-way send gets a UUID-correlated host receipt; `delivered: true` means admitted
+  to the bus, not read or acted on by the peer. Each child is limited to 64 pending receipts with a
+  maximum 10-second wait. Abort, disconnect, a full or missing inbox, or a lost receipt reports
+  `delivered: false`. It never waits for a recipient answer or approval and does not replay.
+  `extension/broker-host.ts`'s `SupervisorBroker` owns the lifecycle: it starts
+  the host lazily on the first child-engine build and warns once on a failed bind. Children built while
+  it's down spawn without a bus endpoint, so they never burn connect backoff against a dead socket;
+  the next build retries; `/doctor` surfaces its state on one line. A dropped client connection flips the
   child-side bridge to `⇄ offline` and fails a fresh ask fast rather than hanging.
+  A connected child exposes `contact_supervisor` when `canUseBus` is allowed; `contact_peer` also
+  requires the run's peer opt-in. Granted custom tool names join a nonempty plain allowlist so Pi's
+  host filter does not hide them. Explicit `tools: []` and exclusions remain restrictive. A denied
+  semantic bus does not remove supervisor runtime steering or an independently scoped result reader.
 
 ### Presentation is a projection, not another comm plane
 
@@ -627,6 +728,30 @@ for the supervisor and for explicit retrieval; the default TUI projection is del
   unreadable versions. Session-file deletion owns log deletion; ordinary shutdown saves diagnostics,
   not deletes them. Operator-only expandable log entries do not create model context or extra wakes.
 
+**Terminal result archive** (`src/results/`, `src/extension/results.ts`) applies the same
+ownership model to settled agent work: every terminal delegate/council/flow outcome (and each final
+SDK leg result, after any model recovery) is projected — once, idempotently by immutable origin —
+into a versioned session entry with an opaque `result:<UUID>` reference, independent from runtime
+run ids. Budgets: 128 entries, 8 MiB cumulative serialized payload per owning session file, 512 KiB
+per record; bodies cap at 262,144 UTF-16 units with honest truncation metadata. Unknown, malformed
+and duplicate history still consumes quota; unaccountable history disables new persistence instead
+of resetting it. A fork/copy is a new owning file charged only for the entries it actually carries.
+`storage: "session-entry"` means the host accepted the entry — never an fsync guarantee; memory-only
+retention is labelled as such. Retrieval is read-only: `intercom results` lists, `intercom result
+{ ref, offset, limit }` pages (8,000 default / 16,000 max units, surrogate-safe), with no respawn,
+rebilling, collection or extra wake; reading a page never returns the whole run hidden in metadata.
+A saved result is not a live worker: the restore notice says runtime handles are gone while retained
+reports remain readable. Archive listeners belong to the extension factory/tracker lifetime and are
+installed exactly once. `session_shutdown` revokes that session's archive owner and clears its
+captures. A later activation creates a fresh owner and capture context before the ordinary completion
+listener observes terminal results for that activation; a late callback bound to the old owner cannot
+append into the new session.
+
+Flow reference handoff needs durable session-entry storage when a phase's result feeds a dependent
+phase. In a no-session run, a source phase can finish with a memory-only receipt, but the dependent's
+reader preflight rejects it before that dependent is spawned. Use a persisted session for reference
+handoff across phases, or use inline handoff when no durable reader is available.
+
 This is a UI invariant only: truncating a collapsed card must never be confused with truncating the
 underlying result or changing a strategy's contract.
 
@@ -640,17 +765,22 @@ and message peer-to-peer, with no parent/child relationship. (intercom = interna
 external comm.)
 
 Exocom supplies fenced one-way postcards and presence; chat `message` never mutates shared work
-state. Separately, a workspace work ledger (`ledger.ts`, tools in `tools/exocom-work.ts`) records
-claims/asks/answers/progress/releases. `exocom_ask` canonicalizes its target through
-`plane.resolvePeer` (raw session ids on the ledger, never the display name); registry display name is
-keyed by `from_session`, never the envelope's self-reported `from_name`. A pending ask constrains the
-turn (`gate.ts`: answer/decline plus read-only tools) behind a bounded `pendingAskPrompt`.
-`exocom_wait` is non-blocking. Clean shutdown releases this session's claims/asks; if that best-effort
-write fails, the vanished owner is pruned on the next ledger transaction (live registry sessions are
-the lease), and `expireWaiters` wakes any waiter left behind instead of leaving `exocom_wait` armed
-forever. This gate is cooperative coordination for participating local Pi processes — not filesystem
-authorization, not isolation from another same-user process, and not a delegate/council or task/run
-replacement.
+state. `src/exocom/ledger.ts` stores claims, questions, answers and progress; `src/exocom/collaboration.ts`
+adds voluntary tasks, optional offers and explicit evidence excerpts. Tool adapters live in
+`src/tools/exocom.ts`, `src/tools/exocom-collaboration.ts`, and `src/tools/exocom-profile.ts`.
+`exocom_ask` resolves its target through the live registry to a raw session id, never a display name.
+Attribution is resolved by `from_session`, never the envelope's self-reported `from_name`.
+
+A pending ask gates the participant to `exocom_answer`/`exocom_decline`, `exocom_name` identity
+metadata, `exocom_status`, explicit collaboration reads (`exocom_task` list/get, `exocom_publish`
+read, `exocom_profile` get), and read-only filesystem tools. Profile `set`/`clear` and all other
+mutations remain unavailable until the ask is settled. Naming does not settle an ask. The bounded
+`pendingAskPrompt` explains the outstanding obligation. `exocom_wait` is non-blocking. Clean shutdown
+releases this session's claims/asks; if that best-effort write fails, the vanished owner is pruned on
+the next ledger transaction (live registry sessions are the lease), and `expireWaiters` wakes any
+waiter left behind instead of leaving `exocom_wait` armed forever. This gate is cooperative
+coordination for participating local Pi processes — not filesystem authorization, not isolation from
+another same-user process, and not a delegate/council or task/run replacement.
 
 - **Opt-in, OFF by default.** `PI_PERSONA_EXOCOM=1` or bare `--exocom` joins the current workspace;
   `--exocom=Ab0T` joins an existing scope by its exact, case-sensitive four-character Base62 alias
@@ -677,18 +807,31 @@ replacement.
   standing brief, and `/exocom` label a peer as same-workspace or external without exposing its
   absolute `cwd`. External peers are full Pi instances that can inspect files in their own workspace;
   paths are never implicitly shared.
-- **Postcards plus a durable, non-blocking join.** `exocom_send` returns a `msg_id` immediately; a
-  reply is another `exocom_send` with `in_reply_to` set. `target: "*"` broadcasts postcards
-  best-effort (one unreachable peer doesn't fail the rest). Work coordination is separate:
-  `exocom_ask` commits an obligation to the ledger, `answer`/`decline` settles it, and `exocom_wait`
-  arms a bounded idle wake rather than blocking. The signed frame is a wake signal; the ledger remains
-  the source of truth if delivery is deferred.
+- **Postcards, asks and offers have different obligations.** `exocom_send` returns a `msg_id`
+  immediately; a reply is another `exocom_send` with `in_reply_to` set. `target: "*"` broadcasts
+  postcards best-effort. `exocom_ask` commits a targeted question that must be answered or declined;
+  `exocom_wait` arms a bounded idle wake rather than blocking. `exocom_offer` is an optional,
+  expiring invitation to consider an open task, targeted to one peer or the pool; it creates no ask,
+  no answer obligation and no work authorization. Its default lifetime is one hour, capped at 24 hours.
+  Signed immediate-wake frames are signals; the ledger remains authoritative when delivery is deferred.
+- **Task generations and atomic pickup.** `exocom_task create` records a voluntary objective and
+  declared write set; creation neither launches work nor claims paths. The task's immutable
+  `task_id` is its creation frame's `msg_id`; later take/progress/finish, offer and publish actions
+  carry both `work_key` and `task_id`, so reusing a key cannot attach a delayed action to a newer
+  task. A write-set task's pickup and overlapping write claim commit together under the ledger lock;
+  competing overlapping pickups are rejected. Read-only tasks can be taken by a peer in another
+  workspace scope. A task whose owning registry lease disappears becomes stale and cannot be taken
+  over automatically. `exocom_task list` is paginated; `get` returns the complete bounded task detail,
+  including the exact write set. `exocom_publish` attaches an explicitly authored bounded excerpt to
+  one task generation; discovery pages titles and message ids, and the full excerpt is read by id.
+  These excerpts do not grant access to a peer's terminal-result archive.
 - **Cross-workspace writes are advisory-only in v1.** A repository-relative claim path has meaning
   only in the workspace that owns the selected scope, so a member whose home workspace differs from
-  the scope cannot `exocom_claim` (the tool and the signed-frame receiver both reject a foreign
-  claim) — it can still send, inspect its own files, ask, answer/decline, wait, and release its own
-  asks. Multi-repository write coordination would need a versioned resource namespace; paths from
-  unrelated repositories are never compared as if they named the same files.
+  the scope cannot `exocom_claim` or create/pick up a write-set task (the tool and signed-frame
+  transaction both enforce the scope). It can still read shared tasks/evidence, take read-only tasks,
+  send postcards, ask, answer/decline, and release its own asks. Multi-repository write coordination
+  would need a versioned resource namespace; paths from unrelated repositories are never compared as
+  if they named the same files.
 - **Reply routing is session-stable.** `exocom_list` shows human display names (`name`/`name#2`);
   sends and inbound reply hints use `name@<96-bit session hash>`, so a retained qualified target
   stays valid after a rename. Ambiguous suffix matches fail closed rather than guess. The
@@ -727,15 +870,23 @@ replacement.
   double-trigger a turn. An exchange's LENGTH is instead bounded prompt-side: the per-turn peer brief
   (`core/brief.ts`) carries a relevance bound — send only what changes what someone does — deliberately
   not a round count, since a counter can't see whether a round still serves the work.
-- **Tools are lazy and fail closed.** `exocom_list({ offset?, limit? })` exposes bounded, paginated
-  presence; `exocom_send({ target, message, in_reply_to? })` sends one-way (a session-qualified-looking
-  target resolves only as one, never falling back to a display name, since names are self-chosen);
-  `exocom_name({ name })` rebrands the display call-sign without moving any state. The ledger tools —
-  `exocom_claim`, `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait`, `exocom_progress`,
-  `exocom_release` — are capability-gated with the postcard tools; the live accessor, capability gate,
-  and active-tool set all deny them once the plane stops, since Pi has no dynamic tool-unregister API.
-  Admission requires at least one obligation closer, because every published peer may receive a
-  durable ask and must retain a way to settle it.
+- **Fifteen tools are lazy and fail closed.** `EXOCOM_TOOL_NAMES` lists `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`. Each tool rechecks effective persona capabilities at call
+  time; the live accessor and active-tool set also deny calls once the plane stops, since Pi has no
+  dynamic tool-unregister API. A joined foreign-scope peer has no `exocom_claim`. Admission requires
+  `canUseBus` and at least one callable ask closer, because every published peer may receive a durable
+  ask and must retain a way to settle it.
+- **Collaboration and profile retention are bounded.** The ledger retains at most 64 tasks, 64 offers,
+  and 64 evidence excerpts with a 128 KiB aggregate collaboration-state budget. Task descriptions cap
+  at 2,048 characters; write sets at 64 paths of 256 characters each; progress/finish notes at 4,096.
+  Evidence titles cap at 160 characters and excerpts at 4,096 characters / 8,192 UTF-8 bytes. Finished
+  or stale tasks remain for up to one hour; expired offers remain for up to one hour after expiry, and
+  evidence for up to one hour after publication. Active tasks remain while their owner lease is live.
+  `exocom_profile` contains up to eight self-described capability labels (48 characters each) and
+  optional `available`, `busy` or `away` status. Missing status is unknown. Profiles exist only for
+  their live Exocom session and never prove skills, permission or availability.
 - **Inbound delivery is bounded without loss.** Each message is injected under the same byte cap
   whether plain text or an artifact descriptor. Bursts stay FIFO-queued; each rate-limited wake drains
   as many whole messages as fit, leaving the rest queued. A presentation cap on the collapsed card

package/docs/COLLABORATION.md

@@ -0,0 +1,110 @@
+# Supervised workers and independent colleagues
+
+Use **Intercom** for workers launched by this session. Use **Exocom** for independent Pi sessions
+that choose to collaborate. An Exocom peer is responsible to its own user; messages and shared tasks
+do not make it a subordinate or grant it permission to act.
+
+## Supervising a leg
+
+Choose `thinking` independently of `model` in a delegate or roster entry. The runtime preserves an
+explicit provider choice and reports requested and observed thinking separately. A compact tree
+label is only a projection; it does not prove the provider's internal reasoning effort.
+
+Use `intercom peek` to inspect a particular uncertainty, `steer` to queue an instruction, and `stop`
+to stop work. A steering receipt proves acceptance, not that the worker acted on it. Interactive
+completions wake the supervisor automatically; end the turn instead of polling or sleeping.
+
+`intercom results` lists terminal reports. `intercom result { ref, offset, limit }` reads a bounded
+page after reload. A `result:<UUID>` identifies stored evidence, not a live worker. The receipt says
+whether storage is durable or memory-only and whether retention truncated the original report.
+Paging to the end cannot restore text that exceeded the retention ceiling.
+
+An unanswered decision remains unresolved. Timeout, cancellation, disconnection and headless delivery
+never imply approval. Continue only independent work already authorized, or return a partial result.
+
+## Sharing an objective without a leader
+
+Start participating sessions with `--exocom` in the same workspace, or join an existing scope with
+its code as described in [the user guide](EXPERIENCE.md#work-with-another-pi-through-exocom).
+Use `exocom_list` to find stable qualified targets and self-reported profiles. A profile's capabilities
+and availability are suggestions for choosing a colleague, not verified skills, reservations or tool
+permissions. Missing availability is **unknown**. Profiles disappear when the Exocom plane stops.
+
+1. Describe an independent slice with `exocom_task { action: "create", work_key, description,
+   write_set }`. An empty write set means read-only work. Creation is an invitation to collaborate,
+   not an assignment. Keep tasks within the users' authorized objective.
+2. Inspect tasks using `exocom_task { action: "list", offset, limit, detail }`. Every task carries a
+   `task_id`, the immutable creation message ID, alongside its human-selected `work_key`. Before
+   taking a write task, use `exocom_task { action: "get", work_key, task_id }` to inspect the complete
+   bounded write set; list previews may shorten paths.
+3. Optionally send `exocom_offer { work_key, task_id, target, expiresInMinutes }`. Omitting target
+   records a pool invitation for discovery; it does not broadcast a model wake. A targeted offer uses
+   the existing signed wake path. Default expiry is one hour, maximum 24 hours. It never creates a
+   response obligation; expiration is not acceptance or rejection.
+4. A colleague voluntarily calls `exocom_task { action: "take", work_key, task_id }`. Pickup and the
+   declared file claim commit atomically; a second pickup or overlapping claim fails. A stale task ID
+   cannot act on a newly created task that reused the same key. Foreign-workspace members may take
+   read-only tasks, but cannot create or take write tasks in the joined scope.
+5. The taker posts `progress` with a bounded `note`, then `finish` with `outcome: "done"` or
+   `"abandoned"` and a note, always supplying the same `work_key` and `task_id`. The latest progress
+   note is retained. Finishing releases the task's claim; it never merges or approves code.
+
+Task division does not need leader election. Each task has one taker and its own claim. Peers choose
+separate open tasks; availability and execution remain up to each session. A peer may propose a different split, decline by doing
+nothing with an offer, or discuss a conflict in a postcard. If a decision belongs to a user, bring it
+to that user; there is no automatic arbitration or authority transfer between peers.
+
+Use `exocom_ask` only when a peer's answer must gate the next action. Unlike an offer, an ask constrains
+its addressee until `exocom_answer` or `exocom_decline`. Identity metadata and explicit read actions
+remain available. `exocom_wait` arms a nonblocking wake; it does not block the current tool call.
+
+## Publishing evidence
+
+`exocom_publish { action: "publish", work_key, task_id, title, excerpt }` copies an explicit excerpt
+into the shared ledger. A title is at most 160 characters; an excerpt is at most 4,096 UTF-16 units
+and 8,192 UTF-8 bytes. No tool follows paths or archive references in that text. To share a retained
+leg report, read the needed page through Intercom, select the relevant excerpt, then publish that text.
+
+Discover evidence with `exocom_publish { action: "read", work_key, offset, limit }`, then retrieve one
+excerpt with `msg_id`. Publisher identity is resolved from the registry or retained session ID, never
+the envelope's claimed display name. The excerpt remains fenced peer data. Verify its claims before
+using it; a peer's `done` means that peer finished its task, not that checks passed or a reviewer approved.
+
+## Failure, retention and controls
+
+`exocom_status` and `/exocom` show claims, questions, shared task states and invitations. Task lists
+default to 10 entries (maximum 20); detailed pages default to 5 and allow at most 5. Evidence-title pages are bounded.
+Tool cards collapse long content and expand using Pi's normal keybinding; this never changes the
+stored evidence or the text supplied to the model.
+
+Loss of a task owner's registry lease or explicit release marks unfinished work **stale**. It never
+silently reopens the task. Inspect the work and create a newly scoped task if reassignment is needed.
+Clean shutdown releases both write and read-only task ownership. `exocom_release` intentionally
+releases this session's current ownership and outbound asks on a work key.
+
+The ledger retains at most 64 tasks, 64 offers and 64 evidence excerpts in a 128 KiB collaboration
+budget, including lifecycle headroom. Terminal/stale tasks remain visible for the existing one-hour
+result retention window; offers remain until one hour after expiry, evidence for one hour after
+publication. Removing a task also removes its related offers/evidence. Live open/taken tasks are not
+evicted to admit new work. Limits fail explicitly; there is no silent ownership loss or global archive
+access. Transactions perform durable cleanup; reads project current expiry without starting workers.
+
+## Contract boundaries
+
+| Boundary | Required meaning | Enforcement |
+|---|---|---|
+| Intercom vs Exocom | Worker supervision vs independent peers | Existing capability gates, attribution and distinct transports |
+| Delivery vs decision | Accepted/delivered is not answered, acted or approved | Explicit outcomes and unresolved guidance |
+| Task identity | A reused key cannot retarget old intent | Creation `task_id` checked inside the ledger transaction and signed on frames |
+| Pickup and ownership | One taker, claim admitted together, no overlap | Atomic ledger transaction; scope/capability admission inside its lock |
+| Optional offer vs ask | Invitations never gate; targeted asks do | Separate records, tool actions and pending-ask gate |
+| Evidence | Explicit bounded copied text, no cross-session archive access | Schema validation, ledger budgets, registry attribution and fences |
+| Persistence | Versioned authoritative state must not become an empty ledger on error | Snapshot validation, retained-message idempotency and lifecycle budget reservation |
+| Retention | Stale is visible, expiry never implies takeover | First-stale timestamp, bounded retention, fresh generation on recreation |
+| Profiles and views | Self-report/projection cannot grant authority | Separate presence metadata and runtime-owned status |
+| Flow references | Only compatible, successful archived phases can resume | Journal-version/status checks, scoped reads, explicit unavailable/truncated outcomes |
+
+These are runtime contracts. The existing `outputContract` facility validates a worker's final JSON
+report with scalar fields; a model-written `proof` is not a command receipt. It is not the right place
+to encode task ownership or ledger transitions. Nested report schemas and host-executed acceptance
+receipts remain separate product work; this collaboration protocol does not claim to implement them.

package/docs/EXPERIENCE.md

@@ -80,6 +80,10 @@ receipt previews the message that was actually queued; expand it (`Ctrl+O` by de
 configured key) to read the full message and diagnostic run ID. Aliases are display names, not
 addresses: tools still route by run ID, and duplicate aliases show a secondary ID to distinguish them.
 Saved launch/control receipts keep their display names even after the runtime tracker is gone.
+Council and flow launch receipts also retain each participant's model and requested effort, with
+phase and auxiliary roles identified. Expand the card for the full panel. A pending model choice
+is marked explicitly; launch selections are not proof of the effective model or effort after
+setup, provider recovery or Pi's effort adjustment. Later settings changes do not rewrite history.
 
 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:
@@ -92,14 +96,35 @@ 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.
+Use Intercom for this supervisor's workers and Exocom for independent Pi sessions. Use
+`exocom_list` or `/exocom` to find the intended session-qualified target before sending a postcard
+or asking a question.
+
+`exocom_task create` records a voluntary objective and declared write paths; it does not start
+another Pi or require a peer to accept. The receipt gives a `task_id`; keep it with the
+`work_key` when inviting, taking, reporting progress, finishing or publishing evidence. A work key
+can be reused after retention, so the task id identifies the exact generation. The peer chooses
+whether to take the task. Write-set pickup and its advisory claim happen atomically, but a claim is
+not an OS file lock. A peer that joined from another workspace can take read-only tasks, not tasks
+that claim paths in the selected workspace. Use `exocom_task get` to inspect the complete write set;
+the paginated list is a summary.
+
+Use `exocom_offer` for a non-blocking invitation that expires by itself; it creates no obligation
+to answer. Use `exocom_ask` when a specific decision is needed and the recipient must answer or
+decline. A pending ask temporarily permits settlement, `exocom_name`, `exocom_status`, explicit
+read actions (task list/get, evidence read and profile get), and read-only filesystem tools.
+Changing `exocom_profile` is not allowed while an ask is pending. Changing the name does not answer
+the ask.
+
+Share only a bounded excerpt through `exocom_publish`; it does not grant access to another session's
+terminal-result archive. Peer text is untrusted and appears fenced with registry-resolved attribution.
+Capability labels and availability in `exocom_profile` are self-reported metadata, not verified
+skills or permissions. Exchange decisions and evidence when they affect the work; acknowledgement-only
+conversations add noise. If a peer joined from another workspace, agree which workspace owns each
+artifact.
+
+See the [cross-session collaboration guide](./COLLABORATION.md) for command shapes, retention limits,
+and detailed examples.
 
 `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

package/docs/README.md

@@ -16,6 +16,8 @@ introduced a behavior. An `Unreleased` entry is not yet part of a published rele
   - Vendor-neutral observer contract, privacy boundary, persistence, and consumer conformance.
 - [`EXPERIENCE.md`](./EXPERIENCE.md)
   - Choosing a persona, supervising background work, and collaborating through Exocom.
+- [`COLLABORATION.md`](./COLLABORATION.md)
+  - Intercom supervision, voluntary peer tasks, invitations, evidence, retention and runtime contracts.
 - [`MONITORS.md`](./MONITORS.md)
   - Clock snapshots, timers, and background event sources that wake the supervisor.
 - [`REFERENCE.md`](./REFERENCE.md)
@@ -28,6 +30,16 @@ introduced a behavior. An `Unreleased` entry is not yet part of a published rele
 - **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.
 
+## Research and verification records
+
+- [`The pi-subagents comparison`](https://github.com/AeonDave/pi-persona/blob/main/docs/reviews/2026-10-24-pi-subagents.md) records the bounded source
+  study and links its evidence and source notes.
+- [`Current-host cleanup and final requalification`](https://github.com/AeonDave/pi-persona/blob/main/docs/reviews/2026-10-25-current-host-cleanup.md)
+  is the latest qualification report and links the preceding implementation review for its distinct
+  behavioral and live-run evidence.
+- [`ROADMAP.md`](https://github.com/AeonDave/pi-persona/blob/main/ROADMAP.md) tracks the remaining work, including the unqualified
+  [compaction proposal](https://github.com/AeonDave/pi-persona/blob/main/docs/plans/2026-10-20-compaction-evaluation-proposal.md).
+
 ## Documentation maintenance notes
 
 When touching this folder: