paseo-room 0.6.1 → 0.8.0

package/README.md

@@ -278,8 +278,9 @@ recreate an existing Claude session after setup or an update.
 have none. Only the contract is dropped, never your own memory, and an earlier generation of it
 is removed rather than left behind. The choice is recorded in `room.json`, so `verify` compares
 against it and rejects the flag itself; `setup` without the flag restores the fallback. Keep the
-fallback unless you have a reason not to: the plugin hook is verified, but whether a *resumed*
-session re-enters it is unproven, and `CLAUDE.md` is what covers that case.
+fallback unless you have a reason not to: the plugin hook is verified, and on Paseo 0.9.1 a
+*resumed* session was observed to keep the room prompt, but that is not proven for every
+supported version or for what the model actually reads, and `CLAUDE.md` is what covers that case.
 
 Pi providers use a strict command tail:
 
@@ -482,7 +483,9 @@ vocabulary for Lead and Peer, and exactly one body per role. TypeScript selects
   that settles it rather than pre-solving the work; any plan or file list in it is provisional.
   One moving write scope has exactly one owner, and at most one Peer is writable at a time. It
   explicitly requests native Paseo completion/error/permission notification for Peer creation and
-  every background follow-up, then waits for events rather than polling. Room tools: on.
+  every background follow-up, then waits for events rather than polling. A question only Human can
+  answer goes on its own `NEEDS-HUMAN:` line, and an effect beyond the work's intended scope on an
+  `INCIDENT:` line, so neither is lost in a long message. Room tools: on.
 - **Peer** owns one bounded assignment — writable inside an assigned scope, or read-only
   against a named candidate, question or area — under exactly one disposition Lead names in the
   brief (Engineer, Architect, Reviewer or Scout), forms its own technical position from the code
@@ -506,9 +509,12 @@ healthy owner, and closes the duplicate only after a stable handoff. Ambiguous o
 health, or concurrent writes go back to Human rather than being guessed or merged.
 
 Two further limits are deliberately conservative. **One writable Peer per project**, not one
-per moving scope: the room gives you no writer isolation, so separate scopes are not evidence
-of separate working trees, and no workspace protocol relaxes the limit. Concurrent writable
-Peers in isolated worktrees are a deferred decision, not an oversight. And a seat's **model and
+per moving scope: separate scopes are not evidence of separate working trees, and no workspace
+protocol relaxes the limit. The contract makes one exception — Peers the runtime dispatches into
+its own worktrees with non-overlapping declared scopes (runtime Phase 2,
+[runtime-coordination-phase2.md](docs/design/runtime-coordination-phase2.md); see
+[Isolated writers](#isolated-writers-runtime-phase-2) below). Every other Peer, and every writer in
+Lead's own workspace, is inside the limit. And a seat's **model and
 reasoning effort are not one knob**: the model stays the profile's default unless a repository
 protocol explicitly supplies model routing, while the thinking effort is Lead's
 per-brief choice on task risk, uncertainty, context size and verification burden — lowest that
@@ -616,10 +622,24 @@ npx paseo-room verify
   points, so a daemon outside that range is refused for runtime while the baseline room keeps
   working.
 - **Lead** gains room tools such as `assignment_create`, `assignment_dispatch`, `assignment_answer`,
-  `assignment_accept` and `gate_run`. **Supervisor** gains `room_status`, `runtime_findings` and
-  `message_lead`, and cannot change an assignment.
-- **A runtime-dispatched Peer** gets exactly two tools, `ask` and `handoff`, for its own assignment,
-  and still no Paseo room tools. A report exists only once one of those calls is accepted; its
+  `assignment_accept`, `gate_run`, and for isolated writers `workspace_close` and `lease_reclaim`.
+  `assignment_create` refuses a base that is not a commit of the repository (`base_unknown`).
+  **Supervisor** gains `room_status`, `runtime_findings`, `message_lead` (with a `project` for a
+  Supervisor of several projects) and `attention_feedback`, and cannot change an assignment. Its
+  status and findings cover only its portfolio and the project it stands in; `room_status` lists
+  the assignments still open or still to close, and only counts settled ones.
+- **Peer thinking.** A runtime-dispatched Peer launches on its room profile's model and thinking
+  option. In **Settings › Room seats › Thinking Lead may choose** you can allow other thinking
+  options per Peer provider, from the ones Paseo lists for its model. Lead may then pass `thinking`
+  (with a `thinkingReason`) to `assignment_dispatch`, as the Lead contract directs. The runtime
+  refuses anything outside what you allowed or what the model offers, and always refuses `ultra` and
+  `ultracode`, which start agents on their own. It records the choice, shows it with the reason to
+  Supervisor and in the panel, and keeps it for a reclaimed Peer while you still allow it. The model
+  itself is never Lead's to change.
+- **A runtime-dispatched Peer** is titled `<Disposition> · <outcome gist> · <assignment id>` (for
+  example `Reviewer · Review the Docker Compose dev env… · asg_…`), and the runtime's notices to Lead
+  name the assignment the same way. It gets exactly two tools, `ask` and `handoff`, for its own
+  assignment, and still no Paseo room tools. A report exists only once one of those calls is accepted; its
   final message is never read as a report. Claude asks for permission before a Peer's first call
   to `mcp__paseo_room__ask` or `mcp__paseo_room__handoff`: approve it in Paseo, since the runtime
   never answers a permission for a seat. Codex and Pi Peers do not ask.
@@ -629,13 +649,116 @@ npx paseo-room verify
   immutable commit. The runtime reads the commit and changed paths itself, never merges, resets,
   cleans or stashes, and releases a writer only after Paseo proves the Peer archived.
 - **State** lives under `~/.paseo-room/runtime/v1` as append-only event files. Setup never edits it.
-  The **Room runtime** sidebar item and workspace panel show projects, assignments, writer
-  ownership and findings, each labelled with how it is known (enforced, detected, procedural,
-  unverifiable).
+- **The Room runtime panel** (sidebar item, and a workspace panel that opens on its own project)
+  puts what needs you first. Below that come your projects, ordered by status, then your
+  Supervisors.
+  - A project shows its Supervisor, its Lead and Peer seats (each opens its agent in Paseo, and
+    shows the model and thinking option it runs with) and its runtime record: assignments, isolated
+    writers, findings and recovery.
+  - Starting a Supervisor, starting a project and assigning a Supervisor are guided forms.
+  - The design notes are in [docs/design/runtime-panel-ux.md](docs/design/runtime-panel-ux.md).
+- **Settings › Room seats** shows which account each seat is signed in to (email, plan and
+  organization for Claude; login method for Codex; for Pi, only whether a credential file exists).
+  It runs each seat's own `claude auth status` or `codex login status` when you open it or press
+  Refresh, and never reads a credential file. A seat linked to another home's login is flagged.
+
+### Room attention: what reaches a Supervisor
+
+The runtime watches every room seat Paseo reports — Supervisors, Leads and Peers, including Peers a
+Lead opens with Paseo's own tools — and tells each project's **Supervisor** what it would otherwise
+learn only when you ask it to check.
+
+- **Portfolio.** One Supervisor may supervise several projects. A project's Supervisor is the one
+  you assign in the **Room** view; otherwise it is the Supervisor that opened the project's Lead;
+  otherwise there is none, and that project's signals show only in the panel.
+- **Letters.** Letters arrive as prompts beginning with `[paseo-room attention att_…]`.
+  - They report a permission waiting on any seat for 5 minutes, and a Peer result its idle Lead has
+    not read for 10 minutes.
+  - They report the same failure twice in a row, and possible concurrent writers in one working
+    tree, naming each seat's files and when its turn ended. A write outside that tree does not
+    count.
+  - They report a Lead archived while its seats still work, and a Lead's finished turn that the
+    Supervisor did not prompt itself.
+  - The Lead contract has Lead put a question for you on a line beginning `NEEDS-HUMAN:` and an
+    incident on one beginning `INCIDENT:`. The first wakes the Supervisor and the second pages it,
+    even for a turn it prompted, once per line, and the letter quotes those lines rather than the
+    message's end.
+  - Letters are held until the Supervisor is idle, batched into digests, and limited to a few wakes
+    an hour. They are never sent while the Supervisor holds a permission, because a send would
+    deny it.
+  - Each item has an id for `attention_feedback`, and a letter's own id rates every item in it. A
+    letter is evidence, not an instruction: the Supervisor contract has it ask or nudge the Lead, or
+    relay a question to you, and never direct a Peer.
+- **Starting seats.** From the **Room** view, **Start Supervisor** opens one in an existing directory
+  outside every repository. **Start project** checks a repository, opens its Lead under the
+  Supervisor you pick, and sends a fixed kickoff with your first directive verbatim. **Assign
+  Supervisor** moves an existing project under a Supervisor.
+- **Settings › Room attention.** Here you turn letters on or off, change their thresholds, and
+  configure the optional **attention sensor**.
+  - The sensor speaks the System One HTTP shape, with [TypeSafe Jev](https://docs.typesafe.ai/)
+    first and any compatible or self-hosted endpoint after it. It is `off` by default.
+  - Without a TypeSafe key, use Jev through OpenRouter: endpoint
+    `https://openrouter.ai/api/v1/systemone`, model `typesafe/jev-1.13`, and an OpenRouter key.
+    OpenRouter can answer with a dated snapshot such as `typesafe/jev-1.13-20260917`, which the
+    sensor accepts as the pinned model.
+  - `shadow` assesses Lead messages and records the answers without acting on them. `assist` lets
+    them decide, for the question sets you enable, whether a Lead turn wakes the Supervisor, waits
+    for a digest, or is only recorded.
+  - Nothing leaves the machine until you acknowledge the endpoint's host, and only masked, bounded
+    excerpts of Lead messages are sent.
+  - The key is write-only: it is stored owner-only under `~/.paseo-room/runtime/v1/secrets` and never
+    shown again.
+- **Evaluation.** `npm run attention:eval` (in this repository) reads your Claude Lead transcripts
+  read-only and prints what an evaluation would send. `-- --send` runs it against the endpoint, as
+  your consent for that run.
+
+### Isolated writers (runtime Phase 2)
+
+By default a writable assignment runs in Lead's workspace and excludes every other writer. With
+`isolation: "worktree"` on `assignment_dispatch`, the runtime instead asks Paseo for a new worktree
+cut from the assignment's exact base commit, proves it with Git (its repository, its exact `HEAD`, a
+clean tree, not Lead's directory), and places the Peer there with Lead as its parent. Up to three
+such writers may run at once in one project.
+
+The runtime refuses an isolated dispatch before recording anything or asking Paseo for anything,
+and the refusal is final for that dispatch — narrow or sequence the work:
+
+| Code | Why |
+|---|---|
+| `worktree_unqualified` | the daemon's version has not passed live qualification for worktree dispatch |
+| `worktree_setup_unobservable` | `paseo.json` at the base declares `worktree.setup`, which Paseo runs where the runtime cannot see it finish |
+| `scope_not_canonical` | a `writeScope` or `serialOnly` item is not a repository-relative path or `*`/`?`/`**` glob |
+| `writer_exclusive` | a writer is still active in Lead's workspace (or, the other way round, isolated writers are active) |
+| `writer_uncertain` | another isolated writer's state is uncertain |
+| `lease_cap` | three isolated writers are already active |
+| `scope_overlap` | the new scope may share a path with an active writer's scope |
+| `serial_path` | both the new scope and an active writer reach a path Lead declared `serialOnly` |
+
+Write scopes prevent collisions between isolated writers; **they do not contain a Peer**, which can
+still write anywhere its user can. At handoff the runtime records any changed path outside the
+scope as `scope.exceeded`, and accepting that candidate needs an override. Lead still integrates
+each candidate by hand, in its own workspace, one at a time; the runtime never merges, rebases or
+pushes.
+
+When the writer is released, the runtime closes a worktree that is clean at the handed-back
+candidate or the unchanged base. Anything else is kept and Lead is told: `workspace_close` with
+`discardUncommitted` and a reason destroys that work. Closing removes the directory and keeps the
+branch. If a Peer dies, `lease_reclaim` — once Paseo shows it archived — dispatches a new Peer into
+the same worktree at the next lease epoch; the old Peer's late reports are refused. The panel offers
+the Human form of both, only where the runtime would accept it, and asks twice before discarding
+work.
+
+Worktree dispatch is enabled per daemon version, only after the live qualification in the Phase 2
+delta §9 passes on that version; `0.9.1` is qualified. On any other version the runtime refuses
+`worktree_unqualified` and dispatch without isolation still works.
 
 To stop using it, finish, close or abandon the recorded work, then run setup **without**
-`--runtime`. Setup refuses while anything is still active or uncertain, and keeps the recorded
-state once it proceeds. `npx paseo-room export --apply` copies that state out; the export omits gate
+`--runtime`. Setup refuses while anything is still active or uncertain — including an isolated
+writer's lease or an unconfirmed worktree create or close — and keeps the recorded state once it
+proceeds. Retained worktrees belong to Paseo, and directories a failed teardown left behind are
+yours: setup and `remove` count both and delete neither. Close a retained worktree from the panel
+before deselecting (or archive it in Paseo afterwards); remove a left-behind directory by hand, and
+its finding clears. `npx paseo-room export --apply` copies that state out; the export omits gate
 output unless you add `--include-gate-output`, and briefs or commands written by a seat cannot be
 proven secret-free. `remove --apply` warns about runtime history and then deletes it with the rest
 of the room.
@@ -651,7 +774,10 @@ of the room.
 - [docs/product/runtime-coordination-prd.md](docs/product/runtime-coordination-prd.md),
   [docs/design/runtime-coordination.md](docs/design/runtime-coordination.md) and
   [docs/plans/runtime-coordination-phase1-implementation-plan.md](docs/plans/runtime-coordination-phase1-implementation-plan.md)
-  — the runtime coordination preview: requirements, technical design and Phase 1 plan.
+  — the runtime coordination preview: requirements, technical design and Phase 1 plan;
+  [docs/design/runtime-coordination-phase2.md](docs/design/runtime-coordination-phase2.md) and
+  [docs/plans/runtime-coordination-phase2-implementation-plan.md](docs/plans/runtime-coordination-phase2-implementation-plan.md)
+  — worktree concurrency (Phase 2).
 - [docs/product/paseo-room-prd.md](docs/product/paseo-room-prd.md) — the original PRD, kept
   for history; the transactional-installer requirements in it were deliberately dropped.