paseo-room 0.7.0 → 0.9.0

package/README.md

@@ -278,9 +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, 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.
+fallback unless you have a reason not to: the plugin hook is verified, and a *resumed* session
+keeps the room prompt it was created with (on Paseo 0.9.2 a daemon restart does not refresh it),
+but what the model actually reads is not proven, and `CLAUDE.md` is what covers that case.
 
 Pi providers use a strict command tail:
 
@@ -406,8 +406,10 @@ npx paseo-room@<new-version> verify
 First inspect the dry run, then apply it. The apply regenerates managed prompt carriers,
 the Codex model catalogs and `AUTHENTICATION.md` from the newly resolved binaries, but
 preserves role credential paths and the operator agent homes. Stop and restart every affected
-seat after the apply; sending another turn to an already-running seat is not a restart.
-`setup` and `verify` prove the files and live Paseo configuration, not that an existing model
+seat after the apply; sending another turn to an already-running seat is not a restart. A
+Claude seat keeps the contract Paseo stored when it was created, and a daemon restart resumes it
+with that same prompt, so for Claude open a new seat instead. `setup` and `verify` prove the
+files and live Paseo configuration, not that an existing model
 context reloaded them. Only a newly launched seat context is expected to ingest the
 regenerated instructions.
 
@@ -483,7 +485,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
@@ -621,10 +625,38 @@ npx paseo-room verify
   working.
 - **Lead** gains room tools such as `assignment_create`, `assignment_dispatch`, `assignment_answer`,
   `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`).
+  `gate_run` runs in the background, and a notice tells Lead when the gate ends, green, red or
+  without a trustworthy result.
+  `assignment_status` leaves out the brief Lead wrote (its outcome stays), keeps the last 10 history
+  entries, and gives a decided assignment with nothing left to close one line, unless Lead passes
+  `full: true`.
   **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.
-- **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
+  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.
+- **Seat context.** The panel and each seat's role pill show how full the seat's context is, as
+  Paseo reports it for the latest model call, and when the runtime last saw it compact. **Settings ›
+  Room seats › Seat context** sets marks per role, as a share of each seat's own model window:
+  - *Lead · report at* (30%): past it, the Lead's Supervisor gets one fact line and the panel shows
+    it with **Replace Lead…**, so you can hand over to a fresh Lead rather than let this one compact.
+  - *compact at* (Lead 50%, Supervisor and Peer off): a room Claude seat gets
+    `CLAUDE_CODE_AUTO_COMPACT_WINDOW` when its session opens, at creation or on a resume after a
+    daemon restart, so Claude compacts at that share instead of near the end of a 1M window. An open
+    session keeps what it opened with. Codex and Pi seats show their context and keep their own
+    compaction.
+- **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.
@@ -637,9 +669,11 @@ npx paseo-room verify
 - **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 its
-    runtime record: assignments, isolated writers, findings and recovery.
-  - Starting a Supervisor, starting a project and assigning a Supervisor are guided forms.
+  - 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, adding a repository, starting a Lead for a project that has none, 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).
@@ -659,19 +693,47 @@ learn only when you ask it to check.
   - 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.
+    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.
+  - They report, in a digest, a Lead whose context passes the rotation mark, once per crossing.
+  - 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`. 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.
+  - 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, **New Supervisor** opens one in an existing directory
+  outside every repository. **Add repository** checks a repository, opens its Lead under the
+  Supervisor you pick, and sends a fixed kickoff with your first directive verbatim; it also offers
+  the projects the room observes without a Lead. A project with no live Lead offers **Start Lead**
+  on its own screen, with its Supervisor preselected. **Assign Supervisor** moves an existing
+  project under a Supervisor.
+- **Replacing a Lead.** **Replace Lead…** above a project's seats, or on a *context past rotation
+  mark* item, hands the project to a fresh Lead:
+  - It checks for a quiet point first: the Lead idle, every runtime assignment it leads settled, no
+    runtime notice waiting for it, no seat it opened still working. It also shows what Paseo's
+    archive does to each seat the Lead opened: those in its workspace are archived with it, and one
+    in another workspace or open in a tab is detached and kept.
+  - It asks the Lead for a handoff in fixed sections, and you review and edit it. Nothing is
+    archived until you confirm, and you may cancel until then.
+  - On **Replace Lead**, the runtime archives the Lead and starts `<repository> — Lead` with the same
+    agent under the same Supervisor. The new Lead's first message is the kickoff and your reviewed
+    handoff, verbatim, and it verifies the handoff and reports to you before it acts outside the
+    repository. The Supervisor gets one line naming the new Lead.
+  - The handoff stays on this machine, under `~/.paseo-room/runtime/v1/attention/successions/`,
+    owner-only and never sent to the sensor or in a letter. Finished replacements are pruned after 30
+    days.
+  - If the replacement stops after the archive, the project offers **Finish replacing Lead**, which
+    creates no second Lead, or cancel, which leaves the project as it is. A replacement that fails
+    before the archive stays on the project's screen for a day, with the reason.
+  - Paseo archives the seats in the Lead's workspace with it; the runtime archives them too when the
+    Lead is not running, when Paseo would take none.
 - **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/)

package/dist/index.js

@@ -15,7 +15,7 @@ var init_package = __esm({
   "package.json"() {
     package_default = {
       name: "paseo-room",
-      version: "0.7.0",
+      version: "0.9.0",
       description: "One CLI that configures Codex, Claude Code, and Pi role homes in $HOME and registers them with your local Paseo daemon.",
       keywords: [
         "paseo",
@@ -691,10 +691,10 @@ async function loginRole(agentValue, roleValue, options, output) {
   const childEnv = { ...env, ...invocation.env };
   const launch = options.spawn ?? spawnLogin;
   return new Promise((resolve5) => {
-    let settled = false;
+    let settled2 = false;
     const finish = (code2) => {
-      if (settled) return;
-      settled = true;
+      if (settled2) return;
+      settled2 = true;
       resolve5(code2);
     };
     let child;
@@ -870,6 +870,11 @@ var init_prompts = __esm({
       pi: {
         communicationStyle: { path: "pi/communication-style.md", kind: "capsule" },
         runtime: { path: "pi/runtime.md", kind: "capsule" }
+      },
+      /** Messages the runtime plugin sends a Lead on Human's instruction; setup renders them into the plugin. */
+      runtime: {
+        handoffRequest: { path: "runtime/handoff-request.md", kind: "section" },
+        successorKickoff: { path: "runtime/successor-kickoff.md", kind: "section" }
       }
     };
     PromptAssetError = class extends Error {
@@ -1688,20 +1693,20 @@ function runProbeProcess(executable, adapterEntry, env, options, cwd) {
     const child = spawn2(executable, args, { cwd, detached: true, env, stdio: ["pipe", "pipe", "pipe"] });
     const stdout = [];
     let bytes = 0;
-    let settled = false;
+    let settled2 = false;
     const finish = (result) => {
-      if (settled) return;
-      settled = true;
+      if (settled2) return;
+      settled2 = true;
       clearTimeout(timer);
       resolveResult(result);
     };
     const abort = (reason3) => {
-      if (settled) return;
+      if (settled2) return;
       terminateProbe(child);
       finish({ ok: false, stdout: Buffer.concat(stdout).toString("utf8"), reason: reason3 });
     };
     const capture = (chunk, keep) => {
-      if (settled) return;
+      if (settled2) return;
       bytes += chunk.length;
       if (bytes > outputLimit) {
         abort("overflow");
@@ -2417,6 +2422,21 @@ function renderRuntimeManifestFile(agents, roles) {
   return `${JSON.stringify(renderRuntimeManifest(agents, roles), null, 2)}
 `;
 }
+function renderSuccessionText() {
+  return [
+    "/** Generated by paseo-room setup. The Markdown prompt assets remain authoritative. */",
+    "export interface SuccessionText {",
+    "  readonly request: string;",
+    "  readonly kickoff: string;",
+    "}",
+    "",
+    "export const SUCCESSION_TEXT: SuccessionText | undefined = {",
+    `  request: ${typescriptTemplateLiteral(loadPromptAsset("runtime", "handoffRequest"))},`,
+    `  kickoff: ${typescriptTemplateLiteral(loadPromptAsset("runtime", "successorKickoff"))},`,
+    "};",
+    ""
+  ].join("\n");
+}
 function renderRuntimeLocation(layout) {
   const location = { pluginDirectory: runtimePluginDir(layout), runtimeRoot: join12(layout.roomHome, "runtime", "v1") };
   return [
@@ -2448,22 +2468,25 @@ function runtimePluginEntries(layout, agents, roles) {
     ...files.map((path) => ({
       kind: "file",
       path: join12(root, path),
-      content: path === LOCATION_MODULE ? renderRuntimeLocation(layout) : readFileSync4(join12(BUNDLE, path), "utf8")
+      content: path === LOCATION_MODULE ? renderRuntimeLocation(layout) : path === SUCCESSION_MODULE ? renderSuccessionText() : readFileSync4(join12(BUNDLE, path), "utf8")
     })),
     { kind: "file", path: join12(root, MANIFEST_FILE), content: renderRuntimeManifestFile(agents, roles) }
   ];
 }
-var BUNDLE, LOCATION_MODULE;
+var BUNDLE, LOCATION_MODULE, SUCCESSION_MODULE;
 var init_runtime = __esm({
   "src/runtime.ts"() {
     "use strict";
+    init_plugin();
     init_roles();
     init_instructions();
+    init_prompts();
     init_manifest();
     init_identity();
     init_policy();
     BUNDLE = fileURLToPath(new URL("./runtime-plugin/", import.meta.url));
     LOCATION_MODULE = "server/generated/location.ts";
+    SUCCESSION_MODULE = "server/generated/succession.ts";
   }
 });
 
@@ -2481,7 +2504,7 @@ function boundedString(max = MAX_STRING_BYTES) {
 function boundedArray(item) {
   return z4.array(item).max(MAX_ARRAY_ITEMS);
 }
-var MAX_AGGREGATE_BYTES, MAX_ARRAY_ITEMS, MAX_STRING_BYTES, MAX_COMMAND_BYTES, MAX_GATE_TIMEOUT_SECONDS, encoder, MAX_WORKTREE_LEASES;
+var MAX_AGGREGATE_BYTES, MAX_ARRAY_ITEMS, MAX_STRING_BYTES, MAX_COMMAND_BYTES, MAX_GATE_TIMEOUT_SECONDS, MAX_HANDOFF_BYTES, encoder, MAX_WORKTREE_LEASES;
 var init_limits = __esm({
   "src/runtime-plugin/shared/limits.ts"() {
     "use strict";
@@ -2490,6 +2513,7 @@ var init_limits = __esm({
     MAX_STRING_BYTES = 8 * 1024;
     MAX_COMMAND_BYTES = 16 * 1024;
     MAX_GATE_TIMEOUT_SECONDS = 3600;
+    MAX_HANDOFF_BYTES = 64 * 1024;
     encoder = new TextEncoder();
     MAX_WORKTREE_LEASES = 3;
   }
@@ -2841,6 +2865,7 @@ function reclaimed(view, event) {
   delete copy.peerAgentId;
   delete copy.observedProviderId;
   delete copy.observedModel;
+  delete copy.observedThinking;
   return { ...copy, state: "dispatching", reportingState: "consumed", eventIds: [...view.eventIds, event.id] };
 }
 function applyReport(state, view, event) {
@@ -2923,7 +2948,13 @@ function applyEvent(state, event) {
   const id2 = view.id;
   switch (event.type) {
     case "assignment.dispatch-requested":
-      update(state, id2, { state: "dispatching", peerProviderId: event.data.peerProviderId, workspaceId: event.data.workspaceId }, event);
+      update(state, id2, {
+        state: "dispatching",
+        peerProviderId: event.data.peerProviderId,
+        workspaceId: event.data.workspaceId,
+        ...event.data.thinking === void 0 ? {} : { chosenThinking: event.data.thinking },
+        ...event.data.thinkingReason === void 0 ? {} : { thinkingReason: event.data.thinkingReason }
+      }, event);
       return;
     case "ownership.reserved":
       state.ownership.set(id2, { assignmentId: id2, workspaceId: event.data.workspaceId, baseCommit: event.data.baseCommit, state: "reserved" });
@@ -2950,7 +2981,12 @@ function applyEvent(state, event) {
       update(state, id2, { state: "uncertain" }, event);
       return;
     case "binding.published":
-      update(state, id2, { observedProviderId: event.data.providerId, observedModel: event.data.model, workspaceId: event.data.workspaceId }, event);
+      update(state, id2, {
+        observedProviderId: event.data.providerId,
+        observedModel: event.data.model,
+        workspaceId: event.data.workspaceId,
+        ...event.data.thinking === void 0 ? {} : { observedThinking: event.data.thinking }
+      }, event);
       return;
     case "ownership.held":
       setOwner(state, id2, { state: "held", agentId: event.data.agentId });
@@ -3281,7 +3317,11 @@ var init_actions = __esm({
         ...assignment,
         peerProvider: z6.string().min(1).max(128),
         isolation: z6.enum(["lead-workspace", "worktree"]).optional(),
-        serialOnly: boundedArray(boundedString()).optional()
+        serialOnly: boundedArray(boundedString()).optional(),
+        // A thinking option the operator allows for that Peer provider, and why; omitted, the Peer
+        // launches on its profile's option (docs/design/runtime-coordination-peer-effort.md E-D2).
+        thinking: z6.string().min(1).max(64).optional(),
+        thinkingReason: boundedString(1024).optional()
       }),
       assignment_answer: z6.strictObject({ ...assignment, answer: boundedString() }),
       assignment_rework: z6.strictObject({ ...assignment, instructions: boundedString() }),
@@ -3295,7 +3335,7 @@ var init_actions = __esm({
       assignment_reject: z6.strictObject({ ...assignment, reason }),
       assignment_abandon: z6.strictObject({ ...assignment, reason }),
       assignment_close: z6.strictObject(assignment),
-      assignment_status: z6.strictObject({ assignmentId: assignmentIdSchema.optional() }),
+      assignment_status: z6.strictObject({ assignmentId: assignmentIdSchema.optional(), full: z6.boolean().optional() }),
       gate_run: z6.strictObject(assignment),
       // Discarding a retained worktree's uncommitted work is Lead's explicit decision, with a reason.
       workspace_close: z6.strictObject({ ...assignment, discardUncommitted: z6.literal(true).optional(), reason: reason.optional() }).refine((input) => input.discardUncommitted !== true || input.reason !== void 0, { message: "discardUncommitted needs a reason", path: ["reason"] }),
@@ -3402,7 +3442,7 @@ function readEvent(value) {
   const parsed2 = readerSchema.safeParse(value);
   return parsed2.success ? { ok: true, event: parsed2.data } : { ok: false, reason: "invalid", detail: z8.prettifyError(parsed2.error) };
 }
-var EVENT_SCHEMA, id, text2, reason2, generation2, digest2, timestamp, workspaceIdSchema, branch, epoch, scopes, gateResultSchema, NOTICE_DISPOSITIONS, NOTICE_CLASSES, EVENT_PAYLOADS, EVENT_TYPES, SUPPORTED_PAYLOAD_VERSIONS, actorSchema, envelope, firstWriter, restWriters, firstReader, restReaders, writerSchema, readerSchema;
+var EVENT_SCHEMA, id, text2, reason2, thinkingOption, generation2, digest2, timestamp, workspaceIdSchema, branch, epoch, scopes, gateResultSchema, NOTICE_DISPOSITIONS, NOTICE_CLASSES, EVENT_PAYLOADS, EVENT_TYPES, SUPPORTED_PAYLOAD_VERSIONS, actorSchema, envelope, firstWriter, restWriters, firstReader, restReaders, writerSchema, readerSchema;
 var init_schema = __esm({
   "src/runtime-plugin/server/events/schema.ts"() {
     "use strict";
@@ -3415,6 +3455,7 @@ var init_schema = __esm({
     id = z8.string().min(1).max(128);
     text2 = boundedString();
     reason2 = boundedString(1024);
+    thinkingOption = z8.string().min(1).max(64);
     generation2 = z8.number().int().min(1);
     digest2 = z8.string().regex(/^sha256:[0-9a-f]{64}$/);
     timestamp = z8.iso.datetime({ offset: true });
@@ -3449,7 +3490,8 @@ var init_schema = __esm({
       "project.ownership-resolved": { keptLeadAgentId: id, decidedBy: z8.enum(["evidence", "human"]) },
       // Assignment lifecycle decided by Lead or Human (§5.1).
       "assignment.created": { input: assignmentCreateSchema, leadAgentId: id, leadProviderId: id },
-      "assignment.dispatch-requested": { peerProviderId: id, workspaceId: id },
+      // Lead's thinking choice within the operator's envelope, and why (peer-effort delta E-D2, E-D4).
+      "assignment.dispatch-requested": { peerProviderId: id, workspaceId: id, thinking: thinkingOption.optional(), thinkingReason: reason2.optional() },
       "assignment.answered": { answer: text2 },
       "assignment.rework-requested": { instructions: text2 },
       "assignment.accepted": {
@@ -3492,7 +3534,8 @@ var init_schema = __esm({
         model: z8.string().min(1).max(256),
         parentAgentId: id,
         workspaceId: id,
-        roomGeneration: id
+        roomGeneration: id,
+        thinking: thinkingOption.optional()
       },
       "reporting.generation-opened": { generation: generation2, capabilityHash: digest2, turn: z8.enum(["initial", "answer", "rework", "follow-up"]) },
       "run.requested": { intentId: id, generation: generation2, promptDigest: digest2 },