ruvnet-brain 4.5.16 → 4.6.0

package/plugin/scripts/nightly-scheduler.mjs

@@ -5,10 +5,12 @@ import path from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { automaticPath } from './automatic-update.mjs';
+import { sharedLockStatus } from './developer-update-lock.mjs';
+import { EXECUTION_MODULES } from './developer-update-policy.mjs';
 
 export const NIGHTLY_LABEL = 'com.ruvnet.brain-update';
 export const NIGHTLY_HOUR = 3;
-export const NIGHTLY_MINUTE = 47;
+export const NIGHTLY_MINUTE = 30;
 export const NIGHTLY_PROOF_LABEL = /^com\.ruvnet\.brain-update\.proof-[A-Za-z0-9._-]+$/;
 export const NIGHTLY_ENV_ALLOWLIST = Object.freeze([
   'PATH', 'HOME', 'USERPROFILE', 'RUVNET_BRAIN_HOME', 'RUVNET_BRAIN_KB', 'npm_config_cache', 'NO_COLOR', 'SystemRoot', 'SYSTEMROOT', 'ComSpec', 'COMSPEC', 'PATHEXT', 'TEMP', 'TMP',
@@ -140,8 +142,13 @@ function inspectRefreshOwner(owner) {
   } catch { return 'unknown'; }
 }
 
-function updateModules(directory, sourceDir = path.dirname(fileURLToPath(import.meta.url))) {
-  const files = ['automatic-update.mjs', 'user-settings.mjs', 'ruvnet-gate1-pattern.mjs'];
+const HISTORICAL_UPDATE_MODULES = ['automatic-update.mjs', 'user-settings.mjs', 'ruvnet-gate1-pattern.mjs'];
+const BRIDGED_UPDATE_MODULES = [...HISTORICAL_UPDATE_MODULES, 'developer-update-owner.mjs'];
+const LEGACY_UPDATE_MODULES = [...BRIDGED_UPDATE_MODULES, 'developer-update-policy.mjs'];
+const PREVIOUS_DEVELOPER_MODULES = [...BRIDGED_UPDATE_MODULES, ...EXECUTION_MODULES.filter(name => name !== 'plugin-artifact-proof.mjs')];
+const DEVELOPER_UPDATE_MODULES = [...new Set([...LEGACY_UPDATE_MODULES, ...EXECUTION_MODULES])];
+function updateModules(directory, sourceDir = path.dirname(fileURLToPath(import.meta.url)), developerSuite = true) {
+  const files = developerSuite ? DEVELOPER_UPDATE_MODULES : LEGACY_UPDATE_MODULES;
   const bytes = Object.fromEntries(files.map(file => [file, fs.readFileSync(path.join(sourceDir, file))]));
   const digest = sha256(Buffer.concat(files.flatMap(file => [Buffer.from(file), bytes[file]])));
   const target = path.join(directory, `update-modules-${digest}`);
@@ -157,7 +164,8 @@ function updateModules(directory, sourceDir = path.dirname(fileURLToPath(import.
 
 function verifyUpdateModules(modules) {
   if (!modules) return; // existing schema-2 registrations remain inspectable
-  if (Object.keys(modules).sort().join(',') !== 'automatic-update.mjs,ruvnet-gate1-pattern.mjs,user-settings.mjs') throw new Error('invalid update module closure');
+  if (![HISTORICAL_UPDATE_MODULES, BRIDGED_UPDATE_MODULES, LEGACY_UPDATE_MODULES, PREVIOUS_DEVELOPER_MODULES, DEVELOPER_UPDATE_MODULES].some(names => [...names].sort().join(',') === Object.keys(modules).sort().join(','))) throw new Error('invalid update module closure');
+  if (modules['developer-update.mjs'] && !modules['plugin-artifact-proof.mjs'] && fs.readFileSync(modules['developer-update.mjs'].path, 'utf8').includes('./plugin-artifact-proof.mjs')) throw new Error('new coordinator artifact closure is incomplete');
   for (const [name, item] of Object.entries(modules)) {
     if (!path.isAbsolute(item.path) || path.basename(item.path) !== name
       || path.dirname(item.path) !== path.dirname(modules['automatic-update.mjs'].path)
@@ -167,7 +175,7 @@ function verifyUpdateModules(modules) {
 }
 
 export function installNightlyRunner({ brainHome, source, nodePath = process.execPath,
-  identity = NIGHTLY_LABEL, packageTarget, bundleTarget, env = {}, moduleSource } = {}) {
+  identity = NIGHTLY_LABEL, packageTarget, bundleTarget, env = {}, moduleSource, developerSuite = !NIGHTLY_PROOF_LABEL.test(identity) } = {}) {
   validateIdentity(identity);
   if (!source || !fs.existsSync(source)) throw new Error(`nightly runner source is missing: ${source || '(unset)'}`);
   const bytes = fs.readFileSync(source);
@@ -179,8 +187,8 @@ export function installNightlyRunner({ brainHome, source, nodePath = process.exe
     throw new Error(`nightly runner at ${runnerPath} does not match its content-addressed identity`);
   }
   if (!fs.existsSync(runnerPath)) fs.writeFileSync(runnerPath, bytes, { mode: 0o755 });
-  const modules = updateModules(dir, moduleSource);
-  const record = { updateModules: modules, schemaVersion: 2, kind: 'ruvnet-brain-nightly-scheduler', identity,
+  const modules = updateModules(dir, moduleSource, developerSuite);
+  const record = { updateModules: modules, ...(developerSuite ? { mode: 'developer-suite' } : {}), schemaVersion: 2, kind: 'ruvnet-brain-nightly-scheduler', identity,
     nodePath: path.resolve(nodePath), runnerPath, runnerSha256: digest, argv: [],
     environment: Object.fromEntries(NIGHTLY_ENV_ALLOWLIST.filter(key => env[key] !== undefined).map(key => [key, key === 'PATH' ? automaticPath({ nodePath, home: homeOf(env), env }) : String(env[key])])),
     packageTarget: normalizePackageTarget(packageTarget), bundleTarget: normalizeBundleTarget(bundleTarget, identity) };
@@ -200,6 +208,7 @@ export function readNightlyRegistration({ brainHome, identity = NIGHTLY_LABEL,
       || !path.isAbsolute(record.nodePath) || !path.isAbsolute(record.runnerPath)
       || !Array.isArray(record.argv) || record.argv.length !== 0) throw new Error('invalid registration schema');
     if (record.environment !== undefined && (!record.environment || Array.isArray(record.environment) || Object.entries(record.environment).some(([key, value]) => !NIGHTLY_ENV_ALLOWLIST.includes(key) || typeof value !== 'string'))) throw new Error('invalid registered environment');
+    if (![undefined, 'developer-suite'].includes(record.mode) || (record.mode === 'developer-suite') !== Boolean(record.updateModules?.['developer-update.mjs'])) throw new Error('nightly coordinator mode/module closure mismatch');
     verifyUpdateModules(record.updateModules);
     const actual = sha256(fs.readFileSync(record.runnerPath));
     if (actual !== record.runnerSha256) throw new Error('runner digest mismatch');
@@ -242,8 +251,35 @@ export function resolveNightlyProofBundle({ brainHome, env = process.env } = {})
   return execution.record.bundleTarget;
 }
 
+export function developerRunHealth({ brainHome, registration, now = Date.now(), maxAgeHours = 30 }) {
+  const file = path.join(brainHome, 'nightly-suite-update.json');
+  if (!fs.existsSync(file)) return { state: 'never-ran', evidence: 'No coordinated update receipt exists yet.', receipt: null };
+  let receipt;
+  try { receipt = JSON.parse(fs.readFileSync(file, 'utf8')); }
+  catch (error) { return { state: 'failed', evidence: `Coordinated update receipt unreadable: ${error.message}`, receipt: null }; }
+  const validDigest = value => typeof value === 'string' && /^[a-f0-9]{64}$/.test(value);
+  const bound = validDigest(receipt.sourceSha256) && receipt.kind === 'nightly-suite-update' && receipt.schemaVersion === 1
+    && receipt.sourceSha256 === registration.updateModules?.['developer-update.mjs']?.sha256
+    && EXECUTION_MODULES.filter(name => name !== 'plugin-artifact-proof.mjs' || registration.updateModules?.[name]).every(name => validDigest(receipt.sourceSnapshot?.[name]) && receipt.sourceSnapshot[name] === registration.updateModules?.[name]?.sha256);
+  const ageHours = (now - Date.parse(receipt.finishedAt || receipt.startedAt || '')) / 3_600_000;
+  if (!bound || !Number.isFinite(ageHours)) return { state: 'failed', evidence: 'Coordinated update receipt is not bound to registered source.', receipt };
+  if (receipt.state === 'running') {
+    const lock = sharedLockStatus({ brainHome });
+    const live = lock.state === 'running' && lock.owner.pid === (receipt.ownerPid || receipt.pid) && lock.owner.token === receipt.ownerToken;
+    return { state: live ? 'running' : 'failed', ageHours, receipt, evidence: live ? 'Coordinated updates have a live exact owner.' : 'Coordinated update owner is absent or unverified.' };
+  }
+  if (receipt.state === 'failed' || receipt.ok !== true) return { state: 'failed', ageHours, receipt, evidence: receipt.error || 'Coordinated updates failed.' };
+  if (receipt.mode !== 'apply' || receipt.schedulerIdentity !== registration.identity) return { state: 'never-ran', ageHours, receipt, evidence: 'Latest receipt is manual or a currency check; nightly execution remains unproven.' };
+  if (receipt.state !== 'completed') return { state: 'failed', ageHours, receipt, evidence: 'Coordinated update terminal state is unverified.' };
+  if (ageHours > maxAgeHours) return { state: 'stale', ageHours, receipt, evidence: `Last coordinated update is ${ageHours.toFixed(1)}h old.` };
+  const verification = { ok: bound && receipt.mode === 'apply' && receipt.schedulerIdentity === registration.identity && receipt.state === 'completed' && receipt.ok === true && ageHours >= 0 && ageHours <= maxAgeHours };
+  return { state: verification.ok ? 'ok' : 'failed', verification, ageHours, receipt, evidence: verification.ok ? `Coordinated updates completed ${ageHours.toFixed(1)}h ago; ${receipt.config?.scope || 'unknown'} scope.` : 'Coordinated update timestamp or terminal evidence is invalid.' };
+}
+
 export function refreshRunHealth({ brainHome, identity = NIGHTLY_LABEL, now = Date.now(), maxAgeHours = 30,
   inspectOwner = inspectRefreshOwner } = {}) {
+  const registration = readNightlyRegistration({ brainHome, identity });
+  if (registration.ok && registration.record.mode === 'developer-suite') return developerRunHealth({ brainHome, registration: registration.record, now, maxAgeHours });
   const dir = path.join(brainHome, 'refresh-runs');
   let files = [];
   try {
@@ -270,13 +306,13 @@ export function refreshRunHealth({ brainHome, identity = NIGHTLY_LABEL, now = Da
   const stamp = Date.parse(receipt.finishedAt || receipt.startedAt || '');
   if (!Number.isFinite(stamp)) return { state: 'failed', evidence: 'Latest nightly receipt has no valid timestamp.', receipt };
   const ageHours = (now - stamp) / 3_600_000;
-  const registration = readNightlyRegistration({ brainHome, identity });
-  if (!registration.ok) return { state: 'failed', ageHours,
-    evidence: `Nightly registration is invalid: ${registration.why}`, receipt };
-  const expectedIdentity = { schedulerIdentity: registration.record.identity,
-    registrationPath: registration.record.recordPath, nodePath: registration.record.nodePath,
-    runnerPath: registration.record.runnerPath, runnerSha256: registration.record.runnerSha256, argv: [] };
-  if (receipt.schedulerIdentity !== registration.record.identity
+  const legacyRegistration = readNightlyRegistration({ brainHome, identity });
+  if (!legacyRegistration.ok) return { state: 'failed', ageHours,
+    evidence: `Nightly registration is invalid: ${legacyRegistration.why}`, receipt };
+  const expectedIdentity = { schedulerIdentity: legacyRegistration.record.identity,
+    registrationPath: legacyRegistration.record.recordPath, nodePath: legacyRegistration.record.nodePath,
+    runnerPath: legacyRegistration.record.runnerPath, runnerSha256: legacyRegistration.record.runnerSha256, argv: [] };
+  if (receipt.schedulerIdentity !== legacyRegistration.record.identity
     || JSON.stringify(receipt.executableIdentity) !== JSON.stringify(expectedIdentity)) {
     return { state: 'failed', ageHours, evidence: 'Nightly receipt is not bound to the registered runner bytes.', receipt };
   }
@@ -334,9 +370,12 @@ export function refreshHistory({ brainHome }) {
     failuresSinceSuccess: sinceSuccess.filter(({ receipt }) => receipt.status === 'FAILED').length };
 }
 
-/** agentic-kit owns this machine's Brain updates (`ak sync`), so the Brain's own scheduler is off on purpose. */
+/** Kit retains the legacy update owner unless this machine explicitly assigns it to Brain. */
 export function updateOwnedByAgenticKit(home = os.homedir()) {
-  try { return JSON.parse(fs.readFileSync(path.join(home, '.config', 'agentic-kit', 'kit.json'), 'utf8')).ruvnetBrain === true; }
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(home, '.config', 'agentic-kit', 'kit.json'), 'utf8'));
+    return config.ruvnetBrain === true && config.ruvnetBrainUpdateOwner !== 'brain';
+  }
   catch { return false; }
 }
 

package/plugin/scripts/plugin-artifact-proof.mjs

@@ -0,0 +1,135 @@
+// Immutable Git blobs prove the active Claude surface, independently of stale provider metadata.
+import fs from 'node:fs';
+import path from 'node:path';
+import crypto from 'node:crypto';
+export const gitBlobHash = bytes => crypto.createHash('sha1').update(`blob ${bytes.length}\0`).update(bytes).digest('hex');
+const safePath = name => typeof name === 'string' && name && !name.includes('\\') && !path.posix.isAbsolute(name)
+  && !name.split('/').some(part => part === '..' || part === '' || part === '.') && !name.includes('\0');
+const within = (root, file) => file === root || file.startsWith(root + path.sep);
+export function pinnedGithubRepo(source) {
+  if (source?.source === 'github' && /^[A-Za-z0-9][A-Za-z0-9_-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(source.repo || '')) return source.repo;
+  if (source?.source === 'url') return /^https:\/\/github\.com\/([A-Za-z0-9][A-Za-z0-9_-]*\/[A-Za-z0-9][A-Za-z0-9_.-]*?)(?:\.git)?$/.exec(source.url || '')?.[1] || null;
+  return null;
+}
+export async function pinnedClaudeTarget(source, commit, { request = fetch, cache = new Map() } = {}) {
+  const repo = pinnedGithubRepo(source);
+  if (!repo || !/^[a-f0-9]{40}$/i.test(commit || '')) throw Error('pinned artifact owner is not a known GitHub repository');
+  const subdir = source.path ? String(source.path).replace(/^\.\//, '').replace(/\/$/, '') : '';
+  if (subdir && !safePath(subdir)) throw Error('pinned plugin path escapes repository');
+  const key = `${repo}:${commit}:${subdir}`;
+  if (cache.has(key)) return cache.get(key);
+  const get = async url => {
+    const response = await request(url, { signal: AbortSignal.timeout(20_000), headers: { 'User-Agent': 'ruvnet-brain/claude-artifact-proof' } });
+    if (!response.ok) throw Error(`immutable GitHub artifact HTTP ${response.status}`);
+    return response;
+  };
+  const tree = await (await get(`https://api.github.com/repos/${repo}/git/trees/${commit}?recursive=1`)).json();
+  if (!Array.isArray(tree.tree) || tree.truncated !== false || !tree.tree.length || tree.tree.length > 5000) throw Error('immutable repository tree is incomplete or unbounded');
+  const prefix = subdir ? subdir + '/' : '';
+  const entries = tree.tree.filter(entry => entry.path?.startsWith(prefix)).map(entry => ({ ...entry, path: entry.path.slice(prefix.length) })).filter(entry => entry.path);
+  if (entries.some(entry => !safePath(entry.path) || !/^[a-f0-9]{40}$/i.test(entry.sha || ''))) throw Error('immutable repository path or hash malformed');
+  const manifestPath = '.claude-plugin/plugin.json', manifestEntry = entries.find(entry => entry.path === manifestPath && entry.type === 'blob');
+  if (!manifestEntry) throw Error('immutable Claude manifest absent');
+  const resource = prefix + manifestPath;
+  const response = await get(`https://raw.githubusercontent.com/${repo}/${commit}/${resource.split('/').map(encodeURIComponent).join('/')}`);
+  const manifestBytes = Buffer.from(await response.arrayBuffer());
+  if (gitBlobHash(manifestBytes) !== manifestEntry.sha) throw Error('immutable Claude manifest does not match pinned Git blob');
+  const result = { repo, commit, manifest: JSON.parse(manifestBytes.toString('utf8')), entries, manifestBlob: manifestEntry.sha };
+  cache.set(key, result);
+  return result;
+}
+
+export function verifyClaudeArtifact(target, installPath) {
+  const proof = { ok: false, scope: 'active-claude-artifact', repo: target.repo, pinnedCommit: target.commit,
+    immutableManifestBlob: target.manifestBlob, declaredVersion: target.manifest.version || null,
+    compared: [], outsideClaudeProof: [], mismatches: [], actualClaudeSourceMatched: false, entireRepositoryMatched: false,
+    limits: ['Active resource directories and default Claude files reject extras; other cached files and dynamically computed runtime references are unverified.'] };
+  try {
+    const root = fs.realpathSync(installPath);
+    const actualManifest = path.join(root, '.claude-plugin/plugin.json');
+    if (!within(root, fs.realpathSync(actualManifest)) || fs.lstatSync(actualManifest).isSymbolicLink()) throw Error('unsafe cached Claude manifest');
+    proof.actualVersion = JSON.parse(fs.readFileSync(actualManifest, 'utf8')).version || null;
+    const entries = new Map(target.entries.map(entry => [entry.path, entry]));
+    const selected = new Set(), activeDirectories = new Set(['.claude-plugin', 'commands', 'agents', 'skills', 'hooks']);
+    const add = (name, required = true) => {
+      name = name.replace(/^\.\//, '').replace(/\/$/, '');
+      if (!safePath(name)) throw Error('declared Claude resource path is unsafe');
+      const found = target.entries.filter(entry => entry.path === name || entry.path.startsWith(name + '/'));
+      if (required && !found.length) throw Error(`declared Claude resource absent from pinned tree: ${name}`);
+      if (found.some(entry => entry.type === 'tree' && entry.path === name || entry.path.startsWith(name + '/'))) activeDirectories.add(name);
+      for (const entry of found) if (entry.type !== 'tree') selected.add(entry.path);
+    };
+    add('.claude-plugin');
+    for (const directory of ['commands', 'agents', 'skills', 'hooks']) add(directory, false);
+    // Root instructions/configuration can affect Claude even without a resource-directory entry.
+    for (const entry of target.entries) if (!entry.path.includes('/') && entry.type === 'blob') selected.add(entry.path);
+    for (const key of ['commands', 'agents', 'skills', 'hooks', 'mcpServers', 'lspServers', 'settings']) {
+      const value = target.manifest[key];
+      if (value !== undefined && !['hooks', 'mcpServers', 'lspServers', 'settings'].includes(key) && !(typeof value === 'string' || Array.isArray(value) && value.every(item => typeof item === 'string'))) throw Error('unsupported Claude resource declaration');
+      for (const name of (Array.isArray(value) ? value : [value])) if (typeof name === 'string') add(name);
+      if (value && typeof value === 'object') {
+        const refs = JSON.stringify(value).matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([A-Za-z0-9_./-]+)/g);
+        for (const ref of refs) add(ref[1]);
+      }
+    }
+    const pending = [...selected], seen = new Set();
+    for (let index = 0; index < pending.length; index++) {
+      const name = pending[index]; if (seen.has(name)) continue; seen.add(name);
+      const entry = entries.get(name);
+      if (!entry || entry.type !== 'blob' || !['100644', '100755', '120000'].includes(entry.mode)) throw Error(`unverifiable active Claude entry: ${name}`);
+      const file = path.join(root, ...name.split('/'));
+      const stat = fs.lstatSync(file); let bytes;
+      if (entry.mode === '120000') {
+        if (!stat.isSymbolicLink()) throw Error(`declared symlink changed: ${name}`);
+        const link = fs.readlinkSync(file), resolved = path.resolve(path.dirname(file), link);
+        if (!within(root, resolved) || !within(root, fs.realpathSync(file))) throw Error(`Claude symlink escapes artifact: ${name}`);
+        bytes = Buffer.from(link); const dependency = path.relative(root, resolved).split(path.sep).join('/'); add(dependency);
+      } else {
+        if (!stat.isFile() || stat.isSymbolicLink() || !within(root, fs.realpathSync(file)) || stat.size > 8 * 1024 * 1024) throw Error(`unsafe Claude artifact file: ${name}`);
+        bytes = fs.readFileSync(file);
+      }
+      const actual = gitBlobHash(bytes), matched = actual === entry.sha;
+      proof.compared.push({ path: name, expectedBlob: entry.sha, actualBlob: actual, matched });
+      if (!matched) proof.mismatches.push(name);
+      // Expand only references from bytes already independently matched to their immutable Git blob.
+      if (matched && bytes.length < 1024 * 1024 && !bytes.includes(0)) {
+        const refs = bytes.toString('utf8').matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([A-Za-z0-9_./-]+)/g);
+        for (const ref of refs) add(ref[1]);
+        // Literal local imports/config arguments form a bounded, file-relative runtime closure.
+        if (/\.(?:[cm]?js|py|sh|json)$/.test(name)) {
+          const localRefs = bytes.toString('utf8').matchAll(/["'](\.{1,2}\/[^"'\s]+\.(?:[cm]?js|py|sh|json))["']/g);
+          for (const ref of localRefs) {
+            const dependency = path.posix.normalize(path.posix.join(path.posix.dirname(name), ref[1]));
+            if (!safePath(dependency)) throw Error('local Claude runtime reference escapes artifact');
+            // Claude manifest resources resolve from plugin root, already validated above.
+            if (name !== '.claude-plugin/plugin.json') add(dependency);
+          }
+        }
+      }
+      for (const next of selected) if (!seen.has(next) && !pending.includes(next)) pending.push(next);
+    }
+    // Cached default/declared resource directories must not contain undeclared active additions.
+    let inventoried = 0;
+    const reverse = (file, relative) => {
+      if (++inventoried > 5000) throw Error('cached Claude resource inventory is unbounded');
+      const stat = fs.lstatSync(file);
+      if (stat.isDirectory()) {
+        if (!within(root, fs.realpathSync(file))) throw Error('cached Claude resource directory escapes artifact');
+        for (const child of fs.readdirSync(file)) reverse(path.join(file,child), `${relative}/${child}`);
+      } else if (!selected.has(relative)) throw Error(`extra cached active Claude resource: ${relative}`);
+    };
+    for (const directory of activeDirectories) {
+      const file=path.join(root,...directory.split('/'));
+      if (fs.existsSync(file)) reverse(file,directory);
+    }
+    const defaultFiles = ['.mcp.json', '.lsp.json', 'CLAUDE.md', 'settings.json'];
+    for (const name of defaultFiles) if (fs.existsSync(path.join(root,name))) reverse(path.join(root,name),name);
+    proof.reverseInventory = { ok: true, inventoried, directories: [...activeDirectories].sort(), defaultFiles };
+    proof.outsideClaudeProof = target.entries.filter(entry => entry.type !== 'tree' && !seen.has(entry.path)).map(entry => entry.path);
+    proof.ok = proof.compared.length > 0 && proof.mismatches.length === 0;
+    proof.actualClaudeSourceMatched = proof.ok;
+    // Cache contents outside this bounded Claude inventory were not reverse-enumerated.
+    proof.entireRepositoryMatched = false;
+  } catch (error) { proof.error = error.message; }
+  return proof;
+}

package/plugin/scripts/project-capture-queue.mjs

@@ -264,38 +264,42 @@ export function replayOutboxDetached({ projectDir, token = null, spawnFn = spawn
  */
 export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_LOCK_TOKEN || null, budgetMs = DETACHED_REPLAY_BUDGET_MS,
   makeStoreFactory = boundedStoreFactory, now = Date.now, runCapture = runSessionSnapshotHook, onClaim = null,
-  captureNormalized = captureNormalizedTransition, onCaptured = null, env = process.env } = {}) {
-  const deadlineAt = now() + budgetMs;
+  captureNormalized = captureNormalizedTransition, onCaptured = null, env = process.env,
+  deadlineAt: inheritedDeadlineAt = Infinity, signal } = {}) {
+  const deadlineAt = Math.min(inheritedDeadlineAt, now() + budgetMs);
+  if (signal?.aborted || now() >= deadlineAt) return 0;
   if (developmentHooksSuspended(projectDir)) return 0;
   if (operatorProgressionSuspension(env)) { if (token) releaseReplayLock(projectDir, token); return 0; }
   const brainHome = env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain');
   try {
-    const consent = resolveTurnDb({ projectDir, brainHome });
+    const consent = resolveTurnDb({ projectDir, brainHome, deadlineAt, signal });
     if (consent.skipped && !consent.skipped.startsWith('no project memory db')) return 0;
   } catch { return 0; }
+  if (signal?.aborted || now() >= deadlineAt) return 0;
   let held = token || takeReplayLock(projectDir);
   let replayed = 0;
-  for (let round = 0; held && round < 8 && now() < deadlineAt; round += 1) {
+  for (let round = 0; held && round < 8 && now() < deadlineAt && !signal?.aborted; round += 1) {
     try {
       if (!adoptReplayLock(projectDir, held)) return replayed;
       reclaimOrphans(projectDir);
-      const resolution = resolveProjectStore({ projectDir });
-      const store = makeStoreFactory(deadlineAt)({ projectDir, env, requestedStorePath: resolution.canonicalAgentDbPath });
+      const resolution = resolveProjectStore({ projectDir, deadlineAt });
+      const store = makeStoreFactory(deadlineAt)({ projectDir, env, requestedStorePath: resolution.canonicalAgentDbPath, deadlineAt, signal });
       for (const snapshot of store.outbox.pendingSnapshots()) {
         if (operatorProgressionSuspension(env)) return replayed;
-        if (now() >= deadlineAt) return replayed;
+        if (signal?.aborted || now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
-        store.captureFrozen(snapshot, { canCommit: () => refreshReplayLock(projectDir, held) });
+        store.captureFrozen(snapshot, { canCommit: () => !signal?.aborted && now() < deadlineAt && refreshReplayLock(projectDir, held) });
         // captureFrozen commits only the verified key, retaining conflicting original history.
         replayed += 1;
       }
       for (const file of queuedCaptures(projectDir)) {
         if (operatorProgressionSuspension(env)) return replayed;
-        if (now() >= deadlineAt) return replayed;
+        if (signal?.aborted || now() >= deadlineAt) return replayed;
         if (!refreshReplayLock(projectDir, held)) return replayed;
         const claimed = claimQueued(file);
         if (!claimed) continue;
         onClaim?.(claimed);
+        if (signal?.aborted || now() >= deadlineAt) { returnClaim(claimed); return replayed; }
         if (!refreshReplayLock(projectDir, held)) {
           returnClaim(claimed);
           return replayed;
@@ -308,16 +312,17 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
           if (job) {
             // Pre-upgrade raw queues lack origin identity and cannot be truthfully reconstructed.
             if (runCapture === runSessionSnapshotHook && (!job.originProjectDir || (!job.payload?.projectProgression && !job.payload?.normalizedTransition))) { returnClaim(claimed); return replayed; }
-            const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome });
+            const consent = resolveTurnDb({ projectDir: job.originProjectDir || projectDir, brainHome, deadlineAt, signal });
             if (developmentHooksSuspended(job.originProjectDir || projectDir)
               || (consent.skipped && !consent.skipped.startsWith('no project memory db'))) { returnClaim(claimed); return replayed; }
             const options = { rawInput: JSON.stringify(job.payload), host: job.host, env,
-              budgetMs: Math.max(0, deadlineAt - now()), makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
+              budgetMs: Math.max(0, deadlineAt - now()), deadlineAt, signal,
+              makeStoreFactory: () => makeStoreFactory(deadlineAt), now, ordered: held, writeMetadata: false,
               captureTurn: () => ({ recorded: false, skipped: 'detached replay' }),
               captureEvents: () => ({ recorded: 0, skipped: 'detached replay' }) };
             const result = job.payload?.normalizedTransition ? captureNormalized(job, options)
               : runCapture(job.originProjectDir || projectDir, job.event, options);
-            committed = result?.progressionCaptured === true && Boolean(result.receipt);
+            committed = now() < deadlineAt && !signal?.aborted && result?.progressionCaptured === true && Boolean(result.receipt);
             if (committed) onCaptured?.(result);
           }
         } catch { /* retain the queue until an exact-readback receipt exists */ }
@@ -327,7 +332,7 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
     } catch { /* the debt stays durable; the next boundary hands it on again */ } finally {
       releaseReplayLock(projectDir, held);
     }
-    held = now() < deadlineAt && queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
+    held = !signal?.aborted && now() < deadlineAt && queuedWork(projectDir) ? takeReplayLock(projectDir) : null;
   }
   if (held) releaseReplayLock(projectDir, held);
   return replayed;
@@ -338,9 +343,11 @@ export function runOutboxReplay({ projectDir, token = process.env.RUVNET_REPLAY_
 export function drainCaptureQueue({ projectDir, budgetMs = 1000, ...options } = {}) {
   if (operatorProgressionSuspension(options.env || process.env)) return { state: 'suspended', replayed: 0, pending: null };
   const startedAt = Date.now();
-  const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)) });
+  const deadlineAt = Math.min(options.deadlineAt ?? Infinity, startedAt + budgetMs);
+  if (options.signal?.aborted || startedAt >= deadlineAt) return { state: 'pending', replayed: 0, pending: null, reason: 'restore deadline exceeded' };
+  const resolution = resolveProjectStore({ projectDir, gitTimeoutMs: Math.max(1, Math.min(300, budgetMs)), deadlineAt });
   const root = resolution.projectRoot;
-  const replayed = runOutboxReplay({ ...options, projectDir: root, budgetMs: Math.max(0, budgetMs - (Date.now() - startedAt)) });
+  const replayed = runOutboxReplay({ ...options, deadlineAt, projectDir: root, budgetMs: Math.max(0, deadlineAt - Date.now()) });
   let outboxPending = 0;
   try { outboxPending = new ProgressionOutbox({ projectRoot: root }).pendingSnapshots().length; } catch { return { state: 'degraded', replayed, pending: null }; }
   const pending = queuedWork(root) + outboxPending;

package/plugin/scripts/project-progression-producer.mjs

@@ -72,7 +72,7 @@ function marker(source) {
  * The owner's convention writes them into the project's own namespace and into `default`; both are
  * checked, because which one a given session used depends on whether `-n` was passed.
  */
-function ownerNoteRows(canonicalAgentDbPath, projectNamespace) {
+function ownerNoteRows(canonicalAgentDbPath, projectNamespace, options = {}) {
   const namespaces = [...new Set([projectNamespace, ...OWNER_NOTE_NAMESPACES].filter(Boolean))];
   const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
     const rows = [];
@@ -84,12 +84,12 @@ function ownerNoteRows(canonicalAgentDbPath, projectNamespace) {
       }
     }
     return rows;
-  });
+  }, options);
   return result.ok ? result.value : [];
 }
 
 /** The committed heads, computed the same way a restore computes them. Empty store → no heads. */
-function committedHeads(canonicalAgentDbPath, projectIdentity) {
+function committedHeads(canonicalAgentDbPath, projectIdentity, options = {}) {
   const result = withProgressionReader(canonicalAgentDbPath, (reader) => {
     const snapshots = [];
     for (const key of reader.listKeys(PROGRESSION_NAMESPACE)) {
@@ -98,7 +98,7 @@ function committedHeads(canonicalAgentDbPath, projectIdentity) {
       try { snapshots.push(JSON.parse(content)); } catch { /* a malformed row is the restore's problem */ }
     }
     return snapshots;
-  });
+  }, options);
   if (!result.ok) {
     if (fs.existsSync(canonicalAgentDbPath)) throw new Error(`prior progression read unavailable: ${result.reason}`);
     return { heads: [], state: null, readPath: `unavailable (${result.reason})` };
@@ -130,14 +130,20 @@ export function buildProjectProgression({
   env = process.env,
   now = () => new Date().toISOString(),
   trigger = payload.hook_event_name,
+  deadlineAt = Infinity,
+  signal,
 } = {}) {
   if (!resolution || typeof resolution !== 'object') throw new TypeError('resolution must be a project store resolution');
-  const source = readSourceIdentity({ checkoutRoot: resolution.checkoutRoot, kind: resolution.kind });
+  const options = { deadlineAt, signal };
+  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
+  checkDeadline();
+  const source = readSourceIdentity({ checkoutRoot: resolution.checkoutRoot, kind: resolution.kind, ...options });
   source.identity.capturePath = fs.realpathSync.native(projectDir);
   const ledger = readWorkLedger({ projectId: resolution.projectIdentity.id, env });
-  const note = readOwnerNote(() => ownerNoteRows(resolution.canonicalAgentDbPath, path.basename(resolution.projectRoot)));
+  const note = readOwnerNote(() => ownerNoteRows(resolution.canonicalAgentDbPath, path.basename(resolution.projectRoot), options));
   const transcript = readTranscriptReference(payload.transcript_path, { host });
-  const { heads, state: priorState } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity);
+  const { heads, state: priorState } = committedHeads(resolution.canonicalAgentDbPath, resolution.projectIdentity, options);
+  checkDeadline();
 
   const priorSequence = heads.reduce((highest, head) => Math.max(highest, head.sequence ?? 0), 0);
 
@@ -290,7 +296,8 @@ export function buildProjectProgression({
     projectProgression,
     provenance,
     meaningDigest: meaning,
-    ...(priorMeaning === meaning
+    // Compaction requires a fresh durable boundary even when application state is unchanged.
+    ...(trigger !== 'PreCompact' && priorMeaning === meaning
       ? { skipped: { reason: 'no-op capture: project state and source identity are identical to the current head' } }
       : {}),
   };

package/plugin/scripts/project-progression-reader.mjs

@@ -176,7 +176,9 @@ function requireKey(value) {
  * @returns {{ listKeys: Function, readContent: Function, close: Function }}
  * @throws {ProgressionReaderUnavailable} when the CLI must be used instead.
  */
-export function openProgressionReader(dbPath) {
+export function openProgressionReader(dbPath, { deadlineAt = Infinity, signal } = {}) {
+  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
+  checkDeadline();
   const DatabaseSync = databaseSync();
   if (typeof DatabaseSync !== 'function') throw new ProgressionReaderUnavailable('node:sqlite is unavailable');
   if (typeof dbPath !== 'string' || !dbPath) throw new ProgressionReaderUnavailable('no canonical store path');
@@ -230,8 +232,15 @@ export function openProgressionReader(dbPath) {
   return {
     /** Every active key in `namespace`, sorted, deduplicated-by-error, bounded. */
     listKeys(namespace, { maxEntries = 10_000 } = {}) {
+      checkDeadline();
       if (!Number.isSafeInteger(maxEntries) || maxEntries < 1) throw new TypeError('maxEntries must be a positive safe integer');
-      const rows = query(listStatement, [namespace]);
+      let rows = [];
+      if (Number.isFinite(deadlineAt) || signal) {
+        for (const row of listStatement.iterate(namespace)) {
+          checkDeadline(); rows.push(row);
+          if (rows.length > maxEntries) throw new Error('progression enumeration exceeds its bound');
+        }
+      } else rows = query(listStatement, [namespace]);
       if (rows.length > maxEntries) throw new Error('progression enumeration exceeds its bound');
       const keys = [];
       const seen = new Set();
@@ -246,6 +255,7 @@ export function openProgressionReader(dbPath) {
 
     /** The exact stored value for one (namespace, key), or null when that row does not exist. */
     readContent(namespace, key) {
+      checkDeadline();
       requireKey(key);
       const rows = query(readStatement, [namespace, key]);
       if (rows.length === 0) return null;
@@ -275,10 +285,10 @@ export function openProgressionReader(dbPath) {
  * Returns `{ ok: true, value }`, or `{ ok: false, reason }` when the CLI must be used instead.
  * Structural errors are NOT converted — they propagate, by design (see ProgressionReaderUnavailable).
  */
-export function withProgressionReader(dbPath, work) {
+export function withProgressionReader(dbPath, work, options = {}) {
   let reader;
   try {
-    reader = openProgressionReader(dbPath);
+    reader = openProgressionReader(dbPath, options);
   } catch (error) {
     if (error instanceof ProgressionReaderUnavailable) return { ok: false, reason: error.reason };
     throw error;

package/plugin/scripts/project-progression-session-start.mjs

@@ -32,6 +32,7 @@ const UNKNOWN_EXPLANATIONS = Object.freeze({
   'output-bound': 'The full checkpoint and a goal/action-preserving bounded summary do not fit the host context; no checkpoint state was injected.',
   'no-coherent-state': 'No coherent progression head survived validation.',
   'restore-failed': 'The exact structural restore did not complete.',
+  'deadline-exceeded': 'The SessionStart restore deadline expired; no project restoration is claimed and durable work is retained.',
   // MEASURED, and named rather than hidden. The in-process read path costs ~15ms for six snapshots;
   // the `ruflo memory` CLI fallback costs 3634ms for the same six and does NOT fit the 2500ms
   // restore deadline. Both produce an identical result, so this is a SPEED limit, not a correctness
@@ -74,16 +75,17 @@ function unknown(reason, { rowCount = null } = {}) {
  * UNKNOWN should speak, so it never throws and never falls back to a CLI spawn: a count we cannot
  * take cheaply is reported as null ("cannot tell"), which downgrades the banner rather than the run.
  */
-function committedRowCount(canonicalAgentDbPath) {
+function committedRowCount(canonicalAgentDbPath, options) {
   try {
     const result = withProgressionReader(canonicalAgentDbPath,
-      (reader) => reader.listKeys(PROGRESSION_NAMESPACE).length);
+      (reader) => reader.listKeys(PROGRESSION_NAMESPACE).length, options);
     return result.ok ? result.value : null;
   } catch { return null; }
 }
 
 function classify(error) {
   const message = String(error?.message ?? error ?? '');
+  if (/deadline exceeded|deadline exhausted/i.test(message)) return 'deadline-exceeded';
   if (/ruflo was not found|managed global ruflo/i.test(message)) return 'managed-ruflo-unavailable';
   if (/canonical agentdb initialization failed/i.test(message)) return 'initialization-failed';
   if (/structural pagination failed/i.test(message)
@@ -187,31 +189,44 @@ export function restoreProgressionForSession({
   storeFactory,
   maxOutputBytes = SESSION_CONTINUITY_LIMIT_BYTES,
   deadlineMs = SESSION_CONTINUITY_DEADLINE_MS,
+  deadlineAt: inheritedDeadlineAt = Infinity,
+  signal,
   writable = (projectRoot) => {
     try { fs.accessSync(projectRoot, fs.constants.W_OK); return true; } catch { return false; }
   },
 } = {}) {
+  const deadlineAt = Math.min(inheritedDeadlineAt, Date.now() + deadlineMs);
+  const checkDeadline = () => { if (signal?.aborted || Date.now() >= deadlineAt) throw new Error('restore deadline exceeded'); };
+  const boundedRunner = (binary, args, options) => {
+    checkDeadline();
+    const result = spawnSync(binary, args, { ...options,
+      timeout: Math.max(1, Math.floor(Math.min(options.timeout || Infinity, deadlineAt - Date.now()))), killSignal: 'SIGKILL' });
+    if (result.error) throw new Error('restore deadline exceeded');
+    checkDeadline(); return result;
+  };
   const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
   try {
+    checkDeadline();
     if (operatorProgressionSuspension(env)) {
       // Turn recording is independent: suspension must not strand ordinary AgentDB capture.
       const turns = replayTurnQueue({ projectDir, env, home: env.HOME || os.homedir(), synchronous: true,
-        deadlineMs: Date.now() + deadlineMs });
+        deadlineMs: deadlineAt, runner: boundedRunner });
       return { status: 'unavailable', reason: 'operator-suspended', severity: 'info', pendingTurns: turns.pending,
         context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\nAutomatic progression capture, replay and restore are operator-suspended. Evidence and queues are preserved. Ordinary AgentDB memory and explicit checkpoints remain available; no project progression was restored.' };
     }
-  } catch { return unknown('restore-failed'); }
+  } catch (error) { return unknown(classify(error)); }
   let resolution;
   try {
-    resolution = resolveProjectStore({ projectDir });
-  } catch {
-    return unknown('canonical-path');
+    resolution = resolveProjectStore({ projectDir, deadlineAt });
+    checkDeadline();
+  } catch (error) {
+    return unknown(/deadline|timed out/i.test(error.message) ? 'deadline-exceeded' : 'canonical-path');
   }
 
   if (!isProject(resolution)) return unavailable('non-project');
   if (!writable(resolution.projectRoot)) return unavailable('read-only');
   const initializing = !fs.existsSync(resolution.canonicalAgentDbPath);
-  const rowCount = initializing ? 0 : committedRowCount(resolution.canonicalAgentDbPath);
+  const rowCount = initializing ? 0 : committedRowCount(resolution.canonicalAgentDbPath, { deadlineAt, signal });
   const miss = (reason) => unknown(reason, { rowCount });
 
   const prefix = `${RESTORED_HEADER}\n`;
@@ -222,14 +237,7 @@ export function restoreProgressionForSession({
 
   let store;
   try {
-    const deadlineAt = Date.now() + deadlineMs;
-    const boundedRunner = (binary, args, options) => {
-      const remaining = deadlineAt - Date.now();
-      if (remaining < 1) throw new Error('restore deadline exceeded');
-      const result = spawnSync(binary, args, { ...options, timeout: Math.min(options.timeout, remaining) });
-      if (result.error) throw new Error('restore deadline exceeded');
-      return result;
-    };
+    checkDeadline();
     const makeStore = storeFactory ?? ((options) => new ProjectProgressionStore({
       ...options,
       env,
@@ -238,9 +246,11 @@ export function restoreProgressionForSession({
     store = makeStore({
       projectDir,
       requestedStorePath: resolution.canonicalAgentDbPath,
+      deadlineAt, signal,
     });
     const home = env.HOME || env.USERPROFILE || os.homedir();
     const turns = replayTurnQueue({ projectDir, env, home, synchronous: true, runner: boundedRunner, deadlineMs: deadlineAt });
+    checkDeadline();
     if (turns.pending > 0 || turns.failed > 0) {
       const failed = miss('outbox-replay');
       return { ...failed, pendingTurns: turns.pending,
@@ -263,7 +273,8 @@ export function restoreProgressionForSession({
     }
     if (!suspended) {
       const queue = drainCaptureQueue({ projectDir, budgetMs: Math.max(0, deadlineAt - Date.now()),
-        makeStoreFactory: () => () => store });
+        deadlineAt, signal, env, makeStoreFactory: () => () => store });
+      checkDeadline();
       if (queue.state !== 'settled') {
         const failed = miss('outbox-replay');
         return { ...failed, pendingReplay: queue.pending,
@@ -275,6 +286,7 @@ export function restoreProgressionForSession({
     let restored;
     try {
       restored = store.restoreLatest({ maxOutputBytes: payloadLimit, replayPending: !suspended, projectToBound: true });
+      checkDeadline();
     } catch (error) {
       if (store.pendingReplayCount?.() > 0) {
         const failed = miss('outbox-replay');