instar 1.3.682 → 1.3.684

package/upgrades/1.3.684.md

@@ -0,0 +1,62 @@
+# Upgrade Guide — vNEXT
+
+<!-- assembled-by: assemble-next-md -->
+<!-- bump: minor -->
+
+## What Changed
+
+Added the **Dynamic MCP Lifecycle** (⚗️ experimental, ships DARK) — the on-demand
+loader for heavy MCP servers. MCP servers (Playwright's Chromium, Electron bridges)
+are heavy and mostly idle, and stacked idle copies were a dominant share of the
+process footprint behind the 2026-06-26 resource panic. This lets a claude-code
+session launch with a LEAN MCP set and load a heavy server only when it's needed
+(a `claude --resume` restart preserves the conversation), then offload it when idle.
+
+This ship lands the foundation + the load-on-demand path, all behind the explicit
+`sessions.dynamicMcp.enabled` flag (off by default — every `/mcp/*` route 503s when
+dark, and `buildSessionMcpFlags` returns a byte-identical launch). The design was
+converged via a two-reviewer adversarial pass (DYNAMIC-MCP-LIFECYCLE-SPEC), which
+caught and designed out two CRITICAL bugs before any code: the offload-leak (killing
+a session does NOT cascade to its MCP children — they reparent to launchd, so a naive
+offload would leak a Chromium) and an approval self-certification hole (the agent
+could have rubber-stamped its own change over the shared Bearer token).
+
+Tracked follow-ups before the dev-gate flip: the idle-offload background sweep + real
+process-cleanup, the operator-approval route (approve a load from a non-autonomous
+chat), and the live-user-channel proof (driving it through Telegram as the operator).
+
+## What to Tell Your User
+
+If a user asks "can you free up resources from idle browser/MCP servers?" or "why did
+my session restart to add a tool?", the agent now has a real mechanism for it
+(experimental, off by default): start a session lean, load a heavy tool only when
+needed, drop it when idle. During an autonomous run the agent loads on demand and
+carries on; otherwise it asks the operator before a restart, and it can never approve
+its own change.
+
+## Summary of New Capabilities
+
+- `GET /mcp/session/:topicId` — what MCP servers a topic's session is running with.
+- `POST /mcp/load` / `POST /mcp/offload` — request an on-demand load/offload
+  (Bearer-gated; authorization requires a live preapproval or an operator yes — the
+  agent cannot self-approve).
+- A lean baseline MCP set at spawn (`sessions.dynamicMcp.keepWarm`), fail-safe to the
+  full `.mcp.json`.
+- All dark by default (`sessions.dynamicMcp.enabled`); a no-op on single-server /
+  no-`.mcp.json` agents.
+
+## Evidence
+
+- **Spec:** `docs/specs/DYNAMIC-MCP-LIFECYCLE-SPEC.md` — converged (2 adversarial
+  reviewers, folded 2 CRITICAL + 9 MAJOR + 4 MINOR findings) + approved.
+- **Tests (three tiers, 98 across 10 files):** unit cores (baseline/mutation/idle
+  decision, driver orchestration incl. two-phase rollback + capture-then-reap + the
+  verified-auth gate, nonce store, loaded-set store, composition service,
+  buildSessionMcpFlags); integration (the `/mcp/*` routes over the real createRoutes
+  pipeline incl. the C4 body-nonce-rejection); e2e (the routes alive on the real
+  AgentServer boot — 200 enabled, 401 unauth, 503 disabled).
+- **Dark-safety:** a dedicated test asserts the spawn path is byte-identical when the
+  feature is off; the service construction is fail-safe (a throw ⇒ null ⇒ routes 503),
+  so a wiring fault can never break server boot.
+- **Awareness/migration:** the "Dynamic MCP Lifecycle" CLAUDE.md section ships to new
+  agents (generateClaudeMd) and existing agents (migrateClaudeMd, idempotent), tested.

package/upgrades/process-footprint-monitor.eli16.md

@@ -0,0 +1,47 @@
+# Process-footprint monitor — ELI16 overview
+
+## The problem in plain words
+
+On 2026-06-26 the machine running this agent crashed hard — a kernel panic that forced
+a reboot. The trigger was resource exhaustion: too many processes piled up on one
+machine (several full agent stacks plus their heavy helper "MCP" servers — a whole
+Chromium for the browser tool, an Electron app for another — most of them sitting idle).
+The number of processes climbed slowly over time until the operating system hit an
+internal limit and gave up.
+
+The painful part: nobody SAW it coming. The agent already tracks CPU and memory, but it
+never tracked the simplest, most relevant number for this kind of crash — *how many
+processes are running on this machine right now, and is that number climbing?* That
+measurement was missing, so the buildup was invisible until it was too late.
+
+## What this change does
+
+This adds a small, observe-only monitor that fills exactly that gap. On an interval it
+counts the agent-relevant processes on the machine and sorts them into buckets:
+
+- **agent CLIs** — the per-session reasoning processes (claude / codex / gemini),
+- **MCP servers** — the heavy, mostly-idle helper servers (Playwright's Chromium, etc.),
+  matched by the same precise signatures the cleanup sweep already uses,
+- **other node** — the agent's servers, lifelines, and wrappers.
+
+It keeps a rolling window of those readings so a TREND is visible — is the count rising,
+stable, or falling? You can read it any time:
+
+`GET /resources/footprint` → `{ enabled, latest: { total, byKind, rssBytes }, trend,
+overThreshold, samples }`
+
+## What it deliberately does NOT do
+
+It is **observe-only**. It never kills, throttles, or blocks anything — reclaiming
+processes is the job of the existing reapers. This monitor only MEASURES, so it can't
+cause harm. There is an optional heads-up that can fire when the count crosses a
+threshold, but it's off by default ("measure first") — the goal of this first step is
+just to make the climb visible.
+
+It ships **dark** (off on the fleet, on for development agents) so it's exercised here
+before any wider rollout, and every reading path fails safe: if the process scan fails,
+the monitor keeps its last reading rather than crashing. The route returns a clear
+"unavailable" (503) when the monitor is turned off.
+
+The point: the next time the process footprint starts climbing toward danger, it will be
+a number you can watch — not an invisible buildup that ends in a crash.

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

@@ -0,0 +1,36 @@
+# Side-effects review — dynamic-MCP agent awareness + migration
+
+**Change:** A "Dynamic MCP Lifecycle" CLAUDE.md section (honestly experimental/dark),
+delivered to new agents (generateClaudeMd) and existing agents (migrateClaudeMd) via
+one shared `DYNAMIC_MCP_CLAUDEMD_SECTION(port)` helper. 3 unit tests.
+
+## 1. Blast radius
+Documentation only. No runtime behavior, no gate, no route. New agents get the
+section at init; existing agents get it appended once on the next update.
+
+## 2. Reversibility
+Reversible — remove the helper + call sites + migration block. The migration is
+add-if-missing; it never rewrites or deletes existing CLAUDE.md content.
+
+## 3. State / data touched
+Appends one section to the agent's own CLAUDE.md on update (idempotent, content-
+sniffed on the heading). Nothing else.
+
+## 4. Failure modes
+The migration inherits migrateClaudeMd's guards (missing CLAUDE.md ⇒ skipped; read
+error ⇒ recorded, no crash). Idempotent: a second run is a no-op (test-verified
+byte-identical).
+
+## 5. Security / authority
+None. The section TEXT states the Know-Your-Principal authorization rule (the agent
+cannot self-approve), which is enforced in code elsewhere; this is awareness, not
+enforcement.
+
+## 6. Framework generality
+Documentation; the capability it describes is claude-code-scoped (stated in the
+text). No framework-launch surface touched.
+
+## 7. Tests
+3 unit tests: the section lands on an existing agent (dark tag + /mcp/session + the
+needs-approval rule); idempotent second run (byte-identical); generateClaudeMd
+parity. Plus the existing migrator tests still green. tsc clean.

package/upgrades/side-effects/dynamic-mcp-baseline-at-spawn.md

@@ -0,0 +1,74 @@
+# Side-effects review — dynamic-MCP baseline-at-spawn wiring
+
+**Change:** Wire the dynamic-MCP launch-set resolver into the real interactive
+spawn path so a claude-code session can launch with a lean/explicit MCP subset
+instead of the full `.mcp.json`. Three edits:
+- `src/core/frameworkSessionLaunch.ts` — add `mcpFlags?: string[]` to
+  `InteractiveLaunchOptions`; `claudeCodeBuilder` pushes them into argv (right
+  before returning). Empty/absent ⇒ no flags ⇒ full `.mcp.json` (the default).
+- `src/core/SessionManager.ts` — new fail-safe private `buildSessionMcpFlags(topicId,
+  framework)` (reads `.mcp.json` + the committed loaded-set state file,
+  `resolveSessionMcpServers` → `filterMcpConfig` → writes a unique filtered config,
+  seeds the committed state file from baseline when absent); wired into the
+  `buildInteractiveLaunch` call via a spread.
+- `src/core/types.ts` — `SessionManagerConfig.dynamicMcp?` config field (type-only,
+  NOT in ConfigDefaults).
+
+## 1. Blast radius
+**Zero while dark** (the default). `buildSessionMcpFlags` returns `[]` on the FIRST
+line when `dynamicMcp.enabled !== true`, so no `mcpFlags` are passed, so
+`claudeCodeBuilder` pushes nothing → the launch argv is byte-identical to today.
+A dedicated test asserts this no-op. Behavior changes ONLY when an operator sets
+`dynamicMcp.enabled:true` + a `keepWarm` trim.
+
+## 2. Reversibility
+Fully reversible. Removing the field/flag/method returns launch to its prior
+behavior. The filtered config + state files live under `.instar/state/` and are
+inert once the feature is disabled (the resolver enabled-gates FIRST, so a
+disabled feature ignores any state file — verified by the C3 test).
+
+## 3. State / data touched
+Writes two best-effort files under `<projectDir>/.instar/state/` ONLY when enabled
++ trimming: a per-topic committed loaded-set (`mcp-loaded/<topic>.json`, atomic
+temp+rename) and a unique filtered `--mcp-config` (`session-mcp-config/mcp-<topic>-<ts>.json`).
+Never mutates `.mcp.json` (read-only; `filterMcpConfig` returns a new object).
+
+## 4. Failure modes
+Fail-safe to the FULL `.mcp.json` (`[]`) on EVERY error: unreadable/absent
+`.mcp.json`, write failure, undefined topicId, any thrown error (outer try/catch).
+A seed-write failure is swallowed and the launch still proceeds with the resolved
+set. The worst case is "the full tool set", never "a session stranded without its
+tools". State-file-unreadable-but-config-readable falls back to the LEAN baseline,
+not full config (M6) — so a transient state error cannot relaunch every heavy
+server warm and re-create the resource-panic condition.
+
+## 5. Security / authority
+None exercised here. This is launch-time config selection only — no restart of a
+live session, no operator-approval flow (those land in the driver/routes commits
+with the server-minted-nonce gate). No authority is taken; the agent cannot self-
+authorize anything via this change.
+
+## 6. Framework generality
+The MCP `--mcp-config` / `--strict-mcp-config` mechanism is **Claude-Code
+specific**. `buildSessionMcpFlags` returns `[]` for any framework other than
+`claude-code` (explicit gate, tested), and `claudeCodeBuilder` is the only builder
+that consumes `mcpFlags` — the **codex-cli**, **gemini-cli**, and **pi-cli**
+builders ignore the option entirely. codex-cli configures MCP via `mcp_servers` in
+its config.toml and gemini-cli differs again, so a per-framework MCP-trim is NOT
+attempted for them here; this is a deliberate Claude-Code-scoped capability, not a
+Claude-only assumption baked into a framework-general path. The `framework` is
+resolved per-spawn (the topic's framework), so a codex session on a mixed-framework
+agent is correctly excluded.
+
+## 7. Tests
+8 wiring tests (`session-manager-dynamic-mcp-flags.test.ts`) against a real temp
+projectDir: dark ⇒ [] (no-op); non-claude-code ⇒ []; enabled+no-keepWarm ⇒ [];
+enabled+lean ⇒ trimmed config + seeded committed state; committed state file wins;
+un-committed state file ignored; unreadable `.mcp.json` ⇒ [] (fail-safe); undefined
+topic ⇒ []. Plus the 26 + 10 pure-core tests. tsc clean across the project.
+
+## Scope note
+Ships behind the EXPLICIT `dynamicMcp.enabled` flag (not the dev-agent gate) on
+purpose: baseline-trim must NOT go live before the on-demand load/offload driver
+exists, or a trimmed dev session could be stranded without Playwright and no way to
+load it. The flip to the dev-agent gate is the final step once the full path lands.

package/upgrades/side-effects/dynamic-mcp-capability-classification.md

@@ -0,0 +1,36 @@
+# Side-effects review — dynamic-MCP capability classification + silent-fallback ratchet
+
+**Change:** Two CI-guardrail fixes for the dynamic-MCP PR (#1293):
+- `src/server/CapabilityIndex.ts`: add `{ prefix: 'mcp', reason: ... }` to
+  INTERNAL_PREFIXES — the `/mcp/*` routes are dark/experimental (503 when off), so they
+  are agent-invisible in /capabilities until matured (the honest classification; the
+  agent learns the feature via the CLAUDE.md awareness section).
+- `tests/unit/no-silent-fallbacks.test.ts`: raise the ratchet baseline 476→488 with a
+  justification — the +12 are the feature's INTENTIONAL fail-safes (fail toward full
+  .mcp.json / abort, never a wrong action), documented in the spec + side-effects.
+
+## 1. Blast radius
+Zero behavior change. INTERNAL_PREFIXES classification only affects whether /mcp shows
+in the /capabilities discovery list (it doesn't — correct for a dark feature). The
+ratchet baseline is a test threshold, not runtime code.
+
+## 2. Reversibility
+Fully reversible — remove the prefix entry / restore the baseline number.
+
+## 3. State / data touched
+None.
+
+## 4. Failure modes
+None introduced. The classification is the deliberate "skip discovery" choice the lint
+offers; the ratchet still prevents net regressions beyond 488.
+
+## 5. Security / authority
+None. Hiding a dark feature from discovery is the conservative choice (does not surface
+an unavailable capability as available).
+
+## 6. Framework generality
+N/A (classification + a test threshold).
+
+## 7. Tests
+144 tests pass (capabilities-discoverability 139 + no-silent-fallbacks 5). tsc clean.
+These were the only two failing tests across the #1293 CI shards (1/4 + 3/4).

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

@@ -0,0 +1,53 @@
+# Side-effects review — dynamic-MCP load/offload driver
+
+**Change:** New `src/core/DynamicMcpManager.ts` — the load/offload orchestration
+for the dynamic-MCP lifecycle. All IO is INJECTED (state write, restart, pid
+capture/reap, authorization, mid-tool-use probe); the class touches no
+fs/process/network directly. 16 unit tests via fakes.
+
+## 1. Blast radius
+Zero at runtime. The class has NO importer yet (verified by grep) — nothing
+instantiates it. It becomes live only when the routes/sweep wire it with real
+deps (a later commit, behind the dark flag).
+
+## 2. Reversibility
+Fully reversible — deleting the file + tests removes it. No persisted state, no
+migration, no config consumed.
+
+## 3. State / data touched
+None directly. The class CALLS injected `writeLoadedSet` / `reapPids` / etc., but
+in this commit those are only ever the test fakes.
+
+## 4. Failure modes
+The orchestration is designed fail-safe: a non-`ok` restart rolls the committed
+state back to the prior set (no phantom unapproved change); an offload whose
+restart fails does NOT reap the captured pids (the old session is still alive); a
+mid-tool-use `true` OR `null` aborts an offload (fail-closed); audit is best-effort
+(a throwing audit sink never breaks a change). Authorization fails closed: an
+unverified request returns needs-approval, never proceeds.
+
+## 5. Security / authority
+This is the authority-bearing core, so the gate is built to the "Agent Proposes,
+Operator Approves" + Know-Your-Principal standards: a change proceeds ONLY when
+the topic is LIVE-preapproved (re-checked via the injected `isPreapproved`, not
+trusted from the caller) OR an operator-supplied single-use nonce is consumed
+successfully. An `agent`-actor request that is not preapproved can NEVER proceed —
+it returns needs-approval with a server-minted nonce. The approval prompt text is
+server-authored (a fixed template), never agent free-text. No authority is
+exercised in this commit (nothing wires it live).
+
+## 6. Framework generality
+Not applicable here — the manager is framework-neutral orchestration over injected
+deps. The Claude-Code-specific surface (the actual `--mcp-config` restart) lives in
+the deps' implementations, which the wiring commit will scope to claude-code (the
+restart dep returns `unsupported-unbound`/`not_telegram_bound` for sessions the
+restart mechanism doesn't support).
+
+## 7. Tests
+16 unit tests (`dynamic-mcp-manager.test.ts`): no-op short-circuits (already-loaded
+/ not-loaded / unknown-server, no restart); the auth gate both sides incl. valid vs
+invalid nonce; two-phase write-then-commit + rollback on a failed restart;
+not_telegram_bound ⇒ unsupported-unbound; offload capture→restart→reap ordering;
+no-reap on a failed offload restart; mid-tool-use true/null abort; load skips the
+mid-tool-use check; per-topic serialization (no two restarts in flight for one
+topic). tsc clean.

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

@@ -0,0 +1,40 @@
+# Side-effects review — dynamic-MCP idle-offload sweep (orchestration)
+
+**Change:** New `src/monitoring/McpIdleOffloadSweep.ts` — the automatic
+"offload a heavy MCP server once it's been idle a while" trigger. Stateful
+orchestration over INJECTED deps (proc listing, session→topic, signature→server,
+mid-tool-use, keep-warm, requestOffload). 9 unit tests.
+
+## 1. Blast radius
+Zero at runtime. No importer yet — nothing ticks it until the background-interval
+wiring lands (a thin follow-up). The whole feature is also behind the dark
+`sessions.dynamicMcp.enabled` flag.
+
+## 2. Reversibility
+Fully reversible — delete the file + tests. No persisted state (the idle clocks are
+in-memory and pruned).
+
+## 3. State / data touched
+None on disk. An in-memory Map of per-proc idle clocks, pruned each tick for procs
+that vanished (cannot grow unbounded).
+
+## 4. Failure modes
+Fail-closed by construction: a busy OR unknown(null) mid-tool-use resets the idle
+clock (never ages an ambiguous session toward an offload); an unmapped server or a
+non-topic-bound session is skipped; a thrown requestOffload never breaks the sweep.
+It delegates the actual offload to the authorization-gated driver, so the same
+"agent can't self-approve" + "abort if mid-tool-use" + capture-then-reap guarantees
+apply — the sweep adds no new destructive path of its own.
+
+## 5. Security / authority
+No new authority. An idle-offload it triggers goes through the SAME
+authorization-gated requestOffload as an explicit request — on a non-preapproved
+session it returns needs-approval (no silent restart).
+
+## 6. Framework generality
+Framework-neutral orchestration; the mid-tool-use dep is framework-aware upstream.
+
+## 7. Tests
+9 unit tests: disabled no-op; below-window no-offload; offload once the window is
+crossed; mid-tool-use reset (busy + unknown); keep-warm exclusion; dry-run logs-only;
+non-topic-bound skip; clock pruning. tsc clean.

package/upgrades/side-effects/dynamic-mcp-launch-resolver.md

@@ -0,0 +1,44 @@
+# Side-effects review — dynamic-MCP launch-set resolver
+
+**Change:** Add one pure function `resolveSessionMcpServers` (+ its input type) to
+`src/core/dynamicMcpConfig.ts`, with 8 unit tests. It encodes the load-bearing
+launch-set resolution ORDER from the converged spec (DYNAMIC-MCP-LIFECYCLE-SPEC.md),
+folding convergence findings C3 (enabled-gate first ⇒ clean rollback) and M6
+(state-unreadable ⇒ lean baseline, not full config). No wiring — pure, computes a
+list only.
+
+## 1. Blast radius
+Zero at runtime. The function is not yet called by any live path; it is a pure
+addition to an already-dark module. Behavior change lands only when the IO caller
+(SessionManager.buildSessionMcpFlags) wires it in a later commit, behind a flag.
+
+## 2. Reversibility
+Fully reversible — removing the function + tests returns the module to the prior
+committed state (1fbf13bbb). No persisted state, no migration, no config consumed.
+
+## 3. State / data touched
+None. Reads nothing, writes nothing. Returns a fresh array or null.
+
+## 4. Failure modes
+None reachable here (no IO). The function is total over its typed inputs. Its
+DESIGN intent is fail-safe: the caller passes `stateFileUnreadable:true` on a read
+error and the resolver returns the lean baseline (M6), never full config; and the
+enabled-gate returns null (full) first so a disabled feature is a clean no-op (C3).
+
+## 5. Security / authority
+None. No authority exercised; the live-restart authority + the operator-approval
+nonce flow land in the driver/routes commits with their own review.
+
+## 6. Framework generality
+The resolver itself is framework-data-driven: it takes `framework` as input and
+returns null (full .mcp.json) for any non-`claude-code` framework, because the MCP
+`--mcp-config` mechanism is Claude-Code-specific (codex-cli uses `mcp_servers` in
+config.toml; gemini differs). The eventual spawn caller will resolve THIS topic's
+framework and pass it in. No Claude-only assumption is baked in beyond that
+explicit, tested gate.
+
+## 7. Tests
+8 new unit tests (26 total in the file): disabled-with-committed-state ⇒ null (C3);
+non-claude-code ⇒ null; committed state wins; empty committed ⇒ []; unreadable ⇒
+lean baseline (M6); unreadable + no baseline ⇒ null; baseline present ⇒ baseline;
+no state + no baseline ⇒ null. tsc clean.

package/upgrades/side-effects/dynamic-mcp-loaded-set-store.md

@@ -0,0 +1,37 @@
+# Side-effects review — dynamic-MCP loaded-set state store
+
+**Change:** New `src/core/McpLoadedSetStore.ts` — durable per-topic "which MCP
+servers is this session running with" state, with two-phase commit + atomic writes.
+7 unit tests.
+
+## 1. Blast radius
+Zero at runtime. No importer yet — the spawn builder and driver wire it in a later
+commit (behind the dark flag). `buildSessionMcpFlags` currently inlines an
+equivalent read; the composition commit will route both through this store.
+
+## 2. Reversibility
+Fully reversible — delete the file + tests. No migration; the on-disk JSON it would
+write is inert when the feature is off.
+
+## 3. State / data touched
+Writes `<dir>/<topicId>.json` ONLY when its `write` is called (by the driver/spawn
+builder in a later commit). Atomic temp+rename. Holds no secrets — just server
+NAMES + a committed flag + timestamp.
+
+## 4. Failure modes
+`read`/`readCommitted` return null on absent/unreadable/torn files (never throw);
+`exists` lets the caller distinguish absent from unreadable (drives the M6 fail-to-
+lean decision). `write` throws on a genuine fs failure so the driver can roll back —
+the driver is responsible for fail-safety. The two-phase contract (un-committed is
+invisible to the reader) is the M1/M3 fix.
+
+## 5. Security / authority
+None. No authority; just state IO of server names.
+
+## 6. Framework generality
+Not applicable — framework-neutral state file; no launch/inject surface.
+
+## 7. Tests
+7 unit tests: absent ⇒ nulls; committed write readable; un-committed exists-but-
+readCommitted-null (M1/M3); commit-after-in-flight; de-dup; torn file ⇒ read-null-
+exists-true; no leftover .tmp (atomic). tsc clean.

package/upgrades/side-effects/dynamic-mcp-nonce-store.md

@@ -0,0 +1,38 @@
+# Side-effects review — dynamic-MCP approval nonce store
+
+**Change:** New `src/core/McpApprovalNonceStore.ts` — the single-use, change-bound,
+TTL approval nonce substrate for the dynamic-MCP authorization gate (fold C4). 8
+unit tests.
+
+## 1. Blast radius
+Zero at runtime. No importer yet — nothing mints/consumes from it until the
+approval routes wire it (a later commit, behind the dark flag).
+
+## 2. Reversibility
+Fully reversible — delete the file + tests. In-memory only; no persisted state, no
+migration, no config.
+
+## 3. State / data touched
+None on disk. An in-memory Map of (topicId|kind|server) → {nonce, expiresAt},
+TTL-bounded, pruned on read. Holds no secrets.
+
+## 4. Failure modes
+Fails CLOSED: consume returns false for a never-minted change, a wrong nonce, an
+expired nonce, or a binding mismatch. A wrong attempt does NOT burn the real nonce
+(the genuine operator can retry). Single-use on success.
+
+## 5. Security / authority
+This IS the authority substrate. The nonce is the proof that an operator-
+authenticated approval happened: it is server-minted, random (crypto.randomBytes),
+bound to the exact (topicId, kind, server), single-use, and TTL-expiring. An agent
+cannot forge, reuse, or cross-replay one — closing the "agent self-certifies
+approved:true over the shared Bearer" hole (C4). No authority is exercised in this
+commit (nothing wires it live).
+
+## 6. Framework generality
+Not applicable — framework-neutral in-memory store; no launch/inject surface.
+
+## 7. Tests
+8 unit tests: consume-once; single-use (second fails); wrong value fails without
+burning the real one; bound (cross server/kind/topic replay rejected); never-minted
+fails; TTL expiry; re-mint replaces prior; size()/prune. tsc clean.

package/upgrades/side-effects/dynamic-mcp-pure-cores.md

@@ -0,0 +1,53 @@
+# Side-effects review — dynamic-MCP pure cores
+
+**Change:** Two pure, dark-by-default decision modules for the on-demand MCP
+lifecycle: `src/core/dynamicMcpConfig.ts` (baseline trim + load/offload mutation)
+and `src/monitoring/mcpIdleLiveOffload.ts` (idle-offload eligibility). 28 unit
+tests. No wiring — these compute answers only; nothing spawns, kills, or writes.
+
+## 1. Blast radius
+Zero at runtime. Neither module is imported by any live code path in this commit;
+they are pure functions with no side effects. The eventual wiring (next commit)
+is where behavior changes, and it ships behind a disabled flag.
+
+## 2. Reversibility
+Fully reversible — deleting the two files and their tests returns the tree to
+its prior state. Nothing persisted, no migrations, no config consumed yet.
+
+## 3. State / data touched
+None. No files written, no DB, no network. `mutateLoadedServers` and
+`resolveBaselineServers` return fresh arrays; `filterMcpConfig` returns a new
+object and never mutates its input (explicitly tested).
+
+## 4. Failure modes
+Fail-closed by construction. `decideIdleLiveOffload` keeps the server on ANY
+uncertainty: feature off, owner not live, light signature, keep-warm, mid-tool-use
+true OR unknown (null), or idle clock not yet crossed. `mutateLoadedServers`
+rejects loading an undefined server and no-ops a redundant load/offload. There is
+no path that can drop a tool out from under a session in this commit (no actuation).
+
+## 5. Security / authority
+None exercised here. The actuation layer (restart a live session) carries real
+authority and lands in the wiring commit with the full Tier-2 spec ceremony —
+including the now-decided authorization model: an autonomous/preapproved session
+loads + restarts autonomously; a non-preapproved session must ASK the operator
+("ready for a quick restart?") before acting. That gate is NOT in this commit.
+
+## 6. Framework generality
+Not applicable to these two pure modules (they touch no framework launch/inject
+surface). NOTE for the wiring commit: injecting the lean baseline at spawn WILL
+touch the Claude-code launch path, and MCP config is a Claude-Code-specific
+mechanism (`--mcp-config`/`--strict-mcp-config`); codex-cli and gemini-cli handle
+MCP differently. The wiring will scope the baseline-trim + restart to the
+claude-code framework branch and state that reasoning in its own artifact.
+
+## 7. Tests
+28 unit tests covering both sides of every decision boundary (baseline
+on/off/trim, load known/unknown/redundant, offload present/absent/to-empty,
+idle-offload each gate both ways, fail-closed on unknown mid-tool-use). tsc clean.
+
+## Decision context
+Supersedes the static per-topic profile model (#1292, held as draft) per Justin's
+2026-06-27 correction: MCP needs are not knowable at launch and must be mutable
+mid-session via restart. Design now fully decided: genuinely-lean baseline +
+load-on-demand gated by preapproval (autonomous = preapproved; else ask).

package/upgrades/side-effects/dynamic-mcp-real-offload.md

@@ -0,0 +1,57 @@
+# Side-effects review — dynamic-MCP real offload primitives (capture-then-reap)
+
+**Change:** Complete the offload path (elevated from follow-up to required by the
+operator's full-lifecycle directive). Two edits:
+- `src/core/mcpPidCapture.ts` (new, pure): `captureHeavyMcpPidsForSession` — given the
+  live MCP process scan + process tree + tmux pane map, returns the heavy MCP child
+  PIDs belonging to a specific session AND server. Conservative: unknown/non-heavy
+  server or unresolvable session ⇒ no pid.
+- `src/server/AgentServer.ts`: replace the three conservative offload stubs in the
+  DynamicMcpService construction with REAL primitives — `captureHeavyPids` (reaper
+  ps-listing + the pure capture), `reapPids` (the reaper's `killProcess`), and
+  `isMidToolUse` (live pane frame + `looksActivelyWorking`).
+
+## 1. Blast radius
+Dark by default (`sessions.dynamicMcp.enabled`); when off, the service is built but
+its methods are never invoked (the routes 503). When ON, the offload path can now
+actually drop a server + reap its orphaned heavy process. Service construction stays
+fail-safe (a throw ⇒ null ⇒ routes 503), and the e2e boot is unaffected (verified).
+
+## 2. Reversibility
+Reversible — revert the stubs. No persisted state beyond the existing loaded-set file.
+
+## 3. State / data touched
+`captureHeavyPids` READS the process table (ps) + tmux pane map (read-only).
+`reapPids` sends SIGTERM/SIGKILL to the captured PIDs (the reaper's audited
+`killProcess`). No new files; the reaper audit path is reused.
+
+## 4. Failure modes — THE destructive-authority review
+`reapPids` is the only destructive op. It is tightly bounded: it kills ONLY the PIDs
+`captureHeavyPids` returned, which are ONLY procs that (a) match a HEAVY MCP signature
+mapped from the offloaded server name, AND (b) resolve via the ppid-walk to the EXACT
+target session. An unknown/non-heavy server captures nothing; an orphan or
+wrong-session proc captures nothing — so the worst case is "reap nothing" (a missed
+reclaim the generic reaper still backstops), never "kill the wrong process". The kill
+only runs AFTER an authorized offload's restart is CONFIRMED (the old session is gone),
+and the offload aborts entirely if the session is — or might be — mid-tool-use. Every
+step is fail-safe (capture ⇒ [] on any error; reap ⇒ best-effort per-pid try/catch;
+mid-tool-use ⇒ null ⇒ abort on any uncertainty).
+
+## 5. Security / authority
+No new authority surface — the change only makes the already-gated offload actually
+reclaim. The kill is gated behind: feature enabled + an authorized offload (live
+preapproval or operator nonce) + a confirmed restart + not-mid-tool-use. The agent
+cannot trigger an unauthorized kill.
+
+## 6. Framework generality
+The MCP-server processes are framework-agnostic (a Chromium is a Chromium); the
+mid-tool-use probe passes the session's framework to `looksActivelyWorking` (which is
+framework-aware). The capture/reap is claude-code-relevant in practice (only
+claude-code sessions get a trimmed/dynamic MCP set), but the pid-capture itself is not
+Claude-specific.
+
+## 7. Tests
+7 unit tests for the pure capture (target-session-only, unknown/light server ⇒ none,
+wrong-session ⇒ none, orphan ⇒ none, multiple pids, the conservative server→signature
+map). The e2e AgentServer boot + the routes integration remain green with the new
+wiring. tsc clean.

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

@@ -0,0 +1,59 @@
+# Side-effects review — dynamic-MCP routes + AgentServer wiring (live-authority)
+
+**Change:** Make the dynamic-MCP feature reachable. Three edits:
+- `src/server/routes.ts` — `RouteContext.dynamicMcpService?` field + three routes:
+  `GET /mcp/session/:topicId`, `POST /mcp/load`, `POST /mcp/offload`. Bearer-gated
+  (global middleware); 503 when the service is absent/disabled (dark by default).
+- `src/server/AgentServer.ts` — build `DynamicMcpService` with the host's REAL
+  primitives (restart→SessionRefresh via `getSessionForTopic`, isPreapproved→
+  `activeAutonomousJobs`) and thread it into `routeCtx`. Construction is fail-safe
+  (a throw ⇒ null ⇒ routes 503).
+- Integration test (9 cases) over the real createRoutes pipeline.
+
+## 1. Blast radius
+Reachable but DARK by default: every `/mcp/*` route 503s unless
+`sessions.dynamicMcp.enabled === true` (explicit flag, not the dev-gate yet). The
+service construction is wrapped in try/catch → null on any error, so a wiring fault
+can NEVER break server boot — it just disables the feature. When dark, `routeCtx`
+gains one extra (unused) field; nothing else changes.
+
+## 2. Reversibility
+Fully reversible — remove the field/routes/construction. No migration; the on-disk
+state the service would write only happens when an enabled change is requested.
+
+## 3. State / data touched
+None unless enabled + a change is requested (then McpLoadedSetStore writes under
+`.instar/state/mcp-loaded/`). Reads `.mcp.json`. Never mutates `.mcp.json`.
+
+## 4. Failure modes
+Service construction fail-safe (→ null → 503). The restart primitive maps a null
+SessionRefresh / unbound session to `not_telegram_bound` ⇒ `unsupported-unbound`
+(no crash). isPreapproved fails CLOSED on any error. v1 OFFLOAD is conservatively
+inert (isMidToolUse ⇒ null ⇒ the driver aborts every offload; captureHeavyPids ⇒ [])
+so there is NO leak and NO bad restart until the paneTail probe + reaper pid-capture
+land in a follow-up.
+
+## 5. Security / authority — THE load-bearing review
+The agent-facing routes are Bearer-gated and ALWAYS act as `{kind:'agent'}` — they
+NEVER honor a caller-supplied `nonce` from the request body. This is the C4 fix made
+concrete: the agent RECEIVES the nonce in a needs-approval response, so if the route
+honored a body nonce the agent could self-approve over the shared Bearer. An
+integration test asserts that a body `nonce` does NOT authorize a not-preapproved
+change. The only paths that complete a change are (a) a live-preapproved topic
+(active autonomous run — the operator's own standing grant) or (b) — FOLLOW-UP — an
+operator-authenticated approval route (dashboard PIN / sentinel-bound yes) that
+consumes the server-minted nonce. Until that route lands, a non-preapproved change
+returns needs-approval and performs no restart. No authority can be self-granted.
+
+## 6. Framework generality
+The routes/service are framework-neutral; the Claude-Code-specific surface is the
+restart primitive (SessionRefresh, which returns not_telegram_bound for sessions it
+can't restart ⇒ unsupported-unbound). The baseline-trim that the restart re-applies
+is already claude-code-scoped in buildSessionMcpFlags (prior commit). codex-cli /
+gemini-cli sessions are not trimmed and a restart of them carries no mcpFlags.
+
+## 7. Tests
+9 integration tests (`dynamic-mcp-routes.test.ts`): 503 absent / 503 disabled / GET
+state shape / GET 400 / POST load applied + restart / POST load needs-approval (202,
+no restart) / C4 body-nonce-rejected / POST 400 missing server / offload conservative
+409 abort. Plus the ~105 unit tests for the underlying blocks. tsc clean.