instar 1.3.73 → 1.3.74

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.3.73",
+  "version": "1.3.74",
   "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-05-29T01:32:22.569Z",
-  "instarVersion": "1.3.73",
+  "generatedAt": "2026-05-29T03:06:18.079Z",
+  "instarVersion": "1.3.74",
   "entryCount": 193,
   "entries": {
     "hook:session-start": {
@@ -409,7 +409,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -417,7 +417,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -425,7 +425,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -433,7 +433,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -441,7 +441,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -449,7 +449,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -457,7 +457,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -465,7 +465,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -473,7 +473,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -481,7 +481,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -489,7 +489,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -497,7 +497,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -505,7 +505,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -513,7 +513,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -521,7 +521,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -529,7 +529,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -537,7 +537,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -545,7 +545,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -553,7 +553,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -561,7 +561,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -569,7 +569,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -577,7 +577,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -585,7 +585,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -593,7 +593,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -601,7 +601,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -609,7 +609,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -617,7 +617,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -625,7 +625,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -633,7 +633,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -641,7 +641,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -649,7 +649,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -657,7 +657,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -665,7 +665,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -673,7 +673,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -681,7 +681,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -689,7 +689,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -697,7 +697,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -705,7 +705,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -713,7 +713,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -721,7 +721,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -729,7 +729,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -737,7 +737,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -745,7 +745,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -761,7 +761,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "5c238f63374ee42f2cfcae05b9642af8a23b50a7fd19d13a5043a2818ba97419",
+      "contentHash": "c61fc73ca69a17414aadfd5c095f7846d0dbaef9f7a2d2d7e67ca1dc5488881f",
       "since": "2025-01-01"
     },
     "cli:init": {
@@ -1457,7 +1457,7 @@
       "type": "subsystem",
       "domain": "server",
       "sourcePath": "src/server/AgentServer.ts",
-      "contentHash": "5e5b05a51602b7e5e5d863fffc3071af5eb5eaf1c8cc5ba5efa8d8e0a22458b1",
+      "contentHash": "c79bc89d11c4dde21ab48c9c6c90ad63ecc80aae9c7d3a968de49c438b38b2dc",
       "since": "2025-01-01"
     },
     "subsystem:session-manager": {

package/src/scaffold/templates.ts

@@ -415,6 +415,12 @@ This routes feedback to the Instar maintainers automatically. Valid types: \`bug
 - Also: when a session is autonomously shut down, you get a "your session was shut down — <reason>" notice (recovery-bounces and your own operator kills stay silent). Turn the notice off with \`{"monitoring": {"reapNotify": {"enabled": false}}}\`.
 - Proactive: user asks "where did my session go?" / "why did X disappear?" / "did something get killed?" → GET /sessions/reap-log and explain the most recent reaped/skipped entries for that session.
 
+**Sleep/Wake telemetry** — The "why does my agent keep restarting / saying it's overloaded?" answer. My SleepWakeDetector spots real machine sleep via timer drift, but on a CPU-oversubscribed box (many concurrent sessions, load ≫ cores) the event loop starves and a timer fires seconds late — which *looks* identical to a brief sleep. The CPU-starvation guard tells them apart: a short drift under high load (\`loadavg[0]/cpuCount > maxLoadRatio\`) is suppressed instead of triggering expensive wake-recovery (tunnel restart, re-registration) that would pile on more load; a long drift is always honored as real sleep; an emit cooldown caps the recovery rate. So "overloaded" is about CPU, NOT memory — check load average, not RAM.
+- Read it: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/monitoring/sleep-wake\` → \`{ wakeCount, totalSleepSeconds, longestSleepSeconds, suppressedCount, suppressedByReason: { 'cpu-starvation', cooldown }, lastSuppressedAt }\`. \`?sinceMs=<epoch>\` windows it. Read-only.
+- High \`suppressedCount\` (cpu-starvation) = the box is oversubscribed and the guard is absorbing false wakes — the real fix is fewer concurrent sessions / a less-loaded machine, not a code change.
+- Tune (rarely needed) in \`.instar/config.json\`: \`{"monitoring": {"sleepWake": {"maxLoadRatio": 1.5, "longSleepFloorSeconds": 300, "minWakeIntervalMs": 60000}}}\`. Defaults live in code, so the guard is active with no config.
+- Proactive: user reports "you keep restarting" / "your agent is overloaded" / "is it a memory problem?" → GET /monitoring/sleep-wake, then check \`uptime\` load average against core count; explain CPU oversubscription (load ≫ cores) vs. memory.
+
 **Multi-Session Autonomy** — I can run multiple autonomous jobs at once, one per topic (default cap 5, set \`autonomousSessions.maxConcurrent\` in config). Each topic's job is isolated, survives restarts, and is keyed on its topic.
 - What's running: \`curl -H "Authorization: Bearer $AUTH" http://localhost:${port}/autonomous/sessions\`
 - The cap + budget gate is checked automatically when a job starts (\`GET /autonomous/can-start\`); a start is refused when at the cap or under budget pressure.

package/upgrades/1.3.74.md

@@ -0,0 +1,95 @@
+# Instar Upgrade Guide — NEXT
+
+<!-- bump: patch -->
+
+## What Changed
+
+**The SleepWakeDetector no longer mistakes CPU starvation for machine sleep — the "my agent keeps restarting / it's overloaded" storm is fixed.**
+
+The detector spots real OS sleep by watching timer drift: a 2-second heartbeat
+that fires much later than expected means the process was suspended. But timer
+drift has **two** causes, and the detector treated both as sleep:
+
+1. **Real sleep** — the OS suspends the process; the wall clock jumps forward.
+2. **CPU starvation** — on an oversubscribed box (many concurrent agent sessions,
+   load ≫ cores) the event loop is so backed up it can't service the 2s timer on
+   time, so the callback fires seconds late. Nothing actually slept.
+
+On a heavily-loaded machine the second case fired constantly — in one real
+incident, **466 false "wake after ~8–29s sleep" events in a single server log**.
+Each false wake ran expensive recovery (Cloudflare tunnel force-restart that then
+timed out, re-registration, the lifeline `ServerSupervisor` resetting its
+failure counters), which piled *more* load onto the box — a self-reinforcing
+storm the user experienced as the agent endlessly "restarting due to overload"
+even though memory was completely fine.
+
+The detector now **classifies** drift instead of blindly trusting it:
+
+- **Short drift under heavy CPU load** (`loadavg[0] / cpuCount > maxLoadRatio`,
+  default `1.5`) is treated as event-loop starvation and **suppressed** — no wake
+  event, so none of the expensive recovery fires.
+- **A long drift** (`>= longSleepFloorSeconds`, default `300`) is *always* honored
+  as real sleep — a live event loop never starves for minutes (a watchdog would
+  declare the process dead first).
+- **A short drift under normal load** is a genuine brief sleep — emitted as before.
+- An **emit cooldown** (`minWakeIntervalMs`, default `60000`) caps how often wake
+  recovery can fire, so even a misclassified burst can't storm; long sleeps bypass
+  it. On Windows (`os.loadavg()` returns `[0,0,0]`) the load guard self-disables,
+  preserving prior behavior.
+
+Suppressed starvation drifts are deliberately kept *out* of the wake history, so
+`getCumulativeSleepMsBetween` (the wake-reaper's sleep-credit source) never counts
+starvation as if a job had slept through it.
+
+The thresholds live as defaults in the detector class, so **both** consumers — the
+server's wake-recovery handler and the lifeline's `ServerSupervisor` (which shares
+the class) — get the fix on update with no config migration. A new read-only
+route **`GET /monitoring/sleep-wake`** reports `wakeCount` (genuine sleep/wake) vs.
+`suppressedCount` with a `cpu-starvation` / `cooldown` breakdown — the visibility
+that was missing while the storm was happening.
+
+## What to Tell Your User
+
+If I've been telling you I keep "restarting because too many sessions are
+overloading the system," that message was half-right and half-misleading: the
+machine really was overloaded, but on **CPU**, not memory — so checking RAM
+looked fine and the warning seemed wrong. The cause was too many things running at
+once (lots of concurrent sessions / agents), which starved my internal timers and
+made me *think* the computer had gone to sleep and woken up — over and over,
+hundreds of times an hour. Each false "wake" kicked off heavy recovery work
+(restarting my tunnel, re-registering) that just added more load.
+
+I can now tell the difference between the machine actually sleeping and the
+machine just being too busy, so I stop overreacting to a busy moment. When things
+are genuinely overloaded I now ride it out quietly instead of thrashing. If you
+want to see it, ask me — I can show you how many real wakes vs. false ones I've
+absorbed, and I'll point you at the load average (not RAM) as the thing to watch.
+
+The real-world remedy when that number is high is still fewer things running at
+once or a less-loaded machine — but the agent will no longer make a busy box worse
+by storming itself.
+
+## Summary of New Capabilities
+
+| Capability | How to Use |
+|-----------|-----------|
+| CPU-starvation guard on sleep detection | Automatic. Short timer drift under high CPU load (`loadavg[0]/cpuCount > 1.5`) is classified as starvation and suppressed instead of triggering wake-recovery; long drift is always treated as real sleep. Fixes both the server's wake handler and the lifeline `ServerSupervisor`. |
+| Sleep/wake telemetry route | `curl -H "Authorization: Bearer $AUTH" http://localhost:4040/monitoring/sleep-wake` → `{ wakeCount, totalSleepSeconds, longestSleepSeconds, suppressedCount, suppressedByReason: { 'cpu-starvation', cooldown }, lastSuppressedAt }`. `?sinceMs=<epoch>` windows it. |
+| Tunable thresholds | Optional `.instar/config.json` → `{"monitoring": {"sleepWake": {"maxLoadRatio": 1.5, "longSleepFloorSeconds": 300, "minWakeIntervalMs": 60000}}}`. Defaults live in code, so the guard is active with no config. |
+
+## Evidence
+
+- Unit: `tests/unit/sleep-wake-starvation-guard.test.ts` — classification boundary
+  (short-drift-high-load suppressed / short-drift-normal-load emitted /
+  long-drift-always-emitted), emit cooldown (suppress within window, long-sleep
+  bypass, re-emit after elapse), Windows `loadavg=[0,0,0]` self-disable,
+  `maxLoadRatio: Infinity` opt-out, and the cumulative-sleep exclusion of
+  suppressed drifts. Existing detector tests updated to inject idle load so they
+  test the drift mechanism independent of the host's real load.
+- Integration: `tests/integration/sleep-wake-routes.test.ts` — `GET
+  /monitoring/sleep-wake` returns 503 when unwired, 200 with the full wake +
+  suppression telemetry through the HTTP pipeline, and honors `?sinceMs` filtering.
+- E2E: `tests/e2e/sleep-wake-telemetry-lifecycle.test.ts` — boots the real
+  `AgentServer`, asserts the route is alive (200, not 503) + telemetry surfaces +
+  Bearer auth, plus a wiring-integrity guard that `server.ts` actually passes the
+  detector into `AgentServer` (anti-shipped-but-asleep).