instar 1.2.5 → 1.2.7

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "instar",
-  "version": "1.2.5",
+  "version": "1.2.7",
   "description": "Persistent autonomy infrastructure for AI agents",
   "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-21T16:21:18.911Z",
-  "instarVersion": "1.2.5",
+  "generatedAt": "2026-05-21T17:33:33.304Z",
+  "instarVersion": "1.2.7",
   "entryCount": 191,
   "entries": {
     "hook:session-start": {
@@ -392,7 +392,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:agents": {
@@ -400,7 +400,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:backups": {
@@ -408,7 +408,7 @@
       "type": "route-group",
       "domain": "operations",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:git": {
@@ -416,7 +416,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:memory": {
@@ -424,7 +424,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:semantic": {
@@ -432,7 +432,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:status": {
@@ -440,7 +440,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:capabilities": {
@@ -448,7 +448,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:project-map": {
@@ -456,7 +456,7 @@
       "type": "route-group",
       "domain": "mapping",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:coherence": {
@@ -464,7 +464,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:topic-bindings": {
@@ -472,7 +472,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:context": {
@@ -480,7 +480,7 @@
       "type": "route-group",
       "domain": "context",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:scope-coherence": {
@@ -488,7 +488,7 @@
       "type": "route-group",
       "domain": "coherence",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:canonical-state": {
@@ -496,7 +496,7 @@
       "type": "route-group",
       "domain": "state",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:ci": {
@@ -504,7 +504,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:sessions": {
@@ -512,7 +512,7 @@
       "type": "route-group",
       "domain": "sessions",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:jobs": {
@@ -520,7 +520,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:skip-ledger": {
@@ -528,7 +528,7 @@
       "type": "route-group",
       "domain": "scheduling",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:telegram": {
@@ -536,7 +536,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:attention": {
@@ -544,7 +544,7 @@
       "type": "route-group",
       "domain": "communication",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:relationships": {
@@ -552,7 +552,7 @@
       "type": "route-group",
       "domain": "relationships",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:feedback": {
@@ -560,7 +560,7 @@
       "type": "route-group",
       "domain": "feedback",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:updates": {
@@ -568,7 +568,7 @@
       "type": "route-group",
       "domain": "updates",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:dispatches": {
@@ -576,7 +576,7 @@
       "type": "route-group",
       "domain": "dispatches",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:quota": {
@@ -584,7 +584,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:publishing": {
@@ -592,7 +592,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:private-views": {
@@ -600,7 +600,7 @@
       "type": "route-group",
       "domain": "publishing",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:tunnel": {
@@ -608,7 +608,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:events": {
@@ -616,7 +616,7 @@
       "type": "route-group",
       "domain": "networking",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:evolution": {
@@ -624,7 +624,7 @@
       "type": "route-group",
       "domain": "evolution",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:watchdog": {
@@ -632,7 +632,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:topic-memory": {
@@ -640,7 +640,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:state-sync": {
@@ -648,7 +648,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:intent": {
@@ -656,7 +656,7 @@
       "type": "route-group",
       "domain": "intent",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:triage": {
@@ -664,7 +664,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:operations": {
@@ -672,7 +672,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:sentinel": {
@@ -680,7 +680,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:trust": {
@@ -688,7 +688,7 @@
       "type": "route-group",
       "domain": "safety",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:monitoring": {
@@ -696,7 +696,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:commitments": {
@@ -704,7 +704,7 @@
       "type": "route-group",
       "domain": "commitments",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:episodes": {
@@ -712,7 +712,7 @@
       "type": "route-group",
       "domain": "memory",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:messages": {
@@ -720,7 +720,7 @@
       "type": "route-group",
       "domain": "coordination",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:system-reviews": {
@@ -728,7 +728,7 @@
       "type": "route-group",
       "domain": "monitoring",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "route-group:machine-mesh": {
@@ -744,7 +744,7 @@
       "type": "route-group",
       "domain": "security",
       "sourcePath": "src/server/routes.ts",
-      "contentHash": "de2d5dabf08599cfb7bfe454145369fc09fa511018231989c37117f45e237d44",
+      "contentHash": "909be5f4c0f174f688356cc66c804b363e61b118a7a4e754a3d5bc1474c8839b",
       "since": "2025-01-01"
     },
     "cli:init": {

package/upgrades/1.2.6.md

@@ -0,0 +1,42 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = internal refactor with new test surface, no behavioral change -->
+
+## What Changed
+
+**refactor(capabilities): /capabilities and its lint now share one source of truth — src/server/CapabilityIndex.ts.**
+
+PR #290 surfaced the discoverability gap that started the 2026-05-21 case study. PR #292 closed the workaround-reflex side by retiring the unsafe Secret Drop retrieval pattern. This release closes the last loose end: the /capabilities handler used to be a 440-line hand-curated object literal in routes.ts, and the discoverability lint kept a parallel hand-written INTERNAL_ALLOWLIST. Two surfaces had to stay in sync; nothing structurally enforced the sync.
+
+After this release:
+
+- A new module, src/server/CapabilityIndex.ts, holds the full registry — one entry per capability with a typed build function plus an INTERNAL_PREFIXES allowlist for operator-only routes.
+- The /capabilities handler in routes.ts shrinks from ~440 lines of inline logic to ~25 lines that iterate the index.
+- The discoverability lint in tests/unit/capabilities-discoverability.test.ts imports CAPABILITY_INDEX and INTERNAL_PREFIXES directly instead of duplicating policy in test code.
+- A new CapabilityIndex unit-test file pins module-level invariants: every entry key is unique, every prefix is unique across the registry, INTERNAL_PREFIXES has a reason on every entry, and the secrets entry continues to surface the hardened-retrieval hint.
+
+The response shape is unchanged. Every key that appeared in /capabilities before still appears with the same nested fields. Existing consumers (agents, dashboard, integration tests) see identical output.
+
+## What to Tell Your User
+
+No user-visible behavior change. Adding a new top-level route prefix to instar now requires a single deliberate classification in CapabilityIndex.ts — either claim it under a CAPABILITY_INDEX entry (surfaces it to agents) or add it to INTERNAL_PREFIXES with a one-line reason (skips discovery). The lint refuses unclassified prefixes at CI time, so the next primitive cannot slip through silently.
+
+## Summary of New Capabilities
+
+For the agent: nothing new at runtime. The /capabilities response carries the same data; the way it is produced is now a single iteration over a typed array.
+
+For contributors: a new file to maintain, but only when adding or renaming top-level route prefixes. The compiler enforces shape; the lint enforces classification.
+
+## Evidence
+
+Behavioral parity verified:
+- The 76-case integration suite that touches /capabilities (tests/integration/view-tunnel-routes.test.ts, tests/integration/publishing-routes.test.ts, tests/integration/external-operation-safety-routes.test.ts, tests/integration/imessage-routes.test.ts) passes unchanged.
+- The discoverability lint shrunk from 81 cases (with a hand-written allowlist) to 84 cases that read from the source-of-truth module. All green.
+- New CapabilityIndex.test.ts pins 9 invariants on the registry itself. All green.
+
+Spec: docs/specs/capabilities-introspection.md
+ELI16: docs/specs/capabilities-introspection.eli16.md
+Side-effects: upgrades/side-effects/capabilities-introspection.md
+
+Origin: 2026-05-21 case-study audit (topic 11141, follow-up #2 of two).

package/upgrades/1.2.7.md

@@ -0,0 +1,82 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: patch -->
+<!-- patch = bug fixes, refactors, test additions, doc updates -->
+
+## What Changed
+
+**fix(safe-fs): runtime artifacts under `<root>/.instar/` get a carve-out from the source-tree guard.**
+
+Closes the "agent goes dark on cold start" failure mode that surfaced after v1.2.4 in the field (Echo, 2026-05-21): every fresh launchd spawn hit `EADDRINUSE` on the stale unix socket at `.instar/listener.sock`, the `WakeSocketServer` stale-socket-recovery path correctly tried to unlink it, but `SafeFsExecutor` routed the unlink through `assertNotInstarSourceTree` and the guard fired because the agent's deployed directory IS a checkout of the instar source (same `.git`, same `.instar-source-tree` marker, same `package.json` with `name: "instar"`). The supervisor then escalated to its bind-failure recovery path and force-rebuilt better-sqlite3 on every cycle, which in turn produced an incompatible binary and the server never bound.
+
+The fix is a narrow carve-out in `SafeFsExecutor.guard()`: when the canonicalized target path is under a `.instar/` subdirectory of the source root, skip the source-tree guard. The carve-out is intentionally interior-only — the `.instar` directory itself is still protected (`safeRmSync` on `<root>/.instar` still throws `SourceTreeGuardError`). All five subdirectories that the project's own `.gitignore` excludes (`.instar/state/`, `.instar/logs/`, `.instar/audit/`, `.instar/instar-dev-traces/`, plus `.instar/shared-state.jsonl`) are runtime state, not source code, and destructive ops on them are a normal part of operation rather than a 2026-04-22-class incident.
+
+The guard's three layers (marker file, canonical origin URL, source-identity signature) are unchanged. The 2026-04-22 incident is still caught: that incident targeted source files at the tree root (`README.md`, `src/auth.ts`, `src/middleware.ts`), not anything under `.instar/`. The included tests verify both directions — the carve-out lets the right paths through, and source-tree paths outside `.instar/` (and `.instar` itself) still fault.
+
+## Why now
+
+After v1.2.4 every fresh boot of Echo on dawn-macbook entered the loop: lifeline restarts → WakeSocketServer EADDRINUSE → stale-socket-recovery blocked by guard → supervisor declares health-check failed → bind-failure escalation → force-rebuild better-sqlite3 → binary mismatch → loop. Manually unlinking the socket and bootstrapping cleanly worked once, but the next launchd respawn re-entered the loop because nothing fixed the structural block.
+
+## Audit trail
+
+The carve-out also leaves a positive audit signal: `safeUnlinkSync` (and siblings) emit an `outcome: "allowed"` entry to `.instar/audit/destructive-ops.jsonl` with `reason: "agent-runtime-state-carveout"` whenever the carve-out path is taken. Lets you see how often the runtime-state path is being exercised vs how often it would have been a false-positive block before.
+
+## Tests
+
+5 new tests in `tests/unit/SafeFsExecutor.test.ts` under `SafeFsExecutor agent-runtime-state carve-out`:
+
+- `allows unlink on a socket file under <root>/.instar/`
+- `allows unlink on a lock file under <root>/.instar/`
+- `allows rm on a nested file under <root>/.instar/state/`
+- `still BLOCKS rm on the .instar directory itself (not its contents)`
+- `still BLOCKS unlink on source files at the tree root`
+
+All 17 SafeFsExecutor tests pass (12 existing + 5 new).
+
+## Summary of New Capabilities
+
+This is a fix-only release. No new user-facing capabilities. The carve-out unblocks `WakeSocketServer.stale-socket-recovery`, `AutoUpdater` shadow-install management, and lifeline lockfile cleanup — all of which were already supposed to work but were silently blocked by the source-tree guard in agent mode.
+
+## What to Tell Your User
+
+If you're running an instar agent on macOS and have hit cold-start crash loops where the agent's logs say EADDRINUSE and reference SafeFsExecutor, this release fixes the underlying block. Pull v1.2.x (next), restart your agent. No config changes required, no migration needed.
+
+If you've never seen this — you're on a deployment style where the agent dir is NOT a checkout of the instar source, and the guard was never the problem. This release is a no-op for you.
+
+If you ran the manual workaround (rm .instar/listener.sock then bootstrap your launchd plist) — the workaround is no longer needed once this release is installed.
+
+## Evidence
+
+**Reproduction**: Run instar in agent mode where the agent's deployed directory is also a checkout of the instar source tree (the `~/.instar/agents/echo` pattern on dawn-macbook). Cold-start with a stale `.instar/listener.sock` present. Observed before this fix: `WakeSocketServer` attempts to unlink the stale socket via `SafeFsExecutor.safeUnlinkSync`, which throws `SourceTreeGuardError`. The supervisor's bind-failure escalation triggers (`Bind-failure escalation armed: N consecutive spawns failed before binding`). After 5 retries the supervisor enters 300s cooldown. Server never binds. Tunnel returns 502.
+
+**Observed before** (Echo, 2026-05-21T16:46Z, sample from `logs/lifeline-launchd.err`):
+
+```
+Error: stale socket at /Users/justin/.instar/agents/echo/.instar/listener.sock could not be unlinked:
+  Refusing to run src/threadline/WakeSocketServer.ts:stale-socket-recovery against the instar source tree
+  (requested dir: /Users/justin/.instar/agents/echo/.instar/listener.sock,
+   resolved git root: /Users/justin/.instar/agents/echo).
+[Supervisor] Bind-failure escalation armed: 34 consecutive spawns failed before binding.
+[Supervisor] Max restart attempts (5) reached. Cooling down for 300s before retrying.
+```
+
+**Observed after** (same agent, hot-patched 2026-05-21T17:00Z with the same source change applied to `shadow-install/.../SafeFsExecutor.js`):
+
+```
+$ curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:4042/health   # 5 times, 3s apart
+200
+200
+200
+200
+200
+
+$ curl -s -o /dev/null -w "%{http_code}\n" https://echo.dawn-tunnel.dev/health
+200
+```
+
+Tunnel-fronted dashboard at `https://echo.dawn-tunnel.dev/dashboard?session=<...>` returns HTTP 200 with the live dashboard HTML (316KB). The bind-failure escalation never fires. The audit log shows the carve-out's positive signal:
+
+```
+$ grep agent-runtime-state-carveout .instar/audit/destructive-ops.jsonl | head -3
+{"timestamp":"2026-05-21T17:00:23.118Z","executor":"fs","operation":"WakeSocketServer.ts:stale-socket-recovery","verb":"safeUnlinkSync","target":".../.instar/listener.sock","outcome":"allowed","reason":"agent-runtime-state-carveout","caller":"..."}
+```

package/upgrades/side-effects/capabilities-introspection.md

@@ -0,0 +1,119 @@
+# Side-Effects Review — Capabilities Introspection
+
+**Version / slug:** `capabilities-introspection`
+**Date:** `2026-05-21`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required` (pure refactor; response shape preserved; no new decision-point surface)
+
+## Summary of the change
+
+Extracts `src/server/CapabilityIndex.ts` as the single source of truth for the /capabilities self-discovery surface AND the discoverability lint that PR #290 introduced. The /capabilities handler shrinks from ~440 lines of inline build logic to ~25 lines that iterate the index. The lint rewrites to import the registry directly instead of maintaining a parallel hand-written allowlist. Adds a CapabilityIndex unit-test file that pins module-level invariants.
+
+Files touched:
+
+- `src/server/CapabilityIndex.ts` — new module (the registry).
+- `src/server/routes.ts` — /capabilities handler refactor.
+- `tests/unit/capabilities-discoverability.test.ts` — switch from inline allowlist to imports.
+- `tests/unit/CapabilityIndex.test.ts` — new module-level invariant tests.
+- `src/data/builtin-manifest.json` — regenerated hashes.
+- `upgrades/NEXT.md` — release notes.
+- `docs/specs/capabilities-introspection.{md,eli16.md}` — spec + ELI16.
+
+## Decision-point inventory
+
+- /capabilities response builder — **modify (refactor)** — same output, different production path.
+- Discoverability lint — **modify** — same invariant, different source of truth.
+
+No new gate/block surface. No runtime decisions changed.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The lint refuses CI for unclassified route prefixes (the desired behavior). A new route prefix that the author forgot to classify fails the lint with a precise error pointing at CapabilityIndex.ts.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The lint catches the structural gap (prefix not classified) but does not validate the SEMANTIC correctness of a classification — a contributor could claim a public agent-facing route under INTERNAL_PREFIXES with a bogus reason and the lint would pass. The reason field is reviewer-enforced, not machine-enforced. Acceptable: the reviewer is the right authority for semantic intent; the machine's job is to ensure the choice is made and documented.
+
+The CapabilityIndex.test.ts regression guard for the secrets entry's retrievalHint is intentionally narrow — it asserts the hint mentions `secret-drop-retrieve.mjs` and "NEVER prints the response body." A reviewer could weaken the hint in other ways that still pass the regex (e.g., remove the explicit warning against raw curl). That's a residual risk; the broader feature-delivery-completeness lint catches the related CLAUDE.md → /capabilities parity.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+Yes. The CapabilityIndex module sits in `src/server/` alongside routes.ts and SecretDrop.ts. It depends on the route-context type via a `type-only` import to avoid a circular module dependency at runtime. The lint sits in `tests/unit/` and imports from `src/server/` as a regular dependency, which is the standard test-to-source direction.
+
+A higher-level abstraction (e.g., deriving CAPABILITY_INDEX from the Express router at runtime) would not replace the classification step — the router doesn't carry semantic intent. The static registry is the right shape.
+
+---
+
+## 4. Signal vs authority compliance
+
+**Required reference:** [docs/signal-vs-authority.md](../../docs/signal-vs-authority.md)
+
+**Does this change hold blocking authority with brittle logic?**
+
+- [x] No — this change has no block/allow surface at runtime.
+
+The lint has CI-time block authority but only via the CI gate's enforcement; it emits a signal that a smart authority (the reviewer + branch protection) acts on. The lint's logic is straightforward set arithmetic — not a brittle heuristic.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** none. The /capabilities handler is the only consumer of the registry at runtime; the lint is the only consumer at test time.
+- **Double-fire:** none. Each invocation produces a fresh map; no shared mutable state.
+- **Races:** none. CAPABILITY_INDEX is a frozen const at module load; the build functions are pure.
+- **Feedback loops:** none. /capabilities reads from the registry; nothing writes back.
+
+The refactor preserves all existing consumers of /capabilities. Concretely verified: `tests/integration/view-tunnel-routes.test.ts` (privateViewer assertion), `tests/integration/publishing-routes.test.ts` (publishing assertion), `tests/integration/external-operation-safety-routes.test.ts` (externalOperationSafety assertion), `tests/integration/imessage-routes.test.ts` (imessage assertion) — all 76 cases pass unchanged.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Agents on the same machine:** see the same /capabilities response. Field names, nesting, values, iteration order all preserved.
+- **Dashboard:** unchanged. The dashboard reads the JSON and renders selected fields; field names are stable.
+- **External systems:** none touched.
+- **Persistent state:** none introduced.
+- **Timing / runtime conditions:** no measurable latency change. The iteration over CAPABILITY_INDEX is O(n) with n=~30; the prior inline literal was also O(n) at JIT eval time.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change. Revert the three new files (CapabilityIndex.ts, CapabilityIndex.test.ts, the spec/artifact docs) and the routes.ts diff. The lint test reverts to its prior body. No persistent state, no agent-state repair, no user-visible regression during the rollback window.
+
+Realistic rollback: revert + patch release. Under 5 minutes.
+
+---
+
+## Conclusion
+
+This is a low-risk refactor that closes the parallel-surfaces gap introduced by PR #290. The /capabilities response shape is preserved byte-for-byte; the lint is now anchored to a typed module instead of a hand-maintained test allowlist; module-level invariants are pinned by a new test file. No second-pass review required.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/capabilities-introspection.md`
+- ELI16: `docs/specs/capabilities-introspection.eli16.md`
+- New tests: `tests/unit/CapabilityIndex.test.ts` (9 cases), refactored `tests/unit/capabilities-discoverability.test.ts` (84 cases). All green.
+- Integration tests that exercise /capabilities (76 cases) pass unchanged.
+- `npx tsc --noEmit` clean.
+- Origin: 2026-05-21 case-study audit (topic 11141, follow-up #2 of two).