ruvnet-brain 4.3.28 → 4.3.30

package/README.md

@@ -7,7 +7,7 @@ Created: 2026-06-29 22:36:38 EDT
 
 # 🧠 RuvNet Brain
 
-### 🧠 RuvNet Brain — [![RuvNet Brain version 4.3.28 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.28-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.30 — updated 2026-07-30 03:24 EDT](https://img.shields.io/badge/version_4.3.30-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.**
 

package/bin/install.mjs

@@ -561,7 +561,7 @@ export function ensureUpdaterPrerequisites(kbDir) {
   return { updater: true, validator: placeTrustedCoverageValidator(kbDir) };
 }
 
-export async function unzipInto(zipPath, cacheDir, sourceDir = null, { releaseTag = null } = {}) {
+export async function unzipInto(zipPath, cacheDir, sourceDir = null, { releaseTag = null, activate = true } = {}) {
   step(
     'Unpacking the brain into place',
     'so the plugin finds forge-mcp-all.mjs and the vector stores right where it looks',
@@ -668,6 +668,13 @@ export async function unzipInto(zipPath, cacheDir, sourceDir = null, { releaseTa
       'The live brain was not touched. Fetch a complete current release and retry.');
   }
 
+  // Recovery (stageBundleForRecovery / kb/forge-update.mjs's applyVerifiedStagedRelease) consumes
+  // this authenticated, validated stage through runStorageTransaction instead — the SAME apply
+  // primitive main()'s normal --apply uses, which preserves a private overlay properly. Keep fresh
+  // activation below as the only owner of installer replacement and the private-overlay refusal:
+  // a caller that wants staged-only output must never fall through to it.
+  if (!activate) return { status: 'STAGED', stageDir, extractedBy, coverage: stagedCoverage };
+
   // Activation is an exact directory generation swap. A malformed candidate never reaches this
   // point, retired public files cannot survive as overlay debris, and a failed rename restores the
   // prior generation. Existing private overlays are update-owned and must never be stripped by the
@@ -750,6 +757,20 @@ export async function unzipInto(zipPath, cacheDir, sourceDir = null, { releaseTa
     : null };
 }
 
+/** Stage and validate a bundle for forge-update's private-overlay recovery rail
+ * (kb/forge-update.mjs's applyVerifiedStagedRelease) without touching the live generation. */
+export async function stageBundleForRecovery(zipPath, cacheDir, sourceDir = null, { releaseTag = null, signaturePath = `${zipPath}.sig` } = {}) {
+  const verified = verifyBundle(zipPath, signaturePath);
+  if (!verified.ok) throw new Error(`recovery bundle signature verification failed: ${verified.reason}`);
+  const bundleSha256 = crypto.createHash('sha256').update(fs.readFileSync(zipPath)).digest('hex');
+  const result = await unzipInto(zipPath, cacheDir, sourceDir, { releaseTag, activate: false });
+  fs.writeFileSync(`${result.stageDir}.staged-release.json`, JSON.stringify({
+    schemaVersion: 1, kind: 'ruvnet-brain-authenticated-stage', bundleSha256,
+    releaseTag, stagedAt: new Date().toISOString(),
+  }) + '\n', { mode: 0o600 });
+  return { ...result, bundleSha256 };
+}
+
 /**
  * ISSUE #128 / #153 — STALE PLUGIN GENERATIONS MAY STILL BACK LIVE SESSIONS.
  *
@@ -986,7 +1007,12 @@ export function serverDependencies(source, seen = new Set()) {
     seen.add(file);
     let src = '';
     try { src = fs.readFileSync(file, 'utf8'); } catch { return; }
-    for (const m of src.matchAll(/^\s*(?:import|export)[^'"\n]*from\s*['"](\.[^'"]+)['"]/gm)) {
+    // Lazy [^'"]* (no \n exclusion) so a multi-line named import — `import {\n  a,\n} from './x.mjs';`
+    // — is still seen: the exclusion used to stop at the first newline, so this walker silently
+    // missed any dependency imported that way. Caught live 2026-09-27: session-snapshot-hook.mjs's
+    // multi-line import of project-progression-hook.mjs never reached the Codex MCP server package,
+    // reproducing the exact packaging-boundary failure this function's own header warns about.
+    for (const m of src.matchAll(/^\s*(?:import|export)[^'"]*?from\s*['"](\.[^'"]+)['"]/gm)) {
       const spec = specPrefix ? path.join(specPrefix, m[1]) : m[1];
       const from = path.resolve(path.dirname(file), m[1]);
       if (out.some((d) => d.from === from)) continue;
@@ -2423,7 +2449,22 @@ async function smokeQuery(cacheDir) {
       // The stable MCP shell sets this exact default before spawning its worker. Passing the same
       // path here makes the install smoke warm the model cache the product will actually reopen,
       // instead of a second kb-local cache that can go green while the real door stays cold.
-      env: { ...process.env, KB_MODEL_CACHE: resolveRuntimeModelCache() },
+      //
+      // RUVNET_BRAIN_QUERY_DEADLINE_MS: this ONE probe is the very first query ever run against a
+      // freshly-installed cache — the model is cold and the cross-encoder "rerank" phase has to pay
+      // load cost that every later, warm query never pays again. Measured on macOS GitHub Actions
+      // runners 2026-09-27 (public-verification runs 36324328134 job 108636740357, 28.5-28.7s; and
+      // 36325803503 job 108638381147, 27.1-27.2s): this exact probe consistently needs ~27-29s on
+      // that platform, against the general 20s deadline (kb/query-deadline.mjs
+      // DEFAULT_QUERY_DEADLINE_MS) that is correct for every normal, warm query. 45s keeps this
+      // bounded (never unbounded — the module's core guarantee) while giving this one cold-start
+      // probe real margin, without touching the default that protects normal queries everywhere
+      // else. Only applied if the caller hasn't already set an explicit override.
+      env: {
+        ...process.env,
+        KB_MODEL_CACHE: resolveRuntimeModelCache(),
+        RUVNET_BRAIN_QUERY_DEADLINE_MS: process.env.RUVNET_BRAIN_QUERY_DEADLINE_MS ?? '45000',
+      },
     });
   } catch {
     warn("skipped the live test (couldn't launch the reader) — it'll warm on your first real question");
@@ -3180,6 +3221,11 @@ export function classifyUpdaterExit(status, { fallbackAllowed = true, result = n
   if (status === 0) {
     if (result?.terminalVerdict === 'applied') return { verdict: 'applied', fallback: false, exitCode: 0 };
     if (result?.terminalVerdict === 'noop') return { verdict: 'noop', fallback: false, exitCode: 0 };
+    // S2 (ONE CURRENCY VERDICT): rollback protection — the offered candidate's corpus generation
+    // predates the installed one. A clean, intentional no-op, not a failure: the live tree is exactly
+    // as it was, on purpose, and reporting it as 'invalid-result'/failed would turn the updater's own
+    // correct refusal into a reported --update failure (the exact issue #106 shape, one gate later).
+    if (result?.terminalVerdict === 'refused') return { verdict: 'refused', fallback: false, exitCode: 0 };
     if (!requireResult) return { verdict: 'legacy-success', fallback: false, exitCode: 0 };
     return { verdict: 'invalid-result', fallback: false, exitCode: 1 };
   }
@@ -3422,7 +3468,7 @@ export function classifyHostConvergence(receipt, expectedVersion = PACKAGE_VERSI
   return { healthy: true, state: 'channels-converged' };
 }
 
-function runUpdate() {
+async function runUpdate() {
   printBanner('update');
   const kbDir = resolvedKbDir();
   const brainHome = process.env.RUVNET_BRAIN_HOME || path.dirname(kbDir);
@@ -3564,10 +3610,46 @@ function runUpdate() {
     warn("the knowledge bundle could not refresh; continuing with executable host synchronization only");
     updateStatus = 0;
   } else if (outcome.fallback) {
-    warn("\nthe bundle's own updater couldn't complete — falling back to a fresh install of the latest Release (this always works)…\n");
-    const self = fileURLToPath(import.meta.url);
-    const fr = spawnSync(process.execPath, [self, '--force'], { stdio: 'inherit',
-      env: { ...refreshEnv, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' } });
+    // A blind fresh --force reinstall REFUSES to activate on top of a private overlay (unzipInto's
+    // own "fresh-install activation refused" guard, above) — so for a private-overlay install this
+    // branch used to die() in a loop every time the bundle's own updater failed: same refusal, same
+    // non-zero exit, forever, with no path that ever actually recovers the KB. The authenticated
+    // staged recovery rail (kb/forge-update.mjs's applyVerifiedStagedRelease) exists for exactly
+    // this case: it stages and independently re-verifies the signed bundle, then activates through
+    // runStorageTransaction — the SAME apply primitive main()'s normal --apply uses — which DOES
+    // preserve the private overlay, instead of a second, less careful mechanism that cannot.
+    let hasPrivateOverlay = false;
+    try {
+      const installedSource = JSON.parse(fs.readFileSync(path.join(kbDir, 'SOURCE.json'), 'utf8'));
+      const installedStores = Array.isArray(installedSource.stores) ? installedSource.stores : Object.values(installedSource.stores || {});
+      hasPrivateOverlay = installedStores.some((store) => store?.updateManaged === false);
+    } catch { /* updater already supplied the authoritative failure */ }
+    let fr;
+    if (hasPrivateOverlay) {
+      warn("\nthe installed updater failed; using authenticated staged recovery to preserve private stores…\n");
+      const release = await resolveRelease();
+      const bundle = await obtainBundle(release);
+      if (!bundle.zipPath) throw new Error('private-overlay recovery requires a downloadable signed bundle');
+      const sigPath = `${bundle.zipPath}.sig`;
+      const stagedRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'ruvnet-recovery-stage-'));
+      const staged = await stageBundleForRecovery(bundle.zipPath, stagedRoot, null, { signaturePath: sigPath,
+        releaseTag: release?.source === 'latest' ? (release.tag || null) : null });
+      const descriptor = path.join(stagedRoot, 'recovery-input.json');
+      let expectedRuntimeVersion = PACKAGE_VERSION;
+      try { expectedRuntimeVersion = JSON.parse(fs.readFileSync(path.join(kbDir, 'RUNTIME-IDENTITY.json'), 'utf8')).brainVersion || expectedRuntimeVersion; } catch { /* validator reports missing identity */ }
+      fs.writeFileSync(descriptor, JSON.stringify({ stagedDir: staged.stageDir, liveDir: kbDir,
+        bundlePath: bundle.zipPath, signaturePath: sigPath, bundleSha256: staged.bundleSha256,
+        expectedRuntimeVersion, releaseTag: release?.source === 'latest' ? (release.tag || null) : null,
+      }) + '\n', { mode: 0o600 });
+      fr = spawnSync(process.execPath, [path.join(REPO_ROOT, 'kb', 'forge-update.mjs'), '--staged-release', descriptor], {
+        stdio: 'inherit', cwd: path.dirname(kbDir), env: { ...refreshEnv, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' },
+      });
+    } else {
+      warn("\nthe bundle's own updater couldn't complete — falling back to a fresh install of the latest Release (this always works)…\n");
+      const self = fileURLToPath(import.meta.url);
+      fr = spawnSync(process.execPath, [self, '--force'], { stdio: 'inherit',
+        env: { ...refreshEnv, RUVNET_BRAIN_NO_UPDATE_FALLBACK: '1' } });
+    }
     updateStatus = fr.error ? 1 : (fr.status === null ? 1 : fr.status);
   } else {
     updateStatus = outcome.exitCode;

package/console/app.js

@@ -3672,7 +3672,12 @@ async function doManualRefresh() {
     announce('The refresh could not be started.');
     return;
   }
-  if (body.started === false && pill) {
+  if (body.refresh?.status === 'failed') {
+    if (pill) { pill.className = 'chip tone-warn'; pill.textContent = 'refresh failed — click to try again'; }
+    announce(`The refresh failed: ${body.refresh.error || 'the measurement child exited'}.`);
+    return;
+  }
+  if (body.started === false && body.refresh?.status === 'already-running' && pill) {
     // Honest, and not an error: a measurement was already running, so this click joined it instead
     // of starting a second full scan of the same machine.
     pill.className = 'chip tone-cyan';
@@ -4099,7 +4104,7 @@ async function mockGet(url) {
 
 async function mockPost(url, body) {
   await sleep(850);
-  if (url === '/api/refresh') return { status: 200, ok: true, data: { ok: true, refreshing: true, started: true } };
+  if (url === '/api/refresh') return { status: 200, ok: true, data: { ok: true, refreshing: true, started: true, refresh: { status: 'started', runId: 'mock-refresh' } } };
   if (url === '/api/save-brain-power') {
     return { status: 200, ok: true, data: { ok: true, off: !!(body.values || {}).off, log: 'mock: the switch moved and was read back from disk' } };
   }

package/kb/corpus-release-identity.mjs

@@ -50,6 +50,42 @@ import { createHash } from 'node:crypto';
 /** The corpus transport tag shape published by scripts/corpus-seed-publish.mjs's corpusSeedTag(). */
 export const CORPUS_TAG_PATTERN = /^corpus-sha256-[0-9a-f]{64}$/;
 
+// CODE_TAG_PATTERN / releaseKind / CORPUS_GENERATION_FIELD / parseCorpusGeneration below are literal
+// copies of scripts/release-channel-kind.mjs and scripts/corpus-promotion.mjs. This module SHIPS
+// standalone inside the distributed KB bundle (kb/forge-update.mjs's only imports are siblings in
+// this same directory — see the fixtures in tests/unit/*-apply-rollback.test.mjs, which copy exactly
+// the kb/*.mjs files a real bundle carries); `scripts/` is build/release tooling that never ships.
+// CORPUS_TAG_PATTERN above is already duplicated this same way for the same reason. Keep both copies
+// byte-identical in behavior; tests/unit/corpus-release-identity-channel-parity.test.mjs pins that.
+
+/** Owner-approved product release: a plain semver tag. */
+export const CODE_TAG_PATTERN = /^v\d+\.\d+\.\d+$/;
+
+export function releaseKind(tag) {
+  const value = String(tag ?? '');
+  if (CORPUS_TAG_PATTERN.test(value)) return 'corpus';
+  if (CODE_TAG_PATTERN.test(value)) return 'code';
+  return 'other';
+}
+
+/** The author-side ordering key field name for a corpus release's `releases/latest` promotion
+ * (scripts/corpus-promotion.mjs's CORPUS_GENERATION_FIELD) — S2 reuses it as the client-side
+ * ordering key so promotion and currency comparisons can never disagree about what "generation"
+ * means. */
+export const CORPUS_GENERATION_FIELD = 'Corpus generation:';
+
+/** Parse the `Corpus generation:` line out of a release's body/notes text, exactly as
+ * scripts/corpus-promotion.mjs's evaluateCorpusPromotion does for publish-time ordering. Returns
+ * `{ value, epoch }` (the raw string and its parsed epoch) or null when absent/unparseable. */
+export function parseCorpusGeneration(body) {
+  const line = String(body || '').split('\n').map((row) => row.trim())
+    .find((row) => row.startsWith(CORPUS_GENERATION_FIELD));
+  if (!line) return null;
+  const value = line.slice(CORPUS_GENERATION_FIELD.length).trim();
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? { value, epoch: parsed } : null;
+}
+
 /** The installer-written record of which approved runtime this KB belongs to. */
 export const INSTALLED_RUNTIME_FILE = 'RUNTIME-IDENTITY.json';
 
@@ -210,6 +246,43 @@ export function recordCorpusTransportIdentity(treeDir, { releaseTag }) {
   return source;
 }
 
+/**
+ * Record the ordering key a corpus release's generation is compared by (S2, corpus-currency gate).
+ * Written IN the tree being installed, next to `recordCorpusTransportIdentity` (same caller, same
+ * candidate directory, same atomic rename into place) so a crash between the two can never leave a
+ * tree whose transport tag and generation ordering key disagree.
+ *
+ * `generation` is read from the CANDIDATE release's own published record — parseCorpusGeneration
+ * against the release body's `Corpus generation:` line (scripts/corpus-promotion.mjs), the same
+ * field that is already the sole author-side ordering key for `releases/latest` promotion. It is
+ * never invented locally and never derived from a local clock: kb/forge-update.mjs's isBehind()
+ * history (this file's header) is the standing lesson in why a locally-observed timestamp can never
+ * safely stand in for an authenticated ordering key.
+ *
+ * IDEMPOTENT for the same reason recordCorpusTransportIdentity is (see its comment): touch the file
+ * only when the field's value actually changes, or a byte-identical re-apply reads as `applied`
+ * instead of `noop` and strands a rollback copy.
+ */
+export function recordCorpusGenerationIdentity(treeDir, { corpusReleaseTag, generation }) {
+  const file = path.join(treeDir, 'SOURCE.json');
+  const source = JSON.parse(fs.readFileSync(file, 'utf8'));
+  if (isCorpusReleaseTag(corpusReleaseTag) && typeof generation === 'string' && generation) {
+    if (source.corpusGeneration === generation) return source;
+    source.corpusGeneration = generation;
+  } else {
+    // No generation identity to record for this candidate — an ordinary code release, or a corpus
+    // release whose published record carries no readable ordering key. Never leave a PRIOR
+    // generation stamped: a code release supersedes it outright (its bundle IS the corpus), and a
+    // corpus candidate that declares no generation of its own must not leave behind a number that no
+    // longer describes what is actually on disk — the next comparison must read UNKNOWN, not compare
+    // against a generation this tree no longer holds.
+    if (!Object.hasOwn(source, 'corpusGeneration')) return source;
+    delete source.corpusGeneration;
+  }
+  atomicJson(file, source);
+  return source;
+}
+
 // ── the anti-loop ledger ────────────────────────────────────────────────────────────────────────
 // A refusal that is rediscovered every night is a download loop with extra steps. The refused tag
 // is remembered next to the KB (never inside it, where an update would replace it), so the very

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ruvnet-brain",
-  "version": "4.3.28",
-  "description": "One-command installer for RuvNet Brain — 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.",
+  "version": "4.3.30",
+  "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": {
     "ruvnet-brain": "bin/install.mjs"
@@ -70,7 +70,8 @@
     "cap:ab": "node scripts/rerank-cap-warm-ab.mjs",
     "hooks:check": "node scripts/hook-retirement-check.mjs",
     "release:qualify": "node scripts/release-qualification.mjs",
-    "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs"
+    "rehearse:corpus": "node scripts/rehearse-corpus-pipeline.mjs",
+    "single-source:check": "node scripts/single-source-check.mjs"
   },
   "files": [
     ".claude-plugin/marketplace.json",

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.28",
+  "version": "4.3.30",
   "author": {
     "name": "Stuart Kerr"
   },

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

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

package/plugin/mcp/managed-cli-interface.mjs

@@ -5,6 +5,8 @@ import path from 'node:path';
 import { loadRuntimePreferences, runtimeChildEnv } from '../scripts/runtime-preferences.mjs';
 import { projectDirectory } from '../scripts/project-identity.mjs';
 import { recordManagedCliObservation, recordRegistryLatestObservation } from '../scripts/capability-claim-evidence.mjs';
+import { runSessionSnapshotHook } from '../scripts/session-snapshot-hook.mjs';
+import { resolveProjectStore } from '../scripts/project-store-resolver.mjs';
 
 export const MANAGED_EXECUTABLES = Object.freeze([
   'ruflo',
@@ -233,20 +235,69 @@ function execute(executable, argv, env) {
       clearTimeout(timer);
       resolve({ code: null, stdout: '', stderr: '', error: error.message });
     });
-    child.once('close', (code) => {
-      if (settled) return;
-      settled = true;
-      clearTimeout(timer);
-      resolve({ code, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), error: null });
+      child.once('close', (code, signal) => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve({ code, signal, stdout: Buffer.concat(stdout).toString(), stderr: Buffer.concat(stderr).toString(), error: null });
     });
   });
 }
 
+/**
+ * Convert the child-process result into the managed boundary's terminal vocabulary. A zero exit
+ * status is necessary but not sufficient: a tool that emits a fatal marker or cannot provide a
+ * terminal status must remain failure/unknown evidence for progression consumers.
+ */
+export function normalizeManagedExecution(execution) {
+  const output = [execution?.stdout, execution?.stderr].filter(Boolean)
+    .join(execution?.stdout && execution?.stderr ? '\n' : '');
+  const contradictoryFailure = /(?:^|\n)\s*(?:❌|\[ERROR\])|invalid pragma command|key not found/i.test(output);
+  if (execution?.signal) return { outcome: 'interrupted', output, signal: execution.signal, contradictoryFailure };
+  if (execution?.error || contradictoryFailure || execution?.code === null || execution?.code === undefined) {
+    return { outcome: execution?.error || contradictoryFailure ? 'failure' : 'unknown', output, contradictoryFailure };
+  }
+  return { outcome: execution.code === 0 ? 'success' : 'failure', output, contradictoryFailure };
+}
+
+function managedSessionId(env) {
+  const supplied = env.RUVNET_BRAIN_SESSION_ID || env.RUVNET_HOOK_SESSION_ID;
+  return typeof supplied === 'string' && supplied.trim() ? supplied.trim() : `managed-cli-${process.pid}`;
+}
+
+/** Bind managed CLI execution to the existing progression writer when this project has adopted it. */
+function managedProgressionCapture({ executable, argv, projectRoot, env, event, execution, normalized }) {
+  const adopted = fs.existsSync(path.join(projectRoot, '.swarm'));
+  if (!adopted) return { adopted: false, skipped: 'project has not adopted the canonical store' };
+  const host = String(env.RUVNET_HOOK_HOST || '').toLowerCase();
+  if (!['claude', 'codex'].includes(host)) return { adopted: true, error: 'managed host identity unavailable' };
+  let resolution;
+  try { resolution = resolveProjectStore({ projectDir: projectRoot }); }
+  catch (error) { return { adopted: true, error: `project store could not be resolved: ${error?.message || error}` }; }
+  const payload = {
+    session_id: managedSessionId(env),
+    hook_event_name: event,
+    tool_name: executable,
+    tool_input: { command: [executable, ...argv].join(' ') },
+    ...(execution ? {
+      tool_response: {
+        stdout: execution.stdout,
+        stderr: execution.stderr,
+        exit_code: execution.code,
+        ...(execution.signal ? { signal: execution.signal, interrupted: true } : {}),
+        outcome: normalized?.outcome,
+        ...(execution.error ? { error: execution.error } : {}),
+      },
+    } : {}),
+  };
+  return { adopted: true, ...runSessionSnapshotHook(projectRoot, event, { rawInput: JSON.stringify(payload), host }) };
+}
+
 function resultOf(executable, argv, result) {
   const output = [result.stdout, result.stderr].filter(Boolean).join(result.stdout && result.stderr ? '\n' : '');
-  const contradictoryFailure = /(?:^|\n)\s*(?:❌|\[ERROR\])|invalid pragma command|key not found/i.test(output);
-  if (result.error || result.code !== 0 || contradictoryFailure) {
-    const reason = result.error || (contradictoryFailure ? 'fatal output despite exit 0' : `exit ${result.code}`);
+  const normalized = normalizeManagedExecution(result);
+  if (normalized.outcome !== 'success') {
+    const reason = result.error || (normalized.contradictoryFailure ? 'fatal output despite exit 0' : result.code == null ? 'no terminal exit status' : `exit ${result.code}`);
     return {
       content: [{ type: 'text', text: output || `${executable} ${argv.join(' ')} failed: ${reason}` }],
       isError: true,
@@ -258,7 +309,7 @@ function resultOf(executable, argv, result) {
   };
 }
 
-export async function callManagedCli(toolName, args, env = process.env, fetchImpl = globalThis.fetch) {
+export async function callManagedCli(toolName, args, env = process.env, fetchImpl = globalThis.fetch, lifecycle = {}) {
   try {
     const executable = assertExecutable(args?.executable);
     const argv = literalArgv(args?.argv ?? []);
@@ -327,11 +378,34 @@ export async function callManagedCli(toolName, args, env = process.env, fetchImp
           isError: true,
         };
       }
+      // Host identity is process context established by the native adapter, never a tool argument.
+      // A caller can request a CLI command, but must not relabel its continuity record as another
+      // host by supplying an arbitrary `host` property.
       const childEnv = (executable === 'agentic-flow' || executable === 'agentic-qe')
         ? runtimeChildEnv({ env, cwd: projectRoot })
         : env;
+      const capture = typeof lifecycle.capture === 'function' ? lifecycle.capture : managedProgressionCapture;
+      const beforeCapture = await capture({ executable, argv, projectRoot, env: childEnv, event: 'PreToolUse' });
+      if (beforeCapture?.error || (beforeCapture?.adopted && beforeCapture.progressionCaptured !== true)) {
+        const reason = beforeCapture.error || beforeCapture.skipped || 'pre-execution progression was not durably captured';
+        return { content: [{ type: 'text', text: `managed execution refused: ${reason}` }], isError: true };
+      }
+      if (lifecycle && typeof lifecycle.beforeExecute === 'function') {
+        await lifecycle.beforeExecute({ executable, argv, projectRoot, env: childEnv });
+      }
       const execution = await execute(executable, argv, childEnv);
+      const normalized = normalizeManagedExecution(execution);
+      const afterCapture = await capture({ executable, argv, projectRoot, env: childEnv, event: 'PostToolUse', execution, normalized });
+      if (lifecycle && typeof lifecycle.afterExecute === 'function') {
+        await lifecycle.afterExecute({ executable, argv, projectRoot, env: childEnv, execution, normalized });
+      }
       recordManagedCliObservation({ toolName, executable, argv, execution, env });
+      if (afterCapture?.adopted && afterCapture.progressionCaptured !== true) {
+        return {
+          content: [{ type: 'text', text: `managed command ${normalized.outcome}; continuity result was not durably captured: ${afterCapture.skipped || 'unknown reason'}` }],
+          isError: true,
+        };
+      }
       return resultOf(executable, argv, execution);
     }
 

package/plugin/scripts/advocacy-route.mjs

@@ -450,7 +450,10 @@ async function main() {
   }
   // DIRECT MODE (a human running this file, or a host without the runtime). Here this process IS the
   // writer, so it owns the denominator too.
-  try { record({ id: candidate.findingId, action: ACTIONS.OFFERED, severity: 'normal', stateHash: candidate.observationHash }); } catch { /* never break the surface we measure */ }
+  let receipt;
+  try { receipt = record({ id: candidate.findingId, action: ACTIONS.OFFERED, severity: 'normal', stateHash: candidate.observationHash }); }
+  catch { receipt = null; }
+  if (!receipt?.ok) return 0; // never emit an untracked offer that cannot be resolved later
   process.stdout.write(`${candidate.copy}\n`);
   return 0;
 }

package/plugin/scripts/capacity-aware-parallel-work.mjs

@@ -12,6 +12,7 @@ import os from 'node:os';
 import { spawnSync } from 'node:child_process';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { isHarnessGenerated } from './hook-input.mjs';
 
 export const UNKNOWN_RUNTIME_TOTAL_AGENT_CEILING = 4;
 const INPUT_LIMIT = 32 * 1024;
@@ -180,6 +181,9 @@ export function runCapacityHook(rawInput, sample) {
   let input;
   try { input = JSON.parse(String(rawInput || '')); } catch { return ''; }
   const prompt = input?.prompt ?? input?.user_prompt ?? input?.input;
+  // H2: a background task notification or other harness-authored message reads as substantial
+  // "independent work" prose but nobody wrote it — never advise a parallel-work fan-out off of one.
+  if (isHarnessGenerated(prompt)) return '';
   if (!isSubstantialParallelWork(prompt)) return '';
   return formatAdvisory(effectiveAgentRecommendation(sample === undefined ? collectMacPressure() : sample, {
     configuredMaxChildren: input?.configured_max_children,

package/plugin/scripts/continuation-gate.mjs

@@ -226,6 +226,77 @@ if (has('--done')) {
   process.exit(0);
 }
 
+/**
+ * H4: the continuation objective could never be closed. `--commit-to` writes `led.objective` with
+ * `state: 'active'` (above), and the Stop-side allow-list at ~275 already checks for
+ * `['cancelled', 'completed', 'blocked'].includes(led.objective?.state)` — but until now NOTHING
+ * ever wrote one of those three states, so an objective, once opened, forced every Stop for the rest
+ * of the project's life (short of `--clear`, which also wipes every unrelated ledger ITEM — a
+ * blunt instrument for closing one objective). These two verbs are the missing other half of
+ * `--commit-to`: they touch ONLY `led.objective`, leaving `led.items` untouched, and each REQUIRES
+ * its evidence/reason text — an empty completion would be exactly the "marked done without doing
+ * it" fabrication this whole gate exists to refuse (see the "THE HONEST EXIT" note below on why a
+ * genuinely dead item must be closed with a recorded reason, never silently). Nothing here runs
+ * automatically; both are explicit, human/model-invoked CLI verbs only.
+ */
+if (has('--complete-objective')) {
+  const evidence = arg('--complete-objective');
+  if (!evidence || !evidence.trim()) {
+    console.error('--complete-objective requires evidence: --complete-objective "<what proves it is done>"');
+    process.exit(2);
+  }
+  const led = load();
+  if (led.objective) {
+    // DERIVED from the required argument checked above, not asserted (ADR-0024 / status-honesty.mjs):
+    // this line is unreachable with blank/missing evidence — the guard exits 2 first. That proves an
+    // explicit, human/model-invoked CLI action supplied named evidence; it does not verify the
+    // evidence is TRUE, which is exactly why continuation-objective.mjs's own header already
+    // documents this ledger as non-authoritative ("neither prove user provenance nor establish task
+    // completion") — a nudge-suppression preference with the reason attached for audit, not a
+    // verified fact standing in for a real completion check.
+    led.objective.state = evidence.trim() ? 'completed' : led.objective.state;
+    led.objective.completedAt = new Date().toISOString();
+    led.objective.completionEvidence = evidence;
+  }
+  save(led);
+  console.log(led.objective ? `objective completed: ${evidence}` : 'no objective to complete');
+  process.exit(0);
+}
+
+if (has('--cancel-objective')) {
+  const reason = arg('--cancel-objective');
+  if (!reason || !reason.trim()) {
+    console.error('--cancel-objective requires a reason: --cancel-objective "<why this objective no longer applies>"');
+    process.exit(2);
+  }
+  const led = load();
+  if (led.objective) {
+    led.objective.state = 'cancelled';
+    led.objective.cancelledAt = new Date().toISOString();
+    led.objective.cancellationReason = reason;
+  }
+  save(led);
+  console.log(led.objective ? `objective cancelled: ${reason}` : 'no objective to cancel');
+  process.exit(0);
+}
+
+if (has('--help') || has('-h')) {
+  console.log([
+    'usage: continuation-gate.mjs <verb> [args]  (no verb + JSON on stdin = the Stop hook itself)',
+    '',
+    '  --commit-to "<text>"               record work the model agreed to do; opens/reopens the',
+    '                                      objective as state: active',
+    '  --done "<exact item text>"         mark a plain ledger item done (exact text match only)',
+    '  --complete-objective "<evidence>"  close the current objective as state: completed, with the',
+    '                                      completion evidence recorded — leaves other ledger items',
+    '                                      untouched',
+    '  --cancel-objective "<reason>"      close the current objective as state: cancelled, with the',
+    '                                      reason recorded — leaves other ledger items untouched',
+    '  --clear                            wipe the ENTIRE ledger: every item AND the objective',
+  ].join('\n'));
+  process.exit(0);
+}
+
 if (has('--clear')) { save({ items: [] }); console.log('ledger cleared'); process.exit(0); }
 
 // ── the Stop hook itself (default action) ────────────────────────────────────────────────────────