@aiwayds/dsh-mcp-adapter 0.4.2 → 0.5.1

package/lib/index.js

@@ -33,8 +33,9 @@
  * three latches at once — its tools force-fold out of every prompt (keep and
  * `servers` whitelist exemptions included), it disappears from the catalog,
  * and `mcp_call` refuses it with an enable hint. Each server gets a stable
- * numeric id (1..99, smallest free first) persisted in the dsh settings
- * service (`mcp-adapter` namespace), so ids survive restarts and re-syncs.
+ * numeric id (1..99, smallest free first) persisted in the plugin's own gate
+ * file under the dsh home (`storages/mcp-adapter/gate.json`), so ids survive
+ * restarts and re-syncs.
  *
  * Child-owned projections are preserved: `mcp_call` delegates its
  * `output.render` to the dispatched child and forwards the child's
@@ -52,6 +53,10 @@
  *
  * @module @aiwayds/dsh-mcp-adapter
  */
+import { mkdir, rename, writeFile } from 'node:fs/promises';
+import { existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { basename, join, resolve as resolvePath } from 'node:path';
 import z from '@deepseek-ai/schemastery';
 /** Cordis plugin name used by loader diagnostics. */
 export const name = 'mcp-adapter';
@@ -87,19 +92,19 @@ const PREFIX_PATTERN = /^[A-Za-z0-9_-]{1,64}$/;
 /** Upper bound of the stable per-server id space. */
 export const MCP_SERVER_ID_LIMIT = 99;
 /**
- * dsh settings namespace persisting the stable ids and the disabled set.
- * Plain literal: dsh-settings 0.1.2-alpha.3 removed the runtime
- * settingsNamespace() helper this constant used to call (same adaptation as
- * dsh-model-sync / dsh-cron / dsh-vault).
+ * dsh 0.1.7 note: the runtime settings registry this state used to live in
+ * (`settings.register('mcp-adapter', …)` on the 0.1.5 `SettingsScope`) is
+ * gone — 0.1.7 settings are the projection of a plugin's `Config` schema and
+ * volatile fields are user-editable values, which a machine-maintained id
+ * registry must never be. The gate therefore persists through the plugin's
+ * OWN file under the dsh home (same seam as dsh-cron/dsh-vault):
+ * `<dsh home>/storages/mcp-adapter/gate.json`.
  */
-export const MCP_ADAPTER_SETTINGS_NAMESPACE = 'mcp-adapter';
+export const MCP_ADAPTER_STORAGE_DIRNAME = 'mcp-adapter';
+/** The gate document file name inside {@link MCP_ADAPTER_STORAGE_DIRNAME}. */
+export const GATE_FILE_NAME = 'gate.json';
 /** Gate snapshot meaning "nothing observed, nothing disabled". */
 export const EMPTY_SERVER_GATE = { serverIds: {}, disabled: [] };
-/** Schema of the persisted `mcp-adapter` settings section. */
-export const SERVER_ID_REGISTRY_SCHEMA = z.object({
-    serverIds: z.dict(z.number().step(1).min(1).max(MCP_SERVER_ID_LIMIT)).default({}),
-    disabled: z.array(z.number().step(1).min(1).max(MCP_SERVER_ID_LIMIT)).default([]),
-});
 /** Whether one number is an allocatable server id. */
 function isValidServerId(id) {
     return typeof id === 'number' && Number.isInteger(id) && id >= 1 && id <= MCP_SERVER_ID_LIMIT;
@@ -212,11 +217,278 @@ export function setServerDisabledState(state, server, disable) {
         changed: disable ? id !== undefined && !has : has,
     };
 }
+/** Resolve the dsh home (`DSH_HOME`, else `~/.dsh`) — same seam as dsh-cron/dsh-vault. */
+export function resolveDshHome() {
+    return process.env.DSH_HOME !== undefined && process.env.DSH_HOME !== ''
+        ? process.env.DSH_HOME
+        : join(homedir(), '.dsh');
+}
+/**
+ * Absolute gate directory for one `storageDir` config value: empty (default)
+ * means `<dsh home>/storages/mcp-adapter`, anything else is the override used
+ * verbatim (resolved).
+ */
+export function resolveGateDir(configured) {
+    return configured.trim() === ''
+        ? join(resolveDshHome(), 'storages', MCP_ADAPTER_STORAGE_DIRNAME)
+        : resolvePath(configured);
+}
+/**
+ * Load the gate mirror from one gate file. A missing file is the fresh-install
+ * zero state (silent); an unreadable or unparseable one is warned about once
+ * here and degrades to the empty gate — every server counts as enabled, the
+ * fail-open hard requirement.
+ */
+function loadInitialGate(file, warn) {
+    try {
+        return normalizeServerGate(JSON.parse(readFileSync(file, 'utf8')));
+    }
+    catch (error) {
+        if (error?.code !== 'ENOENT') {
+            warn(`mcp-adapter: the persisted enable/disable state at ${file} is unreadable `
+                + `(${error instanceof Error ? error.message : String(error)}) `
+                + '— starting from an empty gate (every server enabled)');
+        }
+        return EMPTY_SERVER_GATE;
+    }
+}
+/**
+ * Build the production gate store over one directory. The initial read is
+ * synchronous (boot-time, once); writes land atomically (tmp file + rename)
+ * so a crash mid-write can never leave a torn document, and the in-memory
+ * mirror only advances after the file is durably renamed into place.
+ *
+ * Legacy absorption (one-time, 0.1.5 → 0.1.7): on a FRESH gate — no
+ * gate.json yet — the machine state from the removed settings registry is
+ * absorbed once from the host's legacy settings documents (see
+ * {@link absorbLegacyGate}). Opt-in through `options.home`: the legacy
+ * documents are a HOME-level concern (not this store's `dir`), and stores
+ * built without a home (bare test harnesses) stay exactly as isolated as
+ * before.
+ */
+export function createFileGateStore(dir, warn, options = {}) {
+    const file = join(dir, GATE_FILE_NAME);
+    const hadGateFile = existsSync(file);
+    let mirror = loadInitialGate(file, warn);
+    if (!hadGateFile) {
+        // Fresh install: one chance to take over the pre-0.1.7 gate state.
+        mirror = absorbLegacyGate(mirror, dir, warn, options);
+    }
+    return {
+        get: () => mirror,
+        async write(next) {
+            // Copy-on-write payload: the document is complete and self-contained,
+            // exactly what the old wholesale settings `replace` guaranteed.
+            const payload = JSON.stringify({ serverIds: { ...next.serverIds }, disabled: [...next.disabled] }, null, 2) + '\n';
+            await mkdir(dir, { recursive: true });
+            const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+            await writeFile(tmp, payload, 'utf8');
+            await rename(tmp, file);
+            mirror = normalizeServerGate(next);
+        },
+    };
+}
+// ---- Legacy settings absorption (one-time, 0.1.5 → 0.1.7) ----
+/**
+ * dsh 0.1.7 renamed the old `<home>/settings.yaml` to
+ * `settings.yaml.imported` after a one-shot import keyed by "section name =
+ * entry id". This plugin's old `mcp-adapter:` section (the machine-maintained
+ * id registry / disabled set) does not match the entry id `dsh-mcp-adapter`
+ * and was silently dropped by the host — the state lives on only in the
+ * renamed document. {@link absorbLegacyGate} recovers it once into the
+ * plugin's own gate.json.
+ */
+/** Legacy host settings documents, in read priority order. */
+export const LEGACY_SETTINGS_FILES = ['settings.yaml.imported', 'settings.yaml'];
+/** Legacy top-level section name in the old settings document. */
+export const LEGACY_GATE_SECTION = 'mcp-adapter';
+/** Audit marker file name: `<home>/storages/mcp-adapter/<name>`. */
+export const LEGACY_IMPORT_MARKER = 'legacy-import.json';
+/**
+ * Decode one YAML scalar of the old settings document — the shapes the 0.1.5
+ * writer actually produced (plain scalars, booleans, and quoted single-line
+ * flow-JSON payloads). A value that opens a quote it does not close on the
+ * same line is a FOLDED long scalar (dumpers wrap at 80 columns):
+ * unparseable here by design, so the key is skipped — never a half-read
+ * value.
+ */
+function decodeLegacyScalar(raw) {
+    const value = raw.trim();
+    if (value === '' || value === 'null' || value === '~')
+        return undefined;
+    if (value === 'true')
+        return true;
+    if (value === 'false')
+        return false;
+    const quote = value[0];
+    const closed = value.length >= 2 && value[value.length - 1] === quote;
+    if (quote === "'" || quote === '"') {
+        if (!closed || value.length < 2)
+            return undefined; // folded / unterminated — skip
+        if (quote === '"') {
+            // Double-quoted payloads are JSON-compatible as-is.
+            try {
+                return JSON.parse(value);
+            }
+            catch {
+                return undefined;
+            }
+        }
+        return value.slice(1, -1).replace(/''/g, "'");
+    }
+    const hash = value.indexOf(' #');
+    return hash >= 0 ? value.slice(0, hash).trim() : value;
+}
+/**
+ * Extract the top-level `mcp-adapter:` section of the old settings document.
+ * Handles both shapes the 0.1.5 writer produced:
+ * - single-line values (`serverIds: '{"fs": 1}'`, `disabled: '[1]'`);
+ * - block collections (`serverIds:` followed by deeper-indented
+ *   `name: <int>` lines; `disabled:` followed by `- <int>` lines).
+ * Everything else (comments, folded scalars, nested junk) is skipped.
+ * undefined = no section found. Pure function — tests run it against
+ * literal strings.
+ */
+export function legacyGateSection(text) {
+    const lines = text.split('\n');
+    const start = lines.findIndex(line => /^mcp-adapter:\s*(#.*)?$/.test(line));
+    if (start < 0)
+        return undefined;
+    const section = {};
+    const ids = {};
+    const seq = [];
+    let block;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        const line = lines[index];
+        if (line.trim() === '' || /^\s*#/.test(line))
+            continue;
+        if (/^\S/.test(line))
+            break; // the next top-level key ends the section
+        const indent = line.length - line.trimStart().length;
+        if (block !== undefined && indent > block.indent) {
+            // Children of an open block collection carry the machine state.
+            if (block.key === 'serverIds') {
+                const entry = /^([^\s:#]+):\s*(\d+)\s*(?:#.*)?$/.exec(line.trim());
+                if (entry !== null)
+                    ids[entry[1]] = Number(entry[2]);
+            }
+            else {
+                const entry = /^-\s*(\d+)\s*(?:#.*)?$/.exec(line.trim());
+                if (entry !== null)
+                    seq.push(Number(entry[1]));
+            }
+            continue;
+        }
+        block = undefined;
+        const match = /^([A-Za-z][A-Za-z0-9_-]*):[ \t]?(.*)$/.exec(line.trim());
+        if (match === null)
+            continue; // nested shape we do not model — skip the line
+        const [, key, rawValue] = match;
+        if (key !== 'serverIds' && key !== 'disabled')
+            continue;
+        const value = rawValue.trim();
+        if (value === '') {
+            // Opens a block collection (or is null — the children decide).
+            block = { key, indent };
+            continue;
+        }
+        section[key] = decodeLegacyScalar(rawValue);
+    }
+    if (Object.keys(ids).length > 0)
+        section.serverIds = ids;
+    if (seq.length > 0)
+        section.disabled = seq;
+    return section;
+}
+/**
+ * Turn one decoded section into the raw candidate {@link normalizeServerGate}
+ * sanitizes: flow-JSON strings are JSON-parsed (malformed → undefined, the
+ * key degrades to "absent"), already-decoded block collections pass through.
+ */
+export function legacyGateCandidate(section) {
+    const fromFlow = (value) => {
+        if (typeof value !== 'string')
+            return value;
+        try {
+            return JSON.parse(value);
+        }
+        catch {
+            return undefined;
+        }
+    };
+    return { serverIds: fromFlow(section.serverIds), disabled: fromFlow(section.disabled) };
+}
+/**
+ * The one-time absorption pass over the legacy documents. Marker semantics
+ * match the sibling plugins: written for EVERY settled outcome EXCEPT the
+ * retry-worthy failure (an unexpected error — no marker, the next boot
+ * retries); a present marker short-circuits the whole pass (idempotent — a
+ * later manual edit of the imported file must not resurrect old values).
+ * Returns the mirror to run on (the absorbed state, or the input unchanged).
+ */
+function absorbLegacyGate(current, dir, warn, options) {
+    try {
+        const home = options.home;
+        if (home === undefined)
+            return current;
+        const markerPath = join(home, 'storages', MCP_ADAPTER_STORAGE_DIRNAME, LEGACY_IMPORT_MARKER);
+        if (existsSync(markerPath))
+            return current;
+        const writeMarker = (marker) => {
+            try {
+                mkdirSync(join(markerPath, '..'), { recursive: true });
+                writeFileSync(markerPath, `${JSON.stringify(marker, null, 2)}\n`);
+            }
+            catch {
+                // contained — a missing audit file only costs a re-scan next boot
+            }
+        };
+        const source = LEGACY_SETTINGS_FILES
+            .map(name => join(home, name))
+            .find(path => existsSync(path));
+        if (source === undefined) {
+            writeMarker({ at: new Date().toISOString(), outcome: 'no-legacy', source: undefined });
+            return current;
+        }
+        const section = legacyGateSection(readFileSync(source, 'utf8'));
+        const absorbed = normalizeServerGate(section === undefined ? {} : legacyGateCandidate(section));
+        const serverIdCount = Object.keys(absorbed.serverIds).length;
+        if (serverIdCount === 0 && absorbed.disabled.length === 0) {
+            writeMarker({ at: new Date().toISOString(), outcome: section === undefined ? 'no-section' : 'no-op', source });
+            return current;
+        }
+        // Persist IMMEDIATELY (sync atomic tmp+rename, the write-through pose):
+        // gate.json must exist the moment the state was taken over, so ids and
+        // toggles visibly survive the upgrade without waiting for a first write.
+        const file = join(dir, GATE_FILE_NAME);
+        const payload = JSON.stringify({ serverIds: { ...absorbed.serverIds }, disabled: [...absorbed.disabled] }, null, 2) + '\n';
+        mkdirSync(dir, { recursive: true });
+        const tmp = `${file}.${process.pid}.${Date.now()}.tmp`;
+        writeFileSync(tmp, payload, 'utf8');
+        renameSync(tmp, file);
+        writeMarker({
+            at: new Date().toISOString(),
+            outcome: 'imported',
+            source,
+            serverIds: serverIdCount,
+            disabled: absorbed.disabled.length,
+        });
+        options.info?.(`mcp-adapter: legacy settings import (${basename(source)} → ${MCP_ADAPTER_STORAGE_DIRNAME}/${GATE_FILE_NAME}): `
+            + `serverIds=${serverIdCount}, disabled=${absorbed.disabled.length}`);
+        return absorbed;
+    }
+    catch (error) {
+        warn(`mcp-adapter: legacy settings absorption failed (ignored — starting from the current gate, retried next boot): `
+            + `${error instanceof Error ? error.message : String(error)}`);
+        return current;
+    }
+}
 export const Config = z.object({
-    prefix: z.string().pattern(PREFIX_PATTERN).default(DEFAULT_PREFIX),
-    keep: z.array(String).default([]),
-    servers: z.array(String).default([]),
-    descriptionLimit: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_DESCRIPTION_LIMIT),
+    prefix: z.string().pattern(PREFIX_PATTERN).default(DEFAULT_PREFIX).volatile(),
+    keep: z.array(String).default([]).volatile(),
+    servers: z.array(String).default([]).volatile(),
+    descriptionLimit: z.number().step(1).min(1).max(Number.MAX_SAFE_INTEGER).default(DEFAULT_DESCRIPTION_LIMIT).volatile(),
+    storageDir: z.string().default('').volatile(),
 });
 // ---- Keep-pattern matching (pure) ----
 /** Compiled keep patterns, keyed by source pattern. */
@@ -648,7 +920,7 @@ export function liveServerNames(schemas, options) {
  *
  * @param schemas - schemas visible to the receiving agent.
  * @param options - adapter knobs (prefix/keep/servers) plus the live gate
- *   snapshot (`gate`) when the settings service is composed.
+ *   snapshot (`gate`) when a gate store is available.
  * @param metaToolsLive - whether both meta-tools resolve to this plugin's
  *   definitions in the receiving agent's scope.
  * @returns the folding health plus the partition behind it.
@@ -902,7 +1174,7 @@ export function renderMcpConfig(schemas, options) {
         const hits = candidates.filter(schema => serverOfToolName(schema.name, options.prefix) === server);
         lines.push(`  - ${server}`, hits.length === 0 ? '      (no matching tools)' : `      tools: ${hits.map(schema => annotateDisabled(schema.name)).join(', ')}`);
     }
-    // Persistent gate inventory — only meaningful with a live settings-backed
+    // Persistent gate inventory — only meaningful with a live gate-backed
     // snapshot, so absent snapshots keep the legacy output untouched.
     if (options.gate !== undefined) {
         const mapped = Object.entries(options.gate.serverIds).sort((left, right) => left[1] - right[1]);
@@ -1022,8 +1294,8 @@ async function runServerToggle(form, id, registry, view) {
     if (registry === undefined || view.writeGate === undefined) {
         return {
             kind: 'error',
-            text: `"/mcp ${form}" needs the dsh settings service to persist server state, `
-                + 'and it is not composed in this process',
+            text: `"/mcp ${form}" needs the persistent gate store to record server state, `
+                + 'and it is not available in this process',
         };
     }
     const liveServers = new Set(liveServerNames(view.schemas, view.config));
@@ -1191,7 +1463,11 @@ export function delegateFinalizeContent(metaArgs, result, exec, resolveChild) {
 }
 /**
  * Build the `mcp_list` meta-tool definition.
- * @param options - catalog knobs (prefix, description limit).
+ * @param options - catalog knobs (prefix, description limit). MAY be a live
+ *   options object (plain getters): the factory reads `prefix`, `servers`,
+ *   `descriptionLimit` and `getGate` through the object on EVERY execution,
+ *   so volatile config can be wired by reference — only the description text
+ *   freezes at factory time.
  * @param listSchemas - visible-schemas source (production: `ctx.tools.schemas`,
  *   called with the calling agent so restrictions are respected).
  * @returns the complete tool definition.
@@ -1240,24 +1516,29 @@ export function createMcpListTool(options, listSchemas) {
 }
 /**
  * Build the `mcp_call` meta-tool definition.
- * @param prefix - the configured MCP prefix (dispatch boundary).
+ * @param prefix - the configured MCP prefix (dispatch boundary). A thunk is
+ *   accepted so volatile config is re-read on every dispatch; a plain string
+ *   freezes the boundary at factory time.
  * @param resolve - scope-aware definition resolver (production:
  *   `ctx.tools.get`, called with the calling agent).
- * @param servers - server-name whitelist (default: no filtering).
- * @param getGate - live disabled-server reader (production: fresh
- *   `settingsScope.get()` snapshot per dispatch; default/omitted: nothing is
- *   disabled). Deliberately a callback — the definition object outlives any
- *   one settings snapshot and must observe later /mcp enable/disable writes.
+ * @param servers - server-name whitelist (default: no filtering). A thunk is
+ *   accepted for live volatile config, same as `prefix`.
+ * @param getGate - live disabled-server reader (production: the file-backed
+ *   gate store's current mirror; default/omitted: nothing is disabled).
+ *   Deliberately a callback — the definition object outlives any one gate
+ *   snapshot and must observe later /mcp enable/disable writes.
  * @returns the complete tool definition.
  */
 export function createMcpCallTool(prefix, resolve, servers = [], getGate) {
+    const prefixNow = typeof prefix === 'function' ? prefix : () => prefix;
+    const serversNow = typeof servers === 'function' ? servers : () => servers;
     return {
         name: MCP_CALL_TOOL_NAME,
         description: [
-            `Invoke one MCP tool by its full registered name (like "${prefix}<server>__<tool>").`,
+            `Invoke one MCP tool by its full registered name (like "${prefixNow()}<server>__<tool>").`,
             `First call ${MCP_LIST_TOOL_NAME} to discover tool names and expand the exact input schema,`,
             'then pass { "tool": "<full name>", "arguments": { ... } }.',
-            `Only tools named with the "${prefix}" prefix are dispatchable — anything else is refused.`,
+            `Only tools named with the "${prefixNow()}" prefix are dispatchable — anything else is refused.`,
             'The result is the invoked tool\'s own return value, or a structured { "error": ... } you can correct and retry.',
         ].join(' '),
         parameters: {
@@ -1277,7 +1558,7 @@ export function createMcpCallTool(prefix, resolve, servers = [], getGate) {
             schema: {},
             render: (args, value) => renderDispatched(args, value, name => resolve(name)),
         },
-        execute: (args, exec) => dispatchMcpCall(args, prefix, name => resolve(name, exec.agent), exec, servers, getGate?.()),
+        execute: (args, exec) => dispatchMcpCall(args, prefixNow(), name => resolve(name, exec.agent), exec, serversNow(), getGate?.()),
         // Restore child-owned projections (image attachments): the registry
         // invokes THIS definition's finalizer, so it must forward to the child's
         // with the same exec object dispatch passed to child.execute.
@@ -1292,79 +1573,57 @@ export function createMcpCallTool(prefix, resolve, servers = [], getGate) {
  * both registrations are rolled back, a warning is logged, and NO listener
  * is installed — the official full-schema passthrough stays intact.
  *
- * Server gating: when a dsh settings service is composed, the `mcp-adapter`
- * namespace is registered on it and every gate consumer reads FRESH resolved
- * values through small callbacks — the plugin keeps no in-memory copy that
- * could drift from settings. The read itself is defended too: if the
- * resolved-value lookup throws, consumers see an absent gate (everything
- * enabled) instead of the error, keeping the assemble waterfall alive.
+ * Server gating: the gate mirror loads synchronously once from the plugin's
+ * gate file (`resolveGateDir(config.storageDir.get())`), and every gate
+ * consumer reads the CURRENT mirror through {@link getGate} — the plugin
+ * keeps no stale copy that could drift from /mcp writes. A corrupt or
+ * unreadable document degrades to the empty gate (everything enabled) at
+ * load time, keeping the assemble waterfall alive.
+ *
+ * Config volatility: every knob (prefix/keep/servers/descriptionLimit) is a
+ * volatile reference — 0.1.7 settings-page writes swap values in place
+ * WITHOUT remounting the plugin, so nothing captured at apply time may go
+ * stale: the waterfall, both meta-tools and the /mcp command all re-read
+ * through {@link cfgNow} per use.
  *
- * Commands: `/mcp` mounts through a runtime `ctx.inject(['commands'], ...)`
- * (same seam as settings), so hosts without the commands service keep this
- * plugin fully functional — one warning, no command. A registration name
- * conflict degrades to the same warning independently.
+ * Commands: `/mcp` mounts through a runtime `ctx.inject(['commands'], ...)`,
+ * so hosts without the commands service keep this plugin fully functional —
+ * one warning, no command. A registration name conflict degrades to the same
+ * warning independently.
  *
  * @param ctx - plugin context carrying the tool registry.
- * @param config - resolved adapter configuration.
+ * @param config - resolved adapter configuration (volatile live references).
  */
 export function apply(ctx, config) {
-    const foldOptions = {
-        prefix: config.prefix,
-        keep: config.keep,
-        servers: config.servers,
-    };
-    const listOptions = {
-        prefix: config.prefix,
-        descriptionLimit: config.descriptionLimit,
-        servers: config.servers,
-    };
-    // Optional settings consumption (the canonical inject-scoped pattern): the
-    // registration rides its own child fiber, so disposing it removes exactly
-    // the namespace. Late binding over `settingsScope` means the meta-tools,
-    // waterfall, and command created below observe the mount whenever it lands.
-    let settingsScope;
-    if (typeof ctx.inject === 'function') {
-        ctx.inject(['settings'], (sctx) => {
-            settingsScope = sctx.settings.register(MCP_ADAPTER_SETTINGS_NAMESPACE, SERVER_ID_REGISTRY_SCHEMA);
-            return () => { settingsScope = undefined; };
-        });
-    }
-    // One-shot latch: a persistently broken settings provider would otherwise
-    // re-warn on EVERY assembled prompt (getGate runs per waterfall execution).
-    let gateReadWarned = false;
-    // Fresh snapshot per read; normalize guards hand-edited documents. The
-    // scope being absent is distinguishable from an empty section: undefined
-    // propagates so toggle commands can name their missing dependency.
-    const getGate = () => {
-        const scope = settingsScope;
-        if (scope === undefined)
-            return undefined;
-        try {
-            return normalizeServerGate(scope.get());
-        }
-        catch (error) {
-            // Fail-open, hard requirement: a throwing read must never blow up the
-            // system-prompt/assemble waterfall or a /mcp invocation. Gate-less
-            // means every server counts as enabled — visibility only ever grows.
-            if (!gateReadWarned) {
-                gateReadWarned = true;
-                ctx.logger.warn(`mcp-adapter: reading the persisted enable/disable state failed `
-                    + `(${error instanceof Error ? error.message : String(error)}) `
-                    + '— treating every server as enabled');
-            }
-            return undefined;
-        }
-    };
-    const writeGate = async (next) => {
-        const scope = settingsScope;
-        if (scope === undefined)
-            throw new Error('settings service went away before the write');
-        // Wholesale replace (not update): we always hold the complete next
-        // section, and replace cannot merge stale keys back under us.
-        await scope.replace({ serverIds: { ...next.serverIds }, disabled: [...next.disabled] });
-    };
-    const listDefinition = createMcpListTool({ ...listOptions, getGate }, scope => ctx.tools.schemas(scope));
-    const callDefinition = createMcpCallTool(config.prefix, (name, scope) => ctx.tools.get(name, scope), config.servers, getGate);
+    const cfgNow = () => ({
+        prefix: config.prefix.get(),
+        keep: config.keep.get(),
+        servers: config.servers.get(),
+        descriptionLimit: config.descriptionLimit.get(),
+    });
+    // Persistent enable/disable state: file-backed gate store (the 0.1.5
+    // settings namespace is gone; volatile fields are for user-facing values,
+    // which a machine id registry must never be). Reads come from the mirror,
+    // writes go through atomically; the storage dir is read once — moving it
+    // takes effect on the next plugin restart. On a fresh gate (no gate.json)
+    // the store absorbs the pre-0.1.7 `mcp-adapter:` settings state once —
+    // fully contained, audit marker under storages/mcp-adapter.
+    const store = createFileGateStore(resolveGateDir(config.storageDir.get()), message => ctx.logger.warn(message), {
+        info: message => ctx.logger.info?.(message),
+        home: resolveDshHome(),
+    });
+    const getGate = () => store.get();
+    const writeGate = (next) => store.write(next);
+    // Live options object: getters re-resolve volatile config per execution, so
+    // catalog/dispatch immediately follow settings-page edits (the list tool's
+    // description text is the only factory-time freeze, and it is cosmetic).
+    const listDefinition = createMcpListTool({
+        get prefix() { return cfgNow().prefix; },
+        get servers() { return cfgNow().servers; },
+        get descriptionLimit() { return cfgNow().descriptionLimit; },
+        getGate,
+    }, scope => ctx.tools.schemas(scope));
+    const callDefinition = createMcpCallTool(() => cfgNow().prefix, (name, scope) => ctx.tools.get(name, scope), () => cfgNow().servers, getGate);
     const disposers = [];
     try {
         disposers.push(ctx.tools.register(listDefinition));
@@ -1392,7 +1651,10 @@ export function apply(ctx, config) {
         // missing, shadowed, or foreign `mcp_list`/`mcp_call` means passthrough.
         const metaToolsLive = ctx.tools.get(MCP_LIST_TOOL_NAME, context.scope) === listDefinition
             && ctx.tools.get(MCP_CALL_TOOL_NAME, context.scope) === callDefinition;
-        return foldPromptAssembly(assembled, foldOptions, metaToolsLive, getGate());
+        // Volatile knobs are re-read per assembly: settings-page edits reach the
+        // next prompt without a plugin remount.
+        const { prefix, keep, servers } = cfgNow();
+        return foldPromptAssembly(assembled, { prefix, keep, servers }, metaToolsLive, getGate());
     });
     // Status + server toggles on the platform command service (visible in TUI
     // completion and web slash panels). The service is mounted SOFTLY: unlike
@@ -1423,18 +1685,13 @@ export function apply(ctx, config) {
                         const schemas = ctx.tools.schemas(scope);
                         const metaToolsLive = ctx.tools.get(MCP_LIST_TOOL_NAME, scope) === listDefinition
                             && ctx.tools.get(MCP_CALL_TOOL_NAME, scope) === callDefinition;
-                        // ONE snapshot per execution keeps config.gate and view.gate identical.
+                        // ONE snapshot per execution keeps config.gate and view.gate identical;
+                        // volatile knobs are re-read per invocation (live settings-page edits).
                         const gate = getGate();
                         return executeMcpCommand({
                             rawInput: invocation.rawInput,
                             schemas,
-                            config: {
-                                prefix: config.prefix,
-                                keep: config.keep,
-                                servers: config.servers,
-                                descriptionLimit: config.descriptionLimit,
-                                gate,
-                            },
+                            config: { ...cfgNow(), gate },
                             metaToolsLive,
                             gate,
                             signal: invocation.signal,