instar 1.3.1611 → 1.3.1613

package/upgrades/side-effects/locked-proof-driver.md

@@ -0,0 +1,72 @@
+# Side-Effects Review — locked-Mac proof driver and test-user setup scripts
+
+**Version / slug:** `locked-proof-driver`
+**Date:** `2026-11-02`
+**Author:** `Echo`
+**Tier:** 1 (maintainer scripts, no runtime source change, nothing runs without `--execute`). Size: 7 new files under `scripts/locked-proof/` (~750 lines), 1 test file. Effort: no spec rounds; first commit attempt.
+
+## Summary of the change
+
+The locked-Mac proof plan (`.instar/lanes/locked-mac-proof-plan-134088.md`, items M3 and M5) needs a driver for P12/P15 and repeatable throwaway-user setup. This adds them as scripts only. One change from the plan, per the brief for this work: the agent types the throwaway user's password through the remote-desktop viewer, instead of the operator typing it about 30 times. The password is generated by the setup script, never chosen by a person, kept in the agent vault (`locked_proof_user_password`, stored through `credential-store.mjs` with the value on stdin, Bitwarden first), and read once into the driver's memory. It is not the owner's password: the spec's "no agent ever handles it" concerns the owner's real password, which this run never touches (the test account is empty and throwaway). The user is created without a forced password change at first login (`pwpolicy -clearaccountpolicies`; the plan's `newPasswordRequired` step is dropped).
+
+Files: `lib.mjs` (cases, expected table, runner, verdict, password generator, attempt reset rule, target check), `driver.mjs` (real target: sudo against the proof user, the proof agents' HTTP API, the real viewer page through playwright-core with system Chrome), `create-proof-user.sh`, `pty-feed.py`, `stage-proof-agents.sh`, `configure-proof-agent.mjs`, `reset-attempts.py`, `remove-proof-user.sh`.
+
+## Decision-point inventory
+
+None in runtime code. The driver's verdict is a test-harness judgement recorded with its evidence; it gates nothing by itself (a passing record still goes through a normal PR to the proven-versions table).
+
+## Review follow-ups (independent review on #2598)
+
+1. Signals are owner-checked: `serverPid` asks `lsof -a -u instarproof` (only the proof user's listener), and `kill()` reads the pid's owner (`ps -o user=`) immediately before every signal and throws for anyone but `instarproof`. `assertProofTarget` now gets the real owner of each agent's listening process and of each agent directory, not a constant.
+2. `runCase` runs the case in try/finally: whatever throws, `target.recover()` resumes every pid the run SIGSTOPped, clears the guard-stopper and locks the proof session; a recovery problem or the error fails the case by name. `close()` runs the same recovery.
+3. `configure-proof-agent.mjs` and `reset-attempts.py` refuse without `--execute`, and refuse anything that does not resolve inside `/Users/instarproof` (the reset script's only other accepted root is a test root inside the system temporary directory named by `LOCKED_PROOF_TEST_ROOT`).
+4. Expectations without a measurement now fail as "not measured" instead of passing silently. Measured from the run's own samples: relock time after a transport drop (15.5/15.6, must be at least the 30 s resume window) and whether the password field is left dirty at the end (15.9, from the store's `dirty` flag, which blocks any later Enter). Lock calls against another session (12.12/12.13) have no observable source yet, so those two cases fail as "not measured" until one exists.
+5. Bitwarden: the agent's `credential-store.mjs` put the base64 item (which holds the password) on `bw`'s command line. Echo's copy on this machine now pipes it on stdin (`bw create item` / `bw edit item <id>` read the encoded JSON from stdin, per `bw --help`, version 2026.7.0). `create-proof-user.sh` refuses to run if the helper it would call still puts the item on the command line, so the Laptop's copy must be updated before setup. The password is on no command line in this flow: stdin to the helper, stdin to `bw`, the pty prompt to `sysadminctl` and `dscl`.
+
+## 1. Over-block
+
+None: no runtime path changes.
+
+## 2. Under-block
+
+- The verdict can only judge what it observes. "Lock call against another session" (12.12/12.13) is not directly observable from outside the helper; the driver records the marker outcome and leaves that sub-check to the helper's own audit rows, read at the sitting.
+- The loginwindow submission count is recorded as raw evidence (`loginwindowLines`); its log pattern is unverified until the sitting, so the verdict relies on the helper's `enterPendingAt` records for "no submission after close".
+- Timing of "immediately before Enter" depends on calibration; the plan's rerun rule (offset off by more than 500 ms) is applied by the person running the sitting from the recorded timestamps.
+
+## 3. Level-of-abstraction fit
+
+Maintainer tooling outside `src/`, driving the same surfaces an owner uses (viewer page, revoke route, PIN route). It adds no test-only hooks to the helper, so the helper under proof is byte-identical to the shipped one.
+
+## 4. Signal vs authority compliance
+
+Not applicable: no runtime authority. The scripts refuse to act on anything but the `instarproof` user running a `-lockedproof` build.
+
+## 5. Interactions
+
+- Uses `sudo -n` (passwordless sudo on the proof Mac) to signal only the proof user's processes and read its relock store. `reset-attempts.py` takes the helper's own `state.lock` and refuses while a duty is open.
+- `create-proof-user.sh` depends on `sysadminctl -password -` prompting on its terminal; if a macOS version does not prompt, `pty-feed.py` fails loudly ("never asked") after storing the vault value, and no user exists. Rerun with `--replace-vault`.
+- Starting the proof servers in the proof user's session needs that session to exist (the person's first login).
+
+## 6. External surfaces
+
+None for users or agents. A Bitwarden item "Instar locked-proof test user (<host>)" is created when setup runs.
+
+## 7. Multi-machine posture
+
+Machine-local by design: the proof runs on one Mac, against a user on that Mac.
+
+## 8. Rollback cost
+
+Delete the scripts. If setup was run, `remove-proof-user.sh --execute` deletes the user; the vault key is deleted by the agent.
+
+## Conclusion
+
+Adds the missing driver and setup tooling, with the agent typing the throwaway password so the operator's part is two permission grants and a few local actions. Tier 1.
+
+## Second-pass review (if required)
+
+Not required: no runtime gate, session lifecycle or messaging change.
+
+## Evidence pointers
+
+- `tests/unit/locked-proof-driver.test.ts`

package/upgrades/side-effects/locked-proof-test-build.md

@@ -0,0 +1,64 @@
+# Side-Effects Review — locked-screen test build script
+
+**Version / slug:** `locked-proof-test-build`
+**Date:** `2026-11-02`
+**Author:** `Echo`
+**Tier:** 1 (maintainer script + test, no runtime source change). Size: 2 new scripts (~170 lines), 1 new test file. Effort: no spec rounds, first commit attempt.
+
+## Summary of the change
+
+The locked-screen spec says P12 and P15 run "on a test build" that "alone compiles in a test proven-versions table; no environment variable, config key or route can reach it in dist". That build did not exist. This adds:
+1. `scripts/lib/locked-proof-build.mjs`: pure helpers (version naming, macOS major parsing, the table rewrite, the committed-table proof check).
+2. `scripts/build-locked-proof.mjs`: `git archive` of a committed revision into a scratch directory outside the checkout, rewrite of the scratch copy's `src/core/DesktopProvenVersions.ts` (one `PROOF-RUN-IN-PROGRESS <version>` row), version `<release>-lockedproof.<n>`, `npm run build`, `npm pack --ignore-scripts`, manifest with commit, macOS major, helper `sourceHash`, tgz SHA-256.
+3. `tests/unit/locked-proof-build.test.ts`, including a guard that every committed table row cites existing proof records for P12 and P15 and never the marker.
+
+## Decision-point inventory
+
+- The macOS-version admission decision (`provenVersion`) is unchanged. The test build only feeds it a different table in a scratch copy, which is the mechanism the spec names.
+
+## 1. Over-block
+
+None: no runtime path changes.
+
+## 2. Under-block
+
+- Someone could copy the marker row into the committed table by hand; the new unit test fails the suite in that case.
+- The test package could be installed somewhere other than the throwaway user. It is never published to npm and carries a distinct version; installation is a deliberate act by the proof setup scripts. The proof agent must run with auto-update off, or the updater would replace it with the latest release (handled by the setup scripts in the next PR).
+
+## 3. Level-of-abstraction fit
+
+A build-time source rewrite is exactly what the spec asks for (no env/config/route reaches the table). Kept as a maintainer script, not shipped runtime code.
+
+## 4. Signal vs authority compliance
+
+No decision logic added. The unit guard is a CI check on committed data.
+
+## 5. Interactions
+
+- `npm run build` in the scratch copy runs the normal build chain with `INSTAR_RELEASE_PRIVATE_KEY_PEM`, `INSTAR_RELEASE_PRIVATE_KEY_PEM_PATH` and `INSTAR_RELEASE_BUILD` removed from its environment, so the lock-file signer writes an unsigned lock-file (the scratch tree, a fresh `git archive`, has no `.instar-release-keys/`). A test build is never release-signed.
+- The scratch copy symlinks this checkout's `node_modules` for the build and removes the link before packing.
+- `tests/e2e/desktop-locked-lifecycle.test.ts` still asserts the shipped table is empty; unchanged.
+
+## 6. External surfaces
+
+None for users or agents. `scripts/` ships in the npm package, so the script is present in installs but does nothing unless run from a git checkout.
+
+## 7. Multi-machine posture
+
+Machine-local by design: a build tool run on one Mac for that Mac's macOS major.
+
+## 8. Rollback cost
+
+Delete the scripts and test. Nothing persists.
+
+## Conclusion
+
+Adds the spec's missing test build, plus a guard that the committed table can only hold proven rows. Tier 1.
+
+## Second-pass review (if required)
+
+Not required: no gate, session lifecycle or messaging change.
+
+## Evidence pointers
+
+- `tests/unit/locked-proof-build.test.ts`

package/upgrades/side-effects/locked-security-item-no-telegram.md

@@ -0,0 +1,78 @@
+# Side-Effects Review — locked-screen security item reaches an attention list without Telegram
+
+**Version / slug:** `locked-security-item-no-telegram`
+**Date:** `2026-11-02`
+**Author:** `Echo`
+**Tier:** 1 (small, reversible: a revert restores the previous behaviour exactly). Size: 5 src files changed + 1 new (about 150 lines), 3 new test files. Effort: no spec rounds (Tier 1), first commit attempt.
+
+## Summary of the change
+
+`AgentServer`'s `raiseSecurity` dependency for `DesktopLockedController` went only through `telegramAdapter.createAttentionItem`. With no Telegram adapter it logged a warning and returned `false`, so on an agent without Telegram the owner was never told that a Mac may still be unlocked (relock failed), that the relock record was unreadable, or that locked-screen access was turned off. The locked-Mac proof plan (topic 134088, P12 cases 12.8/12.11) needs this item to be raised within about 10 s on a test agent with no Telegram, and it is a real gap for any agent run without Telegram.
+
+Changes:
+1. New `src/core/LocalAttentionItems.ts`: a file-backed list (`state/local-attention-items.json`, 0600, atomic tmp+rename write), one row per id, a re-raise refreshes and reopens the row, bounded to 200 rows dropping the oldest closed rows first and never an open one. `raise()` returns `true` only when the row is on disk.
+2. `AgentServer`: the `raiseSecurity` closure becomes a private method `raiseLockedSecurityItem`. With Telegram: unchanged. Without: stores the item locally (HIGH, category security, source agent) and calls `mobilePairing.push.onHubPost` (best effort); returns `false` with a degradation report when the write fails. The store is constructed only when there is no Telegram adapter, and passed to the route context.
+3. `routes.ts`: `GET /attention`, `GET /attention/:id`, `PATCH /attention/:id` serve the local list when `ctx.telegram` is null and `ctx.localAttention` is set. Other attention routes (POST, lifecycle, clear, remote-ack) keep their 503 without Telegram.
+4. `mobilePairingRoutes.ts`: the notification title lookup `GET /mobile/attention/:id` falls back to the local list.
+5. CLAUDE.md template + `migrateClaudeMd` bullet (sniff `local-attention-items.json`).
+
+## Decision-point inventory
+
+- `DesktopLockedController` "told" decision (marks the relock record `reported`) — unchanged logic; its input (`raiseSecurity` result) is now honest on agents without Telegram (true only when stored).
+- No new gate, filter or block.
+
+## 1. Over-block
+
+None. Nothing is refused that was accepted before. Routes that answered 503 now answer 200 only when a local list exists (no Telegram).
+
+## 2. Under-block
+
+- Without Telegram, `POST /attention` still answers 503: an agent cannot queue its own items there. This change is about the owner seeing security items; the agent itself writing to the list is a separate question with no current user.
+- The phone push is best-effort; if APNs is not configured the item is still on the list and in the app.
+- The local list is not merged into `GET /attention?scope=pool` from peers that have Telegram (a peer's pool read calls this machine's `/attention`, which now answers with the local list, so it IS visible to Telegram peers' pool view).
+
+## 3. Level-of-abstraction fit
+
+The attention store living inside `TelegramAdapter` is the root cause; moving it out is a large refactor. This adds the smallest store at the same route surface, so readers (`GET /attention`, the app) need no new address.
+
+## 4. Signal vs authority compliance
+
+Signal only: the store records and reports. No blocking authority added.
+
+## 5. Interactions
+
+- `DesktopLockedController.sweep` retries an unreported `relock-failed` each sweep until `raiseSecurity` returns true; now it gets true on a no-Telegram agent after the first successful write, so `mark-reported` runs and the guard's record closes as before with Telegram.
+- `disable()` raises an item each time locked access is turned off; the row is reused (same id), so repeated disables refresh one row.
+- Mobile push dedupe key includes a timestamp, so a re-raise can push again; push budgets (2-minute fold, daily cap) still bound it.
+- No change when a Telegram adapter exists: `localAttention` is null and every route takes its old path.
+
+## 6. External surfaces
+
+`GET /attention` without Telegram changes from 503 to 200 with `surface: "local"`. Any client treating 503 as "no Telegram" now gets a list instead; the dashboard and the app already render an item list. CLAUDE.md gains one bullet.
+
+## 7. Multi-machine posture
+
+Machine-local by design: the security item concerns this Mac. Peers see it through their existing `GET /attention?scope=pool` fan-out, which calls this machine's `/attention`.
+
+## 8. Rollback cost
+
+Revert the PR. The leftover `state/local-attention-items.json` is inert. No migration.
+
+## Class-Closure Declaration
+
+- `unbounded-self-action`: closure `n/a`. No new self-triggered loop. The added local write and phone push run once per raise from the existing DesktopLockedController sweep, which stops raising a condition once `raiseSecurity` returns true (`mark-reported`); a failed write retries at the existing 10 s sweep cadence only while the condition is open. Each push passes the MobilePush per-device budgets and folding.
+
+## Conclusion
+
+Closes a real gap where a security warning was dropped on agents without Telegram, with no change for agents that have Telegram. Tier 1.
+
+## Second-pass review (if required)
+
+Not required: no block/allow, session lifecycle, gate or sentinel logic changes; this only gives an existing report a place to land.
+
+## Evidence pointers
+
+- `tests/unit/local-attention-items.test.ts`
+- `tests/integration/attention-local-without-telegram.test.ts`
+- `tests/e2e/locked-security-item-without-telegram.test.ts`
+- `tests/unit/PostUpdateMigrator-attentionWithoutTelegram.test.ts`

package/upgrades/side-effects/mobile-native-conversations-inc4.md

@@ -0,0 +1,115 @@
+# Side-Effects Review — Native app conversations, increment 4 (Slack conversations from the app)
+
+**Version / slug:** `mobile-native-conversations-inc4`
+**Date:** `2026-11-02`
+**Author:** `echo`
+**Second-pass reviewer:** `not run (--second-pass false, as instructed for this build)`
+**Tier:** 2 (spec-driven; inbound dispatch and a signed-record format). Size: 11 source files (~520 added source lines, one new route module) + 3 new test files (~560 lines). No spec review round (the spec was already converged and approved); commit attempts recorded in the PR.
+
+## Summary of the change
+
+Increment 4 of docs/specs/mobile-native-conversations.md (§4.9 Slack, §4.10 allowlist), behind the existing boot-read `mobilePairing.native.enabled` gate.
+
+- **List:** `GET /mobile/conversations` adds this machine's local Slack conversations (registry entries whose origin is not `replicated`): `{id: <negative durable id>, platform: "slack", title: label or "#<channel>" (+" (thread)"), lastActivity, lastPreview}`, merged on the same lossless cursor as app and Telegram rows (sort key `slack:<id>`). `?scope=pool` accepts peers' Slack rows (re-validated: negative safe integer). With `mobilePairing.slackOwnerUserId` unset the rows are withheld and the response says `slackOwnerUnset: true`.
+- **History:** `GET /mobile/chat/slack/:id/messages` (device, or the agent's Bearer token) merges the tail of `slack-messages.jsonl` (newest 5000 lines within 8 MiB), the adapter's in-memory ring, and the app-sent messages kept in the app conversation store under the registry's canonical key. App-sent rows carry `originVerified` (and their delivery state); rows typed in Slack and agent replies read `none`. Pages backwards by `(at, eventId)`.
+- **Send:** `POST /mobile/chat/slack/:id` follows §4.2: authenticate → look up (`MobileChatRequestStore`) → emergency stop skips the setting and rate limit → preflight (chat setting, 20/min, request-id age, `scanInbound`) → serving-lease check → token removal, credential signal → reserve → persist (fsync) with the signed origin and a **v2 receipt** → a copy in `slack-messages.jsonl` carrying the store `eventId` → stop/pause intercepts → the server's real Slack inbound dispatch with the operator as sender (`mobilePairing.slackOwnerUserId`, `threadline.ownerName`) and `appOrigin` → delivery event → mirror "📱 <owner> (from the app): <text with credential spans hidden>" → done. Boot recovery of an interrupted send is the existing `recoverStranded` (`op: send` with the canonical key).
+- **v2 receipt:** a Slack send path names a machine-local alias, so the receipt also signs the canonical key (`instar-app-receipt-v2`, fields `v: 2`, `conversationKey`). `verifyRecordedOrigin` requires, for a `slack:` record, a POST to `/mobile/chat/slack/-N` and a v2 receipt naming the record's key; a v1 receipt, a different key, or a non-Slack path reads `failed`. Non-Slack records are verified exactly as before (a v2 receipt on them must also name their key).
+- **Slack dispatch outcome:** `slackInboundDispatch` now returns `delivered | queued | refused` (previously `void`); the live and forwarded Slack paths ignore it. A message sent from the app gets ` (📱 signed)` (verified) or ` (📱 from the app)` appended to its tag by the server, after the sanitized name.
+- **Agent replies in the Slack log:** `handleSlackReply` now writes the agent's reply to `slack-messages.jsonl` (Slack never echoes the bot's messages), so the app's Slack history shows both sides. Inbound Slack rows gain `threadTs` when they sit in a thread.
+- **Config:** `mobilePairing.slackOwnerUserId` (optional, `U…`/`W…`). Never inferred.
+- **Awareness:** CLAUDE.md section "Slack conversations from the Instar app" (template + `migrateClaudeMd`, sniffed by heading); CapabilityIndex lists the two routes.
+
+## Decision-point inventory
+
+- Slack send preflight — add — invariant: the same content-free checks as the app/Telegram send routes; only exact authority tokens are removed; credential-shaped text is a signal.
+- Owner identity — add — invariant: a config field (`slackOwnerUserId`) that must also be an authorized user on the Slack adapter; never inferred from content.
+- Serving-lease check — add — invariant (as the Telegram chat route): refused before anything is saved.
+- Origin verdict for Slack records — modify — invariant cryptographic checks (v2 receipt).
+
+---
+
+## 1. Over-block
+
+- A machine that does not hold the serving lease answers `409 not-serving` before saving, as the Telegram route does; with the session pool on, a Slack conversation owned by another machine is still sent through this machine's dispatch only if this machine holds the lease (the dispatch then re-checks ownership through `SpawnAdmission`). No message is lost: nothing is saved on a refusal and the app keeps the text.
+- `slackOwnerUserId` unset or not an authorized Slack user ⇒ 503 with a plain reason. Intentional (spec: never inferred).
+- A thread conversation's history shows only rows that say they are in that thread; Slack log rows written before this change have no thread field, so older thread replies are not shown in a thread view (they still appear nowhere else either; Slack itself keeps them).
+
+---
+
+## 2. Under-block
+
+- History reads a bounded tail of `slack-messages.jsonl`; messages older than the newest 5000 lines are not reachable from the app (app-sent messages are, from the store, never rotated). Slack keeps its own full history.
+- **Slack ids are local to one machine (review fix).** Every Slack list row names the machine that serves it (`machine`), a pool list never includes another machine's Slack rows (a peer row with the same number would otherwise collapse onto this machine's row, or name a different conversation), and both Slack routes require the row's machine (`?machine=` on the read, `machine` in the signed send body): another machine answers 409 `wrong-machine` (with `servedBy`), none answers 400 `machine-required`, before anything is read, saved or sent. A Slack conversation is therefore only reachable through the machine that lists it; with several machines that is the one the phone is paired to.
+- Verification of a Slack record is relative to the canonical key: a workspace id that was `_` on one machine and `T…` on another yields two keys (two store files) for one channel; each record still verifies under its own key.
+
+---
+
+## 3. Level-of-abstraction fit
+
+Reuses the app conversation service (request store, store, verify, delivery events, boot recovery), `buildSignedOrigin`, the registry's canonical key, and the server's own Slack inbound dispatch (the same function the live and mesh-forwarded Slack paths run), so a message from the app gets the same session lookup, spawn admission, context and relay instructions as a Slack message. The bridge is a thin adapter over SlackAdapter with an interface small enough to stub in tests.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [ ] No — this change produces a signal consumed by an existing smart gate.
+- [x] No — this change has no brittle block/allow surface.
+- [ ] Yes — but the logic is a smart gate with full conversational context.
+- [ ] ⚠️ Yes, with brittle logic — STOP.
+
+No content check refuses a message. The added refusals are structural (feature setting, rate, request-id age, lease, configured owner identity); credential-shaped text only adds `credentialShaped: true` and is hidden in the mirror copy, never refused.
+
+---
+
+## 4b. Judgment-point check (Judgment Within Floors standard)
+
+No new judgment point. Credential-shape detection is the existing `detectOutboundCredential` signal (the spec's decision table classifies it as a judgment candidate whose floor never refuses).
+
+---
+
+## 5. Interactions
+
+- **Slack log readers:** PresenceProxy's Slack log check and the Slack compaction-resume path now also see the agent's own replies in `slack-messages.jsonl`. Both look for "did the agent answer after the user's last message"; seeing the reply is the correct answer (previously they only learned it through `onMessageLogged`). `slack-cli` search shows the replies too.
+- **slackInboundDispatch** return type change: callers `await`/`void` it and ignore the value; tsc and the Slack wiring tests pass.
+- **Tag:** the app mark is appended inside the bracket after `(uid:U…)`; the existing tag parser in sessions only reads `[slack:<channel>`.
+- **Mirror loop:** the mirror is posted by the bot; Slack does not deliver bot messages back as inbound, so it cannot re-enter dispatch.
+- **Emergency stop:** an app stop into Slack kills every running session, exactly what a Slack "emergency stop" does.
+
+---
+
+## 6. External surfaces
+
+Two new device routes (allowlisted for active devices: `POST /mobile/chat/slack/-N`, `GET /mobile/chat/slack/-N/messages`, both requiring the list row's `machine`), Slack rows in the conversation list, a new optional config field, a new receipt version in stored records (replicated; an older machine reading a v2 Slack record cannot verify it and reads `failed` for a Slack path — such records only exist once this version runs), a new message posted into Slack (the mirror) on each app send, and agent replies added to the Slack log. CLAUDE.md gains a section on update.
+
+- **iOS app:** must list `platform: "slack"` rows, send to `/mobile/chat/slack/<id>` with the row's `machine` in the body and read `/mobile/chat/slack/<id>/messages?machine=<row machine>`, show `slackOwnerUnset` as a plain hint, and show marks from `originVerified` (increment 5).
+- **Operator surface:** setting the owner id is done by the agent after the operator's yes in conversation (no PIN, no file editing by the operator).
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+- App-sent Slack messages: **replicated** in the app conversation store under the canonical Slack key (the existing `appConversations` replicated kind); the v2 receipt makes them checkable on any machine.
+- Slack rows in the list and Slack history: **machine-local BY DESIGN** (a Slack conversation id is minted per machine): the list carries only this machine's Slack rows even with `?scope=pool`, and the routes refuse any other machine's id.
+- Sending: on the serving-lease holder (where Slack inbound is dispatched).
+
+---
+
+## 8. Rollback cost
+
+Switch `mobilePairing.native.enabled` off: the Slack routes answer 503 and the list has no Slack rows (the conversation service is not built). Unsetting `slackOwnerUserId` hides Slack alone. Reverting the PR leaves stored Slack records with v2 receipts that an older version reads as `failed`/unknown (display only) and extra agent-reply rows in `slack-messages.jsonl` (harmless log rows). No data migration.
+
+---
+
+## Class-Closure Declaration (display-only mirror)
+
+Not applicable: no agent-authored-artifact defect. The mirror post fires once per operator app send (an external event), never on a timer or its own output.
+
+---
+
+## Second-pass review
+
+Not run for this build (`--second-pass false`, per the build instructions). The PR is the review surface.
+
+Review follow-up (Slack ids are per machine): independent reviewer — Concur with the review. The machine check runs before any read or send in both routes; the query is inside the signed path and the body field inside the body hash; the agent read works with ?machine=; pool lists drop peers' Slack rows; the CLAUDE.md text matches (it now names the 400 too).

package/upgrades/side-effects/origin-config-unknown-not-missing.eli16.md

@@ -0,0 +1,16 @@
+# Why bug-topic messages from Mama PC failed, in plain words
+
+Every few seconds, each machine re-reads its own settings file so it knows where to send Telegram messages. Bug topics live in a separate Telegram group, and the settings say which one.
+
+Mama PC sometimes gets so busy that its server freezes for 10 to 30 seconds. When that happens, the settings read takes longer than its 2-second limit and is thrown away. The code then behaved as if the settings had no bug group at all, and refused messages to bug topics with "no messaging config issuesChatId". That was false: the setting was there the whole time.
+
+Those refused messages were saved for a retry. But the retry step only trusts a small set of "definitely not sent" answers, and this refusal was not one of them. So it marked them "may already be delivered" and never sent them. They were lost without anyone being told.
+
+After this change:
+- If the settings can't be read, the refusal says so honestly ("could not read config", with the reason), and it is marked as safe to retry.
+- The retry step recognises this refusal, and the two older ones (the misleading "no bug group" one, and the bare "display authority unavailable" one that hit a message on the Studio today), as "definitely not sent", so the message goes out once the settings read again. It still passes the usual tone check and duplicate check, and it still expires after 6 hours.
+- The server log now says why a settings read failed, so the next time this happens the cause is written down.
+
+Nothing changes about the safety rule that a bug-topic message is never sent to the main group by mistake.
+
+Why Mama PC freezes is a separate problem and is reported on its own.

package/upgrades/side-effects/origin-config-unknown-not-missing.md

@@ -0,0 +1,38 @@
+# Side-effects review: an unreadable config is "unknown", not "missing"
+
+Tier 1. 5 runtime/test files plus artifacts, about 120 lines. One review round.
+
+## Change
+1. `TelegramOriginBoot.ts`: the 5-second config refresh used to end in `catch { snapshot = null }`. The snapshot then fed `toWireParams` with `issuesChatId: undefined`, so a failed read surfaced as `IssuesChatNotConfiguredError` ("this process has no messaging config issuesChatId"). Now, with no snapshot, an issues-topic send throws `OriginConfigUnavailableError(reason)` instead, and the sender-display check throws the same error when the snapshot is stale. The refresh records a bounded, secret-free reason code and logs it once per change (and on recovery). `refresh()` itself is unchanged in what it accepts.
+2. `types.ts`: new `OriginConfigUnavailableError` (retryable, `reason`). Its message is still exactly `origin-display-authority-unavailable`, so existing string matchers keep working.
+3. `routes.ts` (`POST /telegram/reply` catch): this error now answers `503 {error:'origin-config-unavailable', reason, retryable:true, message}` instead of a generic 500.
+4. `OriginLegacy.ts`: `snapshotLegacyOrigin` treats two exact bodies on the latest attempt as definite non-delivery, the same way PR 2596 does for the boot beacon: that 503 body, and the 500 body `{"error":"issues-chat-not-configured: topic N belongs to the issues group…"}`. It also accepts the bare 500 `{"error":"origin-display-authority-unavailable"}` that earlier releases returned when config could not be read; that text is thrown only by display resolution inside `prepareBot`. All of these are thrown while a send is being prepared, before admission and before any network call.
+
+## 1. Over-block
+None added. A send that was refused before is still refused while config is unreadable; only the reason and status change. Main-group protection is unchanged: with no snapshot an issues topic is never translated to the main chat, and `authorize()` still requires a healthy snapshot.
+
+## 2. Under-block
+The underlying stall on a busy machine is not fixed here (see Interactions). Sends during a stall still wait; they are now retried instead of lost. A row with several attempts qualifies only if every earlier attempt was 401/404 (the table keeps only the latest body), which is the safe direction.
+
+## 3. Level-of-abstraction fit
+The misreport was produced where the snapshot is built, so it is fixed there; the HTTP mapping lives in the existing reply-route catch; the replay proof lives in the existing replay check. No new layer.
+
+## 4. Signal vs authority
+The replay check is an authority (it lets a held message be sent). It is deterministic and narrow: exact bodies from our own reply route, exact key sets, a 1 KiB cap, and a body relayed from another machine (`relayedFromHolder`) is rejected (tested). Replayed rows still pass the legacy tone review, content dedup and the original 6-hour deadline.
+
+## 5. Interactions
+- PR 2596 edits the same lines of `snapshotLegacyOrigin` (boot-beacon 503). The two compose: both are "latest attempt carries an exact pre-dispatch body". Whichever lands second rebases into one helper.
+- The relay script already queues any 5xx ("Queued for recovery"), so the new 503 needs no script change.
+- The stalls behind this (server event loop blocked for 10–30 s, then the lifeline restarting it after 60 s unresponsive) are a separate problem and are reported separately.
+
+## 6. External surfaces
+`POST /telegram/reply` returns 503 with a new error code for this case instead of 500. Callers that treat 5xx as retryable (the relay script) behave as before. Messages refused this way are now delivered later instead of silently dropped.
+
+## 7. Multi-machine posture
+Machine-local by design: each process reads its own config and imports its own queue. This matters most on standbys, which send through the lease holder but prepare locally.
+
+## 8. Rollback cost
+Revert the commit. Rows already replayed were delivered once; nothing to repair.
+
+## Second-pass review
+Concur with the review. Both refusals are raised in `prepareBot` (wireParams, then display) before admission. Every failure after dispatch is a `TelegramOriginHoldError`, and the adapter does not fall back to a second send. There is no partial multi-chunk send, because chunks are children of one sealed operation built after translation. A holder's relayed refusal carries `relayedFromHolder`, which fails the exact key check. The relay script stores the body untruncated (the 1024 cap applies only to the event payload), and both bodies are well under 1 KiB; an oversized body fails safe. `OriginConfigUnavailableError` is matched by `instanceof` only in the reply route; every other caller matches the unchanged message. Main-group protection is intact. Logged reasons are fixed codes only. The integration test's wait was lengthened so a loaded machine does not make it flaky.

package/upgrades/side-effects/pool-rows-use-local-machine-name.eli16.md

@@ -0,0 +1,5 @@
+# One machine, one name, everywhere on the dashboard
+
+Each machine running the agent keeps its own list of the other machines and what to call them. Those lists can disagree. Today one Mac was called "Mac M5 Pro" in the Studio's list, while that same Mac called itself "Mac Lan". When the dashboard gathered information from every machine, some rows used the name the Studio knows and others used the name the Mac gave itself. So the Machines page said "Mac M5 Pro" while an alert on the home page said "Mac Lan: Remote Desktop needs its Mac permission again", and it looked like two different machines.
+
+Now, when the dashboard gathers rows from other machines, it names each machine using the list of the machine you are looking at, and only falls back to the machine's own name if it has none. Alerts whose title starts with the machine's own name get that start replaced with the same name. The result is that a machine has one name everywhere on a given dashboard. Which name is right is still a choice for the operator. A rename is still recorded only on the machine where it is made, so each machine's own dashboard follows its own list; making a rename reach every machine is a separate fix.

package/upgrades/side-effects/pool-rows-use-local-machine-name.md

@@ -0,0 +1,34 @@
+# Side-effects review: pool reads name each machine from THIS machine's registry
+
+## Change
+`src/server/routes.ts`, three pool merges (`GET /sessions?scope=pool`, `GET /jobs?scope=pool`, `GET /attention?scope=pool`): a peer row's `machineNickname` now comes from this machine's registry first (`machinePoolRegistry.getCapacity(id).nickname`), and the peer's self-reported name is the fallback (it was the other way round). For attention items, a title the peer prefixed with its own name (`"<own>: …"`) is re-prefixed with the registry name when the two differ.
+
+## Evidence
+On the Studio (2026-11-02) `GET /pool` named `m_a8048693…` "Mac M5 Pro" (the Studio's durable registry), while that machine's own attention items arrived as "Mac Lan: Remote Desktop needs its Mac permission again" with `machineNickname: "Mac Lan"`. The dashboard showed the same machine under two names (Machines page vs needs-you).
+
+## 1. Over-block
+None.
+
+## 2. Under-block
+Free text inside a body that names the peer is not rewritten. The registries themselves still disagree across machines (machine registry is not shared on a git-ignored registry); which name is correct is the operator's call. `PATCH /pool/machines/:id` updates only the local registry, so a rename applies to this machine's dashboard only (filed separately).
+
+## 3. Level-of-abstraction fit
+The merge is where rows from several machines are composed for one viewer; naming there keeps every page consistent without per-page fixes.
+
+## 4. Signal vs authority
+No decision logic; display data only. Routing uses `machineId`, unchanged.
+
+## 5. Interactions
+P17 coalescing keys on `sourceContext`, not title or nickname: unchanged. Rows from this machine are unchanged.
+
+## 6. External surfaces
+Pool API rows carry the viewer's name for a machine. A peer with no registry entry here keeps its own name.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+Each machine has one name across the Machines page, needs-you rows, sessions and schedule, so the operator never wonders whether "Mac Lan" and "Mac M5 Pro" are two machines.
+
+## 7. Multi-machine posture
+Proxied-on-read: each viewing machine names peers from its own registry. Registry convergence across machines is separate.
+
+## 8. Rollback cost
+Revert.

package/upgrades/side-effects/prompt-gate-settle-before-relay.eli16.md

@@ -0,0 +1,11 @@
+# Prompt Gate waits before telling you about a prompt (plain-English overview)
+
+When one of my sessions stops at a question on its screen (a yes/no confirmation, a menu), a part of Instar called Prompt Gate copies that question to your Telegram topic so you can answer it from your phone. Until now it did that the instant it saw the question.
+
+The trouble is that many of those questions get answered without you. When a session hits its account's usage limit, Instar moves it to another account; when Claude Code asks a low-level permission question, a safety floor answers it; sometimes the session is simply restarted. In each case you still got a message asking you to choose, about something that no longer needed you. On 2 November that happened twice in one minute, plus a separate notice saying "Prompt Gate is now active".
+
+What changes: after seeing a question, Prompt Gate now waits 45 seconds and looks at the session's screen again. If the question is still there, you get the message as before. If it's gone, or the session no longer exists, nothing is sent. If the screen can't be read, it sends anyway, so a question that really needs you is never dropped. The "now active" notice becomes one short line on the first real question instead of its own message.
+
+What you might notice: fewer of these messages, and a real one arrives about 45 seconds after the question appears. The wait can be changed or switched off with one setting.
+
+If the screen check itself fails, that counts as "can't tell", and the message is sent.

package/upgrades/side-effects/prompt-gate-settle-before-relay.md

@@ -0,0 +1,57 @@
+# Side-Effects Review — Prompt Gate waits before relaying
+
+**Version / slug:** `prompt-gate-settle-before-relay`
+**Date:** `2026-11-02`
+**Author:** `Echo`
+**Second-pass reviewer:** `independent reviewer subagent (see below)`
+
+## Summary of the change
+
+Operator report 2026-11-02 13:50 (topic 134088, with a photo): "I feel like [you] shouldn't be notifying for prompts that are handled automatically." At 13:42 two prompts from the operator's own session (a confirmation and Claude Code's weekly-usage-limit menu) were relayed, plus the standalone "Prompt Gate is now active" disclosure; both prompts were resolved without him (the session moved to another account).
+
+1. `src/monitoring/promptRelaySettle.ts` (new): `settleBeforeRelay(prompt, deps)` waits `settleMs`, then: session not alive → no relay; prompt anchors (option labels, else the raw text's last lines) found in the last 20 pane lines → relay; not found → no relay; pane unreadable or no anchor → relay.
+2. `src/commands/server.ts`: the relay branch calls it before Telegram/Slack relay, with `sessionManager.isSessionAlive` and `sessionManager.captureOutput`. A skipped relay is logged and resets the detector for that session.
+3. `src/core/types.ts`: `promptGate.relaySettleMs` (default 45000; 0 = immediate).
+4. `src/messaging/TelegramAdapter.ts`: the first-use disclosure is appended to the first relayed prompt as one line instead of a separate message.
+
+## Decision-point inventory
+
+- `settleBeforeRelay` — add — invariant: whether to send a notification about a prompt. Deterministic by design: it only suppresses a message when the live pane positively no longer shows the prompt or the session is gone; every uncertain case relays.
+
+## 1. Over-block
+
+A prompt answered by the operator at the terminal within 45 s is not relayed (correct). A prompt whose menu text is redrawn differently (labels reworded) would read as cleared and not relay; anchors are the detector's own parsed labels from the same pane, so a redraw of the same menu keeps them. A prompt pushed out of the last 20 lines by later output while still waiting is possible but unlikely for a blocking prompt (the session is stopped on it).
+
+## 2. Under-block
+
+A prompt that stays on screen but is being handled by another mechanism slower than 45 s is still relayed. The window is configurable.
+
+## 3. Level-of-abstraction fit
+
+The relay decision lives in the one server relay branch that both Telegram and Slack share, so both channels get it. The detector and classifier are unchanged.
+
+## 4. Signal vs authority compliance
+
+It never answers or blocks a prompt; it only decides whether to send a message, and fails toward sending. Reference: docs/signal-vs-authority.md.
+
+## 5. Interactions
+
+Auto-dismiss and auto-approve paths run before it and are unchanged. Relayed prompts arrive ~45 s later, so a reply relayed back targets a prompt that was confirmed still present moments before. Detector dedup/cooldown is reset on a skipped relay, as it is after a handled one.
+
+## 6. External surfaces
+
+Fewer Telegram/Slack messages; a ~45 s delay on genuine prompts; one less standalone message per topic.
+
+## 7. Multi-machine posture
+
+Machine-local by design (`hardware-bound-resource`: the prompt is on this machine's tmux pane, and only this machine can read it).
+
+## 8. Rollback cost
+
+Set `promptGate.relaySettleMs: 0`, or revert. No state.
+
+## Second-pass review
+
+Independent reviewer — Concur with the review. Argument types match (prompt.sessionName is the tmux name, as the auto-dismiss sendKey already uses); a prompt is dropped only when the session is gone or no anchor is in the pane tail, every uncertain case relays; a skipped relay resets the detector like the auto-approve path; the 45 s wait is per prompt and does not hold the event loop; the appended note is fixed text. Minor: the topic is marked disclosed before the send succeeds, unchanged from before.
+
+Follow-up: Local Verify flagged the pane-read catch for the silent-fallback rule; it now carries the marker explaining that an unreadable pane relays.

package/upgrades/side-effects/topic-names-through-lifeline.eli16.md

@@ -0,0 +1,9 @@
+# New topics show their real names on the dashboard
+
+When you create a topic in the agent's Telegram group, Telegram announces it with a small "topic created" note that carries the topic's name, and nothing else: no message text. On most of your machines the agent does not read Telegram directly. A small helper process (the lifeline) reads Telegram and hands each message to the agent's server. That helper threw away anything without text, so the "topic created" note, and with it the name, never reached the server. The dashboard then showed those conversations as "Conversation name unavailable", which is what you would have seen for several topics created today.
+
+Now the helper passes the name on whenever it sees one: from the "topic created" or "topic renamed" note, and also from ordinary messages, because Telegram attaches the topic's creation note to each message in a topic. So the topics created today will get their names the next time anyone writes in them, and new topics get their names straight away.
+
+Only the helper itself (which proves who it is with a secret) can set a name this way, so nothing else running on the machine can change what your topics are called.
+
+A follow-up marks two deliberate catches (a failed rename display update is only logged) so the check that looks for silently swallowed errors can tell they are intentional.

package/upgrades/side-effects/topic-names-through-lifeline.md

@@ -0,0 +1,39 @@
+# Side-effects review: topic names reach the server when the lifeline owns polling
+
+## Change
+1. `TelegramLifeline.processUpdate`: a topic-created or topic-renamed service message (no text) was dropped by `if (!msg.text) return;`. It is now passed on as a name-only forward (`text: ''`, `topicName`, `topicRenamed`, `nameOnly: true`). An ordinary message in a topic also carries the topic's name, because Telegram attaches the topic's creation message as `reply_to_message`; the lifeline now includes it as `topicName`.
+2. `POST /internal/telegram-forward`: after the existing lifeline-secret gate, a `topicName` is recorded with `TelegramAdapter.captureTopicName` only when the sender is lifeline-trusted and the request is not a mobile one. A name-only forward is acknowledged (`{ ok: true, nameOnly: true }`) and goes no further; an empty text without `nameOnly` is still a 400.
+3. `TelegramAdapter.captureTopicName(topicId, name, isEdit)`: the poller's existing capture logic, extracted so both paths share it. A creation name never overwrites a known name; a rename does and fires the existing rename handler. Names are trimmed and capped at 128 characters.
+
+## Evidence
+On 2026-11-02, five sessions on Mama PC showed as "Conversation name unavailable" on the dashboard. Four were topics the operator created in Telegram that day (135187, 135556, 135758, 135786); neither the Studio (which polls through its lifeline) nor Mama PC had their names, and the Studio's message log had their messages. The lifeline's `processUpdate` returned early on any update without text.
+
+## 1. Over-block
+None.
+
+## 2. Under-block
+A topic created while the server is down: the name-only forward is skipped, and the name arrives with the topic's next message (which carries the creation message). A topic whose messages never reach this machine stays unnamed here, as before.
+
+## 3. Level-of-abstraction fit
+The lifeline is the only component that sees the update; the adapter owns the name registry. Correct layers.
+
+## 4. Signal vs authority
+Display data only. The name is accepted only from a lifeline-proven sender (the same gate that decides sender identity), so a session cannot rename topics shown to the operator.
+
+## 5. Interactions
+The name-only forward returns before pairing-invite handling, message logging, sessions and the sentinel, so it can never be treated as a message. Older servers answer 400 to the name-only forward (empty text); the lifeline ignores the result. Older lifelines omit the fields; nothing changes.
+
+## 6. External surfaces
+Topic names appear on the dashboard and in alerts instead of "Conversation name unavailable" or numbers.
+
+## 7. Multi-machine posture
+The name is recorded on the machine whose lifeline polls (the lease holder). Other machines read it through the pooled topic list.
+
+## 8. Rollback cost
+Revert the commit. Names already recorded stay, which is harmless.
+
+## Class closure
+unbounded-self-action: n/a. One best-effort forward per topic service message received; no retry loop.
+
+## Follow-up
+The two rename-handler catches moved into `captureTopicName` carry `@silent-fallback-ok` (the no-silent-fallbacks ratchet reads 20 lines after each catch, and in the new position those lines include fallback wording from the next function). `session-lifecycle-phase-3-wiring` pins the new source shape.