π The original agent harness. Deploy intelligent multi-player swarms, coordinate autonomous workflows, and build conversational AI systems. Features adaptive memory, self-learning intelligence, federation, vector RAG integration, and native Claude Code / Codex / Hermes and many more Integrated
TypeScript agentic-aiagentic-frameworkagentic-workflowagentsai-agentsai-assistantai-skillsautonomous-agentsclaudecodexdsh-pluginharnessmcp-servermulti-agentmulti-agent-systemsnpmskillsswarmswarm-intelligencetypescript
fix(hooks): harden memory/hook helpers (timeout, signals, truncation, cross-platform slug)
tjaiyencb1e93e8dba6
diff --git a/.claude/helpers/auto-memory-hook.mjs b/.claude/helpers/auto-memory-hook.mjsindex ff45ea468f..7eac928a54 100644--- a/.claude/helpers/auto-memory-hook.mjs+++ b/.claude/helpers/auto-memory-hook.mjs@@ -31,6 +31,27 @@ const log = (msg) => console.log(`${CYAN}[AutoMemory] ${msg}${RESET}`);const success = (msg) => console.log(`${GREEN}[AutoMemory] β ${msg}${RESET}`);const dim = (msg) => console.log(` ${DIM}${msg}${RESET}`);+const DEBUG = !!(process.env.RUFLO_DEBUG || process.env.DEBUG);++// ββ Graceful shutdown (FIX 3) βββββββββββββββββββββββββββββββββββββββββββββββ+// Track the backend currently in use so a SIGTERM/SIGINT mid-run can still+// flush it (the JSON backend persists, a SQLite-backed one closes/flushes WAL)+// instead of leaving a half-written store or a stale lock behind.+let activeBackend = null;+let shuttingDown = false;+function trackBackend(b) { activeBackend = b; return b; }+async function gracefulExit(signal) {+ if (shuttingDown) return;+ shuttingDown = true;+ if (DEBUG) process.stderr.write(`[AutoMemory] received ${signal}, flushing backend before exit\n`);+ try {+ if (activeBackend && typeof activeBackend.shutdown === 'function') await activeBackend.shutdown();+ } catch { /* best effort β never block exit on cleanup */ }+ process.exit(0);+}+process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });+process.on('SIGINT', () => { gracefulExit('SIGINT'); });+// Ensure data dirif (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });@@ -219,7 +240,7 @@ async function doImport() {}const config = readConfig();- const backend = new JsonFileBackend(STORE_PATH);+ const backend = trackBackend(new JsonFileBackend(STORE_PATH));await backend.initialize();const bridgeConfig = {@@ -302,7 +323,7 @@ async function doSync() {}const config = readConfig();- const backend = new JsonFileBackend(STORE_PATH);+ const backend = trackBackend(new JsonFileBackend(STORE_PATH));await backend.initialize();const entryCount = await backend.count();@@ -542,9 +563,17 @@ async function doImportAll() {const command = process.argv[2] || 'status';-// Suppress unhandled rejection warnings from dynamic import() failures-// which can cause non-zero exit codes even when caught-process.on('unhandledRejection', () => {});+// Dynamic import() failures can surface as unhandled rejections on a later+// microtask even when the awaiting call site already caught them, which would+// otherwise force a non-zero exit. Swallow to keep hooks exit-0, but surface the+// reason under RUFLO_DEBUG/DEBUG so genuine async bugs aren't silently hidden+// (FIX 2 β the previous `() => {}` discarded every rejection process-wide).+process.on('unhandledRejection', (reason) => {+ if (DEBUG) {+ const detail = reason && reason.message ? reason.message : String(reason);+ process.stderr.write(`[AutoMemory] unhandledRejection (suppressed): ${detail}\n`);+ }+});try {switch (command) {diff --git a/.claude/helpers/context-persistence-hook.mjs b/.claude/helpers/context-persistence-hook.mjsindex fac133328a..c5eebfcfc9 100644--- a/.claude/helpers/context-persistence-hook.mjs+++ b/.claude/helpers/context-persistence-hook.mjs@@ -59,6 +59,28 @@ const AUTOPILOT_STATE_PATH = join(DATA_DIR, 'autopilot-state.json');// Approximate tokens per character (Claude averages ~3.5 chars per token)const CHARS_PER_TOKEN = 3.5;+const DEBUG = !!(process.env.RUFLO_DEBUG || process.env.DEBUG);++// ββ Graceful shutdown (FIX 3) βββββββββββββββββββββββββββββββββββββββββββββββ+// The active backend is created mid-handler and closed at the end. SQLite holds+// a native handle and a WAL; if a SIGTERM/SIGINT arrives between creation and+// `backend.shutdown()`, that close is skipped β risking an unflushed WAL or a+// stale lock file. Track the active backend and flush it on signal before exit.+let activeBackend = null;+let shuttingDown = false;+function trackBackend(b) { activeBackend = b; return b; }+async function gracefulExit(signal) {+ if (shuttingDown) return;+ shuttingDown = true;+ if (DEBUG) process.stderr.write(`[ContextPersistence] received ${signal}, flushing backend before exit\n`);+ try {+ if (activeBackend && typeof activeBackend.shutdown === 'function') await activeBackend.shutdown();+ } catch { /* best effort β never block exit on cleanup */ }+ process.exit(0);+}+process.on('SIGTERM', () => { gracefulExit('SIGTERM'); });+process.on('SIGINT', () => { gracefulExit('SIGINT'); });+// Ensure data dirif (!existsSync(DATA_DIR)) mkdirSync(DATA_DIR, { recursive: true });@@ -714,7 +736,7 @@ async function resolveBackend() {try {const backend = new SQLiteBackend(ARCHIVE_DB_PATH);await backend.initialize();- return { backend, type: 'sqlite' };+ return { backend: trackBackend(backend), type: 'sqlite' };} catch { /* fall through */ }// Tier 2: RuVector PostgreSQL (TB-scale, vector search, GNN)@@ -723,7 +745,7 @@ async function resolveBackend() {if (rvConfig) {const backend = new RuVectorBackend(rvConfig);await backend.initialize();- return { backend, type: 'ruvector' };+ return { backend: trackBackend(backend), type: 'ruvector' };}} catch { /* fall through */ }@@ -739,14 +761,14 @@ async function resolveBackend() {if (memPkg?.AgentDBBackend) {const backend = new memPkg.AgentDBBackend();await backend.initialize();- return { backend, type: 'agentdb' };+ return { backend: trackBackend(backend), type: 'agentdb' };}} catch { /* fall through */ }// Tier 4: JSON file (always works)const backend = new JsonFileBackend(ARCHIVE_JSON_PATH);await backend.initialize();- return { backend, type: 'json' };+ return { backend: trackBackend(backend), type: 'json' };}// ============================================================================diff --git a/.claude/helpers/hook-handler.cjs b/.claude/helpers/hook-handler.cjsindex 93a3e6312b..4a94838bc5 100644--- a/.claude/helpers/hook-handler.cjs+++ b/.claude/helpers/hook-handler.cjs@@ -37,20 +37,35 @@ const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));// ββ Intelligence timeout protection (fixes #1530, #1531) βββββββββββββββββββvar INTELLIGENCE_TIMEOUT_MS = 3000;+// Race the (possibly-async) work against a real timeout.+//+// The previous implementation called `fn()` and then `clearTimeout(timer)`+// immediately β but if `fn()` returns a *pending* promise (async work), the+// timer was cancelled before the work settled and the promise resolved with the+// still-pending promise, so the timeout protected nothing. This version only+// settles when the work resolves OR the timeout fires, whichever comes first,+// and clears the timer afterwards.+//+// LIMITATION (be honest): a *synchronous* CPU-bound `fn` (e.g. the current+// intelligence.init(), which does blocking fs reads) cannot be interrupted by+// any in-process timer β the event loop is blocked, so the timeout callback+// can't run until `fn` already returned. The real guard for that case lives in+// intelligence.cjs (MAX_DATA_FILE_SIZE / MAX_GRAPH_NODES caps). This util only+// bounds work that yields to the event loop (async I/O, dynamic import, etc.).function runWithTimeout(fn, label) {- return new Promise(function(resolve) {- var timer = setTimeout(function() {+ var timer;+ var timeout = new Promise(function(resolve) {+ timer = setTimeout(function() {process.stderr.write("[WARN] " + label + " timed out after " + INTELLIGENCE_TIMEOUT_MS + "ms, skipping\n");resolve(null);}, INTELLIGENCE_TIMEOUT_MS);- try {- var result = fn();- clearTimeout(timer);- resolve(result);- } catch (e) {- clearTimeout(timer);- resolve(null);- }+ });+ // Promise.resolve().then(fn) turns a synchronous throw into a rejection so it+ // is handled here rather than escaping the Promise constructor.+ var work = Promise.resolve().then(fn).catch(function() { return null; });+ return Promise.race([work, timeout]).then(function(result) {+ clearTimeout(timer);+ return result;});}@@ -261,9 +276,16 @@ if (command && handlers[command]) {}}-main().catch(function(e) {- console.log('[WARN] Hook handler error: ' + e.message);-}).finally(function() {- // Ensure clean exit for Claude Code hooks- process.exit(0);-});+// Only dispatch hooks when run directly (node hook-handler.cjs ...). When+// require()'d by a test, just expose the internals so they can be unit-tested+// without triggering stdin reads / process.exit.+if (require.main === module) {+ main().catch(function(e) {+ console.log('[WARN] Hook handler error: ' + e.message);+ }).finally(function() {+ // Ensure clean exit for Claude Code hooks+ process.exit(0);+ });+}++module.exports = { runWithTimeout: runWithTimeout, INTELLIGENCE_TIMEOUT_MS: INTELLIGENCE_TIMEOUT_MS };diff --git a/.claude/helpers/intelligence.cjs b/.claude/helpers/intelligence.cjsindex 375fca07e9..d252ab953a 100644--- a/.claude/helpers/intelligence.cjs+++ b/.claude/helpers/intelligence.cjs@@ -56,6 +56,21 @@ function tokenize(text) {return text.toLowerCase().replace(/[^a-z0-9\s]/g, " ").split(/\s+/).filter(function(w) { return w.length > 2; });}+// ββ Truncation transparency (FIX 4) βββββββββββββββββββββββββββββββββββββββββ+// Silently severing stored values means later reasoning can be built on+// incomplete text. Warn (debug-gated) and mark the cut point with an ellipsis+// so it is visible that the value was clipped.+var DEBUG = !!(process.env.RUFLO_DEBUG || process.env.DEBUG);+function clip(text, max, label) {+ text = text == null ? "" : String(text);+ if (text.length <= max) return text;+ if (DEBUG) {+ process.stderr.write("[INTELLIGENCE] WARN: truncated " + (label || "value") ++ " from " + text.length + " to " + max + " chars\n");+ }+ return text.slice(0, max - 1) + "β¦";+}+// ββ Deduplication helper (fixes #1518) ββββββββββββββββββββββββββββββββββββββfunction deduplicateById(entries) {if (!entries || !Array.isArray(entries)) return entries;@@ -73,8 +88,14 @@ function deduplicateById(entries) {function bootstrapFromMemoryFiles() {var entries = [];- // Scope to current project only (not all 51+ project dirs)- var projectSlug = process.cwd().replace(/^\//, '').replace(/\//g, '-');+ // Scope to current project only (not all 51+ project dirs).+ // Match Claude Code's project-dir slug convention: every non-alphanumeric char+ // becomes '-' (e.g. "G:\\My Drive\\TJ_Vault" -> "G--My-Drive-TJ-Vault"). The old+ // version only stripped a leading '/' and replaced '/', so on Windows the slug+ // kept ':' and '\\' and never matched the real ~/.claude/projects/<slug> dir β+ // memory bootstrap then silently found nothing (FIX 5). Runs are NOT collapsed:+ // Claude emits "G--My" because ':' and '\\' each map to their own '-'.+ var projectSlug = process.cwd().replace(/[^a-zA-Z0-9]/g, '-');var candidates = [path.join(os.homedir(), ".claude", "projects", projectSlug, "memory"),path.join(process.cwd(), ".claude-flow", "memory"),@@ -101,14 +122,15 @@ function bootstrapFromMemoryFiles() {for (var s = 0; s < sections.length; s++) {var lines = sections[s].split("\n");var title = lines[0] ? lines[0].trim() : "section-" + s;+ var clippedContent = clip(sections[s], 500, "memory content");entries.push({id: "mem-" + entries.length,- content: sections[s].substring(0, 500),- summary: title.substring(0, 100),+ content: clippedContent,+ summary: clip(title, 100, "memory summary"),category: "memory",confidence: 0.5,sourceFile: files[k],- words: tokenize(sections[s].substring(0, 500)),+ words: tokenize(clippedContent),});}} catch (e) { /* skip */ }diff --git a/tests/hook-handler-runwithtimeout.test.cjs b/tests/hook-handler-runwithtimeout.test.cjsnew file mode 100644index 0000000000..7a3dfecff6--- /dev/null+++ b/tests/hook-handler-runwithtimeout.test.cjs@@ -0,0 +1,56 @@+'use strict';+/**+ * Unit tests for hook-handler.cjs runWithTimeout (FIX 1).+ *+ * The previous implementation called fn() and clearTimeout(timer) immediately,+ * so an async fn returned a *pending* promise that resolved through the race β+ * the timeout never fired. The "times out a slow async fn" case below fails+ * against the old code (it would return 'late') and passes against the fix.+ *+ * Uses node:test (built-in) so it runs without installing dependencies.+ */+const test = require('node:test');+const assert = require('node:assert/strict');+const path = require('path');++const { runWithTimeout, INTELLIGENCE_TIMEOUT_MS } = require(+ path.join(__dirname, '..', '.claude', 'helpers', 'hook-handler.cjs')+);++test('returns the value for a fast async fn', async () => {+ const r = await runWithTimeout(() => Promise.resolve(42), 'fast-async');+ assert.equal(r, 42);+});++test('returns the value for a fast sync fn', async () => {+ const r = await runWithTimeout(() => 7, 'fast-sync');+ assert.equal(r, 7);+});++test('resolves null (never rejects) when fn throws synchronously', async () => {+ const r = await runWithTimeout(() => { throw new Error('boom'); }, 'sync-throw');+ assert.equal(r, null);+});++test('resolves null (never rejects) when an async fn rejects', async () => {+ const r = await runWithTimeout(() => Promise.reject(new Error('boom')), 'async-reject');+ assert.equal(r, null);+});++test('times out a slow async fn and resolves null near the timeout', { timeout: 8000 }, async () => {+ const start = Date.now();+ const r = await runWithTimeout(+ () => new Promise((res) => {+ // .unref() so the dangling timer never keeps the test process alive+ const t = setTimeout(() => res('late'), INTELLIGENCE_TIMEOUT_MS + 2000);+ if (t.unref) t.unref();+ }),+ 'slow-async'+ );+ const elapsed = Date.now() - start;+ assert.equal(r, null, "should time out to null, not return the late value");+ assert.ok(+ elapsed >= INTELLIGENCE_TIMEOUT_MS - 200 && elapsed < INTELLIGENCE_TIMEOUT_MS + 1500,+ `should resolve near the ${INTELLIGENCE_TIMEOUT_MS}ms timeout, took ${elapsed}ms`+ );+});diff --git a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjsindex 7d1bf7f65a..73cfee5f4b 100644--- a/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs+++ b/v3/@claude-flow/cli/.claude/helpers/hook-handler.cjs@@ -49,23 +49,27 @@ const intelligence = safeRequire(path.join(helpersDir, 'intelligence.cjs'));// ββ Intelligence timeout protection (fixes #1530, #1531) βββββββββββββββββββconst INTELLIGENCE_TIMEOUT_MS = 3000;+// Race the (possibly-async) work against a real timeout. The previous version+// called fn() and clearTimeout(timer) immediately, so an async fn returned a+// pending promise that resolved THROUGH the race β the timeout protected+// nothing. This settles on whichever finishes first, then clears the timer.+//+// LIMITATION: a synchronous blocking fn (the current intelligence.init() does+// blocking fs reads) cannot be interrupted by any in-process timer β the event+// loop is blocked. The real guard for that case is the readJSON file-size+// limit in intelligence.cjs. This util only bounds work that yields (async I/O).function runWithTimeout(fn, label) {- // For synchronous blocking calls, we use a global safety timer.- // The readJSON file-size guard prevents loading huge files, but this- // is an additional safety net.- return new Promise((resolve) => {- const timer = setTimeout(() => {+ let timer;+ const timeout = new Promise((resolve) => {+ timer = setTimeout(() => {process.stderr.write("[WARN] " + label + " timed out after " + INTELLIGENCE_TIMEOUT_MS + "ms, skipping\n");resolve(null);}, INTELLIGENCE_TIMEOUT_MS);- try {- const result = fn();- clearTimeout(timer);- resolve(result);- } catch (e) {- clearTimeout(timer);- resolve(null);- }+ });+ const work = Promise.resolve().then(fn).catch(() => null);+ return Promise.race([work, timeout]).then((result) => {+ clearTimeout(timer);+ return result;});}