instar 1.3.230 → 1.3.231

package/package.json

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

package/src/scaffold/templates.ts

@@ -650,6 +650,11 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Returns \`{ totals, features: [{ feature, calls, tokensIn, tokensOut, fired, noop, fireRate, p50LatencyMs, p95LatencyMs, ... }] }\` — one row per system (e.g. MessagingToneGate, CoherenceReviewer). Filter with \`?feature=<name>\`.
 - **When to use**: when asked "which checks cost the most / fire the least?", "is this gate worth it?", or before tuning a sentinel/gate — read the numbers instead of guessing. (Spec: \`docs/specs/llm-feature-metrics-spec.md\`.)
 
+**Resource Usage (rate-limit events)** — Durable per-agent record of rate-limit events, so they survive restarts instead of vanishing. Every circuit-breaker trip (the account got throttled) and session-sentinel detection is written down. Read-only observability — it never gates. (Phase A; CPU/memory tracking is a follow-up.)
+- Check: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/resources/rate-limits?sinceHours=24"\`
+- Returns \`{ windowHours, summary: { circuitOpenCount, circuitRecoverCount, sentinelCount, tripsPerHour, ... }, byKind, events }\`. \`circuitOpenCount\` is the headline (breaker trips); \`sentinelCount\` is session-scoped detections, counted separately.
+- **When to use**: when asked "how many times were we throttled today?", "is the rate-limit pressure getting worse?", or before/while tuning anything that reacts to rate limits — read the durable count instead of guessing. (Spec: \`docs/specs/per-agent-resource-ledger.md\`.)
+
 **Session Clock** — How long have you been running, and how much time is left? For any active time-boxed (autonomous) session, this returns the computed elapsed + remaining so you never have to guess or compute it yourself. Read-only observability.
 - Check: \`curl -H "Authorization: Bearer $AUTH" "http://localhost:${port}/session/clock"\` (optional \`?topic=<N>\` to bind to one session)
 - Returns \`{ now, nowIso, sessions: [{ label, kind, startedAt, endsAt, elapsedSeconds, remainingSeconds, elapsedHuman, remainingHuman, percentElapsed, status }] }\`; \`{ sessions: [] }\` when nothing is time-boxed. Per-machine (the record is local).

package/upgrades/1.3.231.md

@@ -0,0 +1,39 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+**Rate-limit events are now recorded durably (per-agent ResourceLedger, Phase A).**
+Until now, every time the account got throttled — a circuit-breaker trip, or a
+session hitting Anthropic's server-side rate limit — was counted only in
+process-local memory and lost on restart, so "how many times were we throttled
+today?" had no answer. This adds a small read-only SQLite ledger
+(`server-data/resource-ledger.db`, same pattern as the TokenLedger) that persists
+each rate-limit event, fed by a minimal new trip/recover observer on the circuit
+breaker plus the existing RateLimitSentinel.
+
+New read-only route `GET /resources/rate-limits?sinceHours=N` returns the durable
+count + rate (breaker trips as the headline; session-sentinel detections counted
+separately) and recent events. Default-on (event-driven, negligible cost);
+`monitoring.resourceLedger.enabled: false` opts out. It never gates or changes any
+behavior — the breaker observer is wrapped so a listener error can never affect
+the breaker. CPU/memory tracking and a unified `/resources` snapshot are Phase B.
+
+Spec: `docs/specs/per-agent-resource-ledger.md`.
+
+## What to Tell Your User
+
+Nothing to configure. Your agent now keeps a durable record of how often it's
+being rate-limited, so that history survives restarts instead of resetting to
+zero. You can ask it how many times it was throttled today, or whether the
+pressure is getting worse, and it can answer from real recorded numbers.
+
+## Summary of New Capabilities
+
+- New read-only endpoint GET /resources/rate-limits (durable rate-limit-event
+  count, rate, and recent events).
+- Circuit-breaker trips and session rate-limit detections are now persisted
+  across restarts instead of being lost.
+- New config flag monitoring.resourceLedger.enabled (default on).

package/upgrades/side-effects/resource-ledger-phase-a.md

@@ -0,0 +1,101 @@
+# Side-Effects Review — Per-agent ResourceLedger, Phase A (durable rate-limit events)
+
+**Version / slug:** `resource-ledger-phase-a`
+**Date:** `2026-06-03`
+**Author:** `Echo (instar-dev agent)`
+**Second-pass reviewer:** `not required`
+
+## Summary of the change
+
+Phase A of `docs/specs/per-agent-resource-ledger.md`: a durable, read-only store
+for rate-limit events, so breaker trips + session-sentinel detections survive
+restarts (today they're process-local and vanish). New:
+- `src/monitoring/ResourceLedger.ts` — SQLite store (`rate_limit_events`),
+  TokenLedger pattern (NativeModuleHealer/WAL/registerSqliteHandle), swallow-on-write.
+- `src/monitoring/ResourceLedgerPoller.ts` — event-driven; subscribes to the
+  breaker observer (+ optional RateLimitSentinel) and writes one row per emission.
+- `src/core/LlmCircuitBreaker.ts` — added a minimal `onTrip`/`onRecover` observer
+  (emit in `onRateLimited` and on open→closed `onResolved`).
+- `src/server/AgentServer.ts` — construct ledger (own try/catch) + start poller
+  (breaker = `getLlmCircuitBreaker()`); inject into route ctx; stop on shutdown.
+- `src/server/routes.ts` — `GET /resources/rate-limits` (503 on null ledger).
+- `src/config/ConfigDefaults.ts` — `monitoring.resourceLedger.enabled` (default on).
+- `src/scaffold/templates.ts` — CLAUDE.md Capabilities entry (Agent Awareness).
+
+## Decision-point inventory
+- `LlmCircuitBreaker.onRateLimited / onResolved` — **modify (additive emit only)** —
+  fire observer callbacks; no change to gating/state logic.
+- `ResourceLedger` writes, route, poller, config default, template — **add**.
+
+## 1. Over-block
+No block/allow surface — not applicable (read-only observability).
+
+## 2. Under-block
+No block/allow surface. (Phase A captures breaker trips + sentinel detections; it
+does not claim to capture every provider 429 — the breaker trip is the canonical
+account-level signal, sentinel detections are counted separately by `source`.)
+
+## 3. Level-of-abstraction fit
+Correct. The ledger is a recorder, not an authority; it FEEDS the read-only
+`/resources` surface and never gates. The breaker observer is a pure side-channel
+on a component that DOES hold gating authority — see §4.
+
+> CI-fix addendum (full-suite caught two regressions the local subset missed,
+> both no-behavior-change): (a) the new `/resources` route prefix was unclassified
+> in `CapabilityIndex` — added a read-only `resourceLedger` capability entry
+> (enabled only when `ctx.resourceLedger` exists); (b) `ResourceLedger.ts`
+> registers a SQLite handle so it was added to the `SqliteRegistry-wiring` test's
+> `LONG_LIVED_STORES` allowlist. No new surface; purely discoverability/test wiring.
+
+## 4. Signal vs authority compliance
+**Required reference:** docs/signal-vs-authority.md
+- [x] No — this change has no block/allow surface of its own.
+
+The one sensitive point: `LlmCircuitBreaker` holds real blocking authority (it
+gates ALL LLM work). I added an *observer* to it, NOT logic that affects gating.
+Safety properties, all tested (`tests/unit/llm-circuit-breaker-observers.test.ts`):
+- `emitTrip`/`emitRecover` iterate listeners inside a per-listener `try/catch`, so
+  a throwing observer **cannot** propagate into the breaker — verified by a test
+  that registers a throwing listener and asserts `onRateLimited` doesn't throw and
+  `tripCount` is still correct.
+- The emit happens AFTER all state mutation (last line of `onRateLimited`; end of
+  `onResolved`), so an observer can never see/affect an intermediate state.
+- The 30 existing breaker tests still pass unchanged — no behavioral drift.
+
+## 5. Interactions
+- **Shadowing/double-fire:** none. The observer is additive; the breaker's
+  acquire/onRateLimited/onResolved behavior is byte-identical to before.
+- **Races:** the poller's per-source `seq` + the ledger's `(source,ts,seq)` id +
+  `INSERT OR IGNORE` make writes idempotent; a replay can't double-count.
+- **Lifecycle:** ledger constructed in its OWN try/catch in AgentServer (cascade
+  isolation — a failure can't 503 TokenLedger/FeatureMetricsLedger); poller
+  `stop()` unsubscribes the breaker observer + the ledger closes on shutdown.
+- **Feedback loops:** none — observe-only.
+
+## 6. External surfaces
+- New route `GET /resources/rate-limits` (additive; Bearer-auth; read-only).
+- Persistent state: a new `server-data/resource-ledger.db` per agent. No schema
+  change to existing DBs. Naturally bounded (~hundreds of events/day) — no
+  retention needed for `rate_limit_events` (the high-frequency `resource_samples`
+  table that WILL need retention is Phase B, not in this PR).
+- Config: `monitoring.resourceLedger.enabled` default true (ships ON — event-driven,
+  negligible cost; `false` leaves the ledger null and the route 503s).
+
+## 7. Rollback cost
+Pure additive code + a new DB file. Revert and ship a patch; the orphaned
+`resource-ledger.db` is harmless (nothing else reads it). No migration of existing
+state, no agent-state repair, no user-visible regression.
+
+## Conclusion
+Complete, working Phase A with all three test tiers green (unit store+emitter+poller
+incl. a real-breaker→real-ledger wiring test; integration route 200/503; e2e
+"feature is alive" 200 on the real AgentServer init path). The only authority-
+adjacent edit (the breaker observer) is provably unable to affect gating. CPU/mem
+sampling + retention + the unified `/resources` snapshot + dashboard are Phase B
+(specced, not in this PR). Clear to ship.
+
+## Evidence pointers
+- `tsc --noEmit` clean; vitest green: `ResourceLedger.test.ts` (6),
+  `ResourceLedgerPoller.test.ts` (4), `llm-circuit-breaker-observers.test.ts` (4),
+  `llm-circuit-breaker-wait.test.ts` (30, unchanged),
+  `resources-rate-limits-routes.test.ts` (2), `resources-rate-limits-lifecycle.test.ts` (3).