instar 1.3.656 → 1.3.658

package/upgrades/side-effects/idle-throttle-settle-gate.md

@@ -0,0 +1,37 @@
+# Side-Effects Review — Idle-monitor throttle settle-gate
+
+**Version / slug:** `idle-throttle-settle-gate`
+**Date:** `2026-06-24`
+**Author:** Echo (autonomous, 8-hour run)
+**Spec:** `docs/specs/idle-throttle-settle-gate.md` (review-convergence + approved)
+**Second-pass reviewer:** REQUIRED (touches the SessionManager idle/recovery path) — verdict appended below.
+
+## Summary of the change
+
+The safe slice of the false-rate-limit F3 residual (CMT-1785). The SessionManager idle-monitor emitted `rateLimitedAtIdle` (handing to RateLimitSentinel recovery) the instant `detectRateLimited(last-30-lines)` matched — a single glance, which false-fires on a stale/transient throttle line. Behind a DARK flag, the idle-monitor now gates that hand-off behind the SAME settle discipline the SessionWatchdog already uses (`evaluateThrottleSettle`: throttle present AND pane byte-identical across polls = the turn genuinely ended on the throttle). Strictly more conservative — it can only ever emit `rateLimitedAtIdle` LESS often, never more.
+
+Files modified:
+- `src/monitoring/rateLimitDetection.ts` — new pure `nextIdleThrottleAction` (a thin wrapper over the existing `evaluateThrottleSettle`; returns `'emit'`/`'wait'`/`'fall-through'`). No change to `evaluateThrottleSettle` or `detectRateLimited`.
+- `src/core/SessionManager.ts` — (a) new dark-flagged per-tick settle check inside `if (isActuallyIdle)` AHEAD of the first-idle-tick gate, so the pane is re-sampled every tick (load-bearing — see F1 below); (b) the first-tick legacy emit fenced to `detectRateLimited(recentOutput) && !this.idleThrottleSettleGate` (flag-off only); (c) per-session `idleThrottleSettle` Map + `idleThrottleSettleGate` field from new opt; (d) unconditional cleanup of the Map on `sessionComplete` (constructor) + on session-active.
+- `src/core/devGatedFeatures.ts` — new `idleThrottleSettleGate` DEV_GATED_FEATURES entry (`monitoring.idleThrottleSettleGate.enabled`, omitted ⇒ dev-live/dark-fleet).
+- `src/core/types.ts` — `MonitoringConfig.idleThrottleSettleGate?: { enabled?: boolean }`.
+- `src/commands/server.ts` — resolves the flag via `resolveDevAgentGate(...)` and threads it into the SessionManager opts.
+
+Files added:
+- `tests/unit/idle-throttle-settle-gate.test.ts` — 6 unit tests for `nextIdleThrottleAction` (every decision boundary: no-throttle→fall-through, first-sighting→wait, unchanged≥settleMs→emit, unchanged<settleMs→wait, pane-changed→wait+restart, transient-clears→fall-through).
+- `docs/specs/idle-throttle-settle-gate.md` (+ `.eli16.md`, convergence report).
+
+## Blast radius
+
+- **Flag OFF (the FLEET, by default):** byte-identical to legacy. The per-tick block is skipped entirely (`if (this.idleThrottleSettleGate)` false); the first-tick emit fires exactly as before; the `idleThrottleSettle` Map is never written (cleanup deletes are no-ops on an empty map). Confirmed by the adversarial reviewer + the existing watcher/quota suites unchanged.
+- **Flag ON (dev only):** the idle-path rate-limit hand-off is settle-gated. It only WITHHOLDS a spurious `rateLimitedAtIdle`; it never adds a kill/send/authority. RateLimitSentinel stays the recovery authority. The SessionWatchdog independently settle-gates the same class (the two emits are deduped by `RateLimitSentinel.report()`), so no double-recovery and no coverage gap.
+- **Multi-machine:** machine-local-by-design — per-process state about locally-running sessions; no replicated/proxied state.
+- **Migration parity:** dev-gated flag, `enabled` omitted from ConfigDefaults (no user default written) ⇒ no migration surface. No hooks/CLAUDE.md/skill/dashboard changes.
+
+## Rollback
+
+Flip `monitoring.idleThrottleSettleGate.enabled` false (or revert the commit) ⇒ legacy immediate emit. Fully additive and reversible; nothing irreversible ships.
+
+## Second-pass reviewer verdict
+
+Multi-angle spec-converge (adversarial + decision-completeness + lessons/integration internal lenses, + codex-cli:gpt-5.5 + gemini-2.5-pro external) over 2 rounds. Round 1 caught a CRITICAL functional defect (F1: the settle check ran only on the first idle tick → `'settled'` unreachable → flag-ON would emit recovery never, silently delegating to the watchdog) and a LOW map-cleanup leak (F2). Both fixed (per-tick re-sample; unconditional constructor cleanup) and verified RESOLVED + CONVERGED in round 2, with new adversarial checks (idle-kill starvation, flag-off regression, decision boundaries) clean. External minors (overstated safety claim; polling redundancy) folded into the spec. 130 unit tests green, no regression, clean typecheck. The one non-blocking note (per-tick wider capture cost when flag ON) is documented + deferred to the CMT-1785 unification. Verdict: APPROVED.

package/upgrades/side-effects/real-channel-absence-collect.md

@@ -0,0 +1,73 @@
+# Side-Effects Review — Real-channel collectMessages (absence proof over a live channel)
+
+**Version / slug:** `real-channel-absence-collect`
+**Date:** `2026-06-24`
+**Author:** Echo (autonomous, 8-hour run)
+**Spec:** `docs/specs/real-channel-absence-collect.md` (review-convergence + approved)
+**Second-pass reviewer:** REQUIRED (touches the LiveTestHarness verdict path) — verdict appended below.
+
+## Summary of the change
+
+The `LiveTestHarness` absence assertion (PR #1262) could only run against a fake driver,
+because the production `RealChannelDriver` had no `collectMessages`. This adds it, so the
+"no spurious background message" proof runs over a REAL Telegram/Slack channel. The whole
+risk of an absence proof is a silent **false PASS** (reporting "no spurious message" over
+an incomplete read), so every under-collection path is forced to BLOCK, never PASS.
+
+Files modified:
+- `src/core/LiveTestHarness.ts` — new `AbsenceUnverifiableError` (a sender's
+  read-incompleteness signal) + the absence-path catch now maps BOTH it and
+  `DriverCapabilityError` to **BLOCKED**; a plain `Error` stays a FAIL. The §5.3
+  pre-flight now treats any `absenceWindowMs != null` scenario as demo-only regardless of
+  its `safe` tag (a whole-history read must never touch a live channel).
+- `src/core/RealChannelDriver.ts` — new `collectMessages(surface, channelId, opts)`
+  delegating to the surface sender; raises `DriverCapabilityError` for a surface whose
+  sender has no collector; new optional `SurfaceSender.collectMessages`.
+- `src/core/TelegramLiveSender.ts` — `collectMessages`: polls `getHistory` across the
+  window, keeps ALL text versions per messageId (anti edit-laundering), skips non-finite
+  ids, clamps the window to 300s, and BLOCKS (AbsenceUnverifiableError) on a
+  marker-bounded full-page truncation (full page whose oldest entry is still after the
+  marker — so a reused demo topic is not wrongly blocked).
+- `src/core/SlackLiveSender.ts` — `collectMessages` (mirror): `oldest`-bounded read,
+  BLOCKS on `ok:false` (failed read) or `next_cursor`/full-page (truncation); new
+  `isAgentAuthored` helper matches `user` OR an injected `agentBotId` (a background nudge
+  may carry only `bot_id`) — applied to `collectMessages` AND `awaitReply` for parity;
+  optional `agentBotId` dep.
+
+Files added:
+- `tests/unit/realchannel-collect-messages.test.ts` — 22 unit tests: collect semantics,
+  late-nudge polling, anti-laundering, truncation→BLOCK (marker-bounded), reused-topic
+  no-mis-fire, Slack bot_id / ok:false / next_cursor, §5.3 absence-demo guard, and the
+  end-to-end harness PASS/FAIL/BLOCKED over a RealChannelDriver.
+- `docs/specs/real-channel-absence-collect.md` (+ `.eli16.md`, convergence report).
+
+## Blast radius
+
+- **Production runtime:** none. `collectMessages` is reachable ONLY via
+  `LiveTestHarness.run` → `RealChannelDriver`, constructed per-request in the live-test
+  route and the `instar dev` runner. No sentinel, gate, scheduler, or request path calls
+  it (verified by the scalability + integration reviewers).
+- **Existing callers:** unchanged. `RealChannelDriver`'s constructor signature is
+  untouched; `collectMessages` is a new instance method. The harness's `!driver.collectMessages`
+  BLOCKED path still fires for FAKE drivers (RealChannelDriver now routes per-surface
+  "unsupported" through the typed error instead). `awaitReply`'s new `bot_id` matching is
+  additive — unset `agentBotId` → byte-identical prior behavior (existing tests green).
+- **Multi-machine:** machine-local-by-design — a live channel read happens on the serving
+  machine against that channel's live history; no replicated/proxied state.
+
+## Rollback
+
+Fully additive and revertible: drop the three `collectMessages` method bodies, the
+`AbsenceUnverifiableError` class + its catch clause, the §5.3 `absenceWindowMs` predicate,
+and the `agentBotId` dep. No config defaults, hooks, CLAUDE.md template, migration, or
+dashboard surface touched, so no Migration Parity obligation. Reverting the commit is
+sufficient; nothing ships dark or irreversible.
+
+## Second-pass reviewer verdict
+
+Multi-angle spec-converge (6 internal lenses + codex-cli:gpt-5.5 + gemini-2.5-pro across
+3 rounds) converged with zero material findings in the final round. Round 1 surfaced 5
+material false-PASS holes (truncation, edit-laundering, Slack `bot_id`, Slack `ok:false`,
+§5.3 safe-bypass) — all fixed + tested. Round 2 surfaced 1 material (Telegram full-page
+guard mis-firing on a reused demo topic) — fixed marker-bounded + tested. Round 3
+verified resolution. Standards-Conformance Gate: 0 flags all rounds. Verdict: APPROVED.