instar 1.3.374 → 1.3.376

package/upgrades/side-effects/sentinel-stale-uuid-fallback.md

@@ -0,0 +1,75 @@
+# Side-Effects Review — Sentinel stale-uuid fallback + last-writer-wins bridge
+
+**Version / slug:** `sentinel-stale-uuid-fallback`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `pending (Phase 3 review agents)`
+
+## Summary of the change
+
+Two-layer fix for the 2026-06-06 false-escalation incident (echo-api-errors: 6
+futile resume nudges against an actively-answering session; echo-exo-3-0: false
+"no jsonl growth after 6 attempts over 22m" escalation at 02:26 PDT):
+
+1. `SessionManager.setClaudeSessionId` + the `/hooks/events` route guard change
+   from write-once to last-writer-wins, so the claudeSessionId record follows
+   conversation-UUID rotation (fresh respawn / `claude --resume`).
+2. `RateLimitSentinel.readJsonlBaseline` + `CompactionSentinel.readJsonlBaseline`
+   degrade a stale uuid (recorded transcript missing on disk) to the existing
+   newest-jsonl heuristic instead of returning null (which made recovery
+   verification permanently unable to succeed).
+
+## Decision-point inventory
+
+- Bridge update condition: `session.claudeSessionId !== payload.session_id`
+  (route) / identical-id no-op (manager). Both sides tested.
+- Sentinel baseline resolution: exact-uuid file exists → exact (unchanged);
+  uuid recorded but file missing → newest-jsonl fallback (NEW); no uuid →
+  newest-jsonl (unchanged). All three arms tested.
+
+## 1. Over-block
+
+Nothing new is rejected. The bridge accepts strictly MORE updates than before
+(rotations were previously dropped). The sentinels accept strictly MORE
+verification evidence than before.
+
+## 2. Under-block / residual risk
+
+- **Sibling false-positive on the fallback arm:** in a multi-session project
+  root, the newest jsonl can belong to ANOTHER session, so a genuinely-stuck
+  session with a stale pointer could be falsely marked "recovered" when a
+  sibling produces output. This is the SAME accepted risk profile as the
+  pre-existing no-uuid arm, it only applies while the pointer is stale (layer 1
+  re-freshens it on the next hook event, typically within seconds on an active
+  session), and the failure mode it replaces — guaranteed false escalation +
+  6 wasted nudge-refires on healthy sessions — is strictly worse. A falsely
+  "recovered" stuck session is still backstopped by ActiveWorkSilenceSentinel.
+- **Stale event flip-back:** a late-arriving hook event from a dying old
+  conversation could briefly flip the pointer backwards; the next event from
+  the live conversation flips it forward again, and all consumers re-resolve
+  per call (no cached snapshot), so the effect is transient.
+- Sessions that emit no hook events (none expected — the reporter fires on
+  every tool use/stop) keep whatever pointer they have; the sentinel fallback
+  covers them.
+
+## 3. Level-of-abstraction fit
+
+The rotation fix lives at the single bridge chokepoint both consumers share
+(`setClaudeSessionId` + its one route caller). The degrade-not-fail fix lives
+inside each sentinel's existing `readJsonlBaseline`, the single resolution
+point per sentinel; codex/gemini framework arms are untouched (they never used
+the uuid path). No migration needed: the fix is pure server code; existing
+stale records self-heal on the first post-deploy hook event per session.
+
+## Rollback
+
+Single revert of the PR restores write-once + null-on-missing exactly (no
+state-shape changes, no config, no new files).
+
+## Blast radius
+
+Server-side only. No agent-installed files, no hook templates, no config
+defaults, no CLAUDE.md template changes → no Migration Parity obligations.
+Consumers of `claudeSessionId` (session resume save, reaper guards,
+TopicResumeMap, sentinels) now see a FRESHER value — the value they were
+always designed to expect.

package/upgrades/side-effects/topic-operator-polling-bind-inc2e.md

@@ -0,0 +1,62 @@
+# Side-effects review — Topic Operator polling-path auto-bind (Know Your Principal #898, increment 2e)
+
+## What this change does
+Closes the auto-bind gap #909 documented: the adapter long-poll (no-lifeline)
+ingress path never bound the verified operator. The bind now lives at the
+`onTopicMessage` seam in `wireTelegramRouting` (src/commands/server.ts) — the
+convergence point BOTH ingress paths reach — so a no-lifeline install learns its
+operator too. Three coordinated pieces:
+
+- `wireTelegramRouting` gains a late-bound `getTopicOperatorStore` parameter
+  (the `getHubDeps` precedent in the same function) and an additive bind block
+  early in the callback: an AUTHENTICATED + AUTHORIZED sender is recorded as the
+  topic's verified operator.
+- `AgentServer.getTopicOperatorStore()` — public read-only accessor so the seam
+  resolves the server's OWN store instance at message-time.
+- `TopicOperatorStore.setOperator` idempotency guard: an identical record skips
+  the disk write (both paths re-bind per message; unchanged = pure read).
+
+## The load-bearing security property
+The seam fires for unauthorized senders too — the lifeline path only skips its
+own bind, it does not drop the message. So the `isAuthorizedSender` check INSIDE
+the seam bind is load-bearing: without it, an unauthorized group member could
+seat themselves as operator (the cross-principal "Caroline" bug). The
+integration Caroline replay proves the refusal — an unauthorized sender with
+`firstName: "Caroline"` cannot displace the bound operator.
+
+## Why the SAME store instance (the lost-update hazard)
+`TopicOperatorStore` caches its map in memory (`this.cache`). A second instance
+on the same file would hold a divergent cache: a record written through one
+instance disappears from the other's next full-map save. The original Inc-2e
+scout suggested constructing a fresh store inside the callback — that design is
+REJECTED here for exactly this reason. Instead the seam resolves
+`AgentServer.getTopicOperatorStore()` late-bound (module-level `_agentServerRef`
+assigned right after construction; the server is built long after routing is
+wired). The integration no-clobber test pins the invariant.
+
+## Blast radius (hot path — reviewed carefully)
+- **Additive + fail-soft.** The bind block is wrapped in try/catch; a getter
+  error, store error, or missing uid logs and falls through — message routing
+  is never affected. Proven by unit tests (getter throws / setOperator throws /
+  null store → handleCommand still runs).
+- **Pre-construction window.** Messages arriving before `_agentServerRef` is
+  assigned bind nothing (getter → null). Fail-safe: no binding means "unknown",
+  never a wrong operator. Lifecycle test covers the transition.
+- **Lifeline double-bind.** On the lifeline path both the routes-side bind
+  (#909) and the seam bind run — same instance, same record; the new
+  idempotency guard makes the second a no-op read.
+- **Disk-write reduction (behavior change, benign).** `setOperator` with a
+  byte-identical record no longer rewrites the file. Callers only ever read the
+  returned record or the store state — both unchanged. Existing store tests
+  (12) stay green; 2 new tests pin both sides (identical skips, changed
+  writes).
+- **No new route / config key / dependency.** `wireTelegramRouting` is now
+  exported (test seam only; no runtime caller change beyond the two existing
+  callsites gaining the getter argument).
+
+## No-allowlist trust model (unchanged, documented)
+`isAuthorizedSender` semantics are #909's: with no `authorizedUserIds`
+allowlist, every authenticated sender is accepted, so the operator is the
+most-recent authenticated sender. Consistent with the existing trust model;
+the uid is Telegram-authenticated, never a content name
+(`TopicOperatorStore.setOperator` enforces that by construction, #904).

package/upgrades/topic-operator-polling-bind-inc2e.eli16.md

@@ -0,0 +1,56 @@
+# ELI16 — Remembering the boss on the simpler phone line too
+
+## The one-sentence version
+The agent now writes down "this is the verified boss of this chat" no matter
+which of its two message pipes the boss's message arrived through — before, one
+pipe did this and the other forgot.
+
+## The backstory
+We've been closing a real security hole: an agent on a shared computer slowly
+started treating a *different real person* (call her Caroline) as its boss. The
+fix was a filing cabinet that records, per chat, who the verified boss is —
+decided ONLY by the verified ID of whoever actually sent the message, never by a
+name typed in a document. The last step (increment 2d) made the cabinet fill in
+automatically — but only on the agent's MAIN message pipe (the relay most of the
+fleet uses). A simpler setup, where the agent talks to Telegram directly without
+the relay, still never filled in the cabinet. That was safe (an empty cabinet
+just means "I don't know," never a wrong answer), but it meant some agents never
+learned who their boss was.
+
+## What this change adds
+Both pipes eventually flow through one shared doorway in the code (the
+`onTopicMessage` seam). This change puts the "write down the boss" step at that
+doorway, so it runs no matter which pipe delivered the message. Two careful
+details:
+
+1. **The doorway still checks the allowed list.** The main pipe lets messages
+   from non-allowed people *through the doorway* (it just refuses to bind them
+   earlier) — so the doorway check is load-bearing. Without it, an outsider in
+   the group could seat themselves as boss — the exact Caroline bug. We test
+   this with a literal unauthorized "Caroline" message and prove nobody gets
+   written down.
+2. **One cabinet, not two.** The cabinet keeps a copy of its contents in memory.
+   If the doorway opened its OWN second cabinet on the same file, the two copies
+   could silently overwrite each other's entries. So the doorway asks the server
+   for its existing cabinet (resolved late, because the server is built after
+   the doorway is wired) — same instance, no lost entries. A test proves an
+   entry written one way survives an entry written the other way.
+
+## A small bonus fix
+Since both pipes now re-write the boss on every message, the cabinet learned to
+notice "this is exactly what I already have" and skip the disk write — a
+re-delivered or repeated message is now a pure read instead of a pointless file
+rewrite.
+
+## Why it's safe
+- Wrapped so any failure is logged and swallowed — recording the boss can never
+  break message handling.
+- Before the server finishes booting, the doorway just skips the step (no
+  cabinet yet = nothing written = fail-safe).
+- On the main pipe both the old write (increment 2d) and the new doorway write
+  run — same cabinet, same record, harmless.
+
+## What's deliberately left for next time
+Nothing in this family — the operator-binding loop is now closed on every
+ingress path. The remaining Know Your Principal work is elsewhere (per-agent
+credential isolation, Phase 3).