instar 1.3.655 → 1.3.657

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.655",
+  "version": "1.3.657",
   "description": "Coherence infrastructure for self-evolving AI agents — on the Claude Code or Codex subscription you already have.",
   "type": "module",
   "main": "dist/index.js",

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-24T16:39:12.372Z",
-  "instarVersion": "1.3.655",
+  "generatedAt": "2026-06-24T22:34:53.907Z",
+  "instarVersion": "1.3.657",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {

package/upgrades/1.3.656.md

@@ -0,0 +1,68 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A shared safety helper that rescues sessions blocked by an AI-provider throttle was
+mis-firing: a session that had already FINISHED sits idle with the old throttle message
+still on its screen, so the helper kept trying to "rescue" a session that was simply
+done and pinged the user with *"the temporary server throttle should have cleared —
+please continue where you left off."* Because the helper is shared, the false alarm
+showed up fleet-wide (it was also seen on AI Guy).
+
+The fix makes a finished/killed session structurally incapable of being a rescue target:
+the helper now checks the session is still running at every point it can act (when it
+decides to rescue, before each retry, AND before the "did it respond?" check) and bails
+out silently if the session ended. When a session completes, the helpers stop watching
+it immediately. A separate noisy "rate limit" log that fired on harmless quota-meter
+hiccups is also quieted (it now only logs on a sustained problem).
+
+It also adds a reusable prevention capability: the user-channel test harness can now
+prove that NO unwanted background message (like the false throttle nudge) appears over a
+time window — so this class of "a background feature messages you by mistake" is caught
+by the ship gate before it reaches the fleet.
+
+## What to Tell Your User
+
+You should stop seeing phantom "throttle cleared, continue" messages that don't match
+anything actually happening in your session. Real throttles are still handled — genuine
+rescues still run and still tell you. Nothing you need to do; it takes effect on update.
+
+## Summary of New Capabilities
+
+- Finished/killed sessions can no longer trigger a false throttle/error recovery, and a
+  rescue whose session ends mid-flight stops silently instead of sending a stray
+  "still can't get through" message.
+- (Agent/dev) The live-test harness gained an absence-assertion: a scenario can drive a
+  real conversation and assert that no message matching a pattern arrives within a
+  window, with the result feeding the existing "is this done?" gate.
+
+## Evidence
+
+**Reproduction (observed incident, 2026-06-24, topic 28130):** the Mac Mini's Claude
+account was quota-walled, so its session for the topic finished. The finished session
+sat idle with a throttle line still on its terminal; the RateLimitSentinel read that
+stale scrollback, classified the done session as "throttled," and began resume attempts
+that produced repeated *"the temporary server throttle should have cleared — please
+continue where you left off."* nudges across every topic the Mini owned. Server logs
+corroborated the second trigger: 716 "rate limit" hits were almost entirely
+`QuotaCollector.collect.oauth: OAuth usage returned 429 retry-after: 0` — the quota-meter
+endpoint briefly saying no, not a real rate limit (a genuine limit carries a meaningful
+retry-after). One healthy working session was false-flagged 54 times, confirming the
+detector — not any one agent — was the cause (it also surfaced on AI Guy).
+
+**Before:** a completed session, having no new terminal output, was indistinguishable
+from a throttled one and stayed a recovery target indefinitely (never cleared from the
+topic map) → repeated phantom nudges; junk `retry-after:0` 429s logged as rate limits.
+
+**After (verified):** the new `isSessionRecoverable` guard NO-OPS recovery for any session
+not in the live running set, at all three fire points (decide-to-rescue, pre-retry,
+pre-verify) — proven both-sides by `RateLimitSentinel-recoverable-guard` /
+`CompactionSentinel-recoverable-guard` unit tests; the finished-during-verify race is
+reproduced and locked by a dedicated test; the absence-assertion integration test drives
+a regressed build (false nudge reintroduced) and confirms the done gate VETOES it. The
+`retry-after:0` 429 is reclassified as a transient blip (log-level only). 16 unit + 2
+integration tests, no regression across the existing watcher/quota/harness suites, clean
+typecheck.

package/upgrades/1.3.657.md

@@ -0,0 +1,32 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The live-test harness gained the ability to run its **absence proof** — "after this conversation, prove the agent sent NO unwanted background message (e.g. the false throttle nudge)" — over a **real** Telegram or Slack channel. Previously that assertion only worked against a simulated driver; the production channel driver had no way to collect a window of channel messages, so a real-channel absence scenario was reported as unverifiable.
+
+A new `collectMessages` step (on the Telegram and Slack live senders, exposed through `RealChannelDriver`) polls the channel's history over a window and gathers every agent-authored message, so the harness can prove none of them matches a forbidden pattern. Because the only dangerous failure of an absence proof is a silent **false PASS**, every way the read could be incomplete is forced to BLOCK ("can't verify") instead of passing:
+
+- a **paginated/truncated** read (more messages than one page) → BLOCKED;
+- an **edited** message can't launder its earlier text away (every version is kept);
+- a **Slack background post** under a `bot_id` (not a user id) is now matched;
+- a **failed** history read → BLOCKED;
+- a reused, long-lived demo channel no longer trips a false "too busy" alarm (the Telegram check is bounded to where the test message sits in history).
+
+## What to Tell Your User
+
+Nothing changes in day-to-day use — this is testing infrastructure that runs before code ships, not something on the live conversation path. The benefit is indirect: the "no surprise background message" guarantee can now be proven over a real channel, and it refuses to give a green light it can't actually justify — one more way a feature side-effect is caught before it reaches the fleet.
+
+## Summary of New Capabilities
+
+- `RealChannelDriver.collectMessages` + `SurfaceSender.collectMessages` on the Telegram and Slack live senders — collect a window of agent-authored channel messages for the harness absence assertion.
+- A second typed harness signal, `AbsenceUnverifiableError`: a sender raises it for an incomplete/failed read so the harness records BLOCKED (never a false PASS); `DriverCapabilityError` stays the capability-layer "no collector on this surface" signal; a plain error stays a FAIL.
+- Absence scenarios are demo-channel-only (a whole-history read never touches a live operator channel).
+
+## Evidence
+
+- **Reproduction (the gap):** before this change, an absence scenario pointed at a real Telegram/Slack channel returned `BLOCKED — driver does not support collectMessages`; the proof could only be exercised against the fake driver in `rate-limit-false-positive-prevention.test.ts`.
+- **Before → after (the false-PASS holes, found in review):** a naive `collectMessages` that returned a single 100-entry page, kept last-write-wins text, matched Slack by user id only, and ignored failed reads would PASS an absence scenario even when a spurious message existed (on a paginated read, an edited message, a `bot_id` post, or a failed read). After: each of those four paths now produces BLOCKED, proven by dedicated tests (`Telegram: a FULL page … → AbsenceUnverifiableError`, `Telegram: … marker IN-PAGE does NOT block`, `Slack: ok:false → AbsenceUnverifiableError`, `Slack: next_cursor → AbsenceUnverifiableError`, `Slack: bot_id … IS collected`, `harness: a SAFE absence scenario on a NON-demo channel is refused`).
+- **Verified:** 22 unit tests across the collect path (both sides of every guard boundary), no regression across the existing harness/sender/gate suites, clean typecheck. Multi-angle spec review (6 internal lenses + 2 non-Claude models, 3 rounds) converged with zero material findings.

package/upgrades/side-effects/false-ratelimit-recovery-completed-sessions.md

@@ -0,0 +1,113 @@
+# Side-Effects Review — Fix false rate-limit/error recovery on finished sessions + user-channel proof harness
+
+**Version / slug:** `false-ratelimit-recovery-completed-sessions`
+**Date:** `2026-06-24`
+**Author:** Echo (autonomous, 8-hour run)
+**Spec:** `docs/specs/false-ratelimit-recovery-completed-sessions.md` (review-convergence + approved)
+**Second-pass reviewer:** REQUIRED (touches "sentinel"/"guard"/session-recovery) — verdict appended below.
+
+## Summary of the change
+
+A finished/idle session sitting at a prompt with a stale throttle string in its
+scrollback was mistaken for a live-but-throttled session, so `RateLimitSentinel` (and
+its sibling `CompactionSentinel`) ran a futile recovery and spammed the user with
+`RATE_LIMIT_RESUME_NUDGE` ("the temporary server throttle should have cleared…").
+Fleet-wide (shared detector). Fix makes a terminal session structurally incapable of
+being a recovery target, and adds a reusable test capability that catches spurious
+background messages before deploy.
+
+Files modified:
+- `src/monitoring/RateLimitSentinel.ts` — new optional `isSessionRecoverable?` dep,
+  consulted in `report()` (no-op + no notice for a non-recoverable session),
+  `attemptResume()` and `verify()` (silent `abort()` if the session finished mid-flight
+  — new `rate-limit:aborted` event; `abort()` keeps the `recentReports` dedupe entry as
+  a flap cooldown).
+- `src/monitoring/CompactionSentinel.ts` — the SAME `isSessionRecoverable?` guard in
+  `report()`.
+- `src/commands/server.ts` — defines `isSessionRecoverable = (name) =>
+  sessionManager.listRunningSessions().some(...)`; passes it to BOTH sentinels; adds a
+  `sessionComplete` handler that clears both sentinels (the completion cleanup that had
+  zero callers).
+- `src/monitoring/QuotaCollector.ts` — the OAuth-429 `DegradationReport` now fires only
+  when the 3-strike breaker trips (kills the `retry-after:0` log spam); the error is
+  still recorded in `errors[]`, breaker + quota accounting unchanged.
+- `src/core/LiveTestHarness.ts` — the prevention layer: an optional
+  `ChannelDriver.collectMessages` + a scenario `absenceWindowMs` + `expect.noMessageMatching`
+  / `expect.replyMustNotContain`. An absence scenario collects every channel message over
+  the window and FAILs if any matches; an unsupported driver yields BLOCKED (never a
+  silent pass).
+
+Files added:
+- `src/core/rateLimitFalsePositiveMatrix.ts` — the rate-limit user-role scenario matrix
+  (happy-path reply + absence regression, optional Slack parity).
+- `tests/unit/RateLimitSentinel-recoverable-guard.test.ts`,
+  `tests/unit/CompactionSentinel-recoverable-guard.test.ts`,
+  `tests/unit/rate-limit-false-positive-matrix.test.ts`,
+  `tests/unit/sentinel-recoverable-wiring.test.ts`,
+  `tests/integration/rate-limit-false-positive-prevention.test.ts`.
+- Spec + ELI16 + convergence report.
+
+## Decision-point inventory
+
+- **Added** `isSessionRecoverable` guard — a bounded NO-OP that SUPPRESSES a recovery
+  action; it never adds an authoritative block over a user. Signal-vs-authority: it
+  removes a spurious action, the safe direction.
+- **Added** harness absence assertion → a PASS/FAIL SIGNAL the already-dark, dry-run-
+  default `LiveTestGate` consumes. BLOCKED (not silent-pass) when unverifiable. No new
+  blocking authority.
+- **Modified** `QuotaCollector` 429 path — a LOG-LEVEL decision only (report vs not);
+  accounting + breaker untouched.
+
+## Side effects & blast radius
+
+- **Behavior change (intended):** a finished/killed session no longer receives recovery
+  nudges; a recovery whose session ends mid-flight aborts silently (no escalation ping).
+- **Preserved:** a genuinely-throttled RUNNING session still recovers — the notify
+  templates are byte-for-byte unchanged; dep-absent installs (bare/test) behave exactly
+  as before (regression-locked by tests).
+- **Fail direction:** `listRunningSessions()` fails OPEN on a transient tmux error, so a
+  hiccup cannot drop a live session and suppress a real recovery; only genuine
+  termination removes it.
+- **Machine-local:** each machine runs its own sentinels over its own running set; no
+  cross-machine state introduced. The QuotaCollector poll is already per-machine.
+- **Residual (scoped to CMT-1785):** a still-RUNNING idle session with stale throttle
+  scrollback can still trigger one self-correcting "back online" message (not the
+  6-nudge spam). The known fix (adopt the watchdog `evaluateThrottleSettle` settle-gate
+  on the idle path) is tracked, driven evidence-first by the new absence harness.
+
+## Migration parity
+
+None required. All changes are server-internal wiring + a log-level change — no
+`.claude/settings.json` hook, `.instar/config.json` default, CLAUDE.md template, or
+built-in-skill change ships. Existing agents pick this up on the normal code-update path.
+
+## Rollback
+
+Each fix is independently revertible: F1 is additive (dep-absent = old behavior); F2 is
+a pure cleanup addition; F4 is log-level only; the harness extension is additive (the
+absence path only runs when a scenario sets `absenceWindowMs`).
+
+## Tests
+
+16 unit (guards both-sides + verify/abort lifecycle + harness absence + matrix + wiring-
+integrity) + 2 integration (harness → signed artifact → `LiveTestGate` ALLOW on clean /
+VETO on a reintroduced regression). No regression across the existing sentinel (96),
+quota (53), and harness/gate (30) suites; clean `tsc`.
+
+---
+
+## Second-pass review
+
+**Concur with the review.** Independent audit of the diff verified: the
+`isSessionRecoverable` guard uses running-set membership (the correct criterion) and
+genuinely fails OPEN via `isSessionAlive`'s catch-returns-true path, so no genuine
+recovery is suppressed by a transient tmux error — only actual termination removes a
+session. The `verify()`/`attemptResume()` abort returns BEFORE any user-facing
+`notify()` (no escalation/"still throttled" ping for a finished session); `abort()`
+correctly keeps `recentReports` as the flap cooldown. The `sessionComplete` cleanup is
+best-effort try/catch and cannot break completion. The QuotaCollector change preserves
+the 429 signal in `errors[]` + the breaker, suppressing only transient per-poll log
+spam (no other consumer keys on that feature). The notify templates are byte-for-byte
+unchanged (a genuinely-throttled RUNNING session recovers as before). The harness
+returns BLOCKED (never a silent pass) when absence is unverifiable. All 322 relevant
+tests green. — independent second-pass reviewer, 2026-06-24.

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.