instar 1.3.658 → 1.3.660

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.658",
+  "version": "1.3.660",
   "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-24T23:28:12.769Z",
-  "instarVersion": "1.3.658",
+  "generatedAt": "2026-06-25T07:17:11.166Z",
+  "instarVersion": "1.3.660",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -11,7 +11,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/session-start.sh",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:dangerous-command-guard": {
@@ -20,7 +20,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/dangerous-command-guard.sh",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:grounding-before-messaging": {
@@ -29,7 +29,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/grounding-before-messaging.sh",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:compaction-recovery": {
@@ -38,7 +38,7 @@
       "domain": "identity",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/compaction-recovery.sh",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:external-operation-gate": {
@@ -47,7 +47,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-operation-gate.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:deferral-detector": {
@@ -56,7 +56,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/deferral-detector.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:self-stop-guard": {
@@ -65,7 +65,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/self-stop-guard.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:post-action-reflection": {
@@ -74,7 +74,7 @@
       "domain": "evolution",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/post-action-reflection.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:external-communication-guard": {
@@ -83,7 +83,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/external-communication-guard.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-collector": {
@@ -92,7 +92,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-collector.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:scope-coherence-checkpoint": {
@@ -101,7 +101,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/scope-coherence-checkpoint.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:free-text-guard": {
@@ -110,7 +110,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/free-text-guard.sh",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:claim-intercept": {
@@ -119,7 +119,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:claim-intercept-response": {
@@ -128,7 +128,7 @@
       "domain": "coherence",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/claim-intercept-response.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:stop-gate-router": {
@@ -137,7 +137,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/stop-gate-router.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "hook:auto-approve-permissions": {
@@ -146,7 +146,7 @@
       "domain": "safety",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
       "installedPath": ".instar/hooks/instar/auto-approve-permissions.js",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "job:health-check": {
@@ -1562,7 +1562,7 @@
       "type": "subsystem",
       "domain": "updates",
       "sourcePath": "src/core/PostUpdateMigrator.ts",
-      "contentHash": "25307559192c0fd8e51ea087b3ba9ee4473424a330518b8899ce06bb4cdcdb80",
+      "contentHash": "4c5fa1d050d577392ce8e682974c6d495df23727ff7622a0ed01ff8fd6663c48",
       "since": "2025-01-01"
     },
     "subsystem:scheduler": {

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/1.3.660.md

@@ -0,0 +1,27 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixed the "session paused" hang: an autonomous session would freeze indefinitely the first time a helper sub-agent (spawned via the Task/Agent tool) ran a shell command. Root cause: a sub-agent does NOT inherit the parent session's `--dangerously-skip-permissions` MODE — confirmed against Claude Code docs, it inherits only the permission RULES from `.claude/settings.json`. With no allow-rules configured, the sub-agent's first `Bash` call surfaced the interactive "This command requires approval" dialog, and in an unattended run there was no human to answer it, so the session sat modal-blocked forever (indistinguishable from "paused"). It affected the whole fleet because every agent shipped with an empty permissions block.
+
+`PostUpdateMigrator.ensurePermissionAllowRules()` now runs inside `migrateSettings()` and adds a `permissions.allow` list for the built-in tools a sub-agent uses (`Bash`, `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Task`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`). Sub-agents inherit permission rules, so the allow-rule is the structural lever that reliably applies — unlike the existing `PermissionRequest` auto-approve hook, which does not reliably fire for sub-agent calls. The migration is idempotent (adds only missing tool names), never touches the operator's `deny`/`ask` lists, and deliberately excludes MCP tools (`mcp__*`) so external/network operations keep their external-operation-gate approval posture. Because it rides `migrateSettings()`, every existing agent picks it up on its next update and every new agent gets it at init (Migration Parity).
+
+Safety is unchanged: the allow-rules only skip the duplicative human-in-the-loop prompt. The PreToolUse guard chain (`dangerous-command-guard`, `external-operation-gate`, `external-communication-guard`, `self-stop-guard`, …) still runs on every tool call and can still block — and the same `migrateSettings()` pass that adds the allow-rules also wires that guard chain (via `ensureInstarBashPreToolUseHooks`, before the allow-rules), so the guards and the allow-rules always arrive together.
+
+## What to Tell Your User
+
+If your agent ever seemed to "pause" mid-task during an unattended/autonomous run — silently stuck and only resuming when you messaged it — this is a common cause: a helper it spawned hit an approval prompt nobody was there to answer. After this update (and a session restart so the new settings load), helper tasks no longer stall on those prompts, so autonomous runs keep moving. Your safety guards are unchanged — every command still passes the same pre-action checks; the only thing removed is the approval pop-up that had no one to answer it.
+
+## Summary of New Capabilities
+
+- `PostUpdateMigrator.ensurePermissionAllowRules()` — adds inherited `permissions.allow` rules for sub-agent built-in tools to every agent's `.claude/settings.json` via the migration path (new agents at init, existing agents on update). Idempotent, non-clobbering of operator `deny`/`ask`, and scoped to local tools (MCP stays gated by the external-operation-gate).
+
+## Evidence
+
+- **Reproduction (2026-06-24):** an unattended autonomous run sat silent for ~68 min; a screenshot showed the session modal-blocked on a sub-agent's `Bash` "This command requires approval" dialog. Confirmed the same class on a second agent (AI Guy). Settings inspection showed the `permissions` block was entirely absent (no allow-rules for sub-agents to inherit).
+- **Mechanism confirmed:** Claude Code docs — sub-agents inherit permission RULES but not the permission MODE; PreToolUse hooks run BEFORE permission-rule evaluation and a hook exiting 2 blocks the call even for an allowed tool (so allow-rules cannot weaken the guards).
+- **Tests:** `tests/unit/PostUpdateMigrator-permissionAllowRules.test.ts` — 6 tests: adds all sub-agent tools when absent; includes Bash; does NOT blanket-allow MCP; preserves operator allow entries with no duplicates; never touches deny/ask; idempotent on second pass. All passing. Adjacent `PostUpdateMigrator-cleanupPeriodDays.test.ts` (same migrateSettings path) still green. `npm run build` green.
+- **Second-pass review:** independent reviewer concurred; verified the safety argument against the docs and confirmed the guard chain is wired in the same migration pass, before the allow-rules.

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`.

package/upgrades/side-effects/subagent-permission-allow-rules.md

@@ -0,0 +1,109 @@
+# Side-Effects Review — Subagent permission allow-rules (the "session paused" fix)
+
+**Version / slug:** `subagent-permission-allow-rules`
+**Date:** `2026-06-24`
+**Author:** `Instar Agent (echo)`
+**Second-pass reviewer:** `general-purpose reviewer subagent (Phase 5 — touches permission allow/deny surface)`
+
+## Summary of the change
+
+Adds `PostUpdateMigrator.ensurePermissionAllowRules()` and wires it into `migrateSettings()` so every agent's `.claude/settings.json` gains a `permissions.allow` list for the built-in tools a Task/Agent-spawned sub-agent uses (`Bash`, `Read`, `Edit`, `Write`, `Glob`, `Grep`, `Task`, `NotebookEdit`, `WebFetch`, `WebSearch`, `TodoWrite`). Root cause: a sub-agent does NOT inherit the parent session's `--dangerously-skip-permissions` MODE — only the permission RULES from settings.json. With no allow-rules, a sub-agent's first Bash call surfaces the interactive approval dialog and an unattended autonomous session freezes on it forever (the "session paused" bug; reproduced on this agent and AI Guy). Files: `src/core/PostUpdateMigrator.ts` (new method + one call site in `migrateSettings`), `tests/unit/PostUpdateMigrator-permissionAllowRules.test.ts` (6 tests).
+
+## Decision-point inventory
+
+- `migrateSettings() → ensurePermissionAllowRules()` — **add** — populates `permissions.allow` for subagent tools, set-if-missing per tool name; idempotent; never touches `deny`/`ask`.
+- The interactive permission PROMPT for sub-agent local-tool calls — **remove** (only the human-in-the-loop prompt; the programmatic PreToolUse guards are untouched).
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No new block surface — this change only ADDS allow-rules, it never adds a deny. It cannot reject anything that worked before; the worst case direction is "allows too much," covered under §2. Over-block not applicable.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss / does it allow too much?**
+
+The allow-rules skip the interactive prompt for the listed local tools, so a human is no longer asked before a sub-agent runs e.g. an arbitrary Bash command. This is intentional and acceptable because the real safety is the PreToolUse guard chain (`dangerous-command-guard.sh`, `external-operation-gate.js`, `external-communication-guard.js`, `self-stop-guard.js`) which runs on EVERY tool call regardless of allow-rules — the prompt was duplicative friction, not the protective layer. Deliberately NOT covered: MCP tools (`mcp__*`) are left out of the allow list so external/network operations keep their external-operation-gate plan/approval posture. A sub-agent calling an MCP tool could still prompt — but MCP calls are not the wedge this fixes, and broadening to MCP would weaken the external-op gate's intended approval step.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. `permissions.allow` in settings.json is the exact Claude Code mechanism that sub-agents inherit (per docs), so the fix lives at the layer that actually controls the behavior. The alternative — the `PermissionRequest` auto-approve hook — sits at a layer that does not reliably reach sub-agent calls, which is why it failed. Putting the rule in `migrateSettings()` (rather than only `init`) is the correct layer for Migration Parity: it reaches both new agents (init → refreshHooksAndSettings → migrateSettings) and the existing fleet (update → migrateSettings) through one code path, mirroring the established `cleanupPeriodDays` migration.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no block/allow surface that adds brittle blocking authority. It REMOVES a human-in-the-loop prompt while leaving every existing smart/programmatic gate (the PreToolUse guards) fully in force.
+
+This change adds zero new decision authority. It does not inspect command content, classify, or gate — it declares static allow-rules so the existing PreToolUse authorities are the sole deciders. There is no brittle detector holding block power here.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** none. Allow-rules and the PreToolUse hooks are orthogonal — an allow-rule skips the prompt; the hooks still fire and can still block (exit 2 / deny). The allow-rule cannot shadow a guard.
+- **Double-fire:** the `PermissionRequest` auto-approve hook (`ensurePermissionAutoApprove`) remains in place as defense-in-depth. With allow-rules present, the prompt typically never arises, so the hook is a redundant backstop, not a conflicting one — both pushing toward "allow" is harmless.
+- **Races:** none. `migrateSettings()` is a synchronous, idempotent file patch run at init/update; it shares no runtime state with live sessions. The new rules take effect only on the next session start (settings load once at spawn).
+- **Feedback loops:** none.
+
+---
+
+## 6. External surfaces
+
+- Other agents on the machine: unaffected at runtime — this only changes a file each agent reads at its own session start.
+- Install base: every existing agent gains the allow-rules on its next update; new agents at init. This is the intended fleet-wide fix.
+- External systems: none. No Telegram/Slack/GitHub/Cloudflare surface changes.
+- Persistent state: writes `permissions.allow` into each agent's local `.claude/settings.json`. Idempotent, additive, reversible.
+- **Operator surface (Mobile-Complete Operator Actions):** no operator-facing action added or changed — this is internal config plumbing. Not applicable.
+
+---
+
+## 6b. Operator-surface quality (Operator-Surface Quality standard)
+
+No operator surface — this change touches no dashboard renderer, approval page, or grant/revoke/secret-drop form. Not applicable.
+
+---
+
+## 7. Multi-machine posture (Cross-Machine Coherence)
+
+**machine-local BY DESIGN.** `.claude/settings.json` is a per-machine file that Claude Code reads from local disk at session start; the permission rules must exist on whichever machine actually spawns the session. There is no cross-machine state to replicate — each machine's `PostUpdateMigrator` runs the same idempotent migration locally on its own update/init, so the fleet converges to identical allow-rules without any replication path. It emits no user-facing notices (no one-voice concern), holds no durable cross-topic state (nothing strands on topic transfer), and generates no URLs.
+
+---
+
+## 8. Rollback cost
+
+Pure additive config migration. Back-out: revert the code change and ship as the next patch — new/updated agents simply stop gaining the allow-rules. Already-migrated agents keep a `permissions.allow` block in their settings.json; it is harmless (it only ever skipped a prompt the operator didn't want in an unattended run) and an operator can delete it by hand if desired. No data migration, no agent-state repair, no user-visible regression during the rollback window.
+
+---
+
+## Conclusion
+
+The review produced no design changes. The fix is minimal, additive, idempotent, and scoped to the exact mechanism (inherited permission rules) that controls sub-agent prompting. It preserves all real safety (the PreToolUse guard chain) and only removes the human-in-the-loop prompt that was freezing unattended autonomous runs. Clear to ship pending second-pass concurrence.
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** general-purpose reviewer subagent
+**Independent read of the artifact: concur**
+
+Concur with the review. The reviewer independently verified, against Claude Code docs, that PreToolUse hooks run BEFORE permission-rule evaluation and a hook exiting 2 blocks the call even when the tool is in `permissions.allow` — the docs describe exactly this pattern (Bash in allow + a PreToolUse guard) as the recommended architecture, so the safety argument holds. Key corroboration: the SAME `migrateSettings()` pass calls `ensureInstarBashPreToolUseHooks()` (which registers the full `INSTAR_BASH_PRETOOLUSE_HOOKS` guard chain) BEFORE `ensurePermissionAllowRules()`, so any agent that gains the allow-rules gains the blocking guards in the same migration — no race, no window where allow-rules exist without the guards. Idempotency, non-clobbering of operator deny/ask, mcp__* exclusion, and the absence of any shared-array mutation were all confirmed. Non-blocking note: the allow list is a fixed in-code array; a future new built-in subagent tool won't be covered until the list is updated — benign failure direction (it would prompt, not over-allow).
+
+---
+
+## Evidence pointers
+
+- `tests/unit/PostUpdateMigrator-permissionAllowRules.test.ts` — 6 tests: adds all subagent tools when absent; includes Bash; does NOT blanket-allow MCP; preserves operator allow entries + no dupes; never touches deny/ask; idempotent on second pass. All passing.
+- Adjacent regression: `tests/unit/PostUpdateMigrator-cleanupPeriodDays.test.ts` still green (same `migrateSettings` path).
+- `npm run build` green on the worktree.