instar 1.2.2 → 1.2.3

package/package.json

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

package/upgrades/1.2.3.md

@@ -0,0 +1,43 @@
+# Upgrade Guide — vNEXT
+
+<!-- bump: minor -->
+<!-- minor = new agent-facing capability without breaking changes -->
+
+## What Changed
+
+**feat(server): `/capabilities` now actually enumerates the primitives it claims to know about — and a lint locks the promise structurally.**
+
+The agent CLAUDE.md template tells every new agent: *"Before EVER saying 'I don't have' or 'this isn't available' — check what actually exists: `curl /capabilities`. It is the source of truth about what you can do."* That promise was silently false. `GET /capabilities` is a hand-curated object literal in `routes.ts`, and several agent-facing primitives lived as registered routes without ever appearing in the response:
+
+- **Secret Drop** — the safe-channel credential intake (`POST /secrets/request`, `/secrets/retrieve/:token`, `/secrets/pending`, `DELETE /secrets/pending/:token`). Agents that trusted `/capabilities` as authoritative reached for chat-paste / env-var workarounds because the discovery primitive didn't list it.
+- **CommitmentTracker** — `/commitments/*` CRUD that feeds PromiseBeacon.
+- **TokenLedger** — `/tokens/{summary,sessions,by-project,orphans}` for token-usage observability.
+- **SemanticMemory** — `/semantic/*`, the successor to the deprecated `/memory` endpoint.
+- **Private Viewer endpoints** — `POST /view`, `GET /views`, `GET/PUT/DELETE /view/:viewId` were behind a block that only reported a count.
+- **Telegraph publishing endpoints** — `POST /publish`, `GET /published`, `PUT /publish/:pagePath` were behind a block that only reported a count and a warning.
+
+This release surfaces all of the above in `/capabilities` with full endpoint listings, including a hardening note on the `secrets` block pointing at `.instar/scripts/secret-drop-retrieve.mjs` as the safe retrieval helper (raw `curl` against `/secrets/retrieve` leaks the secret into the Bash transcript).
+
+The structural enforcement is a new unit test, `tests/unit/capabilities-discoverability.test.ts`, that walks `src/server/routes.ts` for every top-level route prefix and asserts each either appears in the `/capabilities` response body or is on an explicit `INTERNAL_ALLOWLIST` with a one-line reason. Adding a new route prefix that is neither surfaced nor allowlisted will fail CI until the author makes a deliberate choice about discoverability.
+
+## What to Tell Your User
+
+No user-visible behavior change. Agents will, however, become more accurate about what they can do: when asked "can you do X?" they will read their live self-discovery surface first, and that surface now actually lists the full picture. The most visible improvement is that agents will reach for Secret Drop when a user needs to share a credential, instead of falling back to "paste it in chat" or "put it in an env var."
+
+## Summary of New Capabilities
+
+For the agent: the same primitives existed before, but they were only discoverable by reading the CLAUDE.md template — a ~1500-line document that is easy to skim past. Now they are first-class entries in the live `/capabilities` response.
+
+Quick check from an agent session:
+
+```bash
+curl -s -H "Authorization: Bearer $AUTH" http://localhost:$INSTAR_PORT/capabilities | jq '.secrets, .commitments, .tokens, .semantic, .privateViewer.endpoints, .publishing.endpoints'
+```
+
+## Evidence
+
+The discoverability gap was reproduced before the fix: `curl /capabilities | jq 'keys'` on v1.1.4 returned a 25-key object with no `secrets`, `commitments`, `tokens`, or `semantic` blocks, and `.privateViewer` / `.publishing` exposed only counts. After the fix, the same call returns all six blocks with explicit endpoint listings.
+
+The new lint test was verified end-to-end: with the `secrets` block removed from the response, `npx vitest run tests/unit/capabilities-discoverability.test.ts` fails with a precise error pointing the author at the missing entry; with the block restored, all 81 tests pass.
+
+Origin: case study seeded into topic 11141 ("🔍 Discoverability Secret Access") on 2026-05-20, root-cause audit on 2026-05-21.

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

@@ -0,0 +1,116 @@
+# Side-Effects Review — Capabilities Discoverability
+
+**Version / slug:** `capabilities-discoverability`
+**Date:** `2026-05-21`
+**Author:** `Echo (instar-developing agent)`
+**Second-pass reviewer:** `not required` (additive observability change with no decision-point surface)
+
+## Summary of the change
+
+Surfaces six previously-invisible primitives in the `GET /capabilities` response — `secrets`, `commitments`, `tokens`, `semantic`, plus explicit endpoint arrays on the existing `publishing` and `privateViewer` blocks. Adds a new unit test `tests/unit/capabilities-discoverability.test.ts` that walks `src/server/routes.ts` for every top-level route prefix and asserts each either appears in the `/capabilities` response body or is on an explicit `INTERNAL_ALLOWLIST` with a one-line reason.
+
+Files touched:
+
+- `src/server/routes.ts` — six additive blocks inside the existing `GET /capabilities` handler.
+- `src/data/builtin-manifest.json` — regenerated content hashes for the `route-group` entries that cover routes.ts.
+- `tests/unit/capabilities-discoverability.test.ts` — new lint test.
+- `upgrades/NEXT.md` — release notes.
+- `docs/specs/capabilities-discoverability.md` + `docs/specs/capabilities-discoverability.eli16.md` — spec + ELI16 companion.
+
+## Decision-point inventory
+
+- `GET /capabilities` response body — **modify (additive)** — the agent's authoritative self-discovery surface. Six new fields added; no existing field removed or shape-changed.
+- New lint test — **add** — fails CI if any route prefix isn't either surfaced or allowlisted. No runtime block authority.
+
+---
+
+## 1. Over-block
+
+**What legitimate inputs does this change reject that it shouldn't?**
+
+No block/allow surface — over-block not applicable. The runtime change is pure response-body enrichment. The lint test only blocks at CI when a new route prefix is registered without a discoverability decision being made; that's the intent.
+
+---
+
+## 2. Under-block
+
+**What failure modes does this still miss?**
+
+The lint asserts each prefix appears *somewhere* in the response body. It does NOT verify the surfaced entries actually match the live routes — a typo in the endpoint listing string ("POST /secrtes/request") would slip through. This is the minimum-viable bar; a follow-up could compare the endpoint strings against the actual registered routes. Tracked but not blocking.
+
+The lint also does not catch the case where a route prefix exists, is allowlisted as "surfaced inside X block," but X block was later removed. The allowlist is comment-anchored, not code-anchored. Acceptable because each allowlist entry has a one-line reason; reviewer catches drift on the next PR that touches X.
+
+---
+
+## 3. Level-of-abstraction fit
+
+**Is this at the right layer?**
+
+The runtime change is at the right layer: it enriches a response handler that already exists, no new module needed. The lint is at the right layer: a unit test that parses source, no server runtime needed, fast enough to run on every push.
+
+The deferred follow-up (introspecting `/capabilities` from `FeatureRegistry` + live router) would be a refactor at a higher layer — replacing the hand-curated object literal with a derivation. That's the right home for a future PR but would balloon scope here.
+
+---
+
+## 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 test holds CI-time block authority (it can fail a build), but that authority is delegated to a human reviewer + branch-protection rules; the lint itself just emits a signal. The runtime change is pure observability — no decision point is gated on the new fields.
+
+---
+
+## 5. Interactions
+
+**Does this interact with existing checks, recovery paths, or infrastructure?**
+
+- **Shadowing:** the `/capabilities` response is consumed by agents, by the dashboard, by `feature-delivery-completeness.test.ts`, and by `SeedMigration.test.ts`. All consumers do field-presence checks, not exact-shape assertions; additive fields are safe. Verified by running the full unit suite — no new failures introduced.
+- **Double-fire:** no overlap with other checks; `/capabilities` is a single read endpoint.
+- **Races:** no shared state introduced.
+- **Feedback loops:** none. The response is read-only.
+
+The new lint test reads `src/server/routes.ts` and the `INTERNAL_ALLOWLIST` literal. Its only "interaction" is with future PRs that add route prefixes — the lint will fail loudly until those PRs either surface or allowlist the new prefix. That's the intent.
+
+---
+
+## 6. External surfaces
+
+**Does this change anything visible outside the immediate code path?**
+
+- **Agents on the same machine:** yes — agents will see additional fields in `/capabilities`. All new fields are nested under new keys (`secrets`, `commitments`, etc.) or are new keys (`endpoints`) on existing nested objects. No existing key changes shape. Agents that ignore unknown keys continue to work; agents that iterate keys now see more capabilities, which is the intended behavior.
+- **Other users / install base:** no behavioral change. The next release will publish the enlarged response.
+- **External systems:** no external surface touched.
+- **Persistent state:** none — `/capabilities` is a read endpoint, no writes.
+- **Timing / runtime conditions:** the new blocks include `secretDrop.listPending().length` and reads of `ctx.publisher?.listPages()`, `ctx.viewer?.list()`. All three are cheap in-memory reads that the response already touched. No new latency surface.
+
+---
+
+## 7. Rollback cost
+
+**If this turns out wrong in production, what's the back-out?**
+
+Pure code change. Revert the two files (`src/server/routes.ts` and the new test) and the manifest will regenerate on the next build. No persistent state, no agent-state repair needed.
+
+User-visible regression during rollback window: the new `/capabilities` fields would disappear, and any agent that had started relying on them in the meantime would see a temporary loss of discoverability for those primitives. The primitives themselves keep working — only the discovery surface contracts.
+
+Realistic rollback cost: under 5 minutes, single revert + patch release. No downtime.
+
+---
+
+## Conclusion
+
+This is a low-risk additive observability change. It closes a structural-honesty gap in the agent's self-discovery surface and locks the promise with a lint that catches future regressions. The runtime change is pure response enrichment with no decision-point surface; the lint is a signal-only test that delegates block authority to the CI gate. Two follow-ups are explicitly deferred and tracked in the spec. No second-pass review required.
+
+---
+
+## Evidence pointers
+
+- Spec: `docs/specs/capabilities-discoverability.md`
+- ELI16: `docs/specs/capabilities-discoverability.eli16.md`
+- Repro of the gap (pre-fix): `curl /capabilities | jq 'keys'` on v1.1.4 returns no `secrets`, `commitments`, `tokens`, or `semantic` blocks.
+- Repro of the fix: the new unit test passes 81/81 with the additions in place; removing the `secrets` block from the response makes the corresponding test fail with a precise error pointing the author at the missing entry.
+- Origin: topic 11141 ("🔍 Discoverability Secret Access"), case study seeded 2026-05-20.