ruvnet-brain 4.2.2-dev → 4.3.1

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

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const OUTBOX_NAME = 'project-progression-outbox.jsonl';
+
+function requireIdentity(value, label) {
+  if (typeof value !== 'string' || !value) throw new TypeError(`${label} must be a non-empty string`);
+}
+
+function writeAll(fd, value) {
+  const content = Buffer.from(value);
+  let offset = 0;
+  while (offset < content.length) offset += fs.writeSync(fd, content, offset, content.length - offset);
+}
+
+export class ProgressionOutbox {
+  constructor({ projectRoot, fsync = fs.fsyncSync } = {}) {
+    requireIdentity(projectRoot, 'projectRoot');
+    this.path = path.join(projectRoot, '.swarm', OUTBOX_NAME);
+    this.fsync = fsync;
+  }
+
+  appendRecord(record) {
+    fs.mkdirSync(path.dirname(this.path), { recursive: true, mode: 0o700 });
+    const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+    const fd = fs.openSync(this.path, fs.constants.O_APPEND | fs.constants.O_CREAT | fs.constants.O_WRONLY | noFollow, 0o600);
+    try {
+      fs.fchmodSync(fd, 0o600);
+      writeAll(fd, `${JSON.stringify(record)}\n`);
+      this.fsync(fd);
+    } finally {
+      fs.closeSync(fd);
+    }
+    return record;
+  }
+
+  appendSnapshot(snapshot) {
+    requireIdentity(snapshot?.eventKey, 'snapshot.eventKey');
+    requireIdentity(snapshot?.payloadDigest, 'snapshot.payloadDigest');
+    return this.appendRecord({
+      type: 'snapshot',
+      eventKey: snapshot.eventKey,
+      payloadDigest: snapshot.payloadDigest,
+      snapshot,
+    });
+  }
+
+  markCommitted(receipt) {
+    requireIdentity(receipt?.eventKey, 'receipt.eventKey');
+    requireIdentity(receipt?.payloadDigest, 'receipt.payloadDigest');
+    requireIdentity(receipt?.readbackDigest, 'receipt.readbackDigest');
+    requireIdentity(receipt?.committedAt, 'receipt.committedAt');
+    if (receipt.readbackDigest !== receipt.payloadDigest) throw new Error('readback digest mismatch');
+    return this.appendRecord({ type: 'commit', ...receipt });
+  }
+
+  records() {
+    if (!fs.existsSync(this.path)) return [];
+    const content = fs.readFileSync(this.path, 'utf8');
+    const lines = content.split('\n');
+    if (lines.at(-1) !== '') lines.pop();
+    else lines.pop();
+    return lines.filter(Boolean).map((line, index) => {
+      try { return JSON.parse(line); } catch { throw new Error(`malformed outbox record at line ${index + 1}`); }
+    });
+  }
+
+  pendingSnapshots() {
+    const snapshots = new Map();
+    const committed = new Map();
+    for (const record of this.records()) {
+      requireIdentity(record?.eventKey, 'outbox eventKey');
+      requireIdentity(record?.payloadDigest, 'outbox payloadDigest');
+      if (record.type === 'snapshot') {
+        const prior = snapshots.get(record.eventKey);
+        if (prior && prior.payloadDigest !== record.payloadDigest) throw new Error('outbox event key collision');
+        snapshots.set(record.eventKey, record);
+      } else if (record.type === 'commit') {
+        const prior = committed.get(record.eventKey);
+        if (prior && prior !== record.payloadDigest) throw new Error('outbox commit collision');
+        committed.set(record.eventKey, record.payloadDigest);
+      } else {
+        throw new Error('unsupported outbox record');
+      }
+    }
+    return [...snapshots.values()]
+      .filter((record) => {
+        const digest = committed.get(record.eventKey);
+        if (digest && digest !== record.payloadDigest) throw new Error('outbox commit digest mismatch');
+        return !digest;
+      })
+      .sort((left, right) => left.eventKey.localeCompare(right.eventKey))
+      .map((record) => record.snapshot);
+  }
+}

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

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { ProjectProgressionStore } from './project-progression-store.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+
+export const SESSION_CONTINUITY_LIMIT_BYTES = 8 * 1024;
+export const SESSION_CONTINUITY_DEADLINE_MS = 2_500;
+
+const RESTORED_HEADER = '[RuvNet Brain — PROJECT CONTINUITY RESTORED]';
+const UNKNOWN_HEADER = '[RuvNet Brain — PROJECT CONTINUITY UNKNOWN]';
+
+const UNKNOWN_EXPLANATIONS = Object.freeze({
+  'canonical-path': 'The canonical project AgentDB path could not be verified.',
+  'initialization-failed': 'The canonical project AgentDB could not be initialized through managed Ruflo.',
+  'managed-ruflo-unavailable': 'The managed global Ruflo CLI is unavailable.',
+  'pagination-unavailable': 'Structural AgentDB pagination is unavailable on the managed global Ruflo CLI.',
+  'malformed-store': 'Structural AgentDB output is malformed or internally inconsistent.',
+  'exact-readback': 'An exact-listed AgentDB row could not be read back by its exact key.',
+  'outbox-replay': 'The durable progression outbox could not be replayed safely.',
+  'output-bound': 'The verified resume payload exceeds the host context bound.',
+  'no-coherent-state': 'No coherent progression head survived validation.',
+  'restore-failed': 'The exact structural restore did not complete.',
+});
+
+function unknown(reason) {
+  const explanation = UNKNOWN_EXPLANATIONS[reason] ?? UNKNOWN_EXPLANATIONS['restore-failed'];
+  return {
+    status: 'unknown',
+    reason,
+    context: `${UNKNOWN_HEADER}\n${explanation} Do not claim project state was restored; verify the canonical store before relying on remembered state.`,
+  };
+}
+
+function classify(error) {
+  const message = String(error?.message ?? error ?? '');
+  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)
+    && /unknown option|page-info|--offset|unsupported/i.test(message)) return 'pagination-unavailable';
+  if (/malformed pagination|pagination total changed|non-advancing pagination|duplicate progression key/i.test(message)) {
+    return 'malformed-store';
+  }
+  if (/exact retrieval failed|exact key\/payload identity mismatch|readback is not json/i.test(message)) {
+    return 'exact-readback';
+  }
+  if (/outbox|replay/i.test(message)) return 'outbox-replay';
+  if (/resume payload.*bound/i.test(message)) return 'output-bound';
+  if (/no coherent progression state/i.test(message)) return 'no-coherent-state';
+  return 'restore-failed';
+}
+
+function validResume(result) {
+  if (!result || typeof result !== 'object' || typeof result.rendered !== 'string') return false;
+  let parsed;
+  try { parsed = JSON.parse(result.rendered); } catch { return false; }
+  return parsed?.schema === 'ruvnet-brain.project-resume'
+    && parsed.schemaVersion === 1
+    && Array.isArray(parsed.heads)
+    && parsed.heads.length > 0
+    && parsed.state && typeof parsed.state === 'object'
+    && Array.isArray(parsed.state.resumeConflicts)
+    && JSON.stringify(parsed) === JSON.stringify(result.payload);
+}
+
+function resultStatus(result) {
+  return Number.isInteger(result?.status) ? result.status : 1;
+}
+
+function resultText(result, field) {
+  const value = result?.[field];
+  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? '');
+}
+
+function initializeCanonicalStore(store, resolution) {
+  const key = 'project-continuity-bootstrap-v1';
+  const namespace = 'project-progression-control';
+  const value = JSON.stringify({
+    schema: 'ruvnet-brain.project-continuity-bootstrap',
+    schemaVersion: 1,
+    projectIdentity: resolution.projectIdentity,
+  });
+  store.run([
+    'memory', 'store', '--key', key, '--value', value,
+    '--namespace', namespace, '--no-upsert', '--provenance', 'system_observation',
+    '--path', resolution.canonicalAgentDbPath,
+  ]);
+  const readback = store.run([
+    'memory', 'retrieve', '--key', key, '--namespace', namespace,
+    '--value-only', '--path', resolution.canonicalAgentDbPath,
+  ]);
+  if (resultStatus(readback) !== 0 || resultText(readback, 'stdout') !== value
+    || !fs.existsSync(resolution.canonicalAgentDbPath)) {
+    throw new Error('canonical AgentDB initialization failed');
+  }
+}
+
+function isProject(resolution) {
+  if (resolution.kind === 'git') return true;
+  return ['.swarm', '.claude-flow', 'package.json', 'pyproject.toml', 'Cargo.toml', 'go.mod']
+    .some((name) => fs.existsSync(path.join(resolution.projectRoot, name)));
+}
+
+function availableContext(reason) {
+  return {
+    status: 'unavailable',
+    reason,
+    context: '[RuvNet Brain — PROJECT CONTINUITY UNAVAILABLE]\n'
+      + 'This working directory is not a writable adopted project. No AgentDB store was created and no project state was restored.',
+  };
+}
+
+/**
+ * Restore one canonical project's progression at the shared SessionStart boundary.
+ * Empty projects are silent. Any adopted-but-unverifiable store is explicit UNKNOWN.
+ */
+export function restoreProgressionForSession({
+  env = process.env,
+  cwd = process.cwd(),
+  storeFactory,
+  maxOutputBytes = SESSION_CONTINUITY_LIMIT_BYTES,
+  deadlineMs = SESSION_CONTINUITY_DEADLINE_MS,
+  writable = (projectRoot) => {
+    try { fs.accessSync(projectRoot, fs.constants.W_OK); return true; } catch { return false; }
+  },
+} = {}) {
+  const projectDir = env.CLAUDE_PROJECT_DIR || cwd;
+  let resolution;
+  try {
+    resolution = resolveProjectStore({ projectDir });
+  } catch {
+    return unknown('canonical-path');
+  }
+
+  if (!isProject(resolution)) return availableContext('non-project');
+  if (!writable(resolution.projectRoot)) return availableContext('read-only');
+  const initializing = !fs.existsSync(resolution.canonicalAgentDbPath);
+
+  const prefix = `${RESTORED_HEADER}\n`;
+  const payloadLimit = maxOutputBytes - Buffer.byteLength(prefix, 'utf8');
+  if (!Number.isSafeInteger(payloadLimit) || payloadLimit < 1) return unknown('output-bound');
+
+  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;
+    };
+    const makeStore = storeFactory ?? ((options) => new ProjectProgressionStore({
+      ...options,
+      runner: boundedRunner,
+    }));
+    const store = makeStore({
+      projectDir,
+      requestedStorePath: resolution.canonicalAgentDbPath,
+    });
+    if (initializing) {
+      fs.mkdirSync(path.dirname(resolution.canonicalAgentDbPath), { recursive: true, mode: 0o700 });
+      initializeCanonicalStore(store, resolution);
+    }
+    const restored = store.restoreLatest({ maxOutputBytes: payloadLimit });
+    if (!validResume(restored)) return unknown('malformed-store');
+    const context = `${prefix}${restored.rendered}`;
+    if (Buffer.byteLength(context, 'utf8') > maxOutputBytes) return unknown('output-bound');
+    return { status: 'restored', context };
+  } catch (error) {
+    // A structurally enumerated, genuinely empty namespace is normal for a newly adopted project.
+    if (/no coherent progression state/i.test(String(error?.message ?? ''))
+      && Array.isArray(error?.rejectedCandidates) && error.rejectedCandidates.length === 0) {
+      if (initializing && !fs.existsSync(resolution.canonicalAgentDbPath)) return unknown('initialization-failed');
+      return {
+        status: initializing ? 'initialized' : 'empty',
+        context: initializing
+          ? '[RuvNet Brain — PROJECT CONTINUITY INITIALIZED]\nThe canonical AgentDB store is ready; no prior progression snapshot exists yet.'
+          : '[RuvNet Brain — PROJECT CONTINUITY EMPTY]\nThe canonical AgentDB store was structurally enumerated and contains no prior progression snapshot.',
+      };
+    }
+    return unknown(classify(error));
+  }
+}

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

@@ -0,0 +1,248 @@
+import { spawnSync } from 'node:child_process';
+import path from 'node:path';
+import { ProgressionOutbox } from './project-progression-outbox.mjs';
+import {
+  digestCanonical,
+  restoreProjectProgression,
+  validateProgressionSnapshot,
+} from './project-progression-contract.mjs';
+import { resolveProjectStore } from './project-store-resolver.mjs';
+import { resolveRuflo, RUFLO_MISSING } from './ruflo-bin.mjs';
+
+const PROGRESSION_NAMESPACE = 'project-progression';
+const RESUME_SCHEMA = 'ruvnet-brain.project-resume';
+const RESUME_VERSION = 1;
+
+function defaultRunner(binary, args, options) {
+  return spawnSync(binary, args, options);
+}
+
+function resultStatus(result) {
+  return Number.isInteger(result?.status) ? result.status : 1;
+}
+
+function resultText(result, field) {
+  const value = result?.[field];
+  return Buffer.isBuffer(value) ? value.toString('utf8') : String(value ?? '');
+}
+
+function parseJson(text, label) {
+  try { return JSON.parse(text); } catch { throw new Error(`${label} is not JSON`); }
+}
+
+function plainRecord(value) {
+  return value && typeof value === 'object' && !Array.isArray(value);
+}
+
+function requirePositiveInteger(value, label) {
+  if (!Number.isSafeInteger(value) || value < 1) throw new TypeError(`${label} must be a positive safe integer`);
+}
+
+function validatePage(page, { offset, pageSize, total }) {
+  if (!plainRecord(page) || !Array.isArray(page.entries)
+    || !Number.isSafeInteger(page.total) || page.total < 0
+    || page.limit !== pageSize || page.offset !== offset
+    || typeof page.hasMore !== 'boolean') {
+    throw new Error('malformed pagination page');
+  }
+  if (total !== null && page.total !== total) throw new Error('pagination total changed during restoration');
+  if (page.entries.length > pageSize || offset + page.entries.length > page.total) {
+    throw new Error('malformed pagination page');
+  }
+  const consumed = offset + page.entries.length;
+  if (page.hasMore) {
+    if (!Number.isSafeInteger(page.nextOffset) || page.nextOffset <= offset) {
+      throw new Error('non-advancing pagination page');
+    }
+    if (page.nextOffset !== consumed || consumed >= page.total) throw new Error('malformed pagination page');
+  } else if (page.nextOffset !== null || consumed !== page.total) {
+    throw new Error('malformed pagination page');
+  }
+  return page.total;
+}
+
+function sortRejected(rows) {
+  return rows.sort((left, right) => String(left.eventKey).localeCompare(String(right.eventKey))
+    || left.reasons.join('|').localeCompare(right.reasons.join('|')));
+}
+
+export class ProjectProgressionStore {
+  constructor({
+    projectDir,
+    requestedStorePath,
+    rufloBinary = resolveRuflo(),
+    runner = defaultRunner,
+    clock = () => new Date().toISOString(),
+    fsync,
+  } = {}) {
+    if (!rufloBinary) throw new Error(RUFLO_MISSING);
+    this.resolution = resolveProjectStore({ projectDir, requestedStorePath });
+    this.rufloBinary = rufloBinary;
+    this.runner = runner;
+    this.clock = clock;
+    this.outbox = new ProgressionOutbox({ projectRoot: this.resolution.projectRoot, fsync });
+  }
+
+  run(args) {
+    return this.runner(this.rufloBinary, args, {
+      cwd: path.dirname(this.resolution.canonicalAgentDbPath),
+      encoding: 'utf8',
+      timeout: 120_000,
+      env: { ...process.env, RUFLO_DAEMON_AUTOSTART: '0' },
+    });
+  }
+
+  validateSnapshot(snapshot) {
+    const verdict = validateProgressionSnapshot(snapshot, {
+      expectedProjectIdentity: this.resolution.projectIdentity,
+    });
+    if (!verdict.ok) throw new Error(`invalid progression snapshot: ${verdict.errors.join(', ')}`);
+  }
+
+  appendExact(snapshot, { onPhase = () => {} } = {}) {
+    this.validateSnapshot(snapshot);
+    const stored = this.run([
+      'memory', 'store', '--key', snapshot.eventKey, '--value', JSON.stringify(snapshot),
+      '--namespace', PROGRESSION_NAMESPACE, '--no-upsert', '--provenance', 'system_observation',
+      '--path', this.resolution.canonicalAgentDbPath,
+    ]);
+    const alreadyStored = resultStatus(stored) !== 0;
+    if (!alreadyStored) onPhase('stored');
+
+    const retrieved = this.run([
+      'memory', 'retrieve', '--key', snapshot.eventKey, '--namespace', PROGRESSION_NAMESPACE,
+      '--value-only', '--path', this.resolution.canonicalAgentDbPath,
+    ]);
+    if (resultStatus(retrieved) !== 0) {
+      const storeFailure = alreadyStored
+        ? `; store failed: ${resultText(stored, 'stderr').trim() || 'unknown error'}`
+        : '';
+      throw new Error(`progression readback failed: ${resultText(retrieved, 'stderr').trim() || 'unknown error'}${storeFailure}`);
+    }
+    let readback;
+    try { readback = JSON.parse(resultText(retrieved, 'stdout')); } catch { throw new Error('progression readback is not JSON'); }
+    if (readback.payloadDigest !== snapshot.payloadDigest || digestCanonical(readback) !== digestCanonical(snapshot)) {
+      throw new Error('progression readback digest mismatch');
+    }
+    onPhase('readback-verified');
+    return {
+      eventKey: snapshot.eventKey,
+      payloadDigest: snapshot.payloadDigest,
+      readbackDigest: readback.payloadDigest,
+      alreadyStored,
+      committedAt: this.clock(),
+    };
+  }
+
+  capture(snapshot, { onPhase = () => {} } = {}) {
+    this.validateSnapshot(snapshot);
+    this.outbox.appendSnapshot(snapshot);
+    onPhase('outbox-fsynced');
+    const receipt = this.appendExact(snapshot, { onPhase });
+    this.outbox.markCommitted(receipt);
+    return receipt;
+  }
+
+  replay() {
+    const receipts = [];
+    for (const snapshot of this.outbox.pendingSnapshots()) {
+      const receipt = this.appendExact(snapshot);
+      this.outbox.markCommitted(receipt);
+      receipts.push(receipt);
+    }
+    return receipts;
+  }
+
+  listSnapshotKeys({ pageSize = 100 } = {}) {
+    requirePositiveInteger(pageSize, 'pageSize');
+    const keys = [];
+    const seen = new Set();
+    let offset = 0;
+    let total = null;
+    do {
+      const listed = this.run([
+        'memory', 'list', '--namespace', PROGRESSION_NAMESPACE,
+        '--limit', String(pageSize), '--offset', String(offset), '--page-info', '--format', 'json',
+        '--path', this.resolution.canonicalAgentDbPath,
+      ]);
+      if (resultStatus(listed) !== 0) {
+        throw new Error(`progression structural pagination failed: ${resultText(listed, 'stderr').trim() || 'unknown error'}`);
+      }
+      const page = parseJson(resultText(listed, 'stdout'), 'progression pagination page');
+      total = validatePage(page, { offset, pageSize, total });
+      for (const entry of page.entries) {
+        if (!plainRecord(entry) || typeof entry.key !== 'string' || !entry.key
+          || entry.namespace !== PROGRESSION_NAMESPACE) throw new Error('malformed pagination entry');
+        if (seen.has(entry.key)) throw new Error(`duplicate progression key across pages: ${entry.key}`);
+        seen.add(entry.key);
+        keys.push(entry.key);
+      }
+      if (!page.hasMore) break;
+      offset = page.nextOffset;
+    } while (true);
+    if (keys.length !== total) throw new Error('pagination did not enumerate the declared total');
+    return keys.sort();
+  }
+
+  retrieveSnapshots(keys) {
+    const snapshots = [];
+    const rejected = [];
+    for (const key of keys) {
+      const retrieved = this.run([
+        'memory', 'retrieve', '--key', key, '--namespace', PROGRESSION_NAMESPACE,
+        '--value-only', '--path', this.resolution.canonicalAgentDbPath,
+      ]);
+      if (resultStatus(retrieved) !== 0) {
+        throw new Error(`progression exact retrieval failed for ${key}: ${resultText(retrieved, 'stderr').trim() || 'unknown error'}`);
+      }
+      let snapshot;
+      try { snapshot = JSON.parse(resultText(retrieved, 'stdout')); } catch {
+        rejected.push({ eventKey: key, reasons: ['readback is not JSON'] });
+        continue;
+      }
+      if (!plainRecord(snapshot) || snapshot.eventKey !== key) {
+        rejected.push({ eventKey: key, reasons: ['exact key/payload identity mismatch'] });
+        continue;
+      }
+      snapshots.push(snapshot);
+    }
+    return { snapshots, rejected: sortRejected(rejected) };
+  }
+
+  restoreLatest({ pageSize = 100, maxOutputBytes = 64 * 1024 } = {}) {
+    requirePositiveInteger(maxOutputBytes, 'maxOutputBytes');
+    this.replay();
+    const keys = this.listSnapshotKeys({ pageSize });
+    const exact = this.retrieveSnapshots(keys);
+    const restored = restoreProjectProgression(exact.snapshots, {
+      expectedProjectIdentity: this.resolution.projectIdentity,
+    });
+    const rejectedCandidates = sortRejected([
+      ...exact.rejected,
+      ...restored.rejected.filter((row) => row.reasons.some((reason) => reason !== 'causally stale')),
+    ]);
+    if (!restored.ok) {
+      const error = new Error('no coherent progression state could be restored');
+      error.rejectedCandidates = rejectedCandidates;
+      throw error;
+    }
+    const payload = {
+      schema: RESUME_SCHEMA,
+      schemaVersion: RESUME_VERSION,
+      projectIdentity: this.resolution.projectIdentity,
+      heads: restored.heads,
+      state: restored.state,
+      evidence: {
+        structurallyEnumerated: keys.length,
+        exactRetrieved: keys.length,
+        causallyStale: restored.causallyStale.length,
+        rejectedCandidates,
+      },
+    };
+    const rendered = JSON.stringify(payload);
+    if (Buffer.byteLength(rendered, 'utf8') > maxOutputBytes) {
+      throw new Error(`resume payload exceeds the ${maxOutputBytes}-byte output bound`);
+    }
+    return { payload, rendered };
+  }
+}

package/plugin/scripts/project-store-resolver.mjs

@@ -0,0 +1,106 @@
+import crypto from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execFileSync } from 'node:child_process';
+
+function sha256(value) {
+  return crypto.createHash('sha256').update(value).digest('hex');
+}
+
+function rejectParentTraversal(value, label) {
+  if (value.split(/[\\/]+/).includes('..')) throw new Error(`${label} contains parent traversal`);
+}
+
+function canonicalDirectory(value, label) {
+  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} must be a non-empty path`);
+  rejectParentTraversal(value, label);
+  let canonical;
+  try { canonical = fs.realpathSync.native(value); } catch { throw new Error(`${label} does not exist`); }
+  if (!fs.statSync(canonical).isDirectory()) throw new Error(`${label} must be a directory`);
+  return canonical;
+}
+
+function canonicalProspectivePath(value) {
+  let cursor = path.resolve(value);
+  const missing = [];
+  while (!fs.existsSync(cursor)) {
+    const parent = path.dirname(cursor);
+    if (parent === cursor) throw new Error('store path has no resolvable ancestor');
+    missing.unshift(path.basename(cursor));
+    cursor = parent;
+  }
+  if (missing.length && !fs.statSync(cursor).isDirectory()) {
+    throw new Error('store path ancestor must be a directory');
+  }
+  return path.join(fs.realpathSync.native(cursor), ...missing);
+}
+
+function isWithin(root, candidate) {
+  const relative = path.relative(root, candidate);
+  return relative === '' || (!path.isAbsolute(relative) && relative !== '..' && !relative.startsWith(`..${path.sep}`));
+}
+
+function gitValue(cwd, args) {
+  try {
+    return execFileSync('git', args, {
+      cwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
+function gitProject(projectDir) {
+  const commonValue = gitValue(projectDir, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  const checkoutValue = gitValue(projectDir, ['rev-parse', '--show-toplevel']);
+  if (!commonValue || !checkoutValue) return null;
+  const gitCommonDir = canonicalDirectory(commonValue, 'Git common directory');
+  const checkoutRoot = canonicalDirectory(checkoutValue, 'Git checkout root');
+  if (path.basename(gitCommonDir) !== '.git') {
+    throw new Error('Git common directory must identify a canonical primary checkout');
+  }
+  return {
+    gitCommonDir,
+    checkoutRoot,
+    projectRoot: canonicalDirectory(path.dirname(gitCommonDir), 'Git project root'),
+  };
+}
+
+export function resolveProjectStore({ projectDir = process.cwd(), requestedStorePath } = {}) {
+  const canonicalInput = canonicalDirectory(projectDir, 'projectDir');
+  const git = gitProject(canonicalInput);
+  const resolved = git ?? {
+    gitCommonDir: null,
+    checkoutRoot: canonicalInput,
+    projectRoot: canonicalInput,
+  };
+  const kind = git ? 'git' : 'non-git';
+  const canonicalAgentDbPath = path.join(resolved.projectRoot, '.swarm', 'memory.db');
+  const resolvedAgentDbPath = canonicalProspectivePath(canonicalAgentDbPath);
+  if (!isWithin(resolved.projectRoot, resolvedAgentDbPath)) {
+    throw new Error('store symlink escape rejected');
+  }
+  if (requestedStorePath !== undefined) {
+    if (typeof requestedStorePath !== 'string' || !requestedStorePath.trim()) {
+      throw new TypeError('requestedStorePath must be a non-empty path');
+    }
+    rejectParentTraversal(requestedStorePath, 'requestedStorePath');
+    if (canonicalProspectivePath(requestedStorePath) !== resolvedAgentDbPath) {
+      throw new Error('foreign store root rejected');
+    }
+  }
+  const projectIdentity = Object.freeze({
+    id: `${kind}-sha256:${sha256(resolved.gitCommonDir ?? resolved.projectRoot)}`,
+    canonicalAgentDbPath,
+  });
+  return Object.freeze({
+    kind,
+    projectRoot: resolved.projectRoot,
+    checkoutRoot: resolved.checkoutRoot,
+    gitCommonDir: resolved.gitCommonDir,
+    canonicalAgentDbPath,
+    projectIdentity,
+  });
+}

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

@@ -1,5 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import {
+  captureProjectTransition,
+  hasProjectProgression,
+} from './project-progression-hook.mjs';
 import { createSessionSnapshot } from './session-snapshot-contract.mjs';
 import { projectDirectory } from './project-identity.mjs';
 
@@ -39,8 +43,32 @@ export function writeSessionSnapshot(projectDir, event) {
   }
 }
 
+export function runSessionSnapshotHook(projectDir, event, {
+  rawInput = '',
+  host = process.env.RUVNET_HOOK_HOST || 'claude',
+  captureProgression = captureProjectTransition,
+} = {}) {
+  const metadataWritten = writeSessionSnapshot(projectDir, event);
+  let payload;
+  try { payload = rawInput ? JSON.parse(rawInput) : {}; } catch { payload = {}; }
+  if (!hasProjectProgression(payload)) {
+    return { metadataWritten, progressionCaptured: false, receipt: null };
+  }
+  if (payload.hook_event_name !== event) {
+    throw new Error(`progression boundary mismatch: expected ${event}, received ${payload.hook_event_name}`);
+  }
+  const result = captureProgression({ host, payload, projectDir });
+  return { metadataWritten, progressionCaptured: true, receipt: result.receipt };
+}
+
 if (process.argv[1] && path.resolve(process.argv[1]).endsWith('session-snapshot-hook.mjs')) {
   // projectDirectory() is the SAME derivation the Console's detector uses. Deriving it here
   // independently is what let this hook write a receipt the Console then reported as missing (#85).
-  writeSessionSnapshot(projectDirectory(), process.argv[2] || 'SessionEnd');
+  const rawInput = fs.readFileSync(0, 'utf8');
+  try {
+    runSessionSnapshotHook(projectDirectory(), process.argv[2] || 'SessionEnd', { rawInput });
+  } catch (error) {
+    process.stderr.write(`[project-progression] ${error.message}\n`);
+    process.exitCode = 1;
+  }
 }