instar 1.3.1649 → 1.3.1650

package/upgrades/side-effects/mobile-console-device-signin.md

@@ -0,0 +1,102 @@
+# Side-Effects Review — Owner phone opens the console without the dashboard PIN
+
+**Version / slug:** `mobile-console-device-signin`
+**Date:** `2026-11-03`
+**Author:** `echo`
+**Second-pass reviewer:** `independent subagent (see below)`
+
+## Summary of the change
+
+Tier 2 (touches sign-in and credentials). An owner's paired iPhone can open the agent console without typing the dashboard PIN. The app enrols a second Secure Enclave key (the presence key, which signs only after Face ID / Touch ID / the passcode) with a proof of possession, asks for a single-use server challenge, signs it with that key, and receives a 60-second single-use ticket bound to the device and the signed Host. The console page redeems the ticket once at a public route for exactly the token `/dashboard/unlock` returns (never the operator session). New: `src/server/mobileConsoleTicket.ts`, three allowlisted device routes, `POST /dashboard/console-ticket` (exact-path bearer exemption), `DeviceRecord.presenceKey` + `setPresenceKey`, config switch `mobilePairing.consoleTicket.enabled` (default on), `dashboard/console/ticket-model.js` and a boot step in `console.js`, a CLAUDE.md line rewrite + migration, an amendment note in `mobile-device-keys.md`. App: `PresenceKey.swift`, `ConsoleSignIn.swift`, `ConsoleView.swift` rewrite (non-persistent store for device-key agents, origin-guarded injection, one-shot script, one-time purge), `AppLock` keeps its authenticated `LAContext`. Size: about 15 files, ~900 LOC including tests. Effort: 5 spec review rounds (cap 6), one commit attempt planned.
+
+## Decision-point inventory
+
+- Presence-key enrollment: device, owner, local TLS, switch, valid key format, proof of possession, set once — **add**, invariant.
+- Challenge / mint: device, owner, local TLS, switch, challenge single-use and bound to device+Host, presence signature — **add**, invariant.
+- Redeem: local TLS, switch, ticket single-use + Host-bound, device still active owner (registry + ledger + person), throughput limit on unknown tickets only — **add**, invariant.
+- App plan (token / ticket / PIN) — **add**, invariant; every failure falls back to today's PIN box.
+- Bearer-gate exemption for `POST /dashboard/console-ticket` — **add**, exact method + path.
+
+---
+
+## 1. Over-block
+
+- A legitimate owner whose phone has no passcode, or whose presence key was deleted by removing the passcode, gets the PIN box (409 → "pair again" note). Intended.
+- A lease move of a shared tunnel hostname between mint and redeem (within 60 s) answers 401 → PIN box. Rare and safe.
+- A Host rewrite by a front (`httpHostHeader`) would make every redeem 401 → PIN box. Instar's fronts pass the Host through (pairing and multi-route already depend on it).
+- Behind the tunnel all remote callers share the loopback address, so the 10/min per-address limit on unknown tickets is effectively global; a known ticket is judged before the limit, so the operator is never blocked by it.
+
+## 2. Under-block
+
+- The token handed to the console outlives a revocation that happens while the console is open, until the screen closes or the API token is rotated (same as a PIN-unlocked tab). Tracked as feedback `fb-d588d77a-cf8` (device-bound console session).
+- The server cannot verify the presence key's Secure Enclave origin or `.userPresence` policy (no App Attest); an attacker controlling the app process before first enrollment could enrol a software key. Same attacker could read a typed PIN.
+- The phone passcode stands in for the PIN (`.userPresence` accepts it). Stated in the spec.
+- A third-party local proxy that accepts plain HTTP and forwards over loopback passes `arrivedOverLocalTls`; the app only ever posts to `https`, and this is the same limit device signatures already accept.
+
+## 3. Level-of-abstraction fit
+
+Reuses the PIN unlock's console credential and storage path (the console stores the token exactly as after a PIN unlock), the device authenticator for the signed requests, `arrivedOverLocalTls` for transport, the device registry + key ledger + person resolution for revocation. A device-bound session would be the deeper fix and sits at the bearer-gate layer; it is out of this change's scope by the brief and tracked as feedback.
+
+## 4. Signal vs authority compliance
+
+Every gate is a cryptographic or exact check (signature, single-use secret, registry status, transport), the hard-invariant class `docs/signal-vs-authority.md` exempts from the judgment requirement. The audit log is a record, never a gate; a failed write is reported through DegradationReporter and does not affect the answer.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No judgment points. All decision points are invariants (spec "Decision points touched" table), each with a deterministic fallback to today's PIN box.
+
+## 5. Interactions
+
+- `authMiddleware`: one new exact-path exemption placed beside `/dashboard/unlock`; the route is also registered before the gate, so the gate never sees it. GET on the path still needs a bearer (tested).
+- `deviceAuthenticator`: three new allowlist rows (JSON bodies, `active` only); the shared per-device rate limit and replay set apply as for every device route. Mint replay safety does not depend on the replay set (single-use challenges).
+- `/dashboard/unlock` and its PIN budget: untouched. The console still falls back to it.
+- Device revocation: the redeem re-reads registry + ledger, so revocation wins without a hook in the revoke route.
+- PostUpdateMigrator: the new line rewrite composes with the earlier Tailscale and word-code rewrites (different match conditions; tested with the word-code fresh text).
+
+## 6. External surfaces
+
+- New public HTTP route `POST /dashboard/console-ticket` (input: a 256-bit single-use secret; output: the API token).
+- Three new device routes visible to paired phones.
+- A new audit file `.instar/state/mobile-console-tickets.jsonl` (metadata only, rotated at 1 MB).
+- The iPhone app's console web view for device-key agents becomes non-persistent and purges a stale stored token once; on an older server the operator types the PIN on every console open.
+- CLAUDE.md wording for the mobile pairing section changes on update.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+1. **Leads with the primary action?** Yes: the console opens signed in; when it cannot, the PIN box is the first and only thing shown, as today.
+2. **Zero raw internals as primary content?** Yes: no ticket, challenge or key is ever rendered; the only new text is the app's plain note "Sign-in without the PIN needs this phone paired again (remove it, then pair)."
+3. **Destructive actions de-emphasized?** No destructive action added.
+4. **Plain language + phone width?** The change is the removal of a step on the phone; the console's existing phone layout is unchanged.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design, with markers in the spec's posture section: challenges and tickets live in one process's memory and redeem for that machine's own API token (hardware-bound-resource); the presence key sits on the device record of the machine the phone paired with, which is the only machine that can verify that phone (physical-credential-locality, consistent with `mobile-device-keys.md`); the audit log sits beside the per-machine registry. No user-facing notices. Durable state: only the presence key on the device record (follows the device record). Generated URL: `redeemOrigin` is the Host the phone itself signed for; a ticket redeemed elsewhere fails to the PIN box.
+
+## 8. Rollback cost
+
+Revert the server PR and ship a patch: routes vanish, apps fall back to the PIN box, memory-only tickets expire in 60 s, the `presenceKey` field becomes inert, the audit file is inert. The CLAUDE.md line on already-updated installs would overstate the feature until a later update; no data migration. The app ships separately (Echo, TestFlight); an app already on phones keeps the non-persistent store (which the device-keys spec required anyway).
+
+---
+
+## Conclusion
+
+The review and five spec rounds changed the design materially: a server-verifiable presence key replaced an app-side "owner verified" flag; single-use server challenges replaced a clock-based restart check; the redeem became Host-bound, TLS/loopback-only, switch-checked, and throttles only unknown tickets; enrollment gained proof of possession; the device-keys spec exception was made explicit and a device-bound session was filed as feedback. Clear to ship pending the second-pass concurrence below.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** independent second-pass subagent (claude-opus-5-5), 2026-11-03
+**Independent read of the artifact: concur**
+
+Concur with the review. Verified against the code: the redeem answers only `{ token }`; single-use deletes happen before any other check for challenges and tickets; the redeem re-reads registry, key ledger and owner role; transport is checked first; the bearer exemption is exact method + path; the app injection is a JSON literal guarded by `location.origin`, main frame only, removed after first navigation. One non-blocking gap raised and fixed before commit: after a passcode is removed and set again, iOS replaces the presence key while the app still believed it was enrolled, so every open silently fell back to the PIN box; the app now clears its enrolled flag on a `401` from the mint (other than an expired challenge), so the next open re-enrols, gets `409`, and shows the "pair again" note.
+
+---
+
+## Evidence pointers
+
+- **User-role live proof (real Chromium, real console page, throwaway agent on a real port, phone stand-in signing as the app does):** valid ticket on an owner phone → signed in, no PIN box, ticket gone from session storage; same ticket again → PIN box; unknown ticket → PIN box; no ticket → PIN box; ticket minted then phone revoked → PIN box; MSP phone → mint refused `403 owner-phone-required`. Result: PASS. The first run FAILED on the valid-ticket row and found a real defect: a phone paired on an address the device authenticator's strict host parser rejects (an IP with a port) could never redeem, because the redeem compared a null normalized Host. Fixed with one shared `normalHost` used on both sides, and pinned by a unit test. Limits: the proof ran over plain HTTP on loopback (which the redeem accepts as loopback), not through a TLS front; the iOS Secure Enclave paths (context reuse without a second prompt, invalidated context, passcode removal) run first on the operator's phone and each fails safe to the PIN box.
+- **App:** `xcodebuild test` on the iPhone 17 Pro simulator: 158 tests, 0 failures, including 10 new `ConsoleSignInTests`.
+
+- Spec: `docs/specs/mobile-console-device-signin.md`; convergence report `docs/specs/reports/mobile-console-device-signin-convergence.md`.
+- Tests: `tests/unit/mobile-console-ticket.test.ts`, `tests/unit/dashboard-console-ticket-model.test.ts`, `tests/unit/mobile-console-ticket-awareness.test.ts`, `tests/integration/mobile-console-ticket-routes.test.ts`, `tests/e2e/mobile-console-ticket-lifecycle.test.ts`; app `apps/instar-ios/Tests/InstarAppTests/ConsoleSignInTests.swift` (agent-home repo).

package/upgrades/side-effects/mobile-native-session-screen.md

@@ -0,0 +1,88 @@
+# Side-Effects Review — Native session screen (device-key session output and input)
+
+**Version / slug:** `mobile-native-session-screen`
+**Date:** `2026-11-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `independent subagent (see the end of this file)`
+
+## Summary of the change
+
+Operator request (Justin, Telegram topic 134088, 2026-11-03 22:01 and 22:55 PST): the chat's session button opens a native session screen in the app. Spec: `docs/specs/mobile-native-session-screen.md` (converged, approved).
+
+- `src/server/mobilePairingRoutes.ts`: two `DEVICE_ALLOWLIST` entries (`GET /sessions/<name>/output`, `POST /sessions/<name>/input`), active devices, `ownerOnly: true`, own buckets `session-output` (90/min) and `session-input` (12/min). New rule flags `ownerOnly` (403 `owner-phone-required` for a non-owner person) and `bucket` (named bucket). `deviceBucketOk` keys by device and bucket name (the media rule keeps its old key) and drops emptied windows once the map holds more than 64 keys.
+- `src/server/mobileSessionTerminalRoutes.ts` (new): a device-only router. Non-device requests call `next()` untouched. For an owner device: exact session resolution on this machine, `sid`/`machine` binding, async pane capture, credential redaction, plain-text filter, durable replay record, machine-wide input window, audit log, and a bounded pool lookup to name the machine of a session that is not here.
+- `src/server/AgentServer.ts`: mounts the router before the main routes when mobile pairing exists; wires state, capture, send, peer lookup, nicknames, secrets.
+- `src/core/PostUpdateMigrator.ts` + template: one CLAUDE.md bullet (sniff "native session screen") after the "Open session" bullet. `src/server/CapabilityIndex.ts`: one sentence.
+- Tests: unit, integration, e2e.
+
+Tier 2 (security-sensitive: new device access to session routes). Size: 1 new module (~290 lines), ~45 lines wiring/allowlist, ~25 lines migration/index, 3 test files (~520 lines). Effort: 6 spec rounds (the Tier-2 cap; later rounds each found real security gaps), 1 commit attempt so far.
+
+## Decision-point inventory
+
+- Device allowlist membership for the two routes — add — exact method/path/status rules.
+- `ownerOnly` — add — refuses non-owner persons in the authenticator; the router re-checks.
+- Named buckets, machine-wide input window — add — fixed counts, 429.
+- Plain-text filter, exact resolution, `sid`/`machine` binding, replay record — add — each can only refuse.
+- Credential redaction — add — changes only what a device sees.
+- "Where is this session" lookup — add — a signal shown to the operator; never grants access.
+
+## 1. Over-block
+
+A phone whose clock is far off is already refused by the existing ±60 s window. A session record that is `starting` is reachable; a tmux session Instar does not track is not (the dashboard can reach it; the phone cannot, deliberately). Typing more than 12 messages a minute across all phones gets 429. Text with control characters (pasted escape codes) is refused rather than cleaned server-side; the app strips them before sending. A session whose name was reused after the phone opened it answers 409 and must be reopened.
+
+## 2. Under-block
+
+Redaction is exact-match: a token split by a wrap or encoded differently can reach the owner's phone. Accepted: the owner's PIN unlock already returns the API token itself to the same phone. With multi-route off, a replay to another machine that holds the same device record and has taken over the paired host within 60 s is not caught by the per-machine replay record (accepted; requires a captured TLS request signed by the owner's Secure Enclave key, and the effect is the owner's own text typed once more). Other secrets a session prints are shown, as on the PIN dashboard.
+
+## 3. Level-of-abstraction fit
+
+Access control stays in the existing device authenticator (one new generic flag). Route behaviour sits in a dedicated router in front of the Bearer handlers, so the Bearer path is not touched. Pane capture and injection go through the existing SessionManager surfaces (`captureOutputAsync`, `sendInput`). The machine lookup reuses `poolPeerFetch` and `resolvePeerUrls`, as `GET /sessions?scope=pool` does.
+
+## 4. Signal vs authority compliance
+
+Every refusal is a deterministic boundary check (identity, role, exact id/name match, character class, exact digest, fixed counts), the structural-validation class `docs/signal-vs-authority.md` exempts. No heuristic gains blocking power. The machine lookup only words an answer; it never allows or refuses access.
+
+## 4b. Judgment-point check
+
+No competing-signals decision point is added; all points are classified `invariant` in the spec with reasons.
+
+## 5. Interactions
+
+- Mounted before `this.app.use(routes)`, after `authMiddleware`; Bearer requests fall through to the same handlers (integration and e2e tests prove it).
+- `deviceBucketOk` keeps the media rule's exact key (`deviceId`), so media chunk limits are unchanged.
+- `sendInput` for Codex sessions with Stage B on journals and may queue; `ok` is reported as "accepted", and the app says "Sent. It appears in the output when the session takes it."
+- The other mobile builder's console ticket may add allowlist rows nearby; rows are independent entries.
+- The coverage test that counts `conversationRef` rules is unaffected (the new rules are not conversation routes); the new unit test pins the two `ownerOnly` rules.
+
+## 6. External surfaces
+
+The iPhone app gains two device routes; answers are new and additive. Bearer callers see no change. Peers receive at most one `GET /sessions` per missing name per 3 s (15 s once found) and at most 8 names per phone per minute. New files: `logs/mobile-session-input.jsonl` (rotated at 2 MB), `state/mobile-session-input-replay.json` (3-minute entries).
+
+## 6b. Operator-surface quality
+
+No dashboard or approval-page file is touched. The operator surface is the iPhone app (separate repo, commit e112dac): plain-language errors, no raw codes, the session text first, the dashboard link only for an old server.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Machine-local by design (`hardware-bound-resource`): a session's pane exists on one host. A request bound to another machine, or a session found on another machine, gets a plain reason naming it from this machine's registry; nothing is proxied. The audit log and replay record are machine-local for the same reason. The sessions list uses the existing pool read. No notices, no generated URLs.
+
+## 8. Rollback cost
+
+Revert the PR. Phones then get 403 `device-not-allowed` and the app offers the dashboard. The audit log and replay file stay behind, harmless. The CLAUDE.md bullet stays true on an older server (it names the 403 fallback). No config or data migration.
+
+## Conclusion
+
+The change gives the owner's phone the session reading and typing the PIN dashboard already offers, with tighter limits than the dashboard (plain text only, rate windows, replay record, audit). Remaining exposure is within what the PIN unlock grants. Clear to ship after the second-pass review.
+
+## Second-pass review (if required)
+
+**Reviewer:** independent general-purpose subagent (Claude Opus 5.5), read-only, given the artifact and the diff.
+**Independent read of the artifact: concur**
+
+No way was found for a non-owner, revoked, unsigned or credential-less request to read or type: device requests must match an allowlist row, pass the signature and ledger-revocation check, and are refused as non-owners in the authenticator and again in the router. Non-device requests fall through `next()` to the unchanged Bearer handlers. Typed text is filtered for control characters, and the durable replay record (keyed on the canonical signed string) is written before typing and fails closed. All refusals are structural. One loose claim (emptied bucket windows are dropped only past 64 keys) was corrected above.
+
+## Evidence pointers
+
+- Spec and report: `docs/specs/mobile-native-session-screen.md`, `docs/specs/reports/mobile-native-session-screen-convergence.md`.
+- Tests: `tests/unit/mobile-session-terminal.test.ts`, `tests/integration/mobile-session-terminal.test.ts`, `tests/e2e/mobile-session-terminal-alive.test.ts`.
+- Feedback filed: fb-8e2a2b9c-99c (Bearer input raw name), fb-7b984fff-335 (async injection).

package/upgrades/side-effects/operator-needs-first-screen.md

@@ -0,0 +1,87 @@
+# Side-Effects Review — Anything that needs the operator is on the first screen, counted, and linked
+
+**Version / slug:** `operator-needs-first-screen`
+**Date:** `2026-11-03`
+**Author:** `Echo`
+**Second-pass reviewer:** `independent subagent, see below`
+
+## Summary of the change
+
+Tier 2, because it adds a rule to the outbound gate. Spec converged in two rounds. New: `dashboard/console/needs-model.js`, `src/core/operatorSurfaceReferral.ts`, two test files. Changed: Home's `combineNeeds` and `headline`, `loadHome`, seven pages (lead marker, Costs card, Development approval button, Agents switch position, alarm action), page copy, the tone gate's rule tables and prompt, the outbound route's signals, and the CLAUDE.md template plus its migration.
+
+## Decision-point inventory
+
+- `B22_SURFACE_REFERRAL` — add — advisory tone-gate rule, LLM-judged, anchored by a signal.
+- `combineNeeds` / `headline` — modify — display only, more rows counted; "Checking in" until sources answer.
+- `getOnce(…, soft403)` — add — a 403 on a Home source does not sign the operator out.
+
+---
+
+## 1. Over-block
+
+The rule can nudge a message that merely mentions a page. It only applies when the detector fires, the prompt lists carve-outs and favours false negatives, and a nudge can be overridden with a reason. The cost of a true nudge is one round trip. An agent with no browser overrides with a stated reason. Automated senders and sentinel redrives never see it: the signal is only raised for a sender that can react.
+
+## 2. Under-block
+
+A referral phrased outside the detector's words gets no signal, so no nudge. Rendering confirmation is a self-report, recorded as one; the gate cannot see a browser. The floor catches its vocabulary and the registered states; a new need phrased differently relies on the side-effects question. A console on another machine does not see `merging`, `approvals` or `secrets` for the machine that holds them, filed to feedback.
+
+## 3. Level-of-abstraction fit
+
+The list is one pure module beside the page models and reuses their builders. The gate rule feeds the existing authority rather than running beside it. The first version put a receipt store and browser tool next to the gate; review cut them as more machinery than the problem earned.
+
+## 4. Signal vs authority compliance
+
+Reference: `docs/signal-vs-authority.md`. The detector is a pure signal with no I/O and is deliberately not in `GateSignalDetectors`, whose hits count as leaks on the outage path; a test pins that. The tone gate is the one authority and the rule's disposition is advisory.
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+B22 is a judgment point within a floor: a detector anchors it and the LLM decides by meaning whether this is a real referral. No static heuristic decides anything.
+
+## 5. Interactions
+
+- B21 covers multi-step procedures and carves out a single link tap. B22 covers a referral missing its link or words. The two do not compete: a one-tap ask with link and words passes both.
+- A nudge plus the existing pending-advisory correlation means a revised resend is credited automatically. Render confirmation specifically needs the complied flag.
+- Home's new reads add load every 30 seconds: about ten small reads, with the four feedback reads every fourth tick and only where the merge watcher answers. Each source has one in-flight read.
+- The refresh place-keeping from the previous PR covers Home's page repaints unchanged.
+- `surfacedNeeds` keeps last good rows for two minutes when a read fails.
+- Live count: Home's count on this agent rises because real needs now count. That is the intended effect and could feel like a jump on first look.
+
+## 6. External surfaces
+
+Operator-visible: the Home count and rows, page leads, wording. Agent-visible: one new nudge and a CLAUDE.md section. No route shape changes, no new stored state.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+1. **Leads with the primary action?** Yes, and now enforced: 18 of 18 browser runs show the action on the first screen with no scrolling.
+2. **Zero raw internals as primary content?** Rows use page wording, with no identifiers. Secret rows carry the label only, never the drop token, pinned by a test.
+3. **Destructive actions de-emphasized?** No destructive action added. The spending card links out, and the alarm card's action is constructive.
+4. **Plain language + phone width?** Screenshots read at 390x844, no sideways scroll on any page in the run.
+
+## 6c. Agent Proposes, Operator Approves
+
+`dashboard/console/mandates.js` only gains a lead marker on its existing approvals block, and Home gains a row that links to it. (1) The operator still approves a pre-filled request and constructs nothing. (2) The authority text is unchanged, authored by the server from structured data. No approval flow, field or wording changed.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+Mixed, stated source by source in the spec. `accounts` is proxied-on-read through `scope=pool`. `merging`, `approvals` and `secrets` are machine-local today, the same reach as their pages. The gate is stateless per message. One-voice and topic transfer are unaffected.
+
+## 8. Rollback cost
+
+Revert and release. No migration to undo beyond a CLAUDE.md paragraph, which is harmless if left.
+
+## Conclusion
+
+Clear to ship after the second pass. The registry wording ships separately on the operator's answer.
+
+## Second-pass review (if required)
+
+Concern raised, then resolved. Independent reviewer: a queued reply redriven by the delivery sentinel could be held by B22, and the recovery policy treats any 422 as final, so it would never deliver. Resolved: a send whose delivery id matches a real queue row gets no B22 signal, pinned by an integration test both ways (a made-up id buys nothing). Precision items also fixed: the quote check was quadratic on long text (now linear and bounded), apostrophes no longer count as quotes, a 200 with the wrong shape counts as failed rather than "nothing waiting", and the conditional feedback source no longer holds the headline at "Checking in". Clean on the reviewer's other checks: the complied flag reaches the signal before the authority runs, a failed source never reads as "All quiet", secret rows carry no token. Concur after these fixes.
+
+## Evidence pointers
+
+Real judge (Haiku tier via the Claude CLI), five sample messages: a bare referral and a link-and-words message without confirmation get the nudge, the same message with confirmation passes, a report of the agent's own work passes. "Check the page if you like" was nudged, a borderline call the agent can override. The rule's text is added only for a flagged message, so the benchmarked prompt template and its saved benchmark are unchanged, pinned by the existing mirror test. `tests/unit/console-needs-first-screen.test.ts`, `tests/unit/operator-surface-referral.test.ts`, `docs/specs/reports/operator-needs-first-screen-convergence.md`. Browser proof ran through a proxy that refused all writes; the stop latch was not touched, no enable or rollback route was called, and the dashboard PIN was never read or used.
+
+## Class-Closure Declaration (display-only mirror)
+
+- **`defectClass`** — the agent-authored rule "Operator-Surface Quality rule 1" was enforced only by a written attestation. Not a prompt defect; the fix is enforcement added beside it.
+- **`closure`** — `guard`: `tests/unit/console-needs-first-screen.test.ts`.

package/upgrades/side-effects/recommended-services-choices.md

@@ -0,0 +1,50 @@
+# Side-Effects Review — recommended services, step 1: saved choices
+
+**Tier 2.** Spec: `docs/specs/recommended-services.md`, approved by the operator on 2026-11-03. About 25 files. Spec review used all 6 rounds and did not converge by the round rule. The operator chose to proceed, with the last fixes reviewed during the build. The second-pass reviewer below covers that for this step.
+
+## Summary
+
+Adds the signed choice ledger, its replicated store, read and no routes, legacy decline import, and retirement of the two old offers. Sends no offers. This is part of rollout step 1, not all of it. Still to come in step 1: the ACT-115 owner-check fix, the migration-complete flag, moving door and Tailscale steps out of the CLI, and the delivered-first-result trigger. The yes route, catalog, recipes and offers follow in later steps. All are tracked by commitment CMT-031.
+
+## 1. Over-block
+
+The evaluator and `/features/:id/surface` now refuse `cloudflare-tunnel` and `git-backup`. Until offers go live, nothing suggests those two features. Both are default on, so few agents ever saw these suggestions. A no without the PIN is refused, which leaves an owner with no PIN configured unable to record one; `checkMandatePin` answers 503 there.
+
+## 2. Under-block
+
+The agent can read the PIN, so a deliberately hostile agent could record a no. The operator accepted this limit until owner proof ships. A local file edit could also alter the ledger; signatures are checked only for peer rows.
+
+## 3. Level-of-abstraction fit
+
+A separate ledger, for reasons in the spec: `FeatureRegistry` state is local, erasable, and overwritten by bootstrap. It reuses the established replicated-store shape and machine signatures.
+
+## 4. Signal vs authority
+
+No brittle check gains blocking authority over messages or actions. The fold decides nothing yet except what the route reports. Refusing retired offers is an exact id match. See `docs/signal-vs-authority.md`.
+
+## 5. Interactions
+
+The store is enabled only where the coherence journal is live, so it never advertises a capability with no applier, and an explicit `enabled: false` is honoured. Old peers don't register the kind and ignore it.
+
+## 6. External surfaces
+
+Two new routes. A new CLAUDE.md section via template and migration. No outbound messages. No operator-facing action is added beyond the PIN route, which has no dashboard surface until step 2; no flow sends anyone to it before then.
+
+## 7. Multi-machine posture
+
+Replicated through the `recommendedServices` store, registered in the coherence registry, `rotateKeep: 0`. **It depends on the coherence journal, which is dev-gated, so on the fleet today choices stay on one machine.** Journal replication must also be enabled, which is explicit-only. `GET /recommended-services` reports `replicating` from those real states, not from a hook being attached. Own rows are re-sent at boot, so nothing written while it was off is lost. Offers must not go live on a multi-machine agent while this is false; the spec's rollout now states that. Rows verify under the writing machine's identity key. An unverifiable row is not accepted now and is re-read at next boot. Single machine: in backup `includeFiles`.
+
+## 8. Rollback cost
+
+Revert the release. The ledger file and journal rows stay inert, and return to use on re-upgrade. Older code offers the two legacy features again through their triggers, as the spec states.
+
+## Second-pass review
+
+**Concern raised, then fixed.** The independent reviewer found that replication wouldn't work on the fleet while the text claimed it would, that a failed legacy import could stop boot, that the store overrode an explicit off switch, and that this artifact understated what step 1 still needs. All four are addressed above. A re-check found `replicating` could read true with nothing replicating; it now reads the store and replication switches. The reviewer checked wiring order, signing, the merge fold, backup paths and journal kind lists and found them clean. Live replication between two real machines has not been run.
+
+## Test corrections from the first CI run
+
+Test files only, no runtime change, so this commit did not go back to the second-pass reviewer.
+
+- `tests/unit/capabilities-discoverability.test.ts`: the new route file is added to the list the check scans. Without it the capability entry read as a dead entry.
+- `tests/e2e/discovery-evaluator.test.ts`: this test never enabled the feature. Its consent record had an empty `dataImplications`, the registry refused it, and the refusal went unchecked. The feature stayed `interested`, and the test passed only because that lower priority pushed it past the 10-feature cap. Retiring two offers freed room and exposed this. The record is now valid and the test asserts that the transition succeeded.

package/upgrades/side-effects/rerouted-lifetime-active-process.md

@@ -0,0 +1,63 @@
+# Side-Effects Review — expired rerouted sessions release capacity
+
+## Summary of the change
+
+Tier 2 session lifecycle repair under the approved `docs/specs/june15-headless-spawn-reroute.md`. The configured hard lifetime is supposed to end a rerouted one-shot and record a timeout. On the operated host, `dashboard-console-default` passed its 480-minute limit while the session manager repeatedly printed “Killing”; durable `logs/reap-log.jsonl` instead recorded `skipped:active-process`, leaving the session running and the subscription lane at 6/6. This patch gives only the rerouted-session monitor a private capability to pass process-activity KEEP checks after it rechecks the saved lane and elapsed lifetime at the termination boundary. Other KEEP reasons still apply. The log now says “Killed” only after termination succeeds.
+
+## Decision-point inventory
+
+The existing decision is whether a rerouted interactive one-shot has passed its saved hard deadline. The monitor and termination boundary both check that fact. A new private capability affects only `active-process`, `main-process-active`, and `process-uninspectable` reasons; it cannot be supplied through the public `terminateSession` method. Normal sessions, unexpired reroutes, and other termination reasons use the previous guard path.
+
+## 1. Over-block
+
+An expired rerouted one-shot with an active tmux child was previously always retained, defeating the lifetime and leaving capacity occupied. A real `ReapGuard` unit test covers the active child and active main-process signals and now expects `killed/rerouted-lifetime`. The existing hard-lifetime test had no installed guard, which is why it missed the production failure.
+
+## 2. Under-block
+
+The patch intentionally allows an active process to be stopped at its explicit hard deadline. It does not bypass protected sessions, standing sessions, recovery, pending injection, relay lease, recent user interaction, open commitment, active subagent, or structural long work. A second real-guard test verifies a recent user message still blocks termination. The private symbol, literal reason, lane, completion mode, positive finite lifetime, valid start time, and elapsed-time check all must agree before the process-activity bypass applies.
+
+## 3. Level-of-abstraction fit
+
+The session manager already owns the hard-lifetime monitor and termination guard. The fix stays there, rather than changing the global ReapGuard or raising the host-wide session cap. It uses the same private termination entry point and durable session state as other lifecycle authorities.
+
+## 4. Signal vs authority compliance
+
+The printed “Killing” line was a misleading signal: it preceded the guarded termination result. The durable reap log showed the actual `skipped:active-process` decision. The patch moves the message after success and keeps the termination guard authoritative. The new capability is not inferred from a log; it is minted by the monitor and independently checked against the saved session and clock.
+
+## 4b. Judgment-point check
+
+No model or operator decision is replaced. The configured 480-minute limit is an existing deterministic policy. Timeout still produces the existing degradation report and job retry semantics only after termination succeeds.
+
+## 5. Interactions
+
+A rerouted one-shot that reaches its hard limit may be stopped even if its process tree is still active. That frees one subscription slot for queued work, including the feedback executor. The job scheduler sees `killed` and records a timeout. If another KEEP reason applies, the session stays running and `reapBlocked` remains durably logged; the timeout line no longer claims it was killed.
+
+## 6. External surfaces
+
+`GET /sessions` reflects the real terminal state after a successful kill. The reap log remains the audit surface for a skipped termination. No API shape, Telegram format, GitHub permission, or credential access changes.
+
+## 6b. Operator-surface quality
+
+The operator can distinguish a completed hard-timeout kill from a blocked attempt. This addresses the observed repeated false “Killing” message and the feedback executor’s unexplained 6/6 admission refusal.
+
+## 7. Multi-machine posture
+
+A rerouted tmux session is machine-local. The existing lease-holder and local session state checks still run before termination. The private capability cannot be sent over the API or another machine. A peer observing the session after owner transfer remains subject to the same lease gate.
+
+## 8. Rollback cost
+
+Revert this small source and test change in a patch release. No stored schema, config, or migration changes. A session already killed at its hard deadline cannot be resumed automatically, which is the pre-existing specified timeout consequence.
+
+## Conclusion
+
+The live 6/6 cap is caused by a hard-lifetime attempt blocked by `active-process`; it is not a phantom counter. Focused real-guard unit tests (49 in file), build, and lint are the current local evidence. Full three-tier verification and CI remain required before shipping.
+
+## Second-pass review
+
+**Reviewer:** rerouted_lifetime_review
+
+Concur with the review. The module-private capability is accepted only for the literal timeout reason, saved rerouted lane and pattern mode, a finite positive limit, and an elapsed deadline. It bypasses three process-activity reasons; lease ownership and the other ReapGuard protections still apply. The real-guard expiry test fails on the old code, and the recent-message test checks a surviving higher-priority veto. The reviewer did not edit files or run broad tests.
+
+## Verification update — 2026-11-04
+
+The first exact-head merge-tree run at `552c8c492` passed all unit tests (57,053) and integration tests (5,507), but one general lifecycle E2E test failed among 3,747 E2E tests. The verifier correctly refused an isolation rerun because that test imports the changed session manager. A direct run of the same lifecycle file on this branch then passed all 10 tests. A separate PR's full verifier also failed that file at 09:00Z, so the first failure cannot yet be attributed to this patch. The full E2E suite is being rerun under the shared test limit; shipping still requires a green exact-head result and a live timeout receipt. This update changes no source or test behavior.

package/upgrades/side-effects/undated-resurfacer-e2e-wait.eli16.md

@@ -0,0 +1,5 @@
+# Plain overview: a test that checked too early now waits
+
+Instar has an automatic helper that brings forgotten to-do items back to attention. One end-to-end test starts a test server and then checks, after just three hundredths of a second, that the helper has already done its first pass. On a busy computer running many tests at once, the first pass sometimes comes a little later, so the test failed even though nothing was broken. That failure blocked an unrelated change, the new native session screen for the phone app, from merging.
+
+The test now waits for the first pass, checking every tenth of a second for up to ten seconds, and then makes exactly the same checks as before. Nothing in Instar itself changes. If the helper ever truly failed to run, the test still fails, just after ten seconds instead of at once.

package/upgrades/side-effects/undated-resurfacer-e2e-wait.md

@@ -0,0 +1,9 @@
+# Side effects: resurfacer e2e waits for its first run
+
+Test-only. tests/e2e/undated-action-resurfacer-lifecycle.test.ts waited a fixed 30 ms after boot and then required the first resurfacer run to have happened. On a loaded peer verifier (2026-11-04, PR 2707) the run came later, so the test failed with totalRuns 0; it passed when rerun on the Studio. The test now polls the status route every 100 ms, up to 10 s, until the first run is recorded, then makes the same assertions. No product code changes.
+
+1-8: no runtime surface; rollback is a revert.
+
+## Class-Closure Declaration
+
+- `unbounded-self-action`: closure `n/a`, test-only, with a bounded wait.