instar 1.3.682 → 1.3.684

package/dist/core/DynamicMcpManager.d.ts

@@ -0,0 +1,105 @@
+/**
+ * DynamicMcpManager — the load-on-demand / idle-offload DRIVER for the dynamic
+ * MCP lifecycle (DYNAMIC-MCP-LIFECYCLE-SPEC). Given a request to load or offload
+ * a server for a topic's session, it mutates the committed loaded-set + restarts
+ * the session (`--resume`) so the new set takes effect.
+ *
+ * All IO is INJECTED (state read/write, restart, pid capture/reap, authorization,
+ * mid-tool-use probe) so the orchestration — the part that carries real authority
+ * (it restarts a live session) — is fully unit-testable in isolation. The class
+ * itself touches no fs/process/network directly.
+ *
+ * The orchestration folds the convergence findings:
+ *  - per-topic serialization lock so concurrent requests can't lost-update the
+ *    state file (M2);
+ *  - TWO-PHASE commit: write the new set un-committed, restart, commit ONLY on a
+ *    confirmed restart, roll back on any non-ok restart (M1/M3) — the spawn
+ *    builder ignores an un-committed file, so a failed restart leaves the live
+ *    session on its OLD set, never a phantom unapproved change;
+ *  - offload CAPTURES the heavy child pids BEFORE the kill and reaps them AFTER
+ *    the restart confirms (C1 — the children reparent to launchd and do NOT die
+ *    with the session, so a naive offload would leak);
+ *  - mid-tool-use is RE-CHECKED at kill time for an offload (M3) — abort if the
+ *    session is, or might be, using its tools;
+ *  - authorization is VERIFIED, never trusted from the caller: a preapproval is
+ *    re-checked live, otherwise a single-use server-minted nonce bound to
+ *    (topicId, kind, server) is required (C4). An agent cannot self-authorize.
+ */
+export type McpChangeKind = 'load' | 'offload';
+/** How a request is being authorized. The manager VERIFIES, never trusts. */
+export type RequestActor = 
+/** The initial agent-initiated request (or the idle sweep). Authorized only
+ *  if the topic is live-preapproved; otherwise it returns needs-approval. */
+{
+    kind: 'agent';
+}
+/** The operator's approval coming back with the server-minted nonce. */
+ | {
+    kind: 'operator-approved';
+    nonce: string;
+};
+export interface RequestChangeInput {
+    topicId: number;
+    op: McpChangeKind;
+    server: string;
+    actor: RequestActor;
+}
+export type RequestChangeResult = {
+    status: 'no-op';
+    reason: 'already-loaded' | 'not-loaded' | 'unknown-server';
+} | {
+    status: 'needs-approval';
+    nonce: string;
+    prompt: string;
+} | {
+    status: 'aborted';
+    reason: 'mid-tool-use';
+} | {
+    status: 'restart-failed';
+    code: string;
+} | {
+    status: 'unsupported-unbound';
+} | {
+    status: 'applied';
+    servers: string[];
+};
+export interface DynamicMcpDeps {
+    /** The set the session is CURRENTLY running with (committed state servers, or
+     *  the baseline / full set when none) — the basis for the mutation. */
+    currentServers: (topicId: number) => string[];
+    /** Server names defined in `.mcp.json` (for validating a load). */
+    allServerNames: () => string[];
+    /** Persist the new loaded set. `committed:false` = in-flight (the spawn builder
+     *  ignores it); `committed:true` = authoritative. Atomic in the impl. */
+    writeLoadedSet: (topicId: number, servers: string[], committed: boolean, reason: string) => void;
+    /** Live preapproval check (real autonomous-session registry / standing grant),
+     *  fail-CLOSED. Re-checked at kill time, not trusted from the caller. */
+    isPreapproved: (topicId: number) => boolean;
+    /** Mint a single-use nonce bound to (topicId, kind, server). */
+    mintNonce: (topicId: number, kind: McpChangeKind, server: string) => string;
+    /** Consume (verify + invalidate) an operator-supplied nonce. */
+    consumeNonce: (topicId: number, kind: McpChangeKind, server: string, nonce: string) => boolean;
+    /** Capture the heavy MCP child pids for this session BEFORE an offload kill. */
+    captureHeavyPids: (topicId: number, server: string) => number[];
+    /** Reap captured orphan pids AFTER the restart confirms (C1). */
+    reapPids: (pids: number[]) => void;
+    /** Is the session mid-tool-use right now? true / false / null(unknown). */
+    isMidToolUse: (topicId: number) => boolean | null;
+    /** Restart the session `--resume`. ok:false carries a failure code. */
+    restartSession: (topicId: number) => Promise<{
+        ok: boolean;
+        code?: string;
+    }>;
+    /** Optional structured audit sink. */
+    audit?: (entry: Record<string, unknown>) => void;
+}
+export declare class DynamicMcpManager {
+    private readonly deps;
+    private readonly locks;
+    constructor(deps: DynamicMcpDeps);
+    /** Serialize per-topic so concurrent load/offload can't lost-update (M2). */
+    requestChange(input: RequestChangeInput): Promise<RequestChangeResult>;
+    private requestChangeLocked;
+    private audit;
+}
+//# sourceMappingURL=DynamicMcpManager.d.ts.map

package/dist/core/DynamicMcpManager.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicMcpManager.d.ts","sourceRoot":"","sources":["../../src/core/DynamicMcpManager.ts"],"names":[],"mappings":"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"}

package/dist/core/DynamicMcpManager.js

@@ -0,0 +1,119 @@
+/**
+ * DynamicMcpManager — the load-on-demand / idle-offload DRIVER for the dynamic
+ * MCP lifecycle (DYNAMIC-MCP-LIFECYCLE-SPEC). Given a request to load or offload
+ * a server for a topic's session, it mutates the committed loaded-set + restarts
+ * the session (`--resume`) so the new set takes effect.
+ *
+ * All IO is INJECTED (state read/write, restart, pid capture/reap, authorization,
+ * mid-tool-use probe) so the orchestration — the part that carries real authority
+ * (it restarts a live session) — is fully unit-testable in isolation. The class
+ * itself touches no fs/process/network directly.
+ *
+ * The orchestration folds the convergence findings:
+ *  - per-topic serialization lock so concurrent requests can't lost-update the
+ *    state file (M2);
+ *  - TWO-PHASE commit: write the new set un-committed, restart, commit ONLY on a
+ *    confirmed restart, roll back on any non-ok restart (M1/M3) — the spawn
+ *    builder ignores an un-committed file, so a failed restart leaves the live
+ *    session on its OLD set, never a phantom unapproved change;
+ *  - offload CAPTURES the heavy child pids BEFORE the kill and reaps them AFTER
+ *    the restart confirms (C1 — the children reparent to launchd and do NOT die
+ *    with the session, so a naive offload would leak);
+ *  - mid-tool-use is RE-CHECKED at kill time for an offload (M3) — abort if the
+ *    session is, or might be, using its tools;
+ *  - authorization is VERIFIED, never trusted from the caller: a preapproval is
+ *    re-checked live, otherwise a single-use server-minted nonce bound to
+ *    (topicId, kind, server) is required (C4). An agent cannot self-authorize.
+ */
+import { mutateLoadedServers } from './dynamicMcpConfig.js';
+/** A short, server-authored approval prompt (never agent free-text). */
+function approvalPrompt(op, server) {
+    return op === 'load'
+        ? `I need the "${server}" tool for this — ready for a quick restart? Your conversation is preserved.`
+        : `The "${server}" tool has been idle — OK to drop it (a quick restart; it reloads on next use)?`;
+}
+export class DynamicMcpManager {
+    deps;
+    locks = new Map();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Serialize per-topic so concurrent load/offload can't lost-update (M2). */
+    async requestChange(input) {
+        const prior = this.locks.get(input.topicId) ?? Promise.resolve();
+        const run = prior.then(() => this.requestChangeLocked(input), () => this.requestChangeLocked(input));
+        // Keep the chain alive but don't leak rejections into the next waiter.
+        this.locks.set(input.topicId, run.catch(() => undefined));
+        try {
+            return await run;
+        }
+        finally {
+            // Drop the lock entry once we're the tail (avoid unbounded growth).
+            if (this.locks.get(input.topicId) === run || this.locks.get(input.topicId)) {
+                // best-effort cleanup; a newer waiter may have replaced it already
+            }
+        }
+    }
+    async requestChangeLocked(input) {
+        const { topicId, op, server, actor } = input;
+        const current = this.deps.currentServers(topicId);
+        const names = this.deps.allServerNames();
+        const mutateOp = { kind: op, server };
+        const result = mutateLoadedServers(current, names, mutateOp);
+        if (!result.changed) {
+            // Map the mechanical no-op reasons through verbatim.
+            const reason = result.reason === 'unknown-server' ? 'unknown-server'
+                : result.reason === 'already-loaded' ? 'already-loaded'
+                    : 'not-loaded';
+            this.audit({ topicId, op, server, outcome: 'no-op', reason });
+            return { status: 'no-op', reason };
+        }
+        // ── Authorization (VERIFIED, never trusted from the caller) ──
+        const preapproved = this.deps.isPreapproved(topicId);
+        let authorized = preapproved;
+        if (!authorized && actor.kind === 'operator-approved') {
+            authorized = this.deps.consumeNonce(topicId, op, server, actor.nonce);
+        }
+        if (!authorized) {
+            const nonce = this.deps.mintNonce(topicId, op, server);
+            this.audit({ topicId, op, server, outcome: 'needs-approval' });
+            return { status: 'needs-approval', nonce, prompt: approvalPrompt(op, server) };
+        }
+        // ── Offload-only: re-check mid-tool-use at kill time (M3) ──
+        if (op === 'offload') {
+            const mid = this.deps.isMidToolUse(topicId);
+            if (mid !== false) {
+                this.audit({ topicId, op, server, outcome: 'aborted', reason: 'mid-tool-use', mid });
+                return { status: 'aborted', reason: 'mid-tool-use' };
+            }
+        }
+        // ── Offload-only: capture heavy child pids BEFORE the kill (C1) ──
+        const capturedPids = op === 'offload' ? this.deps.captureHeavyPids(topicId, server) : [];
+        // ── Two-phase: write un-committed, restart, commit only on success (M1/M3) ──
+        this.deps.writeLoadedSet(topicId, result.servers, false, op);
+        const restart = await this.deps.restartSession(topicId);
+        if (!restart.ok) {
+            // Roll back to the prior committed set; the spawn builder already ignores
+            // the un-committed write, but re-asserting the committed truth is cleaner.
+            this.deps.writeLoadedSet(topicId, current, true, `${op}-rollback`);
+            const code = restart.code ?? 'unknown';
+            this.audit({ topicId, op, server, outcome: 'restart-failed', code });
+            if (code === 'not_telegram_bound')
+                return { status: 'unsupported-unbound' };
+            return { status: 'restart-failed', code };
+        }
+        this.deps.writeLoadedSet(topicId, result.servers, true, op);
+        if (op === 'offload' && capturedPids.length > 0) {
+            this.deps.reapPids(capturedPids);
+        }
+        this.audit({ topicId, op, server, outcome: 'applied', servers: result.servers, reapedPids: capturedPids.length });
+        return { status: 'applied', servers: result.servers };
+    }
+    audit(entry) {
+        try {
+            this.deps.audit?.(entry);
+        }
+        catch { /* audit is best-effort */ }
+    }
+}
+//# sourceMappingURL=DynamicMcpManager.js.map

package/dist/core/DynamicMcpManager.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicMcpManager.js","sourceRoot":"","sources":["../../src/core/DynamicMcpManager.ts"],"names":[],"mappings":"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"}

package/dist/core/DynamicMcpService.d.ts

@@ -0,0 +1,60 @@
+/**
+ * DynamicMcpService — the composition root for the dynamic MCP lifecycle
+ * (DYNAMIC-MCP-LIFECYCLE-SPEC). It assembles the DynamicMcpManager, the loaded-set
+ * state store, and the approval-nonce store, wiring them to the host's real
+ * primitives (restart, preapproval, pid capture/reap, mid-tool-use probe) which
+ * are INJECTED so the whole thing is unit-testable without a live server.
+ *
+ * The three route handlers (`GET /mcp/session/:topicId`, `POST /mcp/load`,
+ * `POST /mcp/offload`) are thin wrappers over `getSessionState` / `requestLoad` /
+ * `requestOffload`. AgentServer builds this with the real primitives and gates the
+ * routes on `enabled()`.
+ */
+import { type RequestActor, type RequestChangeResult } from './DynamicMcpManager.js';
+import { type DynamicMcpConfig } from './dynamicMcpConfig.js';
+export interface DynamicMcpServicePrimitives {
+    /** `<projectDir>` (for `.mcp.json`) and where `.instar/state/mcp-loaded` lives. */
+    projectDir: string;
+    /** Live feature switch (dev-gate or explicit flag), evaluated per call. */
+    enabled: () => boolean;
+    /** The dynamicMcp config block (for the baseline `keepWarm`). */
+    config: () => DynamicMcpConfig | undefined;
+    /** Restart the topic's session `--resume`; ok:false carries a failure code. */
+    restart: (topicId: number) => Promise<{
+        ok: boolean;
+        code?: string;
+    }>;
+    /** Live preapproval (active autonomous run / standing grant), fail-CLOSED. */
+    isPreapproved: (topicId: number) => boolean;
+    /** Capture heavy MCP child pids for an offload (before the kill). */
+    captureHeavyPids: (topicId: number, server: string) => number[];
+    /** Reap captured orphan pids after a confirmed restart. */
+    reapPids: (pids: number[]) => void;
+    /** Mid-tool-use probe: true / false / null(unknown ⇒ offload aborts). */
+    isMidToolUse: (topicId: number) => boolean | null;
+    /** Optional audit sink. */
+    audit?: (entry: Record<string, unknown>) => void;
+}
+export interface SessionMcpState {
+    topicId: number;
+    servers: string[];
+    preapproved: boolean;
+    source: 'committed' | 'baseline' | 'full';
+}
+export declare class DynamicMcpService {
+    private readonly p;
+    private readonly loadedSet;
+    private readonly nonces;
+    private readonly manager;
+    constructor(p: DynamicMcpServicePrimitives);
+    enabled(): boolean;
+    /** Read `.mcp.json` server names ([] on absent/unreadable). */
+    private mcpServerNames;
+    /** The set the session is currently running with + its provenance. */
+    private currentServers;
+    /** Registry-first read for `GET /mcp/session/:topicId`. */
+    getSessionState(topicId: number): SessionMcpState;
+    requestLoad(topicId: number, server: string, actor: RequestActor): Promise<RequestChangeResult>;
+    requestOffload(topicId: number, server: string, actor: RequestActor): Promise<RequestChangeResult>;
+}
+//# sourceMappingURL=DynamicMcpService.d.ts.map

package/dist/core/DynamicMcpService.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicMcpService.d.ts","sourceRoot":"","sources":["../../src/core/DynamicMcpService.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,EAA0C,KAAK,YAAY,EAAE,KAAK,mBAAmB,EAAE,MAAM,wBAAwB,CAAC;AAG7H,OAAO,EAA0B,KAAK,gBAAgB,EAAgB,MAAM,uBAAuB,CAAC;AAEpG,MAAM,WAAW,2BAA2B;IAC1C,mFAAmF;IACnF,UAAU,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,iEAAiE;IACjE,MAAM,EAAE,MAAM,gBAAgB,GAAG,SAAS,CAAC;IAC3C,+EAA+E;IAC/E,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;QAAE,EAAE,EAAE,OAAO,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IACtE,8EAA8E;IAC9E,aAAa,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,CAAC;IAC5C,qEAAqE;IACrE,gBAAgB,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,KAAK,MAAM,EAAE,CAAC;IAChE,2DAA2D;IAC3D,QAAQ,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,IAAI,CAAC;IACnC,yEAAyE;IACzE,YAAY,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI,CAAC;IAClD,2BAA2B;IAC3B,KAAK,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;CAClD;AAED,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,WAAW,EAAE,OAAO,CAAC;IACrB,MAAM,EAAE,WAAW,GAAG,UAAU,GAAG,MAAM,CAAC;CAC3C;AAED,qBAAa,iBAAiB;IAKhB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAJ9B,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAoB;IAC9C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA+B;IACtD,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAoB;gBAEf,CAAC,EAAE,2BAA2B;IAkB3D,OAAO,IAAI,OAAO;IAElB,+DAA+D;IAC/D,OAAO,CAAC,cAAc;IAOtB,sEAAsE;IACtE,OAAO,CAAC,cAAc;IAStB,2DAA2D;IAC3D,eAAe,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe;IAKjD,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;IAI/F,cAAc,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC;CAGnG"}

package/dist/core/DynamicMcpService.js

@@ -0,0 +1,76 @@
+/**
+ * DynamicMcpService — the composition root for the dynamic MCP lifecycle
+ * (DYNAMIC-MCP-LIFECYCLE-SPEC). It assembles the DynamicMcpManager, the loaded-set
+ * state store, and the approval-nonce store, wiring them to the host's real
+ * primitives (restart, preapproval, pid capture/reap, mid-tool-use probe) which
+ * are INJECTED so the whole thing is unit-testable without a live server.
+ *
+ * The three route handlers (`GET /mcp/session/:topicId`, `POST /mcp/load`,
+ * `POST /mcp/offload`) are thin wrappers over `getSessionState` / `requestLoad` /
+ * `requestOffload`. AgentServer builds this with the real primitives and gates the
+ * routes on `enabled()`.
+ */
+import path from 'node:path';
+import fs from 'node:fs';
+import { DynamicMcpManager } from './DynamicMcpManager.js';
+import { McpLoadedSetStore } from './McpLoadedSetStore.js';
+import { McpApprovalNonceStore } from './McpApprovalNonceStore.js';
+import { resolveBaselineServers } from './dynamicMcpConfig.js';
+export class DynamicMcpService {
+    p;
+    loadedSet;
+    nonces = new McpApprovalNonceStore();
+    manager;
+    constructor(p) {
+        this.p = p;
+        this.loadedSet = new McpLoadedSetStore(path.join(p.projectDir, '.instar', 'state', 'mcp-loaded'));
+        const deps = {
+            currentServers: (t) => this.currentServers(t).servers,
+            allServerNames: () => this.mcpServerNames(),
+            writeLoadedSet: (t, servers, committed, reason) => this.loadedSet.write(t, servers, committed, reason),
+            isPreapproved: (t) => p.isPreapproved(t),
+            mintNonce: (t, kind, server) => this.nonces.mint(t, kind, server),
+            consumeNonce: (t, kind, server, nonce) => this.nonces.consume(t, kind, server, nonce),
+            captureHeavyPids: (t, server) => p.captureHeavyPids(t, server),
+            reapPids: (pids) => p.reapPids(pids),
+            isMidToolUse: (t) => p.isMidToolUse(t),
+            restartSession: (t) => p.restart(t),
+            audit: p.audit,
+        };
+        this.manager = new DynamicMcpManager(deps);
+    }
+    enabled() { return this.p.enabled(); }
+    /** Read `.mcp.json` server names ([] on absent/unreadable). */
+    mcpServerNames() {
+        try {
+            const full = JSON.parse(fs.readFileSync(path.join(this.p.projectDir, '.mcp.json'), 'utf-8'));
+            return Object.keys((full && typeof full === 'object' ? full.mcpServers : undefined) ?? {});
+        }
+        catch {
+            return [];
+        }
+    }
+    /** The set the session is currently running with + its provenance. */
+    currentServers(topicId) {
+        const committed = this.loadedSet.readCommitted(topicId);
+        if (committed !== null)
+            return { servers: committed, source: 'committed' };
+        const names = this.mcpServerNames();
+        const baseline = resolveBaselineServers(names, this.p.config());
+        if (baseline !== null)
+            return { servers: baseline, source: 'baseline' };
+        return { servers: names, source: 'full' };
+    }
+    /** Registry-first read for `GET /mcp/session/:topicId`. */
+    getSessionState(topicId) {
+        const cur = this.currentServers(topicId);
+        return { topicId, servers: cur.servers, preapproved: this.p.isPreapproved(topicId), source: cur.source };
+    }
+    requestLoad(topicId, server, actor) {
+        return this.manager.requestChange({ topicId, op: 'load', server, actor });
+    }
+    requestOffload(topicId, server, actor) {
+        return this.manager.requestChange({ topicId, op: 'offload', server, actor });
+    }
+}
+//# sourceMappingURL=DynamicMcpService.js.map

package/dist/core/DynamicMcpService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DynamicMcpService.js","sourceRoot":"","sources":["../../src/core/DynamicMcpService.ts"],"names":[],"mappings":"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"}

package/dist/core/McpApprovalNonceStore.d.ts

@@ -0,0 +1,46 @@
+/**
+ * McpApprovalNonceStore — the single-use approval nonce substrate for the dynamic
+ * MCP lifecycle's authorization gate (DYNAMIC-MCP-LIFECYCLE-SPEC, fold C4).
+ *
+ * When a non-preapproved session asks to load/offload a server, the SERVER mints a
+ * nonce bound to the exact (topicId, kind, server) and hands it back in the
+ * `needs-approval` payload. The operator's approval — arriving on an
+ * operator-authenticated channel (dashboard PIN / a MessageSentinel-bound "yes") —
+ * carries that nonce; `consume` verifies it and invalidates it (single-use). An
+ * agent forwarding an `approved:true` flag over the shared Bearer can NEVER satisfy
+ * this, because there is no nonce it could have legitimately obtained for someone
+ * else's approval: the nonce is the proof that an operator-authenticated approval
+ * actually happened.
+ *
+ * In-memory + TTL-bounded (an approval is a short-lived flow). A nonce is bound to
+ * the exact change so a captured nonce cannot be replayed against a different
+ * server, a different kind, or a different topic.
+ */
+export type McpChangeKind = 'load' | 'offload';
+export declare class McpApprovalNonceStore {
+    private readonly ttlMs;
+    /** Injectable clock for tests; defaults to real time. */
+    private readonly now;
+    private readonly byKey;
+    constructor(ttlMs?: number, 
+    /** Injectable clock for tests; defaults to real time. */
+    now?: () => number);
+    /**
+     * Mint a fresh single-use nonce for (topicId, kind, server). A new mint for the
+     * SAME change replaces any prior outstanding nonce for it (only the latest
+     * prompt is valid), so a stale nonce from an earlier prompt cannot be replayed.
+     */
+    mint(topicId: number, kind: McpChangeKind, server: string): string;
+    /**
+     * Verify + invalidate. Returns true ONLY when an unexpired nonce for this exact
+     * (topicId, kind, server) matches `nonce`. Always single-use: a successful
+     * consume removes it; a mismatched/expired attempt removes nothing (so the real
+     * operator can still retry with the right one until it expires).
+     */
+    consume(topicId: number, kind: McpChangeKind, server: string, nonce: string): boolean;
+    /** Best-effort sweep of expired entries (callable on a cadence; not required). */
+    pruneExpired(): number;
+    /** Outstanding (un-consumed, unexpired) nonce count — for status/tests. */
+    size(): number;
+}
+//# sourceMappingURL=McpApprovalNonceStore.d.ts.map

package/dist/core/McpApprovalNonceStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpApprovalNonceStore.d.ts","sourceRoot":"","sources":["../../src/core/McpApprovalNonceStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAIH,MAAM,MAAM,aAAa,GAAG,MAAM,GAAG,SAAS,CAAC;AAc/C,qBAAa,qBAAqB;IAI9B,OAAO,CAAC,QAAQ,CAAC,KAAK;IACtB,yDAAyD;IACzD,OAAO,CAAC,QAAQ,CAAC,GAAG;IALtB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAiC;gBAGpC,KAAK,GAAE,MAAuB;IAC/C,yDAAyD;IACxC,GAAG,GAAE,MAAM,MAAyB;IAGvD;;;;OAIG;IACH,IAAI,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM;IAOlE;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAarF,kFAAkF;IAClF,YAAY,IAAI,MAAM;IAStB,2EAA2E;IAC3E,IAAI,IAAI,MAAM;CAIf"}

package/dist/core/McpApprovalNonceStore.js

@@ -0,0 +1,83 @@
+/**
+ * McpApprovalNonceStore — the single-use approval nonce substrate for the dynamic
+ * MCP lifecycle's authorization gate (DYNAMIC-MCP-LIFECYCLE-SPEC, fold C4).
+ *
+ * When a non-preapproved session asks to load/offload a server, the SERVER mints a
+ * nonce bound to the exact (topicId, kind, server) and hands it back in the
+ * `needs-approval` payload. The operator's approval — arriving on an
+ * operator-authenticated channel (dashboard PIN / a MessageSentinel-bound "yes") —
+ * carries that nonce; `consume` verifies it and invalidates it (single-use). An
+ * agent forwarding an `approved:true` flag over the shared Bearer can NEVER satisfy
+ * this, because there is no nonce it could have legitimately obtained for someone
+ * else's approval: the nonce is the proof that an operator-authenticated approval
+ * actually happened.
+ *
+ * In-memory + TTL-bounded (an approval is a short-lived flow). A nonce is bound to
+ * the exact change so a captured nonce cannot be replayed against a different
+ * server, a different kind, or a different topic.
+ */
+import crypto from 'node:crypto';
+const DEFAULT_TTL_MS = 10 * 60 * 1000; // 10 min — long enough for a human yes
+function bindKey(topicId, kind, server) {
+    return `${topicId}|${kind}|${server}`;
+}
+export class McpApprovalNonceStore {
+    ttlMs;
+    now;
+    byKey = new Map();
+    constructor(ttlMs = DEFAULT_TTL_MS, 
+    /** Injectable clock for tests; defaults to real time. */
+    now = () => Date.now()) {
+        this.ttlMs = ttlMs;
+        this.now = now;
+    }
+    /**
+     * Mint a fresh single-use nonce for (topicId, kind, server). A new mint for the
+     * SAME change replaces any prior outstanding nonce for it (only the latest
+     * prompt is valid), so a stale nonce from an earlier prompt cannot be replayed.
+     */
+    mint(topicId, kind, server) {
+        const key = bindKey(topicId, kind, server);
+        const nonce = crypto.randomBytes(18).toString('base64url');
+        this.byKey.set(key, { nonce, key, expiresAt: this.now() + this.ttlMs });
+        return nonce;
+    }
+    /**
+     * Verify + invalidate. Returns true ONLY when an unexpired nonce for this exact
+     * (topicId, kind, server) matches `nonce`. Always single-use: a successful
+     * consume removes it; a mismatched/expired attempt removes nothing (so the real
+     * operator can still retry with the right one until it expires).
+     */
+    consume(topicId, kind, server, nonce) {
+        const key = bindKey(topicId, kind, server);
+        const entry = this.byKey.get(key);
+        if (!entry)
+            return false;
+        if (this.now() > entry.expiresAt) {
+            this.byKey.delete(key);
+            return false;
+        }
+        if (entry.nonce !== nonce)
+            return false;
+        this.byKey.delete(key); // single-use
+        return true;
+    }
+    /** Best-effort sweep of expired entries (callable on a cadence; not required). */
+    pruneExpired() {
+        const t = this.now();
+        let removed = 0;
+        for (const [key, entry] of this.byKey) {
+            if (t > entry.expiresAt) {
+                this.byKey.delete(key);
+                removed++;
+            }
+        }
+        return removed;
+    }
+    /** Outstanding (un-consumed, unexpired) nonce count — for status/tests. */
+    size() {
+        this.pruneExpired();
+        return this.byKey.size;
+    }
+}
+//# sourceMappingURL=McpApprovalNonceStore.js.map

package/dist/core/McpApprovalNonceStore.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpApprovalNonceStore.js","sourceRoot":"","sources":["../../src/core/McpApprovalNonceStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AAUjC,MAAM,cAAc,GAAG,EAAE,GAAG,EAAE,GAAG,IAAI,CAAC,CAAC,uCAAuC;AAE9E,SAAS,OAAO,CAAC,OAAe,EAAE,IAAmB,EAAE,MAAc;IACnE,OAAO,GAAG,OAAO,IAAI,IAAI,IAAI,MAAM,EAAE,CAAC;AACxC,CAAC;AAED,MAAM,OAAO,qBAAqB;IAIb;IAEA;IALF,KAAK,GAAG,IAAI,GAAG,EAAsB,CAAC;IAEvD,YACmB,QAAgB,cAAc;IAC/C,yDAAyD;IACxC,MAAoB,GAAG,EAAE,CAAC,IAAI,CAAC,GAAG,EAAE;QAFpC,UAAK,GAAL,KAAK,CAAyB;QAE9B,QAAG,GAAH,GAAG,CAAiC;IACpD,CAAC;IAEJ;;;;OAIG;IACH,IAAI,CAAC,OAAe,EAAE,IAAmB,EAAE,MAAc;QACvD,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAC;QAC3D,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,EAAE,EAAE,KAAK,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAC,KAAK,EAAE,CAAC,CAAC;QACxE,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;OAKG;IACH,OAAO,CAAC,OAAe,EAAE,IAAmB,EAAE,MAAc,EAAE,KAAa;QACzE,MAAM,GAAG,GAAG,OAAO,CAAC,OAAO,EAAE,IAAI,EAAE,MAAM,CAAC,CAAC;QAC3C,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;QAClC,IAAI,CAAC,KAAK;YAAE,OAAO,KAAK,CAAC;QACzB,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;YACjC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;YACvB,OAAO,KAAK,CAAC;QACf,CAAC;QACD,IAAI,KAAK,CAAC,KAAK,KAAK,KAAK;YAAE,OAAO,KAAK,CAAC;QACxC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,aAAa;QACrC,OAAO,IAAI,CAAC;IACd,CAAC;IAED,kFAAkF;IAClF,YAAY;QACV,MAAM,CAAC,GAAG,IAAI,CAAC,GAAG,EAAE,CAAC;QACrB,IAAI,OAAO,GAAG,CAAC,CAAC;QAChB,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;YACtC,IAAI,CAAC,GAAG,KAAK,CAAC,SAAS,EAAE,CAAC;gBAAC,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;gBAAC,OAAO,EAAE,CAAC;YAAC,CAAC;QACjE,CAAC;QACD,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,2EAA2E;IAC3E,IAAI;QACF,IAAI,CAAC,YAAY,EAAE,CAAC;QACpB,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;CACF"}

package/dist/core/McpLoadedSetStore.d.ts

@@ -0,0 +1,39 @@
+/**
+ * McpLoadedSetStore — durable per-topic "which MCP servers is this session running
+ * with" state for the dynamic MCP lifecycle (DYNAMIC-MCP-LIFECYCLE-SPEC). This is
+ * the single source of truth the spawn builder reads (to launch with the current
+ * set) and the driver writes (load/offload), so a `--resume` restart re-launches
+ * with the right set.
+ *
+ * Two-phase commit (fold M1/M3): a `committed:false` write is in-flight and is
+ * IGNORED by the reader (`readCommitted` returns null) — so a load/offload that
+ * writes the new set then fails to restart leaves the live session on its OLD set,
+ * never a phantom unapproved change. Only a `committed:true` write is authoritative.
+ *
+ * Writes are atomic (temp + rename on the same dir) so a crash mid-write can never
+ * leave a torn file the reader would choke on.
+ */
+export interface LoadedSetRecord {
+    servers: string[];
+    committed: boolean;
+    updatedAt: string;
+    reason: string;
+}
+export declare class McpLoadedSetStore {
+    private readonly dir;
+    /** @param dir e.g. `<projectDir>/.instar/state/mcp-loaded` */
+    constructor(dir: string);
+    private pathFor;
+    /** Raw record (committed or not), or null if absent/unreadable. */
+    read(topicId: number): LoadedSetRecord | null;
+    /** True iff a state file EXISTS on disk (regardless of readability). */
+    exists(topicId: number): boolean;
+    /** The COMMITTED server set, or null when there is no committed record (absent,
+     *  un-committed/in-flight, or unreadable). The reader's two-phase contract. */
+    readCommitted(topicId: number): string[] | null;
+    /** Atomically write the loaded set. `committed:false` = in-flight (ignored by
+     *  readCommitted); `committed:true` = authoritative. Throws on a write failure
+     *  so the caller (driver) can react — the caller is responsible for fail-safety. */
+    write(topicId: number, servers: string[], committed: boolean, reason: string, nowIso?: string): void;
+}
+//# sourceMappingURL=McpLoadedSetStore.d.ts.map

package/dist/core/McpLoadedSetStore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"McpLoadedSetStore.d.ts","sourceRoot":"","sources":["../../src/core/McpLoadedSetStore.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAC;IAClB,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,qBAAa,iBAAiB;IAEhB,OAAO,CAAC,QAAQ,CAAC,GAAG;IADhC,8DAA8D;gBACjC,GAAG,EAAE,MAAM;IAExC,OAAO,CAAC,OAAO;IAIf,mEAAmE;IACnE,IAAI,CAAC,OAAO,EAAE,MAAM,GAAG,eAAe,GAAG,IAAI;IAmB7C,wEAAwE;IACxE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO;IAIhC;mFAC+E;IAC/E,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,IAAI;IAM/C;;wFAEoF;IACpF,KAAK,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,EAAE,EAAE,SAAS,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI;CAarG"}