@claude-flow/cli 3.68.0 → 3.70.0

package/dist/src/mcp-tools/agentdb-episode-tools.js

@@ -0,0 +1,214 @@
+/**
+ * agentdb_episode-get / -list / -update / -delete (ADR-520).
+ *
+ * Episodes are the records session ends and `memory distill` write and that
+ * agentdb_episode-recall searches. Needs agentdb >= 3.3.0 (in-place update that keeps the id
+ * and re-indexes); older builds get a clear error instead of a partial operation.
+ *
+ * @module v3/cli/mcp-tools/agentdb-episode-tools
+ */
+import { validateText } from './validate-input.js';
+const TEXT_MAX = 50_000;
+const METADATA_MAX_BYTES = 64 * 1024;
+const FORBIDDEN_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
+let crud = null;
+async function episodeCrud() {
+    crud ??= await import('../memory/episode-crud.js');
+    return crud;
+}
+const unavailable = { success: false, error: 'AgentDB ReflexionMemory not available. Use memory_* tools instead.' };
+function idOf(value, parse) {
+    const id = parse(value);
+    return id ?? { error: 'id must be a positive integer' };
+}
+function hasForbiddenKey(value, depth = 0) {
+    if (depth > 16)
+        return true;
+    if (!value || typeof value !== 'object')
+        return false;
+    for (const [k, v] of Object.entries(value)) {
+        if (FORBIDDEN_KEYS.has(k) || hasForbiddenKey(v, depth + 1))
+            return true;
+    }
+    return false;
+}
+/** Optional text field: undefined = leave alone, null = clear, string = set. */
+function optionalText(value, name, nullable) {
+    if (value === undefined)
+        return {};
+    if (value === null)
+        return nullable ? { value: null } : { error: `${name} cannot be null` };
+    const v = validateText(value, name, TEXT_MAX);
+    if (!v.valid)
+        return { error: v.error };
+    if (!nullable && !v.sanitized.trim())
+        return { error: `${name} cannot be empty` };
+    return { value: v.sanitized };
+}
+export const agentdbEpisodeGet = {
+    name: 'agentdb_episode-get',
+    description: 'Get one past episode (a session summary or distilled trajectory) by id. Use when you already have an episode id from agentdb_episode-recall or agentdb_episode-list and need its full record; memory_retrieve is wrong here because episodes are not key-value entries. Returns episode: null when missing. Needs agentdb >= 3.3.0.',
+    inputSchema: {
+        type: 'object',
+        properties: { id: { type: 'number', description: 'Episode id' } },
+        required: ['id'],
+    },
+    handler: async (params) => {
+        try {
+            const m = await episodeCrud();
+            const id = idOf(params.id, m.parseEpisodeId);
+            if (typeof id !== 'number')
+                return { success: false, ...id };
+            return (await m.bridgeGetEpisode(id)) ?? unavailable;
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message.slice(0, 500) : 'Internal error' };
+        }
+    },
+};
+export const agentdbEpisodeList = {
+    name: 'agentdb_episode-list',
+    description: 'Page through past episodes, newest first, optionally for one session or only successes/failures, with a total count. Use when you need to browse or audit what was recorded (e.g. every episode from one session); use agentdb_episode-recall instead when you want the episodes most relevant to a task. Needs agentdb >= 3.3.0.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            sessionId: { type: 'string', description: 'Only episodes from this session' },
+            success: { type: 'boolean', description: 'Only successes (true) or failures (false)' },
+            limit: { type: 'number', description: 'Page size (1-100)', default: 20 },
+            offset: { type: 'number', description: 'Episodes to skip', default: 0 },
+            order: { type: 'string', enum: ['newest', 'oldest'], default: 'newest' },
+        },
+    },
+    handler: async (params) => {
+        try {
+            if (params.sessionId !== undefined) {
+                const v = validateText(params.sessionId, 'sessionId', 256);
+                if (!v.valid)
+                    return { success: false, error: v.error };
+            }
+            if (params.success !== undefined && typeof params.success !== 'boolean') {
+                return { success: false, error: 'success must be a boolean' };
+            }
+            const limit = params.limit === undefined ? 20 : Number(params.limit);
+            const offset = params.offset === undefined ? 0 : Number(params.offset);
+            if (!Number.isInteger(limit) || limit < 1 || limit > 100)
+                return { success: false, error: 'limit must be an integer 1-100' };
+            if (!Number.isInteger(offset) || offset < 0)
+                return { success: false, error: 'offset must be a non-negative integer' };
+            if (params.order !== undefined && params.order !== 'newest' && params.order !== 'oldest') {
+                return { success: false, error: 'order must be "newest" or "oldest"' };
+            }
+            const m = await episodeCrud();
+            return (await m.bridgeListEpisodes({
+                sessionId: params.sessionId,
+                success: params.success,
+                limit,
+                offset,
+                order: params.order ?? 'newest',
+            })) ?? unavailable;
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message.slice(0, 500) : 'Internal error' };
+        }
+    },
+};
+export const agentdbEpisodeUpdate = {
+    name: 'agentdb_episode-update',
+    description: 'Correct a past episode in place, keeping its id: task/critique/output text, reward, success flag, tags or metadata. Use when an outcome has been verified or an episode turned out wrong (e.g. success=false with a critique); deleting and re-recording is wrong because it changes the id. Text changes are re-embedded and re-indexed so recall sees them; metadata merges unless replaceMetadata is true. Needs agentdb >= 3.3.0.',
+    inputSchema: {
+        type: 'object',
+        properties: {
+            id: { type: 'number', description: 'Episode id' },
+            task: { type: 'string', description: 'New task text' },
+            critique: { type: ['string', 'null'], description: 'New critique, or null to clear' },
+            output: { type: ['string', 'null'], description: 'New output, or null to clear' },
+            reward: { type: 'number', description: 'New reward (0-1)' },
+            success: { type: 'boolean', description: 'New success flag' },
+            tags: { type: 'array', items: { type: 'string' }, description: 'Replacement tag list' },
+            metadata: { type: 'object', description: 'Metadata patch' },
+            replaceMetadata: { type: 'boolean', description: 'Replace metadata instead of merging', default: false },
+        },
+        required: ['id'],
+    },
+    handler: async (params) => {
+        try {
+            const allowed = new Set(['id', 'task', 'critique', 'output', 'reward', 'success', 'tags', 'metadata', 'replaceMetadata']);
+            const unknown = Object.keys(params).filter(k => !allowed.has(k));
+            if (unknown.length)
+                return { success: false, error: `unknown field(s): ${unknown.join(', ')}` };
+            const m = await episodeCrud();
+            const id = idOf(params.id, m.parseEpisodeId);
+            if (typeof id !== 'number')
+                return { success: false, ...id };
+            const patch = {};
+            for (const [field, nullable] of [['task', false], ['critique', true], ['output', true]]) {
+                const r = optionalText(params[field], field, nullable);
+                if (r.error)
+                    return { success: false, error: r.error };
+                if (r.value !== undefined)
+                    patch[field] = r.value;
+            }
+            if (params.reward !== undefined) {
+                if (typeof params.reward !== 'number' || !Number.isFinite(params.reward) || params.reward < 0 || params.reward > 1) {
+                    return { success: false, error: 'reward must be a number between 0 and 1' };
+                }
+                patch.reward = params.reward;
+            }
+            if (params.success !== undefined) {
+                if (typeof params.success !== 'boolean')
+                    return { success: false, error: 'success must be a boolean' };
+                patch.success = params.success;
+            }
+            if (params.tags !== undefined) {
+                if (!Array.isArray(params.tags) || params.tags.length > 64 || params.tags.some(t => typeof t !== 'string' || t.length > 128)) {
+                    return { success: false, error: 'tags must be up to 64 strings of at most 128 characters' };
+                }
+                patch.tags = params.tags;
+            }
+            if (params.metadata !== undefined) {
+                const md = params.metadata;
+                if (md !== null && (typeof md !== 'object' || Array.isArray(md)))
+                    return { success: false, error: 'metadata must be an object or null' };
+                if (md && hasForbiddenKey(md))
+                    return { success: false, error: 'metadata contains a forbidden key (__proto__, constructor, prototype) or is nested too deeply' };
+                if (md && Buffer.byteLength(JSON.stringify(md), 'utf8') > METADATA_MAX_BYTES)
+                    return { success: false, error: 'metadata exceeds 64 KB' };
+                patch.metadata = md;
+            }
+            if (Object.keys(patch).length === 0)
+                return { success: false, error: 'nothing to update' };
+            return (await m.bridgeUpdateEpisode(id, patch, { replaceMetadata: params.replaceMetadata === true })) ?? unavailable;
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message.slice(0, 500) : 'Internal error' };
+        }
+    },
+};
+export const agentdbEpisodeDelete = {
+    name: 'agentdb_episode-delete',
+    description: 'Delete a past episode by id, with its embedding and index entries, so recall stops returning it. Use when an episode must not be recalled at all (wrong, duplicate or sensitive); prefer agentdb_episode-update over deleting when it only needs correcting. Irreversible. Needs agentdb >= 3.3.0.',
+    inputSchema: {
+        type: 'object',
+        properties: { id: { type: 'number', description: 'Episode id' } },
+        required: ['id'],
+    },
+    handler: async (params) => {
+        try {
+            const m = await episodeCrud();
+            const id = idOf(params.id, m.parseEpisodeId);
+            if (typeof id !== 'number')
+                return { success: false, ...id };
+            return (await m.bridgeDeleteEpisode(id)) ?? unavailable;
+        }
+        catch (error) {
+            return { success: false, error: error instanceof Error ? error.message.slice(0, 500) : 'Internal error' };
+        }
+    },
+};
+export const agentdbEpisodeCrudTools = [
+    agentdbEpisodeGet,
+    agentdbEpisodeList,
+    agentdbEpisodeUpdate,
+    agentdbEpisodeDelete,
+];
+//# sourceMappingURL=agentdb-episode-tools.js.map

package/dist/src/mcp-tools/agentdb-tools.js

@@ -1,5 +1,6 @@
 import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feedback-patterns.js';
 import { validateIdentifier, validateText } from './validate-input.js';
+import { agentdbEpisodeCrudTools } from './agentdb-episode-tools.js';
 // ===== Shared validation helpers =====
 const MAX_STRING_LENGTH = 100_000; // 100KB max for any string input
 const MAX_BATCH_SIZE = 500; // Max entries per batch operation
@@ -1603,6 +1604,7 @@ export const agentdbTools = [
     agentdbSessionStart,
     agentdbSessionEnd,
     agentdbEpisodeRecall, // ADR-519
+    ...agentdbEpisodeCrudTools, // ADR-520
     agentdbHierarchicalStore,
     agentdbHierarchicalRecall,
     agentdbHierarchicalDelete,

package/dist/src/mcp-tools/claims-tools.js

@@ -220,7 +220,7 @@ export const claimsTools = [
                 },
                 progress: {
                     type: 'number',
-                    description: 'Current progress percentage (0-100)',
+                    description: 'Current progress percentage (0-100); omit to keep the recorded progress',
                 },
             },
             required: ['issueId', 'from', 'to'],
@@ -230,7 +230,7 @@ export const claimsTools = [
             const fromStr = input.from;
             const toStr = input.to;
             const reason = input.reason;
-            const progress = input.progress || 0;
+            const progress = input.progress;
             {
                 const v = validateIdentifier(issueId, 'issueId');
                 if (!v.valid)
@@ -269,7 +269,11 @@ export const claimsTools = [
             claim.statusChangedAt = now;
             claim.handoffTo = to;
             claim.handoffReason = reason;
-            claim.progress = progress;
+            // Optional: keep the progress recorded with claims_status when it is
+            // left out, and clamp it to 0-100 the same way claims_status does.
+            if (progress !== undefined) {
+                claim.progress = Math.min(100, Math.max(0, progress));
+            }
             store.claims[issueId] = claim;
             saveClaims(store);
             return {

package/dist/src/mcp-tools/config-tools.js

@@ -186,6 +186,30 @@ function filterDangerousKeys(obj) {
     }
     return filtered;
 }
+// Scope names index store.scopes directly, so they must never resolve to
+// Object.prototype (`__proto__`) or to inherited built-ins (`toString`).
+function validateScope(scope) {
+    const v = validateIdentifier(scope, 'scope');
+    if (!v.valid)
+        return v;
+    if (DANGEROUS_KEYS.has(scope))
+        return { valid: false, error: 'scope uses a reserved name' };
+    return { valid: true };
+}
+function readScope(store, scope) {
+    if (!Object.hasOwn(store.scopes, scope))
+        return undefined;
+    const values = store.scopes[scope];
+    return isRecord(values) ? values : undefined;
+}
+function ensureScope(store, scope, reset = false) {
+    const existing = reset ? undefined : readScope(store, scope);
+    if (existing)
+        return existing;
+    const created = {};
+    store.scopes[scope] = created;
+    return created;
+}
 function setNestedValue(obj, key, value) {
     const MAX_NESTING_DEPTH = 10;
     const parts = key.split('.');
@@ -226,7 +250,7 @@ export const configTools = [
             if (!vKey.valid)
                 return { success: false, error: vKey.error };
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -235,8 +259,9 @@ export const configTools = [
             const scope = input.scope || 'default';
             let value;
             // Check scope first, then default values
-            if (scope !== 'default' && store.scopes[scope]) {
-                value = store.scopes[scope][key];
+            const scopeValues = scope !== 'default' ? readScope(store, scope) : undefined;
+            if (scopeValues && Object.hasOwn(scopeValues, key)) {
+                value = scopeValues[key];
             }
             if (value === undefined) {
                 value = readDefaultValue(store, key);
@@ -272,7 +297,7 @@ export const configTools = [
             if (!vKey.valid)
                 return { success: false, error: vKey.error };
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -285,10 +310,10 @@ export const configTools = [
                 writeDefaultValue(store, key, value);
             }
             else {
-                if (!store.scopes[scope]) {
-                    store.scopes[scope] = {};
+                if (DANGEROUS_KEYS.has(key)) {
+                    return { success: false, error: 'key uses a reserved name' };
                 }
-                store.scopes[scope][key] = value;
+                ensureScope(store, scope)[key] = value;
             }
             saveConfigStore(store);
             return {
@@ -316,7 +341,7 @@ export const configTools = [
         handler: async (input) => {
             // Validate user-provided input (#1425)
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -380,7 +405,7 @@ export const configTools = [
         handler: async (input) => {
             // Validate user-provided input (#1425)
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -400,9 +425,12 @@ export const configTools = [
                         resetKeys.push(key);
                     }
                 }
-                else if (store.scopes[scope] && key in store.scopes[scope]) {
-                    delete store.scopes[scope][key];
-                    resetKeys.push(key);
+                else {
+                    const scopeValues = readScope(store, scope);
+                    if (scopeValues && Object.hasOwn(scopeValues, key)) {
+                        delete scopeValues[key];
+                        resetKeys.push(key);
+                    }
                 }
             }
             else {
@@ -411,8 +439,8 @@ export const configTools = [
                     resetKeys = Object.keys(store.values);
                     replaceDefaultValues(store, { ...DEFAULT_CONFIG });
                 }
-                else if (store.scopes[scope]) {
-                    resetKeys = Object.keys(store.scopes[scope]);
+                else if (readScope(store, scope)) {
+                    resetKeys = Object.keys(readScope(store, scope));
                     delete store.scopes[scope];
                 }
             }
@@ -440,7 +468,7 @@ export const configTools = [
         handler: async (input) => {
             // Validate user-provided input (#1425)
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -452,8 +480,9 @@ export const configTools = [
                 exportData = { ...DEFAULT_CONFIG };
             }
             Object.assign(exportData, store.values);
-            if (scope !== 'default' && store.scopes[scope]) {
-                Object.assign(exportData, store.scopes[scope]);
+            const scopeValues = scope !== 'default' ? readScope(store, scope) : undefined;
+            if (scopeValues) {
+                Object.assign(exportData, scopeValues);
             }
             return {
                 config: exportData,
@@ -480,7 +509,7 @@ export const configTools = [
         handler: async (input) => {
             // Validate user-provided input (#1425)
             if (input.scope) {
-                const v = validateIdentifier(input.scope, 'scope');
+                const v = validateScope(input.scope);
                 if (!v.valid)
                     return { success: false, error: v.error };
             }
@@ -499,10 +528,7 @@ export const configTools = [
                 }
             }
             else {
-                if (!store.scopes[scope] || !merge) {
-                    store.scopes[scope] = {};
-                }
-                Object.assign(store.scopes[scope], config);
+                Object.assign(ensureScope(store, scope, !merge), config);
             }
             saveConfigStore(store);
             return {

package/dist/src/mcp-tools/coordination-tools.js

@@ -200,8 +200,11 @@ export const coordinationTools = [
                     selectedNode = nodes.reduce((max, n) => (weights[n.id] || 1) > (weights[max.id] || 1) ? n : max);
                 }
                 else {
-                    // Round robin - just pick first active
-                    selectedNode = nodes[0];
+                    // Round robin: the active node after the one the last task went to,
+                    // wrapping around (and starting over if that node is gone).
+                    const last = nodes.findIndex(n => n.id === store.loadBalance.lastAssigned);
+                    selectedNode = nodes[(last + 1) % nodes.length];
+                    store.loadBalance.lastAssigned = selectedNode.id;
                 }
                 // Update load
                 selectedNode.load += 1;

package/dist/src/mcp-tools/daa-tools.js

@@ -221,10 +221,15 @@ export const daaTools = [
                 id,
                 name: input.name,
                 status: 'pending',
-                steps: (input.steps || []).map((s, i) => ({
-                    name: typeof s === 'string' ? s : `Step ${i + 1}`,
-                    status: 'pending',
-                })),
+                // The schema declares object steps; keep their `name` instead of
+                // renaming every one to "Step N".
+                steps: (input.steps || []).map((s, i) => {
+                    const given = typeof s === 'string' ? s : s?.name;
+                    return {
+                        name: typeof given === 'string' && given.trim() ? given : `Step ${i + 1}`,
+                        status: 'pending',
+                    };
+                }),
                 strategy: input.strategy || 'adaptive',
                 createdAt: new Date().toISOString(),
             };
@@ -323,7 +328,9 @@ export const daaTools = [
             const sourceId = input.sourceAgentId;
             const targetIds = input.targetAgentIds;
             const domain = input.knowledgeDomain || 'general';
-            const knowledgeId = `knowledge-${Date.now()}`;
+            // A random suffix keeps two shares in the same millisecond from
+            // overwriting each other in store.knowledge (and in AgentDB).
+            const knowledgeId = `knowledge-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
             const knowledgeEntry = {
                 domain,
                 content: input.knowledgeContent || {},

package/dist/src/mcp-tools/hooks-tools.js

@@ -5,7 +5,7 @@ import { feedbackPatternsSchema, validateFeedbackPatterns } from '../memory/feed
  */
 import { mkdirSync, writeFileSync, existsSync, readFileSync, statSync, unlinkSync, readdirSync } from 'fs';
 import * as nodeFs from 'fs';
-import { dirname, join, resolve, sep } from 'path';
+import { basename, dirname, isAbsolute, join, relative, resolve, sep } from 'path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validatePath } from './validate-input.js';
 import { commandRecordingDisabled, redactCommandForStorage } from '../services/command-recording.js';
@@ -5109,6 +5109,38 @@ function codemodLangForExt(abs) {
         return 'javascript';
     return 'typescript';
 }
+// Canonicalize a path that may not exist yet: realpath the nearest existing
+// ancestor and re-attach the missing tail, so a symlinked parent still
+// resolves to its real location (mirrors @claude-flow/security's
+// canonicalizeSync, which is not exported).
+function realpathNearest(p) {
+    try {
+        return nodeFs.realpathSync(p);
+    }
+    catch (err) {
+        if (err?.code !== 'ENOENT')
+            throw err;
+    }
+    const parent = dirname(p);
+    if (parent === p)
+        return p;
+    return join(realpathNearest(parent), basename(p));
+}
+// CWE-59 (#4346): containment must compare real paths on BOTH sides — a
+// symlink inside the project pointing outside it must not pass, and a
+// symlinked project root (e.g. macOS /var -> /private/var) must not make
+// every path fail. Fails closed if canonicalization throws (ELOOP, EACCES).
+function isInsideRealRoot(realRoot, abs) {
+    let real;
+    try {
+        real = realpathNearest(abs);
+    }
+    catch {
+        return false;
+    }
+    const rel = relative(realRoot, real);
+    return rel === '' || (rel !== '..' && !rel.startsWith('..' + sep) && !isAbsolute(rel));
+}
 // Deterministic codemod execution — the real Tier-1 path (ADR-143)
 export const hooksCodemod = {
     name: 'hooks_codemod',
@@ -5154,6 +5186,13 @@ export const hooksCodemod = {
         // Resolve the target file set (single / array / glob), with path containment.
         const resolveTargets = () => {
             const out = new Set();
+            let realRoot;
+            try {
+                realRoot = realpathNearest(cwd);
+            }
+            catch (err) {
+                return { abs: [], truncated: false, error: `cannot resolve project root: ${err.message}` };
+            }
             const addRaw = (p) => {
                 const v = validatePath(p, 'path');
                 if (!v.valid)
@@ -5164,13 +5203,11 @@ export const hooksCodemod = {
                 // path like `${cwd}-staging/x.ts` pass as "inside" `cwd`. Matches
                 // the pattern already used correctly elsewhere in this codebase
                 // (@claude-flow/security's `isWithinPrefix`, hooks/workers, plugins/security).
-                // KNOWN LIMITATION (disclosed 2026-10-20, not fixed here): this
-                // compares the resolved-but-not-realpath'd path, so a symlink
-                // inside cwd pointing outside it still escapes containment
-                // (CWE-59, a distinct/broader gap than the CWE-22 prefix bug this
-                // anchors). Needs fs.realpathSync-based containment as a follow-up.
                 if (abs !== cwd && !abs.startsWith(cwd + sep))
                     return `path escapes project root: ${p}`;
+                // The lexical check above cannot see symlinks; re-check on real paths.
+                if (!isInsideRealRoot(realRoot, abs))
+                    return `path escapes project root via symlink: ${p}`;
                 out.add(abs);
                 return undefined;
             };
@@ -5202,7 +5239,9 @@ export const hooksCodemod = {
                 }
                 for (const m of matches) {
                     const abs = resolve(cwd, m);
-                    if ((abs === cwd || abs.startsWith(cwd + sep)) && CODEMOD_EXTENSIONS.has(abs.slice(abs.lastIndexOf('.')).toLowerCase())) {
+                    // Matches that resolve outside the root (via a symlinked file or
+                    // directory) are skipped silently, like other non-matching entries.
+                    if ((abs === cwd || abs.startsWith(cwd + sep)) && isInsideRealRoot(realRoot, abs) && CODEMOD_EXTENSIONS.has(abs.slice(abs.lastIndexOf('.')).toLowerCase())) {
                         out.add(abs);
                     }
                 }

package/dist/src/mcp-tools/session-tools.d.ts

@@ -19,5 +19,15 @@ export interface MemoryCaptureReport {
     };
     error?: string;
 }
+/**
+ * #4404: snapshot map ID for a live (namespace, key) row. A bare
+ * `namespace::key` join collides when either part contains `::`
+ * (`team::alice`/`profile` vs `team`/`alice::profile`), so one row was
+ * dropped on save and a distinct sibling row was skipped as a mirror. `%` and
+ * `:` are percent-escaped in each part, which keeps ordinary IDs unchanged.
+ * Restore reads the explicit namespace/key fields, never this ID, so older
+ * snapshots restore as before.
+ */
+export declare function memorySnapshotId(namespace: string, key: string): string;
 export declare const sessionTools: MCPTool[];
 //# sourceMappingURL=session-tools.d.ts.map

package/dist/src/mcp-tools/session-tools.js

@@ -115,6 +115,19 @@ function listSessions() {
 /** Snapshot format written by session_save since #3573. */
 const MEMORY_SNAPSHOT_FORMAT = 'ruflo-session-memory/2';
 const MEMORY_PAGE_SIZE = 500;
+/**
+ * #4404: snapshot map ID for a live (namespace, key) row. A bare
+ * `namespace::key` join collides when either part contains `::`
+ * (`team::alice`/`profile` vs `team`/`alice::profile`), so one row was
+ * dropped on save and a distinct sibling row was skipped as a mirror. `%` and
+ * `:` are percent-escaped in each part, which keeps ordinary IDs unchanged.
+ * Restore reads the explicit namespace/key fields, never this ID, so older
+ * snapshots restore as before.
+ */
+export function memorySnapshotId(namespace, key) {
+    const escape = (part) => part.replace(/%/g, '%25').replace(/:/g, '%3A');
+    return `${escape(namespace)}::${escape(key)}`;
+}
 async function readLiveEntries(listEntries, dbPath, encryptWrites) {
     const rows = [];
     // Bounded: stop on a short page, once `total` rows are in hand, or after a
@@ -170,7 +183,7 @@ async function captureMemorySnapshot() {
         if (existsSync(primary)) {
             sawStore = true;
             for (const row of await readLiveEntries(listEntries, primary)) {
-                const id = `${row.namespace}::${row.key}`;
+                const id = memorySnapshotId(row.namespace, row.key);
                 seen.add(id);
                 entries[id] = {
                     key: row.key, value: row.content ?? '', namespace: row.namespace,
@@ -189,7 +202,7 @@ async function captureMemorySnapshot() {
             sawStore = true;
             // The AgentDB store is read by native SQLite and must stay plaintext.
             for (const row of await readLiveEntries(listEntries, sibling, false)) {
-                const id = `${row.namespace}::${row.key}`;
+                const id = memorySnapshotId(row.namespace, row.key);
                 if (seen.has(id))
                     continue;
                 seen.add(id);

package/dist/src/mcp-tools/workflow-tools.js

@@ -173,11 +173,13 @@ export const workflowTools = [
                     name: task || `${templateName} workflow`,
                     description: task,
                     steps,
-                    status: 'running',
+                    // #4609: nothing is dispatched here, so this is not a run yet. Saving it
+                    // as 'running' made workflow_execute and workflow_delete refuse it.
+                    // 'ready' matches workflow_create; workflow_execute starts it.
+                    status: 'ready',
                     currentStep: 0,
                     variables: { template: templateName, ...options },
                     createdAt: new Date().toISOString(),
-                    startedAt: new Date().toISOString(),
                 };
                 store.workflows[workflowId] = workflow;
                 saveWorkflowStore(store);
@@ -185,14 +187,17 @@ export const workflowTools = [
             return {
                 workflowId,
                 template: templateName,
-                status: dryRun ? 'validated' : 'running',
+                status: dryRun ? 'validated' : 'ready',
                 stages,
                 metrics: {
                     totalStages: stages.length,
                     completedStages: 0,
                     agentsSpawned: 0,
-                    estimatedDuration: `${stages.length * 30}s`,
+                    estimatedDuration: 'unknown',
                 },
+                ...(dryRun ? {} : {
+                    nextStep: 'Start it with workflow_execute; task steps need config.agentId or options.defaultAgentId.',
+                }),
             };
         },
     },