instar 1.3.1612 → 1.3.1613

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/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.