instar 1.3.657 → 1.3.659

package/dist/monitoring/strandedTopicDecision.js

@@ -0,0 +1,160 @@
+/**
+ * strandedTopicDecision — the PURE, unit-testable decision core of the
+ * StrandedTopicSentinel (spec docs/specs/stranded-inbound-self-heal.md).
+ *
+ * A topic is STRANDED when its durable ownership record names a machine that is
+ * online-by-heartbeat but, persistently across rich beats, cannot serve the
+ * topic's channel — quota-walled (`quotaState.blocked === true`, channel-
+ * independent) OR adapter-disconnected (`machineServesChannel(...) === 'no'`).
+ * Inbound for that topic routes to the owner that cannot serve it, so it is
+ * silently dead while outbound still flows from a healthy lease-holder.
+ *
+ * This module computes the strand verdict ONLY. It mutates nothing: no
+ * ownership CAS, no pin write, no session kill. Fail-closed on EVERY
+ * uncertainty (missing field, stale beat, underivable scope, pool view
+ * unavailable) — an uncertainty can NEVER manufacture a strand, it routes to
+ * SKIP. The quota arm carries detection on its own when the adapter arm skips.
+ *
+ * Signal-vs-authority: pure read + a verdict object. No authority to misuse.
+ */
+import { machineServesChannel, } from '../core/machineServesChannel.js';
+/** Is this owner's rich beat genuine (present + fresh)? */
+function richBeatAgeMs(cap, now) {
+    if (!cap.routerReceivedAt)
+        return undefined;
+    const t = Date.parse(cap.routerReceivedAt);
+    if (!Number.isFinite(t))
+        return undefined;
+    return now - t;
+}
+/**
+ * The pure strand evaluation for one tick. Synchronous, LLM-free, no I/O.
+ *
+ * Predicate per `active`, non-self-owned record:
+ *   owner online
+ *   AND ( quota arm: quotaState.blocked === true   [channel-independent]
+ *         OR adapter arm: machineServesChannel(servesChannels, scope) === 'no'
+ *                         ['unknown'/undefined-scope ⇒ SKIP that arm] )
+ *   AND the condition has held ≥2 consecutive rich beats spanning ≥ dwellMs.
+ *
+ * Early no-op: < 2 machines OR !holdsLease ⇒ empty (and the map is dropped).
+ */
+export function evaluateStrandedTopics(input) {
+    const { records, capacities, selfMachineId, holdsLease, prevStrandedSince, now, cfg } = input;
+    // Early no-op gates (spec step 1). A single-machine agent can't strand on a
+    // peer; a non-lease-holder is not the sole actor. Drop the dwell map so a
+    // demotion/scale-down doesn't carry stale anchors.
+    if (capacities.length < 2 || !holdsLease) {
+        return { strandedSet: [], cantAssessCount: 0, nextStrandedSince: {} };
+    }
+    const capById = new Map();
+    for (const c of capacities)
+        capById.set(c.machineId, c);
+    const strandedSet = [];
+    const nextStrandedSince = {};
+    let cantAssessCount = 0;
+    for (const rec of records) {
+        // Only active, peer-owned records are candidates.
+        if (rec.status !== 'active')
+            continue;
+        if (rec.ownerMachineId === selfMachineId)
+            continue;
+        const owner = capById.get(rec.ownerMachineId);
+        // Unknown owner / not in the pool view → can't assess → skip (fail-closed).
+        if (!owner)
+            continue;
+        // A dead owner is the existing Case C's job; this sentinel only covers the
+        // online-but-unable gap.
+        if (!owner.online)
+            continue;
+        // Require a genuine rich beat: present + fresh. A stale/undecodable beat
+        // fails closed (skip) and does NOT count toward the dwell.
+        const beatAgeMs = richBeatAgeMs(owner, now);
+        if (beatAgeMs === undefined || beatAgeMs > cfg.freshnessBoundMs)
+            continue;
+        // ── Arm (a): quota — channel-independent, the dominant incident case. ──
+        const quotaArm = owner.quotaState?.blocked === true;
+        // ── Arm (b): adapter — best-effort, channel-specific. ──
+        let adapterArm = false;
+        // A missing servesChannels on an online owner is the anti-blind-spot case:
+        // we cannot evaluate the adapter arm. If the quota arm ALSO can't fire
+        // (quotaState absent/undecided), this owner is genuinely unassessable.
+        const servesPresent = owner.servesChannels !== undefined;
+        let armBlind = false;
+        if (input.resolveScope) {
+            const scope = input.resolveScope(rec.sessionKey);
+            if (scope === undefined) {
+                // Underivable scope ⇒ SKIP this arm (not a strand).
+            }
+            else {
+                const serve = machineServesChannel(owner.servesChannels, scope);
+                if (serve === 'no')
+                    adapterArm = true;
+                else if (serve === 'unknown') {
+                    // 'unknown' (sparse/absent servesChannels) ⇒ SKIP this arm.
+                    if (!servesPresent)
+                        armBlind = true;
+                }
+                // 'yes' ⇒ owner can serve on this arm → not stranded here.
+            }
+        }
+        const unableToServe = quotaArm || adapterArm;
+        if (!unableToServe) {
+            // Anti-blind-spot: an online owner we could NOT assess at all — quota
+            // undecided AND the adapter arm blinded by a missing servesChannels —
+            // increments the can't-assess count (spec step 4). A topic with a usable
+            // 'yes' or a derivable scope is genuinely assessed (not blind).
+            const quotaUndecided = owner.quotaState === undefined;
+            if (quotaUndecided && armBlind)
+                cantAssessCount++;
+            continue;
+        }
+        // ── Persistence (dwell) — anchor on the FIRST qualifying beat. ──
+        const prevSince = prevStrandedSince[rec.sessionKey];
+        const strandedSince = typeof prevSince === 'number' ? prevSince : now;
+        nextStrandedSince[rec.sessionKey] = strandedSince;
+        // The condition must have held ≥ dwellMs (which, given the ≥1 prior beat that
+        // set the anchor, spans ≥2 consecutive rich beats). A first-beat strand has
+        // dwell 0 < dwellMs → recorded in the map but NOT yet emitted.
+        if (now - strandedSince < cfg.dwellMs)
+            continue;
+        const reason = quotaArm ? 'quota' : 'adapter';
+        strandedSet.push({
+            sessionKey: rec.sessionKey,
+            ownerMachineId: rec.ownerMachineId,
+            reason,
+            strandedSince,
+            ownerBeatAgeMs: beatAgeMs,
+            servablePeerExists: servablePeerExists(rec, capacities, selfMachineId, input.resolveScope),
+        });
+    }
+    return { strandedSet, cantAssessCount, nextStrandedSince };
+}
+/**
+ * Whether SOME online machine could serve the topic's channel — narrowly "online
+ * AND not quota-blocked AND machineServesChannel(...) === 'yes'" (the same
+ * PlacementExecutor filter, so detector + placement agree). Deliberately NOT a
+ * "safe failover target": it vets no pin policy, lease/router readiness, secrets,
+ * or session limits — v1 never fails over, so this only tells the operator
+ * "somewhere could serve this" vs "nowhere can (fleet-wide wall)". When the scope
+ * can't be derived, a not-quota-blocked online peer counts (quota-arm semantics).
+ */
+function servablePeerExists(rec, capacities, selfMachineId, resolveScope) {
+    const scope = resolveScope?.(rec.sessionKey);
+    for (const c of capacities) {
+        if (c.machineId === rec.ownerMachineId)
+            continue;
+        if (!c.online)
+            continue;
+        if (c.quotaState?.blocked === true)
+            continue;
+        if (scope === undefined) {
+            // No channel scope → quota-arm semantics: a healthy peer suffices.
+            return true;
+        }
+        if (machineServesChannel(c.servesChannels, scope) === 'yes')
+            return true;
+    }
+    return false;
+}
+//# sourceMappingURL=strandedTopicDecision.js.map

package/dist/monitoring/strandedTopicDecision.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"strandedTopicDecision.js","sourceRoot":"","sources":["../../src/monitoring/strandedTopicDecision.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.657",
+  "version": "1.3.659",
   "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-24T22:34:53.907Z",
-  "instarVersion": "1.3.657",
+  "generatedAt": "2026-06-25T01:38:40.089Z",
+  "instarVersion": "1.3.659",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -1538,7 +1538,7 @@
       "type": "subsystem",
       "domain": "sessions",
       "sourcePath": "src/core/SessionManager.ts",
-      "contentHash": "1e975218f0ef7377bf709128150e65af094afcb3ff524c6822f2af136548f12b",
+      "contentHash": "7ea591c3a48b752c066a2fdf0179804a6319177b3664bde1bcc20d9fc0a0d508",
       "since": "2025-01-01"
     },
     "subsystem:auto-updater": {

package/upgrades/1.3.658.md

@@ -0,0 +1,24 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The SessionManager idle-monitor used to hand a session to rate-limit recovery the instant it saw a throttle line in the last ~30 terminal lines — a single glance. That false-fires when the throttle line is stale scrollback the session has moved past, or a transient throttle that already cleared (the milder cousin of the false-rate-limit spam fixed in #1262). Behind a DARK flag (`monitoring.idleThrottleSettleGate`, dev-agent live / dark on the fleet), the idle-monitor now gates that hand-off behind the SAME settle discipline the SessionWatchdog already uses: a throttle must be present AND the terminal pane byte-identical across polls (a working session animates its spinner every tick, so a frozen pane proves the turn genuinely ended on the throttle). It is strictly more conservative — it can only ever trigger recovery LESS often, never more, so it cannot strand a genuinely-stuck session.
+
+## What to Tell Your User
+
+Nothing visible day-to-day — this is internal session-watching behavior and it's off everywhere except the development machine until it's soaked. The eventual benefit is fewer unnecessary "back online" pokes from a session that wasn't really stuck.
+
+## Summary of New Capabilities
+
+- `monitoring.idleThrottleSettleGate` (dev-gated dark flag): settle-gate the idle-monitor's rate-limit recovery hand-off, bringing it to parity with the SessionWatchdog's settle discipline.
+- `nextIdleThrottleAction` (pure helper): the unit-testable settle decision (`emit`/`wait`/`fall-through`) the idle path consults each tick.
+- Deferred (CMT-1785): unifying the idle-monitor and watchdog detection paths (one shared trigger + one shared per-tick capture) + distinguishing an active-tail throttle from old scrollback.
+
+## Evidence
+
+- **Reproduction (the gap):** the idle-monitor's `rateLimitedAtIdle` emit fired on `detectRateLimited(recentOutput)` from a single capture, with no settle check — unlike the SessionWatchdog's `checkRateLimited`, which already required a settled (pane-unchanged-across-polls) throttle before acting.
+- **Before → after:** before, a still-running idle session with a stale/transient throttle line in its buffer got an unnecessary recovery hand-off (≤1 stray "back online" message, after #1262 neutralized the finished-session spam). After, the idle-monitor re-samples the pane every idle tick and only hands off once the throttle has genuinely settled; a stale or already-cleared throttle line no longer triggers recovery. Flag off (the fleet) is byte-identical to the legacy behavior.
+- **Verified:** 6 unit tests for the pure settle decision (`nextIdleThrottleAction`, every boundary), 130 green across the rate-limit/watchdog suites, no regression, clean typecheck. Multi-angle review (3 internal lenses + codex + gemini, 2 rounds) caught a critical defect in an earlier draft (the settle check running only on the first idle tick, making "settled" unreachable) — fixed to re-sample every tick and verified.

package/upgrades/1.3.659.md

@@ -0,0 +1,29 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+A new pure-signal monitoring sentinel, `StrandedTopicSentinel`, ships behind a DARK dev-gate (`monitoring.strandedTopicSentinel.enabled`, omitted from ConfigDefaults ⇒ live on a development agent, dark on the fleet). It closes a real, proven gap: a Telegram/Slack topic's durable ownership record can name a machine that is **online-by-heartbeat but cannot serve** — quota-walled (`quotaState.blocked`) or adapter-disconnected (`servesChannels` omits the topic's channel) — while a healthy machine holds the lease. Inbound for that topic routes to the owner that can't answer, so it is **silently dead** (outbound still flows from the healthy machine — the "my replies send but the user's messages never arrive" split). The existing `OwnershipReconciler` only force-claims a *provably-DEAD* owner (offline ≥180s) and only iterates *pinned* topics, so a walled-but-online owner defers forever and an unpinned strand is never even considered.
+
+The sentinel scans the in-memory ownership cache against the replicated machine-pool view each tick (default 60s), applies a fail-closed predicate with a persistence gate (the unable-to-serve condition must hold ≥2 rich beats over ≥`dwellMs`, default 30s, so a transient quota/adapter blip can't trip it), and raises ONE aggregated `agent-health` attention item per (owner-machine, stranding-window) — never one-per-topic — plus a separate LOW "can't-assess" item if a heartbeat/schema regression blinds it. It is **lease-holder-only** (so peers don't double-report), a **strict no-op on a single-machine agent**, registers in the GuardRegistry (`GET /guards`), and **MUTATES NOTHING** — no ownership CAS, no pin write, no session kill.
+
+This is the deliberately-safe HALF of the fix. Spec-convergence review (3 rounds) established that the *instinctive* auto-failover is unsafe with today's primitives — there is no per-topic remote-liveness signal, the reachability signal is self-reported and up to `failoverThresholdMs` stale, and there's no hysteresis — so a wrong failover would yank a live conversation mid-reply, which is strictly worse than the bug. The auto-failover is therefore deferred to a tracked v2 (`CMT-1786`) whose prerequisites are each named in the spec.
+
+## What to Tell Your User
+
+Nothing visible day-to-day — it's off everywhere except the development machine until it's soaked. The eventual benefit: a conversation whose messages are silently going to a machine that can't answer them gets caught within about a minute, instead of staying invisible until you notice you're being ignored.
+
+## Summary of New Capabilities
+
+- `monitoring.strandedTopicSentinel.enabled` (dev-gated dark flag): a pure-signal sentinel that detects an online-but-unable-to-serve owner stranding a topic's inbound and raises one aggregated `agent-health` attention item; registered on `GET /guards`.
+- `evaluateStrandedTopics(...)` (pure helper): the unit-testable, fail-closed strand decision (quota arm + best-effort adapter arm + dwell persistence + reconciliation).
+- Deferred (CMT-1786): the auto-failover that actually re-points a stranded topic to a healthy server, plus its named prerequisites (per-topic remote liveness signal, hysteresis/cooldown, claim-time re-assertion, atomic CAS+pin, reason-stamped nonce, OwnershipReconciler unification) and a live userbot harness for real-Telegram UX regression testing.
+
+## Evidence
+
+- **Reproduction (the live incident, 2026-06-24):** 17 of 25 topics were owned by an offline/quota-walled Mac Mini; every one had silently-dead Telegram inbound; every code review and CI gate was green the whole time; the wedge surfaced only when the operator reported missing messages. `GET /pool/placement?topic=N` showed `owner=Mini, pendingReplacement:true` — the signal was present and unmonitored. The only recovery was a human hand-editing `.instar/ownership/local/<topicId>.json`.
+- **Before → after:** before, this class of breakage was invisible to all automated checks until a user got bitten. After (dev-gated), the moment a topic's owner is persistently online-but-unable-to-serve, ONE attention item fires within ~`dwellMs + tickMs` (≈ a minute or two on a healthy heartbeat cadence) naming the stranded topics, the walled owner + reason, whether a servable peer exists, and the signal's staleness. Flag off (the fleet) is byte-identical to today (no sentinel).
+- **Safety verified:** the sentinel is pure signal — it raises an attention item and writes nothing. The fail-closed predicate (missing field / stale beat / underivable scope / pool view unavailable ⇒ SKIP) means an uncertainty can never manufacture a strand; the lease-holder-sole-actor + single-machine no-op prevent duplicate items; the aggregated item rides the existing `AttentionTopicGuard` flood ceiling.
+- **Tests:** 29 unit tests on the pure decision core (both sides of every boundary — quota arm, three-valued adapter arm, persistence/dwell, fail-closed skips, `strandedSince` reconciliation, can't-assess counting, servable-peer, single-machine/non-lease-holder no-op, sync/LLM-free invariant) + GuardRegistry registration + a `/guards`-posture integration check. `tsc --noEmit` clean. Multi-angle spec review (6 internal reviewers + GPT-5.5 cross-model, 3 rounds) drove the design from an unsafe auto-failover to this safe detector and caught a critical predicate bug (the three-valued `machineServesChannel` would have made a `!fn(...)` detector never fire).

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/stranded-inbound-self-heal.md

@@ -0,0 +1,80 @@
+# Side-Effects Review — StrandedTopicSentinel (online-but-unable-to-serve inbound detector)
+
+**Version / slug:** `stranded-inbound-self-heal`
+**Date:** `2026-06-24`
+**Author:** Echo (autonomous)
+**Second-pass reviewer:** not-required (Tier 2; dev-gated, pure-signal monitoring sentinel — no mutation, no fleet runtime path, no operator surface)
+
+## Summary of the change
+
+Adds a new dark-gated, pure-signal monitoring sentinel, `StrandedTopicSentinel`, that detects a Telegram/Slack topic whose durable ownership record names a machine that is **online-by-heartbeat but cannot serve** (quota-walled `quotaState.blocked`, or adapter-disconnected `servesChannels` omits the topic's channel) while a healthy machine holds the lease — so inbound for that topic is silently dead. It raises ONE aggregated `agent-health` attention item per (owner-machine, stranding-window) and a separate LOW "can't-assess" item if a heartbeat/schema regression blinds it. It **MUTATES NOTHING** (no ownership CAS, no pin write, no session kill); its sole output is an advisory attention item. The instinctive auto-failover was deferred to a tracked v2 (CMT-1786) because spec-convergence review proved it unsafe with today's primitives (no per-topic remote liveness, self-reported stale reachability, no hysteresis) — a wrong failover drops a live conversation, strictly worse than the bug.
+
+Files added:
+- `src/monitoring/strandedTopicDecision.ts` — the PURE, unit-testable decision core (`evaluateStrandedTopics`): fail-closed predicate (quota arm + best-effort adapter arm), dwell persistence, `strandedSince` reconciliation, `servablePeerExists`.
+- `src/monitoring/StrandedTopicSentinel.ts` — the sentinel (tick loop, per-owner stranding-window discipline, attention emission, `guardStatus`).
+- `tests/unit/stranded-topic-sentinel.test.ts` (29), `tests/integration/stranded-topic-guard-posture.test.ts` (4), `tests/e2e/stranded-topic-guards-lifecycle.test.ts` (2).
+- `docs/specs/stranded-inbound-self-heal.md` (+ `.eli16.md` + convergence report), `upgrades/next/stranded-inbound-self-heal.md`.
+
+Files modified:
+- `src/core/types.ts` — `MonitoringConfig.strandedTopicSentinel?` config type.
+- `src/config/ConfigDefaults.ts` — the `strandedTopicSentinel` defaults block (tickMs/dwellMs/freshnessBoundMs/clearAfterTicks); `enabled` OMITTED (dev-gate decides).
+- `src/core/devGatedFeatures.ts` — `DEV_GATED_FEATURES` entry (pure-signal justification).
+- `src/monitoring/guardManifest.ts` — `GUARD_MANIFEST` entry (`expectRuntime`, `expectedTickMs`).
+- `src/core/SessionOwnershipRegistry.ts` — added `all()` (delegates to `store.all?.()`; reads empty for a store lacking it) so the registry the server holds can be scanned.
+- `src/commands/server.ts` — wires the sentinel (late, after pool boot; `selfMachineId` via a lazy getter to avoid the #1190 boot-ordering null-capture; `raiseAttention` → `telegram.createAttentionItem`; GuardRegistry registration).
+- `tests/unit/lint-dev-agent-dark-gate.test.ts` — hand-shifted the golden line-map keys +14 (my ConfigDefaults block added 14 lines, NO new `enabled:` literal).
+
+## Decision-point inventory
+
+- **Added**: the strand predicate (`evaluateStrandedTopics`) — a READ-ONLY verdict, not a gate. It decides whether to RAISE an attention item; it authorizes no mutation. Fail-closed on every uncertainty.
+- **Added**: the lease-holder-sole-actor + single-machine early-no-op gates — decide WHETHER THIS MACHINE evaluates at all (so peers don't double-report). Observe-only.
+- No agent-to-user or ownership mutation decision point is added. This is pure-signal monitoring.
+
+## 1. Over-block
+
+None — the change blocks nothing. It is observe-only. The only "false positive" risk is a spurious attention item, mitigated by: ≥2-rich-beat dwell persistence (kills transient blips), missing-field/stale-beat/underivable-scope ⇒ SKIP (fail-closed — an uncertainty can never manufacture a strand), and lease-holder-only emission (no duplicate items across machines). A spurious item is cheap and rides the existing `AttentionTopicGuard` flood ceiling.
+
+## 2. Under-block
+
+By design, v1 only DETECTS — it does not remediate; the operator/agent acts on the alert (manual remediation documented in the spec; auto-failover is the tracked v2). The adapter arm is best-effort: for Telegram the channel scope is shared adapter config so the adapter arm rarely fires (the quota arm carries the Telegram case — the actual incident); the adapter arm's real value is Slack per-workspace. A dead (offline) owner is intentionally NOT covered (that is the existing OwnershipReconciler Case C's job) — this sentinel covers only the online-but-unable gap.
+
+## 3. Level-of-abstraction fit
+
+Right layer: a `src/monitoring/` sentinel, mirroring the established pattern (ContextWedgeSentinel/ResumeQueue) — deps-injected, `lastTickAt` liveness, GuardRegistry registration, dark-gate via DEV_GATED_FEATURES. The pure decision is extracted to a separate module so it is unit-testable without tmux/HTTP.
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md). FULLY compliant — this is the textbook SIGNAL side. The sentinel holds NO authority: it raises an advisory attention item and writes nothing else (no CAS, no pin, no kill, no direct user message). The deliberate review-driven retreat from a mutating design to a pure detector is exactly the standard's prescription (the dangerous mutation is deferred until the primitives that make it safe exist).
+
+## 5. Interactions
+
+- **OwnershipReconciler (Case C):** disjoint by trigger — Case C covers offline-DEAD+pinned owners; this covers online-but-UNABLE owners (which Case C explicitly defers as `deferredNoEvidence`). No shared writer (this sentinel writes nothing).
+- **AttentionTopicGuard:** the aggregated item rides the existing flood ceiling; NORMAL/LOW priority never bypasses it.
+- **GuardRegistry / GET /guards:** registers so a silently-disabled instance is visible (the exact failure class this feature exists to surface).
+- **Host spawn cap / event loop:** the tick is synchronous, LLM-free, acquires NO spawn-cap slot (asserted by test), and does NO synchronous peer probe — it reads the in-memory ownership cache + replicated heartbeat view only.
+
+## 6. External surfaces
+
+The only external-visible effect is an `agent-health` attention item (and a LOW can't-assess item) when a strand is detected — calm, aggregated, deduped, flood-ceiling-bounded, with signal-staleness disclosed in the text. No new HTTP route, no dashboard change, no message to a user channel.
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — not applicable. This change touches no dashboard renderer/markup, approval page, or grant/revoke/secret-drop form. Its only operator-facing output is a plain-language attention item whose text leads with the situation ("inbound for topics X is going to <machine>, which can't serve them; <machine> can"), de-emphasizes identifiers, and discloses signal staleness.
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** The detection is per-machine observability over the REPLICATED heartbeat machine-pool view + the local in-memory ownership cache; it writes no durable state, so there is nothing to replicate or strand on a topic transfer. Exactly ONE machine reports per strand: the lease-holder is the sole actor (`syncStatus.holdsLease`), so peers stay observe-only and the user hears one voice. A single-machine agent is a strict no-op (`machines().length < 2` early return — nothing can be stranded on a peer that doesn't exist).
+
+## 8. Rollback cost
+
+Trivial and instant. The feature ships dark on the fleet (`monitoring.strandedTopicSentinel.enabled` omitted ⇒ resolves dark off a dev agent); flag-off is byte-identical to today (no sentinel constructed). On a dev agent, set `monitoring.strandedTopicSentinel.enabled: false` to force-dark. No durable state is written, so there is nothing to clean up on back-out.
+
+## Conclusion
+
+A safe, dark-gated, pure-signal detector that makes a real, proven, previously-invisible cross-machine inbound wedge loud within a bounded window — the deliberately-safe half of the fix, with the dangerous auto-failover deferred behind named, tracked prerequisites (CMT-1786). All three test tiers green; the design passed 3 spec-convergence rounds (6 internal reviewers + GPT-5.5 cross-model).
+
+## Evidence pointers
+
+- Spec + convergence report: `docs/specs/stranded-inbound-self-heal.md`, `docs/specs/reports/stranded-inbound-self-heal-convergence.md`.
+- Live incident (the reproduction): 2026-06-24, 17 of 25 topics stranded on a quota-walled Mac Mini; inbound silently dead; surfaced only when the operator reported missing messages.
+- Tests: unit (29) `tests/unit/stranded-topic-sentinel.test.ts`; integration (4) `tests/integration/stranded-topic-guard-posture.test.ts`; e2e (2) `tests/e2e/stranded-topic-guards-lifecycle.test.ts`.