instar 1.3.32 → 1.3.34

package/upgrades/side-effects/notify-on-stop-layer-b.md

@@ -0,0 +1,34 @@
+# Side-Effects Review — Notify-on-Stop, Layer B (gate-fed unjustified-stall notice)
+
+**Spec:** docs/specs/NOTIFY-ON-STOP-SPEC.md (approved: true) — Layer B of two. Layer A (autonomous-run-ended notice) shipped in a prior PR.
+
+When the UnjustifiedStopGate (shadow/enforce) classifies a stop as unjustified-but-unblockable (`continue` in `shadow` — the gate wants to continue but shadow can't block, so the session silently stalls) or ambiguous (`escalate`), an UNATTENDED session can go quiet mid-task and the user never hears about it. Layer B turns those specific classifications into ONE coalesced heads-up.
+
+## What changed
+- `src/monitoring/StopNotifier.ts` (new) — thin DECISION layer: `isNotifyWorthyStop` (shadow+continue OR escalate; everything else silent) + attended-gate (unattended/autonomous only, default) + per-session dedup (30-min cooldown) + master enable (default ON). Delivery is delegated to an injected `escalate` sink.
+- `src/commands/server.ts` — constructs a dedicated `SentinelNotifier` (telegramEscalation **on** — distinct from the housekeeping sentinel notifier, which stays default-off) reusing the lifeline-topic `sendConsolidated` transport + a JSONL log; wraps it in a `StopNotifier`. Null when telegram isn't wired or config disables it.
+- `src/server/routes.ts` — the `/internal/stop-gate/evaluate` route computes `autonomousActive` (via `getHotPathState`) and, after the authority decision, calls `ctx.stopNotifier?.maybeNotify({ sessionId, mode, decision, autonomousActive })`. Fire-and-forget; never affects the gate decision or the HTTP response.
+- `src/server/AgentServer.ts` — accepts + forwards `stopNotifier` to the routes ctx.
+- `src/core/types.ts` — `monitoring.notifyOnStop?: { enabled?, unattendedOnly?, cooldownMs? }`.
+- Tests: `StopNotifier.test.ts` (21 — both sides of every decision boundary, attended-gate, dedup window/expiry/per-session, master gate, throwing-sink safety) + `stop-notifier-wiring.test.ts` (6 — route→notifier→sink→server→AgentServer chain, guards the PR#334 dead-code failure mode).
+
+## Signal vs authority
+The Stop-hook router is a dumb thin client; the decision to ALARM the user lives server-side in StopNotifier, where the gate decision + attended-state + dedup ledger all exist. StopNotifier adds NO blocking authority — it's a delivery decision only. It never changes the gate's `decision`.
+
+## Near-silent compliance
+Default-on is the deliberate exception Justin explicitly asked for ("tell me why it stopped"), and it is tightly bounded: only two genuinely-stuck decision classes, only unattended sessions, at most once per session per 30 min, coalesced into one message on the single lifeline topic. Routine turn-ends (`allow`), blocked-and-continued (`continue` in enforce), continue-ceiling (`force_allow`), and fail-open are all silent. A single config flag (`monitoring.notifyOnStop.enabled=false`) kills it with no redeploy.
+
+## Over/under-notify
+- OVER: a shadow-mode `continue` could occasionally be a gate misjudgment (the CONTINUE_CEILING exists because the authority can be wrong). Mitigated by attended-gate + 30-min dedup; the alternative (a silent autonomous stall) is exactly what Justin wants eliminated.
+- UNDER: when the gate is `off` (no evaluate call) there's no Layer B notice — but Layer A still covers autonomous terminal exits, and the gate runs in `shadow` on real agents.
+
+## Migration parity
+Default-on works WITHOUT any config key present (`enabled !== false` ⇒ true when undefined), so existing agents get it on update to this version with no migrateConfig step. The wiring is server-side; no agent-installed-file change.
+
+## Rollback
+`monitoring.notifyOnStop.enabled=false` (instant, no redeploy) or revert the 6 files + 2 tests.
+
+## Tests / verification
+- Tier 1 unit: StopNotifier.test.ts (decision matrix both sides + gates).
+- Wiring-integrity: stop-notifier-wiring.test.ts (no dead code).
+- Tier 3 live: test-as-self before merge — drive a synthetic shadow+continue on an autonomous session through the real route and confirm the lifeline-topic heads-up fires once (and a routine `allow` stays silent).

package/upgrades/side-effects/telegram-adapter-multi-instance.md

@@ -0,0 +1,61 @@
+# Side-Effects Review — TelegramAdapter multi-instance isolation + Message-type extension (PR 2a)
+
+**Spec:** `docs/specs/MENTOR-LIVE-READINESS-SPEC.md` §Fix 2b "Implementation surface" items
+1-2 + round-2 integration F1 (converged, approved). PR 2 of the staged build, part a.
+**Change:** Make `TelegramAdapter` safe to run as a second (non-primary) instance in one
+process, and expose the Telegram fields the a2a spoof-defense needs. **Ships dark** — no
+caller passes the new options yet; the new Message fields are additive-optional.
+**Files:** `src/messaging/TelegramAdapter.ts`, `tests/unit/telegram-adapter-multi-instance.test.ts` (new).
+
+## What changed
+
+1. **Constructor opts `{ subDir?, suppressLifelineAutoCreate? }`** (3rd param, optional). When
+   `subDir` is set, the four per-bot state files (registry / message-log / poll-offset /
+   attention) live under `{stateDir}/{subDir}/` via a new `botStateDir`. The PRIMARY bot
+   (no `subDir`) gets `botStateDir === stateDir` → **paths are byte-for-byte unchanged**.
+2. **`suppressLifelineAutoCreate`** — `start()` skips `ensureLifelineTopic()` when true, so a
+   non-primary bot can't create a second Lifeline topic in the chat.
+3. **Message-type extension** — `message.from.is_bot?: boolean` + `message.sender_chat?` added
+   to `TelegramUpdate`. These are the structural inputs to the a2a user-spoof defense (a
+   human typing an `[a2a:…]` marker has `is_bot:false` and no `sender_chat`).
+
+## The seven questions
+
+1. **Over-block.** N/A — no gate. The only behavior gate is `suppressLifelineAutoCreate`,
+   default false (primary unaffected).
+2. **Under-block.** The reviewer-flagged collision (two adapters sharing
+   `telegram-poll-offset.json` → `poll()`'s cross-token detection fires continuously) is
+   eliminated: non-primary state is namespaced. Test asserts the two adapters share NO
+   state-file path.
+3. **Level-of-abstraction fit.** The isolation is at construction (one place), not scattered
+   per-callsite. `botStateDir` is the single source for per-bot paths.
+4. **Signal vs authority.** N/A.
+5. **Interactions — THE risk, and how it's bounded.** This file runs Echo's own (primary)
+   Telegram — the channel to the user. The change is built so the primary path is
+   **identical** (when `subDir` is undefined, `botStateDir === stateDir`). A dedicated test
+   asserts the four primary paths are byte-for-byte the historical `{stateDir}/...` values,
+   and the existing TelegramAdapter suites (71 tests across 5 files) pass unchanged — the
+   regression guard for "did I break my own comms." The new code only branches when `subDir`
+   is set, and nothing sets it yet (dark). Media/dashboard dirs still resolve off `stateDir`
+   inline — NOT isolated — which is fine: the reviewer flagged only the four constructor
+   state files, and the mentor bot (the only future `subDir` user) does no media/dashboard.
+6. **External surfaces.** None. No routes, no config consumed yet. The Message-type fields
+   are additive-optional (every existing reader ignores them).
+7. **Rollback cost.** Trivial — revert restores the 2-param constructor; no data, no migration
+   (the primary never wrote to a subDir).
+
+## Testing
+
+- `tests/unit/telegram-adapter-multi-instance.test.ts` (3 tests): **primary paths byte-for-byte
+  unchanged** (the load-bearing safety assertion); subDir namespaces all four state files +
+  shares no path with primary + creates the sub-dir; `suppressLifelineAutoCreate` recorded
+  (false default for primary).
+- Regression: existing Telegram suites (`TelegramAdapter`, `telegram-format-wireup`,
+  `telegram-adapter`) + the PR-1 `AgentTelegramComms` suite — 71 tests, all green.
+- `tsc --noEmit` clean.
+
+## Migration parity
+
+None — additive constructor option + additive optional Message fields. No agent-installed
+file change, no config consumed yet. PR 2b wires `sendAgentMessage` + the recipient handler;
+PR 3's config/migration is per the spec's §Migration parity.