@claude-flow/cli 3.56.5 → 3.56.7

package/dist/src/init/helper-commands.d.ts

@@ -1,4 +1,6 @@
 export type HelperScope = 'project' | 'user';
+/** Claude Code reads a hook's `timeout` in SECONDS; the auto-memory hooks wrote 6000-10000, i.e. up to 100 minutes (#4058). */
+export declare const AUTO_MEMORY_HOOK_TIMEOUT_S = 30;
 /** Settings written into the user's home directory are user-level settings. */
 export declare function helperScopeFor(targetDir: string | undefined): HelperScope;
 /** Command that runs `node <script> <subcommand>` for a hook. */

package/dist/src/init/helper-commands.js

@@ -14,6 +14,8 @@
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
+/** Claude Code reads a hook's `timeout` in SECONDS; the auto-memory hooks wrote 6000-10000, i.e. up to 100 minutes (#4058). */
+export const AUTO_MEMORY_HOOK_TIMEOUT_S = 30;
 const IS_WINDOWS = process.platform === 'win32';
 const STATUSLINE_SCRIPT = '.claude/helpers/statusline.cjs';
 function canonical(dir) {
@@ -30,20 +32,38 @@ export function helperScopeFor(targetDir) {
         return 'project';
     return canonical(targetDir) === canonical(os.homedir()) ? 'user' : 'project';
 }
+/**
+ * Windows hook command (#4045). It must not go through `cmd /c`: under Git Bash
+ * MSYS rewrites `/c` into a path, cmd starts interactively and executes the
+ * hook's stdin JSON, and any `>` in that text creates a file. A single
+ * `node -e` has no shell syntax to misread (no cmd, no `%VAR%`, no `<>|&$` and
+ * no inner double quotes), so cmd, PowerShell and Git Bash pass it through
+ * unchanged. The script and its subcommand stay in one string, because the
+ * ruflo-mods ownership rule matches `hook-handler.cjs <subcommand>`. Project
+ * scope prefers the project's helper and falls back to the user profile's
+ * (#1943); user scope never looks at the project. The helper runs as a child
+ * with inherited stdio so stdin, stdout and the exit status pass through (a
+ * `require` would skip the helper's `require.main === module` entry point).
+ */
+function windowsHookCommand(script, subcommand, scope) {
+    // Ternaries, not `||`: the command carries no pipe or ampersand at all.
+    const home = "(e.USERPROFILE?e.USERPROFILE:e.HOME?e.HOME:'.')";
+    const pick = scope === 'user'
+        ? `f=p.join(${home},a[0]);`
+        : "f=p.join(e.CLAUDE_PROJECT_DIR?e.CLAUDE_PROJECT_DIR:'.',a[0]);" +
+            `if(!fs.existsSync(f))f=p.join(${home},a[0]);`;
+    const js = `var a='${[script, subcommand].filter(Boolean).join(' ')}'.split(' '),e=process.env,fs=require('fs'),p=require('path'),f;` + pick +
+        "var r=require('child_process').spawnSync(process.execPath,[f].concat(a.slice(1)),{stdio:'inherit'});" +
+        'process.exit(r.status===null?1:r.status)';
+    return `node -e "${js}"`;
+}
 /** Command that runs `node <script> <subcommand>` for a hook. */
 export function helperHookCommand(script, subcommand, scope, windows = IS_WINDOWS) {
-    const winScript = script.replace(/\//g, '\\');
     const arg = subcommand ? ` ${subcommand}` : '';
-    if (scope === 'user') {
-        return windows
-            ? `cmd /c "node "%USERPROFILE%\\${winScript}"${arg}"`
-            : `sh -c 'exec node "\${HOME}/${script}"${arg}'`;
-    }
-    if (windows) {
-        // cmd.exe equivalent of the sh probe below. `IF EXIST` checks the
-        // project-local path; falls back to %USERPROFILE% if missing.
-        return `cmd /c "IF EXIST \"%CLAUDE_PROJECT_DIR%\\${winScript}\" (node \"%CLAUDE_PROJECT_DIR%\\${winScript}\"${arg}) ELSE (node \"%USERPROFILE%\\${winScript}\"${arg})"`;
-    }
+    if (windows)
+        return windowsHookCommand(script, subcommand, scope);
+    if (scope === 'user')
+        return `sh -c 'exec node "\${HOME}/${script}"${arg}'`;
     // POSIX sh: prefer project-local helpers, fall back to $HOME/.claude/.
     // eslint-disable-next-line no-template-curly-in-string
     const projVar = '${CLAUDE_PROJECT_DIR:-.}';
@@ -102,6 +122,17 @@ const IF_EXIST_PREAMBLE = /"IF EXIST "%CLAUDE_PROJECT_DIR%\\\.claude\\helpers\\[
  * commands (other scripts, redirects, chains) are left alone.
  */
 export function pinToUserHelpers(command, windows = IS_WINDOWS) {
+    // The #4045 Windows form: recognised only when it is exactly what ruflo generates.
+    const generated = /^node -e "var a='\.claude\/helpers\/([\w.-]+)((?: [\w:.=-]+)*)'\.split\(' '\)/.exec(command);
+    if (generated) {
+        if (!RUFLO_HELPERS.includes(generated[1]))
+            return null;
+        const script = `.claude/helpers/${generated[1]}`;
+        const subcommand = generated[2].trim();
+        return command === helperHookCommand(script, subcommand, 'project', true)
+            ? helperHookCommand(script, subcommand, 'user', true)
+            : null;
+    }
     const refs = [...command.matchAll(HELPER_REF)];
     if (refs.length === 0)
         return null;

package/dist/src/init/helpers-generator.js

@@ -1306,7 +1306,10 @@ function doStatus() {
 // Suppress unhandled rejection warnings from dynamic import() failures
 process.on('unhandledRejection', () => {});
 
-const command = process.argv[2] || 'status';
+// Older settings.json files ran node -e with the helper imported, which puts the
+// subcommand in argv[1] (#4058); accept that shape as well as script import.
+const COMMANDS = ['import', 'sync', 'status'];
+const command = process.argv[2] || (COMMANDS.includes(process.argv[1]) ? process.argv[1] : 'status');
 
 try {
   switch (command) {

package/dist/src/init/settings-generator.js

@@ -3,7 +3,7 @@
  * Creates .claude/settings.json with V3-optimized hook configurations
  */
 import { detectPlatform } from './types.js';
-import { helperHookCommand, helperScopeFor, helperStatusLineCommand } from './helper-commands.js';
+import { AUTO_MEMORY_HOOK_TIMEOUT_S, helperHookCommand, helperScopeFor, helperStatusLineCommand } from './helper-commands.js';
 /**
  * Generate the complete settings.json content
  */
@@ -278,7 +278,7 @@ function generateHooksConfig(config, scope) {
                     {
                         type: 'command',
                         command: autoMemoryCmd('import', scope),
-                        timeout: 8000,
+                        timeout: AUTO_MEMORY_HOOK_TIMEOUT_S,
                     },
                 ],
             },
@@ -306,7 +306,7 @@ function generateHooksConfig(config, scope) {
                     {
                         type: 'command',
                         command: autoMemoryCmd('sync', scope),
-                        timeout: 10000,
+                        timeout: AUTO_MEMORY_HOOK_TIMEOUT_S,
                     },
                 ],
             },

package/dist/src/init/settings-risk-scanner.js

@@ -44,7 +44,6 @@ const DOWNLOADER_WORDS = ['curl', 'wget'];
 const STANDALONE_RISK_PATTERNS = [
     /\bInvoke-Expression\b/i,
     /\biex\s*\(/i,
-    /powershell(\.exe)?\s+.*-e(nc(odedcommand)?)?\s+\S/i,
     /\/dev\/tcp\//i,
     /\bnc\s+-e\b/i,
     /base64\s+(-d|--decode)\b/i,
@@ -54,17 +53,37 @@ const STANDALONE_RISK_PATTERNS = [
 // own the way `rm`/`chmod` are — pre-approving them removes the human
 // review step for exactly the commands download-and-execute attacks use.
 const RISKY_PREAPPROVE_WORDS = [...DANGEROUS_COMMAND_WORDS, ...SHELL_EXEC_WORDS, ...DOWNLOADER_WORDS];
+// Encoded PowerShell (`powershell[.exe] ... -e|-enc|-encodedcommand <payload>`),
+// matched on whitespace-separated tokens in ONE linear pass. The earlier regex
+// (`powershell\\s+(?:\\S+\\s+)*?-e...`) is quadratic on repeated "powershell "
+// tokens (every start rescans the tail: 256KB measured ~2.5s, 1MB ~40s) because
+// the lazy token loop re-runs from each start. Same semantics: a token ending in
+// powershell/powershell.exe, then LATER a token that is exactly -e/-enc/
+// -encodedcommand, then at least one more token.
+function hasEncodedPowershell(command) {
+    let seenPs = false;
+    let pendingEnc = false;
+    for (const raw of command.split(/\s+/)) {
+        if (!raw)
+            continue;
+        if (pendingEnc)
+            return true;
+        const t = raw.toLowerCase();
+        if (seenPs && (t === '-e' || t === '-enc' || t === '-encodedcommand'))
+            pendingEnc = true;
+        else if (t.endsWith('powershell') || t.endsWith('powershell.exe'))
+            seenPs = true;
+    }
+    return false;
+}
 function wordBoundaryMatches(text, word) {
     return new RegExp(`\\b${word}\\b`, 'i').test(text);
 }
 /** Reasons a single hook `command` string looks risky (empty = clean). */
 export function scanCommandStringForRisk(command) {
     const reasons = [];
-    for (const pattern of STANDALONE_RISK_PATTERNS) {
-        if (pattern.test(command)) {
-            reasons.push('matches a known-dangerous execution pattern (encoded/remote command execution)');
-            break;
-        }
+    if (hasEncodedPowershell(command) || STANDALONE_RISK_PATTERNS.some((pattern) => pattern.test(command))) {
+        reasons.push('matches a known-dangerous execution pattern (encoded/remote command execution)');
     }
     const hasDownloader = DOWNLOADER_WORDS.some((w) => wordBoundaryMatches(command, w));
     const hasShellExec = SHELL_EXEC_WORDS.some((w) => wordBoundaryMatches(command, w));

package/dist/src/mcp-server.js

@@ -619,7 +619,7 @@ export class MCPServerManager extends EventEmitter {
                     version: VERSION,
                     capabilities: {
                         tools: { listChanged: true },
-                        resources: { subscribe: true, listChanged: true },
+                        resources: {},
                     },
                 },
             },
@@ -696,7 +696,7 @@ export class MCPServerManager extends EventEmitter {
                             serverInfo: { name: 'ruflo', version: '3.0.0' },
                             capabilities: {
                                 tools: { listChanged: true },
-                                resources: { subscribe: true, listChanged: true },
+                                resources: {},
                             },
                         },
                     };
@@ -755,6 +755,14 @@ export class MCPServerManager extends EventEmitter {
                             },
                         };
                     }
+                // The server advertises `resources` (so clients such as Codex offer list_mcp_resources), and a declared capability must
+                // be served: it exposes no resources, so the answers are empty, and a read is the spec's "resource not found" (ADR-490).
+                case 'resources/list':
+                    return { jsonrpc: '2.0', id: message.id, result: { resources: [] } };
+                case 'resources/templates/list':
+                    return { jsonrpc: '2.0', id: message.id, result: { resourceTemplates: [] } };
+                case 'resources/read':
+                    return { jsonrpc: '2.0', id: message.id, error: { code: -32002, message: 'Resource not found' } };
                 case 'notifications/initialized':
                     // Client notification - no response needed
                     console.error(`[${new Date().toISOString()}] INFO [claude-flow-mcp] (${sessionId}) Client initialized`);

package/dist/src/mcp-tools/capability-brain.d.ts

@@ -97,7 +97,7 @@ export interface CapabilityBrain {
     };
 }
 /** Top-level commands from the CLI command loader. Kept as a checked manifest. */
-export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements"];
+export declare const RUFLO_CLI_COMMANDS: readonly ["init", "start", "status", "task", "session", "agent", "swarm", "memory", "mcp", "config", "migrate", "hooks", "workflow", "hive-mind", "process", "daemon", "version", "neural", "security", "performance", "providers", "plugins", "deployment", "claims", "policy", "embeddings", "completions", "doctor", "verify", "analyze", "route", "progress", "issues", "update", "ruvector", "benchmark", "guidance", "appliance", "appliance-advanced", "transfer-store", "cleanup", "autopilot", "gaia-bench", "metaharness", "eject", "funnel", "settings", "auth", "proxy", "advisor", "spinner", "announcements", "tui"];
 export interface ImplementationLoopStep {
     id: string;
     name: string;

package/dist/src/mcp-tools/capability-brain.js

@@ -16,7 +16,7 @@ export const RUFLO_CLI_COMMANDS = [
     'ruvector', 'benchmark', 'guidance', 'appliance', 'appliance-advanced',
     'transfer-store', 'cleanup', 'autopilot', 'gaia-bench', 'metaharness',
     'eject', 'funnel', 'settings', 'auth', 'proxy', 'advisor', 'spinner',
-    'announcements',
+    'announcements', 'tui',
 ];
 export const IMPLEMENTATION_LOOP = [
     {

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

@@ -8,6 +8,7 @@ import * as nodeFs from 'fs';
 import { dirname, join, resolve } from 'path';
 import { getProjectCwd } from './types.js';
 import { validateIdentifier, validateText, validatePath } from './validate-input.js';
+import { commandRecordingDisabled, redactCommandForStorage } from '../services/command-recording.js';
 import { checkCommandLoop, recordCommandOutcome } from './tool-loop-guardrail.js';
 import { buildLearnedRoutingPatterns, } from '../services/learned-routing.js';
 import { applyTypesafeRouting, getTypesafeRouter } from '../ruvector/typesafe-router.js';
@@ -1014,13 +1015,34 @@ export const hooksPostCommand = {
         // #6: feed the tool-loop circuit breaker so pre-command can warn/block on
         // repeated consecutive failures of the same command.
         recordCommandOutcome(command, success);
+        // #4056: command history is opt-out (CLAUDE_FLOW_HOOKS_RECORD_COMMANDS=0,
+        // CLAUDE_FLOW_HOOKS_ENABLED=false, or hooks.recordCommands=false in the
+        // config). The circuit breaker above is in-memory only; nothing below
+        // runs when recording is off, so no command text reaches the store or
+        // the trajectory pipeline.
+        if (commandRecordingDisabled(process.env, getProjectCwd())) {
+            return {
+                recorded: false,
+                disabled: true,
+                command: undefined,
+                exitCode,
+                success,
+                timestamp: new Date().toISOString(),
+                _storedIn: 'none',
+                learningPath: 'recorded-only',
+                trajectoriesDelta: 0,
+                note: 'Command recording is switched off (CLAUDE_FLOW_HOOKS_RECORD_COMMANDS / CLAUDE_FLOW_HOOKS_ENABLED / hooks.recordCommands); nothing was stored.',
+            };
+        }
+        // What is stored is the redacted, length-capped form, never the raw text.
+        const storedCommand = redactCommandForStorage(command);
         // Persist command outcome via AgentDB
         let _storedIn = 'none';
         try {
             const bridge = await import('../memory/memory-bridge.js');
             const stored = await bridge.bridgeStoreEntry({
                 key: `cmd-${Date.now()}`,
-                value: JSON.stringify({ command, exitCode, success }),
+                value: JSON.stringify({ command: storedCommand, exitCode, success }),
                 namespace: 'commands',
                 tags: [success ? 'success' : 'error'],
                 ttl,
@@ -1042,7 +1064,7 @@ export const hooksPostCommand = {
                 }
                 const key = `cmd-${now}`;
                 store.entries[key] = {
-                    key, value: JSON.stringify({ command, exitCode, success }), namespace: 'commands',
+                    key, value: JSON.stringify({ command: storedCommand, exitCode, success }), namespace: 'commands',
                     storedAt: new Date(now).toISOString(), lastAccessed: new Date(now).toISOString(), accessCount: 0,
                     expiresAt: new Date(now + ttl * 1000).toISOString(),
                 };
@@ -1063,8 +1085,8 @@ export const hooksPostCommand = {
             const before = intel.getIntelligenceStats().trajectoriesRecorded;
             await intel.recordTrajectory([{
                     type: 'action',
-                    content: `Command \`${command.slice(0, 200)}\` exited ${exitCode} (${success ? 'success' : 'failure'})`,
-                    metadata: { hook: 'post-command', command: command.slice(0, 500), exitCode, success },
+                    content: `Command \`${storedCommand.slice(0, 200)}\` exited ${exitCode} (${success ? 'success' : 'failure'})`,
+                    metadata: { hook: 'post-command', command: storedCommand.slice(0, 500), exitCode, success },
                     timestamp: Date.now(),
                 }], success ? 'success' : 'failure');
             trajectoriesDelta = intel.getIntelligenceStats().trajectoriesRecorded - before;
@@ -3305,19 +3327,23 @@ export const hooksTrajectoryEnd = {
             }
             catch { /* intelligence module not loadable — keep sona-only behaviour */ }
         }
-        // #2351: when an agent calls trajectory-end with no recorded steps but a
-        // non-empty `feedback` string, the feedback was previously dropped on the
-        // floor — `patternsExtracted` reported 0 and `pattern-search` never
-        // surfaced it. Step-less trajectories are the common case for LLM agents
-        // (nothing forces step logging mid-task), and feedback is often the most
-        // distilled lesson available. Route it through the same store + embed
-        // path that pattern-store uses so it becomes searchable. Best-effort:
-        // failures here must not turn the trajectory-end call itself into a
-        // failure — the trajectory record was already persisted above.
+        // #2351: when an agent calls trajectory-end with a non-empty `feedback`
+        // string, the feedback was previously dropped on the floor —
+        // `patternsExtracted` reported 0 and `pattern-search` never surfaced it.
+        // Route it through the same store + embed path that pattern-store uses
+        // so it becomes searchable. Best-effort: failures here must not turn the
+        // trajectory-end call itself into a failure — the trajectory record was
+        // already persisted above.
+        //
+        // #3662: #2351's original fix gated this on `!hasSteps` (step-less
+        // trajectories only). The common start -> step -> end path (the one real
+        // agents actually use) therefore recorded SONA state while leaving the
+        // feedback unindexed. Non-empty feedback is promoted regardless of
+        // whether steps were recorded — a trajectory's steps and its distilled
+        // feedback are not mutually exclusive evidence.
         let feedbackDistilled = { stored: false };
-        const hasSteps = !!trajectory && trajectory.steps.length > 0;
         const trimmedFeedback = typeof feedback === 'string' ? feedback.trim() : '';
-        if (trajectory && !hasSteps && trimmedFeedback.length > 0) {
+        if (trajectory && trimmedFeedback.length > 0) {
             const distilledPatternId = `pattern-feedback-${trajectoryId}-${Date.now()}`;
             const patternMetadata = {
                 sourceTrajectoryId: trajectoryId,

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

@@ -1402,7 +1402,8 @@ export const memoryTools = [
                 if (!v.valid)
                     throw new Error(v.error);
             }
-            const all = await listEntries({ limit: 100000, namespace });
+            // #4056: TTL hides expired rows from normal reads, so the cleanup has to ask for them.
+            const all = await listEntries({ limit: 100000, namespace, includeExpired: true });
             const now = Date.now();
             const expired = all.entries.filter(e => {
                 const exp = e.expiresAt;

package/dist/src/memory/live-memory-row.d.ts

@@ -1,3 +1,5 @@
 /** TTL is a read-time visibility rule, independent of background cleanup. */
-export declare function liveMemoryRowSql(): string;
+export declare function liveMemoryRowSql(opts?: {
+    includeExpired?: boolean;
+}): string;
 //# sourceMappingURL=live-memory-row.d.ts.map

package/dist/src/memory/live-memory-row.js

@@ -1,5 +1,7 @@
 /** TTL is a read-time visibility rule, independent of background cleanup. */
-export function liveMemoryRowSql() {
+export function liveMemoryRowSql(opts = {}) {
+    if (opts.includeExpired)
+        return `(status = 'active' OR status IS NULL)`;
     return `(status = 'active' OR status IS NULL) AND (expires_at IS NULL OR expires_at > ${Date.now()})`;
 }
 //# sourceMappingURL=live-memory-row.js.map

package/dist/src/memory/memory-bridge.d.ts

@@ -142,6 +142,8 @@ export declare function bridgeListEntries(options: {
     provenanceFilter?: string[];
     /** ADR-472: include each entry's embedding as int8+scale (`embeddingQ8`); at most MAX_LIST_EMBEDDINGS rows. */
     includeEmbedding?: boolean;
+    /** #4056: also return rows whose TTL has passed (with `expiresAt`). For cleanup only. */
+    includeExpired?: boolean;
 }): Promise<{
     success: boolean;
     entries: {
@@ -152,6 +154,8 @@ export declare function bridgeListEntries(options: {
         accessCount: number;
         createdAt: string;
         updatedAt: string;
+        /** #4056: epoch ms the row expires at; null when it never does. */
+        expiresAt?: number | null;
         hasEmbedding: boolean;
         /** #2073: Present when `includeContent: true` was requested. */
         content?: string;

package/dist/src/memory/memory-bridge.js

@@ -1453,7 +1453,7 @@ export async function bridgeListEntries(options) {
         // the `status = 'active'` filter matched zero. Treat NULL as
         // "legacy-active" — the safe default for any entry that predates the
         // status column.
-        const statusFilter = liveMemoryRowSql();
+        const statusFilter = liveMemoryRowSql({ includeExpired: options.includeExpired });
         // Count
         let total = 0;
         try {
@@ -1468,7 +1468,7 @@ export async function bridgeListEntries(options) {
         const entries = [];
         try {
             const stmt = ctx.db.prepare(`
-        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type
+        SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at
         FROM memory_entries
         WHERE ${statusFilter} ${extraFilter}
         ORDER BY updated_at DESC
@@ -1486,6 +1486,7 @@ export async function bridgeListEntries(options) {
                     accessCount: row.access_count ?? 0,
                     createdAt: row.created_at || new Date().toISOString(),
                     updatedAt: row.updated_at || new Date().toISOString(),
+                    expiresAt: row.expires_at ?? null,
                     hasEmbedding: !!(row.embedding && String(row.embedding).length > 10),
                     provenanceType: row.provenance_type || 'unknown',
                 };

package/dist/src/memory/memory-initializer.d.ts

@@ -511,6 +511,8 @@ export declare function listEntries(options: {
     provenanceFilter?: string[];
     /** ADR-472: include each entry's embedding as int8+scale (`embeddingQ8`); at most MAX_LIST_EMBEDDINGS rows. Read-only. */
     includeEmbedding?: boolean;
+    /** #4056: also return rows whose TTL has passed (with `expiresAt`). For cleanup only; normal reads hide them. */
+    includeExpired?: boolean;
 }): Promise<{
     success: boolean;
     entries: {
@@ -521,6 +523,8 @@ export declare function listEntries(options: {
         accessCount: number;
         createdAt: string;
         updatedAt: string;
+        /** #4056: epoch ms the row expires at; null when it never does. */
+        expiresAt?: number | null;
         hasEmbedding: boolean;
         /** #2073: Present when `includeContent: true` was requested. */
         content?: string;

package/dist/src/memory/memory-initializer.js

@@ -6,7 +6,7 @@ import * as fs from 'fs';
 import * as path from 'path';
 import { AsyncLocalStorage } from 'node:async_hooks';
 import { createRequire } from 'node:module';
-import { readFileMaybeEncrypted, writeFileAtomic, writeFileRestricted } from '../fs-secure.js';
+import { readFileMaybeEncrypted, writeDbImagePreservingFormat, writeFileRestricted } from '../fs-secure.js';
 import { restoreMemoryDbFromBackup } from '../services/memory-backup.js';
 import { validateIdentifier } from '../mcp-tools/validate-input.js';
 /**
@@ -1248,7 +1248,7 @@ export async function ensureSchemaColumns(dbPath, options = {}) {
             if (modified) {
                 // Save updated database
                 const data = db.export();
-                writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
+                writeDbImagePreservingFormat(dbPath, data, { encrypt: options.encryptWrites ?? true });
             }
             db.close();
             return { success: true, columnsAdded };
@@ -1975,7 +1975,7 @@ export async function applyTemporalDecay(dbPath) {
         return await withMemoryDbLock(path_, async () => {
             const initSqlJs = (await import('sql.js')).default;
             const SQL = await initSqlJs();
-            const fileBuffer = fs.readFileSync(path_);
+            const fileBuffer = readFileMaybeEncrypted(path_, null);
             const db = new SQL.Database(fileBuffer);
             // Apply decay: confidence *= exp(-decay_rate * days_since_last_use)
             const now = Date.now();
@@ -1992,7 +1992,7 @@ export async function applyTemporalDecay(dbPath) {
             const changes = db.getRowsModified();
             // Save (atomic — issue #2584: a torn full-image flush corrupts the store)
             const data = db.export();
-            writeFileAtomic(path_, Buffer.from(data));
+            writeDbImagePreservingFormat(path_, data);
             db.close();
             return {
                 success: true,
@@ -2692,7 +2692,7 @@ export async function storeEntry(options) {
             }
             // Save
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
+            writeDbImagePreservingFormat(dbPath, data);
             db.close();
         });
         // Add to HNSW index for faster future searches
@@ -3019,7 +3019,7 @@ export async function listEntries(options) {
         // that predate the status column may have NULL after migration.
         // See memory-bridge.ts:bridgeListEntries for full context.
         // Get total count
-        const whereClauses = [liveMemoryRowSql()];
+        const whereClauses = [liveMemoryRowSql({ includeExpired: options.includeExpired })];
         const whereParams = [];
         if (namespace) {
             whereClauses.push('namespace = ?');
@@ -3044,7 +3044,7 @@ export async function listEntries(options) {
         const safeLimit = Math.min(parseInt(String(limit), 10) || 100, options.includeEmbedding ? MAX_LIST_EMBEDDINGS : Number.MAX_SAFE_INTEGER);
         const safeOffset = parseInt(String(offset), 10) || 0;
         // #2120 — same NULL-as-active acceptance as the count above.
-        const listStmt = db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type
+        const listStmt = db.prepare(`SELECT id, key, namespace, content, embedding, access_count, created_at, updated_at, provenance_type, expires_at
        FROM memory_entries WHERE ${whereSql}
        ORDER BY updated_at DESC LIMIT ? OFFSET ?`);
         listStmt.bind([...whereParams, safeLimit, safeOffset]);
@@ -3057,7 +3057,7 @@ export async function listEntries(options) {
         const entries = [];
         if (result[0]?.values) {
             for (const row of result[0].values) {
-                const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal] = row;
+                const [id, key, ns, content, embedding, accessCount, createdAt, updatedAt, provenanceTypeVal, expiresAtVal] = row;
                 const entry = {
                     // #2073: don't truncate id when content is requested — callers
                     // (notably memory_export) need the full id to round-trip via import.
@@ -3068,6 +3068,7 @@ export async function listEntries(options) {
                     accessCount: accessCount || 0,
                     createdAt: createdAt || new Date().toISOString(),
                     updatedAt: updatedAt || new Date().toISOString(),
+                    expiresAt: expiresAtVal ?? null,
                     hasEmbedding: !!embedding && embedding.length > 10,
                     provenanceType: provenanceTypeVal || 'unknown'
                 };
@@ -3166,7 +3167,7 @@ export async function getEntry(options) {
       `, [String(id)]);
             // Save updated database
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: true });
+            writeDbImagePreservingFormat(dbPath, data);
             db.close();
             let tags = [];
             if (tagsJson) {
@@ -3302,7 +3303,7 @@ export async function deleteEntry(options) {
             const remainingEntries = countResult[0]?.values?.[0]?.[0] || 0;
             // Save updated database
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
+            writeDbImagePreservingFormat(dbPath, data, { encrypt: options.encryptWrites ?? true });
             db.close();
             // Clean up in-memory HNSW index so ghost vectors don't appear in searches.
             // Remove the entry from the HNSW entries map and invalidate the index.
@@ -3472,7 +3473,7 @@ export async function purgeNamespace(options) {
             const countResult = db.exec(`SELECT COUNT(*) FROM memory_entries WHERE status = 'active'`);
             const remainingEntries = countResult[0]?.values?.[0]?.[0] || 0;
             const data = db.export();
-            writeFileRestricted(dbPath, Buffer.from(data), { encrypt: options.encryptWrites ?? true });
+            writeDbImagePreservingFormat(dbPath, data, { encrypt: options.encryptWrites ?? true });
             db.close();
             if (deletedCount > 0 && hnswIndex?.entries) {
                 for (const [id, entry] of hnswIndex.entries) {

package/dist/src/mods/claude-installs.js

@@ -69,13 +69,17 @@ export function judgeInstalls(installs, enableEnvSet) {
         : '';
     const runs = `${first.path} (${first.version ?? 'version unknown'})`;
     if (!first.version)
-        return { status: 'warn', message: `claude resolves to ${runs}${mixed}` };
+        return { status: 'warn', message: `claude resolves to ${runs}${mixed}`, fix: `run \`${first.path} --version\` and reinstall Claude Code if it prints nothing` };
     if (!versionLess(first.version, MODS_DEFAULT_ON)) {
-        return { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods on by default${mixed}` };
+        return others.length
+            ? { status: 'warn', message: `claude resolves to ${runs}: mods on by default${mixed}`, fix: `put the claude you want first on PATH, or remove: ${others.map((i) => i.path).join(' ')}` }
+            : { status: 'pass', message: `claude resolves to ${runs}: mods on by default` };
     }
     if (!versionLess(first.version, MODS_FIRST)) {
         return enableEnvSet
-            ? { status: others.length ? 'warn' : 'pass', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}` }
+            ? (others.length
+                ? { status: 'warn', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)${mixed}`, fix: `put the claude you want first on PATH, or remove: ${others.map((i) => i.path).join(' ')}` }
+                : { status: 'pass', message: `claude resolves to ${runs}: mods load with CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (set)` })
             : { status: 'warn', message: `claude resolves to ${runs}: below ${MODS_DEFAULT_ON}, mods need CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1 (not set)${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON}, or export CLAUDE_CODE_ENABLE_FUNCTION_HOOKS=1` };
     }
     return { status: 'warn', message: `claude resolves to ${runs}: predates mods (< ${MODS_FIRST}); classic hooks handle every event${mixed}`, fix: `upgrade to >= ${MODS_DEFAULT_ON} and remove the stale install from PATH` };

package/dist/src/mods/install.js

@@ -107,18 +107,38 @@ export function installMod(projectRoot, scope, dryRun = false, plugins = MOD_PLU
         backup = `${settingsFile}.bak-ruflo-mods-${Date.now()}`;
         copyFileSync(settingsFile, backup);
     }
-    writeJson(settingsFile, next);
-    // What ruflo added once is still ruflo's to remove: merge into the record.
-    const record = readRecord(projectRoot) ?? { version: 2, installedAt: '', files: {} };
-    const before = record.files[settingsFile] ?? { plugins: [], marketplace: false, env: false };
-    record.files[settingsFile] = {
-        plugins: [...new Set([...before.plugins, ...added.plugins])],
-        marketplace: before.marketplace || added.marketplace,
-        env: before.env || added.env,
-        claudeInstalled: before.claudeInstalled ?? [],
-    };
-    record.installedAt = new Date().toISOString();
-    writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+    // One operation: the settings and the record that lets uninstall take them back are written together.
+    // If the record cannot be written, the settings go back as they were (or the file ruflo created goes
+    // away), so nothing is left half-installed with no record to remove it by.
+    try {
+        writeJson(settingsFile, next);
+        // What ruflo added once is still ruflo's to remove: merge into the record.
+        const record = readRecord(projectRoot) ?? { version: 2, installedAt: '', files: {} };
+        const before = record.files[settingsFile] ?? { plugins: [], marketplace: false, env: false };
+        record.files[settingsFile] = {
+            plugins: [...new Set([...before.plugins, ...added.plugins])],
+            marketplace: before.marketplace || added.marketplace,
+            env: before.env || added.env,
+            claudeInstalled: before.claudeInstalled ?? [],
+        };
+        record.installedAt = new Date().toISOString();
+        writeJson(join(resolve(projectRoot), INSTALL_RECORD), record);
+    }
+    catch (error) {
+        try {
+            if (backup) {
+                copyFileSync(backup, settingsFile);
+                unlinkSync(backup);
+            }
+            else if (existsSync(settingsFile)) {
+                unlinkSync(settingsFile);
+            }
+        }
+        catch {
+            // the restore itself failed: the original error below is the one to report
+        }
+        throw error;
+    }
     return { settingsFile, backup, added, dryRun, next };
 }
 /** The install record, v1 (3.50.0: one file, ruflo-mods only) read as v2. */

package/dist/src/mods/plugin-resolve.js

@@ -160,7 +160,9 @@ export function resolveFindings(projectRoot, scope, configDir, fs = nodeReadFs,
         else if (!market.location) {
             findings.push(installed.installed
                 ? { name, status: 'pass', message: `installed (${installed.scope} scope, ${installed.installPath})` }
-                : { name, status: 'warn', message: plugin.required ? 'loads once Claude Code has cloned the marketplace' : 'pending: not released in the ruflo marketplace yet' });
+                : plugin.required
+                    ? { name, status: 'warn', message: 'loads once Claude Code has cloned the marketplace (a headless `claude -p` run on a fresh config does not clone it, so the mod is absent there)', fix }
+                    : { name, status: 'warn', message: 'pending: not released in the ruflo marketplace yet' });
         }
         else if (!plugin.required) {
             findings.push({ name, status: 'warn', message: `pending: not in the ruflo marketplace yet (${market.location})${also}` });