@claude-flow/cli 3.56.10 → 3.57.1

package/.claude/helpers/.helpers-version

@@ -1 +1 @@
-3.56.9
+3.57.0

package/.claude/helpers/helpers.manifest.json

@@ -1,6 +1,6 @@
 {
   "manifest": {
-    "version": "3.56.10",
+    "version": "3.57.1",
     "files": {
       "auto-memory-hook.mjs": "631fac9d518835e2852a406888316bbbddddb49e7ed8e406d2e971f46833df9a",
       "hook-handler.cjs": "bc12b3cae92d5a7c8deef699fa00d0ef07b57625c18dbeac4387f15725b8e09f",
@@ -9,6 +9,6 @@
       "router.cjs": "16648b3c0d73b6681ac2d8d13def6a68286c57f5a11004de5b19a0fa088c833d"
     }
   },
-  "signature": "hZ0iy15VIKpZOjC2iG2fPsV68csqXrMhn2mifCIvzsjngaB/wmP0P4iMF38nAo57MeANEM6wW1nhK7YvteUXCg==",
+  "signature": "4QJCbq039ufiBQ0tz2aVw1refajyDbptNNS+xaHszCNADeMKOzqL3pT3dh4k+hZgMn+zKYh1V0FOmF9GyXJhAA==",
   "algorithm": "ed25519"
 }

package/README.md

@@ -10,10 +10,11 @@
 [![Star on GitHub](https://img.shields.io/github/stars/ruvnet/claude-flow?style=for-the-badge&logo=github&color=gold)](https://github.com/ruvnet/claude-flow)
 
 <p align="center">
-<a href="data/npm-downloads.latest.json"><img src="docs/assets/readme/badges/downloads.svg?v=mobile-readable-3" width="300" alt="Ecosystem npm downloads: 12.52M over 12 months through October 4, 2026"></a>
+<a href="docs/harness-origins.md"><img src="https://raw.githubusercontent.com/ruvnet/ruflo/e69e4b95aa08d65ea0f7715489bbf8e62a83a0d2/docs/assets/readme/badges/first-commit.svg" width="300" height="76" alt="Claude Flow lineage: first commit June 2, 2025 by rUv; inspect the evidence"></a>
+<a href="data/npm-downloads.latest.json"><img src="https://raw.githubusercontent.com/ruvnet/ruflo/275aff65a198af758923669acff36f03d1f41623/docs/assets/readme/badges/downloads.svg" width="300" height="76" alt="Illustrative download counter starts at 98,000,000 and adds varied amounts each second in a 30 second loop. Verified dataset: 97,022,120 download events."></a>
 <br>
-<a href="https://github.com/ruvnet/claude-flow"><img src="docs/assets/readme/badges/claude.svg?v=mobile-readable-3" width="300" alt="Claude Code"></a>
-<a href="https://www.npmjs.com/package/@claude-flow/codex"><img src="docs/assets/readme/badges/codex.svg?v=mobile-readable-3" width="300" alt="Codex Plugin"></a>
+<a href="https://github.com/ruvnet/claude-flow"><img src="https://raw.githubusercontent.com/ruvnet/ruflo/d1e80400bdefe01d3b13e70395f88fffab76bb18/docs/assets/readme/badges/claude.svg" width="300" height="76" alt="Claude Code plugin"></a>
+<a href="https://www.npmjs.com/package/@claude-flow/codex"><img src="https://raw.githubusercontent.com/ruvnet/ruflo/d1e80400bdefe01d3b13e70395f88fffab76bb18/docs/assets/readme/badges/codex.svg" width="300" height="76" alt="Codex plugin"></a>
 </p>
 
 </div>
@@ -109,6 +110,14 @@ User → Ruflo (CLI/MCP) → Router → Swarm → Agents → Memory → LLM prov
 
 > **New to Ruflo?** You don't need to learn 314 MCP tools or 26 CLI commands. After `init`, just use Claude Code normally — the hooks system automatically routes tasks, learns from successful patterns, and coordinates agents in the background.
 
+### An origin you can inspect
+
+[![Claude Flow to Ruflo: founding idea on June 2, 2025, orchestration source on June 10, and the continuing Ruflo lineage.](docs/assets/readme/harness-origins.svg)](docs/harness-origins.md)
+
+**Built by [Reuven Cohen (rUv)](https://github.com/ruvnet), originally as Claude Flow.** The [first commit, June 2, 2025](https://github.com/ruvnet/ruflo/commit/7c1f9402d70e7af56c01a879073cbac92564dc4e), describes a code orchestration layer for recursive agent cycles: Claude writes, edits, tests and improves. The [June 10 source snapshot](https://github.com/ruvnet/ruflo/tree/dba545f012ea92a2375a26332bbf3797495e93c9) adds orchestration, task scheduling, memory and terminal modules.
+
+A harness is the workbench around the model: it organizes tasks, carries context between steps and helps check results. **This establishes Ruflo's lineage, not a universal first across every Claude Code tool.** [See the illustrated explainer, exact commits and earlier ecosystem context](docs/harness-origins.md).
+
 <details>
 <summary><strong>📖 Background — where the name comes from</strong></summary>
 

package/catalog-manifest.json

@@ -1,8 +1,8 @@
 {
   "schemaVersion": 1,
   "generation": 7,
-  "generatedAt": "2026-10-14T16:22:09.483Z",
-  "gitSha": "1882006a",
+  "generatedAt": "2026-10-19T16:47:16.220Z",
+  "gitSha": "aedd3d53",
   "catalog": {
     "agents": 176,
     "tools": 423,

package/dist/src/commands/daemon.js

@@ -1247,12 +1247,18 @@ const statusCommand = {
             // its real consent state into daemon-state.json — prefer that when it
             // is the one running.
             let aiWorkersEnabled = status.config.aiWorkersEnabled;
+            // #4238: same for the TTL — a daemon started with `--ttl 0` must not be
+            // reported with this process's 12h default.
+            let ttlMs = status.config.ttlMs;
             if (bgRunning) {
                 try {
                     const st = JSON.parse(fs.readFileSync(join(projectRoot, '.claude-flow', 'daemon-state.json'), 'utf-8'));
                     if (typeof st?.config?.aiWorkersEnabled === 'boolean') {
                         aiWorkersEnabled = st.config.aiWorkersEnabled;
                     }
+                    if (typeof st?.config?.ttlMs === 'number' && Number.isFinite(st.config.ttlMs)) {
+                        ttlMs = st.config.ttlMs;
+                    }
                 }
                 catch { /* no/partial state — fall back to in-process config */ }
             }
@@ -1265,8 +1271,8 @@ const statusCommand = {
                 `Status: ${statusIcon} ${statusText}${mode}`,
                 `PID: ${displayPid}`,
                 status.startedAt ? `Started: ${status.startedAt.toISOString()}` : '',
-                status.config.ttlMs > 0
-                    ? `TTL: ${Math.round(status.config.ttlMs / 3600000)}h (self-shutdown)`
+                ttlMs > 0
+                    ? `TTL: ${Math.round(ttlMs / 3600000)}h (self-shutdown)`
                     : `TTL: ${output.dim('off (runs until stopped)')}`,
                 // #2661: surface the AI-consent gate so "why is audit local-only?"
                 // is answerable from `daemon status` alone.

package/dist/src/commands/doctor.js

@@ -2515,6 +2515,12 @@ export const doctorCommand = {
     name: 'doctor',
     description: 'System diagnostics and health checks',
     options: [
+        {
+            name: 'json',
+            description: 'Emit versioned JSON health checks (cannot be combined with repair flags)',
+            type: 'boolean',
+            default: false
+        },
         {
             name: 'fix',
             short: 'f',
@@ -2561,6 +2567,7 @@ export const doctorCommand = {
         }
     ],
     examples: [
+        { command: 'claude-flow doctor --json -c node', description: 'Emit machine-readable health checks' },
         { command: 'claude-flow doctor', description: 'Run full health check' },
         { command: 'claude-flow doctor --fix', description: 'Print suggested fix commands (does not auto-apply)' },
         { command: 'claude-flow doctor --install', description: 'Auto-install missing dependencies' },
@@ -2575,6 +2582,21 @@ export const doctorCommand = {
         const verbose = ctx.flags.verbose;
         // Parser camelCases kebab-case flag names — read via `fixHandles`, not `['fix-handles']`.
         const fixHandles = ctx.flags.fixHandles;
+        const json = ctx.flags.json;
+        const reportError = (message) => {
+            if (json)
+                output.writeln(JSON.stringify({ schemaVersion: 1, checks: [], error: message }));
+            else
+                output.printError(message);
+            return { success: false, exitCode: 1, message };
+        };
+        if (json && (showFix || autoInstall || fixHandles)) {
+            return reportError('--json cannot be combined with --fix, --install, or --fix-handles');
+        }
+        // Reuse the same callable for anonymous checks so their IDs do not depend
+        // on display names or on whether the full or component suite was selected.
+        const helperCheck = () => checkHelperIntegrity();
+        const nativeAddonCheck = () => checkNativeAddonHeaders();
         // #2677: `--component memory` now runs the whole memory-health suite,
         // not just the existence check. Values can be a single check or an
         // array — expanded at execution time. Stuinfla's report showed the
@@ -2592,7 +2614,7 @@ export const doctorCommand = {
             'browser': checkAgentBrowserVersion,
             'config': checkConfigFile,
             'stale-settings': checkStaleSettingsNpx, // #2448
-            'helpers': () => checkHelperIntegrity(), // #3565
+            'helpers': helperCheck, // #3565
             'daemon': checkDaemonStatus,
             get memory() {
                 return [
@@ -2608,7 +2630,7 @@ export const doctorCommand = {
                 ];
             },
             'memory-package': checkMemoryPackageVersion, // #3392
-            'native-addon': () => checkNativeAddonHeaders(), // #4055
+            'native-addon': nativeAddonCheck, // #4055
             'learning': checkLearningBridge, // #2545
             'learning-bridge': checkLearningBridge, // #2545
             'api': checkApiKeys,
@@ -2634,8 +2656,7 @@ export const doctorCommand = {
         };
         if (component !== undefined && !Object.hasOwn(componentMap, component)) {
             const message = `Unknown doctor component: ${JSON.stringify(component)}. Valid components: ${Object.keys(componentMap).join(', ')}`;
-            output.printError(message);
-            return { success: false, exitCode: 1, message };
+            return reportError(message);
         }
         // Early-return short-circuit: `--fix-handles` is a targeted mitigation, not
         // part of the health-check flow. Runs, reports, exits.
@@ -2699,12 +2720,15 @@ export const doctorCommand = {
             output.writeln(output.dim('Upstream tracking: https://github.com/anthropics/claude-code/issues/67888'));
             return { success: true };
         }
-        output.writeln();
-        output.writeln(output.bold('RuFlo Doctor'));
-        output.writeln(output.dim('System diagnostics and health check'));
-        output.writeln(output.dim('─'.repeat(50)));
-        output.writeln();
-        const nativeAgentDbChecks = (await existingNativeAgentDbPaths())
+        if (!json) {
+            output.writeln();
+            output.writeln(output.bold('RuFlo Doctor'));
+            output.writeln(output.dim('System diagnostics and health check'));
+            output.writeln(output.dim('─'.repeat(50)));
+            output.writeln();
+        }
+        const nativeAgentDbPaths = await existingNativeAgentDbPaths();
+        const nativeAgentDbChecks = nativeAgentDbPaths
             .map((dbPath) => () => checkNativeAgentDbStructuralIntegrity(dbPath));
         const allChecks = [
             checkVersionFreshness,
@@ -2716,7 +2740,7 @@ export const doctorCommand = {
             checkGitRepo,
             checkConfigFile,
             checkStaleSettingsNpx, // #2448/#2677 — runaway `npx @latest` in settings
-            () => checkHelperIntegrity(), // #3565 — installed signed helpers vs manifest
+            helperCheck, // #3565 — installed signed helpers vs manifest
             checkDaemonStatus,
             checkMemoryDatabase,
             checkMemoryStructuralIntegrity, // #2737 — bounded, native quick_check on every default run
@@ -2724,7 +2748,7 @@ export const doctorCommand = {
             checkMemoryPersistenceDriver, // #2968/#3321 — read-only native capability probe
             checkLearningBridge, // #2545 — can the auto-memory hook actually load @claude-flow/memory?
             checkMemoryPackageVersion, // #3392 — loaded @claude-flow/memory must satisfy the CLI's declared range
-            () => checkNativeAddonHeaders(), // #4055 — better-sqlite3 built against Node 24.19+ headers on 24.19-24.21
+            nativeAddonCheck, // #4055 — better-sqlite3 built against Node 24.19+ headers on 24.19-24.21
             checkApiKeys,
             checkMcpServers,
             checkMcpSchemaOverhead, // #2726 — fixed tools/list prompt cost
@@ -2747,21 +2771,59 @@ export const doctorCommand = {
             const entry = componentMap[component];
             checksToRun = Array.isArray(entry) ? entry : [entry];
         }
+        // These are API identifiers: keep them stable even when user-facing names
+        // change. Grouped components have a distinct ID for each individual check.
+        const checkIds = new Map([
+            [checkVersionFreshness, 'version'], [checkNodeVersion, 'node'],
+            [checkNpmVersion, 'npm'], [checkClaudeCode, 'claude'],
+            [checkAgentBrowserVersion, 'browser'], [checkGit, 'git'],
+            [checkGitRepo, 'git-repo'], [checkConfigFile, 'config'],
+            [checkStaleSettingsNpx, 'stale-settings'], [helperCheck, 'helpers'],
+            [checkDaemonStatus, 'daemon'], [checkMemoryDatabase, 'memory-presence'],
+            [checkMemoryStructuralIntegrity, 'memory-structural'],
+            [checkMemoryIntegrity, 'memory-integrity'],
+            [checkMemoryPersistenceDriver, 'memory-driver'],
+            [checkMemoryPackageVersion, 'memory-package'],
+            [checkMemoryContent, 'memory-content'],
+            [checkMemoryEmbeddingCoverage, 'memory-embeddings'],
+            [checkMemoryReflexionCoverage, 'memory-reflexion'],
+            [checkMemoryCritiqueCoverage, 'memory-critique'],
+            [checkLearningBridge, 'learning'], [nativeAddonCheck, 'native-addon'],
+            [checkApiKeys, 'api'], [checkMcpServers, 'mcp'],
+            [checkMcpSchemaOverhead, 'mcp-overhead'], [checkAIDefence, 'aidefence'],
+            [checkDiskSpace, 'disk'], [checkBuildTools, 'typescript'],
+            [checkAgenticFlow, 'agentic-flow'], [checkEncryptionAtRest, 'encryption'],
+            [checkFederationBreaker, 'federation'], [checkMetaharness, 'metaharness'],
+            [checkMetaharnessDeclaredPackages, 'metaharness-packages'],
+            [checkMetaharnessIntegration, 'metaharness-integration'],
+            [checkFunnel, 'funnel'], [checkProxySponsoredConsent, 'proxy-consent'],
+            [checkProxyBinary, 'proxy-binary'], [checkProxyProcess, 'proxy-process'],
+            [checkProxyBindAddress, 'proxy-bind'], [checkAuth, 'auth'],
+            [checkTypesafeRouter, 'typesafe'], [checkMods, 'mods'],
+        ]);
+        nativeAgentDbChecks.forEach((check, index) => {
+            // The path distinguishes simultaneous authority files; normalize separators.
+            checkIds.set(check, `memory-native:${nativeAgentDbPaths[index].replace(/\\/g, '/')}`);
+        });
+        if (json && checksToRun.some(check => !checkIds.has(check))) {
+            return reportError('Doctor check is missing a stable JSON ID');
+        }
         const results = [];
         const fixes = [];
         // OPTIMIZATION: Run all checks in parallel for 3-5x faster execution
-        const spinner = output.createSpinner({ text: 'Running health checks in parallel...', spinner: 'dots' });
-        spinner.start();
+        const spinner = json ? undefined : output.createSpinner({ text: 'Running health checks in parallel...', spinner: 'dots' });
+        spinner?.start();
         try {
             // Execute all checks concurrently
             const checkResults = await Promise.allSettled(checksToRun.map(check => check()));
-            spinner.stop();
+            spinner?.stop();
             // Process results in order
             for (const settledResult of checkResults) {
                 if (settledResult.status === 'fulfilled') {
                     const result = settledResult.value;
                     results.push(result);
-                    output.writeln(formatCheck(result));
+                    if (!json)
+                        output.writeln(formatCheck(result));
                     if (result.fix && (result.status === 'fail' || result.status === 'warn')) {
                         fixes.push(`${result.name}: ${result.fix}`);
                     }
@@ -2773,12 +2835,15 @@ export const doctorCommand = {
                         message: settledResult.reason?.message || 'Unknown error'
                     };
                     results.push(errorResult);
-                    output.writeln(formatCheck(errorResult));
+                    if (!json)
+                        output.writeln(formatCheck(errorResult));
                 }
             }
         }
         catch (error) {
-            spinner.stop();
+            spinner?.stop();
+            if (json)
+                return reportError(`Failed to run health checks: ${error instanceof Error ? error.message : String(error)}`);
             output.writeln(output.error('Failed to run health checks'));
         }
         // #2545: --fix / --install can actually repair the Learning Bridge by
@@ -2827,6 +2892,18 @@ export const doctorCommand = {
         const passed = results.filter(r => r.status === 'pass').length;
         const warnings = results.filter(r => r.status === 'warn').length;
         const failed = results.filter(r => r.status === 'fail').length;
+        if (json) {
+            const checks = results.map((result, index) => ({
+                id: checkIds.get(checksToRun[index]),
+                status: result.status,
+                name: result.name,
+                detail: result.message,
+                ...(result.fix ? { fix: result.fix } : {}),
+            }));
+            const data = { schemaVersion: 1, checks };
+            output.writeln(JSON.stringify(data));
+            return { success: failed === 0, exitCode: failed > 0 ? 1 : 0, data };
+        }
         output.writeln();
         output.writeln(output.dim('─'.repeat(50)));
         output.writeln();

package/dist/src/commands/policy.js

@@ -30,6 +30,7 @@ export const policyCommand = {
         { name: 'mode', type: 'string', description: 'Policy mode: legacy | observe | enforce' },
         { name: 'project-root', type: 'string', description: 'Project root containing .claude-flow/policy' },
         { name: 'establish-anchor', type: 'boolean', description: 'verify: explicitly anchor a ledger that has receipts but no anchor (interactive, logged with user and time)' },
+        { name: 'full', type: 'boolean', description: 'verify: additionally replay the archived receipts (receipts.ledger.jsonl) to verify the complete historical chain, not just the retained hot tail' },
     ],
     async action(context) {
         const args = context.args ?? [];
@@ -93,9 +94,13 @@ export const policyCommand = {
             }
             if (operation === 'verify') {
                 const establishAnchor = flags['establish-anchor'] === true || flags.establishAnchor === true;
+                const full = flags.full === true;
                 if (establishAnchor)
                     requireInteractiveAdministrator();
-                const ledger = await verifyPolicyLedger(root, { establishAnchor });
+                const ledger = await verifyPolicyLedger(root, { establishAnchor, full });
+                if (ledger.error === 'receipt-key-id-mismatch') {
+                    output.printError('Restore the original CLAUDE_FLOW_POLICY_KEY_ID for this ledger; do not rewrite or re-sign historical receipts.');
+                }
                 const result = print({ ...ledger, anchors: anchorPosture(root), scope: LEDGER_TRUST_SCOPE });
                 return ledger.valid ? result : { ...result, success: false, exitCode: 1 };
             }

package/dist/src/index.js

@@ -92,13 +92,13 @@ export class CLI {
             const parseResult = this.parser.parse(args);
             const { command: commandPath, flags, positional } = parseResult;
             // Handle global flags
+            if (flags.noColor || flags.color === false) {
+                this.output.setColorEnabled(false);
+            }
             if (flags.version || flags.V) {
                 this.showVersion();
                 return;
             }
-            if (flags.noColor) {
-                this.output.setColorEnabled(false);
-            }
             // Set verbosity level based on flags
             if (flags.quiet) {
                 this.output.setVerbosity('quiet');
@@ -114,7 +114,7 @@ export class CLI {
                 this.output.printDebug(`CWD: ${process.cwd()}`);
             }
             // Run startup update check (non-blocking, silent on skip)
-            if (!flags.noUpdate && commandPath[0] !== 'update') {
+            if (!flags.noUpdate && flags.update !== false && commandPath[0] !== 'update' && !(commandPath[0] === 'doctor' && flags.json)) {
                 this.checkForUpdatesOnStartup().catch(() => { });
             }
             // Version-stamped helper auto-refresh — propagate hook fixes to an already
@@ -536,7 +536,7 @@ export class CLI {
         catch (error) {
             // Config loading is optional - don't fail if it doesn't exist
             if (process.env.DEBUG) {
-                this.output.writeln(this.output.dim(`Config loading failed: ${error.message}`));
+                this.output.writeErrorln(this.output.dim(`Config loading failed: ${error.message}`));
             }
             return undefined;
         }

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

@@ -27,7 +27,6 @@ export function generateSettings(options) {
         allow: [
             'Bash(npx @claude-flow*)',
             'Bash(npx claude-flow*)',
-            'Bash(node .claude/*)',
             'mcp__claude-flow__*',
         ],
         deny: [
@@ -201,7 +200,7 @@ function generateHooksConfig(config, scope) {
     const hooks = {};
     // Node.js scripts handle errors internally via try/catch.
     // No shell-level error suppression needed (2>/dev/null || true breaks Windows).
-    // PreToolUse — validate commands and edits before execution
+    // PreToolUse — validate shell commands before execution
     if (config.preToolUse) {
         hooks.PreToolUse = [
             {
@@ -214,19 +213,9 @@ function generateHooksConfig(config, scope) {
                     },
                 ],
             },
-            {
-                matcher: 'Write|Edit|MultiEdit',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('pre-edit', scope),
-                        timeout: config.timeout,
-                    },
-                ],
-            },
         ];
     }
-    // PostToolUse — record edits and commands for session metrics / learning
+    // PostToolUse — record edits for session metrics / learning
     if (config.postToolUse) {
         hooks.PostToolUse = [
             {
@@ -239,16 +228,6 @@ function generateHooksConfig(config, scope) {
                     },
                 ],
             },
-            {
-                matcher: 'Bash',
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('post-bash', scope),
-                        timeout: config.timeout,
-                    },
-                ],
-            },
         ];
     }
     // UserPromptSubmit — intelligent task routing
@@ -312,16 +291,13 @@ function generateHooksConfig(config, scope) {
             },
         ];
     }
-    // PreCompact — preserve context before compaction
+    // PreCompact — end the current session before compaction. The handler has no
+    // manual/automatic compaction-specific command, so don't wire no-op hooks.
     if (config.preCompact) {
         hooks.PreCompact = [
             {
                 matcher: 'manual',
                 hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('compact-manual', scope),
-                    },
                     {
                         type: 'command',
                         command: hookHandlerCmd('session-end', scope),
@@ -332,10 +308,6 @@ function generateHooksConfig(config, scope) {
             {
                 matcher: 'auto',
                 hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('compact-auto', scope),
-                    },
                     {
                         type: 'command',
                         command: hookHandlerCmd('session-end', scope),
@@ -345,18 +317,6 @@ function generateHooksConfig(config, scope) {
             },
         ];
     }
-    // SubagentStart — status update when a sub-agent is spawned
-    hooks.SubagentStart = [
-        {
-            hooks: [
-                {
-                    type: 'command',
-                    command: hookHandlerCmd('status', scope),
-                    timeout: 3000,
-                },
-            ],
-        },
-    ];
     // SubagentStop — track agent completion for metrics
     // NOTE: The valid event is "SubagentStop" (not "SubagentEnd")
     hooks.SubagentStop = [
@@ -370,20 +330,6 @@ function generateHooksConfig(config, scope) {
             ],
         },
     ];
-    // Notification — capture Claude Code notifications for logging
-    if (config.notification) {
-        hooks.Notification = [
-            {
-                hooks: [
-                    {
-                        type: 'command',
-                        command: hookHandlerCmd('notify', scope),
-                        timeout: 3000,
-                    },
-                ],
-            },
-        ];
-    }
     // NOTE: TeammateIdle, TaskCompleted, and PostCompact are NOT accepted by
     // Claude Code's settings.json validator (rejected as "Invalid key in record").
     // Agent Teams coordination lives in claudeFlow.agentTeams.hooks instead.

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

@@ -9,7 +9,7 @@
  *
  * @module v3/cli/mcp-tools/memory-tools
  */
-import type { MCPTool } from './types.js';
+import { type MCPTool } from './types.js';
 export declare const DANGEROUS_KEY_PATTERN: RegExp;
 /**
  * #3570: the one key rule for every memory write path (MCP store, CLI store,

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

@@ -11,8 +11,10 @@
  */
 import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, unlinkSync, writeFileSync } from 'fs';
 import { homedir } from 'os';
-import { join, resolve } from 'path';
+import { basename, dirname, join, resolve } from 'path';
+import { execFileSync } from 'node:child_process';
 import { createHash } from 'crypto';
+import { getProjectCwd } from './types.js';
 import { validateIdentifier } from './validate-input.js';
 import { DEFAULT_SEARCH_THRESHOLD, nearMisses } from '../memory/search-defaults.js';
 // #1604: Align with memory-initializer.ts — single source of truth is .swarm/memory.db
@@ -146,7 +148,24 @@ function resolveProjectMemoryDir(claudeProjectsDir, projectPathOverride) {
         sources.push(projectPathOverride);
     }
     else {
-        sources.push(process.cwd());
+        const project = getProjectCwd();
+        sources.push(project);
+        // Claude Code shares auto-memory across linked Git worktrees under the
+        // main checkout's project slug. Preserve the direct-path match first,
+        // then try the common Git directory's parent. Explicit overrides above
+        // remain authoritative, and non-Git projects need no Git dependency.
+        try {
+            const commonDir = execFileSync('git', ['rev-parse', '--path-format=absolute', '--git-common-dir'], {
+                cwd: project,
+                encoding: 'utf-8',
+                timeout: 1000,
+                windowsHide: true,
+                stdio: ['ignore', 'pipe', 'ignore'],
+            }).trim();
+            if (basename(commonDir) === '.git')
+                sources.push(dirname(resolve(project, commonDir)));
+        }
+        catch { /* Git unavailable or not a repository: use the project path */ }
     }
     for (const source of sources) {
         // Candidate 1: legacy POSIX hash — what shipped before #1883
@@ -1066,6 +1085,7 @@ export const memoryTools = [
             }
             let imported = 0;
             let skipped = 0;
+            const importErrors = [];
             // #1791.8 — Claude Code's `~/.claude/projects/` accumulates historical
             // project_id directories (truncated forms, sandbox cwds, renamed
             // workspaces) that all contain copies of the same memory files. The
@@ -1105,7 +1125,7 @@ export const memoryTools = [
                         // #1884 — sanitize key so memory_delete can later remove it. Without
                         // this, dangerous chars from frontmatter `name` strand the key.
                         const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}`);
-                        const stored = await storeEntry({ key, value: body, namespace: ns, generateEmbeddingFlag: true });
+                        const stored = await storeEntry({ key, value: body, namespace: ns, generateEmbeddingFlag: true, upsert: true });
                         if (!stored.success)
                             throw new Error(stored.error || `Failed to store ${key}`);
                         imported++;
@@ -1120,15 +1140,19 @@ export const memoryTools = [
                             // #1884 — sanitize so any dangerous chars in the heading don't
                             // produce keys memory_delete will reject.
                             const key = sanitizeMemoryKey(`claude:${memFile.project}:${name}:${sectionTitle.slice(0, 50)}`);
-                            const stored = await storeEntry({ key, value: sectionBody, namespace: ns, generateEmbeddingFlag: true });
+                            const stored = await storeEntry({ key, value: sectionBody, namespace: ns, generateEmbeddingFlag: true, upsert: true });
                             if (!stored.success)
                                 throw new Error(stored.error || `Failed to store ${key}`);
                             imported++;
                         }
                     }
                 }
-                catch {
+                catch (err) {
                     skipped++;
+                    // Say why a file was skipped instead of returning a bare failure (#4197).
+                    if (importErrors.length < 5) {
+                        importErrors.push(`${memFile.path}: ${err instanceof Error ? err.message : String(err)}`);
+                    }
                 }
             }
             // AUDIT #3: report the embedding backend truthfully — a hash-fallback
@@ -1147,6 +1171,7 @@ export const memoryTools = [
                 skipped,
                 duplicatesSkipped,
                 excludedByPattern,
+                ...(importErrors.length > 0 ? { errors: importErrors } : {}),
                 files: memoryFiles.length,
                 projects: projects.size,
                 namespace: ns,

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

@@ -399,7 +399,7 @@ export const metaharnessTools = [
     },
     // ───────────────────────────────────────────────────────────────────────
     // ADR-153 — @metaharness/darwin integration (3 tools).
-    // Backed by the separate `@metaharness/darwin@~0.10.2` npm package, NOT
+    // Backed by the separate `@metaharness/darwin@~0.12.0` npm package, NOT
     // the umbrella `metaharness`. Plugin scripts shell out via _darwin.mjs.
     // Same {success, data, degraded, exitCode} contract.
     // ───────────────────────────────────────────────────────────────────────