@claude-flow/cli 3.56.3 → 3.56.5

package/dist/src/init/executor.js

@@ -20,6 +20,7 @@ import { generateClaudeMd } from './claudemd-generator.js';
 import { recordMemoryPackagePath } from './memory-package-resolver.js';
 import { ensureCommonJsCompanions } from './helper-companions.js';
 import { scanSettingsForRisk, formatRiskFindingsAsWarnings } from './settings-risk-scanner.js';
+import { helperHookCommand, helperScopeFor, helperStatusLineCommand, pinToUserHelpers } from './helper-commands.js';
 /**
  * Skills to copy based on configuration
  */
@@ -278,12 +279,15 @@ export async function executeInit(options) {
  * Preserves user customizations while adding new features like Agent Teams
  * Uses platform-specific commands for Mac, Linux, and Windows
  */
-export function mergeSettingsForUpgrade(existing) {
+export function mergeSettingsForUpgrade(existing, targetDir) {
     // Scan the pre-existing hooks/permissions BEFORE they get spread into
     // `merged` below — this is the untrusted, disk-sourced content a
     // malicious settings.json would use to smuggle a hook payload through.
     const warnings = formatRiskFindingsAsWarnings(scanSettingsForRisk({ hooks: existing.hooks, permissions: existing.permissions }));
     const merged = { ...existing };
+    // User-level settings (~/.claude/settings.json) apply to every opened
+    // project, so their helper commands never look inside the project.
+    const scope = helperScopeFor(targetDir);
     const platform = detectPlatform();
     const isWindows = platform.os === 'windows';
     // Platform-specific command wrappers
@@ -309,8 +313,12 @@ export function mergeSettingsForUpgrade(existing) {
         + "try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}"
         + 'catch(e){r=process.cwd()}';
     const autoMemoryScript = '.claude/helpers/auto-memory-hook.mjs';
-    const autoMemoryImportCmd = `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" import`;
-    const autoMemorySyncCmd = `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" sync`;
+    const autoMemoryImportCmd = scope === 'user'
+        ? helperHookCommand(autoMemoryScript, 'import', 'user')
+        : `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" import`;
+    const autoMemorySyncCmd = scope === 'user'
+        ? helperHookCommand(autoMemoryScript, 'sync', 'user')
+        : `node -e "${gitRootResolver}var f=p.join(r,'${autoMemoryScript}');import(u.pathToFileURL(f).href)" sync`;
     // Add auto-memory import to SessionStart (if not already present)
     const sessionStartHooks = existingHooks.SessionStart;
     const hasAutoMemoryImport = sessionStartHooks?.some(group => group.hooks?.some(h => h.command?.includes('auto-memory-hook')));
@@ -364,7 +372,8 @@ export function mergeSettingsForUpgrade(existing) {
     // / jetsam / kernel panic. Preserving the user's existing command (the
     // old behavior here) means anyone who installed pre-#2337 and upgraded
     // never gets the fix. Now we detect the broken form and overwrite.
-    const NEW_STATUSLINE_CMD = `node -e "var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}var s=p.join(r,'.claude/helpers/statusline.cjs');process.argv.splice(1,0,s);require(s)"`;
+    const NEW_STATUSLINE_CMD = scope === 'user' ? helperStatusLineCommand('user') :
+        `node -e "var c=require('child_process'),p=require('path'),r;try{r=c.execSync('git rev-parse --show-toplevel',{encoding:'utf8'}).trim()}catch(e){r=process.cwd()}var s=p.join(r,'.claude/helpers/statusline.cjs');process.argv.splice(1,0,s);require(s)"`;
     // Matches any invocation of `claude-flow hooks statusline` — either via npx
     // (`npx [--prefer-offline] [@]claude-flow[/cli][@<tag>] hooks statusline …`)
     // or as a bare command (`claude-flow hooks statusline …`). Both forms cold-
@@ -381,9 +390,10 @@ export function mergeSettingsForUpgrade(existing) {
     if (existingStatusLine) {
         const existingCmd = typeof existingStatusLine.command === 'string' ? existingStatusLine.command : '';
         const isBroken = BROKEN_STATUSLINE_RE.test(existingCmd) || BROKEN_NPX_LATEST_RE.test(existingCmd);
+        const pinned = scope === 'user' ? pinToUserHelpers(existingCmd) : null;
         merged.statusLine = {
             type: 'command',
-            command: isBroken || !existingCmd ? NEW_STATUSLINE_CMD : existingCmd,
+            command: isBroken || !existingCmd ? NEW_STATUSLINE_CMD : pinned ?? existingCmd,
             // Remove invalid fields: refreshMs, enabled (not supported by Claude Code)
         };
     }
@@ -398,15 +408,8 @@ export function mergeSettingsForUpgrade(existing) {
     // migration on already-correct settings is a no-op.
     // Bounded for the same reason as BROKEN_STATUSLINE_RE above (CodeQL js/redos).
     const BROKEN_HOOK_RE = /npx\s+(?:--?\S+\s+){0,10}@?claude-flow\/cli@latest\s+hooks\s+(\S+)/;
-    const localHookCmd = (sub) => {
-        // POSIX form mirrors settings-generator.ts::hookCmd() exactly.
-        // Windows users hit a separate code path (cmd /c …) — Claude Code on
-        // Windows is rarer and the migration there is left to a follow-up.
-        if (process.platform === 'win32') {
-            return `cmd /c "IF EXIST \"%CLAUDE_PROJECT_DIR%\\.claude\\helpers\\hook-handler.cjs\" (node \"%CLAUDE_PROJECT_DIR%\\.claude\\helpers\\hook-handler.cjs\" ${sub}) ELSE (node \"%USERPROFILE%\\.claude\\helpers\\hook-handler.cjs\" ${sub})"`;
-        }
-        return `sh -c 'D="\${CLAUDE_PROJECT_DIR:-.}"; [ -f "$D/.claude/helpers/hook-handler.cjs" ] || D="\${HOME}"; exec node "$D/.claude/helpers/hook-handler.cjs" ${sub}'`;
-    };
+    // Same command settings-generator.ts emits for this settings scope.
+    const localHookCmd = (sub) => helperHookCommand('.claude/helpers/hook-handler.cjs', sub, scope);
     const mergedHooks = merged.hooks;
     if (mergedHooks) {
         for (const eventName of Object.keys(mergedHooks)) {
@@ -419,6 +422,12 @@ export function mergeSettingsForUpgrade(existing) {
                 group.hooks = group.hooks.filter((h) => {
                     if (typeof h?.command !== 'string')
                         return true;
+                    // A user-level probe ruflo generated earlier is re-pinned to HOME.
+                    const pinned = scope === 'user' ? pinToUserHelpers(h.command) : null;
+                    if (pinned) {
+                        h.command = pinned;
+                        return true;
+                    }
                     const m = BROKEN_HOOK_RE.exec(h.command);
                     if (m) {
                         // Subcommand captured (e.g. "pre-bash", "post-edit", "route") — keep it.
@@ -655,7 +664,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
             if (fs.existsSync(settingsPath)) {
                 try {
                     const existingSettings = JSON.parse(fs.readFileSync(settingsPath, 'utf-8'));
-                    const { merged: mergedSettings, warnings: settingsRiskWarnings } = mergeSettingsForUpgrade(existingSettings);
+                    const { merged: mergedSettings, warnings: settingsRiskWarnings } = mergeSettingsForUpgrade(existingSettings, targetDir);
                     fs.writeFileSync(settingsPath, JSON.stringify(mergedSettings, null, 2), 'utf-8');
                     result.updated.push('.claude/settings.json');
                     result.settingsUpdated = [
@@ -677,7 +686,7 @@ export async function executeUpgrade(targetDir, upgradeSettings = false) {
             }
             else {
                 // Create new settings.json with defaults
-                const defaultSettings = generateSettings(DEFAULT_INIT_OPTIONS);
+                const defaultSettings = generateSettings({ ...DEFAULT_INIT_OPTIONS, targetDir });
                 fs.writeFileSync(settingsPath, JSON.stringify(defaultSettings, null, 2), 'utf-8');
                 result.created.push('.claude/settings.json');
                 result.settingsUpdated = ['Created new settings.json with Agent Teams'];

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

@@ -0,0 +1,18 @@
+export type HelperScope = 'project' | 'user';
+/** 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. */
+export declare function helperHookCommand(script: string, subcommand: string, scope: HelperScope, windows?: boolean): string;
+/** Command for the statusLine entry. */
+export declare function helperStatusLineCommand(scope: HelperScope, windows?: boolean): string;
+/**
+ * Rewrite a command that runs one of ruflo's helpers from the opened project
+ * into the pinned user-level form, keeping its subcommand. Covers every form
+ * ruflo has shipped: the #1943 sh/cmd probes, the earlier
+ * `${CLAUDE_PROJECT_DIR:-.}` / `%CLAUDE_PROJECT_DIR%` forms, the ADR-059
+ * `git rev-parse` node -e forms (CJS and ESM, with or without argv.splice),
+ * and plain relative paths. Returns null for anything else, so user-authored
+ * commands (other scripts, redirects, chains) are left alone.
+ */
+export declare function pinToUserHelpers(command: string, windows?: boolean): string | null;
+//# sourceMappingURL=helper-commands.d.ts.map

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

@@ -0,0 +1,142 @@
+/**
+ * Hook and statusline commands that launch the `.claude/helpers` scripts.
+ *
+ * A project-level settings.json (`<project>/.claude/settings.json`) keeps the
+ * #1943 probe: run the project's helper, fall back to `$HOME/.claude/helpers`.
+ * The project controls that settings file anyway, so preferring its helpers
+ * grants it nothing new.
+ *
+ * A user-level settings.json (`~/.claude/settings.json`) applies to every
+ * project the user opens. There the probe would let any opened project supply
+ * the helper that runs, so user-level commands are pinned to the user's own
+ * `$HOME/.claude/helpers` with no project lookup.
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+const IS_WINDOWS = process.platform === 'win32';
+const STATUSLINE_SCRIPT = '.claude/helpers/statusline.cjs';
+function canonical(dir) {
+    try {
+        return fs.realpathSync(dir);
+    }
+    catch {
+        return path.resolve(dir);
+    }
+}
+/** Settings written into the user's home directory are user-level settings. */
+export function helperScopeFor(targetDir) {
+    if (!targetDir)
+        return 'project';
+    return canonical(targetDir) === canonical(os.homedir()) ? 'user' : 'project';
+}
+/** 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})"`;
+    }
+    // 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:-.}';
+    // eslint-disable-next-line no-template-curly-in-string
+    const homeVar = '${HOME}';
+    return `sh -c 'D="${projVar}"; [ -f "$D/${script}" ] || D="${homeVar}"; exec node "$D/${script}"${arg}'`;
+}
+/** Command for the statusLine entry. */
+export function helperStatusLineCommand(scope, windows = IS_WINDOWS) {
+    if (windows) {
+        // The Node CLI's `-e` flag avoids all shell-quoting pitfalls (#1948,
+        // #1973): never `cmd /c` for statusline, it blocks stdin forwarding.
+        const home = "p.join(process.env.USERPROFILE||process.env.HOME||'.', '" + STATUSLINE_SCRIPT + "')";
+        const js = scope === 'user'
+            ? `const p=require('path');require(${home});`
+            : "const fs=require('fs'),p=require('path');" +
+                `const d=process.env.CLAUDE_PROJECT_DIR||'.';` +
+                `const f=p.join(d,'${STATUSLINE_SCRIPT}');` +
+                `const h=${home};` +
+                'require(fs.existsSync(f)?f:h);';
+        return `node -e "${js}"`;
+    }
+    if (scope === 'user')
+        return `sh -c 'exec node "\${HOME}/${STATUSLINE_SCRIPT}"'`;
+    // eslint-disable-next-line no-template-curly-in-string
+    const projVar = '${CLAUDE_PROJECT_DIR:-.}';
+    // eslint-disable-next-line no-template-curly-in-string
+    const homeVar = '${HOME}';
+    return `sh -c 'D="${projVar}"; [ -f "$D/${STATUSLINE_SCRIPT}" ] || D="${homeVar}"; exec node "$D/${STATUSLINE_SCRIPT}"'`;
+}
+// Helpers ruflo installs under .claude/helpers that settings can launch.
+const RUFLO_HELPERS = [
+    'hook-handler.cjs', 'auto-memory-hook.mjs', 'statusline.cjs', 'ruflo-hook.cjs', 'router.cjs',
+    'session.cjs', 'memory.cjs', 'intelligence.cjs', 'learning-service.mjs', 'metrics-db.mjs',
+    'context-persistence-hook.mjs',
+];
+const HELPER_REF = new RegExp(`\\.claude[\\\\/]helpers[\\\\/](${RUFLO_HELPERS.map((h) => h.replace('.', '\\.')).join('|')})`, 'g');
+// How a ruflo-generated command reached the project's copy of a helper:
+// CLAUDE_PROJECT_DIR (sh, cmd or node -e), `git rev-parse --show-toplevel`,
+// or a path relative to the cwd.
+const PROJECT_REACH = /CLAUDE_PROJECT_DIR|git rev-parse --show-toplevel/;
+const RELATIVE_REF = /(?:^|[\s"'])(?:\.[\\/])?\.claude[\\/]helpers[\\/]/;
+const SHELL_CHAINING = /&&|\|\||[;|<>`]/;
+const ARGS = /^(?: [\w:.=-]+)*$/;
+// The fixed shell scaffolding of the #1943 probes, which itself contains `;`
+// and `||`; removed before checking the rest for chaining.
+const PROBE_PREAMBLE = /D="\$\{CLAUDE_PROJECT_DIR:-\.\}"; \[ -f "\$D\/\.claude\/helpers\/[\w.-]+" \] \|\| D="\$\{HOME\}"; /;
+const IF_EXIST_PREAMBLE = /"IF EXIST "%CLAUDE_PROJECT_DIR%\\\.claude\\helpers\\[\w.-]+" \(node "%CLAUDE_PROJECT_DIR%\\\.claude\\helpers\\[\w.-]+"(?: [\w:.=-]+)*\) ELSE \(/;
+/**
+ * Rewrite a command that runs one of ruflo's helpers from the opened project
+ * into the pinned user-level form, keeping its subcommand. Covers every form
+ * ruflo has shipped: the #1943 sh/cmd probes, the earlier
+ * `${CLAUDE_PROJECT_DIR:-.}` / `%CLAUDE_PROJECT_DIR%` forms, the ADR-059
+ * `git rev-parse` node -e forms (CJS and ESM, with or without argv.splice),
+ * and plain relative paths. Returns null for anything else, so user-authored
+ * commands (other scripts, redirects, chains) are left alone.
+ */
+export function pinToUserHelpers(command, windows = IS_WINDOWS) {
+    const refs = [...command.matchAll(HELPER_REF)];
+    if (refs.length === 0)
+        return null;
+    const helper = refs[refs.length - 1][1];
+    if (refs.some((m) => m[1] !== helper))
+        return null;
+    if (!PROJECT_REACH.test(command) && !RELATIVE_REF.test(command))
+        return null;
+    let args;
+    const nodeEval = /^node -e "(.*)"((?: [\w:.=-]+)*)$/.exec(command);
+    if (nodeEval) {
+        if (!/git rev-parse --show-toplevel|CLAUDE_PROJECT_DIR/.test(nodeEval[1]))
+            return null;
+        args = nodeEval[2];
+    }
+    else {
+        if (!/^(?:sh -c '|cmd \/c |node )/.test(command))
+            return null;
+        // Drop the shell wrapper's closing quote / paren, then split around the
+        // last helper reference: the head launches it, the tail is its argv.
+        const body = command.replace(/'$/, '').replace(/\)"$/, '');
+        const last = refs[refs.length - 1];
+        const head = body.slice(0, last.index ?? 0).replace(PROBE_PREAMBLE, '').replace(IF_EXIST_PREAMBLE, '');
+        let tail = body.slice((last.index ?? 0) + last[0].length);
+        if (tail.startsWith('"'))
+            tail = tail.slice(1);
+        if (SHELL_CHAINING.test(head) || SHELL_CHAINING.test(tail))
+            return null;
+        args = tail.trimEnd();
+    }
+    if (!ARGS.test(args))
+        return null;
+    const script = `.claude/helpers/${helper}`;
+    if (helper === 'statusline.cjs' && args === '')
+        return helperStatusLineCommand('user', windows);
+    return helperHookCommand(script, args.trim(), 'user', windows);
+}
+//# sourceMappingURL=helper-commands.js.map

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

@@ -127,10 +127,52 @@ export function generateSessionManager() {
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 
 const SESSION_DIR = path.join(process.cwd(), '.claude-flow', 'sessions');
 const SESSION_FILE = path.join(SESSION_DIR, 'current.json');
 
+// Archive names are generated by start(); anything else in current.json is
+// untrusted project content and must never pick a path.
+const SESSION_ID = /^session-\\d+$/;
+
+// current.json lives in the opened project. A symlink there must never be read
+// or written through, so only a regular file counts as an active session.
+function hasSessionFile() {
+  try { return fs.lstatSync(SESSION_FILE).isFile(); } catch { return false; }
+}
+
+function archiveId(id) {
+  return SESSION_ID.test(String(id)) ? String(id) : \`session-\${Date.now()}\`;
+}
+
+// The session directory must resolve inside the project (no symlinked escape).
+function assertSessionDirContained() {
+  const root = fs.realpathSync(process.cwd());
+  // Resolve the deepest part of the path that exists (lstat: a symlink counts),
+  // so a symlinked .claude-flow is refused before anything is created under it.
+  let dir = SESSION_DIR;
+  for (;;) {
+    try { fs.lstatSync(dir); break; } catch { /* not created yet */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const rel = path.relative(root, fs.realpathSync(dir));
+  if (rel === '..' || rel.startsWith(\`..\${path.sep}\`) || path.isAbsolute(rel)) {
+    throw new Error('Session directory resolves outside the project');
+  }
+}
+
+// Exclusive temp file + rename: never writes through a planted symlink, and
+// rename() replaces a symlinked target instead of following it.
+function atomicWrite(file, data) {
+  assertSessionDirContained();
+  const tmp = \`\${file}.tmp.\${process.pid}.\${crypto.randomBytes(6).toString('hex')}\`;
+  fs.writeFileSync(tmp, data, { flag: 'wx' });
+  fs.renameSync(tmp, file);
+}
+
 const commands = {
   start: () => {
     const sessionId = \`session-\${Date.now()}\`;
@@ -147,29 +189,30 @@ const commands = {
       },
     };
 
+    assertSessionDirContained();
     fs.mkdirSync(SESSION_DIR, { recursive: true });
-    fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+    atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
 
     console.log(\`Session started: \${sessionId}\`);
     return session;
   },
 
   restore: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No session to restore');
       return null;
     }
 
     const session = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
     session.restoredAt = new Date().toISOString();
-    fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+    atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
 
     console.log(\`Session restored: \${session.id}\`);
     return session;
   },
 
   end: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No active session');
       return null;
     }
@@ -178,12 +221,12 @@ const commands = {
     session.endedAt = new Date().toISOString();
     session.duration = Date.now() - new Date(session.startedAt).getTime();
 
-    // Archive session
-    const archivePath = path.join(SESSION_DIR, \`\${session.id}.json\`);
-    fs.writeFileSync(archivePath, JSON.stringify(session, null, 2));
+    // Archive session under a validated name; a crafted id cannot pick the path.
+    const id = archiveId(session.id);
+    atomicWrite(path.join(SESSION_DIR, \`\${id}.json\`), JSON.stringify(session, null, 2));
     fs.unlinkSync(SESSION_FILE);
 
-    console.log(\`Session ended: \${session.id}\`);
+    console.log(\`Session ended: \${id}\`);
     console.log(\`Duration: \${Math.round(session.duration / 1000 / 60)} minutes\`);
     console.log(\`Metrics: \${JSON.stringify(session.metrics)}\`);
 
@@ -191,7 +234,7 @@ const commands = {
   },
 
   status: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No active session');
       return null;
     }
@@ -208,7 +251,7 @@ const commands = {
   },
 
   update: (key, value) => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No active session');
       return null;
     }
@@ -216,20 +259,20 @@ const commands = {
     const session = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
     session.context[key] = value;
     session.updatedAt = new Date().toISOString();
-    fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+    atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
 
     return session;
   },
 
   metric: (name) => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       return null;
     }
 
     const session = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
     if (session.metrics[name] !== undefined) {
       session.metrics[name]++;
-      fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+      atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
     }
 
     return session;
@@ -606,7 +649,9 @@ export function generateHookHandler() {
         'function spawnFunnelRefresh() {',
         '  try {',
         "    var cmd = process.platform === 'win32' ? 'npx.cmd' : 'npx';",
-        "    var args = ['--prefer-offline', '@claude-flow/cli', 'hooks', 'refresh-funnel', '--quiet'];",
+        // --prefix: resolve the package from this helper's install root, never
+        // from the cwd (the opened project); the CLI still runs in the project.
+        "    var args = ['--prefer-offline', '--prefix', path.resolve(helpersDir, '..', '..'), '@claude-flow/cli', 'hooks', 'refresh-funnel', '--quiet'];",
         '    var child = spawn(cmd, args, {',
         "      detached: true, stdio: 'ignore', env: Object.assign({}, process.env),",
         '    });',
@@ -1157,9 +1202,12 @@ import { fileURLToPath } from 'url';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
+// Executable modules resolve only from the helper's own install root; a
+// home-level helper can serve an untrusted project. PROJECT_ROOT is data only.
+const MODULE_ROOT = join(__dirname, '../..');
 const PROJECT_ROOT = process.env.CLAUDE_PROJECT_DIR
   ? resolve(process.env.CLAUDE_PROJECT_DIR)
-  : join(__dirname, '../..');
+  : MODULE_ROOT;
 const DATA_DIR = join(PROJECT_ROOT, '.claude-flow', 'data');
 const STORE_PATH = join(DATA_DIR, 'auto-memory-store.json');
 
@@ -1171,7 +1219,7 @@ const dim = (msg) => console.log(\`  \${DIM}\${msg}\${RESET}\`);
 // #2545: fail LOUD instead of a silent dim skip when @claude-flow/memory is
 // unresolvable — self-learning imports are a no-op and the user must be told.
 function warnMemoryUnavailable() {
-  const l1 = \`[AutoMemory] @claude-flow/memory not resolvable from \${PROJECT_ROOT} — self-learning imports are DISABLED.\`;
+  const l1 = \`[AutoMemory] @claude-flow/memory not resolvable from \${MODULE_ROOT} — self-learning imports are DISABLED.\`;
   const l2 = '             Fix: npm i -D @claude-flow/memory   (or re-run: npx ruflo@latest init, then npx ruflo@latest doctor --fix)';
   console.log(\`\${YELLOW}\${l1}\${RESET}\`);
   console.log(\`\${YELLOW}\${l2}\${RESET}\`);
@@ -1186,7 +1234,7 @@ async function loadMemoryPackage() {
   // path @claude-flow/memory lands in the npx cache (unreachable by walk-up), so
   // init records its absolute path here — the only strategy that works there.
   try {
-    const sidecar = join(PROJECT_ROOT, '.claude-flow', 'memory-package.json');
+    const sidecar = join(MODULE_ROOT, '.claude-flow', 'memory-package.json');
     if (existsSync(sidecar)) {
       const rec = JSON.parse(readFileSync(sidecar, 'utf-8'));
       if (rec && rec.distPath && existsSync(rec.distPath)) {
@@ -1199,15 +1247,15 @@ async function loadMemoryPackage() {
   // when installed as a transitive dependency via npx ruflo / npx claude-flow)
   try {
     const { createRequire } = await import('module');
-    const require = createRequire(join(PROJECT_ROOT, 'package.json'));
+    const require = createRequire(join(MODULE_ROOT, 'package.json'));
     return require('@claude-flow/memory');
   } catch { /* fall through */ }
 
   // Strategy 2: ESM import (works when @claude-flow/memory is a direct dependency)
   try { return await import('@claude-flow/memory'); } catch { /* fall through */ }
 
-  // Strategy 3: Walk up from PROJECT_ROOT looking for the package in any node_modules
-  let searchDir = PROJECT_ROOT;
+  // Strategy 3: Walk up from MODULE_ROOT looking for the package in any node_modules
+  let searchDir = MODULE_ROOT;
   const { parse } = await import('path');
   while (searchDir !== parse(searchDir).root) {
     const candidate = join(searchDir, 'node_modules', '@claude-flow', 'memory', 'dist', 'index.js');
@@ -1405,6 +1453,7 @@ export function generateCrossPlatformSessionManager() {
 
 const fs = require('fs');
 const path = require('path');
+const crypto = require('crypto');
 const os = require('os');
 
 // Platform-specific paths
@@ -1431,6 +1480,49 @@ function getDataDir() {
 const SESSION_DIR = getDataDir();
 const SESSION_FILE = path.join(SESSION_DIR, 'current.json');
 
+// Archive names are generated by start(); anything else in current.json is
+// untrusted project content and must never pick a path.
+const SESSION_ID = /^session-\\d+$/;
+
+// current.json lives in the opened project. A symlink there must never be read
+// or written through, so only a regular file counts as an active session.
+function hasSessionFile() {
+  try { return fs.lstatSync(SESSION_FILE).isFile(); } catch { return false; }
+}
+
+function archiveId(id) {
+  return SESSION_ID.test(String(id)) ? String(id) : \`session-\${Date.now()}\`;
+}
+
+// The project session directory must resolve inside the project (no
+// symlinked escape). The per-user fallback directory is not project-owned.
+function assertSessionDirContained() {
+  if (SESSION_DIR !== path.join(process.cwd(), '.claude-flow', 'sessions')) return;
+  const root = fs.realpathSync(process.cwd());
+  // Resolve the deepest part of the path that exists (lstat: a symlink counts),
+  // so a symlinked .claude-flow is refused before anything is created under it.
+  let dir = SESSION_DIR;
+  for (;;) {
+    try { fs.lstatSync(dir); break; } catch { /* not created yet */ }
+    const parent = path.dirname(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  const rel = path.relative(root, fs.realpathSync(dir));
+  if (rel === '..' || rel.startsWith(\`..\${path.sep}\`) || path.isAbsolute(rel)) {
+    throw new Error('Session directory resolves outside the project');
+  }
+}
+
+// Exclusive temp file + rename: never writes through a planted symlink, and
+// rename() replaces a symlinked target instead of following it.
+function atomicWrite(file, data) {
+  assertSessionDirContained();
+  const tmp = \`\${file}.tmp.\${process.pid}.\${crypto.randomBytes(6).toString('hex')}\`;
+  fs.writeFileSync(tmp, data, { flag: 'wx' });
+  fs.renameSync(tmp, file);
+}
+
 // Ensure directory exists
 function ensureDir(dir) {
   if (!fs.existsSync(dir)) {
@@ -1440,6 +1532,7 @@ function ensureDir(dir) {
 
 const commands = {
   start: () => {
+    assertSessionDirContained();
     ensureDir(SESSION_DIR);
     const sessionId = \`session-\${Date.now()}\`;
     const session = {
@@ -1450,25 +1543,25 @@ const commands = {
       context: {},
       metrics: { edits: 0, commands: 0, tasks: 0, errors: 0 }
     };
-    fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+    atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
     console.log(\`Session started: \${sessionId}\`);
     return session;
   },
 
   restore: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No session to restore');
       return null;
     }
     const session = JSON.parse(fs.readFileSync(SESSION_FILE, 'utf-8'));
     session.restoredAt = new Date().toISOString();
-    fs.writeFileSync(SESSION_FILE, JSON.stringify(session, null, 2));
+    atomicWrite(SESSION_FILE, JSON.stringify(session, null, 2));
     console.log(\`Session restored: \${session.id}\`);
     return session;
   },
 
   end: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No active session');
       return null;
     }
@@ -1476,17 +1569,18 @@ const commands = {
     session.endedAt = new Date().toISOString();
     session.duration = Date.now() - new Date(session.startedAt).getTime();
 
-    const archivePath = path.join(SESSION_DIR, \`\${session.id}.json\`);
-    fs.writeFileSync(archivePath, JSON.stringify(session, null, 2));
+    // Archive under a validated name; a crafted id cannot pick the path.
+    const id = archiveId(session.id);
+    atomicWrite(path.join(SESSION_DIR, \`\${id}.json\`), JSON.stringify(session, null, 2));
     fs.unlinkSync(SESSION_FILE);
 
-    console.log(\`Session ended: \${session.id}\`);
+    console.log(\`Session ended: \${id}\`);
     console.log(\`Duration: \${Math.round(session.duration / 1000 / 60)} minutes\`);
     return session;
   },
 
   status: () => {
-    if (!fs.existsSync(SESSION_FILE)) {
+    if (!hasSessionFile()) {
       console.log('No active session');
       return null;
     }
@@ -1615,6 +1709,9 @@ function resolveCommandPath(command, env = process.env, platform = process.platf
     ? (envValue(env, 'PATHEXT') || '.COM;.EXE;.BAT;.CMD').split(';')
     : [''];
   for (const dir of dirs) {
+    // A relative or empty PATH entry resolves against the cwd, i.e. the
+    // opened project; never resolve the CLI from there.
+    if (!hasSeparator && !(platform === 'win32' ? path.win32 : path.posix).isAbsolute(dir)) continue;
     for (const ext of extensions) {
       const base = path.resolve(dir || '.', command);
       const candidates = ext
@@ -1767,7 +1864,9 @@ function main() {
   // exists but cannot be resolved to an entrypoint still runs, via layer 2.
   if (resolveCommandPath('ruflo')) { invokeHook('ruflo', [], hookArgs, stdinData); done(); }
   if (resolveCommandPath('claude-flow')) { invokeHook('claude-flow', [], hookArgs, stdinData); done(); }
-  invokeHook('npx', ['--prefer-offline', '--yes', 'ruflo@latest'], hookArgs, stdinData);
+  // --prefix: npx resolves ruflo from this helper's install root, never from
+  // the cwd (the opened project); the CLI still runs in the project.
+  invokeHook('npx', ['--prefer-offline', '--yes', '--prefix', path.resolve(__dirname, '..', '..'), 'ruflo@latest'], hookArgs, stdinData);
   done();
 }