ruvnet-brain 4.7.21 → 4.7.23

package/plugin/scripts/agentdb-recall-process.mjs

@@ -2,8 +2,8 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
-import { rufloInvocation } from './ruflo-bin.mjs';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+import { rufloInvocation, nativeNodeFor } from './ruflo-bin.mjs';
 export function searchJsonResult(stdout) {
   const s = String(stdout || '');
   // Live Ruflo prints warnings AFTER the JSON object as well as logs before it.
@@ -20,6 +20,105 @@ function killGroup(child) {
   catch { try { child.kill('SIGKILL'); } catch { /* already gone */ } }
 }
 
+const readJson = (file) => { try { return JSON.parse(fs.readFileSync(file, 'utf8')); } catch { return null; } };
+const inside = (root, file) => { const rel = path.relative(root, file); return rel && !rel.startsWith('..') && !path.isAbsolute(rel); };
+
+/**
+ * Can reads go through Ruflo's own published code instead of one CLI process per read (#429)? Only when the resolved
+ * `ruflo` is the real package entry AND the `@claude-flow/cli` it loads (found as bin/ruflo.js finds it) declares a
+ * `./memory` export that resolves to a file inside it. Otherwise null and the caller keeps the per-read CLI route.
+ * The three functions and result shapes are checked again inside the child, where they are actually loaded.
+ */
+export function resolveBatchTarget(bin, { env = process.env, deadlineAt } = {}) {
+  try {
+    if (!bin || process.platform === 'win32') return null; // npm .cmd shims are not inspected here
+    const entry = fs.realpathSync(bin);
+    const pkgRoot = path.dirname(path.dirname(entry));
+    const pkg = readJson(path.join(pkgRoot, 'package.json'));
+    const declared = typeof pkg?.bin === 'string' ? pkg.bin : pkg?.bin?.ruflo;
+    if (pkg?.name !== 'ruflo' || typeof declared !== 'string' || fs.realpathSync(path.resolve(pkgRoot, declared)) !== entry) return null;
+    let cliRoot = null;
+    for (let dir = pkgRoot, i = 0; i < 10 && !cliRoot; i += 1, dir = path.dirname(dir)) {
+      const candidate = path.join(dir, 'node_modules', '@claude-flow', 'cli');
+      if (fs.existsSync(path.join(candidate, 'package.json'))) cliRoot = candidate;
+      if (path.dirname(dir) === dir) break;
+    }
+    const cli = cliRoot && readJson(path.join(cliRoot, 'package.json'));
+    const target = cli?.name === '@claude-flow/cli' ? (cli.exports?.['./memory']?.import ?? cli.exports?.['./memory']) : null;
+    if (typeof target !== 'string') return null;
+    const file = fs.realpathSync(path.resolve(cliRoot, target));
+    if (!inside(fs.realpathSync(cliRoot), file) || !fs.statSync(file).isFile()) return null;
+    return { node: nativeNodeFor(bin, { env, deadlineAt })?.node ?? process.execPath, moduleUrl: pathToFileURL(file).href };
+  } catch { return null; }
+}
+
+/**
+ * ONE owned child answering `list` / `get` for a store through Ruflo's public memory export. Spawned on first use,
+ * killed (whole process group) at the absolute deadline or on close(). Every op resolves, never rejects:
+ * { state: 'ok' | 'unavailable' | 'timed out' | 'fallback', rows?, value? } — 'fallback' means this route cannot
+ * answer (capability or shape mismatch) and the caller must use the per-read CLI route. `{success:false}` from
+ * Ruflo is 'unavailable', never an empty result.
+ */
+export function openBatchSession({ bin, storePath, env, deadline, makeCwd, signal }) {
+  const target = resolveBatchTarget(bin, { env, deadlineAt: deadline });
+  if (!target || !storePath) return null;
+  let child = null, cwd = null, ready = null, resolveReady = null, seq = 0, closed = false, timer;
+  const pending = new Map();
+  const settleAll = (state) => { for (const finish of [...pending.values()]) finish({ state }); };
+  const close = (state = 'unavailable') => {
+    if (closed) return; closed = true; clearTimeout(timer);
+    settleAll(state);
+    if (child) { killGroup(child); try { child.stdin.destroy(); } catch { /* gone */ } }
+    cwd?.cleanup?.();
+  };
+  const start = () => {
+    if (child || closed) return;
+    try {
+      cwd = makeCwd();
+      child = spawn(target.node, [fileURLToPath(new URL('./agentdb-recall-reader.mjs', import.meta.url)), '--session', storePath, target.moduleUrl],
+        { cwd: cwd.cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false', CLAUDE_FLOW_MEMORY_PATH: undefined },
+          stdio: ['pipe', 'pipe', 'ignore'], detached: process.platform !== 'win32', windowsHide: true });
+    } catch { child = null; close(); return; }
+    ready = new Promise((resolve) => {
+      resolveReady = resolve;
+      child.once('close', () => { resolve(false); if (!closed) settleAll('unavailable'); });
+      child.once('error', () => resolve(false));
+    });
+    let buffer = '';
+    child.stdout.setEncoding('utf8');
+    child.stdout.on('data', (chunk) => {
+      buffer += chunk;
+      for (let at = buffer.indexOf('\n'); at >= 0; at = buffer.indexOf('\n')) {
+        const line = buffer.slice(0, at); buffer = buffer.slice(at + 1);
+        let row; try { row = JSON.parse(line); } catch { continue; }
+        if (typeof row.ready === 'boolean') resolveReady(row.ready);
+        else pending.get(row.id)?.(row);
+      }
+    });
+    child.stdin.on('error', () => {});
+    timer = setTimeout(() => close('timed out'), Math.max(1, deadline - Date.now()));
+    signal?.addEventListener('abort', () => close('unavailable'), { once: true });
+  };
+  const ask = (request, opDeadline = deadline) => new Promise((resolve) => {
+    if (closed || signal?.aborted) return resolve({ state: signal?.aborted ? 'unavailable' : 'timed out' });
+    if (opDeadline - Date.now() <= 0) return resolve({ state: 'timed out' });
+    start();
+    if (!child) return resolve({ state: 'unavailable' });
+    const id = ++seq;
+    const opTimer = opDeadline < deadline ? setTimeout(() => finish({ state: 'timed out' }), Math.max(1, opDeadline - Date.now())) : null;
+    const finish = (row) => { if (!pending.delete(id)) return; clearTimeout(opTimer); const { id: _id, ...rest } = row; resolve(rest); };
+    pending.set(id, finish);
+    ready.then((ok) => {
+      if (!pending.has(id)) return;
+      if (!ok) return finish({ state: closed ? 'unavailable' : 'fallback' });
+      try { child.stdin.write(JSON.stringify({ id, ...request }) + '\n'); } catch { finish({ state: 'unavailable' }); }
+    });
+  });
+  return { storePath, close,
+    list: (namespace, limit, opDeadline) => ask({ op: 'list', namespace, limit }, opDeadline),
+    get: async (namespace, key, opDeadline) => { const r = await ask({ op: 'get', namespace, key }, opDeadline); return r.state === 'ok' ? { ...r, value: r.value.trim() } : r; } };
+}
+
 /** One ruflo search, bounded by an absolute deadline. Resolves { rows, state } — never rejects. */
 export function searchOnce({ ruflo, store, args, deadline, env, scratch, operation = 'search', signal, invocation }) {
   return new Promise((resolve) => {
@@ -82,7 +181,18 @@ export function searchOnce({ ruflo, store, args, deadline, env, scratch, operati
 }
 
 /** Isolate synchronous read-only SQLite work inside the same cancellable process budget. */
-export async function nativeRead({ store, requests, namespaces, deadline, env, scratch, signal }) {
+export async function nativeRead({ store, requests, namespaces, deadline, env, scratch, signal, session }) {
+  if (session && session.storePath === store.path) {
+    const rows = requests ? await Promise.all(requests.map(({ namespace, key }) => session.get(namespace, key)))
+      : await Promise.all(namespaces.map((namespace) => session.list(namespace, 100000)));
+    const states = rows.map((row) => row.state);
+    if (!states.includes('fallback')) {
+      const dead = states.find((state) => state === 'timed out') ?? (!requests && states.find((state) => state !== 'ok'));
+      if (dead) return { ok: false, fatal: true, state: dead };
+      return { ok: true, state: 'ok', value: requests ? rows.map((row) => (row.state === 'ok' ? row.value : null))
+        : Object.fromEntries(namespaces.map((namespace, i) => [namespace, rows[i].rows.map((row) => row.key).filter((key) => typeof key === 'string')])) };
+    }
+  }
   const result = await searchOnce({ store, deadline, env, scratch, signal, operation: 'native',
     invocation: { executable: process.execPath, args: [fileURLToPath(new URL('./agentdb-recall-reader.mjs', import.meta.url)),
       store.path, JSON.stringify({ requests, namespaces, deadline })] } });
@@ -94,7 +204,7 @@ export async function nativeRead({ store, requests, namespaces, deadline, env, s
   } catch { return { ok: false, fatal: true, state: 'unavailable' }; }
 }
 
-export async function exactReads({ candidates, bin, deadline, env, scratch, signal }) {
+export async function exactReads({ candidates, bin, deadline, env, scratch, signal, session }) {
   const groups = new Map();
   for (const candidate of candidates) {
     const storePath = candidate.storePath;
@@ -104,7 +214,7 @@ export async function exactReads({ candidates, bin, deadline, env, scratch, sign
   const results = new Map();
   await Promise.all([...groups].map(async ([storePath, rows]) => {
     const native = await nativeRead({ store: { path: storePath }, requests: rows.map(({ namespace, key }) => ({ namespace, key })),
-      deadline, env, scratch, signal });
+      deadline, env, scratch, signal, session });
     await Promise.all(rows.map(async (row, index) => {
       const result = native.ok ? { state: 'ok', value: native.value[index] ?? '' }
         : native.fatal ? { state: native.state, value: '' }

package/plugin/scripts/agentdb-recall-reader.mjs

@@ -3,8 +3,46 @@
  * so a stalled CLI is retired at the recall deadline. Output contract unchanged: {ok, value}.
  */
 import { execFile } from 'node:child_process';
+import readline from 'node:readline';
 import { resolveRuflo, rufloInvocationOrPlain } from './ruflo-bin.mjs';
 
+/** Batch session (#429): ONE process answering line-based `list` / `get` requests by calling the installed Ruflo
+ * package's own public `@claude-flow/cli/memory` export — the functions its `memory list` / `memory retrieve`
+ * commands call. argv: --session <storePath> <moduleUrl>. Replies are single JSON lines on the real stdout. */
+async function session(storePath, moduleUrl) {
+  const write = process.stdout.write.bind(process.stdout);
+  process.stdout.write = (chunk, ...rest) => process.stderr.write(chunk, ...rest); // module chatter must not corrupt the protocol
+  const reply = (row) => write(JSON.stringify(row) + '\n');
+  let mod;
+  try { mod = await import(moduleUrl); } catch { mod = null; }
+  if (!mod || typeof mod.listEntries !== 'function' || typeof mod.getEntry !== 'function' || typeof mod.resolveDbPath !== 'function') {
+    reply({ ready: false }); process.exit(0);
+  }
+  const dbPath = mod.resolveDbPath(storePath);
+  reply({ ready: true });
+  const run = async ({ op, namespace, key, limit }) => {
+    if (typeof namespace !== 'string') return { state: 'fallback' };
+    if (op === 'list') {
+      const r = await mod.listEntries({ namespace, limit, offset: 0, dbPath });
+      if (r?.success === false) return { state: 'unavailable' };
+      // Every entry must carry a string key. If Ruflo renames the field the list is UNREADABLE by this route, never
+      // an empty namespace: fall back to the CLI route rather than report no memory (#429).
+      return r?.success === true && Array.isArray(r.entries) && r.entries.every((e) => e && typeof e === 'object' && typeof e.key === 'string')
+        ? { state: 'ok', rows: r.entries.map((e) => ({ key: e.key, createdAt: e.createdAt })) } : { state: 'fallback' };
+    }
+    if (op === 'get' && typeof key === 'string' && key) {
+      const r = await mod.getEntry({ key, namespace, dbPath });
+      if (r?.success === false || r?.success === true && r.found === false) return { state: 'unavailable' };
+      return r?.success === true && typeof r.entry?.content === 'string' ? { state: 'ok', value: r.entry.content } : { state: 'fallback' };
+    }
+    return { state: 'fallback' };
+  };
+  readline.createInterface({ input: process.stdin }).on('line', (line) => {
+    let request; try { request = JSON.parse(line); } catch { return; }
+    run(request).catch(() => ({ state: 'unavailable' })).then((out) => reply({ id: request.id, ...out }));
+  }).on('close', () => process.exit(0));
+}
+
 const call = (bin, args, deadline) => new Promise((resolve) => {
   const timeout = Math.max(1, deadline - Date.now());
   const inv = rufloInvocationOrPlain(bin, args, { env: process.env });
@@ -12,7 +50,8 @@ const call = (bin, args, deadline) => new Promise((resolve) => {
     (error, stdout) => resolve(error ? null : String(stdout || '')));
 });
 
-try {
+if (process.argv[2] === '--session') await session(process.argv[3], process.argv[4]);
+else try {
   const [storePath, input] = process.argv.slice(2);
   const { requests, namespaces, deadline } = JSON.parse(input);
   if (!Number.isFinite(deadline) || Date.now() >= deadline
@@ -33,7 +72,10 @@ try {
       const out = await call(bin, ['memory', 'list', '--namespace', namespace, '--limit', '100000', '--format', 'json', '--path', storePath], deadline);
       if (out === null) throw new Error('list failed');
       const at = out.indexOf('[');
-      return [namespace, at < 0 ? [] : JSON.parse(out.slice(at)).map((row) => row.key).filter((key) => typeof key === 'string')];
+      const rows = at < 0 ? [] : JSON.parse(out.slice(at));
+      // A list whose entries lack a string key is a changed contract, not an empty namespace: fail the read.
+      if (!Array.isArray(rows) || rows.some((row) => typeof row?.key !== 'string')) throw new Error('list shape changed');
+      return [namespace, rows.map((row) => row.key)];
     }));
     value = Object.fromEntries(lists);
   }

package/plugin/scripts/agentdb-recall.mjs

@@ -22,7 +22,7 @@ import { safeAction } from './learn-capture.mjs';
 import { redactText } from './continuity-events.mjs';
 import { resolveTurnDb } from './turn-outcome-capture.mjs';
 import { maskExcludedPaths } from './turn-capture-privacy.mjs';
-import { searchOnce, nativeRead, exactReads, searchJsonResult } from './agentdb-recall-process.mjs';
+import { searchOnce, nativeRead, exactReads, searchJsonResult, openBatchSession } from './agentdb-recall-process.mjs';
 import { makeLesson } from './lesson-store.mjs';
 import { supersededKeys, tombstonedKeys } from './decision-record.mjs';
 import { checkpointMs, checkpointNamespaces, newestCheckpoint } from './checkpoint-keys.mjs';
@@ -50,8 +50,8 @@ export function recallBinding({ binding = {}, projectRoot, storePath, prompt } =
 }
 
 /** Bounded structural enumeration uses the same cancellable read-only canonical provider. */
-export function enumerateCanonicalKeys({ storePath, namespaces, deadline, signal, env, scratch }) {
-  return nativeRead({ store: { path: storePath }, namespaces, deadline, signal, env, scratch });
+export function enumerateCanonicalKeys({ storePath, namespaces, deadline, signal, env, scratch, session }) {
+  return nativeRead({ store: { path: storePath }, namespaces, deadline, signal, env, scratch, session });
 }
 
 export function applicableRecallLesson(value, projectRoot) {
@@ -234,12 +234,12 @@ export function formatBlock({ picks, status, withheld = 0 }) {
 export const SEARCH_BUDGET_SHARE = 0.8;
 export function searchDeadlineFor(started, deadline) { return Math.min(deadline, started + Math.floor((deadline - started) * SEARCH_BUDGET_SHARE)); }
 
-async function consequentialRecall({ prompt, root, store, bin, scratch, env, deadline, binding, signal, enumerateKeys, exclusions, rankedSearch = true }) {
+async function consequentialRecall({ prompt, root, store, bin, scratch, env, deadline, binding, signal, enumerateKeys, exclusions, rankedSearch = true, session }) {
   const searchDeadline = searchDeadlineFor(Date.now(), deadline);
   const phaseBinding = recallBinding({ binding, projectRoot: root, storePath: store.path, prompt });
   const stateNamespaces = checkpointNamespaces(root);
   const namespaces = [...new Set([...stateNamespaces, 'lessons', 'continuity-events'])];
-  const enumeration = await enumerateKeys({ storePath: store.path, namespaces, deadline, signal, env, scratch });
+  const enumeration = await enumerateKeys({ storePath: store.path, namespaces, deadline, signal, env, scratch, session });
   if (!enumeration?.ok || signal?.aborted || Date.now() >= deadline) return { block: formatBlock({ picks: [], status: 'unavailable structural enumeration' }), picks: [], stores: [store],
     status: { 'memory.db': 'unavailable' }, outcome: signal?.aborted ? 'unavailable' : Date.now() >= deadline ? 'timed-out' : 'unavailable', categories: { state: 'unavailable', decisions: 'unavailable', lessons: 'unavailable' } };
   const keys = Object.fromEntries(namespaces.map(namespace => [namespace, Array.isArray(enumeration.value?.[namespace]) ? enumeration.value[namespace] : []]));
@@ -279,7 +279,7 @@ async function consequentialRecall({ prompt, root, store, bin, scratch, env, dea
   const categories = { state: unorderedState ? 'unavailable' : 'ok-empty', decisions: decisionAvailability, lessons: lessonAvailability };
   const records = [];
   candidates.forEach(candidate => { candidate.storePath = store.path; });
-  const exactResults = await exactReads({ candidates, bin, deadline, env, scratch, signal });
+  const exactResults = await exactReads({ candidates, bin, deadline, env, scratch, signal, session });
   // ADR-105 §8: supersession is a link on the NEWER record, computed from every decision record read, plus
   // the tombstones already in the enumeration so a superseder that was not read still retires its target.
   const superseded = tombstonedKeys(keys[path.basename(root)]);
@@ -338,6 +338,8 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
   binding = {}, signal, absoluteDeadline, consequential = false, enumerateKeys = enumerateCanonicalKeys } = {}) {
   const started = Date.now();
   const empty = { block: '', picks: [], stores: [], status: {} };
+  let session = null;
+  let specAbort = null;   // hoisted so `finally` can stop a speculative search that a later throw would orphan
   try {
     if (signal?.aborted) return { ...empty, outcome: 'unavailable', reason: 'cancelled' };
     if (!agentdbFirstEnabled(env)) return { ...empty, outcome: 'disabled' };
@@ -370,7 +372,15 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     const store = stores[0];
     const query = recallQuery(prompt);
     const scratchFor = scratch || ((storePath) => rufloCwdFor(storePath, { root: rufloScratchRoot(env) }));
-    if (consequential) return await consequentialRecall({ prompt, root, store, bin, scratch: scratchFor, env, deadline, binding, signal, enumerateKeys, exclusions });
+    // ONE owned child answers every list/get of this recall through Ruflo's public memory export (#429); null
+    // (not the real package, no ./memory export, an injected `ruflo`) keeps the per-read CLI route.
+    if (store) {
+      session = openBatchSession({ bin, storePath: store.path, env, deadline, signal, makeCwd: () => {
+        const cwd = fs.mkdtempSync(path.join(scratchFor(store.path), 'run-'));
+        return { cwd, cleanup: () => { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later */ } } };
+      } });
+    }
+    if (consequential) return await consequentialRecall({ prompt, root, store, bin, scratch: scratchFor, env, deadline, binding, signal, enumerateKeys, exclusions, session });
     // Only namespaces something below reads: curated lessons/decisions, the checkpoint namespaces (dirname, its
     // lowercase form, default) and turns for the single ranked search. Each one is a `ruflo memory list` process.
     const namespaces = [...new Set(['lessons', 'turns', 'continuity-events', ...checkpointNamespaces(root)])];
@@ -378,12 +388,21 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     // per namespace; run concurrently they starve every other read past the deadline. So: ONE native enumeration
     // (reused for the curated pass and for pruning empty namespaces), then exact curated state/lessons/decisions,
     // then spend what remains on ranking.
-    const presence = store ? await nativeRead({ store, namespaces, deadline, env, scratch: scratchFor, signal }) : null;
-    if (presence?.fatal) { return { ...empty, stores, outcome: presence.state === 'timed out' ? 'timed-out' : 'unavailable',
+    // The batch child's start-up (loading Ruflo's memory module, ~0.4 s) and the ranked search are independent, so with a
+    // session the search for the first-choice namespace starts NOW instead of after enumeration (#429 probe: the
+    // sequence left a 1.3-1.6 s tail against the 1.9 s budget). Still ONE search: it is cancelled and replaced only if
+    // enumeration shows that namespace is empty.
+    const specNamespace = path.basename(root);
+    specAbort = new AbortController();
+    const specSignal = signal ? AbortSignal.any([signal, specAbort.signal]) : specAbort.signal;
+    const specArgs = ['--format', 'json', '-q', query, '-n', specNamespace, '--limit', '12'];
+    const spec = session && store ? searchOnce({ ruflo: bin, store, deadline: searchDeadlineFor(Date.now(), deadline), env, scratch: scratchFor, args: specArgs, signal: specSignal }) : null;
+    const presence = store ? await nativeRead({ store, namespaces, deadline, env, scratch: scratchFor, signal, session }) : null;
+    if (presence?.fatal) { specAbort.abort(); return { ...empty, stores, outcome: presence.state === 'timed out' ? 'timed-out' : 'unavailable',
       block: formatBlock({ picks: [], status: presence.state }), reason: 'namespace enumeration failed' }; }
     const sharedKeys = presence?.ok ? async () => ({ ok: true, value: presence.value }) : enumerateCanonicalKeys;
     const curated = store ? await consequentialRecall({ prompt, root, store, bin, scratch: scratchFor, env, deadline, binding, signal,
-      enumerateKeys: sharedKeys, exclusions, rankedSearch: false }).catch(() => null) : null;
+      enumerateKeys: sharedKeys, exclusions, rankedSearch: false, session }).catch(() => null) : null;
     const searchDeadline = searchDeadlineFor(Date.now(), deadline);
     const activeNamespaces = presence?.ok ? namespaces.filter(namespace => presence.value[namespace]?.length) : namespaces;
     // ONE supplementary search (owner ruling 2026-10-12). Measured on a live-size store at load 17: ~10
@@ -392,8 +411,10 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     const searchNamespace = [path.basename(root), 'default', 'turns'].find((namespace) => activeNamespaces.includes(namespace));
     const jobs = store && searchNamespace ? [{ store, namespace: searchNamespace, family: null,
       args: ['--format', 'json', '-q', query, '-n', searchNamespace, '--limit', '12'] }] : [];
+    const useSpec = spec && jobs[0]?.namespace === specNamespace;
+    if (!useSpec) specAbort.abort();
     const results = await Promise.all(jobs.map(async ({ store: jobStore, namespace, family: recordFamily, args }) => ({ namespace, family: recordFamily, storePath: jobStore.path,
-      ...await searchOnce({ ruflo: bin, store: jobStore, deadline: searchDeadline, env, scratch: scratchFor, args, signal }) })));
+      ...await (useSpec ? spec : searchOnce({ ruflo: bin, store: jobStore, deadline: searchDeadline, env, scratch: scratchFor, args, signal })) })));
     let status = results.every((r) => r.state === 'ok') ? 'ok'
       : results.some((r) => r.state === 'timed out') ? 'timed out' : 'unavailable';
     // Overfetch a bounded twelve exact values (the one search already returns twelve; the exact reads are
@@ -402,7 +423,7 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
     const candidates = pickRows(results, 12);
     // Ruflo previews are ~60 characters. Read the actual selected values within
     // the same deadline so the block contains useful evidence rather than titles.
-    const exactResults = await exactReads({ candidates, bin, deadline, env, scratch: scratchFor, signal });
+    const exactResults = await exactReads({ candidates, bin, deadline, env, scratch: scratchFor, signal, session });
     const retrieved = await Promise.all(candidates.map(async (p) => {
       const r = exactResults.get(p);
       if (r.state === 'ok' && r.value && !r.value.startsWith('[WARN]')) {
@@ -462,6 +483,7 @@ export async function recall({ prompt, projectDir = process.cwd(), env = process
       authority: false };
     return { block: formatBlock({ picks, status, withheld: curated?.withheld || 0 }), picks, stores, status: { 'memory.db': status }, outcome, receipt };
   } catch (error) { return { ...empty, outcome: 'unavailable', reason: 'canonical recall failed: ' + clean(error.message, 180) }; }
+  finally { specAbort?.abort(); session?.close(); }
 }
 
 async function main() {

package/plugin/scripts/completion-claim-evidence.mjs

@@ -106,6 +106,54 @@ function segmentMutates(segment) {
   return /(?:^|[^0-9&>])>{1,2}\s*(?!&|\/dev\/null)(['"]?)([^\s'"]+)/.test(segment)
     && !TMP_PATH.test((/>{1,2}\s*['"]?([^\s'"]+)/.exec(segment) || [])[1] || '');
 }
+/**
+ * #369/#425: the exit status a transcript reports is the WHOLE command's. It is the status of one check only
+ * when the command is one simple command, or an `&&` chain (which reaches its end only if every part passed).
+ * Returns the reason a command is NOT such a shape (pipe, `||`, `;`, `&`, newline, substitution, subshell,
+ * redirection other than 2>&1 / /dev/null), or null. When unsure it names a reason: never binds by default.
+ */
+export function compoundReason(command) {
+  const s = String(command || '');
+  // A leading `!` (also after `&&`, after optional VAR=x prefixes) inverts the exit status: a failing check reports success.
+  if (/(?:^|&&)\s*(?:[A-Za-z_]\w*=\S*\s+)*!\s/.test(s)) return 'negated exit status (`!`)';
+  let q = '';
+  for (let i = 0; i < s.length; i++) {
+    const c = s[i];
+    const n = s[i + 1];
+    if (q === "'") { if (c === "'") q = ''; continue; }
+    if (c === '\\') { i++; continue; }
+    if (q === '"') {
+      if (c === '"') q = '';
+      else if (c === '`' || (c === '$' && n === '(')) return 'command substitution';
+      continue;
+    }
+    if (c === "'" || c === '"') { q = c; continue; }
+    if (c === '|') return n === '|' ? '`||` fallback' : 'pipe';
+    if (c === ';') return '`;` sequence';
+    if (c === '\n' || c === '\r') return 'multiple lines';
+    if (c === '`' || c === '(' || c === ')' || (c === '$' && n === '(')) return 'subshell or substitution';
+    if (c === '&') {
+      if (n === '&') { i++; continue; }
+      if (/^&>/.test(s.slice(i))) return 'redirection';
+      return 'background `&`';
+    }
+    if (c === '>' || c === '<') {
+      const m = /^(?:>&\d|>>?\s*\/dev\/null)/.exec(s.slice(i));
+      if (m) { i += m[0].length - 1; continue; }
+      return 'redirection';
+    }
+  }
+  return null;
+}
+const SAFE_REDIRECT = /\s*\d?>>?\s*\/dev\/null|\s*\d?>&\d/g;
+/** The command a claim would name: safe redirects (2>&1, >/dev/null) are not part of it. */
+const withoutSafeRedirects = (seg) => seg.replace(SAFE_REDIRECT, '').trim();
+/** For an unbound segment: the leading command a claim could have named (cut at the first operator). */
+function headsOf(seg) {
+  const lead = seg.replace(/^[\s(]*(?:\$\()?/, '');
+  const cut = (t) => t.split(/[|;&<>()`$\n]/)[0].trim();
+  return [...new Set([cut(seg), cut(lead)].filter((h) => h.length >= 4))];
+}
 const segmentChecks = (segment) => !TRIVIAL.test(segment) && !segmentMutates(segment);
 function checkName(segment) {
   const words = segment.replace(/^(?:[A-Z_][A-Z0-9_]*=\S+\s+)+/, '').split(/\s+/);
@@ -133,7 +181,10 @@ export function currentTurnRecords(lines) {
     const isToolResult = Array.isArray(c) && c.some((x) => x?.type === 'tool_result');
     if (o?.type === 'user' && (o.message?.role || 'user') === 'user' && !isToolResult && !o.isMeta && textOf(c).trim()) start = i;
   });
-  return { boundaryFound: start >= 0, prompt: start >= 0 ? textOf(recs[start].message?.content) : '', recs: recs.slice(start + 1) };
+  // `openerId` identifies the turn by its opening record (uuid, else its position among the main-thread records),
+  // never by the prompt text: a repeated "continue" is a different turn with the same words.
+  const openerId = start < 0 ? '' : (typeof recs[start].uuid === 'string' && recs[start].uuid ? `uuid:${recs[start].uuid}` : `pos:${start}`);
+  return { boundaryFound: start >= 0, prompt: start >= 0 ? textOf(recs[start].message?.content) : '', openerId, recs: recs.slice(start + 1) };
 }
 
 // Codex tools that neither change state nor run a check; every other unrecognised tool is a change (fail
@@ -147,7 +198,7 @@ const CODEX_NEUTRAL = /^(?:update_plan|view_image|sleep|list_agents|wait_agent|w
 /** Ordered events for the current turn of a Claude JSONL (or normalized Codex) transcript. */
 export function claudeTurnEvents(lines, { host = 'claude' } = {}) {
   const codex = host === 'codex';
-  const { boundaryFound, recs: turnRecs } = currentTurnRecords(lines);
+  const { boundaryFound, prompt: turnPrompt, openerId, recs: turnRecs } = currentTurnRecords(lines);
   const results = new Map();
   for (const o of turnRecs) {
     const c = o?.message?.content;
@@ -173,9 +224,14 @@ export function claudeTurnEvents(lines, { host = 'claude' } = {}) {
       if (['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(u.name) || (codex && u.name === 'apply_patch')) {
         events.push({ kind: 'change', what: `${u.name} ${input.file_path || input.notebook_path || ''}`.trim() });
       } else if (u.name === 'Bash') {
+        const unbound = compoundReason(input.command);
         for (const seg of segments(input.command)) {
           if (segmentMutates(seg)) events.push({ kind: 'change', what: seg.slice(0, 120) });
-          else if (segmentChecks(seg)) events.push({ kind: 'check', what: seg.slice(0, 120), name: checkName(seg), ...result });
+          else if (segmentChecks(seg)) {
+            const cmd = unbound ? seg : withoutSafeRedirects(seg);
+            events.push({ kind: 'check', what: cmd.slice(0, 120), command: cmd.slice(0, 400), name: checkName(seg), ...result,
+              ...(unbound ? { unbound: `the command uses ${unbound}, so its exit status is not this check's`, heads: headsOf(seg) } : {}) });
+          }
         }
       } else if (u.name === 'Agent' || u.name === 'Task') {
         if (!READ_ONLY_AGENTS.test(String(input.subagent_type || ''))) events.push({ kind: 'change', what: `${u.name} ${input.subagent_type || 'agent'}` });
@@ -187,7 +243,7 @@ export function claudeTurnEvents(lines, { host = 'claude' } = {}) {
       }
     }
   }
-  return { boundaryFound, events };
+  return { boundaryFound, prompt: turnPrompt, openerId, events };
 }
 
 /** Verification that ran AFTER the last state change this turn, with a present, non-error result. */
@@ -195,8 +251,12 @@ export function postChangeVerification(turn) {
   const events = turn?.events || [];
   let lastChange = -1;
   events.forEach((e, i) => { if (e.kind === 'change') lastChange = i; });
-  const checks = events.slice(lastChange + 1).filter((e) => e.kind === 'check' && e.present && !e.error);
-  return { lastChange: lastChange >= 0 ? events[lastChange].what : null, checks,
+  const after = events.slice(lastChange + 1).filter((e) => e.kind === 'check' && e.present && !e.error);
+  // `checks` is STRICT (binds a claim or a promise). `maskedChecks` ran with output and no error, but the command
+  // is a pipe / `||` / `;` / file redirect, so its exit status is not attributable: counted only as "a check ran".
+  const checks = after.filter((e) => !e.unbound);
+  const maskedChecks = after.filter((e) => e.unbound);
+  return { lastChange: lastChange >= 0 ? events[lastChange].what : null, checks, maskedChecks,
     staleChecks: events.slice(0, Math.max(0, lastChange)).filter((e) => e.kind === 'check').length };
 }
 
@@ -214,16 +274,19 @@ export function readClaudeTurn(transcriptPath, { read = readSettledTranscript, h
  */
 export function auditCompletionClaims(message, { turn = null, host = 'claude' } = {}) {
   const claims = extractCompletionClaims(message);
-  if (!claims.length) return { verdict: 'NONE', claims };
+  if (!claims.length) return { verdict: 'NONE', claims, outcomes: [] };
   const text = String(message || '');
   const verification = turn ? postChangeVerification(turn) : null;
-  const names = verification?.checks.map((c) => String(c.name || '').toLowerCase()).filter((n) => n.length >= 3) || [];
+  // Naming a check that ran is not binding it: masked checks count here so an inline mention is not 'unnamed'; transcriptOk below still uses strict checks only.
+  const names = verification ? [...verification.checks, ...verification.maskedChecks].map((c) => String(c.name || '').toLowerCase()).filter((n) => n.length >= 3) : [];
   const namesCheck = NAMED_CHECK.test(text) || names.some((n) => text.toLowerCase().includes(n));
   const disclosesGaps = DISCLOSES_GAPS.test(strippedProse(text).replace(/```[\s\S]*?```/g, ''))
     || DISCLOSES_GAPS.test(text);
   const problems = [];
   if (!turn) problems.push(`this host's (${host}) transcript is unavailable or not parsed, so whether a check ran after the change is UNKNOWN`);
-  else if (!verification.checks.length) {
+  else if (!verification.checks.length && verification.maskedChecks.length) {
+    problems.push('a check ran after the last change, but its command uses a pipe, `||`, `;` or a file redirect, so its exit status is not attributable to it; completion is UNKNOWN');
+  } else if (!verification.checks.length) {
     problems.push(verification.lastChange
       ? `no end-to-end check ran this turn after the last change (${verification.lastChange})`
       : 'no end-to-end check ran this turn');
@@ -236,7 +299,81 @@ export function auditCompletionClaims(message, { turn = null, host = 'claude' }
   if (transcriptOk && namesCheck && disclosesGaps && !scopedCheck) problems.push('observed checks cover only their executed scope; whole-task completion is UNKNOWN');
   const verdict = transcriptOk && namesCheck && disclosesGaps && scopedCheck ? 'OBSERVED_CHECK'
     : namesCheck && disclosesGaps ? 'UNKNOWN' : 'FAIL';
-  return { verdict, claims, verification, namesCheck, disclosesGaps, problems };
+  return { verdict, claims, verification, namesCheck, disclosesGaps, problems, outcomes: claimOutcomes(claims, text, turn) };
+}
+
+// ── per-claim outcomes (#425) ───────────────────────────────────────────────────────────────────
+// Evidence per claimed outcome, NOT completion authority: `authority:false` always, the verdict above is
+// computed without it, and no state here is PASS. A claim is `observed-check` only when its own sentence
+// (or a line-start `Verified:` line) NAMES the command of a check that ran after the last change, produced
+// output and did not error. Anything else is reported as what it is: stale, failed, or unbound.
+const VERIFIED_LINE = /(?:^|\n)[ \t]*(?:[-*•][ \t]*|\*\*)*verified\b[^\n:—–]{0,4}?(?:\*\*)?[ \t]*[:—–][ \t]*([^\n]+)/gi;
+// Env-var prefixes are part of the command (`SKIP_HOOKS=1 npm run x` is not `npm run x`): never stripped.
+const squash = (value) => String(value || '').replace(/\s+/g, ' ').trim().toLowerCase();
+/** `hay` contains `cmd` as a whole command: not preceded by an env-var assignment or a word character. */
+export function containsCommand(hay, cmd) {
+  const h = String(hay || ''); const c = String(cmd || '');
+  if (!c) return false;
+  for (let at = h.indexOf(c); at >= 0; at = h.indexOf(c, at + 1)) {
+    const before = h.slice(0, at);
+    if (/[\w./:=-]$/.test(before) || /^[\w:-]/.test(h.slice(at + c.length))) continue;
+    if (/(?:^|[\s`'"(])[A-Za-z_][A-Za-z0-9_]*=\S*\s+$/.test(before)) continue;
+    return true;
+  }
+  return false;
+}
+
+function rawSentenceOf(message, claim) {
+  for (const raw of String(message || '').split(/(?<=[.!?])\s+|\n+/)) if (sentences(raw).includes(claim.text)) return raw;
+  return claim.text;
+}
+
+export function claimOutcomes(claims, message, turn) {
+  const events = turn?.events || [];
+  let lastChange = -1;
+  events.forEach((e, i) => { if (e.kind === 'change') lastChange = i; });
+  const checks = events.map((e, i) => ({ e, i })).filter(({ e }) => e.kind === 'check' && String(e.command || '').length >= 4);
+  const verifiedLines = [...String(message || '').matchAll(VERIFIED_LINE)].map((m) => squash(m[1])).join('\n');
+  return (claims || []).map((claim) => {
+    const own = squash(rawSentenceOf(message, claim));
+    const namedAll = checks.filter(({ e }) => { const c = squash(e.command); const hit = (h) => containsCommand(own, h) || containsCommand(verifiedLines, h);
+      return hit(c) || (e.unbound && (e.heads || []).some((h) => hit(squash(h)))); });
+    const named = namedAll.filter(({ e }) => !e.unbound);
+    const good = named.filter(({ e, i }) => i > lastChange && e.present && !e.error);
+    const state = good.length ? 'observed-check'
+      : named.some(({ e, i }) => i > lastChange && !(e.present && !e.error)) ? 'failed-check'
+        : named.length ? 'stale' : 'unbound';
+    const reason = state === 'unbound' ? namedAll.find(({ e }) => e.unbound)?.e.unbound : undefined;
+    return { claim: claim.text.slice(0, 200), state, ...(reason ? { reason } : {}),
+      checks: (state === 'observed-check' ? good : named).slice(-3).map(({ e }) => ({ command: e.command, name: e.name })), authority: false };
+  });
+}
+
+/**
+ * #425 (sparkling): the audit category of a correction, independent of wording. A correction is delivered
+ * at most once per session + user turn + category, so rewording the answer or waiting cannot rearm it.
+ */
+export function completionCategory(completion) {
+  const ids = (completion?.problems || []).map((p) => /unavailable or not parsed/.test(p) ? 'transcript-unavailable'
+    : /no end-to-end check ran/.test(p) ? 'no-check' : /not attributable/.test(p) ? 'check-unattributed' : /does not name the check/.test(p) ? 'check-unnamed'
+      : /does not disclose/.test(p) ? 'gaps-undisclosed' : /observed checks cover only/.test(p) ? 'scope' : 'other');
+  return `${completion?.verdict || 'NONE'}:${[...new Set(ids)].sort().join('+')}`;
+}
+
+/** Correction copy for a FAIL/UNKNOWN verdict. When checks DID run, ask for an outcome-by-outcome report. */
+export function completionCorrectionText(completion) {
+  const lead = `You claimed "${completion.claims[0].text.slice(0, 160)}" is done; ${completion.problems.join('; ')}.`;
+  return (completion.verification?.checks?.length || 0) + (completion.verification?.maskedChecks?.length || 0) > 0
+    ? `${lead} A check ran, but it does not cover every claim: report outcome by outcome, naming the check that ran for each claim or restating it as UNVERIFIED.`
+    : `${lead} Run the real consumer path, or restate it as UNVERIFIED.`;
+}
+
+/** Non-blocking advisory text: which claims have an observed check and which do not. */
+export function outcomeAdvisoryText(completion) {
+  const lines = (completion.outcomes || []).map((o) => `- ${o.state}: "${o.claim.slice(0, 100)}"${o.checks.length ? ` (${o.checks.map((c) => c.command).join('; ')})` : ''}`);
+  const masked = !(completion.verification?.checks?.length) && (completion.verification?.maskedChecks?.length || 0) > 0;
+  return `A check ran after the last change${masked ? ' (its command uses a pipe, `||`, `;` or a redirect, so its exit status is not attributable to it)' : ''} and the answer names it and discloses what is not verified. Per claimed outcome:\n${lines.join('\n')}\n`
+    + 'This is evidence per outcome, not completion authority: completion stays UNKNOWN. Not blocking: more checks or rewording cannot change it.';
 }
 
 // ── promises (first-person commitments) ─────────────────────────────────────────────────────────
@@ -277,7 +414,24 @@ export function extractCommitments(message) {
       out.push({ text, key });
     }
   }
-  return out.slice(0, PROMISE_CAP_PER_TURN);
+  return out.slice(0, PROMISE_CAP_PER_TURN).map((p) => {
+    const evidenceCommands = promiseCommands(message, p.key);
+    return evidenceCommands.length ? { ...p, evidenceCommands } : p;
+  });
+}
+
+// #369: inline-code commands in the promise's own sentence are what the promise says it will run. They are
+// recorded at capture (max 2) so a later observed check can be matched to them; prose alone never is.
+const COMMAND_SPAN = /`([^`\n]{4,160})`/g;
+function promiseCommands(message, key) {
+  for (const raw of String(message || '').split(/(?<=[.!?])\s+|\n+/)) {
+    const prose = strippedProse(raw).replace(/^\s*(?:\d+[.)]|[-*•])\s+/, '').trim();
+    const action = PROMISE_LEAD.exec(prose)?.[1] ?? prose;
+    if (normalizePromise(action) !== key) continue;
+    const found = [...raw.matchAll(COMMAND_SPAN)].map((m) => squash(m[1])).filter((c) => /\s/.test(c) || c.startsWith('./'));
+    return [...new Set(found)].slice(0, 2);
+  }
+  return [];
 }
 
 const STOP = new Set(['the', 'a', 'an', 'and', 'or', 'to', 'of', 'in', 'on', 'for', 'with', 'it', 'is', 'are',
@@ -304,6 +458,10 @@ const unquoted = (value) => String(value).replace(/"([^"\n]{0,300})"|“([^”\n
 export function promiseClosingClaim(completion, answer, promiseText) {
   // DORMANT: auditCompletionClaims no longer returns PASS (only OBSERVED_CHECK/UNKNOWN/FAIL/NONE), so this never closes a promise today.
   if (completion?.verdict !== 'PASS') return null;
+  return matchingClaim(completion, answer, promiseText);
+}
+
+function matchingClaim(completion, answer, promiseText) {
   const direct = completion.claims.find((c) => claimClosesPromise(c.text, promiseText));
   if (direct) return direct;
   for (const raw of String(answer || '').split(/(?<=[.!?])\s+|\n+/)) {
@@ -313,3 +471,19 @@ export function promiseClosingClaim(completion, answer, promiseText) {
   }
   return null;
 }
+
+/**
+ * #369: the evidence that moves a promise to the NON-completed state `evidenced`, or null. Never `done`, never
+ * PASS, never authority. ALL must hold: a command the promise itself named ran after the last change with
+ * output and no error; the answer names that command and states what is not verified; a claim sentence
+ * matches the promise; the verdict is not FAIL. (Same-session ownership is checked by the caller.)
+ */
+export function promiseEvidence(completion, answer, item) {
+  const commands = Array.isArray(item?.evidenceCommands) ? item.evidenceCommands.map(squash) : [];
+  if (!commands.length || !completion?.claims?.length || !['OBSERVED_CHECK', 'UNKNOWN'].includes(completion.verdict)
+    || completion.disclosesGaps !== true) return null;
+  const said = squash(answer);
+  const check = (completion.verification?.checks || []).find((c) => !c.unbound && commands.includes(squash(c.command)) && containsCommand(said, squash(c.command)));
+  const claim = check && matchingClaim(completion, answer, item.text);
+  return claim ? { command: squash(check.command), check: check.what, claim: claim.text, auditVerdict: completion.verdict, authority: false } : null;
+}