@aeondave/pi-persona 1.17.1 → 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

@@ -43,33 +43,47 @@ supervisor is free. Keep the session open, and cancel a watch when its purpose e
 - **F9** opens the agent tree. Queued rows have not started their clocks. Live supervisor asks show
   `waiting for supervisor`, not a stall; running rows otherwise show elapsed time and switch to
   `⚠ stalled <duration>` after 90 seconds without progress — a suspicion, not proof of a deadlock.
-  Council parent clocks refresh on child engine events; that indicates liveness, not useful work.
+  Council parent clocks refresh on child engine events; that indicates liveness, not useful work. For the
+  stall card and `/peek`, "stalled" is stricter: 90 seconds with no assistant output, tokens, turns or
+  completed tool call, so a tool that only streams output (`npm run dev`, `tail -f`) is flagged too. It is
+  advice only: nothing is killed.
   A parent is waiting only when all its live descendant branches are waiting. Enter opens a selectable worker's output; `s` sends a course correction;
   `x` requests cancellation and appears only when the run can actually be stopped, marking the row
   `stopping…` at once; a stop that can't be applied says so instead of doing nothing. Escape goes
   back or closes the panel.
 - **`/peek`** gives a compact progress view. A quiet worker is a reason to inspect its last
   progress and current activity, not to launch a duplicate immediately.
+- **`/flow <name> <task>`** runs a flow (`/flow` alone lists them with descriptions; a `gate: true`
+  phase pauses for your approval, showing its output and what runs next). `/orchestrate <task>` runs
+  the active persona's `orchestration:` block (bundled personas declare `council:` instead, used via the
+  `council` tool); both run inline and their result also reaches the
+  supervisor's next turn. In the F9 list, `X` stops every running leaf agent after a
+  second press that states how many.
 - **Background results arrive automatically.** A supervisor can continue independent work while
   they run. When only background workers remain, end the turn and let completion follow-ups return
-  their results; do not monitor or poll healthy workers or automatically join the whole batch.
-  `intercom wait` snapshots immediately by default in interactive/RPC sessions; use `sync: true` for
-  an intentional bounded join when the next step depends on those results. Headless waits remain
-  blocking by default; pass `sync: false` for a snapshot.
-- **Answer a waiting worker before joining it.** A coaching worker may need a decision from its
+  their results; never sleep, poll, or arm a timer to wait for healthy workers (or monitors) - a
+  finished worker wakes the supervisor by itself. `intercom result { to: runId }` retrieves a settled
+  run. Interactive `delegate`, `council` and `flow` always run in the background (a receipt now, one
+  follow-up with the outcome; a flow checkpoint waits for you, not the supervisor; Esc does not abort
+  them: stop legs from F9 with `x`/`X`, or have the supervisor `intercom stop` the run); headless `pi -p` always blocks for the
+  turn and returns results inline, since nothing drains a follow-up after the process exits.
+- **Answer a waiting worker promptly.** A coaching worker may need a decision from its
   supervisor before it can finish. An unanswered question is actionable work.
 - **Steering is a request.** Check the subsequent output to see whether the worker incorporated
   it. In-process workers can receive guidance mid-run; child-engine workers (including MCP/worktree
   runs) receive it as a queued follow-up. Neither promises to interrupt arbitrary tool work, and
-  steering does not preempt an explicitly blocking `intercom wait`. End the supervisor turn rather
-  than join merely to idle. Check the terminal result after requesting cancellation; changes already
-  made are not undone.
+  steering is not a substitute for ending the turn. After requesting cancellation, the stopped report
+  arrives as a completion follow-up; changes already made are not undone.
 
 Launch cards and targeted Intercom calls show the same worker alias as the live tree. A steering
 receipt previews the message that was actually queued; expand it (`Ctrl+O` by default, or your
 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:
@@ -82,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/MONITORS.md

@@ -6,7 +6,8 @@ preserving the cached system prefix. During a long run it can call `timer` with
 to refresh the clock. This is sampled wall-clock time, not a continuously updated model sense.
 
 Use `timer arm` for a known time. Use `monitor arm` when a program can report the event you care
-about. Sub-agent completions and Exocom messages already wake the supervisor automatically.
+about, never one whose only job is to elapse time. Sub-agent completions and Exocom messages already
+wake the supervisor automatically, so neither tool should wait on them.
 
 ## Background programs
 
@@ -36,13 +37,70 @@ Adapters can use native file/system subscriptions, a program's streaming API, or
 polling inside the program when no subscription exists. The model does not run a polling loop.
 Print one short event per line to stdout; send diagnostic chatter to stderr. Flush output promptly
 (for Python, use `-u` or `flush=True`). Repeated identical lines are ignored for that watch.
-Keep complete logs in the program's normal log file if they are needed later.
+Monitor stdout and stderr are captured automatically within fixed limits. For a complete, unlimited
+transcript, keep using the program's own log file; monitor capture is bounded diagnostic evidence.
 
 The model can continue independent work while a monitor runs. Events wait while it is busy and
 arrive together at an idle boundary. When only the event remains, it should end its turn. Natural
 requests such as “let me know when this build finishes” are enough; tool parameters are for the
 model or an integration, not something the user needs to manage.
 
+## Visibility
+
+An armed timer or active monitor shows as a row in the agent widget and the F9 / `/agents` overlay,
+beside the sub-agents: `◉ <label>  <id> · <mode> · <elapsed> · deadline in <remaining>` for a monitor
+(`<id> · output · k/N events` as events arrive), `⏰ <label>  <id> · fires in <remaining>` for a timer
+(just `⏰ <id>  fires in <remaining>` when the timer has no label).
+The countdown replaces the stall clock, so a quiet watch is never `⚠ stalled`. While a process runs,
+its latest useful stdout/stderr progress is displayed on its row, including partial lines and carriage-return
+progress updates. Tails ingest every chunk immediately; their display is updated at the existing UI
+frame cadence instead of rebuilding the full row for every chunk. Terminal events and cancellation
+include the final tail immediately. This is a bounded, sanitized UI projection: it does not create a
+model wake or consume an output-event allowance. `⏎` opens the command, cwd, times, bounded live output tails and last 40 event
+lines (monitor), or the fire time and message (timer); `x` cancels that
+one watch like `monitor cancel` / `timer cancel`. These are rows, not agents: no steer, `X` stop-all
+skips them (`intercom stop { to: "all" }` likewise leaves them alone; cancel with `monitor cancel` /
+`timer cancel` or `x`), and they never count in `N agents` or reach telemetry. A finished row settles
+and leaves like an async run: its final ✓/✗/■ goes to the tree change stream (telemetry excluded), not
+to the screen.
+
+## Session-owned logs and results
+
+`monitor { action: "result" }` lists retained captures, including completed jobs; add `id` to read one.
+The default read shows a short tail; `full: true` reads the complete **retained** capture, not bytes
+already discarded by the capture limit. This is retrieval, not a wait: do not poll it for completion.
+`list` still lists only active watches. IDs are activation-unique so reload cannot confuse an old log
+with a newly launched process.
+
+The archive belongs to the **whole session tree**, not only the active conversation branch.
+`result` can therefore list or retrieve a log from a sibling branch that is absent from the current
+transcript. Branch navigation changes the transcript, not archive visibility or ownership. Both
+retention budgets below are shared across all branches and remain shared after reload.
+
+A terminal event or cancellation saves one bounded stdout/stderr snapshot and outcome as a custom
+entry in the owning Pi session. An expandable operator-only log card exposes it without adding the
+raw log to model context or triggering another turn. No per-chunk session entries or sidecar files
+are written. Shutdown/reload stops processes and saves their available diagnostics; resume can read
+the snapshots but never restarts the processes. A hard crash can lose a running job's not-yet-saved
+capture. In a non-persistent session, logs remain in memory only.
+
+Deleting the owning session file removes its stored logs with it. Reload, ordinary shutdown and
+context compaction are not deletion. Forking/copying a session can copy its historical log entries;
+each copy then owns its own data, with no shared external file to orphan or delete accidentally.
+Backups and exports may also retain copies; deleting the original session is not secure erasure
+of those copies. Treat captured stdout/stderr as session data: printed credentials, signed URLs
+and other secrets can be stored in the JSONL. Sanitize/redact sensitive output in the producing
+program before capture. Display sanitization is not secret redaction; requesting `result` returns
+the selected retained text to the model, even when it originated on a sibling branch.
+
+Each capture retains the last 16,384 UTF-16 code units of stdout and stderr independently, plus at
+most 16,384 code units of status text. Live F9 tails retain 4,000 code units per stream. The journal
+admits at most 64 terminal records and a conservative 2 MiB cumulative serialized-data budget per
+session (JSON escaping, metadata and envelope allowance included). Historical entries, even unknown
+formats, consume that budget; reload does not reset it. Once exhausted, new captures remain only in
+the bounded runtime history, and `result` explicitly reports the storage limitation. Truncation and
+persistence failures never claim a complete or durable log.
+
 ## Lifetime and limits
 
 - `list` shows active watches; `cancel` with the returned `id` stops the owned process tree and
@@ -56,7 +114,8 @@ model or an integration, not something the user needs to manage.
   to four per batch, and reports omitted older events if a busy model cannot keep up.
 - Keep Pi open. Watches are in memory and stop on shutdown, reload, or session replacement;
   they are not restored on resume. A headless `pi -p` invocation that exits after its answer is
-  not a persistent monitoring service.
+  not a persistent monitoring service: an alarm or event wakes it only if it lands before the single
+  turn settles, and the arm result says so instead of inviting the model to end its turn.
 
 ## Permissions and architecture
 

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: