@aeondave/pi-persona 1.17.3 → 1.17.4

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:

package/docs/REFERENCE.md

@@ -34,7 +34,7 @@ hard-fail.
 
 | Surface | Does |
 |---|---|
-| `delegate` tool | spawn one or more sub-agents; interactive sessions always run it in the background (results return as completion follow-ups); headless `pi -p` always blocks and returns results inline. There is no `sync`/`async` parameter. A leg whose tool is silent longer than the idle window (180 s) fails with a message telling you to raise that leg's `timeoutMs`. A `tasks` fan-out's receipt pairs each run id with its call-sign, and one wake covers the whole batch |
+| `delegate` tool | spawn one or more sub-agents; interactive sessions always run it in the background (results return as completion follow-ups); headless `pi -p` always blocks and returns results inline. There is no `sync`/`async` parameter. A leg whose tool is silent longer than the idle window (180 s) fails with a message telling you to raise that leg's `timeoutMs`. A `tasks` fan-out's receipt pairs each run id with its call-sign, and one wake covers the whole batch. An optional `thinking` picks that leg's effort level (off…max); omission keeps the agent's own setting and the configured/inherited child default, and results distinguish requested from observed effort |
 | `council` tool | select any installed strategy over a named roster or temporary inline `members`; voting strategies preserve tally and dissent. Interactive sessions run a council in the background, like `delegate`: a receipt with a run id now, ONE completion follow-up with the ruling (`intercom result { to: runId }` for the full payload); headless `pi -p` returns it inline. Use it when the method adds value (vote, arbiter's pick, critique loop, per-item sweep, rival builds), not for plain independent parallel work, which is `delegate`. The strategy list in the tool description is generated from the registry (`when`, positional `roster`, `*` for a required param); a call missing a required param (`judge` and `compete` need `params.judge`) fails at once with `council failed: "<strategy>" requires params.<key> — …` and launches nothing, while an unknown strategy or roster is reported by the run itself, in the completion follow-up. A persona's declared `council:` still resolves when strategy, roster and params are omitted. Per-strategy behaviour (section labels, MAGI reflection fallbacks) is in [`STRATEGIES.md`](./STRATEGIES.md) |
 | `intercom` tool | observe and control internal runs with `peek`, `result`, `steer`, and `stop`; `list`, `inbox`, `message`, `reply`, and `send` drive the coaching bus. There is no `wait`: a finished child wakes the supervisor through the completion follow-up |
 | `timer` tool | read the fresh clock with `now`, or schedule an idle wake with `arm`, `cancel`, and `list`; alarms are one-shot and in-memory per session; an armed alarm shows as a row in the agent widget and F9 until it fires or is cancelled |
@@ -77,14 +77,15 @@ its lighter variants when present. The current provider is a default, not a user
 explicit worker-model request may select another configured provider. The LLM retains the choice.
 
 The delegate tool's optional `name` is carried into `AgentRunSpec.name` and reaches both engine
-backends, keeping a caller-provided run label available in the live tree and runtime result. Every
-settled async run also emits immediate UI feedback with that name and its terminal outcome. TUI
-failures persist an expandable card with the agent, model, elapsed time and a concise cause; expansion
-retains the full technical diagnostic. Other modes use a concise notification. These operator-only
-cards do not inject context or start a second turn. The model-facing report remains independently
-idle-gated; a UI notification failure cannot discard it.
+backends, keeping a caller-provided run label available in the live tree and runtime result. A
+successful or stopped run announces ONCE: the idle-gated completion follow-up is the single
+settlement surface (the agent-tree row already settles immediately). A failure keeps an immediate
+operator surface — in the TUI a durable expandable card with the agent, model, elapsed time and a
+concise cause (expansion retains the full technical diagnostic); other modes use a concise
+sanitized notification. These operator-only cards do not inject context or start a second turn.
+The model-facing report remains independently idle-gated; a UI notification failure cannot discard it.
 
-### Pi 1.0 codemode
+### Native codemode
 
 Pi's native `codemode` can call callable pi-persona tools through the normal nested-tool pipeline.
 Argument validation and persona permission gates still apply to every inner call; scripts do not
@@ -124,13 +125,18 @@ a live pending ask on the exact child handle, never inferred from its last activ
 | Surface | Needs | What you get |
 |---|---|---|
 | **Observe and control** | any persona | `peek` inspects async sub-agents; `steer` sends a soft correction; `stop` requests cancellation, and `stop { to: "all" }` cancels every running run, `council` and `flow` included (runs already stopping are skipped, never force-cleared in bulk; a slash or mandated run is stopped at shutdown, not by this). The `f9` overlay provides the same controls (`s`, `x`, `X`). Cancelling a worker does not undo existing changes; an unknown id on `result`, `steer` or `stop` returns a miss text listing the known runs |
-| **Retrieve** | any persona | `result { to }` returns one retained run payload; `message { messageId }` returns one retained bus message. History is bounded to 256 messages and 256,000 body characters, and retrieval never starts a worker |
-| **Message bus** | `coaching: true` | children get `contact_supervisor`; progress appears in results and `intercom inbox`, while a blocking `decision` wakes the supervisor for `intercom reply` |
+| **Retrieve** | any persona | `result { to }` returns one retained run payload (`offset`/`limit` page a bounded view without collecting it; `collect: true` acknowledges whole-body collection of a live run); `result { ref, offset, limit }` reads a page of a retained terminal result after reload; `results` lists retained terminal results with immutable refs; `message { messageId }` returns one retained bus message. History is bounded to 256 messages and 256,000 body characters, terminal results to 128 entries / 8 MiB per session, and retrieval never starts a worker |
+| **Message bus** | bus allowed; in-process children also require `coaching: true` | broker-connected children and coached in-process children get `contact_supervisor`, subject to explicit empty tool grants and exclusions; progress appears in results and `intercom inbox`, while a blocking `decision` wakes the supervisor for `intercom reply` |
 | **Sibling peer comm** | strategy opt-in | `debate` and `pair` members always get one-way `contact_peer`; `map` and `synthesize` add it with `params: { peers: true }` |
 
-With coaching enabled, an async child's `decision` or `interview` waits for a supervisor reply.
-A headless (inline) child posts the question one-way and continues instead: the supervisor is
-parked in that call and cannot answer a blocking ask. Progress messages are always one-way.
+When supervisor contact is available, an async child's `decision` or `interview` waits for a supervisor reply.
+A headless (inline) child posts the question one-way without waiting: the supervisor is parked
+in that call and cannot answer. The decision/interview remains unresolved; the child may continue
+only independent work already authorized, otherwise it returns a blocked/partial result. A timeout,
+disconnection or failure is never permission to invent an answer. Results expose `outcome` as
+`reported`, `answered`, `unavailable`, `timed-out`, `cancelled` or `failed`; `delivered` means only
+confirmed delivery, not a reply or approval (false can mean unconfirmed). An already-cancelled call
+sends nothing. Progress messages remain one-way.
 
 Delegated output is untrusted and is fenced before it reaches the supervisor. Interactive
 delegation always runs in the background: continue independent work, and when only children remain, end the turn for
@@ -200,6 +206,43 @@ and your own open asks. A claim's `write_set` is advisory, not enforced: a super
 coordinate (`exocom_ask`) or claim the path itself; calling the same tool again on the same path is
 then allowed through (one warning per claim + normalized path, not a standing lock).
 
+### Exocom collaboration tools
+
+The external plane exposes fifteen 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`. Persona denials still apply during an active session; a
+foreign-workspace member does not receive usable `exocom_claim` access.
+
+| Tool | Contract |
+|---|---|
+| `exocom_list`, `exocom_send`, `exocom_name` | Discover session-qualified targets, send a one-way postcard, or set this session's display handle. A rename does not change the routing identity. |
+| `exocom_claim`, `exocom_release`, `exocom_progress`, `exocom_status` | Declare advisory repository-relative ownership, release it, add progress, or inspect current ledger state. Claims do not enforce OS-level write access. |
+| `exocom_ask`, `exocom_answer`, `exocom_decline`, `exocom_wait` | Send a targeted question that creates an obligation, settle an incoming ask, or arm a non-blocking wake for an answer. |
+| `exocom_task` | Create a voluntary task (creation does not launch a worker), take it, report progress, finish it as `done` or `abandoned`, or inspect retained tasks. Use `list` then `get` for full details. |
+| `exocom_offer` | Send an optional invitation for an open task to a peer or the pool. It expires after one hour by default and at most 24 hours; it never creates an ask or an obligation to answer. |
+| `exocom_publish` | Share an explicit bounded evidence excerpt for a task, discover titles/message ids by `work_key`, and retrieve one excerpt by `msg_id`. This does not expose an `intercom` terminal-result archive. |
+| `exocom_profile` | Read, set or clear this session's self-reported capability labels and availability. Up to eight labels of 48 characters each; availability is `available`, `busy`, `away` or unknown. It never grants permission or verifies skill. |
+
+`exocom_task list` is discovery: omit `work_key` and `task_id`, then use the returned identifiers for
+`get` or a task action. Summary pages default to 10 rows; `detail: true` defaults to 5, and an
+explicit detailed limit above 5 is rejected. `exocom_task create` returns `task_id`, which equals
+the creation message id. Carry it with `work_key` for take/progress/finish, offers and evidence
+publication; the key alone is only a lookup name and can be reused after retention. Write-set pickup
+and claim are committed atomically under the ledger lock. Read-only tasks can be taken from another
+workspace scope. A task whose owner leaves becomes stale and cannot be taken over automatically.
+Detailed paths are available through `exocom_task({ action: "get", work_key, task_id })`;
+paginated list summaries may clip the write set.
+
+While an incoming ask is pending, allowed actions are answer/decline, `exocom_name`, status, explicit
+collaboration reads (`exocom_task` list/get, `exocom_publish` read, `exocom_profile` get), and
+read-only filesystem tools. Profile edits and other mutations wait until the ask is settled. Identity
+metadata does not settle it. Task, offer and evidence records are each capped at 64 and share a
+128 KiB state budget; terminal or stale tasks and expired offers are retained for up to an hour,
+while evidence is retained for up to an hour after publication. Active tasks remain while their owner
+lease is live. See the [cross-session collaboration guide](./COLLABORATION.md) for workflows and
+bounded examples.
+
 ## Configuration and data
 
 Personas and agents are Markdown files with YAML frontmatter. Teams, flows, contracts, and presets
@@ -592,6 +635,14 @@ queued or later stages may still start.
 `/persona-settings [show]` · `/models [query]` · `/orchestrate <task>` · `/flow <name> <task>` ·
 `/peek [id]` · `/exocom` · `/doctor`.
 
+`/persona off` is the deactivation command. `/persona restore` force-restores every bundled resource
+into the user persona directory: personas and agents, flows, contracts, presets, `teams.yaml`, and
+the shared prompt pair. Existing bundled destinations are overwritten; additional user files are
+not pruned. For example, custom `agents/pippo.md` (a persona) and `agents/pluto.md` (an agent) survive
+unchanged. Reusing a bundled destination filename means opting into its replacement. This is not a
+reset of `settings.json`, credentials, sessions or project-local overrides. Definitions are reloaded
+afterward, including any preserved custom persona that was active.
+
 `/doctor` reports the cross-process broker's lifecycle on one line: `broker: on — endpoint …` once
 the host is listening, `broker: on — (starting…)` mid-attempt, or
 `broker: on — (not started — no child-engine build yet)` before any child-engine build has run. A
@@ -602,7 +653,7 @@ build retries. A connected broker child's status shows `⇄ <handle>`; if that c
 status flips to `⇄ offline` and a fresh ask on it fails fast instead of hanging.
 
 `/doctor` also reports the installed host's version against this extension's floor: `pi: <version>
-(requires ≥ 1.0.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
+(requires ≥ 1.4.0)`, with a trailing `— BELOW FLOOR` marker once an installed version fails the
 check (`src/core/pi-compat.ts`). `pi: unknown` means the host's own `package.json` could not be
 resolved (a non-standard install layout) — not a failed check.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aeondave/pi-persona",
-  "version": "1.17.3",
+  "version": "1.17.4",
   "private": false,
   "type": "module",
   "description": "Supervised multi-agent orchestration for Pi — async workers, live steering, cross-session collaboration, and switchable personas.",
@@ -42,6 +42,7 @@
     "docs/README.md",
     "docs/ARCHITECTURE.md",
     "docs/EXPERIENCE.md",
+    "docs/COLLABORATION.md",
     "docs/MONITORS.md",
     "docs/REFERENCE.md",
     "docs/SPINE.md",
@@ -94,18 +95,23 @@
     "node": ">=22.19.0"
   },
   "devDependencies": {
-    "@earendil-works/pi-agent-core": "1.3.0",
-    "@earendil-works/pi-ai": "1.3.0",
-    "@earendil-works/pi-coding-agent": "1.3.0",
-    "@earendil-works/pi-tui": "1.3.0",
+    "@earendil-works/pi-agent-core": "1.4.0",
+    "@earendil-works/pi-ai": "1.4.0",
+    "@earendil-works/pi-coding-agent": "1.4.0",
+    "@earendil-works/pi-tui": "1.4.0",
     "@types/node": "^22.20.4",
     "fast-check": "^4.10.2",
     "tsx": "^4.23.13",
     "typebox": "1.4.2",
     "typescript": "^7.0.2"
   },
+  "overrides": {
+    "@earendil-works/pi-coding-agent@1.4.0": {
+      "undici": "8.12.3"
+    }
+  },
   "pi": {
-    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.3/assets/banner.png",
+    "image": "https://raw.githubusercontent.com/AeonDave/pi-persona/v1.17.4/assets/banner.png",
     "video": "https://cdn.jsdelivr.net/gh/AeonDave/pi-persona@6655d281ce7965a75303dd704bd29db73db04070/assets/demo1.mp4",
     "extensions": [
       "./src/extension.ts"

package/src/agents/agent.ts

@@ -10,6 +10,8 @@
 
 import { sanitizeStatusLabel } from "../core/display-label.ts";
 import { asBoolean, asPermission, parseYamlSubset, splitFrontmatter } from "../core/frontmatter.ts";
+import { parseLegThinking } from "../core/leg-thinking.ts";
+import type { ThinkingLevel } from "../core/types.ts";
 import { writeSetPathError } from "../core/ownership.ts";
 
 export interface AgentConfig {
@@ -21,6 +23,8 @@ export interface AgentConfig {
 	 *  prompt text: the body already carries the behaviour, this only labels it. */
 	purpose?: string;
 	model?: string;
+	/** Default requested effort for this agent; an explicit leg override wins. Pi clamps it. */
+	thinking?: ThinkingLevel;
 	/** Tool allowlist passed to Pi. Absent means the session default tool set. */
 	tools?: string[];
 	/** Tool denylist applied after the allowlist/session default. */
@@ -73,6 +77,8 @@ export function parseAgent(content: string, source: string): AgentConfig | null
 		if (purpose && purpose !== "agent") agent.purpose = purpose;
 	}
 	if (typeof fm.model === "string" && fm.model.trim()) agent.model = fm.model.trim();
+	const thinking = parseLegThinking(fm.thinking);
+	if (thinking !== undefined) agent.thinking = thinking;
 	const tools = asPermission(fm.tools);
 	if (tools?.allow) agent.tools = tools.allow;
 	if (tools?.deny) agent.excludeTools = tools.deny;

package/src/bridge.ts

@@ -23,6 +23,9 @@ import { makeContactSupervisorTool } from "./bus/contact.ts";
 import { InProcessBus, type MsgKind } from "./bus/inproc.ts";
 import { makeContactPeerTool, type PeerInfo } from "./bus/peers.ts";
 import { attributeInbound } from "./core/fence.ts";
+import { isReaderToken } from "./bus/broker/messages.ts";
+import { readFailure } from "./bus/result-reader.ts";
+import { makeReadResultTool } from "./tools/read-result.ts";
 
 type Env = Record<string, string | undefined>;
 
@@ -90,15 +93,22 @@ function sendFollowUp(pi: ExtensionAPI, content: string): void {
  *  `isBridgeMode()` is true. Connects the broker client (capped retries; a failed connect
  *  degrades to a mute executor, never a crash — spec §4), registers the two wire-bound
  *  comm-plane tools, surfaces inbound `deliver`/`steer` frames as follow-ups, and closes the
- *  client on `session_shutdown`. */
+ *  client on `session_shutdown`. An explicit private reader token also installs read_result;
+ *  its handshake/read failures are runtime errors, never ordinary mute degradation. */
 export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: InstallBridgeDeps = {}): void {
 	const env = deps.env ?? process.env;
 	const endpoint = env.PI_PERSONA_BUS;
 	const handle = env.PI_PERSONA_HANDLE;
+	const readerToken = env.PI_PERSONA_RESULT_READER_TOKEN;
+	if (readerToken !== undefined && (!endpoint || !handle || !isReaderToken(readerToken))) {
+		throw new Error("Invalid result reader environment.");
+	}
 	if (!endpoint || !handle) return; // isBridgeMode() gates the real caller; malformed env degrades to a no-op
 
-	const wantsPeers = env.PI_PERSONA_PEERS === "1";
-	const clientDeps: MakeBrokerClientDeps = { endpoint, handle, ...(wantsPeers ? { peers: true } : {}) };
+	const canUseBus = env.PI_PERSONA_BUS_TOOLS !== "off";
+	const wantsPeers = canUseBus && env.PI_PERSONA_PEERS === "1";
+	const clientDeps: MakeBrokerClientDeps = { endpoint, handle, ...(wantsPeers ? { peers: true } : {}),
+		...(readerToken !== undefined ? { readerToken } : {}) };
 	const client = (deps.makeClient ?? makeBrokerClient)(clientDeps);
 
 	// Blocking asks are honoured only when the spawning run is async (`PI_PERSONA_ALLOW_BLOCKING`,
@@ -108,7 +118,11 @@ export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: Ins
 	// (the same safety default the in-process engine applies; see contact.ts / spec §4.9).
 	const allowBlocking = env.PI_PERSONA_ALLOW_BLOCKING === "1";
 	const bus = new BrokerBus(client);
-	pi.registerTool(makeContactSupervisorTool(bus, handle, SUPERVISOR_HANDLE, { allowBlocking }));
+	if (canUseBus) pi.registerTool(makeContactSupervisorTool(bus, handle, SUPERVISOR_HANDLE, { allowBlocking }));
+	if (readerToken !== undefined) {
+		pi.registerTool(makeReadResultTool({ read: (request, signal) => bus.connected
+			? client.read(request, signal) : Promise.resolve(readFailure("unavailable")) }));
+	}
 
 	// The engine-scoped peer roster (B7): fetched from the host's `list` frame and cached —
 	// `contact_peer` accepts an awaitable provider, so the first call can wait for the initial
@@ -147,7 +161,7 @@ export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: Ins
 		peerRefresh = shared;
 		return shared;
 	};
-	pi.registerTool(
+	if (wantsPeers) pi.registerTool(
 		makeContactPeerTool(bus, handle, {
 			listPeers: () => refreshPeers(),
 		}),
@@ -193,9 +207,11 @@ export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: Ins
 			}
 		},
 		() => {
-			// Capped retries exhausted (host gone, or a race on a just-spawned child) — degrade to
-			// a mute executor and keep running; never crash, never hang (spec §4).
-			if (env.PI_PERSONA_DEBUG) process.stderr.write(`[pi-persona] bridge: could not connect to ${endpoint}\n`);
+			// Ordinary comms degrade to a mute executor. An installed read_result remains
+			// fail-closed: a failed handshake cannot expose a fallback body.
+			if (env.PI_PERSONA_DEBUG) process.stderr.write(readerToken !== undefined
+				? "[pi-persona] bridge: result reader unavailable\n"
+				: `[pi-persona] bridge: could not connect to ${endpoint}\n`);
 			try {
 				ctx.ui.setStatus("persona-bridge", "⇄ offline");
 			} catch {
@@ -205,6 +221,7 @@ export function installBridge(pi: ExtensionAPI, ctx: ExtensionContext, deps: Ins
 	);
 
 	pi.on("session_shutdown", () => {
+		bus.connected = false;
 		client.close();
 	});
 }