@jhizzard/termdeck 0.16.1 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jhizzard/termdeck",
-  "version": "0.16.1",
+  "version": "0.17.0",
   "description": "Browser-based terminal multiplexer with metadata overlays, panel flashback memory recall, and AI-aware session management",
   "bin": {
     "termdeck": "./packages/cli/src/index.js"

package/packages/server/src/agent-adapters/claude.js

@@ -7,7 +7,8 @@
 // transcript-parser cut-offs. Sprint 45 adds Codex / Gemini / Grok adapters
 // alongside this one; Sprint 46 wires per-lane agent assignment in 4+1.
 //
-// Contract (memorialization doc § 4 + lane brief T3):
+// Contract (memorialization doc § 4 + lane brief T3, extended in Sprint 47
+// T3 with `acceptsPaste` and Sprint 48 T1 with `mcpConfig`):
 //   {
 //     name:           string,                     // adapter id used in registry
 //     sessionType:    string,                     // session.meta.type produced
@@ -19,6 +20,10 @@
 //     parseTranscript:(raw) => Memory[],          // for memory-session-end hook
 //     bootPromptTemplate: (lane, sprint) => string,
 //     costBand:       'free' | 'pay-per-token' | 'subscription',
+//     acceptsPaste:   boolean,                    // Sprint 47 T3 — bracketed-paste capable
+//     mcpConfig:      { path, format, mnestraBlock, detectExisting } | null,
+//                                                 // Sprint 48 T1 — per-agent MCP auto-wire
+//                                                 // null = user-managed (Claude only)
 //   }
 //
 // `statusFor` returns null when no pattern matches — preserves the original
@@ -157,6 +162,11 @@ const claudeAdapter = {
   // The two-stage submit pattern (paste then \r alone) is the canonical inject
   // shape for this adapter; chunked-fallback is unnecessary.
   acceptsPaste: true,
+  // Sprint 48 T1 — Claude's MCP config (~/.claude.json) is owned by the user
+  // and `claude mcp add`. Auto-wiring a Mnestra block here would conflict
+  // with that surface. `null` declares the contract field while signalling
+  // "user-managed; mcp-autowire.js short-circuits to skipped:no-mcpConfig".
+  mcpConfig: null,
 };
 
 module.exports = claudeAdapter;

package/packages/server/src/agent-adapters/codex.js

@@ -197,6 +197,36 @@ const codexAdapter = {
   // Sprint 47 T3 — Codex's Ratatui TUI accepts bracketed-paste per the
   // Sprint 45 T1 audit; safe to use the two-stage submit pattern unchanged.
   acceptsPaste: true,
+  // Sprint 48 T1 — per-agent MCP auto-wire descriptor consumed by
+  // packages/server/src/mcp-autowire.js. Codex reads MCP servers from
+  // ~/.codex/config.toml in the canonical `[mcp_servers.NAME]` shape with a
+  // sibling `[mcp_servers.NAME.env]` table (snake_case, NOT camelCase — that
+  // distinguishes Codex's TOML schema from the JSON-based agents).
+  mcpConfig: {
+    path: '~/.codex/config.toml',
+    format: 'toml',
+    mnestraBlock: ({ secrets }) => {
+      const lines = ['[mcp_servers.mnestra]', 'command = "mnestra"'];
+      const wanted = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+      const env = {};
+      for (const k of wanted) {
+        if (secrets && typeof secrets[k] === 'string' && secrets[k].length > 0) {
+          env[k] = secrets[k];
+        }
+      }
+      if (Object.keys(env).length > 0) {
+        lines.push('');
+        lines.push('[mcp_servers.mnestra.env]');
+        for (const [k, v] of Object.entries(env)) {
+          // TOML basic-string escaping — backslash + double-quote.
+          const escaped = String(v).replace(/\\/g, '\\\\').replace(/"/g, '\\"');
+          lines.push(`${k} = "${escaped}"`);
+        }
+      }
+      return lines.join('\n') + '\n';
+    },
+    detectExisting: (text) => /^\s*\[mcp_servers\.mnestra\]\s*$/m.test(text),
+  },
 };
 
 module.exports = codexAdapter;

package/packages/server/src/agent-adapters/gemini.js

@@ -126,6 +126,54 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
   ].join('\n');
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// mcpConfig — Sprint 48 T2. Declarative description of where Gemini reads
+// its MCP-server registry and how to write a Mnestra entry into it. The
+// shared helper at packages/server/src/mcp-autowire.js (Sprint 48 T1) uses
+// this on panel spawn to ensure `memory_recall` is available out-of-the-box
+// for outside users running mixed 4+1 with a Gemini lane.
+//
+// Schema reference: https://www.geminicli.com/docs/tools/mcp-server
+// (verified 2026-05-02). Top-level key is `mcpServers` (camelCase). Each
+// entry must specify exactly one transport — `command` (stdio), `url`
+// (SSE), or `httpUrl` (HTTP streaming). Mnestra ships as a stdio binary
+// (`mnestra`), so we use `command`.
+//
+// Note (no `type` field): the `type: 'stdio'` field used in the Claude
+// Code config (~/.claude.json `mcp_servers.mnestra.type`) is a Claude-Code
+// extension. Gemini infers transport from which of command/url/httpUrl is
+// set, so we omit `type` here to keep the entry valid against the
+// documented Gemini schema.
+//
+// Note (restart required): Gemini CLI discovers MCP servers at startup, so
+// adding a new entry only takes effect on the next `gemini` launch. The
+// helper still writes immediately on panel spawn — by the time the user
+// types `gemini` in the panel, the entry is in place.
+//
+// Note (env-key omission): empty/missing secrets are intentionally
+// dropped from the env object instead of written as empty strings. This
+// matches stack-installer/src/index.js:336-339 — concrete-or-omit, never
+// placeholder, because Gemini (like Claude Code) does not shell-expand
+// `${VAR}` references in MCP env. Mnestra's own secrets.env fallback
+// loads what's missing at process start.
+// ──────────────────────────────────────────────────────────────────────────
+
+const MNESTRA_ENV_KEYS = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+
+function buildMnestraBlock({ secrets } = {}) {
+  const env = {};
+  for (const key of MNESTRA_ENV_KEYS) {
+    const value = secrets && secrets[key];
+    if (value) env[key] = value;
+  }
+  return {
+    mnestra: {
+      command: 'mnestra',
+      env,
+    },
+  };
+}
+
 const geminiAdapter = {
   name: 'gemini',
   sessionType: 'gemini',
@@ -156,6 +204,13 @@ const geminiAdapter = {
   // Sprint 47 T3 — Gemini's CLI is paste-friendly per the single-JSON-object
   // session shape captured in Sprint 45 T2; bracketed-paste injects cleanly.
   acceptsPaste: true,
+  // Sprint 48 T2 — see comment block above for schema notes + provenance.
+  mcpConfig: {
+    path: '~/.gemini/settings.json',
+    format: 'json',
+    mcpServersKey: 'mcpServers',
+    mnestraBlock: buildMnestraBlock,
+  },
 };
 
 module.exports = geminiAdapter;

package/packages/server/src/agent-adapters/grok.js

@@ -218,6 +218,136 @@ function bootPromptTemplate(lane = {}, sprint = {}) {
   ].join('\n');
 }
 
+// ──────────────────────────────────────────────────────────────────────────
+// mcpConfig — Sprint 48 T3. Grok's MCP-server registry lives at
+// `~/.grok/user-settings.json` under the `mcp.servers` key, which is an
+// **ARRAY** of `McpServerConfig` items, NOT a record `mcpServers.NAME` like
+// Codex/Gemini use. Authoritative schema lifted from
+// `/usr/local/lib/node_modules/grok-dev/dist/utils/settings.{d.ts,js}`
+// (Bun-bundled source, package `grok-dev` v1.1.5):
+//
+//   interface McpServerConfig {
+//     id: string; label: string; enabled: boolean;
+//     transport: "http" | "sse" | "stdio";
+//     command?, args?, env?, cwd?, url?, headers?
+//   }
+//   interface McpSettings { servers?: McpServerConfig[] }
+//   interface UserSettings { ..., mcp?: McpSettings }
+//   function loadMcpServers(): UserSettings.mcp?.servers ?? []
+//   function saveMcpServers(servers): saveUserSettings({ mcp: { servers } })
+//
+// Hot-load behavior: agent.js calls `loadMcpServers()` at the start of every
+// agent turn (3 sites: stream / batch / child-agent), so MCP changes are
+// picked up on the next user message — no Grok restart required.
+//
+// Schema-divergence implication: the `mcpServersKey + mnestraBlock` record-
+// merge shape used by gemini.js (Sprint 48 T2) and the TOML-append shape used
+// by codex.js cannot represent Grok's array-with-explicit-id-fields layout.
+// Grok therefore declares a `merge(rawText, { secrets }) -> { changed, output }`
+// escape-hatch on its `mcpConfig`. The shared `mcp-autowire.js` helper
+// (Sprint 48 T1) checks for `mcpConfig.merge` first; if present, the adapter
+// owns parse + mutate + serialize, the helper still owns tilde-expansion +
+// parent-dir creation + atomic write + idempotency reporting. See Sprint 48
+// STATUS.md § T3 FIX-PROPOSED for the coordination decision.
+//
+// Env-key omission discipline matches stack-installer/src/index.js:336-339
+// and the Gemini adapter: empty/missing/`${VAR}`-placeholder values are
+// dropped from the env object instead of written as empty strings, because
+// Grok (like Claude Code and Gemini) does not shell-expand `${VAR}` in MCP
+// env. Mnestra's own secrets.env stdio fallback (mnestra@0.3.4) loads what
+// is missing at process start.
+// ──────────────────────────────────────────────────────────────────────────
+
+const MNESTRA_ENV_KEYS = ['SUPABASE_URL', 'SUPABASE_SERVICE_ROLE_KEY', 'OPENAI_API_KEY'];
+
+function _pickConcreteEnv(secrets) {
+  const env = {};
+  if (!secrets || typeof secrets !== 'object') return env;
+  for (const key of MNESTRA_ENV_KEYS) {
+    const value = secrets[key];
+    if (typeof value !== 'string') continue;
+    if (value.length === 0) continue;
+    // Reject literal `${VAR}` placeholders — Grok won't shell-expand them.
+    if (/^\$\{[^}]*\}$/.test(value)) continue;
+    env[key] = value;
+  }
+  return env;
+}
+
+function _buildMnestraServer({ secrets } = {}) {
+  return {
+    id: 'mnestra',
+    label: 'Mnestra',
+    enabled: true,
+    transport: 'stdio',
+    command: 'mnestra',
+    args: [],
+    env: _pickConcreteEnv(secrets),
+  };
+}
+
+// Deep-equal check scoped to the fields we manage. Unknown extra fields on
+// the existing entry (e.g. user-added `cwd` overrides) are tolerated — we
+// only refresh the entry when one of OUR managed fields drifts. Prevents
+// the helper from clobbering hand-edited Grok customizations on every spawn.
+function _mnestraEntryEqual(existing, desired) {
+  if (!existing || typeof existing !== 'object') return false;
+  for (const key of ['id', 'label', 'enabled', 'transport', 'command']) {
+    if (existing[key] !== desired[key]) return false;
+  }
+  const a = Array.isArray(existing.args) ? existing.args : [];
+  const b = desired.args;
+  if (a.length !== b.length) return false;
+  for (let i = 0; i < a.length; i += 1) if (a[i] !== b[i]) return false;
+  const ea = existing.env && typeof existing.env === 'object' ? existing.env : {};
+  const eb = desired.env;
+  const eaKeys = Object.keys(ea).sort();
+  const ebKeys = Object.keys(eb).sort();
+  if (eaKeys.length !== ebKeys.length) return false;
+  for (let i = 0; i < eaKeys.length; i += 1) {
+    if (eaKeys[i] !== ebKeys[i]) return false;
+    if (ea[eaKeys[i]] !== eb[ebKeys[i]]) return false;
+  }
+  return true;
+}
+
+function _mergeMnestraIntoGrokSettings(rawText, { secrets } = {}) {
+  let current = {};
+  if (typeof rawText === 'string' && rawText.trim().length > 0) {
+    try {
+      const parsed = JSON.parse(rawText);
+      if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        current = parsed;
+      }
+    } catch (_) {
+      // Malformed JSON → start fresh. Helper's atomic-write contract means
+      // we don't risk corrupting the user's file partway through; on read
+      // failure the conservative path is to write a clean replacement that
+      // preserves the keys we know how to round-trip (none — we only own
+      // the mcp branch). User's other settings in a corrupt file are
+      // unrecoverable from text anyway.
+      current = {};
+    }
+  }
+  const next = { ...current };
+  next.mcp = next.mcp && typeof next.mcp === 'object' && !Array.isArray(next.mcp)
+    ? { ...next.mcp }
+    : {};
+  const servers = Array.isArray(next.mcp.servers) ? [...next.mcp.servers] : [];
+  const desired = _buildMnestraServer({ secrets });
+  const existingIdx = servers.findIndex((s) => s && s.id === 'mnestra');
+  if (existingIdx >= 0 && _mnestraEntryEqual(servers[existingIdx], desired)) {
+    return { changed: false, output: rawText };
+  }
+  if (existingIdx >= 0) {
+    servers[existingIdx] = desired;
+  } else {
+    servers.push(desired);
+  }
+  next.mcp.servers = servers;
+  return { changed: true, output: `${JSON.stringify(next, null, 2)}\n` };
+}
+
 // ──────────────────────────────────────────────────────────────────────────
 // Adapter export. spawn.env.GROK_MODEL defaults to the cheap-fast tier;
 // per-lane override is the launcher's job at session-spawn time (Sprint 46
@@ -260,6 +390,15 @@ const grokAdapter = {
   // lane-time test shows the OpenTUI input handler eats the paste markers,
   // flip this to false and the inject helper falls back to chunked stdin.
   acceptsPaste: true,
+  // Sprint 48 T3 — see comment block above for schema notes + provenance.
+  // Grok deviates from Codex (TOML) and Gemini (JSON record) — its `mcp.servers`
+  // is an array with explicit `id`/`label`/`enabled`/`transport` fields, so the
+  // adapter declares a `merge` escape-hatch instead of `mcpServersKey + mnestraBlock`.
+  mcpConfig: {
+    path: '~/.grok/user-settings.json',
+    format: 'json',
+    merge: _mergeMnestraIntoGrokSettings,
+  },
 };
 
 module.exports = grokAdapter;

package/packages/server/src/index.js

@@ -81,6 +81,53 @@ const orchestrationPreview = require('./orchestration-preview');
 const { createPtyReaper } = require('./pty-reaper');
 const { AGENT_ADAPTERS } = require('./agent-adapters');
 
+// Sprint 48 T4 deliverable 2: PTY env-var propagation.
+// Reads ~/.termdeck/secrets.env once per server lifetime so each PTY spawn
+// inherits SUPABASE_URL / SUPABASE_SERVICE_ROLE_KEY / OPENAI_API_KEY etc.
+// without depending on the user's shell to have sourced the file.
+//
+// Why this exists: `memory-session-end.js` (the bundled Stop hook installed by
+// `@jhizzard/termdeck-stack`) writes session_summary rows to Mnestra by
+// reading those three vars from `process.env`. When TermDeck spawns a Claude
+// Code panel directly via `pty.spawn`, the child shell inherits the server's
+// `process.env` — but if the *user* didn't source secrets.env in their
+// `.zshrc` before running `termdeck`, those vars are absent and every session
+// close hits `env-var-missing`. Sprint 47 close-out audit confirmed 0
+// session_summary rows had ever landed.
+//
+// Treats `${VAR}` placeholders as unset (Sprint 47.5 hotfix lesson — Claude
+// Code does not shell-expand MCP env values; same trap applies anywhere the
+// secrets file flows through a non-shell consumer).
+let _termdeckSecretsCache = null;
+function readTermdeckSecretsForPty() {
+  if (_termdeckSecretsCache !== null) return _termdeckSecretsCache;
+  const secretsPath = path.join(os.homedir(), '.termdeck', 'secrets.env');
+  const out = {};
+  try {
+    const text = fs.readFileSync(secretsPath, 'utf8');
+    for (const raw of text.split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      let v = m[2].trim();
+      if (v.length >= 2 && (v[0] === '"' || v[0] === "'") && v[v.length - 1] === v[0]) {
+        v = v.slice(1, -1);
+      }
+      if (v.startsWith('${') && v.endsWith('}')) continue;
+      if (v === '') continue;
+      out[m[1]] = v;
+    }
+  } catch (_err) {
+    // File absent or unreadable — empty merge, hook still hits env-var-missing
+    // until the user runs the wizard. Better than a crash on spawn.
+  }
+  _termdeckSecretsCache = out;
+  return out;
+}
+// Test hook — clear the cache between tests that mutate the on-disk file.
+function _resetTermdeckSecretsCache() { _termdeckSecretsCache = null; }
+
 // Sprint 37 T3 — lazy resolution of T2's CLI modules. The orchestration-preview
 // helper is decoupled from T2's templates.js / init-project.js; we resolve
 // them here and pass them into the helper. If a module is missing (e.g.
@@ -805,6 +852,18 @@ function createServer(config) {
       const args = (cmdTrim && !isPlainShell) ? ['-c', cmdTrim] : [];
 
       try {
+        // Sprint 48 T4: merge ~/.termdeck/secrets.env into the PTY env so
+        // the bundled session-end memory hook (`memory-session-end.js`) sees
+        // SUPABASE_URL / SERVICE_ROLE_KEY / OPENAI_API_KEY without depending
+        // on the user's shell to have sourced the file. process.env is the
+        // base; any concrete value the parent already exported wins.
+        const termdeckSecrets = readTermdeckSecretsForPty();
+        const secretFallback = {};
+        for (const [k, v] of Object.entries(termdeckSecrets)) {
+          if (process.env[k] === undefined || process.env[k] === '') {
+            secretFallback[k] = v;
+          }
+        }
         const term = pty.spawn(spawnShell, args, {
           name: 'xterm-256color',
           cols: 120,
@@ -812,6 +871,7 @@ function createServer(config) {
           cwd: resolvedCwd,
           env: {
             ...process.env,
+            ...secretFallback,
             TERMDECK_SESSION: session.id,
             TERMDECK_PROJECT: project || '',
             TERM: 'xterm-256color',
@@ -2162,4 +2222,10 @@ if (require.main === module) {
   });
 }
 
-module.exports = { createServer, loadConfig };
+module.exports = {
+  createServer,
+  loadConfig,
+  // Sprint 48 T4 — exported for unit testing the secrets.env → PTY env merge.
+  readTermdeckSecretsForPty,
+  _resetTermdeckSecretsCache,
+};

package/packages/server/src/mcp-autowire.js

@@ -0,0 +1,253 @@
+// Sprint 48 T1 — Shared per-agent MCP auto-wire helper.
+//
+// Single export: ensureMnestraBlock(adapter, opts?). Idempotent. T1/T2/T3
+// agent adapters (codex, gemini, grok) each ship an `mcpConfig` field
+// describing where their MCP-server config lives, what format it's in,
+// and how to merge a Mnestra entry into it. This helper is the agent-
+// agnostic glue: read the file, dispatch on shape, render+merge+write
+// using the secrets in ~/.termdeck/secrets.env.
+//
+// Why this exists: cross-project memory recall (Mnestra MCP) was unavailable
+// to non-Claude agents by default in Sprint 47's Grok smoke — those CLIs
+// ship without an MCP block and outside users would hit memory_recall
+// failures the first time they spawned a non-Claude lane. This is the
+// v1.0.0 gate-blocker fix.
+//
+// Three adapter shapes are supported (precedence top → bottom):
+//
+//   1. Escape-hatch (Grok-style — array-shape JSON or anything bespoke):
+//        mcpConfig: { path, format, merge: (rawText, {secrets}) =>
+//                                          ({ changed: bool, output: string }) }
+//      Adapter owns parse + mutate + serialize entirely. Helper still owns
+//      tilde expand, mkdir, read, atomic write, return shape.
+//
+//   2. JSON-record (Gemini-style — `{mcpServers: {NAME: {...}}}`):
+//        mcpConfig: { path, format: 'json', mcpServersKey: 'mcpServers',
+//                     mnestraBlock: ({secrets}) => ({mnestra: {command, env}}) }
+//      Helper deep-merges the returned object under `config[mcpServersKey]`.
+//      Existence detected by checking `existing[mcpServersKey]?.mnestra`.
+//
+//   3. TOML-append (Codex-style — `[mcp_servers.NAME]` tables):
+//        mcpConfig: { path, format: 'toml',
+//                     mnestraBlock: ({secrets}) => '[mcp_servers.mnestra]\n...',
+//                     detectExisting: (text) => /\[mcp_servers\.mnestra\]/m.test(text) }
+//      Helper appends the rendered string to the file with one blank-line
+//      separator. Idempotent via the adapter's `detectExisting` predicate.
+//
+// Claude is intentionally exempt — its MCP config (~/.claude.json) is
+// owned by the user and `claude mcp add`. Adding a Mnestra block here
+// would conflict with that surface. Claude's adapter declares
+// `mcpConfig: null` to satisfy the contract-parity tests.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const SECRETS_PATH = path.join(os.homedir(), '.termdeck', 'secrets.env');
+
+function expandTilde(p) {
+  if (typeof p !== 'string') return p;
+  if (p === '~') return os.homedir();
+  if (p.startsWith('~/')) return path.join(os.homedir(), p.slice(2));
+  return p;
+}
+
+// dotenv-subset parser. Mirrors stack-installer's readTermdeckSecrets so the
+// two stay byte-equivalent (KEY=value, optional matched single/double quotes,
+// `#` comments, blanks ignored). Returns {} on absent / unreadable file.
+// Rejects literal `${VAR}` placeholder shapes — same defense as the mnestra
+// MCP stdio fallback (Claude Code et al. don't shell-expand them, so writing
+// the literal placeholder is worse than omitting the key entirely).
+function readSecrets(secretsPath = SECRETS_PATH) {
+  try {
+    const text = fs.readFileSync(secretsPath, 'utf8');
+    const out = {};
+    for (const raw of text.split('\n')) {
+      const line = raw.trim();
+      if (!line || line.startsWith('#')) continue;
+      const m = line.match(/^([A-Z_][A-Z0-9_]*)=(.*)$/);
+      if (!m) continue;
+      let v = m[2];
+      if (
+        v.length >= 2
+        && (v[0] === '"' || v[0] === "'")
+        && v[v.length - 1] === v[0]
+      ) {
+        v = v.slice(1, -1);
+      }
+      if (v.startsWith('${') && v.endsWith('}')) continue;
+      out[m[1]] = v;
+    }
+    return out;
+  } catch (_err) {
+    return {};
+  }
+}
+
+// One-level-deep merge sufficient for the `mcpServers.NAME` shape. Nested
+// objects under matching keys are themselves merged shallowly; arrays +
+// primitives are replaced.
+function mergeJson(base, addition) {
+  const out = { ...base };
+  for (const [k, v] of Object.entries(addition)) {
+    if (
+      v && typeof v === 'object' && !Array.isArray(v)
+      && out[k] && typeof out[k] === 'object' && !Array.isArray(out[k])
+    ) {
+      out[k] = { ...out[k], ...v };
+    } else {
+      out[k] = v;
+    }
+  }
+  return out;
+}
+
+// Append a TOML block to existing file content with one blank-line separator
+// (or none if the file is empty). Codex's TOML parser accepts tables in any
+// order so appending is the safe operation; we don't try to surgically
+// rewrite mid-file.
+function appendTomlBlock(existing, block) {
+  const trailing = existing.endsWith('\n') ? '' : '\n';
+  const sep = existing.length === 0 ? '' : trailing + '\n';
+  const blockTail = block.endsWith('\n') ? '' : '\n';
+  return existing + sep + block + blockTail;
+}
+
+// Detect whether a JSON-shape object already has a Mnestra entry under
+// `mcpServersKey`. Tolerant of the key being absent or non-object.
+function jsonAlreadyHasMnestra(parsedConfig, mcpServersKey) {
+  const bag = parsedConfig && parsedConfig[mcpServersKey];
+  return !!(bag && typeof bag === 'object' && !Array.isArray(bag) && bag.mnestra);
+}
+
+// Idempotent. Returns one of:
+//   { skipped: true, reason: '...' }     — adapter omits or malforms mcpConfig
+//   { unchanged: true, path }            — block already present
+//   { wrote: true, path, bytes }         — block written / appended
+//
+// opts.secretsPath overrides the default ~/.termdeck/secrets.env (used by
+// tests); opts.secrets passes a pre-parsed object directly (also tests).
+function ensureMnestraBlock(adapter, opts = {}) {
+  if (!adapter || !adapter.mcpConfig) {
+    return { skipped: true, reason: 'no-mcpConfig' };
+  }
+  const cfg = adapter.mcpConfig;
+  if (typeof cfg.path !== 'string') {
+    return { skipped: true, reason: 'malformed-mcpConfig' };
+  }
+
+  const useMerge = typeof cfg.merge === 'function';
+  const useJsonRecord = !useMerge
+    && cfg.format === 'json'
+    && typeof cfg.mcpServersKey === 'string'
+    && typeof cfg.mnestraBlock === 'function';
+  const useTomlAppend = !useMerge && !useJsonRecord
+    && cfg.format === 'toml'
+    && typeof cfg.mnestraBlock === 'function'
+    && typeof cfg.detectExisting === 'function';
+  const useJsonAppend = !useMerge && !useJsonRecord && !useTomlAppend
+    && cfg.format === 'json'
+    && typeof cfg.mnestraBlock === 'function'
+    && typeof cfg.detectExisting === 'function';
+
+  if (!useMerge && !useJsonRecord && !useTomlAppend && !useJsonAppend) {
+    return { skipped: true, reason: 'malformed-mcpConfig' };
+  }
+
+  const target = expandTilde(cfg.path);
+  const dir = path.dirname(target);
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+  let existing = '';
+  try { existing = fs.readFileSync(target, 'utf8'); } catch (_) { existing = ''; }
+
+  const secrets = opts.secrets || readSecrets(opts.secretsPath || SECRETS_PATH);
+
+  // 1. Escape-hatch — adapter owns the merge entirely.
+  if (useMerge) {
+    let result;
+    try { result = cfg.merge(existing, { secrets, adapter }); }
+    catch (e) { return { skipped: true, reason: `merge-threw-${e.message}` }; }
+    if (!result || typeof result !== 'object') {
+      return { skipped: true, reason: 'merge-bad-return' };
+    }
+    if (!result.changed) return { unchanged: true, path: target };
+    if (typeof result.output !== 'string') {
+      return { skipped: true, reason: 'merge-output-not-string' };
+    }
+    fs.writeFileSync(target, result.output, { mode: 0o600 });
+    return { wrote: true, path: target, bytes: Buffer.byteLength(result.output) };
+  }
+
+  // 2. JSON record-merge (Gemini shape).
+  if (useJsonRecord) {
+    let parsed = {};
+    if (existing.trim() !== '') {
+      try { parsed = JSON.parse(existing); }
+      catch (_) { return { skipped: true, reason: 'existing-json-malformed' }; }
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) parsed = {};
+    }
+    if (jsonAlreadyHasMnestra(parsed, cfg.mcpServersKey)) {
+      return { unchanged: true, path: target };
+    }
+    let block;
+    try { block = cfg.mnestraBlock({ secrets, adapter }); }
+    catch (e) { return { skipped: true, reason: `mnestraBlock-threw-${e.message}` }; }
+    if (!block || typeof block !== 'object' || Array.isArray(block)) {
+      return { skipped: true, reason: 'mnestraBlock-not-object' };
+    }
+    const next = { ...parsed };
+    const bag = (next[cfg.mcpServersKey] && typeof next[cfg.mcpServersKey] === 'object'
+                 && !Array.isArray(next[cfg.mcpServersKey]))
+      ? { ...next[cfg.mcpServersKey] }
+      : {};
+    Object.assign(bag, block);
+    next[cfg.mcpServersKey] = bag;
+    const serialized = JSON.stringify(next, null, 2) + '\n';
+    fs.writeFileSync(target, serialized, { mode: 0o600 });
+    return { wrote: true, path: target, bytes: Buffer.byteLength(serialized) };
+  }
+
+  // 3 & 4. detectExisting + mnestraBlock-string paths (TOML or JSON-append).
+  if (cfg.detectExisting(existing)) {
+    return { unchanged: true, path: target };
+  }
+  let block;
+  try { block = cfg.mnestraBlock({ secrets, adapter }); }
+  catch (e) { return { skipped: true, reason: `mnestraBlock-threw-${e.message}` }; }
+  if (typeof block !== 'string') {
+    return { skipped: true, reason: 'mnestraBlock-not-string' };
+  }
+
+  let next;
+  if (useTomlAppend) {
+    next = appendTomlBlock(existing, block);
+  } else {
+    // useJsonAppend — original brief shape: mnestraBlock returns JSON text,
+    // helper deep-merges. Used by adapters that prefer to control the
+    // serialization but don't want the escape-hatch's full responsibility.
+    let parsed = {};
+    if (existing.trim() !== '') {
+      try { parsed = JSON.parse(existing); }
+      catch (_) { return { skipped: true, reason: 'existing-json-malformed' }; }
+    }
+    let blockObj;
+    try { blockObj = JSON.parse(block); }
+    catch (_) { return { skipped: true, reason: 'mnestraBlock-not-parseable-json' }; }
+    const merged = mergeJson(parsed, blockObj);
+    next = JSON.stringify(merged, null, 2) + '\n';
+  }
+
+  fs.writeFileSync(target, next, { mode: 0o600 });
+  return { wrote: true, path: target, bytes: Buffer.byteLength(next) };
+}
+
+module.exports = {
+  ensureMnestraBlock,
+  readSecrets,
+  expandTilde,
+  // Internals exposed for unit tests; not part of the public API.
+  _internals: { mergeJson, appendTomlBlock, jsonAlreadyHasMnestra, SECRETS_PATH },
+};