instar 1.3.394 → 1.3.395

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.394",
+  "version": "1.3.395",
   "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:01:10.022Z",
+  "instarVersion": "1.3.395",
   "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": {

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/side-effects/subscription-quota-poller.md

@@ -0,0 +1,71 @@
+# Side-Effects Review — QuotaPoller (P1.2)
+
+## Scope of change
+
+- `src/core/QuotaPoller.ts` (new) — per-account quota reader + mapper + burn rate.
+- `src/server/routes.ts` — 2 new routes under the existing `/subscription-pool`
+  prefix (POST `/subscription-pool/poll`, GET `/subscription-pool/:id/quota`) +
+  RouteContext `quotaPoller` field.
+- `src/server/AgentServer.ts` — threads the `quotaPoller` option → RouteContext.
+- `src/commands/server.ts` — instantiates the poller; starts the background loop
+  ONLY when the pool is non-empty.
+- tests (unit/integration/e2e).
+
+## Mutability / authority analysis
+
+- **External network call with a credential — the notable surface.** The poller
+  resolves each account's OAuth access token transiently from that account's own
+  config home and calls the READ-ONLY `GET /api/oauth/usage` telemetry endpoint.
+  It is NOT inference and NOT a mutation of any Anthropic-side state — it reads
+  usage stats, the same endpoint the official client's /usage screen calls. This
+  stays inside Justin's accepted decision-C bounds (subscription-only, official-
+  client login reused, no API keys). It is distinct from the inference-spoofing
+  Anthropic enforces against.
+- **Token handling (the security-sensitive part).** Tokens are read TRANSIENTLY
+  for the duration of one fetch and never persisted, never logged, never
+  returned. The SubscriptionPool still stores only the config-home LOCATION; the
+  poller reads the token from the OS credential store (macOS keychain entry
+  `Claude Code-credentials-<sha256(configHome)[0:8]>`, or `<configHome>/.credentials.json`
+  on other platforms) at read time only.
+- **Local writes.** The only persisted effect is writing each account's
+  `lastQuota` snapshot (and a `needs-reauth`/`active` status transition) into the
+  pool's single JSON file via the pool's existing atomic update path. No new
+  files, no deletes.
+- **No behavior authority.** The poller does not gate, block, spawn, kill,
+  message, route, or alter any session/scheduling behavior. It is observe-only;
+  the consumer that ACTS on quota (the swap scheduler) is P1.3.
+- **Frequency.** Background loop is low-frequency (default 15 min) and only runs
+  when the pool has ≥1 account. On-demand poll is available via the POST route.
+
+## Failure modes considered
+
+- **Unresolvable token** → account skipped, no snapshot (warn-logged, no token in log).
+- **401/403 (revoked / password change)** → account flagged `needs-reauth`; a
+  later clean read restores it to `active`. Covered both sides by tests.
+- **Network error / timeout** → null snapshot this cycle, status unchanged, retry
+  next cycle. Covered.
+- **Sparse/partial usage response** → mapper tolerates missing windows. Covered.
+- **Non-claude/disabled accounts** → skipped by pollAll. Covered.
+
+## Blast radius if wrong
+
+Contained. Dark (no accounts → no polling). Observe-only (no behavior change).
+Worst realistic case: a stale or missing `lastQuota` value on an account, or an
+account wrongly flagged needs-reauth (self-heals on the next clean read). No
+session/scheduling impact until P1.3 consumes the data.
+
+## Migration / parity
+
+None. No config defaults, hooks, skills, or CLAUDE.md template changes. New
+routes stay under the already-classified `/subscription-pool` INTERNAL prefix
+(no CapabilityIndex change). Ships via dist on update.
+
+## Tier rationale
+
+Declared Tier 1 despite risk-floor signals (new route + new class). The change
+is read-only external TELEMETRY, observe-only (no behavior authority), dark, with
+transient-never-persisted token handling and fully hermetic tests (injected fetch
++ token resolver — zero credentials, zero network). The one genuinely sensitive
+aspect — reading a per-account token to call the usage endpoint — is within the
+operator's explicitly-chosen decision-C bounds and is flagged to the operator in
+the progress report. Below-floor recorded for audit (the mind holds authority).