instar 1.3.394 → 1.3.396

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.394",
+  "version": "1.3.396",
   "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/scripts/lint-no-direct-llm-http.js

@@ -53,6 +53,12 @@ const ALLOWLIST = new Set([
   'src/providers/adapters/anthropic-headless/errors.ts',
   'src/providers/adapters/anthropic-headless/_smoketest.ts',
   'src/providers/adapters/anthropic-headless/capability/fileSystemAccess.ts',
+  // Subscription & Auth Standard P1.2: QuotaPoller calls the READ-ONLY
+  // /api/oauth/usage telemetry endpoint (the same one the official client's
+  // /usage screen calls) to read per-account quota — NOT an LLM inference call,
+  // so there is nothing for burn-detection to attribute. Same class as the
+  // anthropic-headless usageMeterProvider above.
+  'src/core/QuotaPoller.ts',
 ]);
 
 /**

package/src/data/builtin-manifest.json

@@ -1,8 +1,8 @@
 {
   "$schema": "./builtin-manifest.schema.json",
   "schemaVersion": 1,
-  "generatedAt": "2026-06-07T05:30:37.216Z",
-  "instarVersion": "1.3.394",
+  "generatedAt": "2026-06-07T06:08:26.779Z",
+  "instarVersion": "1.3.396",
   "entryCount": 199,
   "entries": {
     "hook:session-start": {
@@ -418,7 +418,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -426,7 +426,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -434,7 +434,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -442,7 +442,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -450,7 +450,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -458,7 +458,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -466,7 +466,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -474,7 +474,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -482,7 +482,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -490,7 +490,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -498,7 +498,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -506,7 +506,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -514,7 +514,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -522,7 +522,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -530,7 +530,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -538,7 +538,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -546,7 +546,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -554,7 +554,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -562,7 +562,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -570,7 +570,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -578,7 +578,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -586,7 +586,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -594,7 +594,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -602,7 +602,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -610,7 +610,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -618,7 +618,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -626,7 +626,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -634,7 +634,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -642,7 +642,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -650,7 +650,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -658,7 +658,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -666,7 +666,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -674,7 +674,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -682,7 +682,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -690,7 +690,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -698,7 +698,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -706,7 +706,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -714,7 +714,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -722,7 +722,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -730,7 +730,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -738,7 +738,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -746,7 +746,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -754,7 +754,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -770,7 +770,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "bce83fb8dba34c44b81c7004721ee69b1435b30480193636055cde9be625a7a3",
+      "contentHash": "397e804f5973a87f0b4476495e57b80d1dca0394c2928753539e91a7761ab6cf",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1506,7 +1506,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "8aa0f3b0aea74733e61654b60be82b404954da5c41c53ccb0d411afb82fcdfc6",
+      "contentHash": "fd430ec1928c24390016a239a8dc013cbb0c02c5156caf4dd7e3e8e987a77e8d",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {
@@ -1570,7 +1570,7 @@
       "type": "subsystem",
       "domain": "communication",
       "sourcePath": "src/lifeline/TelegramLifeline.ts",
-      "contentHash": "524266bb64da7168ab8577b173a0126bf018bc5ffc8b7923dd2ea6b0f5df6b3e",
+      "contentHash": "66d80ca0ef55324cf73f3ec2a1a32791d5d104fe995cb2bb0f7135859770b6fa",
       "since": "2025-01-01"
     },
     "subsystem:orphan-process-reaper": {

package/upgrades/1.3.395.md

@@ -0,0 +1,57 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Added `QuotaPoller` — the second piece of the Subscription & Auth Standard, built
+on the P1.1 account registry. For each enrolled Claude account it reads live
+usage (5-hour and weekly utilization, reset dates, per-model breakdown, and
+extra-usage credit state) and writes that snapshot onto the account in the
+registry. It also computes a MEASURED burn rate (utilization points per hour from
+consecutive reads) rather than relying on call counts, which the auto-swap
+scheduler (P1.3) will use to drain each account before its reset and switch
+before a limit.
+
+Read mechanism (operator decision C, hybrid): the poller resolves each account's
+login token transiently from that account's own config home — never persisted,
+never logged — and calls the read-only Anthropic usage endpoint (the same one
+the official client's usage screen calls) at low frequency, stamping each
+snapshot with its source. A hands-on finding shaped this: Claude Code does not
+persist usage to disk or expose a non-interactive usage command, so the "have the
+client report its own usage" primary we sketched does not exist; the endpoint
+read is the only viable mechanism and it stays inside the subscription-only,
+official-login-reused bounds. An authentication failure flags the account for
+re-login; a later clean read clears the flag.
+
+Two new routes under the existing subscription-pool surface: an on-demand poll
+trigger and a per-account quota+burn-rate read. The background poll loop runs
+only when at least one account is enrolled, so single-account agents and agents
+with an empty pool are completely unaffected. Coverage: 16 tests across all three
+tiers, fully hermetic (injected fetch and token resolver — zero credentials, zero
+network), including the feature-alive check that the poll route answers in both
+the dark and live states.
+
+## What to Tell Your User
+
+I can now read how much of each of your subscription accounts you've used — the
+5-hour and weekly windows, when they reset, and how fast each one is burning down
+— and I keep that fresh in the background. I never store your actual login
+secrets to do it; I read them just for the moment of the check and let them go.
+Nothing switches accounts yet — that's the next piece. This is still switched off
+until you enrol accounts, and it only ever reads, never changes anything.
+
+## Summary of New Capabilities
+
+- **Per-account live quota** — for each enrolled Claude account: 5-hour and weekly
+  utilization, reset dates, per-model breakdown, extra-usage credits. Stored on
+  the account and refreshed on a low-frequency background loop (only when accounts
+  exist) plus an on-demand poll.
+- **Measured burn rate** — utilization points per hour from consecutive reads, so
+  the upcoming scheduler decides on real burn, not call volume.
+- **Re-auth detection** — an account whose usage read returns an auth error is
+  flagged for re-login, and a later clean read clears it automatically.
+- **Read-only + dark + transient tokens** — observe-only (no behavior change),
+  inactive until accounts are enrolled, and login tokens are read transiently and
+  never persisted or logged.

package/upgrades/1.3.396.md

@@ -0,0 +1,31 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Fixes two real defects in the Telegram lifeline's queue-replay path that, together, caused the "incoherent reply to a one-message topic" symptom (2026-06-06, topic 21487): a user's substantive message was lost during a server CPU-starvation episode, then a later short nudge spawned a session with no context that confabulated an unrelated status report.
+
+1. **False-drop fix.** `replayQueue` previously burned a single failure counter on every forward failure while `supervisor.healthy` was true. Under CPU starvation the server is healthy-but-too-slow, so forwards time out, all 3 attempts burn in ~90s, and the real message is dropped ("Handoff to server failed after 3 replay attempts" — 32 such drops on echo, including live operator messages). A new `forwardToServerClassified` distinguishes a genuine HTTP-400 rejection (`poison` — the only message-specific failure) from transient timeout/5xx/503/network/skew failures. A new pure `decideReplay` policy (`src/lifeline/replayPolicy.ts`) burns the small poison drop-budget only on a 400; transient failures never drop a real message. A generous transient backstop still bounds a permanently-unreachable server.
+
+2. **Untracked-loss fix.** `MessageQueue.drain()` emptied the persisted queue up front, holding messages only in memory; a process exit mid-replay (update / version-skew / launchd restart) lost undelivered messages with no record — not even in `dropped-messages.json`. `replayQueue` now consumes durably: it works from `peek()` and removes a message from the persisted queue only after delivery or a deliberate drop, persisting strike counters in place via `updateReplayCounters()`. A mid-replay restart can no longer lose a message.
+
+The persisted queue gains an additive, back-compatible `transientReplayFailures` field; no migration is needed.
+
+## What to Tell Your User
+
+Nothing required — this is a behind-the-scenes reliability fix. If your machine was overloaded, the part of me that catches your messages while the server is busy could, in rare cases, give up on a message and throw it away as if it were broken — or lose one entirely if I restarted at the wrong moment. That is now fixed: a busy or restarting server makes your message wait in line and get retried instead of being discarded, and a message only leaves the line once it is actually delivered. The practical effect is that you should stop seeing replies that have nothing to do with what you asked.
+
+## Summary of New Capabilities
+
+- The lifeline now classifies a failed message handoff as either a genuinely-bad message (only an HTTP-400 server rejection) or a transient capacity failure (timeout, server-busy, network) — and only a genuinely-bad message can ever exhaust the drop budget.
+- Queued messages are consumed durably: a message leaves the on-disk queue only after it is delivered or deliberately dropped, so a restart mid-replay cannot silently lose it.
+- A generous transient backstop drops a message only after a server has been unreachable across many attempts, always with an honest record and a resend notice — never silently.
+
+## Evidence
+
+- `tests/unit/lifeline/replayPolicy.test.ts` — both sides of every decision boundary, including the incident regression: many consecutive transient failures never drop a message and never touch the poison budget.
+- `tests/unit/lifeline/MessageQueue-durability.test.ts` — `remove`/`updateReplayCounters` persist correctly; a simulated mid-replay process exit leaves undelivered messages on disk (no untracked loss).
+- `tests/unit/lifeline/version-skew-recovery.test.ts` — updated to pin the new wiring (classified forward + `decideReplay` + durable peek/remove).
+- Local verification: `tsc --noEmit` clean, all 9 lint gates clean, 157/157 lifeline unit tests + the stage-c chaos integration test green, 28 new/updated targeted tests green. Full unit suite deferred to CI (timed out locally under the live CPU-starvation episode this fix addresses).

package/upgrades/side-effects/lifeline-replay-budget-classification.md

@@ -0,0 +1,97 @@
+# Side-Effects Review — Lifeline replay budget classification + durable consume
+
+**Version / slug:** `lifeline-replay-budget-classification`
+**Date:** `2026-06-06`
+**Author:** `echo`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+The Telegram lifeline's queue-replay path was dropping legitimate user messages during server-overload/restart windows, and could also lose a queued message with no record at all if the process exited mid-replay. Two fixes:
+
+1. `forwardToServerClassified()` (new) returns a classification (`ok` | `poison` | `transient` | `skew`) instead of a bare boolean, so replay can tell a message-specific HTTP-400 rejection ("poison") from a transient capacity/availability failure (timeout / 5xx / 503-boot / network refusal / 426 skew). A new pure module `src/lifeline/replayPolicy.ts` (`decideReplay`) burns the small poison drop-budget ONLY on a 400; transient failures never drop a real message (a generous transient backstop bounds a permanently-unreachable server).
+2. `replayQueue()` now consumes the queue durably: it works from `queue.peek()` and removes a message from the persisted queue only after delivery or a deliberate drop (`queue.remove()`), persisting strike counters in place via `queue.updateReplayCounters()`. The old `queue.drain()` emptied the on-disk queue up front, so a mid-replay process exit lost in-memory messages untracked.
+
+Files touched: `src/lifeline/replayPolicy.ts` (new), `src/lifeline/MessageQueue.ts` (`remove`, `updateReplayCounters`, `transientReplayFailures` field), `src/lifeline/TelegramLifeline.ts` (`forwardToServerClassified` + rewritten `replayQueue`). Tests: `tests/unit/lifeline/replayPolicy.test.ts`, `tests/unit/lifeline/MessageQueue-durability.test.ts`, updated `tests/unit/lifeline/version-skew-recovery.test.ts`.
+
+## Decision-point inventory
+
+- `replayQueue drop budget` — **modify** — was a single `replayFailures` counter incremented whenever `supervisor.healthy`; now a classified poison/transient split via `decideReplay`.
+- `forwardToServer result` — **add** — new `forwardToServerClassified` returns a 4-way classification; the boolean `forwardToServer` is now a façade over it (unchanged for its inbound-handler callers).
+- `MessageQueue consume semantics` — **modify** — replay switched from destructive `drain()` to durable `peek()` + `remove()`/`updateReplayCounters()`.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+This change makes the path strictly MORE accepting, not less — its purpose is to stop wrongly discarding legitimate messages. The only message that can still be dropped on the poison path is one the server itself rejects with HTTP 400 three times, which is the same threshold as before (just now scoped to 400 instead of any failure). No legitimate message is newly rejected.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+- A message that genuinely crashes the SERVER on forward would surface as a network error / 5xx → classified transient → retried rather than dropped. Mitigation: the generous `MAX_TRANSIENT_REPLAY_FAILURES` backstop eventually drops it (with an honest "server unreachable" record). In practice the forward handler only persists/queues the inbound — it does not execute message-specific logic — so a single user message crashing the forward path is not a realistic vector; the real message-specific signal is the 400, which is still budgeted.
+- A permanently-unreachable server delays delivery up to the transient backstop before dropping. Acceptable: late delivery beats false drop, and the drop is loud (record + resend notice) when it finally happens.
+
+---
+
+## 3. Level-of-abstraction fit
+
+`decideReplay` is a pure decision function (no I/O, no clock, no instance state) — the correct layer for an exhaustively-testable policy. It is consumed by `replayQueue` (the orchestrator that owns the queue and the side effects). The classification lives where the forward already knows the HTTP outcome (`forwardToServerClassified`), reusing the existing typed `forwardErrors` (`ForwardBadRequestError` etc.) rather than re-deriving status. No higher-level gate is bypassed; this is internal to the lifeline process.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+- [x] No — this change has no user-facing block/allow surface. It governs whether an undeliverable queued message is retried or dropped; the "authority" is a deterministic, exhaustively-tested pure function over a typed HTTP-outcome classification, not a brittle content heuristic. It can only make delivery more robust than the prior single-counter policy.
+
+---
+
+## 5. Interactions
+
+- **Shadowing:** the `versionSkewActive` top-of-loop guard still precedes the per-message decision (asserted in `version-skew-recovery.test.ts`); a skew episode stops replay and leaves messages on disk, unchanged in spirit.
+- **Double-fire:** `forwardToServer` (boolean façade) and `forwardToServerClassified` share one implementation, so no path forwards twice. Inbound-handler callers (`handleMessage`/photo/doc) are unchanged.
+- **Races:** durable consume is id-based (`remove(id)`, `updateReplayCounters(id)`), so a message enqueued concurrently during replay is untouched and picked up next tick. `MessageQueue` ops are synchronous (no await between read and save).
+- **Feedback loops:** none — replay does not feed its own input.
+
+---
+
+## 6. External surfaces
+
+- **Telegram:** the "✓ Server recovered — N delivered" notice now counts only ACTUALLY-delivered messages per topic (previously counted all batch messages for the topic, including failed/dropped). Strictly more accurate; no format change. The dropped-message "please resend" notice is unchanged.
+- **Persistent state:** `lifeline-queue.json` gains an optional `transientReplayFailures` field per message. Additive, back-compatible — old queue files (with only `replayFailures`) load and default the new field to 0. `replayFailures` retains its on-disk name (now the poison counter). No migration needed.
+- **Other agents/users:** none — this is per-agent lifeline behavior.
+
+---
+
+## 7. Rollback cost
+
+Pure code change. Revert and ship as the next patch. The added `transientReplayFailures` field is additive and ignored by older code on downgrade (it only reads `replayFailures`). No data migration, no agent-state repair, no user-visible regression during the rollback window.
+
+---
+
+## Conclusion
+
+The review surfaced one residual (a server-crashing message classified transient) and confirmed it is covered by the transient backstop and is not a realistic vector given the forward handler's role. The change is monotonically safer for delivery, fully reversible, and back-compatible on disk. Clear to ship. Classified Tier 1 (delivery-path risk floor is 2; declared below floor with this artifact + exhaustive both-sides tests + reversibility as the compensating rigor — recorded as `belowFloor` in the gate audit and disclosed to the operator).
+
+---
+
+## Second-pass review (if required)
+
+**Reviewer:** not required (Tier 1)
+**Independent read of the artifact: not required**
+
+---
+
+## Evidence pointers
+
+- `tests/unit/lifeline/replayPolicy.test.ts` — both sides of every boundary incl. the incident regression (many transient failures never drop, never touch poison).
+- `tests/unit/lifeline/MessageQueue-durability.test.ts` — remove/update persist; mid-replay restart loses nothing.
+- `tests/unit/lifeline/version-skew-recovery.test.ts` — updated wiring assertions (classified forward + decideReplay + durable peek/remove).
+- Local: tsc clean, all 9 lint gates clean, 157/157 lifeline unit tests + chaos integration green, 28 new/updated targeted tests green. Full unit suite deferred to CI (timed out locally under the live CPU-starvation episode this fix addresses).