ruvnet-brain 4.7.21 → 4.7.22

package/plugin/scripts/continuation-gate.mjs

@@ -54,6 +54,7 @@ import { readSettledTranscript } from './turn-outcome-capture.mjs';
 import { continuationProjectIdentity, authorizedContinuationObjective, authorizedPromiseItems, assistantCommitmentOwned, setAssistantCommitmentState } from './continuation-objective.mjs';
 import {
   auditCompletionClaims, readClaudeTurn, extractCommitments, promiseClosingClaim,
+  promiseEvidence, completionCorrectionText, outcomeAdvisoryText, completionCategory,
   PROMISE_KIND, PROMISE_CAP_OPEN,
 } from './completion-claim-evidence.mjs';
 import { writeAtomic } from './user-settings.mjs';
@@ -376,6 +377,7 @@ const HOST = process.env.RUVNET_HOOK_HOST === 'codex' ? 'codex' : 'claude';
  * nativeTurnLines reader, #423) are parsed; a Codex rollout that cannot be read or has no current-turn
  * boundary stays UNKNOWN (completion-claim-evidence.mjs header). Fails open: a throw is NONE.
  */
+let completionTurnKey = null;
 const completion = (() => {
   const message = String(hookInput.last_assistant_message || '');
   if (!message || !hookInput.session_id) return { verdict: 'NONE', claims: [] };
@@ -384,7 +386,15 @@ const completion = (() => {
     // Claude always sends a JSONL transcript; one we cannot read is OUR failure, and a Stop hook
     // fails open on its own machinery (ADR-074 failure semantics) — never a correction request.
     // Missing native evidence stays UNKNOWN; it cannot silently validate a completion claim.
-    return auditCompletionClaims(message, { turn, host: HOST });
+    const audit = auditCompletionClaims(message, { turn, host: HOST });
+    // Turn identity for correction de-duplication (#425): the host's native id (Claude prompt_id, Codex
+    // turn_id), else the transcript record that opened this turn (uuid or position, never its text: a repeated
+    // "continue" is a new turn). Never a clock.
+    const native = HOST === 'codex' ? hookInput.turn_id : hookInput.prompt_id;
+    const opener = typeof native === 'string' && native.trim() ? `native:${native}`
+      : turn?.boundaryFound && turn.openerId ? `opener:${turn.openerId}` : '';
+    if (opener) completionTurnKey = crypto.createHash('sha256').update(JSON.stringify([hookInput.session_id, opener])).digest('hex').slice(0, 24);
+    return audit;
   } catch { return { verdict: 'NONE', claims: [] }; }
 })();
 
@@ -416,6 +426,12 @@ function promiseBookkeeping() {
         changed = true;
       }
     }
+    // #369: observed evidence moves a promise to `evidenced` (NOT done, never forced again); same session only.
+    for (const item of led.items) {
+      if (!assistantCommitmentOwned(item, hookInput.session_id, projectIdentity) || !(item.state === undefined || item.state === 'active')) continue;
+      const closureEvidence = promiseEvidence(completion, hookInput.last_assistant_message, item);
+      if (closureEvidence) { Object.assign(item, { state: 'evidenced', stateAt: at, closureEvidence }); changed = true; }
+    }
     const owned = led.items.filter((i) => assistantCommitmentOwned(i, hookInput.session_id, projectIdentity));
     const openKeys = new Set(owned.map((i) => i.key));
     let activeCount = owned.filter((i) => i.state === undefined || i.state === 'active').length;
@@ -428,6 +444,7 @@ function promiseBookkeeping() {
       led.items.push({ schemaVersion: 1, kind: PROMISE_KIND, text: promise.text, key: promise.key, done: false, state: 'active', at,
         projectId: pid, worktreeIds: [projectIdentity.worktreeId], sessionIds: [hookInput.session_id],
         capturedFrom: { sessionId: hookInput.session_id },
+        ...(promise.evidenceCommands ? { evidenceCommands: promise.evidenceCommands } : {}),
         authorization: { kind: 'owner-mandate', reference: 'i-will-is-a-contract-2026-09-15' } });
       changed = true;
     }
@@ -727,14 +744,12 @@ if (observations.length && STOP_NUDGES_FULL) console.error(JSON.stringify({ kind
 // re-running checks or rewording cannot satisfy it. The verdict stays UNKNOWN (never PASS: it closes
 // no promise and grants no completion authority); under `full` the limitation is reported, not enforced.
 const scopeOnlyUnknown = completion.verdict === 'UNKNOWN' && completion.namesCheck === true
-  && completion.disclosesGaps === true && (completion.verification?.checks?.length || 0) > 0;
+  && completion.disclosesGaps === true
+  && ((completion.verification?.checks?.length || 0) + (completion.verification?.maskedChecks?.length || 0)) > 0;
 if (scopeOnlyUnknown && STOP_NUDGES_FULL) console.error(JSON.stringify({ kind: 'completion-scope-advisory',
-  authority: false, verdict: 'UNKNOWN', text: `"${completion.claims[0].text.slice(0, 160)}": a check ran after the last change`
-    + ' and the answer names it and discloses what is not verified. This gate cannot judge whether that task outcome'
-    + ' is complete (it only qualifies check-scoped statements), so completion stays UNKNOWN. Not blocking: more checks'
-    + ' or rewording cannot change this verdict.' }));
+  authority: false, verdict: 'UNKNOWN', outcomes: completion.outcomes, text: outcomeAdvisoryText(completion) }));
 const completionWork = ['FAIL', 'UNKNOWN'].includes(completion.verdict) && !scopeOnlyUnknown ? [{
-  text: `You claimed "${completion.claims[0].text.slice(0, 160)}" is done; ${completion.problems.join('; ')}. Run the real consumer path, or restate it as UNVERIFIED.`,
+  text: completionCorrectionText(completion),
   at: new Date(nowMs).toISOString(), derived: true, kind: 'completion-claim-integrity',
 }] : [];
 // DECISION RECORDS (ADR-105 §8, ADR-106): a turn that CREATED an ADR in an adopted project must also
@@ -880,6 +895,36 @@ try {
   if (touched) fs.writeFileSync(FORCES, JSON.stringify(counts));
   if (retired.length) { save(led); forceable = forceable.filter((i) => !retired.includes(i)); }
 } catch { /* bookkeeping only: never break a turn */ }
+/**
+ * A completion correction is delivered at most once per native session + user turn + audit category (#425,
+ * sparkling). The marker is an exclusive-create file (the same primitive as the cooldown lock), so two racing
+ * Stop hooks cannot both deliver. Rewording or elapsed time does not rearm it; a new user turn does. With no
+ * turn identity the correction degrades to a non-blocking advisory carrying the ORIGINAL verdict (never PASS).
+ * This only ever removes a blocking item.
+ */
+try {
+  const item = forceable.find((i) => i.kind === 'completion-claim-integrity');
+  if (item) {
+    const category = completionCategory(completion);
+    let deliver = false;
+    if (!completionTurnKey) {
+      console.error(JSON.stringify({ kind: 'completion-correction-advisory', authority: false, verdict: completion.verdict,
+        category, reason: 'turn identity unavailable; a correction cannot be de-duplicated, so it is not enforced', text: item.text }));
+    } else {
+      const id = crypto.createHash('sha256').update(JSON.stringify([hookInput.session_id, completionTurnKey, category])).digest('hex').slice(0, 24);
+      const dir = `${LEDGER}.completion-delivered`;
+      try {
+        fs.mkdirSync(dir, { recursive: true });
+        fs.writeFileSync(path.join(dir, id), new Date(nowMs).toISOString(), { flag: 'wx' });
+        deliver = true;
+        for (const f of fs.readdirSync(dir)) {   // markers are only needed for the turn; keep a week
+          try { if (nowMs - fs.statSync(path.join(dir, f)).mtimeMs > 7 * 86_400_000) fs.rmSync(path.join(dir, f), { force: true }); } catch { /* raced */ }
+        }
+      } catch { /* already delivered this turn/category, or cannot persist: do not block */ }
+    }
+    if (!deliver) forceable = forceable.filter((i) => i !== item);
+  }
+} catch { forceable = forceable.filter((i) => i.kind !== 'completion-claim-integrity'); }
 if (!forceable.length) process.exit(EXIT_ALLOW);
 if (deferralState && forceable.some((i) => i.kind === 'no-deferral')) {
   try { for (const [k, v] of Object.entries(deferralState.counts)) if (nowMs - Date.parse(v?.at) > 7 * 86_400_000) delete deferralState.counts[k];

package/plugin/scripts/lesson-gate.mjs

@@ -80,6 +80,8 @@ import {
   CONFIG_ROOT,
   loadLessons,
   lessonsFor,
+  projectNameFor,
+  lessonApplies,
   ENFORCEMENT,
   STATUS,
   ORIGIN,
@@ -263,42 +265,8 @@ const gateState = event ? readGateState() : {};
  * the fastest way to make someone uninstall a nudge is to nudge them about something that has
  * nothing to do with what they are doing.
  */
-const HERE = (() => {
-  let d = process.cwd();
-  for (let i = 0; i < 12; i++) {
-    if (fs.existsSync(path.join(d, '.git'))) break;
-    const up = path.dirname(d);
-    if (up === d) { d = process.cwd(); break; }
-    d = up;
-  }
-  return path.basename(d);
-})();
-/**
- * A "suffix match" for project names, bounded so it cannot fire on a bare shared tail. `a` matches
- * `b` when `b` is a whole path/name SEGMENT suffix of `a` — the character immediately before it must
- * be a separator, never a mid-word letter. Without this, "Sentry" matched inside "WhitSentry" and any
- * project name that merely happens to end another's, which is the exact cross-project leak the
- * 2026-07-22 project-scope fix (this same function, below) was written to close.
- */
-const segmentSuffixMatch = (a, b) => {
-  if (a === b) return true;
-  if (a.length <= b.length || !a.endsWith(b)) return false;
-  return /[-_/]/.test(a[a.length - b.length - 1]);
-};
-
-/** Does this lesson belong to the project we are standing in? Match is loose on purpose — stored
- *  names carry prefixes like `Code-` that the directory name does not — but bounded to a real
- *  delimiter so it cannot match a bare, accidental shared suffix between unrelated projects. */
-const isHome = (l) => {
-  const ps = Array.isArray(l.projects) ? l.projects : [];
-  if (!ps.length) return true;                       // unscoped: applies anywhere, by declaration
-  return ps.some((p) => {
-    const n = String(p).replace(/^Code-/, '');
-    return n === HERE || String(p) === HERE
-      || segmentSuffixMatch(HERE, n) || segmentSuffixMatch(n, HERE);
-  });
-};
-const isUniversal = (l) => Array.isArray(l.projects) && l.projects.length >= 2;
+const HERE = projectNameFor(process.cwd());
+const applies = (l) => lessonApplies(l, HERE);
 
 // Apply the mutate-machine predicate defined above. `mutate-machine` is requested for EVERY Bash
 // call (plugin/scripts/lesson-hooks.sh:98) — it is the ONLY trigger the dispatcher fires unconditionally
@@ -313,10 +281,10 @@ const effectiveTriggers = command === null
 const seen = new Set();
 const candidates = [];
 for (const t of effectiveTriggers) {
-  for (const l of lessonsFor(t, lessons.filter((l) => isHome(l) || isUniversal(l)), { limit: 3 })) {
+  for (const l of lessonsFor(t, lessons.filter(applies), { limit: 3 })) {
     if (seen.has(l.id)) continue;
-    // Away from home, only a lesson with cross-project evidence may speak.
-    if (!isHome(l) && !isUniversal(l)) continue;
+    // Away from home, only a lesson with cross-project evidence may speak (lessonApplies: one rule, shared with the Console).
+    if (!applies(l)) continue;
     seen.add(l.id); candidates.push(l);
   }
 }

package/plugin/scripts/lesson-scope.mjs

@@ -0,0 +1,51 @@
+/**
+ * Where a lesson applies: the ONE project-identity and applicability rule, shared by plugin/scripts/lesson-gate.mjs and
+ * the Console (scripts/onboarding-console.mjs). Re-exported from lesson-store.mjs. Pure apart from the git/fs reads
+ * projectNameFor makes, which are bounded.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+
+/**
+ * THE project identity lessons are scoped by: the folder name of the CANONICAL project root (the primary checkout,
+ * the same root resolveProjectStore uses for the store), so a linked worktree `feature-x` is the project it belongs to,
+ * not its own name. Falls back to the nearest folder holding a `.git`, then to the folder itself, when the resolver
+ * refuses (the name is only a lesson-scope label; a refusal must not silence the gate).
+ */
+export function projectNameFor(cwd = process.cwd()) {
+  try { return path.basename(resolveProjectStore({ projectDir: cwd, gitTimeoutMs: 500 }).projectRoot); } catch { /* fall through */ }
+  let d = cwd;
+  for (let i = 0; i < 12; i++) {
+    if (fs.existsSync(path.join(d, '.git'))) return path.basename(d);
+    const up = path.dirname(d);
+    if (up === d) break;
+    d = up;
+  }
+  return path.basename(cwd);
+}
+
+/**
+ * `a` matches `b` when `b` is a whole path/name SEGMENT suffix of `a`: the character before it must be a separator,
+ * never a mid-word letter ("Sentry" must not match inside "WhitSentry").
+ */
+export function segmentSuffixMatch(a, b) {
+  if (a === b) return true;
+  if (a.length <= b.length || !a.endsWith(b)) return false;
+  return /[-_/]/.test(a[a.length - b.length - 1]);
+}
+
+/**
+ * THE applicability rule (lesson-gate and the Console share it): a lesson applies to a project when it is unscoped,
+ * scoped to that project (stored names may carry a `Code-` prefix the folder lacks), or proven in two or more
+ * projects (cross-project rediscovery is what makes it universal, ADR-029).
+ */
+export function lessonApplies(lesson, projectName) {
+  const ps = Array.isArray(lesson?.projects) ? lesson.projects : [];
+  if (!ps.length || ps.length >= 2) return true;
+  const here = String(projectName);
+  return ps.some((p) => {
+    const n = String(p).replace(/^Code-/, '');
+    return n === here || String(p) === here || segmentSuffixMatch(here, n) || segmentSuffixMatch(n, here);
+  });
+}

package/plugin/scripts/lesson-store.mjs

@@ -24,7 +24,7 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { SOURCE_CLASS, STATUS, isUntouchedOwnerSeedRow } from './lesson-provenance.mjs';
-
+export { projectNameFor, segmentSuffixMatch, lessonApplies } from './lesson-scope.mjs';
 export { BUNDLED_OWNER_SEED_IDS, SOURCE_CLASS, STATUS, isUntouchedOwnerSeedRow } from './lesson-provenance.mjs';
 
 /** Resolve fixture/plugin configuration without mutating the child process account HOME. */

package/plugin/scripts/ruflo-bin.mjs

@@ -109,7 +109,7 @@ export function rufloInvocationOrPlain(binary, args, opts) {
  * @param {{ env?: Record<string,string|undefined>, candidates?: string[] }} [opts]
  * @returns {{ node: string, entry: string }|null}
  */
-export function nativeNodeFor(binary, { env = process.env, candidates } = {}) {
+export function nativeNodeFor(binary, { env = process.env, candidates, deadlineAt = Infinity } = {}) {
   let entry;
   try { entry = fs.realpathSync(binary); } catch { return null; }
   const addon = findAddon(path.dirname(path.dirname(entry)));
@@ -123,21 +123,29 @@ export function nativeNodeFor(binary, { env = process.env, candidates } = {}) {
   let chosen = null;
   // Bounded: this runs inside hooks that have their own deadline (SessionStart is stopped 1.5 s early), so a
   // wedged candidate must cost seconds at most and then leave the invocation exactly as it was.
+  // A caller's absolute deadline caps the probes too (#501); a probe cut short by it proves nothing, so it is not cached.
   const started = Date.now();
+  let cut = false;
   for (let i = 0; i < list.length; i += 1) {
-    if (Date.now() - started > PROBE_BUDGET_MS) break;
-    const r = spawnSync(list[i], ['-e', probe], { stdio: 'ignore', timeout: PROBE_TIMEOUT_MS, windowsHide: true });
+    const budgetLeft = PROBE_BUDGET_MS - (Date.now() - started);
+    const deadlineLeft = deadlineAt - Date.now();
+    if (Math.min(budgetLeft, deadlineLeft) <= 0) { cut = deadlineLeft <= 0; break; }
+    const probeTimeout = Math.max(1, Math.floor(Math.min(PROBE_TIMEOUT_MS, budgetLeft, deadlineLeft)));
+    const deadlineLimited = deadlineLeft < Math.min(PROBE_TIMEOUT_MS, budgetLeft);
+    const r = spawnSync(list[i], ['-e', probe], { stdio: 'ignore', timeout: probeTimeout, windowsHide: true });
     if (r.status === 0) { chosen = i === 0 ? null : { node: list[i], entry }; break; }
+    // This probe's own timeout came from the deadline, not from PROBE_TIMEOUT_MS: it proves nothing, so do not cache.
+    if (r.error?.code === 'ETIMEDOUT' && deadlineLimited) { cut = true; break; }
   }
-  nativeNodeCache.set(cacheKey, chosen);
+  if (!cut) nativeNodeCache.set(cacheKey, chosen);
   return chosen;
 }
 
 // npm's Windows .cmd shim cannot be spawned without a shell. Resolve the declared entry
 // inside that same managed installation and pass argv directly to Node instead.
-export function rufloInvocation(binary, args, { platform = process.platform, env = process.env, nodeCandidates } = {}) {
+export function rufloInvocation(binary, args, { platform = process.platform, env = process.env, nodeCandidates, deadlineAt } = {}) {
   if (platform !== 'win32') {
-    const native = nativeNodeFor(binary, { env, candidates: nodeCandidates });
+    const native = nativeNodeFor(binary, { env, candidates: nodeCandidates, deadlineAt });
     return native ? { executable: native.node, args: [native.entry, ...args] } : { executable: binary, args };
   }
   if (!/\.cmd$/i.test(binary)) return { executable: binary, args };

package/plugin/scripts/ruflo-memory-hooks.mjs

@@ -16,11 +16,12 @@
 import fs from 'node:fs';
 import crypto from 'node:crypto';
 import path from 'node:path';
-import { execFile, execFileSync, spawnSync } from 'node:child_process';
+import { execFileSync, spawn, spawnSync } from 'node:child_process';
 import os from 'node:os';
 import { resolveRuflo, rufloInvocationOrPlain, rufloRunDir, rufloScratchRoot } from './ruflo-bin.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
 import { checkpointNamespaces, newestOfFamily } from './checkpoint-keys.mjs';
+import { openBatchSession } from './agentdb-recall-process.mjs';
 
 export const CURATED_PREFIX = 'project-state-current-';
 export const AUTO_PREFIX = 'project-state-auto-';
@@ -29,16 +30,30 @@ export const AUTO_PREFIX = 'project-state-auto-';
  * The SAME store and namespace turn capture uses (review M2): the canonical project's `.swarm/memory.db`,
  * which a linked git worktree shares with its main checkout. Every git call is bounded by the deadline.
  */
-export function projectStore(projectDir, { deadlineAt = Date.now() + 3000 } = {}) {
-  let root = projectDir; let db = path.join(projectDir, '.swarm', 'memory.db');
+export function projectStore(projectDir, { deadlineAt = Date.now() + 3000, resolve = resolveProjectStore } = {}) {
+  let resolved;
   try {
     const gitTimeoutMs = Math.max(1, Math.min(1000, Math.floor(deadlineAt - Date.now())));
-    const resolved = resolveProjectStore({ projectDir, gitTimeoutMs, deadlineAt });
-    root = resolved.projectRoot; db = resolved.canonicalAgentDbPath;
-  } catch { /* unresolvable (or out of budget): treated as not adopted below only if no store exists here */ }
+    resolved = resolve({ projectDir, gitTimeoutMs, deadlineAt });
+  } catch (error) {
+    // A refusal (invalid Git marker, identity timeout, symlink/hard-link escape) is never permission to use
+    // the raw local `.swarm/memory.db` instead (#503). A valid non-Git project resolves without throwing.
+    const reason = refusalReason(error);
+    return { root: projectDir, db: null, adopted: false, namespace: path.basename(projectDir), refused: reason,
+      // A local store is only "withheld" when one exists; a project that never adopted stays quiet.
+      withheld: fs.existsSync(path.join(projectDir, '.swarm', 'memory.db')),
+      timedOut: /deadline exceeded|timed out/i.test(String(error?.message || '')) };
+  }
+  const root = resolved.projectRoot; const db = resolved.canonicalAgentDbPath;
   return { root, db, adopted: fs.existsSync(db), namespace: path.basename(root) };
 }
 
+/** The resolver's own short reason; never a path, never a stack (they can carry private locations). */
+function refusalReason(error) {
+  const text = String(error?.message || '').split('\n')[0].slice(0, 120);
+  return text && !/[\\/]/.test(text) ? text : 'canonical project store could not be resolved';
+}
+
 /**
  * The spawn options every ruflo call here uses. `--path` pins the store, so the working directory only receives
  * what ruflo writes beside itself (`ruvector.db`, `.swarm/hnsw.*`, verified on 3.56.9). Run it in a fresh private
@@ -51,16 +66,101 @@ export function rufloSpawnOptions(db, env = process.env) {
   return { cwd, env: { ...env, RUFLO_DAEMON_AUTOSTART: '0', CLAUDE_FLOW_AUTO_UPDATE: 'false' }, cleanup: () => { try { fs.rmSync(cwd, { recursive: true, force: true }); } catch { /* swept later as a stale run- dir */ } } };
 }
 
-/** One `ruflo memory <args>` call, bounded by the caller's deadline. Resolves, never rejects. */
-export function rufloMemory(args, { db, env = process.env, bin = resolveRuflo({ env }), deadlineAt = Date.now() + 3000 } = {}) {
-  const timeout = Math.max(1, Math.floor(deadlineAt - Date.now()));
+/** SIGKILL the child's whole process group (it is spawned detached, so it leads one); the child alone if it does not. */
+function killGroup(child) {
+  try {
+    if (process.platform !== 'win32' && Number.isInteger(child?.pid) && child.pid > 1) process.kill(-child.pid, 'SIGKILL');
+    else child?.kill('SIGKILL');
+  } catch { try { child?.kill('SIGKILL'); } catch { /* already gone */ } }
+}
+
+const WATCHDOG_GRACE_MS = 2000;
+// Runs in `node -e`: argv = [deadlineMs (0 = none), file, ...args]. Exit code is the command's; 127 when it cannot start.
+const WATCHDOG = `const {spawn}=require('node:child_process');
+const ms=Number(process.argv[1]);const file=process.argv[2];const args=process.argv.slice(3);
+const killAll=()=>{try{process.kill(-process.pid,'SIGKILL')}catch{process.exit(137)}};
+if(ms>0)setTimeout(killAll,ms);
+process.stdin.on('end',killAll);process.stdin.on('close',killAll);process.stdin.on('error',killAll);process.stdin.resume();
+const c=spawn(file,args,{stdio:['ignore','inherit','inherit']});
+c.on('error',(e)=>{process.stderr.write(String(e.message)+'\\n');process.exit(127)});
+c.on('close',(code)=>process.exit(code===null?1:code));`;
+
+/**
+ * execFile-shaped runner that really starts the child as its OWN process group. Node's execFile silently drops the
+ * `detached` option (verified: the child stayed in the caller's group), so a group kill needs spawn itself.
+ * Calls back once with (error, stdout, stderr); `error.killed` is true only when WE killed it (timeout/overflow).
+ */
+export function spawnDetached(file, args, opts = {}, cb = () => {}) {
+  // POSIX: the real command runs under a tiny watchdog that leads the new process group. The watchdog (a) SIGKILLs its
+  // whole group at timeout + grace on its own clock and (b) does so the moment its stdin (a pipe held by THIS process)
+  // reaches EOF, which is what happens when this process is SIGKILLed. So a hook killed by its host cannot leave a
+  // ruflo child or grandchild behind, and a child can never outlive its own deadline. Windows has no process groups
+  // here: it keeps the previous behaviour (direct spawn, no watchdog, child-only kill), so the bound there is the parent's timer alone.
+  const guarded = process.platform !== 'win32';
+  const child = guarded
+    ? spawn(process.execPath, ['-e', WATCHDOG, String(opts.timeout > 0 ? opts.timeout + WATCHDOG_GRACE_MS : 0), file, ...args],
+      { cwd: opts.cwd, env: opts.env, detached: true, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })
+    : spawn(file, args, { cwd: opts.cwd, env: opts.env, windowsHide: true, stdio: ['ignore', 'pipe', 'pipe'] });
+  if (guarded) child.stdin.on('error', () => { /* watchdog gone */ });
+  let out = ''; let err = ''; let bytes = 0; let killed = false; let done = false;
+  const finish = (error) => { if (done) return; done = true; clearTimeout(timer); cb(error, out, err); };
+  const take = (chunk, into) => {
+    bytes += chunk.length;
+    if (bytes > (opts.maxBuffer || Infinity)) { killed = true; killGroup(child); return into; }
+    return into + chunk;
+  };
+  child.stdout.setEncoding('utf8'); child.stderr.setEncoding('utf8');
+  child.stdout.on('data', (c) => { out = take(c, out); });
+  child.stderr.on('data', (c) => { err = take(c, err); });
+  const timer = opts.timeout > 0 ? setTimeout(() => { killed = true; killGroup(child); }, opts.timeout) : null;
+  child.on('error', (e) => finish(e));
+  child.on('close', (code, signal) => finish(code === 0 && !killed ? null : Object.assign(new Error(`exited ${code ?? signal}`), { code, signal, killed })));
+  return child;
+}
+
+/**
+ * One `ruflo memory <args>` call, bounded by the caller's ABSOLUTE deadline and cancelled by its signal. Resolves,
+ * never rejects. The child's timeout is what is left AFTER interpreter preparation, and nothing is launched once
+ * the deadline has passed or the signal has fired (#501). The signal is NOT handed to execFile (Node would send
+ * SIGTERM and call back before the child exits): on abort the child is SIGKILLed here and the result resolves
+ * only once it has closed.
+ */
+export function rufloMemory(args, { db, env = process.env, bin = resolveRuflo({ env }), deadlineAt = Date.now() + 3000, signal,
+  run = spawnDetached, invoke = rufloInvocationOrPlain } = {}) {
   return new Promise((resolve) => {
-    if (!bin) return resolve({ ok: false, stdout: '', error: 'global Ruflo unavailable' });
+    const refuse = (error) => resolve({ ok: false, stdout: '', error });
+    if (!bin) return refuse('global Ruflo unavailable');
+    if (signal?.aborted) return refuse('cancelled');
+    if (deadlineAt - Date.now() <= 0) return refuse('deadline exceeded before launch');
     const spawnAt = rufloSpawnOptions(db, env);
-    const inv = rufloInvocationOrPlain(bin, ['memory', ...args, '--path', db], { env: spawnAt.env });
-    execFile(inv.executable, inv.args, { cwd: spawnAt.cwd, env: spawnAt.env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
-      // The ledger gets a fixed reason, never execFile's message (it embeds the whole argv: value, db path).
-      (error, stdout) => { spawnAt.cleanup(); resolve({ ok: !error, stdout: String(stdout || ''), error: error ? (error.killed ? 'timed out' : `ruflo memory ${args[0]} exited ${error.code ?? 'abnormally'}`) : null }); });
+    const inv = invoke(bin, ['memory', ...args, '--path', db], { env: spawnAt.env, deadlineAt });
+    const timeout = Math.floor(deadlineAt - Date.now());
+    if (signal?.aborted || timeout < 1) { spawnAt.cleanup(); return refuse(signal?.aborted ? 'cancelled' : 'deadline exceeded before launch'); }
+    let child; let onAbort; let timer; let timedOut = false;
+    // The ledger gets a fixed reason, never execFile's message (it embeds the whole argv: value, db path).
+    // The default runner starts it as its own process group (spawnDetached): abort and timeout kill the GROUP, so a grandchild (`sh -c 'sleep …'`) cannot
+    // outlive the call and keep running after its working directory is deleted under it.
+    child = run(inv.executable, inv.args, { cwd: spawnAt.cwd, env: spawnAt.env, timeout, killSignal: 'SIGKILL', encoding: 'utf8', maxBuffer: 8 * 1024 * 1024 },
+      (error, stdout) => {
+        clearTimeout(timer);
+        if (onAbort) signal.removeEventListener('abort', onAbort);
+        spawnAt.cleanup();
+        const reason = !error ? null : signal?.aborted ? 'cancelled'
+          : error.killed || timedOut ? 'timed out' : `ruflo memory ${args[0]} exited ${error.code ?? 'abnormally'}`;
+        resolve({ ok: !error, stdout: String(stdout || ''), error: reason });
+      });
+    // Backstop for an injected runner: kills the whole group a hair before any child-only timeout.
+    timer = setTimeout(() => { timedOut = true; killGroup(child); }, Math.max(1, timeout - 5));
+    if (signal) {
+      // Kill the child's group AND destroy its pipes. execFile's callback waits for stdout/stderr to close, so a grandchild
+      // that inherited them (`sh -c 'sleep …'`) held the result until the deadline (#501: measured 5006 ms).
+      // The group kill ends the grandchild; destroying the pipes releases the wait even if one escaped the group.
+      onAbort = () => {
+        killGroup(child);
+        for (const s of [child?.stdout, child?.stderr, child?.stdin]) { try { s?.destroy(); } catch { /* closed */ } }
+      };
+      if (signal.aborted) onAbort(); else signal.addEventListener('abort', onAbort, { once: true });
+    }
   });
 }
 
@@ -72,10 +172,21 @@ function parseJson(text) {
 const entriesOf = (json) => (Array.isArray(json) ? json : json?.entries || json?.results || []);
 
 async function listKeys(namespace, options, limit = 1000) {
+  if (options.session) {
+    // Ruflo's own list function in the one owned child (#429). 'fallback' = that route cannot answer: use the CLI.
+    const r = await options.session.list(namespace, limit, options.deadlineAt);
+    if (r.state === 'ok') return r.rows.filter((e) => typeof e?.key === 'string');
+    if (r.state !== 'fallback') return null;
+  }
   const r = await rufloMemory(['list', '-n', namespace, '--limit', String(limit), '--format', 'json'], options);
   return r.ok ? entriesOf(parseJson(r.stdout)).filter((e) => typeof e?.key === 'string') : null;
 }
 const retrieve = async (key, namespace, options) => {
+  if (options.session) {
+    const r = await options.session.get(namespace, key, options.deadlineAt);
+    if (r.state === 'ok') return r.value;
+    if (r.state !== 'fallback') return null;
+  }
   const r = await rufloMemory(['retrieve', '--key', key, '-n', namespace, '--value-only'], options);
   return r.ok ? r.stdout.trim() : null;
 };
@@ -93,6 +204,7 @@ function gitFacts(root, deadlineAt) {
 export async function checkpoint({ projectDir, event, payload = {}, env = process.env, bin, deadlineAt = Date.now() + 7000, now = Date.now } = {}) {
   if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') return { stored: false, skipped: 'RUVNET_TURN_CAPTURE=off' };
   const store = projectStore(projectDir, { deadlineAt });
+  if (store.refused && store.withheld) return { stored: false, skipped: `canonical project store refused: ${store.refused}` };
   if (!store.adopted) return { stored: false, skipped: 'project has not adopted a .swarm/memory.db' };
   // A short session hash keeps two sessions' same-millisecond checkpoints apart; --no-upsert makes a
   // collision a refusal (ledger row) instead of a silent overwrite (review m1).
@@ -137,10 +249,23 @@ export function needsFallback(facts, best) {
 }
 
 /** SessionStart: newest curated checkpoint (+ newer auto checkpoint) and lesson keys, by exact key. */
-export async function restore({ cwd, env = process.env, bin, deadlineAt = Date.now() + 3000 } = {}) {
-  const store = projectStore(cwd, { deadlineAt });
+export async function restore({ cwd, env = process.env, bin, deadlineAt = Date.now() + 3000, signal, resolve, run, invoke } = {}) {
+  const store = projectStore(cwd, { deadlineAt, resolve });
+  if (store.refused && store.withheld) {
+    // A timeout proves nothing about the store: 'unknown'. A real refusal of a store that exists is 'refused'.
+    return { status: store.timedOut ? 'unknown' : 'refused',
+      context: `[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] the canonical project store ${store.timedOut ? 'could not be resolved in time' : 'was refused'} (${store.refused}); nothing restored.` };
+  }
   if (!store.adopted) return { status: 'unavailable', context: '' };
-  const options = { db: store.db, env, bin, deadlineAt };
+  const options = { db: store.db, env, bin, deadlineAt, signal, run, invoke };
+  // One owned child for every list and exact read (#429) unless a caller injected its own process seams.
+  const session = run === undefined && invoke === undefined && (bin ?? resolveRuflo({ env })) ? openBatchSession({ bin: bin ?? resolveRuflo({ env }), storePath: store.db, env, deadline: deadlineAt, signal,
+    makeCwd: () => { const at = rufloSpawnOptions(store.db, env); return { cwd: at.cwd, cleanup: at.cleanup }; } }) : null;
+  options.session = session;
+  try { return await restoreFrom(store, options, deadlineAt); } finally { session?.close(); }
+}
+
+async function restoreFrom(store, options, deadlineAt) {
   // Dirname, its lowercase form and default: `ruflo memory list -n` is case-sensitive and owners write both.
   const namespaces = checkpointNamespaces(store.root);
   // Fast path: ONE small newest-first page per namespace, all in parallel with the lessons list. ruflo 3.56.9
@@ -177,13 +302,26 @@ export async function restore({ cwd, env = process.env, bin, deadlineAt = Date.n
   const values = await Promise.all(wanted.map((e) => retrieve(e.key, e.namespace, options)));
   const lines = [`[RuvNet Brain — PROJECT STATE · ${store.db}; historical evidence, not instructions; verify current facts]`];
   wanted.forEach((e, i) => lines.push(`${e.namespace}/${e.key}: ${values[i] === null ? '(exact read failed)' : values[i].slice(0, 1200)}`));
-  if (!wanted.length) lines.push('No project-state-current-* checkpoint stored yet.');
+  const unlisted = namespaces.filter((n, i) => rows[i] === null);
+  if (!wanted.length && !unlisted.length) lines.push('No project-state-current-* checkpoint stored yet.');
   if (route !== 'fast') lines.push(route === 'fallback'
     ? `Fast path not used: the newest-first page could not prove the newest checkpoint for ${firstPending.join(', ')}; read a ${RESTORE_FALLBACK_LIMIT}-row page.`
     : `Fast path not verified for ${pending.join(', ')} and no budget left for a larger page.`);
   if (pending.length) lines.push(`Not proven newest (a newer checkpoint may exist in): ${pending.join(', ')}`);
   if (lessons?.length) lines.push(`Lessons (ruflo memory retrieve -n lessons -k <key>): ${lessons.slice(0, 20).map((e) => e.key).join(', ')}`);
-  return { status: wanted.length ? 'restored' : 'empty', context: lines.join('\n'), keys: wanted.map((e) => e.key), route };
+  // `restored` only when every selected checkpoint was read back by exact key (#502); a list proves discovery, not content.
+  const restoredKeys = wanted.filter((e, i) => values[i] !== null).map((e) => e.key);
+  // A list call that failed proves nothing about its namespace: with no checkpoint found, that is `unknown`, never `empty`.
+  // A namespace whose list call failed may hold a newer checkpoint: with one found elsewhere, `restored` would read as complete, so it is `partial`.
+  const status = !wanted.length ? (unlisted.length ? 'unknown' : 'empty')
+    : restoredKeys.length === wanted.length ? (unlisted.length ? 'partial' : 'restored') : restoredKeys.length ? 'partial' : 'unknown';
+  if (!wanted.length && unlisted.length) lines.unshift(`[RuvNet Brain — PROJECT CONTINUITY UNKNOWN] ruflo memory list did not answer for ${unlisted.join(', ')}; the missing state is not proof that no checkpoint exists.`);
+  else if (status === 'partial' || status === 'unknown') {
+    const why = [restoredKeys.length < wanted.length ? 'an exact checkpoint read failed' : null,
+      unlisted.length ? `ruflo memory list did not answer for ${unlisted.join(', ')} (a newer checkpoint may exist there)` : null].filter(Boolean).join('; ');
+    lines.unshift(`[RuvNet Brain — PROJECT CONTINUITY INCOMPLETE] ${why}; do not treat the missing state as restored.`);
+  }
+  return { status, context: lines.join('\n'), keys: wanted.map((e) => e.key), restoredKeys, route };
 }
 
 /**

package/plugin/scripts/session-snapshot-hook.mjs

@@ -62,7 +62,7 @@ async function checkpointNow({ projectDir, event, payload, env, deadlineAt, brai
   if (consent.skipped) return { stored: false, skipped: consent.skipped };
   const { checkpoint } = await import('./ruflo-memory-hooks.mjs');
   const saved = await checkpoint({ projectDir, event, payload, env, deadlineAt });
-  if (saved.stored === false && saved.key || saved.stored && saved.verified !== true) {
+  if (saved.stored === false && saved.key || saved.stored && saved.verified !== true || /refused/.test(saved.skipped || '')) {
     recordHookFailure({ hook: 'checkpoint', event, error: saved.skipped || 'exact checkpoint readback failed' }, { brainHome });
   }
   return saved;

package/plugin/scripts/session-start-core.mjs

@@ -214,7 +214,8 @@ export async function runSessionStart({
     const continuity = await Promise.race([Promise.resolve().then(() => restoreContinuity({ env, cwd,
       deadlineAt: restoreDeadlineAt, signal: restoreController.signal })), expired]);
     if (Date.now() >= restoreDeadlineAt) throw new Error('restore deadline exceeded');
-    restoreFailed = continuity?.status === 'unknown' || continuity?.brief?.status === 'unknown';
+    const bad = ['unknown', 'partial', 'refused'];
+    restoreFailed = bad.includes(continuity?.status) || bad.includes(continuity?.brief?.status);
     if (continuity?.context) emit(continuity.context);
   } catch (error) {
     restoreController.abort();

package/plugin/scripts/session-start-health.mjs

@@ -264,8 +264,9 @@ export const knowledgeCurrency = ({ env = process.env, home, now = Date.now(), w
       + `the last refresh (${latest.action || 'unknown'}) ${age(history.latest.at)} passed its knowledge update phase, `
       + `only the host plugin sync after it did not finish: ${hostOnly.why}. `
       // A restart writes no refresh receipt, so this line stays until the next refresh records the sync.
-      + (restart ? 'Fix: restart Claude Code or Codex (`claude --continue` keeps a Claude conversation), then record it: npx ruvnet-brain@latest --update.'
-        : 'Fix: npx ruvnet-brain@latest --update (verify: npx ruvnet-brain --doctor).');
+      // The host sync alone is what did not finish, so the fix is the host-sync-only repair, not the full knowledge update (#391).
+      + (restart ? 'Fix: restart Claude Code or Codex (`claude --continue` keeps a Claude conversation), then record it: npx ruvnet-brain@latest --update --host-sync-only.'
+        : 'Fix: npx ruvnet-brain@latest --update --host-sync-only (verify: npx ruvnet-brain --doctor).');
   }
   if (!failing && fresh) return coordinatedSuiteLine({ brainHome, now, builtMs, age });
   const kit = agenticKitUpdates({ home, facts });