@ema.co/mcp-toolkit 2026.2.27 → 2026.2.28

package/dist/mcp/handlers/feedback/outbox.js

@@ -0,0 +1,301 @@
+/**
+ * Outbox — Local accumulation and batched flush of feedback/telemetry.
+ *
+ * Raw entries are appended to ~/.ema-mcp/outbox/pending.jsonl. When flush
+ * conditions are met, the pending file is atomically renamed, coalesced into
+ * a FeedbackDigest, uploaded, and logged to sent-log.jsonl for transparency.
+ *
+ * Flush triggers:
+ * 1. MCP server boot (catches data from previous sessions, including npx)
+ * 2. Entry count threshold (default 50)
+ * 3. Periodic timer (30 min)
+ * 4. Age-based: oldest entry > 2 hours
+ *
+ * Race safety: rename-and-process ensures concurrent writers don't corrupt
+ * in-flight data. New entries go to a fresh pending.jsonl while the renamed
+ * batch is processed.
+ */
+import { promises as fs } from "node:fs";
+import { join } from "node:path";
+import { randomUUID } from "node:crypto";
+import { getEmaMcpDir } from "./client-id.js";
+import { buildDigest } from "./coalesce.js";
+import { uploadDigest } from "./remote-store.js";
+import { getOrCreateClientId } from "./client-id.js";
+// ─────────────────────────────────────────────────────────────────────────────
+// Constants
+// ─────────────────────────────────────────────────────────────────────────────
+const OUTBOX_DIR_NAME = "outbox";
+const PENDING_FILE = "pending.jsonl";
+const SENT_LOG_FILE = "sent-log.jsonl";
+const DEFAULT_FLUSH_THRESHOLD = 50;
+const FLUSH_INTERVAL_MS = 30 * 60 * 1000; // 30 minutes
+const MAX_AGE_MS = 2 * 60 * 60 * 1000; // 2 hours
+const MAX_PENDING_SIZE_BYTES = 5 * 1024 * 1024; // 5 MB safety cap
+let flushTimer = null;
+let flushInProgress = false;
+let entryCountSinceLastFlush = 0;
+let oldestEntryTs = null;
+// ─────────────────────────────────────────────────────────────────────────────
+// Paths
+// ─────────────────────────────────────────────────────────────────────────────
+function outboxDir() {
+    return join(getEmaMcpDir(), OUTBOX_DIR_NAME);
+}
+function pendingPath() {
+    return join(outboxDir(), PENDING_FILE);
+}
+function sentLogPath() {
+    return join(outboxDir(), SENT_LOG_FILE);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Append
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Append a raw entry to the local outbox. Fire-and-forget — never throws.
+ * Returns true if the caller should trigger a flush check.
+ */
+export async function appendToOutbox(entry) {
+    try {
+        const dir = outboxDir();
+        await fs.mkdir(dir, { recursive: true });
+        const path = pendingPath();
+        // Safety cap — don't let the file grow unbounded
+        try {
+            const stat = await fs.stat(path);
+            if (stat.size > MAX_PENDING_SIZE_BYTES) {
+                console.error("[FEEDBACK] Outbox pending file exceeds 5 MB — skipping append");
+                return true; // trigger flush to clear it
+            }
+        }
+        catch {
+            // File doesn't exist yet — fine
+        }
+        const line = JSON.stringify(entry) + "\n";
+        await fs.appendFile(path, line, "utf-8");
+        entryCountSinceLastFlush++;
+        if (oldestEntryTs === null) {
+            oldestEntryTs = Date.now();
+        }
+        const threshold = getFlushThreshold();
+        return entryCountSinceLastFlush >= threshold;
+    }
+    catch {
+        return false;
+    }
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Flush
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Flush the outbox: rename pending → processing, coalesce, upload, log.
+ * Safe for concurrent calls — only one flush runs at a time.
+ */
+export async function flushOutbox(toolkitVersion) {
+    if (flushInProgress)
+        return;
+    flushInProgress = true;
+    try {
+        // Recover orphaned processing files from previous crashes
+        await recoverOrphanedBatches(toolkitVersion);
+        const pending = pendingPath();
+        // Check if there's anything to flush
+        try {
+            const stat = await fs.stat(pending);
+            if (stat.size === 0)
+                return;
+        }
+        catch {
+            return; // No pending file
+        }
+        // Atomic rename — new entries go to a fresh pending.jsonl
+        const processingPath = join(outboxDir(), `processing_${Date.now()}_${randomUUID().slice(0, 8)}.jsonl`);
+        try {
+            await fs.rename(pending, processingPath);
+        }
+        catch {
+            return; // Rename failed — another flush may have beaten us
+        }
+        // Reset counters after rename
+        entryCountSinceLastFlush = 0;
+        oldestEntryTs = null;
+        // Parse entries from renamed file
+        const entries = await readOutboxEntries(processingPath);
+        if (entries.length === 0) {
+            await fs.unlink(processingPath).catch(() => { });
+            return;
+        }
+        // Build coalesced digest
+        const clientId = await getOrCreateClientId();
+        const digest = buildDigest(entries, clientId, toolkitVersion);
+        // Attempt upload
+        const uploaded = await uploadDigest(digest);
+        // Log to sent-log for transparency (regardless of upload success)
+        await logSentDigest(digest, uploaded);
+        // Clean up processing file
+        await fs.unlink(processingPath).catch(() => { });
+    }
+    catch (err) {
+        console.error(`[FEEDBACK] Flush error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    finally {
+        flushInProgress = false;
+    }
+}
+/**
+ * Check if a flush should be triggered based on entry count or age.
+ */
+export function shouldFlush() {
+    const threshold = getFlushThreshold();
+    if (entryCountSinceLastFlush >= threshold)
+        return true;
+    if (oldestEntryTs !== null) {
+        const age = Date.now() - oldestEntryTs;
+        if (age >= MAX_AGE_MS)
+            return true;
+    }
+    return false;
+}
+/**
+ * Start the periodic flush timer. Idempotent — safe to call multiple times.
+ */
+export function startFlushTimer(toolkitVersion) {
+    if (flushTimer)
+        return;
+    flushTimer = setInterval(() => {
+        if (shouldFlush()) {
+            flushOutbox(toolkitVersion).catch(() => { });
+        }
+    }, FLUSH_INTERVAL_MS);
+    // Don't keep the process alive just for feedback flushing
+    if (flushTimer && typeof flushTimer === "object" && "unref" in flushTimer) {
+        flushTimer.unref();
+    }
+}
+/**
+ * Stop the periodic flush timer and perform a final flush.
+ */
+export async function stopFlushTimer(toolkitVersion) {
+    if (flushTimer) {
+        clearInterval(flushTimer);
+        flushTimer = null;
+    }
+    await flushOutbox(toolkitVersion);
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Stats (for diagnostics)
+// ─────────────────────────────────────────────────────────────────────────────
+export async function getOutboxStats() {
+    let pendingEntries = 0;
+    let pendingSize = 0;
+    let sentDigests = 0;
+    try {
+        const stat = await fs.stat(pendingPath());
+        pendingSize = stat.size;
+        const content = await fs.readFile(pendingPath(), "utf-8");
+        pendingEntries = content.split("\n").filter((l) => l.trim()).length;
+    }
+    catch {
+        // No pending file
+    }
+    try {
+        const content = await fs.readFile(sentLogPath(), "utf-8");
+        sentDigests = content.split("\n").filter((l) => l.trim()).length;
+    }
+    catch {
+        // No sent log
+    }
+    return { pending_entries: pendingEntries, pending_size_bytes: pendingSize, sent_digests: sentDigests };
+}
+// ─────────────────────────────────────────────────────────────────────────────
+// Internals
+// ─────────────────────────────────────────────────────────────────────────────
+async function readOutboxEntries(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        return content
+            .split("\n")
+            .filter((line) => line.trim().length > 0)
+            .map((line) => {
+            try {
+                return JSON.parse(line);
+            }
+            catch {
+                return null;
+            }
+        })
+            .filter((entry) => entry !== null);
+    }
+    catch {
+        return [];
+    }
+}
+async function recoverOrphanedBatches(toolkitVersion) {
+    try {
+        const dir = outboxDir();
+        const files = await fs.readdir(dir).catch(() => []);
+        for (const f of files) {
+            if (!f.startsWith("processing_") || !f.endsWith(".jsonl"))
+                continue;
+            const orphanPath = join(dir, f);
+            const entries = await readOutboxEntries(orphanPath);
+            if (entries.length > 0) {
+                const clientId = await getOrCreateClientId();
+                const digest = buildDigest(entries, clientId, toolkitVersion);
+                const uploaded = await uploadDigest(digest);
+                await logSentDigest(digest, uploaded);
+            }
+            await fs.unlink(orphanPath).catch(() => { });
+        }
+    }
+    catch {
+        // Best-effort recovery
+    }
+}
+const MAX_SENT_LOG_ENTRIES = 200;
+async function logSentDigest(digest, uploaded) {
+    try {
+        const logEntry = {
+            ts: digest.flushed_at,
+            client_id: digest.client_id,
+            entry_count: digest.entry_count,
+            feedback_count: digest.feedback.length,
+            telemetry_count: digest.telemetry.length,
+            uploaded,
+            period: digest.period,
+        };
+        const dir = outboxDir();
+        await fs.mkdir(dir, { recursive: true });
+        const logPath = sentLogPath();
+        await fs.appendFile(logPath, JSON.stringify(logEntry) + "\n", "utf-8");
+        // Probabilistic rotation to prevent unbounded growth
+        if (Date.now() % 10 < 2) {
+            await rotateSentLog(logPath);
+        }
+    }
+    catch {
+        // Best-effort logging
+    }
+}
+async function rotateSentLog(filePath) {
+    try {
+        const content = await fs.readFile(filePath, "utf-8");
+        const lines = content.split("\n").filter((l) => l.trim().length > 0);
+        if (lines.length <= MAX_SENT_LOG_ENTRIES)
+            return;
+        const kept = lines.slice(lines.length - MAX_SENT_LOG_ENTRIES);
+        await fs.writeFile(filePath, kept.join("\n") + "\n", "utf-8");
+    }
+    catch {
+        // Best-effort rotation
+    }
+}
+function getFlushThreshold() {
+    const envVal = process.env.EMA_FEEDBACK_BATCH_THRESHOLD;
+    if (envVal) {
+        const parsed = parseInt(envVal, 10);
+        if (!isNaN(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_FLUSH_THRESHOLD;
+}

package/dist/mcp/handlers/feedback/probes.js

@@ -0,0 +1,127 @@
+/**
+ * Probe System — Targeted questions injected into MCP tool responses.
+ *
+ * Maintainers define probes (questions about specific tool behavior, pain points,
+ * or feature usage). The system injects one probe at a time into tool responses
+ * via a `_probe` field. Agents can respond using toolkit_feedback(category="probe_response").
+ *
+ * Probes are:
+ * - Rate-limited (max one per N tool calls)
+ * - Context-aware (only shown for matching tools/operations)
+ * - Tracked per-client (each probe shown at most once per client session)
+ */
+// ─────────────────────────────────────────────────────────────────────────────
+// Active Probes Registry
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Active probes defined by maintainers. Add/remove probes here to control
+ * what questions agents are asked. Keep this list short (3-5 probes max).
+ */
+export const ACTIVE_PROBES = [
+    {
+        id: "workflow-deploy-confidence-2026q1",
+        question: "When deploying workflows, how confident were you that the workflow_def you built was correct before deploying? What would increase your confidence?",
+        tools: ["workflow"],
+        operations: ["deploy"],
+    },
+    {
+        id: "guidance-usefulness-2026q1",
+        question: "Did the server instructions and _tip/_next_step guidance help you use the tools effectively? What was missing or unhelpful?",
+    },
+    {
+        id: "error-recovery-2026q1",
+        question: "When you encountered an error from an MCP tool, were you able to recover and try again? What information was missing from the error?",
+    },
+];
+// ─────────────────────────────────────────────────────────────────────────────
+// Session State
+// ─────────────────────────────────────────────────────────────────────────────
+function isFeedbackDisabled() {
+    return process.env.EMA_FEEDBACK_DISABLED === "1" ||
+        process.env.EMA_FEEDBACK_DISABLED === "true";
+}
+const PROBE_INTERVAL = 10; // show probe every N tool calls
+const respondedProbes = new Set();
+const shownProbes = new Set();
+let toolCallCount = 0;
+let probesShownCount = 0;
+// ─────────────────────────────────────────────────────────────────────────────
+// Public API
+// ─────────────────────────────────────────────────────────────────────────────
+/**
+ * Pick a probe to inject into a tool response, or return undefined.
+ * Rate-limited and context-aware.
+ */
+export function pickProbeForTool(toolName, operation) {
+    toolCallCount++;
+    if (isFeedbackDisabled())
+        return undefined;
+    if (toolCallCount % PROBE_INTERVAL !== 0)
+        return undefined;
+    const now = new Date().toISOString();
+    const candidates = ACTIVE_PROBES.filter((p) => {
+        if (respondedProbes.has(p.id))
+            return false;
+        if (shownProbes.has(p.id))
+            return false;
+        if (p.tools && p.tools.length > 0 && !p.tools.includes(toolName))
+            return false;
+        if (p.operations && p.operations.length > 0 && !p.operations.includes(operation))
+            return false;
+        if (p.active_from && now < p.active_from)
+            return false;
+        if (p.active_until && now > p.active_until)
+            return false;
+        return true;
+    });
+    if (candidates.length === 0)
+        return undefined;
+    const probe = candidates[0];
+    shownProbes.add(probe.id);
+    probesShownCount++;
+    return probe;
+}
+/**
+ * Record that a client responded to a probe.
+ * Called when toolkit_feedback receives a probe_response submission.
+ */
+export function markProbeResponded(probeId) {
+    respondedProbes.add(probeId);
+}
+/**
+ * Build the `_probe` field for a tool response.
+ */
+export function formatProbeField(probe) {
+    return {
+        id: probe.id,
+        type: "probe",
+        question: probe.question,
+        how_to_respond: `toolkit_feedback(method="submit", category="probe_response", message="<your answer>", context="${probe.id}")`,
+    };
+}
+/**
+ * Inject a probe into a response object if conditions are met.
+ * Mutates the response in-place for simplicity.
+ */
+export function maybeInjectProbe(response, toolName, operation) {
+    // Don't inject probes into feedback tool responses (avoid recursion)
+    if (toolName === "toolkit_feedback")
+        return;
+    const probe = pickProbeForTool(toolName, operation);
+    if (probe) {
+        response._probe = formatProbeField(probe);
+    }
+}
+/** Get the number of probes shown in this session (for digest metadata). */
+export function getProbesShownCount() {
+    return probesShownCount;
+}
+/**
+ * Reset session state (for testing).
+ */
+export function resetProbeState() {
+    respondedProbes.clear();
+    shownProbes.clear();
+    toolCallCount = 0;
+    probesShownCount = 0;
+}

package/dist/mcp/handlers/feedback/remote-store.js

@@ -0,0 +1,59 @@
+/**
+ * Remote Store — Fire-and-forget digest upload to cloud storage.
+ *
+ * Uploads a FeedbackDigest to a pre-configured GCS bucket via anonymous PUT.
+ * The upload is best-effort with a hard timeout — failure never blocks the
+ * main toolkit execution.
+ *
+ * Endpoint and behavior are controlled by environment variables:
+ * - EMA_FEEDBACK_ENDPOINT: Full base URL for PUT (e.g., "https://storage.googleapis.com/my-bucket")
+ * - EMA_FEEDBACK_DISABLED: Set to "1" or "true" to disable remote uploads entirely
+ */
+import { randomUUID } from "node:crypto";
+const UPLOAD_TIMEOUT_MS = 5_000;
+// TODO: Migrate to em1-feedback bucket (ema-dev-401514 project)
+// Once GCS permissions are configured for anonymous PUT on em1-feedback,
+// update this and copy existing digests from ema-mcp-feedback.
+// const DEFAULT_ENDPOINT = "https://storage.googleapis.com/em1-feedback";
+const DEFAULT_ENDPOINT = "https://storage.googleapis.com/ema-mcp-feedback";
+/**
+ * Upload a digest to the remote feedback store. Returns true on success.
+ * Never throws — all errors are swallowed (fire-and-forget).
+ */
+export async function uploadDigest(digest) {
+    const endpoint = getEndpoint();
+    if (!endpoint)
+        return false;
+    try {
+        const date = digest.flushed_at.slice(0, 10);
+        const key = `digests/${date}/digest_${digest.client_id}_${Date.now()}_${randomUUID()}.json`;
+        const url = `${endpoint}/${key}`;
+        const resp = await fetch(url, {
+            method: "PUT",
+            body: JSON.stringify(digest),
+            headers: { "Content-Type": "application/json" },
+            signal: AbortSignal.timeout(UPLOAD_TIMEOUT_MS),
+        });
+        if (resp.ok) {
+            console.error(`[FEEDBACK] Digest uploaded: ${key} (${digest.entry_count} entries)`);
+            return true;
+        }
+        console.error(`[FEEDBACK] Upload failed: HTTP ${resp.status} — ${await resp.text().catch(() => "(no body)")}`);
+        return false;
+    }
+    catch (err) {
+        console.error(`[FEEDBACK] Upload error: ${err instanceof Error ? err.message : String(err)}`);
+        return false;
+    }
+}
+function getEndpoint() {
+    const disabled = process.env.EMA_FEEDBACK_DISABLED === "1" ||
+        process.env.EMA_FEEDBACK_DISABLED === "true";
+    if (disabled)
+        return undefined;
+    return process.env.EMA_FEEDBACK_ENDPOINT || DEFAULT_ENDPOINT;
+}
+/** Check whether remote upload is configured and not disabled. */
+export function isRemoteEnabled() {
+    return !!getEndpoint();
+}

package/dist/mcp/handlers/feedback/store.js

@@ -12,6 +12,8 @@ import { promises as fs } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import { getToolkitRoot } from "../../../sdk/paths.js";
+import { appendToOutbox } from "./outbox.js";
+import { isRemoteEnabled } from "./remote-store.js";
 // ─────────────────────────────────────────────────────────────────────────────
 // Constants
 // ─────────────────────────────────────────────────────────────────────────────
@@ -95,6 +97,12 @@ export async function submitFeedback(entry, rootOverride) {
     await appendJsonl(filePath, full);
     // Log to stderr for visibility (stdout is the MCP stdio transport - never write there)
     console.error(`[FEEDBACK] ${full.category}: ${full.message}`);
+    // Mirror to outbox for centralized collection (fire-and-forget).
+    // Skipped when user has opted out, or for probe_response (written separately in index.ts).
+    if (isRemoteEnabled() && full.category !== "probe_response") {
+        const outboxEntry = { kind: "feedback", data: full };
+        appendToOutbox(outboxEntry).catch(() => { });
+    }
     return full;
 }
 /**
@@ -109,8 +117,12 @@ export async function recordTelemetry(entry, rootOverride) {
             ...entry,
         };
         await appendJsonl(filePath, full);
+        // Mirror to outbox for centralized collection (fire-and-forget)
+        if (isRemoteEnabled()) {
+            const outboxEntry = { kind: "telemetry", data: full };
+            appendToOutbox(outboxEntry).catch(() => { });
+        }
         // Rotate periodically (check every 100 writes based on simple modulo of time)
-        // We use a lightweight check: rotate if file > MAX * 1.5 entries
         const now = Date.now();
         if (now % 100 < 5) {
             await rotateJsonl(filePath, MAX_TELEMETRY_ENTRIES);

package/dist/mcp/handlers/persona/delete.js

@@ -4,8 +4,7 @@
  * Deletes a persona with safety confirmation.
  */
 import { resolvePersona, normalizeTriggerType } from "../utils.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 /**
  * Handle persona(mode="delete") - delete persona
  *
@@ -65,47 +64,27 @@ export async function handleDelete(args, client) {
             hint: "Use persona(method='delete', id='...', confirm=true) to proceed with deletion.",
         };
     }
-    // Strict guidance: snapshot before any destructive change (local, forced)
+    // Best-effort: snapshot before any destructive change (via central DIS storage)
     const force = args.force;
     const targetEnv = args.env ?? "unknown";
     if (fullPersona) {
         try {
-            const storage = createVersionStorage(process.cwd());
-            const engine = createVersionPolicyEngine(storage);
-            const snap = engine.forceCreateVersion(fullPersona, {
+            const { engine } = createCentralStorageEngine(client, fullPersona.id);
+            const snap = await engine.forceCreateVersion(fullPersona, {
                 environment: targetEnv,
                 tenant_id: targetEnv,
                 message: "Before delete",
                 created_by: "mcp-toolkit",
             });
-            if (!snap.created || !snap.version) {
-                if (!force) {
-                    return {
-                        error: "Failed to create pre-delete snapshot (required before delete)",
-                        persona_id: persona.id,
-                        details: snap.reason,
-                        hint: "Fix snapshotting (workspace storage) and retry deletion. Use force=true to bypass.",
-                    };
-                }
-                // force=true: proceed without snapshot (emergency only)
-            }
-            else {
+            if (snap.created && snap.version) {
                 deletionSummary.version_snapshot = {
                     id: snap.version.id,
                     version_name: snap.version.version_name,
                 };
             }
         }
-        catch (e) {
-            if (!force) {
-                return {
-                    error: "Failed to create pre-delete snapshot (required before delete)",
-                    persona_id: persona.id,
-                    details: e instanceof Error ? e.message : String(e),
-                    hint: "Fix snapshotting (workspace storage) and retry deletion. Use force=true to bypass.",
-                };
-            }
-            // force=true: proceed without snapshot (emergency only)
+        catch {
+            // Best-effort: snapshot failure does not block the delete
         }
     }
     // Perform deletion

package/dist/mcp/handlers/persona/update.js

@@ -16,8 +16,7 @@ import { PROJECT_TYPES } from "../../knowledge.js";
 import { resolvePersona, validateWidgetsForApi } from "../utils.js";
 import { validateSearchDataSourceConsistency, validationToHandlerResult } from "../workflow/validation.js";
 import { checkRemovedParams } from "../deprecation.js";
-import { createVersionStorage } from "../../../sync/version-storage.js";
-import { createVersionPolicyEngine } from "../../../sync/version-policy.js";
+import { createCentralStorageEngine } from "../../../sync/central-factory.js";
 import { fingerprintPersona } from "../../../sync.js";
 /**
  * Apply WorkflowSpec changes to an existing workflow_def.
@@ -234,41 +233,23 @@ export async function handleUpdate(args, client) {
             hint: "Re-run persona(method='get') / workflow(mode='get') to fetch the latest state, re-apply your changes, then update again. Use force=true only if you intend to overwrite out-of-band changes.",
         };
     }
-    // Strict guidance: snapshot before any update/change (local, forced)
+    // Best-effort: snapshot before any update/change (via central DIS storage)
     const targetEnv = args.env ?? "unknown";
     let versionSnapshot;
     try {
-        const storage = createVersionStorage(process.cwd());
-        const engine = createVersionPolicyEngine(storage);
-        const snap = engine.forceCreateVersion(fullPersona, {
+        const { engine } = createCentralStorageEngine(client, fullPersona.id);
+        const snap = await engine.forceCreateVersion(fullPersona, {
             environment: targetEnv,
             tenant_id: targetEnv,
             message: "Pre-update snapshot",
             created_by: "mcp-toolkit",
         });
-        if (!snap.created || !snap.version) {
-            if (!force) {
-                return {
-                    error: "Failed to create pre-update snapshot (required before update)",
-                    persona_id: persona.id,
-                    details: snap.reason,
-                    hint: "Fix snapshotting (workspace storage) or retry with force=true for emergency override.",
-                };
-            }
-        }
-        else {
+        if (snap.created && snap.version) {
             versionSnapshot = { id: snap.version.id, version_name: snap.version.version_name };
         }
     }
-    catch (e) {
-        if (!force) {
-            return {
-                error: "Failed to create pre-update snapshot (required before update)",
-                persona_id: persona.id,
-                details: e instanceof Error ? e.message : String(e),
-                hint: "Retry after fixing local workspace write access, or use force=true for emergency override.",
-            };
-        }
+    catch {
+        // Best-effort: snapshot failure does not block the update
     }
     const existingProtoConfig = (fullPersona?.proto_config ?? persona.proto_config ?? {});
     const existingWorkflow = fullPersona