ruvnet-brain 4.6.3 → 4.7.0

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

@@ -1,233 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { createProgressionSnapshot, digestCanonical } from './project-progression-contract.mjs';
-import { ProjectProgressionStore } from './project-progression-store.mjs';
-import { redactText } from './continuity-events.mjs';
-import os from 'node:os';
-import { resolveTurnDb } from './turn-outcome-capture.mjs';
-import { privateProgressionState, payloadReferencesExcludedResource } from './turn-capture-privacy.mjs';
-
-const HOSTS = new Set(['claude', 'codex']);
-const CAPTURE_TRIGGERS = new Set([
-  'SessionStart',
-  'UserPromptSubmit',
-  'PreToolUse',
-  'PostToolUse',
-  'Stop',
-  'SubagentStop',
-  'PreCompact',
-  'SessionEnd',
-  // The EXPLICIT boundary: /ruvnet-brain:checkpoint. It routes through this same function on
-  // purpose — a second writer for "the model wrote its own state" would be a second writer.
-  'checkpoint',
-]);
-const PLUGIN_JSON = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..', '.claude-plugin', 'plugin.json');
-
-function requireRecord(value, label) {
-  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new TypeError(`${label} must be an object`);
-}
-
-function requireString(value, label) {
-  if (typeof value !== 'string' || !value.trim()) throw new TypeError(`${label} must be a non-empty string`);
-  return value.trim();
-}
-
-function own(value, key) {
-  return Object.prototype.hasOwnProperty.call(value, key);
-}
-
-function aliased(value, camel, snake) {
-  const hasCamel = own(value, camel);
-  const hasSnake = own(value, snake);
-  if (hasCamel && hasSnake) throw new Error(`ambiguous progression field: ${camel}/${snake}`);
-  return hasCamel ? value[camel] : value[snake];
-}
-
-function progressionExtension(payload) {
-  const hasCamel = own(payload, 'projectProgression');
-  const hasSnake = own(payload, 'project_progression');
-  if (hasCamel && hasSnake) throw new Error('ambiguous progression extension');
-  if (!hasCamel && !hasSnake) return null;
-  const value = hasCamel ? payload.projectProgression : payload.project_progression;
-  requireRecord(value, 'project progression');
-  return value;
-}
-
-export function hasProjectProgression(payload) {
-  requireRecord(payload, 'host payload');
-  return progressionExtension(payload) !== null;
-}
-
-export function readProgressionAdapterVersion() {
-  let parsed;
-  try { parsed = JSON.parse(fs.readFileSync(PLUGIN_JSON, 'utf8')); } catch {
-    throw new Error(`progression adapter version is unreadable: ${PLUGIN_JSON}`);
-  }
-  return requireString(parsed?.version, 'progression adapter version');
-}
-
-function normalizeSourceIdentity(value, checkoutRoot, projectDir) {
-  requireRecord(value, 'sourceIdentity');
-  const checkoutPath = requireString(value.checkoutPath, 'sourceIdentity.checkoutPath');
-  let canonicalCheckout;
-  try { canonicalCheckout = fs.realpathSync.native(checkoutPath); } catch {
-    throw new Error('source identity checkout path does not resolve to the active checkout');
-  }
-  if (canonicalCheckout !== checkoutRoot) {
-    throw new Error('source identity checkout path does not match the active checkout path');
-  }
-  return { ...value, checkoutPath: canonicalCheckout, capturePath: fs.realpathSync.native(projectDir) };
-}
-
-const OBSERVATION_TEXT_LIMIT = 4_096;
-
-function boundedText(value) {
-  if (typeof value !== 'string' || !value) return undefined;
-  return value.length <= OBSERVATION_TEXT_LIMIT
-    ? value
-    : `${value.slice(0, OBSERVATION_TEXT_LIMIT)}...[truncated]`;
-}
-
-function toolAction(payload, { contentPathExcludes = [], projectDir } = {}) {
-  const input = payload.tool_input && typeof payload.tool_input === 'object' ? payload.tool_input : {};
-  // Classify original input before bounding it; the excluded reference can occur after 4096 chars.
-  const privateSource = payloadReferencesExcludedResource(payload, contentPathExcludes, projectDir);
-  const command = boundedText(input.command ?? input.cmd);
-  const filePath = boundedText(input.file_path ?? input.notebook_path ?? input.path);
-  const action = command || filePath;
-  if (!action && !payload.tool_name) return null;
-
-  const response = payload.tool_response;
-  const responseRecord = response && typeof response === 'object' && !Array.isArray(response)
-    ? response
-    : null;
-  const explicitCode = responseRecord && [responseRecord.exit_code, responseRecord.exitCode, responseRecord.status]
-    .find((value) => Number.isSafeInteger(value));
-  const responseText = typeof response === 'string' ? response : '';
-  // Native host terminal envelopes may serialize an exact `Exit code: N` line. Do not
-  // scan arbitrary prose: tool output often quotes logs or examples containing `status: 0`.
-  const textualCode = responseText.match(/^\s*Exit code:\s*(-?\d+)\s*$/i);
-  const exitCode = Number.isSafeInteger(explicitCode)
-    ? explicitCode
-    : textualCode ? Number(textualCode[1]) : undefined;
-  const error = boundedText(typeof responseRecord?.error === 'string' ? redactText(responseRecord.error) : undefined);
-  const signal = boundedText(typeof responseRecord?.signal === 'string' ? redactText(responseRecord.signal) : undefined);
-  const interrupted = responseRecord?.interrupted === true || Boolean(signal);
-  const explicitError = responseRecord?.isError === true || payload.is_error === true;
-  const declaredOutcome = ['success', 'failure', 'interrupted', 'unknown'].includes(responseRecord?.outcome)
-    ? responseRecord.outcome : null;
-  const failed = explicitError || Boolean(error) || (Number.isSafeInteger(exitCode) && exitCode !== 0);
-  const terminal = failed || Number.isSafeInteger(exitCode)
-    || responseRecord?.success === true || responseRecord?.ok === true;
-  const outcome = payload.hook_event_name === 'PostToolUse'
-    ? (error ? 'failure' : interrupted ? 'interrupted' : failed ? 'failure' : declaredOutcome || (terminal ? 'success' : 'unknown'))
-    : 'pending';
-  const observation = {
-    trigger: payload.hook_event_name,
-    tool: boundedText(payload.tool_name) || 'unknown',
-    ...(command ? { command } : {}),
-    ...(filePath ? { filePath } : {}),
-    outcome,
-    ...(Number.isSafeInteger(exitCode) ? { exitCode } : responseRecord?.exit_code === null || responseRecord?.exitCode === null ? { exitCode: null } : {}),
-    ...(error ? { error } : {}),
-    ...(signal ? { signal } : {}),
-    ...(interrupted ? { interrupted: true } : {}),
-    ...(explicitError ? { isError: true } : {}),
-  };
-  if (responseRecord) {
-    const stdout = boundedText(responseRecord.stdout);
-    const stderr = boundedText(responseRecord.stderr);
-    if (stdout) observation.stdout = stdout;
-    if (stderr) observation.stderr = stderr;
-  } else {
-    const text = boundedText(response);
-    if (text) observation.result = text;
-  }
-  if (privateSource) {
-    if (command) observation.command = '[REDACTED:excluded-resource-command]'; if (filePath) observation.filePath = '[REDACTED:excluded-path]';
-    for (const field of ['stdout', 'stderr', 'result', 'error', 'signal']) if (Object.hasOwn(observation, field)) observation[field] = '[REDACTED:excluded-resource-output]';
-  }
-  return observation;
-}
-
-export function enrichStateWithObservation(state, payload, privacy) {
-  requireRecord(state, 'completeProjectState');
-  const observation = toolAction(payload, privacy);
-  if (!observation) return state;
-  const commands = Array.isArray(state.commands) ? state.commands : [];
-  const failures = Array.isArray(state.failures) ? state.failures : [];
-  return {
-    ...state,
-    commands: [...commands, observation],
-    ...(observation.outcome === 'failure' || observation.outcome === 'interrupted' ? { failures: [...failures, observation] } : {}),
-  };
-}
-
-function verifyReceipt(snapshot, receipt) {
-  if (!receipt || typeof receipt !== 'object'
-    || receipt.eventKey !== snapshot.eventKey
-    || receipt.payloadDigest !== snapshot.payloadDigest
-    || receipt.readbackDigest !== snapshot.payloadDigest) {
-    throw new Error('progression persistence returned an unverifiable exact-readback receipt');
-  }
-}
-
-export function captureProjectTransition({
-  host,
-  payload,
-  projectDir,
-  adapterVersion = readProgressionAdapterVersion(),
-  recoverFrozen = false,
-  canCommit,
-  env = process.env,
-  storeFactory = (options) => new ProjectProgressionStore(options),
-} = {}) {
-  const normalizedHost = requireString(host, 'host').toLowerCase();
-  if (!HOSTS.has(normalizedHost)) throw new Error(`unsupported progression host: ${normalizedHost}`);
-  requireRecord(payload, 'host payload');
-  const sessionIdentity = requireString(payload.session_id, 'host payload session_id');
-  const trigger = requireString(payload.hook_event_name, 'host payload hook_event_name');
-  if (!CAPTURE_TRIGGERS.has(trigger)) throw new Error(`unsupported progression trigger: ${trigger}`);
-  requireString(adapterVersion, 'adapterVersion');
-  const progression = progressionExtension(payload);
-  if (!progression) throw new Error('host payload is missing a complete progression extension');
-
-  const requestedStorePath = requireString(
-    aliased(progression, 'canonicalAgentDbPath', 'canonical_agent_db_path'),
-    'canonicalAgentDbPath',
-  );
-  if (!path.isAbsolute(requestedStorePath)) throw new Error('canonicalAgentDbPath must be absolute');
-  const store = storeFactory({ projectDir, requestedStorePath });
-  requireRecord(store?.resolution, 'progression store resolution');
-  if (path.resolve(requestedStorePath) !== store.resolution.canonicalAgentDbPath) {
-    throw new Error('foreign store root rejected');
-  }
-
-  const sourceIdentity = normalizeSourceIdentity(
-    aliased(progression, 'sourceIdentity', 'source_identity'),
-    store.resolution.checkoutRoot, projectDir,
-  );
-  const privacy = resolveTurnDb({ projectDir, brainHome: env.RUVNET_BRAIN_HOME || path.join(env.HOME || os.homedir(), '.cache', 'ruvnet-brain') });
-  if (privacy.skipped) throw new Error(`progression capture suspended: ${privacy.skipped}`);
-  const observed = enrichStateWithObservation(aliased(progression, 'completeProjectState', 'complete_project_state'), payload, { contentPathExcludes: privacy.contentPathExcludes, projectDir });
-  const protectedState = privateProgressionState(observed, privacy.contentPathExcludes, projectDir);
-  if (recoverFrozen && digestCanonical(protectedState) !== digestCanonical(observed)) throw new Error('progression capture suspended: content exclusions changed; frozen snapshot retained');
-  let snapshot = createProgressionSnapshot({
-    projectIdentity: store.resolution.projectIdentity,
-    sourceIdentity,
-    hostIdentity: { host: normalizedHost, adapterVersion },
-    sessionIdentity,
-    sequence: progression.sequence,
-    occurredAt: aliased(progression, 'occurredAt', 'occurred_at'),
-    trigger,
-    parentEventKeys: aliased(progression, 'parentEventKeys', 'parent_event_keys'),
-    dedupId: aliased(progression, 'dedupId', 'dedup_id'),
-    completeProjectState: protectedState,
-  });
-  let receipt;
-  if (recoverFrozen) ({ snapshot, receipt } = store.captureFrozen(snapshot, { canCommit }));
-  else receipt = store.capture(snapshot);
-  verifyReceipt(snapshot, receipt);
-  return { snapshot, receipt };
-}

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

@@ -1,225 +0,0 @@
-import fs from 'node:fs';
-import path from 'node:path';
-
-const OUTBOX_NAME = 'project-progression-outbox.jsonl';
-const READ_CHUNK_BYTES = 64 * 1024;
-
-// Decode only complete records, so a multibyte character crossing reads stays intact.
-function* readJsonl(file) {
-  let fd;
-  try { fd = fs.openSync(file, 'r'); } catch (error) { if (error.code === 'ENOENT') return; throw error; }
-  const chunk = Buffer.alloc(READ_CHUNK_BYTES);
-  let parts = [];
-  let line = 0;
-  const parse = (bytes, terminated) => {
-    if (!bytes.length) return undefined;
-    const text = bytes.toString('utf8');
-    if (!text.trim()) return undefined;
-    try { return JSON.parse(text); } catch {
-      if (!terminated) return undefined;
-      throw new Error(`malformed outbox record at line ${line}`);
-    }
-  };
-  try {
-    let length;
-    while ((length = fs.readSync(fd, chunk, 0, chunk.length, null))) {
-      let start = 0;
-      for (let end = 0; end < length; end += 1) {
-        if (chunk[end] !== 10) continue;
-        parts.push(Buffer.from(chunk.subarray(start, end)));
-        line += 1;
-        const record = parse(Buffer.concat(parts), true);
-        if (record !== undefined) yield record;
-        parts = []; start = end + 1;
-      }
-      if (start < length) parts.push(Buffer.from(chunk.subarray(start, length)));
-    }
-    if (parts.length) {
-      line += 1;
-      const record = parse(Buffer.concat(parts), false);
-      if (record !== undefined) yield record;
-    }
-  } finally { fs.closeSync(fd); }
-}
-
-// Inspect only the final record; preceding history is never decoded or copied.
-function finalRecord(fd, size) {
-  const parts = [];
-  let position = size;
-  while (position > 0) {
-    const length = Math.min(READ_CHUNK_BYTES, position);
-    position -= length;
-    const chunk = Buffer.alloc(length);
-    let read = 0;
-    while (read < length) {
-      const count = fs.readSync(fd, chunk, read, length - read, position + read);
-      if (!count) throw new Error('outbox tail changed during inspection');
-      read += count;
-    }
-    const delimiter = chunk.lastIndexOf(10);
-    parts.unshift(delimiter < 0 ? chunk : chunk.subarray(delimiter + 1));
-    if (delimiter >= 0) break;
-  }
-  return Buffer.concat(parts).toString('utf8');
-}
-
-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_RDWR | noFollow, 0o600);
-    try {
-      let separator = '';
-      const size = fs.fstatSync(fd).size;
-      if (size) {
-        const last = Buffer.alloc(1);
-        fs.readSync(fd, last, 0, 1, size - 1);
-        if (last[0] !== 10) {
-          try { JSON.parse(finalRecord(fd, size)); }
-          catch { throw new Error('incomplete outbox final record; preserve and recover the torn tail before appending'); }
-          separator = '\n';
-        }
-      }
-      fs.fchmodSync(fd, 0o600);
-      writeAll(fd, `${separator}${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 });
-  }
-
-  /** Disposition of one frozen payload, never a commit for its conflicting original key. */
-  markRecovered(snapshot, receipt) {
-    for (const [label, value] of Object.entries({ eventKey: snapshot?.eventKey,
-      payloadDigest: snapshot?.payloadDigest, recoveryEventKey: receipt?.eventKey,
-      recoveryPayloadDigest: receipt?.payloadDigest, readbackDigest: receipt?.readbackDigest,
-      committedAt: receipt?.committedAt })) requireIdentity(value, label);
-    if (receipt.eventKey === snapshot.eventKey || receipt.readbackDigest !== receipt.payloadDigest) {
-      throw new Error('unverified recovery disposition');
-    }
-    return this.appendRecord({ type: 'recovery', eventKey: snapshot.eventKey,
-      payloadDigest: snapshot.payloadDigest, recoveryEventKey: receipt.eventKey,
-      recoveryPayloadDigest: receipt.payloadDigest, readbackDigest: receipt.readbackDigest,
-      committedAt: receipt.committedAt });
-  }
-
-  records() {
-    return [...readJsonl(this.path)];
-  }
-
-  /**
-   * Snapshots fsynced but not committed. A key whose records DISAGREE (two snapshots, or a snapshot and
-   * a commit, with different digests) is still never replayed — that is the fail-closed part — but it
-   * is QUARANTINED, not thrown: on this repo's real outbox one such collision (2026-09-18, two Stop
-   * boundaries of one session producing the same sequence and dedup id) made this method throw on
-   * every call, every caller swallowed it, and no pending snapshot was replayed for 13 days while the
-   * SessionStart notice read 0 pending. Quarantined keys are reported by quarantinedKeys().
-   */
-  pendingSnapshots() {
-    const snapshots = new Map();
-    const committed = new Map();
-    const quarantined = new Map();
-    const recoveries = [];
-    let ordinal = 0;
-    for (const record of readJsonl(this.path)) {
-      ordinal += 1;
-      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) quarantined.set(record.eventKey, 'outbox event key collision');
-        // Retain identity/recovery metadata, never every historical snapshot's full payload.
-        // A second incremental scan materializes only the unresolved payloads selected here.
-        else snapshots.set(record.eventKey, { eventKey: record.eventKey, payloadDigest: record.payloadDigest,
-          ordinal, recoveryDiagnostics: record.snapshot?.recoveryDiagnostics && {
-            originalEventKey: record.snapshot.recoveryDiagnostics.originalEventKey,
-            frozenPayloadDigest: record.snapshot.recoveryDiagnostics.frozenPayloadDigest,
-          }, snapshotDigest: record.snapshot?.payloadDigest });
-      } else if (record.type === 'commit') {
-        const prior = committed.get(record.eventKey);
-        if (prior && prior !== record.payloadDigest) quarantined.set(record.eventKey, 'outbox commit collision');
-        committed.set(record.eventKey, record.payloadDigest);
-      } else if (record.type === 'recovery') {
-        requireIdentity(record.recoveryEventKey, 'recovery event key');
-        requireIdentity(record.recoveryPayloadDigest, 'recovery payload digest');
-        if (record.eventKey === record.recoveryEventKey || record.readbackDigest !== record.recoveryPayloadDigest) {
-          throw new Error('unverified recovery disposition');
-        }
-        recoveries.push(record);
-      } else {
-        throw new Error('unsupported outbox record');
-      }
-    }
-    for (const record of snapshots.values()) {
-      const digest = committed.get(record.eventKey);
-      if (digest && digest !== record.payloadDigest && !quarantined.has(record.eventKey)) {
-        quarantined.set(record.eventKey, 'outbox commit digest mismatch');
-      }
-    }
-    const recovered = new Set(recoveries.filter((record) => {
-      const target = snapshots.get(record.recoveryEventKey);
-      return !quarantined.has(record.recoveryEventKey)
-        && committed.get(record.recoveryEventKey) === record.recoveryPayloadDigest
-        && target?.snapshotDigest === record.recoveryPayloadDigest
-        && target.recoveryDiagnostics?.originalEventKey === record.eventKey
-        && target.recoveryDiagnostics?.frozenPayloadDigest === record.payloadDigest;
-    }).map((record) => `${record.eventKey}:${record.payloadDigest}`));
-    this.quarantine = [...quarantined].map(([eventKey, reason]) => ({ eventKey, reason }));
-    const pending = new Map([...snapshots.values()]
-      .filter((record) => !quarantined.has(record.eventKey) && !committed.has(record.eventKey)
-        && !recovered.has(`${record.eventKey}:${record.payloadDigest}`))
-      .map((record) => [record.ordinal, record.eventKey]));
-    const payloads = [];
-    ordinal = 0;
-    if (pending.size) {
-      for (const record of readJsonl(this.path)) {
-        ordinal += 1;
-        if (pending.has(ordinal)) payloads.push({ eventKey: pending.get(ordinal), snapshot: record.snapshot });
-      }
-    }
-    return payloads.sort((left, right) => left.eventKey.localeCompare(right.eventKey)).map((record) => record.snapshot);
-  }
-
-  /** Keys pendingSnapshots() refused to replay because their records disagree, with the reason. */
-  quarantinedKeys() {
-    this.pendingSnapshots();
-    return this.quarantine;
-  }
-}