harness-everything 0.2.2 → 0.4.0

package/plugins/harness-everything/hooks/scripts/codex-action-gate-post.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+'use strict';
+
+const { finalizeExecution } = require('./action-gate');
+
+function inferOutcome(payload) {
+  const response = (payload && (payload.tool_response || payload.toolResponse)) || {};
+  const rawExitCode = response.exitCode ?? response.exit_code ?? payload?.exitCode ?? payload?.exit_code;
+  if (typeof rawExitCode === 'number') return rawExitCode === 0 ? 'success' : 'failure';
+  if (response.success === false || response.ok === false) return 'failure';
+
+  const stderr = response.stderr ?? payload?.stderr ?? '';
+  if (typeof stderr === 'string' && stderr.trim()) {
+    if (/\b(error|fail|failed|failure|exception|fatal|panic|traceback|denied|refused|cannot|unable)\b/i.test(stderr)) {
+      return 'failure';
+    }
+  }
+  return 'success';
+}
+
+function processPayload(payload) {
+  return finalizeExecution(payload, inferOutcome(payload));
+}
+
+function run() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      processPayload(JSON.parse(raw || '{}'));
+    } catch (err) {
+      // PostToolUse runs after the side effect. Audit failures must never be
+      // misrepresented as a successful enforcement decision or block the host.
+      console.error(`[Harness actionGate] Codex post-tool audit failed: ${err.message}`);
+    }
+    process.exitCode = 0;
+  });
+}
+
+if (require.main === module) run();
+
+module.exports = {
+  inferOutcome,
+  processPayload,
+};

package/plugins/harness-everything/hooks/scripts/codex-permission-request.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+'use strict';
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const {
+  getWorkspaceRoot,
+  getSessionDir,
+} = require('./lib/harness-state');
+const {
+  RULES_PATH,
+  classify,
+  exactPayloadText,
+  loadRuleTable,
+} = require('./action-gate');
+
+function hookEventOf(payload) {
+  return String((payload && (payload.hook_event_name || payload.hookEventName)) || 'PermissionRequest');
+}
+
+function toolNameOf(payload) {
+  return String((payload && (payload.tool_name || payload.toolName)) || '');
+}
+
+function hashExact(value) {
+  return crypto.createHash('sha256').update(String(value || ''), 'utf8').digest('hex');
+}
+
+function safePart(value, fallback) {
+  const text = String(value || '').replace(/[^A-Za-z0-9._-]+/g, '_').slice(0, 120);
+  return text || fallback;
+}
+
+function sessionContext(payload, overrideSessionDir) {
+  if (overrideSessionDir) return { sessionDir: overrideSessionDir };
+  const root = getWorkspaceRoot(payload);
+  const sessionId = payload && (payload.session_id || payload.sessionId);
+  return { sessionDir: getSessionDir(root, sessionId, payload) };
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const temp = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(temp, filePath);
+}
+
+function auditPermissionRequest(payload, options = {}) {
+  const event = hookEventOf(payload);
+  if (event !== 'PermissionRequest') return { kind: 'noop', exitCode: 0, record: null, auditFile: null };
+
+  const context = sessionContext(payload, options.sessionDir);
+  const table = options.ruleTable || loadRuleTable(options.rulePath || RULES_PATH);
+  const rule = classify(payload, table.rules, context.sessionDir);
+  const exact = exactPayloadText(payload);
+  const payloadHash = hashExact(exact);
+  const turnId = (payload && (payload.turn_id || payload.turnId)) || null;
+  const now = new Date().toISOString();
+  const record = {
+    schemaVersion: 1,
+    event: 'PermissionRequest',
+    host: 'codex',
+    turnId,
+    toolName: toolNameOf(payload),
+    payloadHash,
+    matchedRule: rule ? rule.id : null,
+    ruleReason: rule ? rule.reason : null,
+    permissionMode: (payload && (payload.permission_mode || payload.permissionMode)) || null,
+    disposition: 'deferred-to-codex-approval',
+    correlation: 'turn-id-and-payload-hash-only',
+    exactToolCallCorrelation: false,
+    ruleTableSource: table.source,
+    degradedRuleTable: table.degraded,
+    degradationReason: table.degradationReason,
+    createdAt: now,
+    updatedAt: now,
+  };
+
+  const dir = path.join(context.sessionDir, 'action-gate', 'codex-permission-request');
+  const file = path.join(dir, `${safePart(turnId, 'turn')}-${payloadHash.slice(0, 24)}.json`);
+  atomicWriteJson(file, record);
+
+  // PermissionRequest means Codex is already entering its native approval flow.
+  // Returning no allow/deny decision preserves that flow. This hook must never
+  // be treated as a way to manufacture an approval prompt for an otherwise
+  // permitted action.
+  return { kind: 'defer', exitCode: 0, stdout: null, stderr: null, record, auditFile: file };
+}
+
+function internalErrorResult(err) {
+  return {
+    kind: 'audit-error',
+    exitCode: 0,
+    stdout: null,
+    stderr: `[Harness actionGate] Codex PermissionRequest audit failed: ${err.message}. Native Codex approval flow remains authoritative.`,
+  };
+}
+
+function processPayload(payload, options = {}) {
+  try {
+    return auditPermissionRequest(payload, options);
+  } catch (err) {
+    return internalErrorResult(err);
+  }
+}
+
+function emitResult(result) {
+  if (result.stderr) console.error(result.stderr);
+  if (result.stdout) process.stdout.write(`${JSON.stringify(result.stdout)}\n`);
+  return result.exitCode || 0;
+}
+
+function run() {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => {
+    let payload = {};
+    try {
+      payload = JSON.parse(raw || '{}');
+    } catch (err) {
+      process.exitCode = emitResult(internalErrorResult(new Error(`invalid hook JSON: ${err.message}`)));
+      return;
+    }
+    process.exitCode = emitResult(processPayload(payload));
+  });
+  process.stdin.on('error', err => {
+    process.exitCode = emitResult(internalErrorResult(err));
+  });
+}
+
+if (require.main === module) run();
+
+module.exports = {
+  auditPermissionRequest,
+  hashExact,
+  internalErrorResult,
+  processPayload,
+};

package/plugins/harness-everything/hooks/scripts/context-compact.js

@@ -0,0 +1,115 @@
+#!/usr/bin/env node
+const { execSync } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+const { getWorkspaceRoot, getSessionDir } = require('./lib/harness-state');
+
+function main(payload) {
+  try {
+    // Let's run a quick Git check to estimate context size from modified files
+    const root = getWorkspaceRoot(payload);
+    const statusRaw = execSync('git status --porcelain', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+    if (!statusRaw) {
+      process.exit(0);
+    }
+
+    const lines = statusRaw.split('\n').filter(Boolean);
+    const modifiedCount = lines.length;
+
+    let totalDiffLines = 0;
+    try {
+      const diffStat = execSync('git diff --numstat', { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] }).trim();
+      if (diffStat) {
+        diffStat.split('\n').forEach(line => {
+          const [added, deleted] = line.split('\t');
+          if (added && added !== '-' && deleted && deleted !== '-') {
+            totalDiffLines += parseInt(added) + parseInt(deleted);
+          }
+        });
+      }
+    } catch (err) {
+      // Ignore git errors
+    }
+
+    // Thresholds for warning
+    const HIGH_FILE_LIMIT = 6;
+    const HIGH_LINE_LIMIT = 400;
+
+    const overThreshold = modifiedCount >= HIGH_FILE_LIMIT || totalDiffLines >= HIGH_LINE_LIMIT;
+
+    // Throttle: this hook fires on EVERY Bash/Edit/Write call, and a warning
+    // about context bloat that repeats on every call becomes context bloat
+    // itself (and trains the model to ignore hook output). Warn on the first
+    // crossing, then only every 10th call while still over - or when the diff
+    // has grown another 50% since the last warning.
+    const stateFile = path.join(getSessionDir(root, payload && (payload.session_id || payload.sessionId)), 'context-compact-state.json');
+    let state = { overCount: 0, lastWarnedLines: 0 };
+    try {
+      if (fs.existsSync(stateFile)) state = JSON.parse(fs.readFileSync(stateFile, 'utf8'));
+    } catch (err) { /* use default */ }
+
+    if (!overThreshold) {
+      if (state.overCount > 0) {
+        try {
+          fs.writeFileSync(stateFile, JSON.stringify({ overCount: 0, lastWarnedLines: 0 }), 'utf8');
+        } catch (err) { /* ignore */ }
+      }
+      process.exit(0);
+    }
+
+    state.overCount += 1;
+    const onBeat = state.overCount === 1 || state.overCount % 10 === 0;
+    const grewALot = totalDiffLines >= (state.lastWarnedLines || 0) * 1.5 && totalDiffLines > state.lastWarnedLines;
+    const shouldWarn = onBeat || grewALot;
+    if (shouldWarn) state.lastWarnedLines = totalDiffLines;
+    try {
+      fs.writeFileSync(stateFile, JSON.stringify(state), 'utf8');
+    } catch (err) { /* ignore */ }
+
+    if (shouldWarn) {
+      // Plain stdout on exit 0 is only surfaced to Claude for UserPromptSubmit/
+      // SessionStart - for PreToolUse it's written to a debug log Claude never
+      // sees. To actually get an advisory (non-blocking) message in front of
+      // Claude here, it has to go through hookSpecificOutput.additionalContext.
+      const message = [
+        `Harness OS - Context Bloat Warning`,
+        `- Modified Files: ${modifiedCount}`,
+        `- Accumulated Diff: ${totalDiffLines} lines`,
+        ``,
+        `Caution: Large number of modified files or big diffs will bloat the Agent context window, leading to:`,
+        `  1. "Lost in the Middle" reasoning degradation`,
+        `  2. Rapidly inflating token costs`,
+        ``,
+        `Recommended Action:`,
+        `  - Run atomic commits or stage completed files.`,
+        `  - Use targeted sub-folders rather than broad searches.`,
+        `  - Ask user to run '/compact' or '/clear' if supported.`
+      ].join('\n');
+
+      console.log(JSON.stringify({
+        hookSpecificOutput: {
+          hookEventName: "PreToolUse",
+          additionalContext: message
+        }
+      }));
+    }
+  } catch (err) {
+    // Fail open - never block user execution on compaction checker
+  }
+
+  process.exit(0);
+}
+
+let inputData = '';
+const timeout = setTimeout(() => { main(null); }, 200);
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  clearTimeout(timeout);
+  let payload = null;
+  try { payload = JSON.parse(inputData.trim()); } catch (err) { /* no payload */ }
+  main(payload);
+});
+process.stdin.on('error', () => {
+  clearTimeout(timeout);
+  main(null);
+});

package/plugins/harness-everything/hooks/scripts/contract-test.js

@@ -0,0 +1,146 @@
+#!/usr/bin/env node
+/**
+ * Contract Test (PostToolUse: Bash|PowerShell)
+ *
+ * Phase 3 resolves Fable stage checks against run-scoped contracts under the
+ * workspace-keyed global state root:
+ *   state/fable-runs/<runId>/contracts/<stageId>.json
+ *
+ * A check is updated only when the command can be correlated to exactly one
+ * run/stage (session/worker metadata narrows the match when the host exposes
+ * it). Ambiguous matches are surfaced instead of mutating multiple runs.
+ * Verification evidence is written beside the run so planId/runId/stageId
+ * remain auditable without moving Fable's audit/model-selection ownership.
+ */
+const fs = require('fs');
+const path = require('path');
+const { getSessionId, getWorkspaceRoot, getStateRoot } = require('./lib/harness-state');
+const {
+  atomicWriteJson,
+  chooseCorrelatedContract,
+  commandMatches,
+  listRunContracts,
+} = require('./lib/fable-contracts');
+
+function resultState(payload) {
+  const toolResponse = payload.tool_response || payload.tool_result || {};
+  const stdout = toolResponse.stdout ?? payload.stdout ?? '';
+  const stderr = toolResponse.stderr ?? payload.stderr ?? '';
+  const rawExitCode = toolResponse.exitCode ?? toolResponse.exit_code ?? toolResponse.code ?? payload.exitCode;
+  const exitCode = typeof rawExitCode === 'number' ? rawExitCode : undefined;
+  const stderrSignal = typeof stderr === 'string' && stderr.trim().length > 0;
+  const failed = toolResponse.is_error === true || Boolean(toolResponse.error) ||
+    (exitCode !== undefined && exitCode !== 0) ||
+    (exitCode === undefined && stderrSignal);
+  const evidence = ((stderrSignal ? stderr : stdout) || '').slice(-1000).trim();
+  return { failed, exitCode, evidence };
+}
+
+function updateRunContract(entry, payload, command, sessionId) {
+  const { failed, exitCode, evidence } = resultState(payload);
+  const observedAt = new Date().toISOString();
+  const contract = {
+    ...entry.contract,
+    status: failed ? 'fail' : 'pass',
+    lastObservedCommand: command,
+    lastObservedExitCode: exitCode ?? null,
+    evidence,
+    verifiedAt: observedAt,
+    updatedAt: observedAt,
+  };
+  const evidenceRelative = path.posix.join('evidence', `${contract.stageId}.json`);
+  contract.verificationEvidence = evidenceRelative;
+
+  atomicWriteJson(path.join(entry.runRoot, evidenceRelative), {
+    schemaVersion: 1,
+    planId: contract.planId,
+    runId: contract.runId,
+    stageId: contract.stageId,
+    sessionId: sessionId || contract.sessionId || null,
+    workerId: contract.workerId || null,
+    checkCommand: command,
+    status: failed ? 'fail' : 'pass',
+    exitCode: exitCode ?? null,
+    evidence,
+    observedAt,
+  });
+  atomicWriteJson(entry.filePath, contract);
+  return contract;
+}
+
+function resolveLegacyContract(stateRoot, command, payload) {
+  const contractsDir = path.join(stateRoot, 'contracts');
+  let files = [];
+  try { files = fs.readdirSync(contractsDir).filter(file => file.endsWith('.json')); } catch (_) { return null; }
+  const matches = [];
+  for (const file of files) {
+    const filePath = path.join(contractsDir, file);
+    let manifest;
+    try { manifest = JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch (_) { continue; }
+    if (manifest.status !== 'pending' || !manifest.checkCommand || manifest.checkCommand.trim() !== command) continue;
+    matches.push({ manifest, filePath });
+  }
+  if (matches.length !== 1) return matches.length > 1 ? { ambiguous: true } : null;
+  const { failed, evidence } = resultState(payload);
+  const match = matches[0];
+  match.manifest.status = failed ? 'fail' : 'pass';
+  match.manifest.evidence = evidence;
+  match.manifest.verifiedAt = new Date().toISOString();
+  atomicWriteJson(match.filePath, match.manifest);
+  return { legacy: true, failed, contract: match.manifest };
+}
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Bash' && payload.tool_name !== 'PowerShell') process.exit(0);
+
+    const command = ((payload.tool_input && payload.tool_input.command) || '').trim();
+    if (!command) process.exit(0);
+
+    const root = getWorkspaceRoot(payload);
+    const stateRoot = getStateRoot(root, payload);
+    const sessionId = getSessionId(payload);
+    const runMatches = listRunContracts(stateRoot).filter(({ contract }) =>
+      ['pending', 'planned', 'running'].includes(contract.status) && commandMatches(contract, command)
+    );
+
+    if (runMatches.length > 0) {
+      const resolution = chooseCorrelatedContract(runMatches, payload, sessionId);
+      if (resolution.ambiguous || !resolution.match) {
+        console.error(`[Contract Test] Ambiguous Fable check command matched ${runMatches.length} active run contract(s): ${command}`);
+        console.error('No contract was mutated. Correlate the worker/session to one run before accepting this check.');
+        process.exit(2);
+      }
+
+      const contract = updateRunContract(resolution.match, payload, command, sessionId);
+      console.log(`[Contract Test] ${contract.planId}/${contract.runId}/${contract.stageId}: ${contract.status.toUpperCase()} ${contract.checkCommand}`);
+      if (contract.status === 'fail') {
+        console.error(`Evidence: ${contract.evidence || '(no output captured)'}`);
+        console.error(`Do not build on this stage's output until it passes. Artifact: ${contract.outputPath || '(no path recorded)'}`);
+        process.exit(2);
+      }
+      process.exit(0);
+    }
+
+    // Temporary compatibility with pre-Phase-3 manifests. New orchestration
+    // must use run-scoped contracts; legacy manifests have no plan/run link.
+    const legacy = resolveLegacyContract(stateRoot, command, payload);
+    if (legacy && legacy.ambiguous) {
+      console.error(`[Contract Test] Ambiguous legacy stage contracts matched: ${command}`);
+      process.exit(2);
+    }
+    if (legacy && legacy.failed) {
+      console.error(`[Contract Test] Legacy stage "${legacy.contract.stageId}" FAILED its named check: ${legacy.contract.checkCommand}`);
+      console.error(`Evidence: ${legacy.contract.evidence || '(no output captured)'}`);
+      process.exit(2);
+    }
+    process.exit(0);
+  } catch (_) {
+    // Hook lookup/parsing remains best-effort. A resolved failed check above
+    // never passes through this path because it exits explicitly.
+    process.exit(0);
+  }
+});

package/plugins/harness-everything/hooks/scripts/depth-guard.js

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+/**
+ * Depth Guard (PreToolUse: Edit|Write)
+ * Claude Code already refuses to Edit a file that wasn't Read first in the
+ * same session - that's native behavior, not something this hook needs to
+ * re-check. The gap is Write: it happily overwrites an existing file with
+ * no prior Read at all. This hook closes that gap: blocks Write on a file
+ * that already exists on disk unless a Read of that exact path shows up
+ * earlier in this session's transcript.
+ * Fails open on any parse/lookup error - never blocks due to a bug here.
+ */
+const fs = require('fs');
+const path = require('path');
+
+let inputData = '';
+process.stdin.on('data', chunk => { inputData += chunk; });
+process.stdin.on('end', () => {
+  try {
+    const payload = JSON.parse(inputData);
+    if (payload.tool_name !== 'Write') {
+      process.exit(0);
+    }
+
+    const filePath = payload.tool_input && payload.tool_input.file_path;
+    if (!filePath || !fs.existsSync(filePath)) {
+      // New file - nothing to have read first.
+      process.exit(0);
+    }
+
+    const transcriptPath = payload.transcript_path;
+    if (!transcriptPath || !fs.existsSync(transcriptPath)) {
+      // Can't verify either way - fail open.
+      process.exit(0);
+    }
+
+    const target = path.resolve(filePath).toLowerCase();
+    const lines = fs.readFileSync(transcriptPath, 'utf8').split('\n').filter(Boolean);
+
+    const wasRead = lines.some(line => {
+      try {
+        const entry = JSON.parse(line);
+        const content = entry && entry.message && entry.message.content;
+        if (!Array.isArray(content)) return false;
+        return content.some(block => {
+          if (!block || block.type !== 'tool_use' || block.name !== 'Read') return false;
+          const readPath = block.input && block.input.file_path;
+          return readPath && path.resolve(readPath).toLowerCase() === target;
+        });
+      } catch (e) {
+        return false;
+      }
+    });
+
+    if (!wasRead) {
+      console.error(`[Depth Guard] BLOCKED: "${filePath}" already exists but hasn't been Read in this session.`);
+      console.error(`Write() overwrites the whole file - doing that blind risks destroying content you never looked at.`);
+      console.error(`Read the file first (even a quick pass), then retry the Write, or use Edit for a targeted change.`);
+      process.exit(2);
+    }
+
+    process.exit(0);
+  } catch (err) {
+    process.exit(0);
+  }
+});

package/plugins/harness-everything/hooks/scripts/lib/fable-contracts.js

@@ -0,0 +1,121 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+function readJson(filePath) {
+  try { return JSON.parse(fs.readFileSync(filePath, 'utf8')); } catch (_) { return null; }
+}
+
+function atomicWriteJson(filePath, value) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  fs.writeFileSync(tempPath, `${JSON.stringify(value, null, 2)}\n`, 'utf8');
+  fs.renameSync(tempPath, filePath);
+}
+
+function listRunContracts(stateRoot) {
+  const runsRoot = path.join(stateRoot, 'fable-runs');
+  let runDirs = [];
+  try {
+    runDirs = fs.readdirSync(runsRoot, { withFileTypes: true })
+      .filter(entry => entry.isDirectory())
+      .map(entry => path.join(runsRoot, entry.name));
+  } catch (_) {
+    return [];
+  }
+
+  const contracts = [];
+  for (const runRoot of runDirs) {
+    const contractsDir = path.join(runRoot, 'contracts');
+    let files = [];
+    try { files = fs.readdirSync(contractsDir).filter(file => file.endsWith('.json')); } catch (_) { continue; }
+    for (const file of files) {
+      const filePath = path.join(contractsDir, file);
+      const contract = readJson(filePath);
+      if (!contract || contract.schemaVersion !== 2 || !contract.stageId || !contract.runId || !contract.planId) continue;
+      contracts.push({ contract, filePath, runRoot });
+    }
+  }
+  return contracts;
+}
+
+function getWorkerId(payload) {
+  if (!payload || typeof payload !== 'object') return null;
+  const direct = payload.worker_id || payload.workerId || payload.subagent_id || payload.subagentId || payload.agent_id || payload.agentId;
+  if (typeof direct === 'string' && direct.trim()) return direct.trim();
+  for (const container of [payload.tool_input, payload.tool, payload.metadata, payload.context]) {
+    if (!container || typeof container !== 'object') continue;
+    const nested = getWorkerId(container);
+    if (nested) return nested;
+  }
+  return null;
+}
+
+function commandMatches(contract, command) {
+  return typeof contract.checkCommand === 'string' && contract.checkCommand.trim() === String(command || '').trim();
+}
+
+function chooseCorrelatedContract(matches, payload, sessionId) {
+  if (!Array.isArray(matches) || matches.length === 0) return { match: null, ambiguous: false };
+  let candidates = matches;
+  if (sessionId) {
+    candidates = candidates.filter(({ contract }) => !contract.sessionId || contract.sessionId === sessionId);
+    if (candidates.length === 0) return { match: null, ambiguous: false };
+  }
+
+  const workerId = getWorkerId(payload);
+  if (workerId) {
+    const hasBoundWorker = candidates.some(({ contract }) => Boolean(contract.workerId));
+    if (hasBoundWorker) {
+      candidates = candidates.filter(({ contract }) => !contract.workerId || contract.workerId === workerId);
+      if (candidates.length === 0) return { match: null, ambiguous: false };
+    }
+    const workerMatches = candidates.filter(({ contract }) => contract.workerId === workerId);
+    if (workerMatches.length === 1) return { match: workerMatches[0], ambiguous: false };
+    if (workerMatches.length > 1) return { match: null, ambiguous: true };
+  }
+
+  if (candidates.length === 1) return { match: candidates[0], ambiguous: false };
+  return { match: null, ambiguous: candidates.length > 1 };
+}
+
+function normalizeChangedPath(statusLine) {
+  const text = String(statusLine || '');
+  const raw = /^..\s/.test(text) ? text.slice(3).trim() : text.trim();
+  const renameTarget = raw.includes(' -> ') ? raw.split(' -> ').pop() : raw;
+  return renameTarget.replace(/\\/g, '/').replace(/^\.\//, '');
+}
+
+function pathWithinScope(filePath, scope) {
+  const file = normalizeChangedPath(filePath).replace(/\/+$/g, '');
+  const declared = String(scope || '').replace(/\\/g, '/').replace(/^\.\//, '').replace(/\/+$/g, '');
+  if (!file || !declared) return false;
+  return file === declared || file.startsWith(`${declared}/`);
+}
+
+function stagesForChangedPath(filePath, contractEntries) {
+  return (contractEntries || []).filter(({ contract }) =>
+    Array.isArray(contract.writeSet) && contract.writeSet.some(scope => pathWithinScope(filePath, scope))
+  );
+}
+
+function getActiveRunContracts(stateRoot, sessionId) {
+  return listRunContracts(stateRoot).filter(({ contract }) => {
+    if (!['pending', 'planned', 'running'].includes(contract.status)) return false;
+    return !sessionId || !contract.sessionId || contract.sessionId === sessionId;
+  });
+}
+
+module.exports = {
+  atomicWriteJson,
+  chooseCorrelatedContract,
+  commandMatches,
+  getActiveRunContracts,
+  getWorkerId,
+  listRunContracts,
+  normalizeChangedPath,
+  pathWithinScope,
+  readJson,
+  stagesForChangedPath,
+};