instar 1.3.683 → 1.3.685

package/upgrades/side-effects/dynamic-mcp-service.md

@@ -0,0 +1,41 @@
+# Side-effects review — dynamic-MCP composition service
+
+**Change:** New `src/core/DynamicMcpService.ts` — the composition root that
+assembles DynamicMcpManager + McpLoadedSetStore + McpApprovalNonceStore and wires
+them to INJECTED host primitives (restart, preapproval, pid capture/reap,
+mid-tool-use). Exposes getSessionState / requestLoad / requestOffload. 7 unit tests.
+
+## 1. Blast radius
+Zero at runtime. No importer yet — AgentServer wires it with real primitives in the
+final commit (behind the dark flag).
+
+## 2. Reversibility
+Fully reversible — delete the file + tests. No migration; consumes the dynamicMcp
+config block only when instantiated (which nothing does yet).
+
+## 3. State / data touched
+Indirectly via McpLoadedSetStore (writes `.instar/state/mcp-loaded/<topic>.json`)
+and reads `.mcp.json` — but ONLY when a caller invokes requestLoad/requestOffload,
+which only the tests do in this commit. Never mutates `.mcp.json`.
+
+## 4. Failure modes
+Inherits the manager's fail-safety (verified-auth, two-phase rollback, capture-then-
+reap, mid-tool-use abort). `.mcp.json` unreadable ⇒ [] names ⇒ a load is
+unknown-server no-op; currentServers falls back baseline→full safely.
+
+## 5. Security / authority
+The authority gate lives in the injected `isPreapproved` + the nonce store: a
+non-preapproved request returns needs-approval with a server-minted nonce and
+performs no restart. The service never trusts a caller-supplied approval; only a
+consumed nonce or a live preapproval proceeds.
+
+## 6. Framework generality
+Framework-neutral composition. The Claude-Code-specific surface lives in the
+primitives AgentServer injects (the restart maps SessionRefresh, which returns
+not_telegram_bound ⇒ unsupported-unbound for sessions it can't restart).
+
+## 7. Tests
+7 unit tests vs a real temp projectDir: lean-baseline state read; full load+restart+
+commit; not-preapproved ⇒ needs-approval then nonce authorizes; forged nonce
+rejected; offload drops+reaps; offload aborts on unknown mid-tool-use; failed
+restart leaves committed set unchanged (rollback). tsc clean.

package/upgrades/side-effects/dynamic-mcp-sweep-wiring.md

@@ -0,0 +1,46 @@
+# Side-effects review — dynamic-MCP idle-offload sweep wiring
+
+**Change:** Wire McpIdleOffloadSweep into AgentServer on a timer so the automatic
+idle-offload actually runs. Two edits:
+- `src/server/AgentServer.ts`: build the sweep with real deps (heavy-live-proc
+  listing via the reaper deps + resolveOwningSession; session→topic via
+  getTopicForSession; signature→server via the reverse map; mid-tool-use via the
+  live pane frame; requestOffload via the gated driver) and tick it on an
+  `.unref()`'d interval; clear it in `stop()`.
+- `src/core/dynamicMcpConfig.ts`: add the `sweep` config block type.
+
+## 1. Blast radius
+Dark + dryRun-first. The sweep timer is created ONLY when BOTH
+`sessions.dynamicMcp.enabled` AND `sessions.dynamicMcp.sweep.enabled` are true; and
+`sweep.dryRun` defaults true, so even then it only LOGS "would offload". Construction
+is wrapped (a fault ⇒ no sweep, never a broken boot). The e2e boot is unaffected
+(verified — no sweep config ⇒ no timer).
+
+## 2. Reversibility
+Fully reversible — remove the block + the config type. The timer is `.unref()`'d and
+cleared on stop, so it never holds the event loop or leaks across a restart.
+
+## 3. State / data touched
+Read-only at the host level (ps + tmux pane map + pane capture). When NOT dryRun and
+a server is eligible, it calls the gated `requestOffload`, which is the SAME path an
+explicit request uses (loaded-set state write + restart + capture-then-reap).
+
+## 4. Failure modes
+Fail-closed throughout: a busy/unknown mid-tool-use resets the idle clock; an
+unmapped server or non-topic session is skipped; a thrown tick is swallowed; the
+timer never keeps the process alive. The sweep adds NO new destructive path — it only
+DECIDES and delegates to the authorization-gated driver (which itself aborts on
+mid-tool-use, requires authorization, and reaps only captured pids).
+
+## 5. Security / authority
+No new authority. An idle-offload it triggers on a non-preapproved session returns
+needs-approval (no silent restart) exactly like an explicit request. dryRun (default)
+takes no action at all.
+
+## 6. Framework generality
+The timer/sweep are framework-neutral; the mid-tool-use probe is framework-aware.
+
+## 7. Tests
+The sweep orchestration has 9 unit tests (committed prior). This wiring is verified
+by the e2e AgentServer boot remaining green (no sweep config ⇒ no timer ⇒ unchanged),
+and tsc clean. A live run is part of the operator live-channel proof (the gate).

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.