instar 1.3.684 → 1.3.685

package/package.json

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

package/upgrades/1.3.685.md

@@ -0,0 +1,37 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: patch -->
+
+## What Changed
+
+Added the **operator-approval route** (`POST /mcp/approve`) for the Dynamic MCP
+Lifecycle (⚗️ experimental, dark) — the piece that lets an **interactive** session
+(not just an autonomous-preapproved one) complete a load-on-demand. It is **PIN-gated**
+(the dashboard PIN), so the agent — which holds only the shared Bearer token and never
+the PIN — structurally cannot reach it to self-approve. The operator supplies the
+server-minted nonce (which the agent surfaced) plus the PIN, and the change completes
+via the existing `{kind:'operator-approved'}` path. This is the concrete completion of
+the C4 "agent can't approve its own change" invariant the dynamic-MCP spec required.
+
+Still dark by default. NOT yet operator-complete: the Mobile-Complete "tap to approve"
+surface (so the operator taps rather than POSTs) is the explicit next increment.
+
+## What to Tell Your User
+
+If a user asks "how do I approve the agent loading a tool mid-chat?" — once the
+feature is enabled, the agent surfaces the request and the user approves it with their
+dashboard PIN; the agent cannot approve on its own behalf.
+
+## Summary of New Capabilities
+
+- `POST /mcp/approve` — operator-PIN-authenticated approval of a non-preapproved MCP
+  load/offload (dark; 503 when the feature is off).
+
+## Evidence
+
+14 integration tests over the real createRoutes pipeline, including the full round
+trip (agent `needs-approval` → server-minted nonce → operator PIN + nonce → `applied`),
+plus the C4 cases (no PIN ⇒ 403, wrong PIN ⇒ 403, wrong/expired nonce ⇒ 403
+needs-approval). Backed by the converged+approved DYNAMIC-MCP-LIFECYCLE-SPEC, which
+named this route as the follow-up. tsc clean.

package/upgrades/side-effects/dynamic-mcp-operator-approval-route.md

@@ -0,0 +1,44 @@
+# Side-effects review — dynamic-MCP operator-approval route (POST /mcp/approve)
+
+**Change:** Add `POST /mcp/approve` to routes.ts — the operator-authenticated approval
+for a non-preapproved interactive load/offload. The DYNAMIC-MCP-LIFECYCLE-SPEC named
+this as the follow-up so an INTERACTIVE session (not just an autonomous-preapproved
+one) can complete a load-on-demand.
+
+## 1. Blast radius
+Zero until enabled. The route 503s when `dynamicMcpService` is absent/disabled (dark
+default), exactly like the other /mcp/* routes.
+
+## 2. Reversibility
+Fully reversible — remove the handler + route.
+
+## 3. State / data touched
+None new. On a valid PIN + nonce it calls the existing
+`DynamicMcpService.requestLoad/Offload(..., {kind:'operator-approved', nonce})`, which
+consumes the server-minted nonce and (on success) drives the existing gated change.
+
+## 4. Failure modes
+Fail-closed: 503 (dark) / 403 (no PIN, wrong PIN) / 400 (missing topicId/server/nonce)
+/ 403 needs-approval (nonce wrong/expired ⇒ the approval did NOT take). A wrong nonce
+can never approve; a wrong PIN can never approve.
+
+## 5. Security / authority — THE load-bearing review (C4 + Know Your Principal)
+The route is **PIN-GATED** (the dashboard PIN, via the existing rate-limited
+checkMandatePin). The agent holds only the shared Bearer token and NEVER the PIN
+(CLAUDE.md: the PIN is operator-only), so the agent **structurally cannot reach this
+route to self-approve** — this is the concrete completion of the C4 invariant: an
+interactive change completes only via a live preapproval OR this operator-PIN-
+authenticated path. The agent-facing /mcp/load|offload routes still NEVER honor a body
+nonce. The operator supplies the nonce (which the agent surfaced) + the PIN together.
+
+## 6. Operator-surface quality (honest)
+This commit ships the MECHANISM (the route), not yet the Mobile-Complete tap surface.
+Until a dashboard "Approve" button lands (the explicit next increment), an operator
+would have to POST the route — which does NOT meet "Operators Act in Taps, Not Text".
+So this is NOT operator-complete yet; it is the auth-correct mechanism the tap surface
+will call. Not claimed as done.
+
+## 7. Tests
+14 integration tests (+5): 503 dark; PIN required (no pin ⇒ 403 — agent can't
+self-approve); wrong PIN ⇒ 403; the real round trip (agent needs-approval → nonce →
+operator PIN+nonce ⇒ applied); wrong nonce ⇒ 403 needs-approval. tsc clean.

package/upgrades/side-effects/pending-mcp-approval-store.md

@@ -0,0 +1,33 @@
+# Side-effects review — PendingMcpApprovalStore (operator-approval tap-surface foundation)
+
+**Change:** New `src/core/PendingMcpApprovalStore.ts` — an in-memory registry that
+lets the operator-approval tap surface put an OPAQUE requestId in the link while the
+server-minted nonce stays server-side (vs. a nonce-in-URL leak). 6 unit tests.
+
+## 1. Blast radius
+Zero at runtime. No importer yet — the approval-page routes (the next increment,
+sequenced after the live-test informs the UI) will use it. Inert + dark-feature.
+
+## 2. Reversibility
+Fully reversible — delete the file + tests. In-memory only; no persisted state.
+
+## 3. State / data touched
+None on disk. An in-memory Map keyed by an opaque requestId → {topicId, kind, server,
+nonce, expiresAt}, TTL-pruned.
+
+## 4. Failure modes
+Fail-closed: peek/consume return null on absent/expired; consume is single-use
+(removes regardless). peek NEVER returns the nonce (the page can't leak it).
+
+## 5. Security / authority
+The nonce is the approval secret; this store keeps it SERVER-SIDE and exposes it only
+once via `consume` (called by the PIN-gated submit), never via `peek` (the page). The
+opaque requestId carries no secret. No authority is exercised — it's a holding ledger;
+the PIN gate + nonce consume in the route are the authority.
+
+## 6. Framework generality
+Framework-neutral in-memory store; no launch/inject surface.
+
+## 7. Tests
+6 unit tests: opaque id + peek-never-leaks-nonce; single-use consume; peek-doesn't-
+consume; unknown-id null; TTL expiry (peek + consume); size/prune. tsc clean.