ruvnet-brain 4.3.35 → 4.3.37

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.35 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.35-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
+### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.37 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.37-updated_2026--07--30_03:24_EDT-1E90FF?style=for-the-badge&labelColor=0757BA)](https://github.com/stuinfla/ruvnet-brain/blob/main/plugin/.claude-plugin/plugin.json)
 
 **A portable, source-grounded brain over Reuven Cohen's (rUv's) RuvNet stack — delivered as a Claude Code plugin that makes Claude _use_ the stack instead of fighting it.**
 
@@ -562,7 +562,7 @@ node forge-ask-all.mjs --dir . --q "How does RuVector implement HNSW vector sear
 
 This project versions in the open (see the live badge up top for the exact plugin version; the downloadable knowledge bundle is a separate track) — we don't claim “done,” “complete,” or “zero hallucinations.” Where it stands:
 
-- ✅ **The grounding brain is real and proven** — 182 public stores · 143,682 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
+- ✅ **The grounding brain is real and proven** — 199 public stores · 160,685 public source chunks, dual embeddings, cross-encoder rerank, plugin (MCP tool + explicit skills; automatic hooks retired), all re-runnable.
 - ✅ **Code-level depth** — the code-rich repos are indexed to full function bodies; “how is it implemented?” returns the implementation. Verified in the shipped bundle (clean-room 3/3).
 - ✅ **Routing holds** — named 47/48, described 26/28, scenario 7/8; behavioral L1–L3 all pass (**L4 downgraded — it measures that the brain spoke, not that anything listened**); private stores fenced out of the public bundle (zero-leak verified).
 - ⚠️ **Two routing residuals** (above) — surfaced, not hidden.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.35",
+  "version": "4.3.37",
   "description": "One-command installer for RuvNet Brain \u2014 a portable, source-grounded brain over rUv's RuvNet building blocks, delivered as a Claude Code plugin so Claude uses the stack instead of fighting it.",
   "type": "module",
   "bin": {

package/plugin/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
   "description": "RuvNet brain transplant for Claude Code — grounds every RuvNet decision in real source across 77 rUv repositories, prefers Ruflo / RuVector-RVF / AgentDB over training-prior defaults (pgvector, Pinecone, hand-rolled cosine), and can pull in any RuvNet repo on demand. Ships a UserPromptSubmit retrieve-and-inject grounding hook and a PreToolUse write gate that refuses ungrounded rUv-product code until search_ruvnet has been consulted (ADR-0012 / ADR-067).",
-  "version": "4.3.35",
+  "version": "4.3.37",
   "author": {
     "name": "Stuart Kerr"
   },

package/plugin/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.35",
+  "version": "4.3.37",
   "description": "Source-grounded RuvNet knowledge, lifecycle enforcement, and learning for Codex.",
   "author": {
     "name": "Stuart Kerr"

package/plugin/hooks/codex-hooks.json

@@ -1,5 +1,5 @@
 {
-  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps only the pre-existing, project-scoped continuation gate. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 §Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on — that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered — today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses. Capacity-aware parallel-work guidance is also registered at UserPromptSubmit: it advises the coordinator to launch only real independent workers within sampled resource headroom and the live runtime/tool cap; it never spawns workers or claims execution.",
+  "description": "RuvNet Brain continuity plane for Codex. Broad legacy automatic gates remain retired. Registrations here are MEASURED, not assumed: a probe hook was registered on all twelve event names the installed codex-cli 0.154.0 binary declares and a real `codex exec` run was observed (2026-09-11). SessionStart, UserPromptSubmit and SessionEnd FIRED and carry handlers. Stop keeps the pre-existing, project-scoped continuation gate; session-snapshot was added at Stop on 2026-09-29 to record each turn's outcome (turn-outcome-capture.mjs) — Codex SessionEnd carries no last_assistant_message, so Stop is the only boundary that can. Its delivery rests on codex-cli 0.158.0's declared stop.command.input schema and the other Codex Stop handlers; it has NOT been live-observed and fails open. PreCompact is DECLARED ABSENT here: the binary declares the event but the probe never observed it, and a capture registered on an unobserved event would look symmetrical while capturing nothing. All handlers are bounded and fail open. Amended 2026-09-11: UserPromptSubmit also runs ground-ruvnet (grounding injection, ADR-040 §Amendment). Amended 2026-09-12: the 2026-09-11 PreToolUse/PostToolUse \"not observed\" note was measured with a prompt (`codex exec \"reply OK\"`) that never invoked a tool, so neither event had anything to fire on — that was an untested path, not a failing one. Re-probed with prompts that actually call a tool: a real apply_patch write fired PreToolUse/PostToolUse with tool_name \"apply_patch\", and a real MCP call to this repo's own search_ruvnet server fired both with tool_name \"mcp__ruvnet_brain__search_ruvnet\". Both are now registered below: decision-gate's write route (matcher includes apply_patch, Codex's raw write-tool name) and grounding-stamp (unchanged matcher already recognizes the mcp__..__search_ruvnet shape). The bash route (exec_command) remains unregistered — today's measurement covered a write and an MCP call, not exec_command, and extending on that evidence would be the same unproven leap this note replaces. Also added 2026-09-12: grounding-turn-mark (UserPromptSubmit) and grounding-turn-gate (Stop), the \"answered without searching\" pair — a prompt-level grounding directive is advisory, so this records whether it fired and forces continuation at Stop if no search_ruvnet call was recorded since (reusing grounding-stamp's own stamp evidence). Both are registered on Codex identically to Claude: the Stop-block contract (hookSpecificOutput.additionalContext) already has a proven Codex translation via codex-hook-adapter.mjs's Stop branch (see tests/unit/codex-lifecycle-hooks.test.mjs), the same path continuation-gate already uses. Capacity-aware parallel-work guidance is also registered at UserPromptSubmit: it advises the coordinator to launch only real independent workers within sampled resource headroom and the live runtime/tool cap; it never spawns workers or claims execution.",
   "hooks": {
     "SessionStart": [
       {
@@ -21,6 +21,11 @@
             "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 continuation-gate",
             "timeout": 10
           },
+          {
+            "type": "command",
+            "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 session-snapshot Stop",
+            "timeout": 10
+          },
           {
             "type": "command",
             "command": "node -e \"const f=require('node:fs'),o=require('node:os'),p=require('node:path'),c=require('node:child_process'),d=process.env.CODEX_HOME||p.join(o.homedir(),'.codex'),b=process.env.RUVNET_BRAIN_HOME||p.join(p.dirname(d),'.cache','ruvnet-brain'),w=p.join(b,'codex-hook.mjs');let s;try{s=f.statSync(w)}catch{}if(!s?.isFile())process.exit(0);const r=c.spawnSync(process.execPath,[w,...process.argv.slice(2)],{stdio:['inherit','pipe','pipe'],encoding:'utf8',env:process.env,timeout:Number(process.argv[1]),killSignal:'SIGKILL'});if(r.status===0||r.status===2){if(r.stdout)process.stdout.write(r.stdout);if(r.stderr)process.stderr.write(r.stderr)}process.exit(r.status===2?2:0)\" 9000 grounding-turn-gate",

package/plugin/hooks/hook-contracts.json

@@ -37,9 +37,10 @@
       "owner": "session-snapshot",
       "class": "continuity capture",
       "hosts": [
-        "claude"
+        "claude",
+        "codex"
       ],
-      "responsibility": "Append one project snapshot to the canonical store and commit any outbox debt a previously interrupted session left behind."
+      "responsibility": "Append one project snapshot to the canonical store and commit any outbox debt a previously interrupted session left behind. Also records the turn's outcome (final assistant text, files changed, command descriptions — never user text) to AgentDB namespace `turns`, in the project store when it exists or the machine-wide store outside the repository; SessionEnd/PreCompact distill those records (ruflo ADR-174)."
     },
     {
       "event": "PreCompact",
@@ -153,7 +154,7 @@
       "Stop": "The 2026-09-11 probe turn never completed, so run_turn_stop_hooks had no completion to fire on. The binary declares the event and StopCommandOutputWire, so this is not-proven rather than unsupported. Stop keeps only the pre-existing continuation gate; no capture handler was added to an event whose delivery has not been seen.",
       "PreCompact": "A one-line turn never approaches a compaction threshold. The binary declares PreCompact and PreCompactCommandOutputWire. No capture handler registered."
     },
-    "consequence": "Codex captures at SessionEnd only; Stop/PreCompact remain unproven and unregistered as above (unchanged by this measurement). PreToolUse/PostToolUse are now proven for a write (apply_patch) and an MCP tool call (search_ruvnet) specifically, and decision-gate's write route plus grounding-stamp are registered on Codex accordingly (see contracts below). Bash-class tool calls (exec_command) were not exercised by this measurement and remain unregistered — extending on unexercised evidence would repeat the exact mistake this record corrects."
+    "consequence": "Codex captures at SessionEnd only; Stop/PreCompact remain unproven and unregistered as above (unchanged by this measurement). PreToolUse/PostToolUse are now proven for a write (apply_patch) and an MCP tool call (search_ruvnet) specifically, and decision-gate's write route plus grounding-stamp are registered on Codex accordingly (see contracts below). Bash-class tool calls (exec_command) were not exercised by this measurement and remain unregistered — extending on unexercised evidence would repeat the exact mistake this record corrects. Amended 2026-09-29: session-snapshot is registered on Codex Stop so each Codex turn's outcome is recorded (SessionEnd carries no last_assistant_message). Stop delivery is still NOT live-observed; the registration rests on codex-cli 0.158.0's declared stop.command.input schema and fails open."
   },
   "contracts": [
     {
@@ -196,7 +197,8 @@
       "id": "session-snapshot",
       "event": "Stop",
       "hosts": [
-        "claude"
+        "claude",
+        "codex"
       ],
       "mode": "advisory",
       "offBehavior": "run",

package/plugin/scripts/continuity-hook-policy.mjs

@@ -20,7 +20,7 @@
  *   session-start       continuity recovery   at SessionStart       claude, codex
  *   unprompted-speech   advisory delivery     at UserPromptSubmit   claude, codex
  *   continuation-gate   continuation nudge    at turn end           claude, codex
- *   session-snapshot    continuity capture    at turn end           claude
+ *   session-snapshot    continuity capture    at turn end           claude, codex
  *   session-snapshot    continuity capture    at PreCompact         claude
  *   session-snapshot    continuity capture    at SessionEnd         claude, codex
  *   ground-ruvnet       grounding injection   at UserPromptSubmit   claude, codex
@@ -95,7 +95,8 @@ const registration = (id, matcher, hosts) => Object.freeze({ id, matcher, hosts:
  *                     struct, so this is "not proven", not "not supported".
  *   PreCompact        NOT OBSERVED — a one-line turn never approaches a compaction threshold.
  *
- * Therefore Codex capture is registered at SessionEnd ONLY. Stop keeps the pre-existing
+ * Therefore Codex capture was registered at SessionEnd ONLY (Stop added 2026-09-29 for turn
+ * outcomes — see the Stop registration below; its delivery is still unobserved). Stop keeps the pre-existing
  * continuation-gate registration (unchanged by this lane); no NEW handler is added to an event whose
  * delivery has not been seen. hook-contracts.json carries the same measurement and its date.
  *
@@ -154,7 +155,13 @@ export const CONTINUITY_EVENTS = Object.freeze({
   ]),
   Stop: Object.freeze([
     registration('continuation-gate', '*', ['claude', 'codex']),
-    registration('session-snapshot', '*', ['claude']),
+    // Codex added 2026-09-29 (owner requirement: every turn's outcome recorded on BOTH hosts —
+    // turn-outcome-capture.mjs). Codex SessionEnd carries no last_assistant_message, so Stop is the
+    // only boundary that can record a Codex turn. Evidence: codex-cli 0.158.0's own
+    // stop.command.input schema (last_assistant_message, turn_id) and the two Codex Stop handlers
+    // already registered above/below. NOT yet live-observed firing — see the probe box: the capture
+    // fails open, so an unfired registration costs nothing but must not be read as proof.
+    registration('session-snapshot', '*', ['claude', 'codex']),
     // The "answered without searching" gate, half 2 of 2 (2026-09-12). Forces continuation
     // (hookSpecificOutput.additionalContext — the same contract continuation-gate.mjs already uses
     // and codex-hook-adapter.mjs already translates to Codex's decision:block on both hosts) when

package/plugin/scripts/coverage-integrity.mjs

@@ -225,6 +225,41 @@ export function generationLedgerBytes(ledger) {
   return Buffer.from(`${JSON.stringify(ledger, null, 2)}\n`);
 }
 
+const isIsoOrNull = (value) => value === null || (typeof value === 'string' && Number.isFinite(Date.parse(value)));
+const isAttemptCount = (value) => Number.isSafeInteger(value) && value >= 1;
+
+/**
+ * ADR-0091 D5: how an ELIGIBLE repository row stands in a bundle. It returns
+ *   'shipped' — the store's bytes ship: CURRENT, or STALE with a verified `carry` record (the refresh
+ *               failed and the previous generation's bytes, re-hashed against the ledger, were kept);
+ *   'absent'  — MISSING with a `failure` record: a store that failed with no prior bytes, excluded
+ *               from the repository store set;
+ *   null      — anything else. A STALE/MISSING row WITHOUT its record, FAILED and UNVERIFIED stay
+ *               rejected, exactly as before.
+ * The status token is never new: the distinction lives in the object (0.1.0's STALE_CARRIED and
+ * PENDING_FAILED were withdrawn).
+ */
+export function eligibleRepositoryStanding(row) {
+  const status = row?.status;
+  const { carry, failure } = row || {};
+  if (status === 'CURRENT') return carry === undefined && failure === undefined ? 'shipped' : null;
+  if (status === 'STALE' && carry && typeof carry === 'object' && failure === undefined) {
+    const carried = String(carry.carriedSourceCommit || '').toLowerCase();
+    const shipped = typeof carry.reason === 'string' && carry.reason.length > 0
+      && HEX40.test(carried) && carried === String(row.artifact?.sourceCommit || '').toLowerCase()
+      && HEX40.test(String(carry.missedUpstream || '').toLowerCase())
+      && String(carry.missedUpstream).toLowerCase() === String(row.upstream?.sha || '').toLowerCase()
+      && carried !== String(carry.missedUpstream).toLowerCase()
+      && isAttemptCount(carry.attempts) && isIsoOrNull(carry.carriedCommittedAt)
+      && row.artifact?.bytesVerified === true && row.artifact?.passagesPresent === true;
+    return shipped ? 'shipped' : null;
+  }
+  if (status === 'MISSING' && failure && typeof failure === 'object' && carry === undefined) {
+    return typeof failure.reason === 'string' && failure.reason.length > 0 && isAttemptCount(failure.attempts) ? 'absent' : null;
+  }
+  return null;
+}
+
 export function validatePublicInventory({ assetsDir, coverage, ledger, installedPublicStores = null, gistReceipt = null }) {
   const root = path.resolve(assetsDir);
   const selected = installedPublicStores === null ? null : [...installedPublicStores].map((store) => String(store).toLowerCase());
@@ -248,11 +283,23 @@ export function validatePublicInventory({ assetsDir, coverage, ledger, installed
     if (stores.some((store) => !store) || new Set(stores).size !== stores.length) throw new Error(`${family} stores are missing or duplicated`);
     return stores.sort();
   };
-  const repos = coverage.rows.filter((row) => row.kind === 'repository' && row.disposition === 'eligible');
-  if (repos.some((row) => row.status !== 'CURRENT')) throw new Error('an eligible repository is not CURRENT');
+  const eligibleRepos = coverage.rows.filter((row) => row.kind === 'repository' && row.disposition === 'eligible');
+  const rejected = eligibleRepos.find((row) => eligibleRepositoryStanding(row) === null);
+  if (rejected) {
+    throw new Error(`an eligible repository is not CURRENT (${rejected.artifact?.store || rejected.name}: ${rejected.status} `
+      + 'without a verified carry/failure record)');
+  }
+  const repos = eligibleRepos.filter((row) => eligibleRepositoryStanding(row) === 'shipped');
   const repositories = uniqueStores(repos, 'repository');
+  // A MISSING-with-failure store ships no bytes: it is in neither the repository set nor the excluded
+  // set, so a stray file under its name still fails below as an unclassified public store.
+  const absentRepositories = uniqueStores(eligibleRepos.filter((row) => eligibleRepositoryStanding(row) === 'absent'),
+    'absent repository');
   const excludedRepositories = uniqueStores(coverage.rows.filter((row) => row.kind === 'repository'
     && row.disposition !== 'eligible'), 'excluded repository');
+  if (absentRepositories.some((store) => repositories.includes(store) || excludedRepositories.includes(store))) {
+    throw new Error('an absent repository store is also shipped or excluded');
+  }
   const excludedSet = new Set(excludedRepositories);
   if (repositories.some((store) => excludedSet.has(store))) throw new Error('eligible and excluded repository stores overlap');
   const gists = coverage.rows.filter((row) => row.kind === 'gist' && row.disposition === 'eligible');
@@ -339,6 +386,15 @@ export function validatePublicInventory({ assetsDir, coverage, ledger, installed
       throw new Error(`${store} generation record provenance is incomplete`);
     }
   }
+  // A carried store ships the PREVIOUS generation's bytes: the ledger must name exactly the commit
+  // the carry record says was kept, or the row describes bytes this bundle does not carry.
+  for (const row of repos) {
+    if (!row.carry) continue;
+    const store = String(row.artifact.store).toLowerCase();
+    if (String(ledger.stores[store]?.sourceCommit || '').toLowerCase() !== String(row.carry.carriedSourceCommit).toLowerCase()) {
+      throw new Error(`${store} carry record names a source commit the generation ledger does not carry`);
+    }
+  }
   const publicStores = expected;
   evidenceFiles.sort((a, b) => a.path.localeCompare(b.path) || a.kind.localeCompare(b.kind));
   return { repositories, excludedRepositories, gistAggregate, derived, publicStores,

package/plugin/scripts/hook-shim.mjs

@@ -120,7 +120,9 @@ const TABLE = {
   // way — it stopped trusting hook-shim.mjs as a blind generic spawner, not their presence here.
   'learn-capture':    { file: 'learn-capture.sh',    interpreter: 'bash', mode: 'advisory', offBehavior: 'silence' },
   'learn-flush':      { file: 'learn-flush.mjs',     interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
-  'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 65536 },
+  // 1 MiB, not 64 KiB: the Stop payload now carries `last_assistant_message`, and a long closing
+  // message truncated mid-JSON would parse as `{}` and silently drop the whole capture.
+  'session-snapshot': { file: 'session-snapshot-hook.mjs', interpreter: 'node', mode: 'advisory', offBehavior: 'run', stdinBytes: 1048576 },
   'md-stamp':         { file: 'md-stamp.mjs',        interpreter: 'node', mode: 'advisory', offBehavior: 'silence' },
   // THE EXTERNAL-SIGNAL WATCH PLANE, W1 OBSERVED (ADR-058 §D3; DDD-0013 Context 2). PostToolUse,
   // matcher ^Bash$ (anchored — an unanchored matcher is F3/F4). Classifies gh/vercel/netlify/npm

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

@@ -10,6 +10,7 @@ import { projectDirectory } from './project-identity.mjs';
 import { buildProjectProgression } from './project-progression-producer.mjs';
 import { ProjectProgressionStore } from './project-progression-store.mjs';
 import { resolveProjectStore } from './project-store-resolver.mjs';
+import { captureTurnOutcome } from './turn-outcome-capture.mjs';
 
 /**
  * The capture boundary's whole budget. hooks.json declares 10s; this keeps the internal work well
@@ -97,11 +98,19 @@ export function runSessionSnapshotHook(projectDir, event, {
   produce = buildProjectProgression,
   budgetMs = CAPTURE_BUDGET_MS,
   now = Date.now,
+  captureTurn = captureTurnOutcome,
 } = {}) {
   const metadataWritten = writeSessionSnapshot(projectDir, event);
   let payload;
   try { payload = rawInput ? JSON.parse(rawInput) : {}; } catch { payload = {}; }
-  const idle = { metadataWritten, progressionCaptured: false, receipt: null };
+  // TURN OUTCOMES FIRST, and independent of `.swarm`: every turn in every repository is recorded
+  // (a project without `.swarm` records to the machine-wide db outside it — turn-outcome-capture.mjs).
+  // It only reads and spawns a detached writer, so it costs the progression budget below nothing.
+  let turn;
+  try { turn = captureTurn({ projectDir, event, payload, host }); } catch (error) {
+    turn = { recorded: false, skipped: `turn capture failed: ${error.message}` };
+  }
+  const idle = { metadataWritten, progressionCaptured: false, receipt: null, turn };
 
   if (hasProjectProgression(payload)) {
     if (payload.hook_event_name !== event) {
@@ -162,6 +171,7 @@ export function runSessionSnapshotHook(projectDir, event, {
   return {
     metadataWritten,
     progressionCaptured: true,
+    turn,
     replayed,
     receipt: result.receipt,
     provenance: produced.provenance,

package/plugin/scripts/turn-outcome-capture.mjs

@@ -0,0 +1,292 @@
+/**
+ * turn-outcome-capture.mjs — record what each turn CONCLUDED, and make it recallable knowledge.
+ *
+ * Called from session-snapshot-hook.mjs's runSessionSnapshotHook, so it rides the capture boundary
+ * both hosts already register (Claude: hooks.json; Codex: codex-hooks.json via codex-hook-adapter,
+ * which sets RUVNET_HOOK_HOST=codex). Two jobs:
+ *
+ *   Stop                  → one AgentDB record per distinct turn outcome, namespace `turns`
+ *   SessionEnd/PreCompact → `ruflo memory distill run` on the same db (ruflo ADR-174: memory_entries
+ *                           is the RECORDING tier; distill mines it into episodes/reasoning_patterns/
+ *                           causal_edges, the KNOWLEDGE tier, which stays empty unless it is run)
+ *
+ * WHERE: the project's `.swarm/memory.db` when it exists, else the machine-wide
+ * `~/.claude/global-memory/.swarm/memory.db` (outside every repository). `.swarm` is NEVER created
+ * inside a project — see session-snapshot-hook.mjs's writeSessionSnapshot for why that is trespass.
+ *
+ * WHAT (measured facts carried over from the owner's local Claude hook, 2026-09-29):
+ *   • The Brain's continuation gate continues most turns, so the turn's REAL final Stop carries
+ *     stop_hook_active=true. It is NOT skipped; exact repeats are dropped by a per-session
+ *     fingerprint of (finalText, files) instead.
+ *   • The transcript may not contain the closing message yet when Stop fires, so the payload's
+ *     `last_assistant_message` wins when present; only without it is the transcript waited on
+ *     (bounded) until it stops growing.
+ *   • Content = assistant outcome text, files changed, Bash descriptions. NEVER raw user text (a
+ *     2026-07-13 measurement: prompt echoes made 87% of a store noise). Trivial turns are skipped.
+ *
+ * CODEX: codex-cli 0.158.0's own `stop.command.input` schema (read from the installed binary
+ * 2026-09-29) carries `last_assistant_message` (nullable) and `transcript_path` (nullable).
+ * The Codex rollout format is NOT parsed: project-progression-sources.mjs already declares it
+ * unknown, and the rollout records observed locally (custom_tool_call / function_call with free-form
+ * inputs) give no stable file-change shape. Codex records therefore carry the outcome text only.
+ *
+ * LATENCY: Stop runs synchronously in the host's turn, and one `ruflo memory store` costs ~0.7s
+ * (measured). So the writes run in ONE detached worker (this file, `--run-steps`), store then
+ * distill in order; the hook itself only reads, fingerprints and spawns. A breadcrumb line is
+ * appended next to the db BEFORE the spawn, and the worker appends a receipt per step, so a lost
+ * write is visible rather than silent. Advisory always: nothing here throws to the caller.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import crypto from 'node:crypto';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { resolveRuflo, rufloInvocation } from './ruflo-bin.mjs';
+
+export const TURN_NAMESPACE = 'turns';
+export const MIN_OUTCOME_CHARS = 200;
+const TRANSCRIPT_TAIL_BYTES = 2 * 1024 * 1024;
+const STEP_TIMEOUT_MS = 60_000;
+const RUFLO_ENV = { RUFLO_DAEMON_AUTOSTART: '0' };
+
+function textOf(content) {
+  if (typeof content === 'string') return content;
+  if (!Array.isArray(content)) return '';
+  return content.filter((c) => c && c.type === 'text' && typeof c.text === 'string').map((c) => c.text).join('\n');
+}
+
+function patchFiles(patch) {
+  const out = new Set();
+  for (const line of String(patch || '').split(/\r?\n/)) {
+    const m = /^\*\*\* (?:Add|Update|Delete) File: (.+)$/.exec(line) || /^\*\*\* Move to: (.+)$/.exec(line);
+    if (m) out.add(m[1].trim());
+  }
+  return [...out];
+}
+
+/**
+ * The current turn of a Claude JSONL transcript = every record after the last genuine user message
+ * (a user record carrying text, not a tool_result). User text is used ONLY to find that boundary.
+ */
+export function claudeTurn(lines) {
+  const recs = [];
+  for (const l of lines) { try { recs.push(JSON.parse(l)); } catch { /* partial or foreign line */ } }
+  let start = 0;
+  recs.forEach((o, i) => {
+    const role = o?.message?.role || o?.role;
+    const c = o?.message?.content;
+    const isToolResult = Array.isArray(c) && c.some((x) => x && x.type === 'tool_result');
+    if (role === 'user' && !isToolResult && textOf(c).trim()) start = i + 1;
+  });
+  const texts = [];
+  const files = new Set();
+  const actions = [];
+  for (const o of recs.slice(start)) {
+    if ((o?.message?.role || o?.role) !== 'assistant') continue;
+    const c = o.message?.content;
+    const t = textOf(c).trim();
+    if (t) texts.push(t);
+    if (!Array.isArray(c)) continue;
+    for (const u of c) {
+      if (!u || u.type !== 'tool_use') continue;
+      const inp = u.input || {};
+      if (['Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(u.name)) {
+        const f = inp.file_path || inp.notebook_path;
+        if (typeof f === 'string' && f) files.add(f);
+      } else if (u.name === 'apply_patch') {
+        for (const f of patchFiles(typeof inp === 'string' ? inp : inp.command || inp.input)) files.add(f);
+      } else if (u.name === 'Bash' && typeof inp.description === 'string' && inp.description) {
+        actions.push(inp.description);
+      }
+    }
+  }
+  // The closing message usually carries the outcome; when it is short (a tool-heavy turn) the turn's
+  // other assistant text is kept too, newest last, so the record still says what happened.
+  const last = texts.length ? texts[texts.length - 1] : '';
+  const finalText = last.length >= MIN_OUTCOME_CHARS ? last : texts.join('\n').slice(-2500);
+  return { finalText, files: [...files], actions };
+}
+
+function readTail(file, bytes = TRANSCRIPT_TAIL_BYTES) {
+  const size = fs.statSync(file).size;
+  const offset = Math.max(0, size - bytes);
+  const handle = fs.openSync(file, 'r');
+  try {
+    const buf = Buffer.alloc(size - offset);
+    fs.readSync(handle, buf, 0, buf.length, offset);
+    const lines = buf.toString('utf8').split(/\r?\n/);
+    if (offset > 0) lines.shift(); // the first line of a tail is almost always cut mid-record
+    return lines;
+  } finally { fs.closeSync(handle); }
+}
+
+/** Wait (bounded) until the transcript stops growing, then return its tail lines. */
+export function readSettledTranscript(file, { stableMs = 400, maxMs = 2000, sleep } = {}) {
+  const pause = sleep || ((ms) => Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms));
+  const deadline = Date.now() + Math.max(0, maxMs);
+  let size = -1;
+  for (;;) {
+    const now = fs.statSync(file).size;
+    if (now === size || Date.now() >= deadline) break;
+    size = now;
+    pause(Math.min(stableMs, Math.max(0, deadline - Date.now())));
+  }
+  return readTail(file);
+}
+
+export function buildTurnRecord({ turn, project, host, session, at = new Date() }) {
+  const parts = [`[turn ${at.toISOString()} project=${project} host=${host}]`,
+    `OUTCOME: ${turn.finalText.replace(/\s+/g, ' ').slice(0, 2500)}`];
+  if (turn.files.length) parts.push(`FILES CHANGED: ${turn.files.slice(0, 25).join(', ')}`);
+  if (turn.actions.length) parts.push(`ACTIONS: ${turn.actions.slice(-15).join(' • ')}`);
+  parts.push(`SESSION: ${session || '?'}`);
+  return parts.join('  ||  ').slice(0, 4000);
+}
+
+/** Project db if the project already has one; otherwise the machine-wide db outside every repo. */
+export function resolveTurnDb({ projectDir, home = os.homedir(), env = process.env } = {}) {
+  const projectDb = path.join(projectDir, '.swarm', 'memory.db');
+  try { if (fs.statSync(projectDb).isFile()) return { db: projectDb, scope: 'project' }; } catch { /* absent */ }
+  const globalDb = env.RUVNET_TURN_GLOBAL_DB || path.join(home, '.claude', 'global-memory', '.swarm', 'memory.db');
+  return { db: globalDb, scope: 'global' };
+}
+
+const projectName = (projectDir) => path.basename(path.resolve(projectDir)).replace(/[^A-Za-z0-9._-]/g, '_') || 'project';
+
+/** Detached worker launch: the hook returns immediately; the worker runs the steps in order. */
+export function launchDetached(steps, { receipts }) {
+  const child = spawn(process.execPath, [fileURLToPath(import.meta.url), '--run-steps', JSON.stringify({ steps, receipts })], {
+    cwd: os.tmpdir(), detached: true, stdio: 'ignore', windowsHide: true, env: { ...process.env, ...RUFLO_ENV },
+  });
+  child.unref();
+  return { launched: true, pid: child.pid };
+}
+
+function sameTurnSeen(stateFile, sessionKey, fingerprint) {
+  let last = {};
+  try { last = JSON.parse(fs.readFileSync(stateFile, 'utf8')) || {}; } catch { /* first run */ }
+  if (last[sessionKey] === fingerprint) return true;
+  const keys = Object.keys(last);
+  for (const k of keys.slice(0, Math.max(0, keys.length - 200))) delete last[k];
+  try {
+    fs.mkdirSync(path.dirname(stateFile), { recursive: true, mode: 0o700 });
+    fs.writeFileSync(stateFile, JSON.stringify({ ...last, [sessionKey]: fingerprint }), { mode: 0o600 });
+  } catch { /* dedupe is best effort; a duplicate record beats a lost one */ }
+  return false;
+}
+
+/**
+ * Capture this turn's outcome (Stop) and/or queue distillation (SessionEnd, PreCompact).
+ * Returns a plain report; `skipped` / `distill.skipped` carry the reason whenever nothing is written.
+ */
+export function captureTurnOutcome({
+  projectDir, event, payload = {}, host = 'claude',
+  env = process.env, home = os.homedir(),
+  brainHome = env.RUVNET_BRAIN_HOME || path.join(home, '.cache', 'ruvnet-brain'),
+  ruflo = resolveRuflo({ env, home }),
+  launch = launchDetached,
+  readTranscript = readSettledTranscript,
+  settleMs = 2000,
+  now = () => new Date(),
+} = {}) {
+  const report = { event, host, recorded: false, distill: { queued: false } };
+  if (String(env.RUVNET_TURN_CAPTURE || '').toLowerCase() === 'off') {
+    return { ...report, skipped: 'RUVNET_TURN_CAPTURE=off', distill: { queued: false, skipped: 'RUVNET_TURN_CAPTURE=off' } };
+  }
+  if (!ruflo) return { ...report, skipped: 'ruflo not found', distill: { queued: false, skipped: 'ruflo not found' } };
+  const { db, scope } = resolveTurnDb({ projectDir, home, env });
+  Object.assign(report, { db, scope });
+  const steps = [];
+  const project = projectName(projectDir);
+  const receipts = path.join(brainHome, 'turn-capture', 'receipts.jsonl');
+
+  if (event === 'Stop') {
+    const sessionKey = String(payload.session_id || payload.transcript_path || '');
+    const message = typeof payload.last_assistant_message === 'string' ? payload.last_assistant_message.trim() : '';
+    let turn = { finalText: '', files: [], actions: [] };
+    if (host === 'claude' && typeof payload.transcript_path === 'string' && payload.transcript_path) {
+      // With the closing message in hand, the transcript is read immediately (tool calls are already
+      // flushed); without it, wait for the closing message to land, bounded.
+      try { turn = claudeTurn(readTranscript(payload.transcript_path, { maxMs: message ? 0 : settleMs })); } catch { /* unreadable */ }
+    }
+    if (message && (message.length >= MIN_OUTCOME_CHARS || message.length >= turn.finalText.length)) turn.finalText = message;
+    if (!sessionKey) report.skipped = 'no session identity in the host payload';
+    else if (turn.finalText.length < MIN_OUTCOME_CHARS && !turn.files.length) {
+      report.skipped = host === 'codex' && !message ? 'codex payload carried no last_assistant_message' : 'trivial turn';
+    } else {
+      const fingerprint = crypto.createHash('sha256').update(JSON.stringify([turn.finalText, turn.files])).digest('hex');
+      const stateFile = path.join(brainHome, 'turn-capture', 'last-turn.json');
+      if (sameTurnSeen(stateFile, `${host}:${sessionKey}`, fingerprint)) report.skipped = 'same turn outcome already recorded';
+      else {
+        const at = now();
+        const key = `turn-${project}-${at.getTime()}`;
+        const value = buildTurnRecord({ turn, project, host, session: payload.session_id, at });
+        steps.push({ kind: 'store', ruflo, args: ['memory', 'store', '-k', key, '--value', value, '-n', TURN_NAMESPACE,
+          '--path', db, '--tags', `project=${project},host=${host}`, '--provenance', 'agent_output'] });
+        Object.assign(report, { recorded: true, key, value });
+      }
+    }
+  } else report.skipped = `turn outcomes are recorded at Stop, not ${event}`;
+
+  if (event === 'SessionEnd' || event === 'PreCompact') {
+    if (!fs.existsSync(db)) report.distill = { queued: false, skipped: 'no memory db to distill yet' };
+    else {
+      steps.push({ kind: 'distill', ruflo, args: ['memory', 'distill', 'run', '--db', db, '--namespace', TURN_NAMESPACE, '--max-entries', '500'] });
+      report.distill = { queued: true, db };
+    }
+  }
+  if (!steps.length) return report;
+
+  try {
+    // The machine-wide db lives outside every repository; its directory is created on first use so a
+    // fresh machine records from its first turn. A project's `.swarm` is never created (scope check).
+    if (scope === 'global') fs.mkdirSync(path.dirname(db), { recursive: true, mode: 0o700 });
+    if (report.recorded) {
+      fs.appendFileSync(path.join(path.dirname(db), 'agentdb-turns.jsonl'),
+        `${JSON.stringify({ ts: Date.now(), key: report.key, project, host, value: report.value })}\n`, { mode: 0o600 });
+    }
+    report.launch = launch(steps, { receipts });
+  } catch (error) {
+    return { ...report, recorded: false, distill: { queued: false, skipped: `launch failed: ${error.message}` }, skipped: `launch failed: ${error.message}` };
+  }
+  return report;
+}
+
+/** The detached worker: run each step in order, bounded, and append one receipt per step. */
+export function runSteps({ steps = [], receipts } = {}, { run = spawnSync } = {}) {
+  const results = [];
+  for (const step of steps) {
+    let status = null;
+    let error = null;
+    const db = step.args[step.args.indexOf(step.kind === 'store' ? '--path' : '--db') + 1];
+    try {
+      const { executable, args } = rufloInvocation(step.ruflo, step.args);
+      // CONTAINMENT (measured 2026-09-29, ruflo 3.48.0): even with an explicit --path, `memory store`
+      // writes `.swarm/hnsw.index` and `ruvector.db` relative to its CWD. Run from an inherited cwd,
+      // that planted `.swarm/` + `ruvector.db` in a repository that never adopted the brain — the
+      // exact trespass session-snapshot-hook.mjs forbids. So every step runs INSIDE the db's own
+      // directory, with ruflo's memory root pinned there too.
+      const home = path.dirname(db);
+      const r = run(executable, args, { stdio: 'ignore', timeout: STEP_TIMEOUT_MS, cwd: home, windowsHide: true,
+        env: { ...process.env, ...RUFLO_ENV, CLAUDE_FLOW_MEMORY_PATH: home } });
+      status = r.status;
+      if (r.error) error = r.error.message;
+    } catch (e) { error = e.message; }
+    const row = { at: new Date().toISOString(), kind: step.kind, db,
+      key: step.kind === 'store' ? step.args[step.args.indexOf('-k') + 1] : undefined, status, error };
+    results.push(row);
+    if (receipts) {
+      try {
+        fs.mkdirSync(path.dirname(receipts), { recursive: true, mode: 0o700 });
+        fs.appendFileSync(receipts, `${JSON.stringify(row)}\n`, { mode: 0o600 });
+      } catch { /* receipts are best effort */ }
+    }
+  }
+  return results;
+}
+
+if (process.argv[1] && path.resolve(process.argv[1]) === fileURLToPath(import.meta.url) && process.argv[2] === '--run-steps') {
+  try { runSteps(JSON.parse(process.argv[3] || '{}')); } catch { /* a detached worker has no one to report to */ }
+  process.exit(0);
+}