claude-flow 3.71.3 → 3.72.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (86) hide show
  1. package/.claude/helpers/auto-memory-hook.mjs +17 -0
  2. package/.claude/helpers/hook-handler.cjs +23 -10
  3. package/.claude/helpers/intelligence.cjs +23 -1
  4. package/.claude/helpers/statusline.cjs +29 -14
  5. package/.claude/proven-config.json +1 -1
  6. package/README.md +18 -3
  7. package/README.zh-CN.md +16 -3
  8. package/package.json +1 -1
  9. package/v3/@claude-flow/cli/README.md +18 -3
  10. package/v3/@claude-flow/cli/bin/cli.js +13 -18
  11. package/v3/@claude-flow/cli/bin/mcp-server.js +13 -18
  12. package/v3/@claude-flow/cli/catalog-manifest.json +2 -2
  13. package/v3/@claude-flow/cli/dist/src/appliance/rvfa-distribution.js +2 -2
  14. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-critic.d.ts +1 -7
  15. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-critic.js +1 -7
  16. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-decomposer.d.ts +1 -8
  17. package/v3/@claude-flow/cli/dist/src/benchmarks/gaia-decomposer.js +1 -8
  18. package/v3/@claude-flow/cli/dist/src/commands/agent-wasm.js +2 -2
  19. package/v3/@claude-flow/cli/dist/src/commands/analyze.js +1 -1
  20. package/v3/@claude-flow/cli/dist/src/commands/daemon.js +1 -1
  21. package/v3/@claude-flow/cli/dist/src/commands/doctor.js +3 -2
  22. package/v3/@claude-flow/cli/dist/src/commands/guidance.js +9 -9
  23. package/v3/@claude-flow/cli/dist/src/commands/hooks.js +13 -8
  24. package/v3/@claude-flow/cli/dist/src/commands/init.js +14 -16
  25. package/v3/@claude-flow/cli/dist/src/commands/memory.js +4 -3
  26. package/v3/@claude-flow/cli/dist/src/commands/neural.js +8 -6
  27. package/v3/@claude-flow/cli/dist/src/commands/route.js +1 -1
  28. package/v3/@claude-flow/cli/dist/src/commands/ruvector/backup.js +7 -5
  29. package/v3/@claude-flow/cli/dist/src/commands/ruvector/benchmark.js +6 -1
  30. package/v3/@claude-flow/cli/dist/src/commands/ruvector/import.js +19 -5
  31. package/v3/@claude-flow/cli/dist/src/commands/ruvector/init.js +1 -1
  32. package/v3/@claude-flow/cli/dist/src/commands/start.js +1 -1
  33. package/v3/@claude-flow/cli/dist/src/commands/status.js +1 -1
  34. package/v3/@claude-flow/cli/dist/src/commands/task.js +18 -1
  35. package/v3/@claude-flow/cli/dist/src/commands/update.js +1 -1
  36. package/v3/@claude-flow/cli/dist/src/funnel/local-signals.js +7 -2
  37. package/v3/@claude-flow/cli/dist/src/init/helpers-generator.js +16 -1
  38. package/v3/@claude-flow/cli/dist/src/mcp-protocol.d.ts +90 -0
  39. package/v3/@claude-flow/cli/dist/src/mcp-protocol.js +179 -0
  40. package/v3/@claude-flow/cli/dist/src/mcp-server.d.ts +1 -0
  41. package/v3/@claude-flow/cli/dist/src/mcp-server.js +20 -22
  42. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-execute-core.js +9 -1
  43. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.d.ts +13 -0
  44. package/v3/@claude-flow/cli/dist/src/mcp-tools/agent-tools.js +63 -12
  45. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-federation.d.ts +18 -1
  46. package/v3/@claude-flow/cli/dist/src/mcp-tools/agentbbs-federation.js +23 -7
  47. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-argv.d.ts +27 -0
  48. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-argv.js +92 -0
  49. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-session-tools.js +4 -0
  50. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-tools.d.ts +1 -1
  51. package/v3/@claude-flow/cli/dist/src/mcp-tools/browser-tools.js +25 -8
  52. package/v3/@claude-flow/cli/dist/src/mcp-tools/coordination-tools.js +5 -4
  53. package/v3/@claude-flow/cli/dist/src/mcp-tools/embeddings-tools.js +12 -4
  54. package/v3/@claude-flow/cli/dist/src/mcp-tools/glob-exclusions.d.ts +6 -0
  55. package/v3/@claude-flow/cli/dist/src/mcp-tools/glob-exclusions.js +81 -0
  56. package/v3/@claude-flow/cli/dist/src/mcp-tools/hive-mind-tools.js +104 -35
  57. package/v3/@claude-flow/cli/dist/src/mcp-tools/hooks-tools.js +12 -5
  58. package/v3/@claude-flow/cli/dist/src/mcp-tools/import-limits.d.ts +4 -0
  59. package/v3/@claude-flow/cli/dist/src/mcp-tools/import-limits.js +28 -0
  60. package/v3/@claude-flow/cli/dist/src/mcp-tools/memory-tools.js +68 -72
  61. package/v3/@claude-flow/cli/dist/src/mcp-tools/neural-tools.js +8 -2
  62. package/v3/@claude-flow/cli/dist/src/mcp-tools/path-containment.d.ts +34 -0
  63. package/v3/@claude-flow/cli/dist/src/mcp-tools/path-containment.js +133 -0
  64. package/v3/@claude-flow/cli/dist/src/mcp-tools/performance-tools.js +7 -2
  65. package/v3/@claude-flow/cli/dist/src/mcp-tools/record-store.d.ts +15 -0
  66. package/v3/@claude-flow/cli/dist/src/mcp-tools/record-store.js +117 -3
  67. package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.d.ts +9 -0
  68. package/v3/@claude-flow/cli/dist/src/mcp-tools/security-tools.js +39 -3
  69. package/v3/@claude-flow/cli/dist/src/mcp-tools/session-tools.js +9 -41
  70. package/v3/@claude-flow/cli/dist/src/mcp-tools/swarm-tools.js +36 -14
  71. package/v3/@claude-flow/cli/dist/src/mcp-tools/task-tools.js +68 -5
  72. package/v3/@claude-flow/cli/dist/src/mcp-tools/terminal-tools.js +16 -2
  73. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.d.ts +2 -0
  74. package/v3/@claude-flow/cli/dist/src/mcp-tools/validate-input.js +14 -0
  75. package/v3/@claude-flow/cli/dist/src/mcp-tools/workflow-tools.js +13 -12
  76. package/v3/@claude-flow/cli/dist/src/mcp-tools/x-federation-join.js +55 -14
  77. package/v3/@claude-flow/cli/dist/src/memory/intelligence.d.ts +11 -0
  78. package/v3/@claude-flow/cli/dist/src/memory/intelligence.js +84 -6
  79. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.d.ts +6 -2
  80. package/v3/@claude-flow/cli/dist/src/memory/memory-initializer.js +15 -6
  81. package/v3/@claude-flow/cli/dist/src/ruvector/model-router.d.ts +6 -1
  82. package/v3/@claude-flow/cli/dist/src/ruvector/model-router.js +16 -4
  83. package/v3/@claude-flow/cli/dist/src/services/worker-daemon.js +30 -12
  84. package/v3/@claude-flow/cli/dist/src/transfer/storage/gcs.js +3 -2
  85. package/v3/@claude-flow/cli/package.json +1 -1
  86. package/.claude/security-scans/scan-all-quick.json +0 -201
@@ -93,6 +93,37 @@ function releaseAgents(agentIds, taskId) {
93
93
  }
94
94
  });
95
95
  }
96
+ /**
97
+ * Stores `task_assign` may bind an agent from.
98
+ *
99
+ * The canonical file is `.claude-flow/agents/store.json`. `hive-mind_spawn`
100
+ * writes its workers to `.claude-flow/agents.json` instead (#1916), so an id
101
+ * that exists in either store is a real agent. A corrupt canonical store
102
+ * throws, matching the read this handler already performed, so a bad file is
103
+ * never replaced. The hive file stays best-effort: a corrupt copy must not
104
+ * hide agents that are present in the canonical store.
105
+ */
106
+ function assignableAgentStores() {
107
+ const canonical = readRecordStore(join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json'), 'agents', () => ({ agents: {} }));
108
+ const stores = [canonical.agents];
109
+ const hivePath = join(getProjectCwd(), STORAGE_DIR, 'agents.json');
110
+ try {
111
+ if (!existsSync(hivePath))
112
+ return stores;
113
+ const parsed = JSON.parse(readFileSync(hivePath, 'utf-8'));
114
+ const agents = parsed?.agents;
115
+ if (agents && typeof agents === 'object' && !Array.isArray(agents)) {
116
+ stores.push(agents);
117
+ }
118
+ }
119
+ catch {
120
+ // Best-effort, same as updateAgents.
121
+ }
122
+ return stores;
123
+ }
124
+ function agentIsAssignable(id, stores) {
125
+ return stores.some((agents) => Object.prototype.hasOwnProperty.call(agents, id) && Boolean(agents[id]));
126
+ }
96
127
  export const taskTools = [
97
128
  {
98
129
  name: 'task_create',
@@ -450,10 +481,20 @@ export const taskTools = [
450
481
  if (!task) {
451
482
  return { taskId, error: 'Task not found' };
452
483
  }
484
+ // Completed and cancelled tasks are terminal (#4725). Assigning a
485
+ // completed task marks the agent busy, and task_complete then returns
486
+ // without releasing it; task_cancel refuses a finished task too, so
487
+ // nothing ever sets that agent back to idle.
488
+ if (task.status === 'completed' || task.status === 'cancelled') {
489
+ return {
490
+ success: false,
491
+ taskId,
492
+ status: task.status,
493
+ error: `Cannot assign a ${task.status} task`,
494
+ };
495
+ }
453
496
  const previouslyAssigned = [...task.assignedTo];
454
- // Load agent store to sync worker state
455
- const agentStorePath = join(getProjectCwd(), STORAGE_DIR, 'agents', 'store.json');
456
- readRecordStore(agentStorePath, 'agents', () => ({ agents: {} }));
497
+ const agentStores = assignableAgentStores();
457
498
  if (input.unassign) {
458
499
  // Revert previously assigned agents to idle
459
500
  releaseAgents(previouslyAssigned, taskId);
@@ -461,6 +502,20 @@ export const taskTools = [
461
502
  }
462
503
  else {
463
504
  const agentIds = input.agentIds || [];
505
+ // An id in neither store is a ghost owner: the task would go
506
+ // in_progress with nobody to do the work (#4725).
507
+ if (Array.isArray(agentIds)) {
508
+ const missing = agentIds.filter((id) => typeof id === 'string' && !agentIsAssignable(id, agentStores));
509
+ if (missing.length > 0) {
510
+ const listed = missing.join(', ');
511
+ return {
512
+ success: false,
513
+ taskId,
514
+ status: task.status,
515
+ error: missing.length === 1 ? `Agent not found: ${listed}` : `Agents not found: ${listed}`,
516
+ };
517
+ }
518
+ }
464
519
  // Revert old agents to idle
465
520
  releaseAgents(previouslyAssigned.filter((id) => !agentIds.includes(id)), taskId);
466
521
  // Set new agents to active
@@ -569,21 +624,29 @@ export const taskTools = [
569
624
  const original = store.tasks[taskId];
570
625
  if (!original)
571
626
  return { success: false, taskId, error: 'Task not found' };
627
+ const retainState = input.resetState === false;
572
628
  const newTaskId = `task-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
573
- store.tasks[newTaskId] = {
629
+ const retry = {
574
630
  taskId: newTaskId,
575
631
  type: original.type,
576
632
  description: original.description,
577
633
  priority: original.priority,
578
634
  status: 'pending',
579
- progress: 0,
635
+ progress: retainState ? original.progress ?? 0 : 0,
580
636
  assignedTo: [...original.assignedTo],
581
637
  tags: [...original.tags, 'retry-of:' + taskId],
582
638
  createdAt: new Date().toISOString(),
583
639
  startedAt: null,
584
640
  completedAt: null,
585
641
  };
642
+ if (retainState && original.result !== undefined)
643
+ retry.result = original.result;
644
+ store.tasks[newTaskId] = retry;
586
645
  saveTaskStore(store);
646
+ updateAgents(retry.assignedTo, (agent) => {
647
+ agent.status = 'busy';
648
+ agent.currentTask = newTaskId;
649
+ });
587
650
  return {
588
651
  taskId,
589
652
  newTaskId,
@@ -4,6 +4,7 @@
4
4
  * Terminal session management with real command execution.
5
5
  */
6
6
  import { getProjectCwd } from './types.js';
7
+ import { nullPrototypeRecords } from './record-store.js';
7
8
  import { existsSync } from 'node:fs';
8
9
  import { mkdirRestricted, readFileMaybeEncrypted, writeFileRestricted, } from '../fs-secure.js';
9
10
  import { validateEnv, validateIdentifier, validatePath, validateText } from './validate-input.js';
@@ -33,13 +34,17 @@ function loadTerminalStore() {
33
34
  // ADR-096 Phase 3: readFileMaybeEncrypted handles both legacy
34
35
  // plaintext stores and post-migration encrypted ones via the RFE1
35
36
  // magic-byte sniff.
36
- return JSON.parse(readFileMaybeEncrypted(path, 'utf-8'));
37
+ const parsed = JSON.parse(readFileMaybeEncrypted(path, 'utf-8'));
38
+ if (parsed && typeof parsed === 'object' && !Array.isArray(parsed)) {
39
+ parsed.sessions = nullPrototypeRecords(parsed.sessions);
40
+ return parsed;
41
+ }
37
42
  }
38
43
  }
39
44
  catch {
40
45
  // Return empty store
41
46
  }
42
- return { sessions: {}, version: '3.0.0' };
47
+ return { sessions: nullPrototypeRecords(undefined), version: '3.0.0' };
43
48
  }
44
49
  function saveTerminalStore(store) {
45
50
  ensureTerminalDir();
@@ -139,6 +144,15 @@ export const terminalTools = [
139
144
  }
140
145
  // Find or create default session
141
146
  let session = sessionId ? store.sessions[sessionId] : Object.values(store.sessions).find(s => s.status === 'active');
147
+ // #4730: terminal_close only flips status to "closed". Executing anyway
148
+ // ran the command and then wrote status back to "active", so a closed
149
+ // session kept accepting commands. Reject anything that is not active
150
+ // before the process is spawned and before that status write. When no
151
+ // sessionId was given, the lookup above already selected an active
152
+ // session (or we create one below).
153
+ if (session && session.status !== 'active') {
154
+ return { success: false, error: `Session is not active (${session.status})` };
155
+ }
142
156
  if (!session) {
143
157
  // Create default session
144
158
  const id = `term-${Date.now()}-${randomBytes(4).toString('hex')}`;
@@ -5,5 +5,7 @@
5
5
  * Was a 256-line byte-identical copy. Loads @claude-flow/security validators
6
6
  * when available, with lightweight fallback otherwise.
7
7
  */
8
+ import { type ValidationResult } from '@claude-flow/cli-core/mcp-tools/validate-input';
8
9
  export * from '@claude-flow/cli-core/mcp-tools/validate-input';
10
+ export declare function validateIdentifier(value: unknown, label: string): ValidationResult;
9
11
  //# sourceMappingURL=validate-input.d.ts.map
@@ -5,5 +5,19 @@
5
5
  * Was a 256-line byte-identical copy. Loads @claude-flow/security validators
6
6
  * when available, with lightweight fallback otherwise.
7
7
  */
8
+ import { validateIdentifier as coreValidateIdentifier, } from '@claude-flow/cli-core/mcp-tools/validate-input';
8
9
  export * from '@claude-flow/cli-core/mcp-tools/validate-input';
10
+ /**
11
+ * Names that resolve to Object.prototype or a built-in when used as a key on a
12
+ * plain object. Identifiers key the JSON record stores, so they are refused.
13
+ * Move this check into cli-core on its next release.
14
+ */
15
+ const RESERVED_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
16
+ export function validateIdentifier(value, label) {
17
+ const result = coreValidateIdentifier(value, label);
18
+ if (result.valid && RESERVED_KEYS.has(result.sanitized)) {
19
+ return { valid: false, sanitized: '', error: `${label} must not be a reserved name (${result.sanitized})` };
20
+ }
21
+ return result;
22
+ }
9
23
  //# sourceMappingURL=validate-input.js.map
@@ -8,6 +8,7 @@ import { join } from 'node:path';
8
8
  import { getProjectCwd } from './types.js';
9
9
  import { validateIdentifier, validatePath, validateText } from './validate-input.js';
10
10
  import { executeAgentTask } from './agent-execute-core.js';
11
+ import { readPreservedJsonStore } from './record-store.js';
11
12
  // Storage paths
12
13
  const STORAGE_DIR = '.claude-flow';
13
14
  const WORKFLOW_DIR = 'workflows';
@@ -73,19 +74,19 @@ function withRecordMaps(store, keys) {
73
74
  return store;
74
75
  }
75
76
  const WORKFLOW_MAPS = ['workflows', 'templates'];
77
+ function isRecordMap(value) {
78
+ return !!value && typeof value === 'object' && !Array.isArray(value);
79
+ }
76
80
  function loadWorkflowStore() {
77
- try {
78
- const path = getWorkflowPath();
79
- if (existsSync(path)) {
80
- const data = JSON.parse(readFileSync(path, 'utf-8'));
81
- if (data && typeof data === 'object' && !Array.isArray(data))
82
- return withRecordMaps(data, WORKFLOW_MAPS);
83
- }
84
- }
85
- catch {
86
- // Return default store on error
87
- }
88
- return withRecordMaps({ workflows: {}, templates: {}, version: '3.0.0' }, WORKFLOW_MAPS);
81
+ // #4737: a parse error used to return an empty store, and the next save
82
+ // overwrote the file. Only a missing file is empty; corrupt bytes are
83
+ // copied aside and the error is reported.
84
+ const path = getWorkflowPath();
85
+ const data = readPreservedJsonStore(path, 'workflow', () => ({ workflows: {}, templates: {}, version: '3.0.0' }), (store) => WORKFLOW_MAPS.every((key) => {
86
+ const map = store[key];
87
+ return map === undefined || isRecordMap(map);
88
+ }));
89
+ return withRecordMaps(data, WORKFLOW_MAPS);
89
90
  }
90
91
  function saveWorkflowStore(store) {
91
92
  ensureWorkflowDir();
@@ -1,14 +1,53 @@
1
1
  import { createHash } from 'node:crypto';
2
- import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
2
+ import { existsSync, lstatSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
3
3
  import { homedir } from 'node:os';
4
- import { join, dirname } from 'node:path';
5
- // ADR-125 precedence: tool args (relayHttp / relayWs / keyFile) take precedence over the
6
- // RUFLO_X_RELAY_HTTP / RUFLO_X_RELAY_WS / RUFLO_NOSTR_KEY_FILE env vars, which precede defaults.
4
+ import { join, dirname, isAbsolute, relative, resolve } from 'node:path';
5
+ // Host configuration precedes defaults. Caller key overrides stay under ~/.ruflo;
6
+ // a caller relayWs must match the configured relay. relayHttp keeps ADR-125 precedence.
7
7
  const HTTP_BASE = (o) => (o || process.env.RUFLO_X_RELAY_HTTP || 'https://relay.ruv.io').replace(/\/$/, '');
8
8
  const RELAY_WS = (o) => o || process.env.RUFLO_X_RELAY_WS || 'wss://relay.ruv.io';
9
9
  const KEY_FILE = () => process.env.RUFLO_NOSTR_KEY_FILE || join(homedir(), '.ruflo', 'nostr.key');
10
10
  const hex = (b) => Buffer.from(b).toString('hex');
11
11
  const unhex = (h) => Uint8Array.from(Buffer.from(h, 'hex'));
12
+ function callerKeyFile(value) {
13
+ // Host configuration is trusted; an MCP argument cannot select a different host file.
14
+ if (value === undefined)
15
+ return KEY_FILE();
16
+ if (typeof value !== 'string' || !value)
17
+ throw new Error('keyFile must name a file under ~/.ruflo');
18
+ const root = resolve(homedir(), '.ruflo');
19
+ const target = resolve(value);
20
+ const rel = relative(root, target);
21
+ if (!rel || rel === '..' || rel.startsWith('../') || rel.startsWith('..\\') || isAbsolute(rel)) {
22
+ throw new Error('keyFile must name a file under ~/.ruflo');
23
+ }
24
+ for (let current = target;; current = dirname(current)) {
25
+ try {
26
+ if (lstatSync(current).isSymbolicLink())
27
+ throw new Error('keyFile must not follow symlinks');
28
+ }
29
+ catch (error) {
30
+ if (error.code !== 'ENOENT')
31
+ throw error;
32
+ }
33
+ if (relative(root, current) === '')
34
+ break;
35
+ }
36
+ return target;
37
+ }
38
+ function configuredRelay(value) {
39
+ const configured = new URL(RELAY_WS());
40
+ if (value !== undefined && typeof value !== 'string')
41
+ throw new Error('relayWs must be the configured relay URL');
42
+ const requested = new URL(value === undefined ? configured.href : value);
43
+ const localTestRelay = Boolean(process.env.RUFLO_X_RELAY_WS)
44
+ && configured.protocol === 'ws:' && ['localhost', '127.0.0.1', '[::1]'].includes(configured.hostname);
45
+ if ((!localTestRelay && configured.protocol !== 'wss:') || requested.href !== configured.href
46
+ || requested.username || requested.password || requested.hash) {
47
+ throw new Error('relayWs must use wss and match the configured relay (explicit loopback ws configuration is allowed)');
48
+ }
49
+ return requested.href;
50
+ }
12
51
  async function loadNostrTools() {
13
52
  try {
14
53
  return (await import('nostr-tools/pure'));
@@ -24,7 +63,7 @@ export function loadOrCreateKey(nt, file = KEY_FILE()) {
24
63
  }
25
64
  mkdirSync(dirname(file), { recursive: true, mode: 0o700 });
26
65
  const sk = nt.generateSecretKey();
27
- writeFileSync(file, hex(sk), { mode: 0o600 });
66
+ writeFileSync(file, hex(sk), { mode: 0o600, flag: 'wx' });
28
67
  return { sk, pubkey: nt.getPublicKey(sk), created: true };
29
68
  }
30
69
  export function nip98Header(nt, sk, url, method, body) {
@@ -80,24 +119,26 @@ export const xFederationJoinTools = [{
80
119
  code: { type: 'string', description: 'Optional private invite code (v2.…), for invite-only relays.' },
81
120
  gatewayUrl: { type: 'string', description: 'Public registration gateway origin; defaults to https://x.ruv.io.' },
82
121
  relayHttp: { type: 'string', description: 'Relay HTTPS base for the claim; takes precedence over RUFLO_X_RELAY_HTTP.' },
83
- relayWs: { type: 'string', description: 'Relay wss URL for NIP-42; takes precedence over RUFLO_X_RELAY_WS.' },
84
- keyFile: { type: 'string', description: 'Key file path; takes precedence over RUFLO_NOSTR_KEY_FILE (default ~/.ruflo/nostr.key).' }
122
+ relayWs: { type: 'string', description: 'Relay wss URL for NIP-42; must match RUFLO_X_RELAY_WS or the default relay.' },
123
+ keyFile: { type: 'string', description: 'Caller-selected file under ~/.ruflo (no symlinks). Omit to use host RUFLO_NOSTR_KEY_FILE or ~/.ruflo/nostr.key.' }
85
124
  }, required: [] },
86
125
  handler: async (input) => {
87
126
  const i = input;
88
- const nt = await loadNostrTools();
89
127
  // Validate input before the optional-dependency check so a bad code fails fast and identically
90
128
  // whether or not nostr-tools is present.
91
129
  if (i.code !== undefined && !/^v2\.[A-Za-z0-9._-]{8,}$/.test(i.code))
92
130
  throw new Error('invite code must look like v2.<token>');
131
+ const registrationBase = i.code ? undefined : secureBase(i.gatewayUrl || process.env.RUFLO_X_GATEWAY_URL || 'https://x.ruv.io');
132
+ const keyFile = callerKeyFile(i.keyFile);
133
+ const relayWs = configuredRelay(i.relayWs);
134
+ const nt = await loadNostrTools();
93
135
  if (!nt)
94
136
  return { degraded: true, reason: 'nostr-tools not installed', hint: 'npm i -g nostr-tools (secp256k1 signing is not in node:crypto)' };
95
- const registrationBase = i.code ? undefined : secureBase(i.gatewayUrl || process.env.RUFLO_X_GATEWAY_URL || 'https://x.ruv.io');
96
- const { sk, pubkey, created } = loadOrCreateKey(nt, i.keyFile);
137
+ const { sk, pubkey, created } = loadOrCreateKey(nt, keyFile);
97
138
  // Existing members need no new grant. In particular never downgrade/re-admit
98
139
  // their key just because they run join again.
99
140
  if (!i.code) {
100
- const existing = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
141
+ const existing = await verifyMembership(nt, sk, relayWs);
101
142
  if (existing.ok)
102
143
  return { ok: true, pubkey, keyCreated: created, membershipVerified: true, alreadyMember: true };
103
144
  }
@@ -108,7 +149,7 @@ export const xFederationJoinTools = [{
108
149
  r = await fetch(url, { method: 'POST', redirect: 'error', headers: { Authorization: nip98Header(nt, sk, url, 'POST', body), 'Content-Type': 'application/json' }, body, signal: AbortSignal.timeout(20_000) });
109
150
  }
110
151
  catch {
111
- const check = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
152
+ const check = await verifyMembership(nt, sk, relayWs);
112
153
  if (check.ok)
113
154
  return { ok: true, pubkey, keyCreated: created, membershipVerified: true };
114
155
  throw new Error('Admission response unavailable and relay membership unverified. Keep your local key and retry; do not create another identity.');
@@ -117,12 +158,12 @@ export const xFederationJoinTools = [{
117
158
  if (!r.ok) {
118
159
  // A lost acknowledgment can follow a successful grant. Check with the
119
160
  // relay before declaring failure; never silently generate a second key.
120
- const check = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
161
+ const check = await verifyMembership(nt, sk, relayWs);
121
162
  if (check.ok)
122
163
  return { ok: true, pubkey, keyCreated: created, membershipVerified: true };
123
164
  throw new Error(`join rejected (${r.status}): ${claim.error ?? claim.message ?? 'unknown'}`);
124
165
  }
125
- const auth = await verifyMembership(nt, sk, RELAY_WS(i.relayWs));
166
+ const auth = await verifyMembership(nt, sk, relayWs);
126
167
  return { ok: auth.ok, pubkey, keyCreated: created, role: claim.role ?? 'member', membershipVerified: auth.ok, ...(auth.ok ? {} : { reason: auth.reason }),
127
168
  next: 'Publish kind-1 events tagged ["t","ruflo-swarm"] — or run `ruflo federation sync` to read the swarm.' };
128
169
  },
@@ -152,6 +152,12 @@ declare class LocalReasoningBank {
152
152
  private persistenceEnabled;
153
153
  private dirty;
154
154
  private saveTimeout;
155
+ /** IDs changed locally since the last successful flush. */
156
+ private dirtyIds;
157
+ /** IDs deleted locally; a disk copy must not be resurrected. */
158
+ private deletedIds;
159
+ /** A local clear() must remove disk entries too. */
160
+ private clearRequested;
155
161
  constructor(options: {
156
162
  maxSize: number;
157
163
  persistence?: boolean;
@@ -168,6 +174,11 @@ declare class LocalReasoningBank {
168
174
  private saveToDisk;
169
175
  /**
170
176
  * Immediately flush patterns to disk
177
+ *
178
+ * Re-reads the file under the cooperating-writer lock and merges only the
179
+ * patterns this process changed, so a long-lived daemon cannot erase patterns
180
+ * written by another hook/process (#4735). Deletions and clear() are carried
181
+ * as tombstones; the write itself is temp-file + rename.
171
182
  */
172
183
  flushToDisk(): void;
173
184
  /**
@@ -337,6 +337,12 @@ class LocalReasoningBank {
337
337
  persistenceEnabled;
338
338
  dirty = false;
339
339
  saveTimeout = null;
340
+ /** IDs changed locally since the last successful flush. */
341
+ dirtyIds = new Set();
342
+ /** IDs deleted locally; a disk copy must not be resurrected. */
343
+ deletedIds = new Set();
344
+ /** A local clear() must remove disk entries too. */
345
+ clearRequested = false;
340
346
  constructor(options) {
341
347
  this.maxSize = options.maxSize;
342
348
  this.persistenceEnabled = options.persistence !== false;
@@ -359,6 +365,7 @@ class LocalReasoningBank {
359
365
  const totalLoaded = data.length;
360
366
  // Group by content to deduplicate
361
367
  const byContent = new Map();
368
+ const removedIds = [];
362
369
  for (const pattern of data) {
363
370
  const key = pattern.content;
364
371
  const existing = byContent.get(key);
@@ -372,10 +379,12 @@ class LocalReasoningBank {
372
379
  (pattern.lastUsedAt ?? 0) > (existing.lastUsedAt ?? 0))) {
373
380
  // Merge: adopt the higher usageCount sum
374
381
  pattern.usageCount = (pattern.usageCount ?? 0) + (existing.usageCount ?? 0);
382
+ removedIds.push(existing.id);
375
383
  byContent.set(key, pattern);
376
384
  }
377
385
  else {
378
386
  existing.usageCount = (existing.usageCount ?? 0) + (pattern.usageCount ?? 0);
387
+ removedIds.push(pattern.id);
379
388
  }
380
389
  }
381
390
  }
@@ -387,15 +396,28 @@ class LocalReasoningBank {
387
396
  const removed = totalLoaded - byContent.size;
388
397
  if (removed > 0) {
389
398
  console.log(`Deduplicated ${removed} patterns (${byContent.size} unique)`);
390
- // Persist the compacted set immediately so the file shrinks on disk
399
+ // Persist the compacted set immediately so the file shrinks on disk.
400
+ // Mark every kept row dirty so this compaction wins over the disk
401
+ // copies, and tombstone the discarded duplicates.
402
+ for (const pattern of byContent.values())
403
+ this.dirtyIds.add(pattern.id);
404
+ for (const id of removedIds)
405
+ this.deletedIds.add(id);
391
406
  this.dirty = true;
392
407
  this.flushToDisk();
393
408
  }
394
409
  }
395
410
  }
396
411
  }
397
- catch {
398
- // Ignore load errors, start fresh
412
+ catch (error) {
413
+ // A corrupt patterns file must be preserved, not silently replaced by
414
+ // an empty bank on the next flush (#4735).
415
+ try {
416
+ const corruptPath = `${getPatternsPath()}.corrupt-${Date.now()}`;
417
+ renameSync(getPatternsPath(), corruptPath);
418
+ console.warn(`[intelligence] Corrupt patterns file moved to ${corruptPath}`);
419
+ }
420
+ catch { /* already absent or rename failed — never overwrite it below */ }
399
421
  }
400
422
  }
401
423
  /**
@@ -415,6 +437,11 @@ class LocalReasoningBank {
415
437
  }
416
438
  /**
417
439
  * Immediately flush patterns to disk
440
+ *
441
+ * Re-reads the file under the cooperating-writer lock and merges only the
442
+ * patterns this process changed, so a long-lived daemon cannot erase patterns
443
+ * written by another hook/process (#4735). Deletions and clear() are carried
444
+ * as tombstones; the write itself is temp-file + rename.
418
445
  */
419
446
  flushToDisk() {
420
447
  if (!this.persistenceEnabled || !this.dirty)
@@ -422,11 +449,52 @@ class LocalReasoningBank {
422
449
  try {
423
450
  ensureDataDir();
424
451
  const path = getPatternsPath();
425
- writeFileSync(path, JSON.stringify(this.patternList, null, 2), 'utf-8');
426
- this.dirty = false;
452
+ withStatsFileLock(path, (canonicalPath) => {
453
+ let diskPatterns = [];
454
+ if (existsSync(canonicalPath)) {
455
+ try {
456
+ const parsed = JSON.parse(readFileSync(canonicalPath, 'utf-8'));
457
+ if (!Array.isArray(parsed))
458
+ throw new Error('patterns.json is not an array');
459
+ diskPatterns = parsed;
460
+ }
461
+ catch {
462
+ // Preserve the corrupt original instead of overwriting it with an
463
+ // empty bank; the new file is written only after this rename.
464
+ try {
465
+ const corruptPath = `${canonicalPath}.corrupt-${Date.now()}`;
466
+ renameSync(canonicalPath, corruptPath);
467
+ console.warn(`[intelligence] Corrupt patterns file moved to ${corruptPath}`);
468
+ }
469
+ catch { /* leave the original in place */ }
470
+ }
471
+ }
472
+ const merged = new Map();
473
+ if (!this.clearRequested) {
474
+ for (const pattern of diskPatterns) {
475
+ if (!this.deletedIds.has(pattern.id))
476
+ merged.set(pattern.id, pattern);
477
+ }
478
+ }
479
+ for (const pattern of this.patternList) {
480
+ if (this.clearRequested || this.dirtyIds.has(pattern.id)) {
481
+ merged.set(pattern.id, pattern);
482
+ }
483
+ }
484
+ const list = [...merged.values()];
485
+ const tmp = `${canonicalPath}.${process.pid}.${Date.now()}.tmp`;
486
+ writeFileSync(tmp, JSON.stringify(list, null, 2), 'utf-8');
487
+ renameSync(tmp, canonicalPath);
488
+ this.patterns = new Map(list.map((pattern) => [pattern.id, pattern]));
489
+ this.patternList = list;
490
+ this.dirty = false;
491
+ this.dirtyIds.clear();
492
+ this.deletedIds.clear();
493
+ this.clearRequested = false;
494
+ });
427
495
  }
428
496
  catch (error) {
429
- // Log but don't throw - persistence failures shouldn't break training
497
+ // Log but don't throw - persistence failures shouldn't break training.
430
498
  console.error('Failed to persist patterns:', error);
431
499
  }
432
500
  }
@@ -459,6 +527,7 @@ class LocalReasoningBank {
459
527
  this.patternList[idx] = stored;
460
528
  }
461
529
  this.patterns.set(pattern.id, stored);
530
+ this.dirtyIds.add(pattern.id);
462
531
  this.saveToDisk();
463
532
  return false;
464
533
  }
@@ -474,6 +543,7 @@ class LocalReasoningBank {
474
543
  }
475
544
  // Keep the Map in sync with the mutated object
476
545
  this.patterns.set(contentDupe.id, contentDupe);
546
+ this.dirtyIds.add(contentDupe.id);
477
547
  this.saveToDisk();
478
548
  return false;
479
549
  }
@@ -482,11 +552,14 @@ class LocalReasoningBank {
482
552
  const oldest = this.patternList.shift();
483
553
  if (oldest) {
484
554
  this.patterns.delete(oldest.id);
555
+ this.deletedIds.add(oldest.id);
556
+ this.dirtyIds.delete(oldest.id);
485
557
  }
486
558
  }
487
559
  this.patternList.push(stored);
488
560
  }
489
561
  this.patterns.set(pattern.id, stored);
562
+ this.dirtyIds.add(stored.id);
490
563
  // Trigger persistence (debounced)
491
564
  this.saveToDisk();
492
565
  return true;
@@ -583,6 +656,8 @@ class LocalReasoningBank {
583
656
  if (idx >= 0) {
584
657
  this.patternList.splice(idx, 1);
585
658
  }
659
+ this.dirtyIds.delete(id);
660
+ this.deletedIds.add(id);
586
661
  this.saveToDisk();
587
662
  return true;
588
663
  }
@@ -592,6 +667,9 @@ class LocalReasoningBank {
592
667
  clear() {
593
668
  this.patterns.clear();
594
669
  this.patternList = [];
670
+ this.dirtyIds.clear();
671
+ this.deletedIds.clear();
672
+ this.clearRequested = true;
595
673
  this.saveToDisk();
596
674
  }
597
675
  }
@@ -361,7 +361,9 @@ export declare function loadEmbeddingModel(options?: {
361
361
  * own embedder is real or stubbed). Set `backend` truthfully by the path that
362
362
  * actually produced the vector. Do NOT change the embedding math.
363
363
  */
364
- export declare function generateEmbedding(text: string): Promise<{
364
+ export declare function generateEmbedding(text: string, options?: {
365
+ normalize?: boolean;
366
+ }): Promise<{
365
367
  embedding: number[];
366
368
  dimensions: number;
367
369
  model: string;
@@ -382,7 +384,9 @@ export declare function generateEmbedding(text: string): Promise<{
382
384
  *
383
385
  * Keeping the local chain as its own export breaks that cycle structurally.
384
386
  */
385
- export declare function generateLocalEmbedding(text: string): Promise<{
387
+ export declare function generateLocalEmbedding(text: string, options?: {
388
+ normalize?: boolean;
389
+ }): Promise<{
386
390
  embedding: number[];
387
391
  dimensions: number;
388
392
  model: string;
@@ -2253,7 +2253,12 @@ async function loadLocalEmbeddingChain(verbose = false, startTime = Date.now())
2253
2253
  * own embedder is real or stubbed). Set `backend` truthfully by the path that
2254
2254
  * actually produced the vector. Do NOT change the embedding math.
2255
2255
  */
2256
- export async function generateEmbedding(text) {
2256
+ export async function generateEmbedding(text, options) {
2257
+ // #4724: AgentDB embed() has no normalize switch and always returns a unit
2258
+ // vector. A raw request has to use the local chain, which can skip L2.
2259
+ if (options?.normalize === false) {
2260
+ return generateLocalEmbedding(text, { normalize: false });
2261
+ }
2257
2262
  // ADR-053: Try AgentDB v3 bridge first
2258
2263
  const bridge = await getBridge();
2259
2264
  if (bridge) {
@@ -2283,7 +2288,9 @@ export async function generateEmbedding(text) {
2283
2288
  *
2284
2289
  * Keeping the local chain as its own export breaks that cycle structurally.
2285
2290
  */
2286
- export async function generateLocalEmbedding(text) {
2291
+ export async function generateLocalEmbedding(text, options) {
2292
+ // Default true keeps the historical unit-norm embedding math.
2293
+ const normalize = options?.normalize !== false;
2287
2294
  // Ensure the LOCAL model is loaded. #3375: this must not go through
2288
2295
  // loadEmbeddingModel(), which is bridge-first — when the bridge answered
2289
2296
  // there, no local model was ever loaded and this function always returned
@@ -2314,7 +2321,7 @@ export async function generateLocalEmbedding(text) {
2314
2321
  // Use ONNX model if available
2315
2322
  if (state.model && typeof state.model === 'function') {
2316
2323
  try {
2317
- const output = await state.model(text, { pooling: 'mean', normalize: true });
2324
+ const output = await state.model(text, { pooling: 'mean', normalize });
2318
2325
  // Handle @xenova/transformers (output.data), ruvector (plain array) and
2319
2326
  // typed-array (ReasoningBank Float32Array, #3114) formats. DataView is an
2320
2327
  // ArrayBuffer view without an iterator (Array.from gives []), so exclude it.
@@ -2338,7 +2345,7 @@ export async function generateLocalEmbedding(text) {
2338
2345
  // Deterministic hash-based fallback (for testing/demo without ONNX).
2339
2346
  // AUDIT #3: backend='mock' — these vectors do NOT carry real semantics.
2340
2347
  (await import('./embedding-policy.js')).enforceNoStub('memory-initializer.generateLocalEmbedding'); // "no stubs" strict mode
2341
- const embedding = generateHashEmbedding(text, state.dimensions);
2348
+ const embedding = generateHashEmbedding(text, state.dimensions, normalize);
2342
2349
  return {
2343
2350
  embedding,
2344
2351
  dimensions: state.dimensions,
@@ -2401,7 +2408,7 @@ export async function generateBatchEmbeddings(texts, options) {
2401
2408
  * Generate deterministic hash-based embedding
2402
2409
  * Not semantic, but deterministic and useful for testing
2403
2410
  */
2404
- function generateHashEmbedding(text, dimensions) {
2411
+ function generateHashEmbedding(text, dimensions, normalize = true) {
2405
2412
  const embedding = new Array(dimensions).fill(0);
2406
2413
  // Simple hash-based approach for reproducibility
2407
2414
  const words = text.toLowerCase().split(/\s+/);
@@ -2413,7 +2420,9 @@ function generateHashEmbedding(text, dimensions) {
2413
2420
  embedding[idx] += Math.sin(charCode * 0.1) * 0.1;
2414
2421
  }
2415
2422
  }
2416
- // Normalize to unit vector
2423
+ // Normalize to unit vector unless the caller asked for the raw vector (#4724).
2424
+ if (!normalize)
2425
+ return embedding;
2417
2426
  const magnitude = Math.sqrt(embedding.reduce((sum, v) => sum + v * v, 0)) || 1;
2418
2427
  return embedding.map(v => v / magnitude);
2419
2428
  }