create-walle 0.10.1 → 0.10.2

package/template/coding-task-manager/lib/auth-rate-limit.js

@@ -1,5 +1,10 @@
 'use strict';
 
+// The one capability that selects the wide `peer` bucket below (WP-3). Spelled as a literal on
+// purpose: lib/auth-rules.js owns the constant, and requiring that module here would put this
+// low-level limiter behind the rule tables (and their consumers) for a one-string comparison.
+const PEER_CONTROL_SCOPE = 'peer-control';
+
 const DEFAULT_LIMITS = Object.freeze({
   // Remote/mobile page bootstrap fans out across settings, sessions, standup,
   // auth state, WebSocket setup, and cached refresh probes. Keep read traffic
@@ -8,6 +13,22 @@ const DEFAULT_LIMITS = Object.freeze({
   mutation: { refillPerMinute: 30, burst: 5 },
   admin: { refillPerMinute: 10, burst: 2 },
   step_up: { refillPerMinute: 10, burst: 3 },
+  // peer (WP-3, docs/remote-machine-hub-sessions-2026-10-22.html §6.4/§10): a remote machine HUB
+  // relays the keystrokes, prompts, approvals and lifecycle frames of every session it views on
+  // this box through ONE peer-control bearer — so the whole hub is one rate-limit key here and the
+  // `admin`/`mutation` buckets (10/min burst 2, 30/min burst 5) would throttle a hub that is simply
+  // relaying several sessions. Sized like `default` (600/min, burst 120) because a relay is
+  // read-shaped traffic that happens to be carried by mutating message types. Selected ONLY for an
+  // authenticated `peer-control` principal (see rateKindForRule below); every other caller keeps
+  // the exact bucket it had before.
+  peer: { refillPerMinute: 600, burst: 120 },
+  // machine_pair (WP-3, docs/machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3/D-13): the
+  // PRE-AUTH POST /api/machine-pairing/join. `sync`'s own bucket. It is the ONLY bucket selected by
+  // route rather than by principal: the join has no authenticated caller yet (the request carries the
+  // pool secret it is trying to prove), so it is keyed by REMOTE ADDRESS and sized for a human typing
+  // a code plus a retry or two — 5/min, burst 5 — never for a script. A code is 20^8; this bucket
+  // plus lib/machine-pairing.js's 5-wrong-redeem burn is what keeps the search space out of reach.
+  machine_pair: { refillPerMinute: 5, burst: 5 },
 });
 
 const DEFAULT_FAILED_AUTH = Object.freeze({
@@ -131,9 +152,28 @@ class AuthRateLimiter {
   }
 }
 
-function rateKindForRule(rule, pathname = '') {
+/**
+ * Which bucket a rule is charged to.
+ *
+ * The optional third argument is the AUTH CONTEXT the decision is being made for. It exists for
+ * exactly one case (WP-3 §6.4): a `peer-control` principal is a machine hub relaying many sessions
+ * through one bearer, so its mutations are charged to the wide `peer` bucket instead of
+ * `admin`/`mutation`. Callers that pass no auth (or an auth with no `peer-control` scope) get
+ * byte-identical behaviour to before this argument existed — it can only ever WIDEN a bucket for a
+ * peer-control principal, never narrow one.
+ *
+ * @param {{mutation?: boolean, scope?: string}} rule
+ * @param {string} [pathname]
+ * @param {{scopes?: Set<string>|string[]}} [auth]
+ */
+function rateKindForRule(rule, pathname = '', auth = null) {
   if (pathname === '/api/auth/begin-step-up') return 'step_up';
   if (!rule?.mutation) return 'default';
+  const scopes = auth && auth.scopes;
+  const isPeerControl = scopes instanceof Set
+    ? scopes.has(PEER_CONTROL_SCOPE)
+    : Array.isArray(scopes) && scopes.includes(PEER_CONTROL_SCOPE);
+  if (isPeerControl) return 'peer';
   if (rule.scope === 'admin' || rule.scope === 'create') return 'admin';
   return 'mutation';
 }

package/template/coding-task-manager/lib/auth-rules.js

@@ -2,30 +2,54 @@
 
 const ALL_SCOPES = Object.freeze(['read', 'respond', 'create', 'admin', 'sync']);
 
+// WP-1 (docs/remote-machine-hub-sessions-2026-10-22.html §5 D-7, §6.2, §9 S-17): the
+// `peer-control` capability. It is deliberately NOT a member of ALL_SCOPES: nothing that
+// parses scopes (env-scoped test tokens, device tokens, the admin expansion in parseScopes)
+// can ever mint it, so the only credential that carries it is the sync peer bearer
+// (CTM_SYNC_PEER_TOKEN / CTM_SYNC_PEER_TOKENS — same secret, no new env var), resolved in
+// lib/auth-context.js's resolveSyncPeerToken. `admin` never implies it and it implies nothing:
+// hasScope()/authorize() grant it ONLY the rule rows that declare `peerControl: true`.
+const PEER_CONTROL_SCOPE = 'peer-control';
+
+// §6.2's allowlist of WS message types a peer-control identity may send:
+// attach, keyframe-req, ack, nack, frame-receipt, wake-resync, submit-prompt,
+// approval-resolve, model-change, park, wake, kill, list, create.
+//
+// WP-3b (docs/remote-machine-hub-sessions-2026-10-22.html §6.2, AC-3a) adds the nine types the
+// relay forwards VERBATIM from the hub browser to the box PTY and whose reply the hub fans back
+// out — without them the box answers `auth-error{code:'insufficient_scope'}` and the relayed
+// terminal cannot be typed into: input, interrupt-session, resize, reflow, snapshot, reconcile,
+// flow, terminal-bootstrap, terminal-bootstrap-ack. Their scope/mutation/step-up are UNCHANGED
+// (only the `peerControl` flag is added, exactly like the §6.2 rows above). Every other WS type
+// stays out of reach for the peer bearer (it keeps only the `sync` scope it already had) — in
+// particular `view`, `detach`, `ping` and `client-info` are never forwarded upstream by the
+// relay, so they remain unflagged.
 const WS_AUTH_RULES = Object.freeze({
-  list: rule('read', false, 'never'),
-  attach: rule('read', false, 'never'),
+  list: peerControl('read', false, 'never'),
+  attach: peerControl('read', false, 'never'),
   detach: rule('read', false, 'never'),
   // D-1 (terminal-delivery-contract-simplification-2026-09-21.html): replaces
   // subscribe/unsubscribe/set-visible/client-visibility with the one full-set
   // declaration. Same viewer-local, read-only class as its predecessors.
   view: rule('read', false, 'never'),
   ping: rule('read', false, 'never'),
-  'wake-resync': rule('read', false, 'never'),
+  'wake-resync': peerControl('read', false, 'never'),
   'subscribe-stream': rule('read', false, 'never'),
   'unsubscribe-stream': rule('read', false, 'never'),
   'subscribe-terminal-tail': rule('read', false, 'never'),
   'unsubscribe-terminal-tail': rule('read', false, 'never'),
-  snapshot: rule('read', false, 'never'),
-  reconcile: rule('read', false, 'never'),
-  resize: rule('read', false, 'never'),
-  reflow: rule('read', false, 'never'),
+  // WP-3b: the relay forwards these viewer-render frames verbatim (S-22 resync/repaint), so the
+  // peer bearer must reach them; scope/mutation/step-up are unchanged.
+  snapshot: peerControl('read', false, 'never'),
+  reconcile: peerControl('read', false, 'never'),
+  resize: peerControl('read', false, 'never'),
+  reflow: peerControl('read', false, 'never'),
   // State-sync render protocol: clients acknowledge frames, request bounded
   // keyframes, and report visible sessions. These only affect that viewer's
   // stream/backpressure state, not agent execution or persisted session data.
-  ack: rule('read', false, 'never'),
-  'frame-receipt': rule('read', false, 'never'),
-  'keyframe-req': rule('read', false, 'never'),
+  ack: peerControl('read', false, 'never'),
+  'frame-receipt': peerControl('read', false, 'never'),
+  'keyframe-req': peerControl('read', false, 'never'),
   'restore-applied': rule('read', false, 'never'),
   // D-2/WP-2 verdict/adopt round-trip ack — same viewer-local render-protocol
   // class as frame-receipt/restore-applied: acknowledges a server-shipped
@@ -35,8 +59,8 @@ const WS_AUTH_RULES = Object.freeze({
   // this session's live output, read-only, no PTY input or persisted-state mutation.
   // Cold bootstrap is the viewer-local bounded terminal baseline and its
   // receipt. Neither message writes PTY input or persisted session state.
-  'terminal-bootstrap': rule('read', false, 'never'),
-  'terminal-bootstrap-ack': rule('read', false, 'never'),
+  'terminal-bootstrap': peerControl('read', false, 'never'),
+  'terminal-bootstrap-ack': peerControl('read', false, 'never'),
   'session-inventory': rule('read', false, 'never'),
   'terminal-geometry-claim-v2': rule('read', false, 'never'),
   'secondary-snapshot-retry': rule('read', false, 'never'),
@@ -46,7 +70,7 @@ const WS_AUTH_RULES = Object.freeze({
   // Backpressure flow control: a viewer asks to pause/resume its own output
   // stream (the server further gates an actual PTY pause to raw-eligible
   // primaries). Same render-control class as reconcile/reflow — read scope.
-  flow: rule('read', false, 'never'),
+  flow: peerControl('read', false, 'never'),
   // Client-reported render diagnostics (rows-flap attribution probe) — telemetry
   // into the per-session diagnostics ring; rate-limited + scalar-whitelisted in
   // handleClientDiag, so viewer (read) scope is sufficient.
@@ -54,7 +78,7 @@ const WS_AUTH_RULES = Object.freeze({
   'client-theme-report': rule('read', false, 'never'),
   'client-diag': rule('read', false, 'never'),
   'client-error-rollup': rule('read', false, 'never'),
-  nack: rule('read', false, 'never'),
+  nack: peerControl('read', false, 'never'),
   'walle-history-request': rule('read', false, 'never'),
   'walle-history-reproject': rule('read', false, 'never'),
   'walle-history-repair-metrics': rule('read', false, 'never'),
@@ -62,37 +86,49 @@ const WS_AUTH_RULES = Object.freeze({
   // metadata. It cannot write PTY input or persisted session state.
   'lifecycle-draft': rule('read', false, 'never'),
 
-  input: rule('respond', true, 'remote'),
-  'interrupt-session': rule('respond', true, 'remote'),
-  'submit-prompt': rule('respond', true, 'remote'),
-  'resume-prompt-select': rule('respond', true, 'remote'),
+  // WP-3b AC-3a: typing in a hub browser reaches the box PTY through these two; the relay
+  // forwards them verbatim and the box echoes the result back. respond + stepUp:'remote' for
+  // every other caller is unchanged — only the peerControl flag is added.
+  input: peerControl('respond', true, 'remote'),
+  'interrupt-session': peerControl('respond', true, 'remote'),
+  'submit-prompt': peerControl('respond', true, 'remote'),
+  // WP-1 (docs/remote-resume-choice-click-2026-10-25.html §5 D-2, §9 S-4): the hub forwards the
+  // resume strip's choice chip for a MIRROR session, so the peer bearer must reach this row or the
+  // box answers with `auth-error insufficient_scope` and the click is lost. FLAG ONLY — the
+  // (`respond`, mutation true, step-up 'remote') tuple every other caller sees is unchanged, and the
+  // box still runs `_selectResumePromptChoice`'s generation/fingerprint/live-screen validation.
+  'resume-prompt-select': peerControl('respond', true, 'remote'),
   'revalidate-recovered-prompt': rule('respond', true, 'remote'),
   'attach-image': rule('respond', true, 'remote'),
   'attach-image-reference': rule('respond', true, 'remote'),
   // WP-3 "Deliver now" override on a stalled draft chip -- same class as attach-image (it
   // triggers the same PTY paste path, just bypassing the reconciler's readiness gate).
-  'image-deliver-now': rule('respond', true, 'remote'),
+  // WP-1 (docs/remote-session-image-upload-forwarding-2026-10-24.html §6/§7): the hub forwards this
+  // verbatim for a mirror session, so the peer bearer must reach it (flag only; scope/mutation/stepUp
+  // unchanged). attach-image/attach-image-reference above stay rule(...) — server-side delivery is
+  // default ON, so the client never sends them for a box-owned draft.
+  'image-deliver-now': peerControl('respond', true, 'remote'),
   'walle-message': rule('respond', true, 'remote'),
   'walle-cancel': rule('respond', true, 'remote'),
   'walle-permission-response': rule('respond', true, 'remote'),
   // Resolve a parked protocol-hook approval (allow/deny) — same class as
   // answering any other approval prompt.
-  'approval-resolve': rule('respond', true, 'remote'),
+  'approval-resolve': peerControl('respond', true, 'remote'),
   // Session lifecycle controls share the same admin boundary as kill/model
   // changes.
   'resume-retry': rule('admin', true, 'remote'),
-  park: rule('admin', true, 'remote'),
+  park: peerControl('admin', true, 'remote'),
   pin: rule('admin', true, 'remote'),
-  wake: rule('admin', true, 'remote'),
+  wake: peerControl('admin', true, 'remote'),
   prewarm: rule('admin', true, 'remote'),
 
-  create: rule('create', true, 'remote'),
+  create: peerControl('create', true, 'remote'),
 
-  kill: rule('admin', true, 'remote'),
+  kill: peerControl('admin', true, 'remote'),
   rename: rule('admin', true, 'remote'),
   'update-session-cwd': rule('admin', true, 'remote'),
   'session-surface-preference': rule('admin', true, 'remote'),
-  'model-change': rule('admin', true, 'remote'),
+  'model-change': peerControl('admin', true, 'remote'),
 });
 
 const HTTP_AUTH_RULES = Object.freeze([
@@ -134,21 +170,25 @@ const HTTP_AUTH_RULES = Object.freeze([
   exact('POST', '/api/remote/messages', 'respond', true, 'never'),
   regex('POST', /^\/api\/remote\/devices\/[^/]+\/revoke$/, 'admin', true, 'remote', { loopbackOnly: true }),
   exact('POST', '/api/mobile/attachments/upload', 'respond', true, 'never'),
-  regex('GET', /^\/api\/sessions\/[^/]+\/image-drafts(?:\/[^/]+\/content)?$/, 'read', false, 'never'),
+  // WP-1 (docs/remote-session-image-upload-forwarding-2026-10-24.html §6, D-3): the box-side
+  // image-draft family a hub forwards for a MIRROR session. Only the `peerControl` flag is added —
+  // scope, mutation and step-up are unchanged for every other caller — exactly like the hub §6.2 rows.
+  regex('GET', /^\/api\/sessions\/[^/]+\/image-drafts(?:\/[^/]+\/content)?$/, 'read', false, 'never', { peerControl: true }),
   regex('GET', /^\/api\/sessions\/[^/]+\/native-subagents\/[^/]+\/messages$/, 'read', false, 'never'),
   // WP-0 (docs/exited-worker-transcript-view-2026-10-17.html §6c): a routed worker's own read-only
   // transcript page. Same posture as its native sibling -- GET, read scope, non-mutation, never
   // step-up. Worker lifecycle (resume/kill/retire) stays on its own stronger rules.
   regex('GET', /^\/api\/sessions\/[^/]+\/worker-transcript\/messages$/, 'read', false, 'never'),
-  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts$/, 'respond', true, 'remote'),
-  regex('PUT', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/, 'respond', true, 'remote'),
-  regex('DELETE', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/, 'respond', true, 'remote'),
-  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/delivery$/, 'respond', true, 'remote'),
-  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/freeze$/, 'respond', true, 'remote'),
-  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/submit$/, 'respond', true, 'remote'),
+  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('PUT', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('DELETE', /^\/api\/sessions\/[^/]+\/image-drafts$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('DELETE', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/delivery$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/freeze$/, 'respond', true, 'remote', { peerControl: true }),
+  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/submit$/, 'respond', true, 'remote', { peerControl: true }),
   // F2 (image-attach-latency-redesign fix round): retry only flips failed->ready so the
   // reconciler re-delivers; same mutation class as the other draft-lifecycle routes above.
-  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/retry$/, 'respond', true, 'remote'),
+  regex('POST', /^\/api\/sessions\/[^/]+\/image-drafts\/[^/]+\/retry$/, 'respond', true, 'remote', { peerControl: true }),
 
   exact('POST', '/api/permissions/walle-check', 'admin', true, 'remote', { loopbackOnly: true }),
   exact('POST', '/api/permissions/check', 'admin', true, 'remote', { loopbackOnly: true }),
@@ -160,6 +200,55 @@ const HTTP_AUTH_RULES = Object.freeze([
   exact('GET', '/api/permissions/doctor', 'admin', false, 'remote', { loopbackOnly: true }),
 
   exact('GET', '/api/setup/network', 'admin', false, 'never'),
+  // WP-0 (remote-machine-hub-sessions-2026-10-22.html §6.1): the hub machine registry. Same
+  // posture as the setup routes above — the registry decides which boxes this CTM will dial and
+  // trusts them with peer-control later (WP-1), so it is an admin act and it is LOCAL-ONLY:
+  // loopbackOnly, which (shared/request-provenance.js) already refuses any forwarded/relayed
+  // request. Registration is a user action in Settings → Machines (D-11, no flag).
+  // WP-2a (machine-pool-picker-pairing-dashboard-2026-10-24.html §5 D-13 rev 2): loopbackOnly is
+  // RELAXED. The phone reads GET /api/machines off-LAN (public/m/app.js:13348) and the phone parity
+  // contract (no phone-only machine feature) makes the management rows reachable too. The rows carry
+  // URLs/hostnames and a credential CLASS WORD, never a token (peerCredential: 'pool'|'env'|'missing').
+  //   GET  /api/machines            read, no step-up, NOT loopbackOnly
+  //   POST /api/machines            admin + step-up remote, NOT loopbackOnly
+  //   POST /api/machines/:id/remove admin + step-up remote, NOT loopbackOnly
+  exact('GET', '/api/machines', 'read', false, 'never'),
+  exact('POST', '/api/machines', 'admin', true, 'remote'),
+  regex('POST', /^\/api\/machines\/[^/]+\/remove$/, 'admin', true, 'remote'),
+  // WP-3 (machine-pool-picker-pairing-dashboard-2026-10-24.html §6.3, D-13, §9 S-16): the MEMBER
+  // side of pairing — this machine joins a pool by redeeming the box's code. It mints nothing and
+  // reads nothing back, but it adopts a shared secret and rewrites this member's roster, so it is
+  // the same act as POST /api/machines: admin + step-up remote, NOT loopbackOnly, and NOT
+  // peerControl (a peer holds the pool bearer already and never needs to pair over it — pinning it
+  // false is what keeps tests/peer-control-auth.test.js's exact set honest).
+  exact('POST', '/api/machines/pair', 'admin', true, 'remote'),
+  // WP-3 §6.3/D-13: the BOX side's offer mint. Admin + step-up remote for the same reason: the
+  // response carries a live bearer code for one redemption, so it is a credential-minting act.
+  // POST /api/machine-pairing/join is deliberately ABSENT here — server.js dispatches phase
+  // 'api-cloudflare' before the auth wall (lib/api/machine-pairing.js states why), so a row would be
+  // a rule the dispatcher never consults.
+  exact('POST', '/api/machine-pairing/offers', 'admin', true, 'remote'),
+  // WP-2a D-4/D-13: this machine's OWN settings (name override, favorite, hidden). A user on any
+  // primary edits a REMOTE member through the ?machine= proxy, so the row must also admit the peer
+  // bearer — peerControl: true. Guest/user scope is `read`/never on GET (nothing here is a secret)
+  // and admin + step-up remote on POST. lib/api/machine-pool.js refuses a non-peer on the pool rows.
+  exact('GET', '/api/machine-self', 'read', false, 'never', { peerControl: true }),
+  exact('POST', '/api/machine-self', 'admin', true, 'remote', { peerControl: true }),
+  // WP-2a D-13/S-27: the pool routes. There is no dedicated "peer-only" rule mechanism in this
+  // codebase (peerControl ADDS the peer bearer to the row's normal reach), so the roster/rotate rows
+  // are declared `admin` + peerControl and the HANDLER refuses a non-peer principal with 403
+  // `peer_only` (lib/api/machine-pool.js) — the same reviewer-visible pattern as the machine-self
+  // rows. POST /api/pool/leave is an ordinary admin + step-up remote act.
+  exact('GET', '/api/pool/roster', 'admin', false, 'never', { peerControl: true }),
+  exact('POST', '/api/pool/roster', 'admin', true, 'remote', { peerControl: true }),
+  exact('POST', '/api/pool/rotate', 'admin', true, 'remote', { peerControl: true }),
+  exact('POST', '/api/pool/leave', 'admin', true, 'remote'),
+  // WP-1 (machine-pool-picker-pairing-dashboard-2026-10-24.html §6.1/D-13): this machine's own host
+  // stats. Read scope, and deliberately NOT loopbackOnly — the pool picker on a phone reaches a
+  // member through the hub's ?machine= proxy, which arrives as a non-loopback peer-control request,
+  // and the payload is hardware counters, not secrets. peerControl: true is the one reach delta this
+  // WP adds (tests/peer-control-auth.test.js pins it).
+  exact('GET', '/api/host/stats', 'read', false, 'never', { peerControl: true }),
   exact('GET', '/api/setup/network/microsoft-dev-tunnel/probe', 'admin', false, 'never'),
   // Go-Live wizard read view (design doc §Bootstrap & Auth): same posture as
   // GET /api/setup/network — admin scope, no step-up, remote-readable. The
@@ -201,16 +290,23 @@ const HTTP_AUTH_RULES = Object.freeze([
   regex('POST', /^\/api\/models\/workflows\/[^/]+\/runs$/, 'admin', true, 'remote'),
   regex('POST', /^\/api\/models\/workflow-runs\/[^/]+\/(?:abort|skip|retry|decide|rate)$/, 'admin', true, 'remote'),
   regex('POST', /^\/api\/models\/workflow-suggestions\/[^/]+$/, 'admin', true, 'remote'),
-  exact('GET', '/api/providers/login-state', 'read', false, 'never'),
-
-  exact('GET', '/api/projects', 'read', false, 'never'),
-  exact('GET', '/api/path-suggest', 'read', false, 'never'),
-  exact('POST', '/api/path-status', 'read', false, 'never'),
+  // WP-3 (DGX Spark coding readiness §2): the hub reads a BOX's sign-in truth with the peer bearer
+  // before it forwards a create — a box whose Claude/Codex CLI is signed out must be refused at the
+  // hub, not answered with a login prompt. `peerControl: true` is the only change: plain `read`/never.
+  exact('GET', '/api/providers/login-state', 'read', false, 'never', { peerControl: true }),
+
+  // WP-1 (§6.2/§6.5): the hub's remote picker calls these three on the BOX, over the relay
+  // leg, with the peer bearer — hence `peerControl: true`. Scope/step-up are unchanged: they
+  // were already plain `read`/never for every other caller.
+  exact('GET', '/api/projects', 'read', false, 'never', { peerControl: true }),
+  exact('GET', '/api/path-suggest', 'read', false, 'never', { peerControl: true }),
+  exact('POST', '/api/path-status', 'read', false, 'never', { peerControl: true }),
   exact('GET', '/api/rules', 'read', false, 'never'),
   exact('GET', '/api/rules/list', 'read', false, 'never'),
   exact('PUT', '/api/rules', 'admin', true, 'remote'),
 
-  exact('GET', '/api/recent-sessions', 'read', false, 'never'),
+  // WP-1 (§6.2): the hub's catalog read for a mirrored box session.
+  exact('GET', '/api/recent-sessions', 'read', false, 'never', { peerControl: true }),
   exact('GET', '/api/sessions/standup', 'read', false, 'never'),
   exact('GET', '/api/sessions/git-status', 'read', false, 'never'),
   exact('GET', '/api/session/prompts', 'read', false, 'never'),
@@ -243,6 +339,16 @@ const HTTP_AUTH_RULES = Object.freeze([
   regex('POST', /^\/api\/sessions\/[^/]+\/attention-dismiss$/, 'respond', true, 'never'),
   regex('POST', /^\/api\/sessions\/[^/]+\/submit-prompt$/, 'respond', true, 'never'),
   regex('POST', /^\/api\/sessions\/[^/]+\/interrupt$/, 'respond', true, 'remote'),
+  // WP-1 (docs/remote-machine-hub-sessions-2026-10-22.html §6.2): the box-side lifecycle verbs the
+  // hub forwards verbatim for a session the BOX owns (WP-6 added pin: the hub's HTTP lifecycle route
+  // forwards all four, and a pin the box refused would surface as a bare 403). Declared explicitly (rather than flagging the
+  // /^\/api\/sessions\// catch-all below, which would hand the peer bearer every unmatched session
+  // POST) with the catch-all's own admin/step-up posture, plus peerControl.
+  regex('POST', /^\/api\/sessions\/[^/]+\/(?:park|wake|revive|pin)$/, 'admin', true, 'remote', { peerControl: true }),
+  // WP-1 (§6.2, hub WP-2/§E): where this session's provider transcripts live, read by the hub for a
+  // mirrored box session. Previously had NO rule (loopback-only in practice) — the explicit read row
+  // is what makes it reachable for the peer bearer; scope read / no step-up / no mutation.
+  regex('GET', /^\/api\/sessions\/[^/]+\/transcripts$/, 'read', false, 'never', { peerControl: true }),
   // Lead-model switch (picker design WP-2): same class as the WS 'model-change' it replaces for
   // Claude/Codex tabs (admin + step-up); reading the request state is a plain read.
   regex('POST', /^\/api\/sessions\/[^/]+\/lead-model$/, 'admin', true, 'remote'),
@@ -272,7 +378,15 @@ const HTTP_AUTH_RULES = Object.freeze([
   exact('POST', '/api/instance/update/apply', 'admin', true, 'remote'),
   exact('GET', '/api/instance/migrate/export', 'admin', false, 'never'),
   exact('POST', '/api/instance/migrate/import', 'admin', true, 'remote'),
-  regex('POST', /^\/api\/providers\/[^/]+\/login$/, 'admin', true, 'remote'),
+  // WP-3 (remote-agent-sign-in-from-hub-browser-2026-10-25.html §5 D-7/D-9, §6): the hub forwards
+  // a sign-in to the BOX that must run it, over the peer bearer — so both POSTs also declare
+  // `peerControl: true`. Scope/mutation/step-up are unchanged: a peer is still evaluated as
+  // `admin` + remote step-up, and every non-peer caller sees exactly what it saw before.
+  regex('POST', /^\/api\/providers\/[^/]+\/login$/, 'admin', true, 'remote', { peerControl: true }),
+  // WP-1 (design §6, S-8): the code-return route is the /login twin — a write on the box
+  // (one PTY frame into the flow's own tab), so the same admin scope and the same remote
+  // step-up ceremony as starting a sign-in.
+  regex('POST', /^\/api\/providers\/[^/]+\/login\/code$/, 'admin', true, 'remote', { peerControl: true }),
   exact('GET', '/api/sync/outbox', 'sync', false, 'never'),
   exact('GET', '/api/sync/manifest', 'sync', false, 'never'),
   exact('POST', '/api/sync/outbox/ack', 'sync', true, 'never'),
@@ -331,10 +445,14 @@ const HTTP_AUTH_RULES = Object.freeze([
   regex('PUT', /^\/api\/workspaces\//, 'admin', true, 'remote'),
   regex('DELETE', /^\/api\/workspaces\//, 'admin', true, 'remote'),
 
-  exact('GET', '/api/worktrees', 'read', false, 'never'),
-  exact('POST', '/api/worktrees/create', 'create', true, 'remote'),
-  regex('GET', /^\/api\/worktrees\/create-jobs\/[a-zA-Z0-9_-]+(?:-[a-zA-Z0-9_-]+)*$/, 'read', false, 'never'),
-  regex('POST', /^\/api\/worktrees\/create-jobs\/[a-zA-Z0-9_-]+(?:-[a-zA-Z0-9_-]+)*\/cancel$/, 'admin', true, 'remote'),
+  // WP-1 (§6.2/§6.5): worktree LIST + CREATE are called on the box by the hub with the peer
+  // bearer, so both rows declare peerControl. Their scope/step-up are untouched.
+  exact('GET', '/api/worktrees', 'read', false, 'never', { peerControl: true }),
+  exact('POST', '/api/worktrees/create', 'create', true, 'remote', { peerControl: true }),
+  // Hub WP-5 amendment: an async create on the box returns a BOX job id, so the hub's progress poll
+  // and its cancel are proxied there too (lib/remote-machine-proxy.js) — same posture, plus the flag.
+  regex('GET', /^\/api\/worktrees\/create-jobs\/[a-zA-Z0-9_-]+(?:-[a-zA-Z0-9_-]+)*$/, 'read', false, 'never', { peerControl: true }),
+  regex('POST', /^\/api\/worktrees\/create-jobs\/[a-zA-Z0-9_-]+(?:-[a-zA-Z0-9_-]+)*\/cancel$/, 'admin', true, 'remote', { peerControl: true }),
   regex('POST', /^\/api\/worktrees\//, 'admin', true, 'remote'),
   regex('DELETE', /^\/api\/worktrees\//, 'admin', true, 'remote'),
 
@@ -412,6 +530,14 @@ function rule(scope, mutation, stepUp, extra = {}) {
   return Object.freeze({ scope, mutation: !!mutation, stepUp, ...extra });
 }
 
+// WP-1 (§6.2): the one way a rule row declares that the peer bearer may reach it. Kept as a
+// distinct flag rather than a scope union so `scope` (and everything that reads it — the
+// step-up matrix, the owner manifest, /api/auth/rules consumers) keeps its existing meaning;
+// authorize() consults the flag directly.
+function peerControl(scope, mutation, stepUp) {
+  return rule(scope, mutation, stepUp, { peerControl: true });
+}
+
 function exact(method, path, scope, mutation, stepUp, extra = {}) {
   return Object.freeze({ kind: 'http', method, path, exact: true, ...rule(scope, mutation, stepUp, extra) });
 }
@@ -437,10 +563,18 @@ function getWsAuthRule(messageType) {
 function hasScope(auth, requiredScope) {
   if (!requiredScope) return true;
   const scopes = auth?.scopes instanceof Set ? auth.scopes : new Set(auth?.scopes || []);
-  if (requiredScope === 'sync') return scopes.has('sync');
+  // Machine-to-machine capabilities are never implied by `admin`: sync keeps its existing
+  // special case, and peer-control (WP-1 §6.2) joins it — it is minted only on the peer
+  // bearer, so an admin/device token can never acquire it through the admin expansion.
+  if (requiredScope === 'sync' || requiredScope === PEER_CONTROL_SCOPE) return scopes.has(requiredScope);
   return scopes.has('admin') || scopes.has(requiredScope);
 }
 
+function hasPeerControlScope(auth) {
+  const scopes = auth?.scopes instanceof Set ? auth.scopes : new Set(auth?.scopes || []);
+  return scopes.has(PEER_CONTROL_SCOPE);
+}
+
 function authorize(auth, rule, options = {}) {
   if (!rule) return { ok: false, status: 403, code: 'auth_rule_missing' };
   if (!auth?.authenticated) return { ok: false, status: 401, code: 'unauthorized' };
@@ -453,6 +587,10 @@ function authorize(auth, rule, options = {}) {
   if (rule.bootstrapLocal && options.zeroWebauthnCredentials && !auth.isLoopback && !options.isLocalOrTailnet) {
     return { ok: false, status: 403, code: 'bootstrap_local_required' };
   }
+  // WP-1 (§6.2): a row that declares peerControl is satisfied by the peer-control scope in
+  // full — the peer is a machine credential that cannot perform a passkey step-up ceremony,
+  // exactly like the sync scope on /api/sync/*. No other rule grants it anything.
+  if (rule.peerControl && hasPeerControlScope(auth)) return { ok: true };
   if (!hasScope(auth, rule.scope)) return { ok: false, status: 403, code: 'insufficient_scope' };
   if (options.enforceStepUp && !auth.isLoopback && rule.stepUp === 'remote' && !auth.stepUpFresh) {
     return { ok: false, status: 403, code: 'step_up_required' };
@@ -471,6 +609,7 @@ function publicRule(rule) {
     stepUp: rule.stepUp,
     loopbackOnly: !!rule.loopbackOnly,
     bootstrapLocal: !!rule.bootstrapLocal,
+    peerControl: !!rule.peerControl,
   };
 }
 
@@ -484,11 +623,13 @@ function listWsAuthRules() {
 
 module.exports = {
   ALL_SCOPES,
+  PEER_CONTROL_SCOPE,
   HTTP_AUTH_RULES,
   WS_AUTH_RULES,
   authorize,
   getHttpAuthRule,
   getWsAuthRule,
+  hasPeerControlScope,
   hasScope,
   listHttpAuthRules,
   listWsAuthRules,

package/template/coding-task-manager/lib/broadcast-serialize.js

@@ -145,7 +145,8 @@ function createBroadcastPayloadSerializer({
       if (options.isMemoBypass?.(session) || !memo) return null;
       signature += memo.key + '\x1e';
     }
-    return signature + '#' + options.sourceSessions.length;
+    // extraSignature: rows appended AFTER the local snapshot (the machine hub's remote rows).
+    return signature + '#' + options.sourceSessions.length + (options.extraSignature ? '#' + options.extraSignature : '');
   }
 
   function makeRecord(envelope, clients, signature) {

package/template/coding-task-manager/lib/browser-session-broker.js

@@ -1189,6 +1189,7 @@ class BrowserSessionBroker {
     if (this.profileMigration?.ensureProfile) record = await this.profileMigration.ensureProfile(record);
     const existing = await this._boundHandle(record, { required: false });
     if (existing && (typeof this.adapter.isLive !== 'function' || this.adapter.isLive(existing))) return existing;
+    if (existing) await this._dropDeadHandle(record, existing);
     let handle;
     try {
       handle = await this.adapter.open({ contextId: record.contextId, profileDir: record.profileDir,
@@ -1210,7 +1211,7 @@ class BrowserSessionBroker {
     record = await this._ensureProcessOwnership(record, { allowTakeover: true });
     const existing = await this._boundHandle(record, { required: false });
     if (existing && (typeof this.adapter.isLive !== 'function' || this.adapter.isLive(existing))) return record;
-    if (existing) this.handles.delete(record.contextId);
+    if (existing) await this._dropDeadHandle(record, existing);
     let recovered = record;
     if (record.processGeneration !== this.processGeneration || existing || record.status === 'dormant') {
       recovered = {
@@ -1292,6 +1293,13 @@ class BrowserSessionBroker {
     return handle;
   }
 
+  // A handle that is no longer live (lost page, disconnected browser) still owns whatever of its
+  // browser survives; close it rather than just forgetting it.
+  async _dropDeadHandle(record, handle) {
+    if (this.handles.get(record.contextId) === handle) this.handles.delete(record.contextId);
+    await this.adapter.close(handle).catch((error) => this._reportFailure('dead-handle-close', error));
+  }
+
   _rebindLocalHandle(record) {
     const handle = this.handles.get(record.contextId);
     if (!handle) return;

package/template/coding-task-manager/lib/browser-use-adapter.js

@@ -31,6 +31,9 @@ function chromiumChildEnvironment(parentEnvironment = process.env) {
   return environment;
 }
 
+// Chromium ChildProcesses whose group has been reaped, so the exit and close paths reap it once.
+const REAPED = new WeakSet();
+
 class BrowserUseAdapter {
   constructor({
     puppeteer = null,
@@ -84,6 +87,11 @@ class BrowserUseAdapter {
         allowedOrigins: new Set([allowedOrigin, ...allowedOrigins].filter(Boolean)),
         blockedOrigin: '', disconnected: false, lastMainResponseStatus: 0 };
       browser.once('disconnected', () => { handle.disconnected = true; });
+      // A browser lost without close() (crash, external kill) leaves the same helpers behind. Reap on
+      // the main process's exit, never on 'disconnected': the CDP socket drops while Chromium is still
+      // shutting down, and killing its group then loses storage it has not flushed yet.
+      const child = typeof browser.process === 'function' ? browser.process() : null;
+      child?.once?.('exit', () => this._reapBrowserProcess(child, 'browser-exit'));
       page.on('response', (response) => {
         try {
           const request = response.request();
@@ -99,7 +107,7 @@ class BrowserUseAdapter {
       handle.documentGeneration = await this._documentGeneration(handle);
       return handle;
     } catch (error) {
-      await browser.close().catch((closeError) => this._reportFailure('open-cleanup', closeError));
+      await this._closeBrowser(browser, 'open-cleanup');
       throw error;
     }
   }
@@ -628,10 +636,33 @@ class BrowserUseAdapter {
 
   async close(handle) {
     if (!handle?.browser) return;
-    await handle.browser.close().catch((error) => this._reportFailure('browser-close', error));
+    await this._closeBrowser(handle.browser, 'browser-close');
     handle.disconnected = true;
   }
 
+  // browser.close() returns once Chromium's browser process exits, but its renderer/GPU helpers
+  // can outlive it (puppeteer launches Chromium detached, so they share its process group), and
+  // its crashpad handler daemonizes into a group of its own still holding the stdio Chromium
+  // inherited. Either one keeps this process's end of that stdio open: orphaned helpers pile up
+  // and a Node process that should exit never does. Reap the group, then drop our end.
+  async _closeBrowser(browser, operation) {
+    const child = typeof browser.process === 'function' ? browser.process() : null;
+    await browser.close().catch((error) => this._reportFailure(operation, error));
+    this._reapBrowserProcess(child, operation);
+  }
+
+  _reapBrowserProcess(child, operation) {
+    if (!child || REAPED.has(child)) return;
+    REAPED.add(child);
+    if (Number.isSafeInteger(child.pid) && child.pid > 0) {
+      // ESRCH: the group is already empty. EPERM: macOS refuses a group whose members are all zombies
+      // (every member here is this user's Chromium, so it is never a foreign process).
+      try { process.kill(-child.pid, 'SIGKILL'); }
+      catch (error) { if (error?.code !== 'ESRCH' && error?.code !== 'EPERM') this._reportFailure(`${operation}-group`, error); }
+    }
+    for (const stream of child?.stdio || []) stream?.destroy?.();
+  }
+
   _reportFailure(operation, error) {
     const kind = String(error?.code || error?.name || 'unknown').slice(0, 128);
     this.logger?.warn?.(`[browser-use-adapter] ${operation} failed (${kind})`);