@sparkleideas/claude-flow-patch 3.1.0-alpha.44.patch.3

package/patch/270-SG-003-init-helpers-all-paths/README.md

@@ -0,0 +1,60 @@
+# SG-003: Init missing helpers for --dual, --minimal, hooks, and upgrade paths
+
+**Severity**: Critical
+**GitHub**: [#1169](https://github.com/ruvnet/claude-flow/issues/1169)
+
+## Root Cause
+
+Multiple `init` code paths generate `settings.json` (which references `hook-handler.cjs`,
+`auto-memory-hook.mjs`, `statusline.cjs`) without generating the helper files those hooks need.
+
+| Path | Generates settings? | Generates helpers? | Result |
+|------|--------------------|--------------------|--------|
+| `init` (default) | YES | YES | OK |
+| `init --dual` | NO (bypasses executeInit) | NO | Broken: no Claude infra despite CLAUDE.md |
+| `init --codex` | NO (bypasses executeInit) | NO | OK (no Claude Code expected) |
+| `init --minimal` | YES | NO (helpers: false) | Broken: dangling settings refs |
+| `init hooks` | YES | NO (helpers: false) | Broken: dangling settings refs |
+| `init upgrade` | Only with --settings | Partial (3 of 8) | Broken: missing router/session/memory |
+| `init wizard` | YES | YES (default) | OK |
+
+Additionally:
+- `helpers-generator.js` generates a `hook-handler.cjs` that hardcodes `require('router.js')`
+  instead of `require('router.cjs')`, failing when `package.json` has `"type": "module"`.
+- `executeUpgrade()` only upgrades 3 critical helpers but `hook-handler.cjs` needs 6.
+- `executeUpgrade()` fallback also only generates 3 in `generatedCritical`.
+
+## Fix
+
+7 ops across 4 files:
+
+1. **init.js** — After `--dual` codex init succeeds, call `executeInit()` with
+   all components so full Claude Code infrastructure is created.
+2. **executor.js** — When `settings` is generated but `helpers` is not, also generate
+   the critical helpers that `settings.json` references (fixes `--minimal` and `init hooks`).
+3. **executor.js** — Expand `executeUpgrade()` critical helpers list to include `router.cjs`,
+   `session.cjs`, `memory.cjs`.
+4. **helpers-generator.js** — Fix generated `hook-handler.cjs` to `require('router.cjs')`
+   instead of `require('router.js')` (same for session and memory).
+5. **hook-handler.cjs** (source template) — Fix source-shipped copy to use `.cjs` requires.
+6. **executor.js** — Expand `executeUpgrade()` fallback `generatedCritical` to include
+   `router.cjs`, `session.cjs`, `memory.cjs` when source helpers aren't found.
+7. **init.js** — Transition op: update `--dual` components from `skills: false` to `true`.
+
+## Files Patched
+
+- `commands/init.js`
+- `init/executor.js`
+- `init/helpers-generator.js`
+- `<pkg-root>/.claude/helpers/hook-handler.cjs` (source template)
+
+## Dependencies
+
+Depends on IN-001 (170) — SG-003's `old_string` contains code introduced by IN-001.
+
+## Ops
+
+7 ops (11 patch calls) in fix.py
+
+Note: .js copies of .cjs helpers are not needed. All require() paths use .cjs
+exclusively after ops d-i. The former SG-002 compat copy approach was retired.

package/patch/270-SG-003-init-helpers-all-paths/fix.py

@@ -0,0 +1,164 @@
+# SG-003: Init missing helpers for --dual, --minimal, hooks, and upgrade paths
+# GitHub: #1169
+#
+# Root cause:
+# 1. init --dual bypasses executeInit() entirely — no .claude/helpers/ created
+# 2. init --minimal and init hooks set components.helpers=false but settings=true
+#    so settings.json references helpers that don't exist
+# 3. executeUpgrade() only upgrades 3 of 8 helpers (missing router/session/memory)
+# 4. helpers-generator.js generates hook-handler.cjs with require('router.js')
+#    instead of require('router.cjs'), failing with "type":"module"
+#
+# 5 ops: dual path (init.js), settings guard (executor.js),
+#         upgrade helpers (executor.js), generated requires (helpers-generator.js),
+#         source-shipped hook-handler.cjs requires (SRC_HOOK_HANDLER)
+
+# Op 1: init --dual should also generate Claude Code infrastructure
+# After codex init succeeds, call executeInit() for helpers/settings/statusline
+patch("SG-003a: --dual also generates helpers + settings via executeInit",
+    INIT_CMD,
+    """    // If codex mode, use the Codex initializer
+    if (codexMode || dualMode) {
+        return initCodexAction(ctx, { codexMode, dualMode, force, minimal, full });
+    }""",
+    """    // If codex mode, use the Codex initializer
+    if (codexMode || dualMode) {
+        const codexResult = await initCodexAction(ctx, { codexMode, dualMode, force, minimal, full });
+        // SG-003: --dual must also create Claude Code infrastructure (.claude/helpers + settings)
+        if (dualMode) {
+            try {
+                await executeInit({
+                    ...DEFAULT_INIT_OPTIONS,
+                    targetDir: cwd,
+                    force,
+                    components: {
+                        settings: true,
+                        helpers: true,
+                        statusline: true,
+                        skills: true,
+                        commands: true,
+                        agents: true,
+                        mcp: true,
+                        runtime: false,
+                        claudeMd: false,
+                    },
+                });
+            } catch { /* non-fatal — codex init already succeeded */ }
+        }
+        return codexResult;
+    }""")
+
+# Op 2: When settings is generated but helpers component is off, still generate
+# the critical helpers that settings.json references
+patch("SG-003b: generate critical helpers when settings references them",
+    EXECUTOR,
+    """        // Generate helpers
+        if (options.components.helpers) {
+            await writeHelpers(targetDir, options, result);
+        }""",
+    """        // Generate helpers
+        if (options.components.helpers) {
+            await writeHelpers(targetDir, options, result);
+        }
+        // SG-003: If settings will be generated but helpers were skipped,
+        // generate the critical helpers that settings.json hooks reference
+        else if (options.components.settings) {
+            const hDir = path.join(targetDir, '.claude', 'helpers');
+            fs.mkdirSync(hDir, { recursive: true });
+            const criticalForSettings = {
+                'hook-handler.cjs': generateHookHandler(),
+                'auto-memory-hook.mjs': generateAutoMemoryHook(),
+            };
+            for (const [name, content] of Object.entries(criticalForSettings)) {
+                const fp = path.join(hDir, name);
+                if (!fs.existsSync(fp)) {
+                    fs.writeFileSync(fp, content, 'utf-8');
+                    try { fs.chmodSync(fp, '755'); } catch {}
+                    result.created.files.push(`.claude/helpers/${name}`);
+                }
+            }
+        }""")
+
+# Op 3: Expand executeUpgrade() critical helpers to include router/session/memory
+# and add compat-copy sweep after statusline
+patch("SG-003c: upgrade generates all helpers + compat sweep",
+    EXECUTOR,
+    """            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs'];""",
+    """            const criticalHelpers = ['auto-memory-hook.mjs', 'hook-handler.cjs', 'intelligence.cjs', 'router.cjs', 'session.cjs', 'memory.cjs'];""")
+
+# Op 4: Fix generated hook-handler.cjs to require .cjs instead of .js
+# This is the fallback generator used when source helpers aren't found
+patch_all("SG-003d: generated hook-handler requires .cjs not .js",
+    HELPERS_GEN,
+    """safeRequire(path.join(helpersDir, 'router.js'))""",
+    """safeRequire(path.join(helpersDir, 'router.cjs'))""")
+
+patch_all("SG-003e: generated hook-handler requires session.cjs",
+    HELPERS_GEN,
+    """safeRequire(path.join(helpersDir, 'session.js'))""",
+    """safeRequire(path.join(helpersDir, 'session.cjs'))""")
+
+patch_all("SG-003f: generated hook-handler requires memory.cjs",
+    HELPERS_GEN,
+    """safeRequire(path.join(helpersDir, 'memory.js'))""",
+    """safeRequire(path.join(helpersDir, 'memory.cjs'))""")
+
+# Op 5: Fix the source-shipped hook-handler.cjs (copied by writeHelpers when source found)
+# This file is at <pkg-root>/.claude/helpers/hook-handler.cjs and gets copied as-is
+patch_all("SG-003g: source hook-handler requires router.cjs",
+    SRC_HOOK_HANDLER,
+    """safeRequire(path.join(helpersDir, 'router.js'))""",
+    """safeRequire(path.join(helpersDir, 'router.cjs'))""")
+
+patch_all("SG-003h: source hook-handler requires session.cjs",
+    SRC_HOOK_HANDLER,
+    """safeRequire(path.join(helpersDir, 'session.js'))""",
+    """safeRequire(path.join(helpersDir, 'session.cjs'))""")
+
+patch_all("SG-003i: source hook-handler requires memory.cjs",
+    SRC_HOOK_HANDLER,
+    """safeRequire(path.join(helpersDir, 'memory.js'))""",
+    """safeRequire(path.join(helpersDir, 'memory.cjs'))""")
+
+# Op 6: Fix executeUpgrade() fallback — generatedCritical missing router/session/memory
+# When source helpers aren't found, only 3 files were generated but hook-handler.cjs needs 6
+patch("SG-003j: upgrade fallback generates router/session/memory",
+    EXECUTOR,
+    """            const generatedCritical = {
+                'hook-handler.cjs': generateHookHandler(),
+                'intelligence.cjs': intelligenceContent,
+                'auto-memory-hook.mjs': generateAutoMemoryHook(),
+            };""",
+    """            const generatedCritical = {
+                'hook-handler.cjs': generateHookHandler(),
+                'intelligence.cjs': intelligenceContent,
+                'auto-memory-hook.mjs': generateAutoMemoryHook(),
+                // SG-003: hook-handler.cjs requires these — generate fallback versions
+                'router.cjs': generateAgentRouter(),
+                'session.cjs': generateSessionManager(),
+                'memory.cjs': generateMemoryHelper(),
+            };""")
+
+# Transition: update caches that already have old SG-003a (skills: false) to new (skills: true)
+# On fresh cache SG-003a applies directly; this skips (new already present).
+# On pre-patched cache SG-003a warns (upstream old_string gone); this catches the delta.
+patch("SG-003l: --dual enables skills/commands/agents (transition)",
+    INIT_CMD,
+    """                        skills: false,
+                        commands: false,
+                        agents: false,
+                        mcp: true,
+                        runtime: false,
+                        claudeMd: false,
+                    },
+                });
+            } catch { /* non-fatal — codex init already succeeded */ }""",
+    """                        skills: true,
+                        commands: true,
+                        agents: true,
+                        mcp: true,
+                        runtime: false,
+                        claudeMd: false,
+                    },
+                });
+            } catch { /* non-fatal — codex init already succeeded */ }""")

package/patch/270-SG-003-init-helpers-all-paths/sentinel

@@ -0,0 +1,3 @@
+grep "SG-003" commands/init.js
+grep "SG-003" init/executor.js
+grep "router.cjs" init/helpers-generator.js

package/patch/280-UI-001-intelligence-stats-crash/README.md

@@ -0,0 +1,11 @@
+# UI-001: intelligence stats crashes on .toFixed()
+**Severity**: Critical
+**GitHub**: [#1145](https://github.com/ruvnet/claude-flow/issues/1145)
+## Root Cause
+`hooks intelligence stats` calls `.toFixed()` on potentially undefined properties (learningTimeMs, adaptationTimeMs, avgQuality, routingAccuracy, loadBalance, cacheHitRate, performance.*) without null checks. Crashes when the intelligence system returns incomplete data.
+## Fix
+Add null checks with 'N/A' fallback for all numeric display values. Wrap performance section in an `if (result.performance)` guard.
+## Files Patched
+- commands/hooks.js
+## Ops
+7 ops in fix.py

package/patch/280-UI-001-intelligence-stats-crash/fix.py

@@ -0,0 +1,57 @@
+# UI-001: intelligence stats crashes on .toFixed() of undefined
+# Absorbed from old patch-17. Applied via sed to npx cache.
+
+# SONA component null checks
+patch("17a: SONA learningTimeMs null check",
+    HOOKS_CMD,
+    "{ metric: 'Learning Time', value: `${result.components.sona.learningTimeMs.toFixed(3)}ms` }",
+    "{ metric: 'Learning Time', value: result.components.sona.learningTimeMs != null ? `${result.components.sona.learningTimeMs.toFixed(3)}ms` : 'N/A' }")
+
+patch("17b: SONA adaptationTimeMs null check",
+    HOOKS_CMD,
+    "{ metric: 'Adaptation Time', value: `${result.components.sona.adaptationTimeMs.toFixed(3)}ms` }",
+    "{ metric: 'Adaptation Time', value: result.components.sona.adaptationTimeMs != null ? `${result.components.sona.adaptationTimeMs.toFixed(3)}ms` : 'N/A' }")
+
+patch("17c: SONA avgQuality null check",
+    HOOKS_CMD,
+    "{ metric: 'Avg Quality', value: `${(result.components.sona.avgQuality * 100).toFixed(1)}%` }",
+    "{ metric: 'Avg Quality', value: result.components.sona.avgQuality != null ? `${(result.components.sona.avgQuality * 100).toFixed(1)}%` : 'N/A' }")
+
+# MoE component null checks
+patch("17d: MoE routingAccuracy null check",
+    HOOKS_CMD,
+    "{ metric: 'Routing Accuracy', value: `${(result.components.moe.routingAccuracy * 100).toFixed(1)}%` }",
+    "{ metric: 'Routing Accuracy', value: result.components.moe.routingAccuracy != null ? `${(result.components.moe.routingAccuracy * 100).toFixed(1)}%` : 'N/A' }")
+
+patch("17e: MoE loadBalance null check",
+    HOOKS_CMD,
+    "{ metric: 'Load Balance', value: `${(result.components.moe.loadBalance * 100).toFixed(1)}%` }",
+    "{ metric: 'Load Balance', value: result.components.moe.loadBalance != null ? `${(result.components.moe.loadBalance * 100).toFixed(1)}%` : 'N/A' }")
+
+# Embeddings null check
+patch("17f: embeddings cacheHitRate null check",
+    HOOKS_CMD,
+    "{ metric: 'Cache Hit Rate', value: `${(result.components.embeddings.cacheHitRate * 100).toFixed(1)}%` }",
+    "{ metric: 'Cache Hit Rate', value: result.components.embeddings.cacheHitRate != null ? `${(result.components.embeddings.cacheHitRate * 100).toFixed(1)}%` : 'N/A' }")
+
+# Performance section null guard
+patch("17g: performance section null guard",
+    HOOKS_CMD,
+    """            output.printList([
+                `Flash Attention: ${output.success(result.performance.flashAttention)}`,
+                `Memory Reduction: ${output.success(result.performance.memoryReduction)}`,
+                `Search Improvement: ${output.success(result.performance.searchImprovement)}`,
+                `Token Reduction: ${output.success(result.performance.tokenReduction)}`,
+                `SWE-Bench Score: ${output.success(result.performance.sweBenchScore)}`
+            ]);""",
+    """            if (result.performance) {
+                output.printList([
+                    `Flash Attention: ${output.success(result.performance.flashAttention || 'N/A')}`,
+                    `Memory Reduction: ${output.success(result.performance.memoryReduction || 'N/A')}`,
+                    `Search Improvement: ${output.success(result.performance.searchImprovement || 'N/A')}`,
+                    `Token Reduction: ${output.success(result.performance.tokenReduction || 'N/A')}`,
+                    `SWE-Bench Score: ${output.success(result.performance.sweBenchScore || 'N/A')}`
+                ]);
+            } else {
+                output.writeln(output.dim('  No performance data available'));
+            }""")

package/patch/280-UI-001-intelligence-stats-crash/sentinel

@@ -0,0 +1 @@
+grep "learningTimeMs != null" commands/hooks.js

package/patch/290-UI-002-neural-status-not-loaded/README.md

@@ -0,0 +1,11 @@
+# UI-002: neural status shows "Not loaded"
+**Severity**: Low (cosmetic)
+**GitHub**: [#1146](https://github.com/ruvnet/claude-flow/issues/1146)
+## Root Cause
+`neural status` reads module-level flags (`initialized`, `sonaAvailable`, `hnswIndex`) without calling their init functions. RuVector WASM, SONA Engine, and HNSW Index always show "Not loaded" even when packages are installed and working.
+## Fix
+Add `initializeTraining()` and `getHNSWIndex()` calls before reading status. Update import to include `getHNSWIndex`.
+## Files Patched
+- commands/neural.js
+## Ops
+2 ops in fix.py

package/patch/290-UI-002-neural-status-not-loaded/fix.py

@@ -0,0 +1,19 @@
+# UI-002: neural status shows "Not loaded" for installed components
+# Absorbed from old patch-18. Applied manually to npx cache.
+
+# Update import to include getHNSWIndex
+patch("18a: neural.js import getHNSWIndex",
+    NEURAL,
+    "const { getHNSWStatus, loadEmbeddingModel } = await import('../memory/memory-initializer.js');",
+    "const { getHNSWIndex, getHNSWStatus, loadEmbeddingModel } = await import('../memory/memory-initializer.js');")
+
+# Add initialization calls before status reads
+patch("18b: neural.js init before status",
+    NEURAL,
+    "            const ruvectorStats = ruvector.getTrainingStats();",
+    """            // Patch 18: Initialize RuVector WASM + SONA + HNSW so status reflects reality
+            if (!ruvector.getTrainingStats().initialized) {
+                await ruvector.initializeTraining({ useSona: true }).catch(() => {});
+            }
+            await getHNSWIndex().catch(() => null);
+            const ruvectorStats = ruvector.getTrainingStats();""")

package/patch/290-UI-002-neural-status-not-loaded/sentinel

@@ -0,0 +1 @@
+grep "getHNSWIndex" commands/neural.js

package/patch/300-DM-006-log-rotation/README.md

@@ -0,0 +1,11 @@
+# DM-006: No log rotation — headless execution logs grow unbounded
+**Severity**: Medium
+**GitHub**: [#1114](https://github.com/ruvnet/claude-flow/issues/1114)
+## Root Cause
+`logExecution()` in `headless-worker-executor.js` creates 2-3 log files per worker run (~75 KB each) but has zero cleanup. No rotation, no max file count, no TTL. At current daemon intervals this accumulates ~23 MB/day, ~702 MB/month.
+## Fix
+(A) Add `unlinkSync` and `statSync` to the ESM import. (B) Call `cleanupOldLogs()` from `ensureLogDir()` so cleanup runs on each execution cycle. (C) Add `cleanupOldLogs()` method: removes `.log` files older than 7 days or beyond a 500-file cap, keeping newest files.
+## Files Patched
+- services/headless-worker-executor.js
+## Ops
+3 ops in fix.py

package/patch/300-DM-006-log-rotation/fix.py

@@ -0,0 +1,58 @@
+# DM-006: No log rotation — headless execution logs grow unbounded
+# GitHub: #1114
+
+# A: Add unlinkSync and statSync to ESM import
+patch("DM-006a: add unlinkSync/statSync to fs import",
+    HWE,
+    "import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync } from 'fs';",
+    "import { existsSync, readFileSync, readdirSync, mkdirSync, writeFileSync, unlinkSync, statSync } from 'fs';")
+
+# B: Call cleanupOldLogs() from ensureLogDir()
+patch("DM-006b: call cleanup from ensureLogDir",
+    HWE,
+    """    ensureLogDir() {
+        try {
+            if (!existsSync(this.config.logDir)) {
+                mkdirSync(this.config.logDir, { recursive: true });
+            }
+        }
+        catch (error) {
+            this.emit('warning', { message: 'Failed to create log directory', error });
+        }
+    }""",
+    """    ensureLogDir() {
+        try {
+            if (!existsSync(this.config.logDir)) {
+                mkdirSync(this.config.logDir, { recursive: true });
+            }
+            this.cleanupOldLogs();
+        }
+        catch (error) {
+            this.emit('warning', { message: 'Failed to create log directory', error });
+        }
+    }""")
+
+# C: Add cleanupOldLogs() method before logExecution()
+patch("DM-006c: add cleanupOldLogs method",
+    HWE,
+    """    logExecution(executionId, type, content) {""",
+    """    cleanupOldLogs(maxAgeDays = 7, maxFiles = 500) {
+        try {
+            const files = readdirSync(this.config.logDir)
+                .filter(f => f.endsWith('.log'))
+                .map(f => {
+                    try { return { name: f, mtime: statSync(join(this.config.logDir, f)).mtimeMs }; }
+                    catch { return null; }
+                })
+                .filter(Boolean)
+                .sort((a, b) => b.mtime - a.mtime);
+            const cutoff = Date.now() - maxAgeDays * 86400000;
+            for (let i = 0; i < files.length; i++) {
+                if (files[i].mtime < cutoff || i >= maxFiles) {
+                    try { unlinkSync(join(this.config.logDir, files[i].name)); } catch {}
+                }
+            }
+        }
+        catch { /* ignore cleanup errors */ }
+    }
+    logExecution(executionId, type, content) {""")

package/patch/300-DM-006-log-rotation/sentinel

@@ -0,0 +1 @@
+grep "cleanupOldLogs" services/headless-worker-executor.js

package/patch/310-HW-004-runwithtimeout-orphan/README.md

@@ -0,0 +1,11 @@
+# HW-004: runWithTimeout rejects but does not kill child process
+**Severity**: Medium
+**GitHub**: [#1117](https://github.com/ruvnet/claude-flow/issues/1117)
+## Root Cause
+`runWithTimeout()` in `worker-daemon.js` has `DEFAULT_WORKER_TIMEOUT_MS = 5 * 60 * 1000` (5 min), but the headless executor's per-worker timeouts range from 5-15 minutes. When the daemon timeout fires first, the promise rejects but the underlying `claude --print` child process keeps running as an orphan until the executor's own timeout fires minutes later.
+## Fix
+Raise `DEFAULT_WORKER_TIMEOUT_MS` from 5 minutes to 16 minutes so the daemon timeout never fires before the executor's own per-worker timeout (max 15 min for audit/refactor workers). The executor handles its own child process cleanup on timeout.
+## Files Patched
+- services/worker-daemon.js
+## Ops
+1 op in fix.py

package/patch/310-HW-004-runwithtimeout-orphan/fix.py

@@ -0,0 +1,10 @@
+# HW-004: runWithTimeout rejects but does not kill child process
+# GitHub: #1117
+
+# A: Raise daemon worker timeout above max headless timeout (15 min)
+patch("HW-004a: raise worker timeout to 16 min",
+    WD,
+    """// Worker timeout (5 minutes max per worker)
+const DEFAULT_WORKER_TIMEOUT_MS = 5 * 60 * 1000;""",
+    """// Worker timeout — must exceed max headless timeout (15 min for audit/refactor)
+const DEFAULT_WORKER_TIMEOUT_MS = 16 * 60 * 1000;""")

package/patch/310-HW-004-runwithtimeout-orphan/sentinel

@@ -0,0 +1 @@
+grep "16 \* 60 \* 1000" services/worker-daemon.js

package/patch-all.sh

@@ -0,0 +1,203 @@
+#!/bin/bash
+# patch-all.sh — Orchestrator for folder-per-defect patches
+# Safe to run multiple times. Each fix.py is idempotent via patch()/patch_all().
+#
+# Usage:
+#   bash patch-all.sh [--global] [--target <dir>]
+#
+# Options:
+#   --global             Patch the npx cache (~/.npm/_npx/*)
+#   --target <dir>       Patch node_modules inside <dir>
+#
+# If neither flag is given, --global is assumed.
+
+set -euo pipefail
+
+# Parse arguments
+DO_GLOBAL=0
+TARGET_DIR=""
+while [[ $# -gt 0 ]]; do
+  case $1 in
+    --global)
+      DO_GLOBAL=1
+      shift
+      ;;
+    --target)
+      TARGET_DIR="${2:-}"
+      if [[ -z "$TARGET_DIR" ]]; then
+        echo "Error: --target requires a directory argument"
+        exit 1
+      fi
+      shift 2
+      ;;
+    -h|--help)
+      echo "Usage: patch-all.sh [--global] [--target <dir>]"
+      echo ""
+      echo "Options:"
+      echo "  --global           Patch the npx cache (~/.npm/_npx/*)"
+      echo "  --target <dir>     Patch node_modules inside <dir>"
+      echo ""
+      echo "If neither flag is given, --global is assumed."
+      exit 0
+      ;;
+    *)
+      echo "Unknown option: $1"
+      exit 1
+      ;;
+  esac
+done
+
+# Default: --global when nothing specified
+if [[ $DO_GLOBAL -eq 0 && -z "$TARGET_DIR" ]]; then
+  DO_GLOBAL=1
+fi
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+
+# ── Find installations ──
+
+# Global: npx cache
+GLOBAL_CF_BASE=""
+GLOBAL_CF_VERSION=""
+GLOBAL_RV_CLI=""
+
+if [[ $DO_GLOBAL -eq 1 ]]; then
+  GLOBAL_MEMORY=$(ls -t ~/.npm/_npx/*/node_modules/@claude-flow/cli/dist/src/memory/memory-initializer.js 2>/dev/null | head -1 || true)
+  if [ -n "$GLOBAL_MEMORY" ]; then
+    GLOBAL_CF_BASE=$(echo "$GLOBAL_MEMORY" | sed 's|/memory/memory-initializer.js||')
+    GLOBAL_CF_VERSION=$(grep -o '"version": "[^"]*"' "$GLOBAL_CF_BASE/../../package.json" 2>/dev/null | head -1 | cut -d'"' -f4 || echo "unknown")
+  fi
+  GLOBAL_RV_CLI=$(ls -t ~/.npm/_npx/*/node_modules/ruvector/bin/cli.js 2>/dev/null | head -1 || true)
+fi
+
+# Target: node_modules in specified directory
+TARGET_CF_BASE=""
+TARGET_CF_VERSION=""
+TARGET_RV_CLI=""
+
+if [[ -n "$TARGET_DIR" ]]; then
+  if [[ ! -d "$TARGET_DIR" ]]; then
+    echo "Error: target directory does not exist: $TARGET_DIR"
+    exit 1
+  fi
+  TARGET_DIR="$(cd "$TARGET_DIR" && pwd)"
+  cf_path="$TARGET_DIR/node_modules/@claude-flow/cli/dist/src"
+  if [ -d "$cf_path" ]; then
+    TARGET_CF_BASE="$cf_path"
+    TARGET_CF_VERSION=$(grep -o '"version": "[^"]*"' "$TARGET_CF_BASE/../../package.json" 2>/dev/null | head -1 | cut -d'"' -f4 || echo "unknown")
+  fi
+  rv_path="$TARGET_DIR/node_modules/ruvector/bin/cli.js"
+  if [ -f "$rv_path" ]; then
+    TARGET_RV_CLI="$(cd "$(dirname "$rv_path")" && pwd)/cli.js"
+  fi
+fi
+
+# ── Report what we found ──
+
+TARGETS=()
+if [[ $DO_GLOBAL -eq 1 ]]; then TARGETS+=(global); fi
+if [[ -n "$TARGET_DIR" ]]; then TARGETS+=("$TARGET_DIR"); fi
+echo "[PATCHES] Targets: ${TARGETS[*]}"
+echo ""
+
+if [[ $DO_GLOBAL -eq 1 ]]; then
+  if [ -n "$GLOBAL_CF_BASE" ]; then
+    echo "  Global @claude-flow/cli: v$GLOBAL_CF_VERSION"
+  else
+    echo "  Global @claude-flow/cli: not found"
+  fi
+  if [ -n "$GLOBAL_RV_CLI" ]; then
+    echo "  Global ruvector: found"
+  else
+    echo "  Global ruvector: not found"
+  fi
+fi
+
+if [[ -n "$TARGET_DIR" ]]; then
+  if [ -n "$TARGET_CF_BASE" ]; then
+    echo "  Target @claude-flow/cli: v$TARGET_CF_VERSION at $TARGET_CF_BASE"
+  else
+    echo "  Target @claude-flow/cli: not found in $TARGET_DIR"
+  fi
+  if [ -n "$TARGET_RV_CLI" ]; then
+    echo "  Target ruvector: found at $TARGET_RV_CLI"
+  else
+    echo "  Target ruvector: not found in $TARGET_DIR"
+  fi
+fi
+
+echo ""
+
+# ── Apply patches function ──
+
+apply_patches() {
+  local base="$1"
+  local ruvector_cli="$2"
+  local label="$3"
+
+  if [ -z "$base" ] && [ -z "$ruvector_cli" ]; then
+    echo "[$label] No packages found, skipping"
+    return
+  fi
+
+  if [ -n "$base" ]; then
+    echo "[$label] Patching @claude-flow/cli at: $base"
+  fi
+  if [ -n "$ruvector_cli" ]; then
+    echo "[$label] Patching ruvector at: $ruvector_cli"
+  fi
+
+  export BASE="${base:-/dev/null}"
+  export RUVECTOR_CLI="$ruvector_cli"
+
+  # Dynamic discovery: concatenate common.py + all fix.py files sorted alphabetically.
+  # Alphabetical order preserves dependencies (e.g. NS-001 < NS-002 < NS-003).
+  #
+  # PATCH_INCLUDE / PATCH_EXCLUDE env vars filter by directory name regex.
+  python3 <(
+    cat "$SCRIPT_DIR/lib/common.py"
+
+    for fix in "$SCRIPT_DIR"/patch/*/fix.py; do
+      [ -f "$fix" ] || continue
+      dirname=$(basename "$(dirname "$fix")")
+      matchname="${dirname#[0-9][0-9][0-9]-}"   # strip NNN- prefix for pattern matching
+      if [ -n "${PATCH_INCLUDE:-}" ] && ! echo "$matchname" | grep -qE "$PATCH_INCLUDE"; then
+        continue
+      fi
+      if [ -n "${PATCH_EXCLUDE:-}" ] && echo "$matchname" | grep -qE "$PATCH_EXCLUDE"; then
+        continue
+      fi
+      cat "$fix"
+    done
+
+    echo "print(f\"[$label] Done: {applied} applied, {skipped} already present\")"
+  )
+
+  # Shell-based patches (e.g. EM-002: transformers cache permissions)
+  for fix in "$SCRIPT_DIR"/patch/*/fix.sh; do
+    [ -f "$fix" ] || continue
+    dirname=$(basename "$(dirname "$fix")")
+    matchname="${dirname#[0-9][0-9][0-9]-}"   # strip NNN- prefix for pattern matching
+    if [ -n "${PATCH_INCLUDE:-}" ] && ! echo "$matchname" | grep -qE "$PATCH_INCLUDE"; then
+      continue
+    fi
+    if [ -n "${PATCH_EXCLUDE:-}" ] && echo "$matchname" | grep -qE "$PATCH_EXCLUDE"; then
+      continue
+    fi
+    bash "$fix" 2>/dev/null || true
+  done
+
+  echo ""
+}
+
+# ── Apply based on flags ──
+
+if [[ $DO_GLOBAL -eq 1 ]]; then
+  apply_patches "$GLOBAL_CF_BASE" "$GLOBAL_RV_CLI" "GLOBAL"
+fi
+
+if [[ -n "$TARGET_DIR" ]]; then
+  apply_patches "$TARGET_CF_BASE" "$TARGET_RV_CLI" "TARGET"
+fi
+
+echo "[PATCHES] Complete"