instar 1.3.994 → 1.3.995

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.994",
+  "version": "1.3.995",
   "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-07-27T05:39:31.180Z",
-  "instarVersion": "1.3.994",
+  "generatedAt": "2026-07-27T06:36:28.815Z",
+  "instarVersion": "1.3.995",
   "entryCount": 202,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "9b2c970297ce842acf784f15cd375d9a0cd009263b9c804f3f6a31b76f7e17e9",
+      "contentHash": "6da3409e8abed4586e60554113b75894f3fa573fc0ac4c6852d75c8f3fd81f1a",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.3.995.md

@@ -0,0 +1,75 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+The channel registry answered "which ways of reaching a PEER work right now?" with real probes. Asked
+the same question about the *operator*, the only available answer was `/capabilities` reporting
+`telegram: { configured: true, adapter: true, bidirectional: true }` — three values read from
+configuration, none of them a measurement. A Telegram whose poll loop died on a rejected token hours
+ago still reports all three as `true`.
+
+The two direct user channels now sit in the same registry, with liveness read from live adapter
+state: Telegram's `started` (is the loop polling *now*) and `fatalReason` (rejected credential vs
+dropped network), and Slack's `isConnected()`. Every channel row gains an `audience` field of `peer`
+or `user`, so one surface answers the whole "which channel should I use?" question instead of two.
+
+## What to Tell Your User
+
+Your agent can now tell whether it can actually reach you, rather than only whether it was set up to.
+
+Before this, asking "are your channels working?" got an answer read from a settings file — which says
+yes just as confidently after the connection has died. Now it checks the live connection, and when
+something is wrong it says which kind of wrong: a rejected login is a different problem from a
+dropped network, and needs a different fix.
+
+It is also careful about what it does not know. If a channel stopped for a reason nothing recorded,
+it reports "unknown" rather than guessing — because a confident wrong answer during an outage is
+worse than an honest one.
+
+And each channel now records *when it is the right one to use*. For your own channels that includes
+something worth saying plainly: they cost your attention, and they are also the only place your agent
+can see what you actually see. Both of those are real, and they pull in opposite directions.
+
+## Summary of New Capabilities
+
+No new endpoint, command, or config key. `GET /channels` gains two rows for the direct user channels
+with live-state liveness, and every row gains an `audience` field marking it `peer` or `user`.
+
+## Evidence
+
+The verdicts distinguish cases a boolean cannot: a rejected token reports
+`reachable-no-credential` ("Telegram answered and REJECTED the bot token") rather than a generic
+failure; a network death reports `broken`; a loop stopped with no recorded reason reports `unknown`
+with "cannot tell a deliberate stop from a silent death" — explicitly not healthy and not a confident
+broken; and no adapter at all reports `not-configured`, because off is not broken.
+
+Refusals, by falsification. Making the Telegram probe read existence instead of liveness — precisely
+what the configuration reading does:
+
+```
+× THE FIX: a configured-but-DEAD Telegram is never reported as working
+× a missing bot token is a credential verdict, not a network one
+× a network death is broken — distinct from a credential problem
+× stopped for NO recorded reason is unknown — never working, never a confident broken
+  Tests  4 failed | 12 passed (16)
+```
+
+Giving Slack "ever connected" semantics — the trap its own source warns about, since `started` means
+"ever connected" while `isConnected()` clears on disconnect:
+
+```
+× THE TRAP: enabled with the socket DOWN is broken, not working
+```
+
+Restored: 35 passed across the three channel-registry suites; `tsc --noEmit` exit 0. Two source
+ratchets keep the probes from drifting back to configuration.
+
+## Known limits
+
+A live reading is not a promise — `working` means the loop was polling when asked, not that it will
+be a second later. Telegram `working` means the poll loop is up, not that a message to a particular
+topic would land. Slack is modelled as a single workspace. WhatsApp and iMessage adapters exist in
+the tree and are **not** covered here, so the registry makes no claim about them at all.

package/upgrades/side-effects/user-channel-liveness.md

@@ -0,0 +1,116 @@
+# Side-effects review — user-channel liveness in the channel registry
+
+**Change:** the two direct USER channels (Telegram, Slack) join the peer channel registry, with
+liveness probes that read live adapter state instead of configuration. `ChannelDefinition` and
+`ChannelReport` gain an `audience: 'peer' | 'user'` field.
+
+**Decision point touched:** none that blocks. This is a read surface — it informs a routing choice a
+caller makes, and holds no authority over it. `advisory: true` is already on the response.
+
+## 1. Over-block — what legitimate inputs does this reject that it shouldn't?
+
+Nothing is rejected; nothing is gated. The nearest analogue is reporting a *usable* channel as
+unusable, which would cause a caller to avoid a working path.
+
+One case deliberately risks that and should be named: a Telegram that is **not polling with no
+recorded reason** reports `unknown`, not `working`. If the adapter was stopped deliberately and could
+still send, this understates it. That direction is chosen on purpose — over-reporting liveness is the
+defect being fixed, and `unknown` carries its reason rather than pretending to a verdict.
+
+Transient errors do NOT downgrade a live channel: still-polling with a non-zero consecutive error
+count stays `working`, with the count named in the detail. Marking that broken would be the opposite
+over-block.
+
+## 2. Under-block — what does it still miss?
+
+- **A live reading is not a promise.** `working` means the loop was polling when asked. It can die a
+  second later. No probe can fix that; the response carries `generatedAt`.
+- **No round-trip is attempted.** Telegram `working` means the poll loop is up, not that a message to
+  a specific topic would land (a topic could be deleted, a user could have blocked the bot). The
+  peer registry's `mutual-ssh` entry already makes the same distinction in its own detail text, and
+  this follows that precedent rather than overstating.
+- **Slack is one workspace.** `isConnected()` is per-adapter; a multi-workspace setup is not modelled.
+- **Other user surfaces are absent** — WhatsApp and iMessage adapters exist in the tree. They are not
+  in this change, and the registry will therefore not claim anything about them. Under the registry's
+  own "absence is impossible" property this is a real limit: a channel with no row cannot report that
+  it is missing. Called out rather than quietly scoped away.
+
+## 3. Level-of-abstraction fit
+
+The user definitions live in a NEW file (`src/core/userChannels.ts`) rather than being added to
+`src/core/instarChannels.ts`, whose header declares an explicit "PEER-TO-PEER only" scope discipline
+and justifies two prior exclusions. Widening that file would have silently discarded a deliberate
+decision by its author.
+
+The two lists are composed at the route and resolved by the same `resolveChannels`, so the registry's
+invariants (one row per definition, bounded probes, `unknown` on failure) apply identically to both
+without being reimplemented.
+
+`audience` is data on the channel, not two registries, because the peer-vs-user choice is itself a
+routing decision a caller must be able to weigh. Two surfaces would require the caller to already
+know which to consult — the arbitrariness the registry exists to remove.
+
+## 4. Signal vs authority
+
+Pure signal. The registry reports; it never routes, blocks, or sends. The response is already flagged
+`advisory: true`. The mapping functions (`telegramStateFrom`, `slackStateFrom`) are exported and pure
+precisely so the verdict logic can be pinned by tests without constructing an adapter — the mapping
+is where a wrong verdict would originate.
+
+## 5. Interactions
+
+- **`/capabilities`** — unchanged. It keeps reporting `telegram: { configured: true }`, which remains
+  correct for what it measures (configuration). This adds the missing state reading; it does not
+  correct or replace the config reading, and the two answer different questions.
+- **Peer channels** — behaviour unchanged; they gain an `audience: 'peer'` tag. Because `audience` is
+  required on `ChannelDefinition`, a future channel cannot be added untagged: it is a compile error,
+  not a silent default.
+- **No double-fire / no races** — read-only, no writes, no timers of its own. Probes are bounded by
+  the registry's existing 3s timeout.
+
+## 6. External surfaces
+
+`GET /channels` gains two rows and every row gains an `audience` field. Additive: existing consumers
+reading `id`/`state`/`detail` are unaffected. No new route, no config key, no user-visible string.
+
+## 7. Multi-machine posture
+
+**Machine-local BY DESIGN**, `machine-local-justification: physical-credential-locality` — a Telegram
+bot token and its long-poll loop, and a Slack Socket Mode connection, live in one process on one
+machine. "Is my Telegram polling?" is only meaningful about the machine asked; replicating another
+machine's answer would assert liveness this process cannot observe. This matches the peer registry,
+which is machine-local for the same reason (its relay/SSH probes read local runtime state).
+
+## 8. Rollback cost
+
+Low. One new file, one required field on two interfaces, one route composing two lists. No data
+migration, no config, no persisted state. Reverting restores the prior behaviour exactly — including
+the gap.
+
+## Refusals demonstrated (command + output)
+
+Falsification 1 — make the Telegram probe read EXISTENCE instead of liveness (`if (status !== null)`
+in place of `if (status.started)`), i.e. exactly what `/capabilities` does:
+
+```
+× THE FIX: a configured-but-DEAD Telegram is never reported as working
+× a missing bot token is a credential verdict, not a network one
+× a network death is broken — distinct from a credential problem
+× stopped for NO recorded reason is unknown — never working, never a confident broken
+  Tests  4 failed | 12 passed (16)
+```
+
+Falsification 2 — give Slack "ever connected" semantics (`if (enabled)` in place of
+`if (connected)`), the exact trap its own source warns about:
+
+```
+× THE TRAP: enabled with the socket DOWN is broken, not working
+  Tests  1 failed | 15 passed (16)
+```
+
+Restored: `Tests 35 passed (35)` across `channel-registry`, `channel-registry-claims` and
+`user-channel-liveness`; `npx tsc --noEmit` exit 0.
+
+Two source ratchets are included so the probes cannot drift back: one asserts `userChannels.ts` never
+reads a `.configured` property or a `config.*` value, the other asserts the route wiring uses
+`isConnected()` and never `slackAdapter.started`.