@enterpriseai/cli 3.19.0 → 3.19.1

package/resources/gofer/node-scripts/gofer-native-benchmark-dispatch.mjs

@@ -0,0 +1,145 @@
+/**
+ * Native dispatch for held-out benchmark cases. Each case runs through the same
+ * ledger-bound Codex executor as production tasks: reserve, lease, authorize,
+ * native authorize, local OS sandbox, scope and git checks.
+ *
+ * A benchmark cannot use the normal routing gate, because that gate needs the
+ * benchmark result these runs produce. Authority here comes from a dedicated
+ * ledger, an explicit user approval receipt, a fixed model, and a hard spend
+ * cap. The bootstrap benchmark receipt used here cannot satisfy
+ * `verifyTrustedBenchmarkEvidence`, so it never becomes routing authority.
+ */
+import { execFile } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import { cp, mkdtemp, readdir, realpath, rm } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { promisify } from 'node:util';
+import { capabilityReceiptHash } from './gofer-host-capability.mjs';
+import { createLedgerBoundCodexExecutor, startLocalCodexInvocation } from './gofer-native-adapter.mjs';
+import { createRuntimeLedger } from './gofer-runtime-ledger.mjs';
+
+const run = promisify(execFile);
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const rate = value => Number.isFinite(value) && value >= 0;
+const sha = value => createHash('sha256').update(value).digest('hex');
+const denied = code => new Error(code);
+const ISOLATION = 'git-worktree+local-os-sandbox';
+const gitEnvironment = Object.fromEntries(Object.entries(process.env)
+  .filter(([key]) => !key.startsWith('GIT_') || key.startsWith('GIT_CONFIG_')));
+
+async function git(directory, args) {
+  return run('git', ['-C', directory, '-c', 'user.name=gofer-benchmark',
+    '-c', 'user.email=benchmark@gofer.invalid', '-c', 'commit.gpgsign=false', ...args],
+  { encoding: 'utf8', env: gitEnvironment, timeout: 30000 });
+}
+
+/** List-price cost from reported token usage. Cached input is charged at its
+ * own rate only when one is given; otherwise at the full input rate. */
+export function priceUsage(usage, rateCard) {
+  if (![usage?.inputTokens, usage?.cachedInputTokens, usage?.outputTokens]
+    .every(value => Number.isInteger(value) && value >= 0) ||
+      usage.cachedInputTokens > usage.inputTokens ||
+      !rate(rateCard?.inputUsdPerMillion) || !rate(rateCard?.outputUsdPerMillion) ||
+      (rateCard.cachedInputUsdPerMillion !== undefined && !rate(rateCard.cachedInputUsdPerMillion))) {
+    throw denied('BENCHMARK_USAGE_REQUIRED');
+  }
+  const cachedRate = rateCard.cachedInputUsdPerMillion ?? rateCard.inputUsdPerMillion;
+  const uncached = usage.inputTokens - usage.cachedInputTokens;
+  return (uncached * rateCard.inputUsdPerMillion + usage.cachedInputTokens * cachedRate +
+    usage.outputTokens * rateCard.outputUsdPerMillion) / 1_000_000;
+}
+
+/** One cap shared by every dispatcher of a benchmark, workers and reviewers. */
+export function createSpendCap(maxTotalCostUsd) {
+  if (!(maxTotalCostUsd > 0)) throw denied('NATIVE_BENCHMARK_DISPATCH_REQUIRED');
+  return { spentUsd: 0, maxTotalCostUsd };
+}
+
+/**
+ * `command` must be the pinned, absolute native executable, never a PATH
+ * lookup. `maxRunCostUsd` bounds one run; `maxTotalCostUsd` bounds the whole
+ * benchmark and is checked before every launch. A run that cannot be metered,
+ * or that times out, is charged at `maxRunCostUsd` so the cap cannot be beaten.
+ */
+export async function createNativeBenchmarkDispatch({ ledgerPath, capabilityReceipt,
+  capabilityPublicKey, requiredCapabilities, modelId, approvalReceipt, command, rateCard,
+  maxRunCostUsd, spend, taskPrefix = 'benchmark', scratchRoot = os.tmpdir(), timeoutMs = 600_000,
+  start = startLocalCodexInvocation, createLedger = createRuntimeLedger } = {}) {
+  if (!text(ledgerPath) || !path.isAbsolute(ledgerPath) || !text(modelId) ||
+      !text(approvalReceipt) || !text(command) || !path.isAbsolute(command) ||
+      capabilityReceipt?.host !== 'codex' || capabilityReceipt.isolationClass !== ISOLATION ||
+      !Array.isArray(capabilityReceipt.models) || !capabilityReceipt.models.some(model => model?.id === modelId) ||
+      !capabilityPublicKey || !rate(rateCard?.inputUsdPerMillion) ||
+      !rate(rateCard?.outputUsdPerMillion) || !(maxRunCostUsd > 0) ||
+      !(spend?.maxTotalCostUsd >= maxRunCostUsd) || !/^[a-z]{3,16}$/.test(taskPrefix) ||
+      !text(scratchRoot) || !path.isAbsolute(scratchRoot) || !Number.isFinite(spend.spentUsd) || !Number.isInteger(timeoutMs) || timeoutMs < 1 ||
+      typeof start !== 'function') throw denied('NATIVE_BENCHMARK_DISPATCH_REQUIRED');
+  const ledger = await createLedger({ ledgerPath });
+  const receiptHash = capabilityReceiptHash(capabilityReceipt);
+
+  return async function dispatchCase({ caseId, run: runNumber, prompt, allowedWriteScope, worktree }) {
+    if (!text(caseId) || !Number.isInteger(runNumber) || !text(prompt) || !text(worktree) ||
+        !path.isAbsolute(worktree) || !Array.isArray(allowedWriteScope) ||
+        !allowedWriteScope.length) throw denied('NATIVE_BENCHMARK_DISPATCH_REQUIRED');
+    // Checked before any process starts, so the cap cannot be exceeded.
+    if (spend.spentUsd + maxRunCostUsd > spend.maxTotalCostUsd) throw denied('BENCHMARK_SPEND_CAP_REACHED');
+
+    // The qualified sandbox needs a linked worktree whose shared git store lies
+    // outside the workspace. Build a scratch base repository from the prepared
+    // files, then check the case out into `worktree` as a linked worktree.
+    const base = await realpath(await mkdtemp(path.join(scratchRoot, 'gofer-benchmark-base-')));
+    try {
+      await cp(worktree, base, { recursive: true });
+      await git(base, ['init', '-q', '-b', 'main']);
+      await git(base, ['add', '-A']);
+      await git(base, ['commit', '-q', '-m', 'baseline']);
+      const head = (await git(base, ['rev-parse', 'HEAD'])).stdout.trim();
+      for (const name of await readdir(worktree)) {
+        await rm(path.join(worktree, name), { recursive: true, force: true });
+      }
+      await git(base, ['worktree', 'add', '-q', '--detach', worktree, head]);
+
+      const worktreeReceipt = sha(JSON.stringify({ worktree, head }));
+      const taskId = `${taskPrefix}:${caseId}:${runNumber}`;
+      const task = { taskId, revision: head, attempt: 1, dependencies: [],
+        worktreeReceipt, allowedEditScope: [...allowedWriteScope],
+        requiredChecks: ['protected-verify'], capabilityReceiptHash: receiptHash,
+        approvalReceipt, selectedModel: modelId,
+        benchmarkReceipt: `bootstrap-${taskPrefix}:${sha(approvalReceipt).slice(0, 24)}` };
+      const reserved = await ledger.reserve(task);
+      const leased = reserved?.allowed === true ? await ledger.lease(task) : null;
+      if (leased?.allowed !== true) throw denied('NATIVE_BENCHMARK_LEDGER_DENIED');
+      const authority = await ledger.authorize({ ...task, leaseId: leased.leaseId,
+        budgetReservation: leased.budgetReservation });
+      if (authority?.allowed !== true) throw denied('NATIVE_BENCHMARK_LEDGER_DENIED');
+
+      let launched = false;
+      const executor = createLedgerBoundCodexExecutor({ isolatedWorkspace: worktree,
+        worktreeReceipt, expectedHead: head, capabilityReceipt, capabilityPublicKey,
+        requiredCapabilities, assertLedger: request => ledger.authorizeNative(request),
+        promptForRequest: () => prompt,
+        start: request => { launched = true; return start({ ...request, command }); } });
+      const startedAt = Date.now();
+      let result;
+      try {
+        result = await executor.execute({ revision: head, taskId, attempt: 1, dependencies: [],
+          ledgerAuthorityReceipt: authority.receipt, selectedModel: modelId,
+          allowedEditScope: [...allowedWriteScope], worktreeReceipt, leaseId: leased.leaseId,
+          budgetReservation: leased.budgetReservation, approvalReceipt, usageReporting: true,
+          signal: AbortSignal.timeout(timeoutMs) });
+      } catch (error) {
+        // An unmetered or interrupted run is charged in full.
+        if (launched) spend.spentUsd += maxRunCostUsd;
+        throw error;
+      }
+      let costUsd;
+      try { costUsd = priceUsage(result.usage, rateCard); }
+      catch (error) { spend.spentUsd += maxRunCostUsd; throw error; }
+      spend.spentUsd += costUsd;
+      if (costUsd > maxRunCostUsd) throw denied('BENCHMARK_RUN_COST_EXCEEDED');
+      return { modelId, costUsd, durationMs: Date.now() - startedAt, isolation: result.isolation,
+        receipt: result.receipt };
+    } finally { await rm(base, { recursive: true, force: true }); }
+  };
+}

package/resources/gofer/node-scripts/gofer-native-runtime.mjs

@@ -0,0 +1,169 @@
+/**
+ * Production composition root for verified local native execution. It does
+ * not manufacture authority: callers must provide one durable ledger that
+ * governs both graph dispatch and the host launch.
+ */
+import path from 'node:path';
+import { lstat, realpath } from 'node:fs/promises';
+import { createVerifiedWorktree, inspectVerifiedWorktree, disposeVerifiedWorktree, createLedgerBoundCodexExecutor, startLocalCodexInvocation,
+  inspectNativeWorkerEvidence, createNativeCancellationVerifier, createNativeBenchmarkCaptureVerifier } from './gofer-native-adapter.mjs';
+import { createRuntimeLedger } from './gofer-runtime-ledger.mjs';
+import { captureConfiguredHeldOutResultSnapshot } from './gofer-heldout-snapshot.mjs';
+import { reconcileCancelledExecution } from './gofer-execution-recovery.mjs';
+import { runVerifiedGraph } from './gofer-verified-execution.mjs';
+import { inspectEaiLocalIsolation } from './gofer-local-isolation.mjs';
+import { verifyCapabilityReceipt } from './gofer-host-capability.mjs';
+import { resolveTrustedEvaluatorPublicKey } from './gofer-trusted-evaluator.mjs';
+import { verifyTrustedBenchmarkEvidence } from './gofer-trusted-benchmark.mjs';
+
+const text = value => typeof value === 'string' && value.trim().length > 0;
+const inside = (parent, child) => {
+  const relative = path.relative(parent, child);
+  return relative === '' || (relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative));
+};
+
+export async function createVerifiedNativeRuntime({ workspaceRoot, host = 'codex',
+  localIsolation = inspectEaiLocalIsolation,
+  capabilityReceipt, requiredCapabilities, ledger,
+  promptForRequest, adapter, baseRef } = {}) {
+  if (!text(workspaceRoot) || host !== 'codex' || typeof localIsolation !== 'function' ||
+      capabilityReceipt?.host !== host ||
+      typeof ledger?.authorize !== 'function' || typeof ledger?.authorizeCommit !== 'function' ||
+      typeof ledger?.authorizeNative !== 'function' || typeof promptForRequest !== 'function' ||
+      typeof adapter?.bindWorkspace !== 'function') {
+    throw new Error('VERIFIED_NATIVE_RUNTIME_CONFIGURATION_REQUIRED');
+  }
+  const capabilityPublicKey = await resolveTrustedEvaluatorPublicKey(capabilityReceipt, { workspaceRoot });
+  if (!verifyCapabilityReceipt(capabilityReceipt, { publicKey: capabilityPublicKey,
+    host, requiredCapabilities })) throw new Error('TRUSTED_CAPABILITY_RECEIPT_REQUIRED');
+  const isolation = await createVerifiedWorktree({ workspaceRoot, host, localIsolation, baseRef });
+  let boundAdapter;
+  try {
+    boundAdapter = await adapter.bindWorkspace(Object.freeze({ workspaceRoot: isolation.isolatedWorkspace,
+      worktreeReceipt: isolation.receipt }));
+    if (boundAdapter?.workspaceRoot !== isolation.isolatedWorkspace ||
+        ['reserve', 'lease', 'inputRevision', 'check', 'verified'].some(method =>
+          typeof boundAdapter?.[method] !== 'function')) throw new Error('NATIVE_ADAPTER_WORKSPACE_BINDING_REQUIRED');
+  } catch (error) {
+    await disposeVerifiedWorktree({ workspaceRoot: isolation.workspace,
+      isolatedWorkspace: isolation.isolatedWorkspace, revision: isolation.revision,
+      receipt: isolation.receipt }).catch(() => {});
+    throw error;
+  }
+  let lifecycle = 'idle';
+  return Object.freeze({
+    isolation,
+    async dispose() {
+      if (lifecycle === 'disposed') return;
+      if (lifecycle !== 'idle' && lifecycle !== 'verified') {
+        throw new Error('NATIVE_RUNTIME_REQUIRES_RECOVERY_BEFORE_DISPOSAL');
+      }
+      const prior = lifecycle;
+      lifecycle = 'disposing';
+      try {
+        await disposeVerifiedWorktree({ workspaceRoot: isolation.workspace,
+          isolatedWorkspace: isolation.isolatedWorkspace, revision: isolation.revision,
+          receipt: isolation.receipt });
+        lifecycle = 'disposed';
+      } catch (error) {
+        lifecycle = prior;
+        throw error;
+      }
+    },
+    async run({ featureDir, checks, benchmarkEvidence, benchmarkAttestation, advisoryConstraints,
+      approvalReceipt, maxCalls, maxConcurrent, deadlineMs, signal, recovery } = {}) {
+      if (lifecycle !== 'idle') throw new Error('NATIVE_RUNTIME_NOT_AVAILABLE');
+      lifecycle = 'running';
+      let graphStarted = false;
+      try {
+        if (!text(featureDir)) throw new Error('NATIVE_EVIDENCE_DIRECTORY_REQUIRED');
+        const controllerRoot = await realpath(featureDir);
+        if (!inside(isolation.workspace, controllerRoot) || inside(isolation.isolatedWorkspace, controllerRoot)) {
+          throw new Error('NATIVE_CONTROL_PLANE_OUTSIDE_SOURCE_WORKSPACE');
+        }
+        const worktree = await inspectVerifiedWorktree({ workspaceRoot: isolation.workspace,
+          isolatedWorkspace: isolation.isolatedWorkspace, revision: isolation.revision,
+          receipt: isolation.receipt, requireClean: true });
+        if (!worktree.valid) throw new Error('NATIVE_WORKTREE_NOT_CLEAN');
+        // The trusted journal stays outside the worker sandbox. The bound
+        // adapter performs input reads, checks, and commits in the task worktree.
+        const evidenceDirectory = path.join(controllerRoot, '.native-worker-evidence');
+        const executor = createLedgerBoundCodexExecutor({ isolatedWorkspace: isolation.isolatedWorkspace,
+          worktreeReceipt: isolation.receipt, expectedHead: isolation.revision,
+          capabilityReceipt, capabilityPublicKey, requiredCapabilities,
+          assertLedger: request => ledger.authorizeNative(request), promptForRequest,
+          start: request => startLocalCodexInvocation({ ...request,
+            command: isolation.nativeExecutable, evidenceDirectory }) });
+        const trustedAdapter = Object.freeze({ ...boundAdapter, worktreeReceipt: isolation.receipt,
+          execute: executor.execute });
+        const trustedRecovery = recovery ? { ...recovery,
+          inspectWorkers: request => inspectNativeWorkerEvidence({ ...request, evidenceDirectory }) } : undefined;
+        graphStarted = true;
+        const verifyBenchmark = request => verifyTrustedBenchmarkEvidence({ ...request,
+          attestation: benchmarkAttestation, capabilityKeyId: capabilityReceipt.provenance.keyId,
+          capabilityPublicKey,
+          workspaceRoot: isolation.workspace });
+        const result = await runVerifiedGraph({ featureDir: controllerRoot, workspaceRoot: isolation.isolatedWorkspace,
+          checks, adapter: trustedAdapter,
+          ledger, capabilityReceipt, capabilityPublicKey, requiredCapabilities, benchmarkEvidence, verifyBenchmark,
+          advisoryConstraints, approvalReceipt, maxCalls, maxConcurrent, deadlineMs, signal, recovery: trustedRecovery });
+        lifecycle = result.status === 'verified' && result.adapterCallsSettled ? 'verified' : 'recovery-required';
+        return result;
+      } catch (error) {
+        lifecycle = graphStarted ? 'recovery-required' : 'idle';
+        throw error;
+      }
+    },
+  });
+}
+
+/** Reopen the dispatch ledger with native cancellation proof after a controller restart. */
+export async function reconcileVerifiedNativeCancellation({ featureDir, ledgerPath, workspaceRoot,
+  abandonedWorkspace, replacementWorkspace, worktreeRevision, replacementWorktreeReceipt,
+  inputRevision, inspectInputRevision, verifyReceipt, timeoutMs } = {}) {
+  if (![featureDir, ledgerPath, workspaceRoot, abandonedWorkspace, replacementWorkspace,
+    worktreeRevision, replacementWorktreeReceipt, inputRevision].every(text) ||
+    !path.isAbsolute(ledgerPath) || typeof inspectInputRevision !== 'function' ||
+    typeof verifyReceipt !== 'function') throw new Error('NATIVE_RECOVERY_CONFIGURATION_REQUIRED');
+  const evidenceDirectory = path.join(featureDir, '.native-worker-evidence');
+  const verifyCancellation = createNativeCancellationVerifier({ workspaceRoot,
+    abandonedWorkspace, replacementWorkspace, worktreeRevision,
+    evidenceDirectory, inspectInputRevision });
+  const ledger = await createRuntimeLedger({ ledgerPath, verifyCancellation });
+  return reconcileCancelledExecution({ featureDir, workspaceRoot, abandonedWorkspace,
+    replacementWorkspace, worktreeRevision, replacementWorktreeReceipt, inputRevision,
+    ledger, verifyReceipt, timeoutMs,
+    inspectWorkers: request => inspectNativeWorkerEvidence({ ...request, evidenceDirectory }) });
+}
+
+/** Reopen the dispatch ledger from the controller's source-side feature root.
+ * Capture stays unavailable until that same ledger proves all native runs and
+ * the controller-owned process evidence proves that every worker has stopped. */
+export async function openVerifiedNativeBenchmarkCapture({ featureDir, ledgerPath, workspaceRoot } = {}) {
+  if (![featureDir, ledgerPath, workspaceRoot].every(text) ||
+      ![featureDir, ledgerPath, workspaceRoot].every(path.isAbsolute)) {
+    throw new Error('NATIVE_BENCHMARK_CAPTURE_CONFIGURATION_REQUIRED');
+  }
+  const [workspace, controllerRoot, ledgerParent] = await Promise.all([
+    realpath(workspaceRoot), realpath(featureDir), realpath(path.dirname(ledgerPath)),
+  ]);
+  if (!inside(workspace, controllerRoot) || controllerRoot === workspace ||
+      !inside(controllerRoot, ledgerParent)) {
+    throw new Error('NATIVE_BENCHMARK_CAPTURE_CONTROL_PLANE_REQUIRED');
+  }
+  const ledgerFile = path.join(ledgerParent, path.basename(ledgerPath));
+  const info = await lstat(ledgerFile);
+  if (!info.isFile() || info.nlink !== 1 ||
+      (typeof process.getuid === 'function' && info.uid !== process.getuid()) ||
+      (info.mode & 0o077) !== 0) {
+    throw new Error('NATIVE_BENCHMARK_CAPTURE_LEDGER_REQUIRED');
+  }
+  const evidenceDirectory = path.join(controllerRoot, '.native-worker-evidence');
+  const ledger = await createRuntimeLedger({ ledgerPath: ledgerFile,
+    verifyBenchmarkCapture: createNativeBenchmarkCaptureVerifier({ evidenceDirectory }) });
+  return Object.freeze({
+    authorizeCapture: request => ledger.authorizeBenchmarkCapture(request),
+    capture: captureAuthorization => captureConfiguredHeldOutResultSnapshot({ workspaceRoot: workspace,
+      ledger, captureAuthorization }),
+  });
+}

package/resources/gofer/node-scripts/gofer-pre-edit-check.mjs

@@ -0,0 +1,204 @@
+#!/usr/bin/env node
+
+import { constants } from 'node:fs';
+import { lstat, open, realpath } from 'node:fs/promises';
+import path from 'node:path';
+import process from 'node:process';
+import { pathToFileURL } from 'node:url';
+import { reviewPriority } from './gofer-priority-check.mjs';
+import { runSemanticReview } from './gofer-semantic-drift.mjs';
+
+const MAX_DOCUMENT_BYTES = 4 * 1024 * 1024;
+const MAX_CONTEXT_FILE_BYTES = 16 * 1024;
+const NO_FOLLOW = process.platform === 'win32' ? 0 : (constants.O_NOFOLLOW ?? 0);
+const PLACEHOLDER_MARKERS = [
+  '[FEATURE NAME]',
+  '[###-feature-name]',
+  '[specific capability',
+  '[domain-specific',
+  '[REMOVE IF UNUSED]',
+  'ACTION REQUIRED',
+  'NEEDS CLARIFICATION',
+];
+
+function isInside(parent, target) {
+  const relative = path.relative(parent, target);
+  return relative !== '..' && !relative.startsWith(`..${path.sep}`) && !path.isAbsolute(relative);
+}
+
+async function assertNoSymlinkPath(root, target) {
+  const relative = path.relative(root, target);
+  if (!isInside(root, target)) throw new Error('Feature or context path must remain inside its workspace.');
+  let current = root;
+  for (const component of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, component);
+    const info = await lstat(current).catch((error) => {
+      if (error?.code === 'ENOENT') return null;
+      throw error;
+    });
+    if (info?.isSymbolicLink()) throw new Error('Feature and context paths must not pass through symbolic links.');
+  }
+}
+
+function sameFileIdentity(left, right) {
+  return left.dev !== undefined && left.ino !== undefined &&
+    right.dev !== undefined && right.ino !== undefined &&
+    left.dev === right.dev && left.ino === right.ino;
+}
+
+async function safeFile(root, target, limit = MAX_DOCUMENT_BYTES, openFile = open) {
+  await assertNoSymlinkPath(root, target);
+  const handle = await openFile(target, constants.O_RDONLY | NO_FOLLOW);
+  try {
+    const opened = await handle.stat();
+    if (!opened.isFile() || opened.size > limit) {
+      throw new Error('A required feature file is missing, not regular, or too large.');
+    }
+    // Recheck the resolved path after opening, then compare it with the open
+    // file identity. Reads come from the validated handle, not the path, so a
+    // swap between lstat and open cannot redirect content outside the workspace.
+    await assertNoSymlinkPath(root, target);
+    const current = await lstat(target);
+    if (current.isSymbolicLink() || !sameFileIdentity(opened, current)) {
+      throw new Error('A required feature file changed while it was being opened.');
+    }
+    return await handle.readFile({ encoding: 'utf8' });
+  } finally {
+    await handle.close();
+  }
+}
+
+function hasTemplateMarker(content) {
+  return PLACEHOLDER_MARKERS.some((marker) => content.includes(marker));
+}
+
+function parseArgs(argv) {
+  const options = { workspace: process.cwd(), featureDir: '', task: '', changedFiles: [], jevChatReadiness: false, chatContextFile: '' };
+  for (let index = 0; index < argv.length; index += 1) {
+    const flag = argv[index];
+    if (flag === '--workspace') options.workspace = argv[++index] || '';
+    else if (flag === '--feature-dir') options.featureDir = argv[++index] || '';
+    else if (flag === '--task') options.task = argv[++index] || '';
+    else if (flag === '--changed-file') options.changedFiles.push(argv[++index] || '');
+    else if (flag === '--jev-chat-readiness') options.jevChatReadiness = true;
+    else if (flag === '--chat-context-file') options.chatContextFile = argv[++index] || '';
+    else throw new Error(`Unknown argument: ${flag}`);
+  }
+  if (!options.workspace || !options.featureDir || !options.task || !options.changedFiles.length) {
+    throw new Error('--workspace, --feature-dir, --task, and at least one --changed-file are required.');
+  }
+  if (options.jevChatReadiness !== Boolean(options.chatContextFile)) {
+    throw new Error('--jev-chat-readiness requires --chat-context-file, and the context file is only valid with that option.');
+  }
+  return options;
+}
+
+export async function checkPreEdit(options, { semanticReview = runSemanticReview, openFile = open } = {}) {
+  const workspace = await realpath(path.resolve(options.workspace));
+  const featureDir = path.resolve(workspace, options.featureDir);
+  await assertNoSymlinkPath(workspace, featureDir);
+  const featureInfo = await lstat(featureDir).catch(() => null);
+  if (!featureInfo?.isDirectory()) return { status: 'blocked', findings: ['FEATURE_DIRECTORY_MISSING'] };
+
+  const findings = [];
+  const contents = {};
+  for (const file of ['goal-ledger.json', 'spec.md', 'plan.md', 'tasks.md']) {
+    try {
+      contents[file] = await safeFile(workspace, path.join(featureDir, file), MAX_DOCUMENT_BYTES, openFile);
+      if (!contents[file].trim()) findings.push(`EMPTY_FILE:${file}`);
+      else if (hasTemplateMarker(contents[file])) findings.push(`TEMPLATE_FILE:${file}`);
+    } catch (error) {
+      findings.push(error?.code === 'ENOENT' ? `MISSING_FILE:${file}` : `INVALID_FILE:${file}`);
+    }
+  }
+  try {
+    const ledger = JSON.parse(contents['goal-ledger.json'] || 'null');
+    if (!Array.isArray(ledger?.goals) || ledger.goals.length === 0 || !ledger.goals.some((goal) => typeof goal.goal === 'string' && goal.goal.trim())) {
+      findings.push('GOAL_LEDGER_HAS_NO_GOAL');
+    }
+  } catch { findings.push('GOAL_LEDGER_INVALID'); }
+
+  if (findings.length) return { status: 'blocked', findings, task: options.task };
+
+  const priority = await reviewPriority(featureDir, {
+    task: options.task,
+    changedFiles: options.changedFiles,
+    workspaceRoot: workspace,
+  });
+  if (priority.status !== 'pass') {
+    return { status: 'blocked', findings: priority.findings, task: options.task, nextTask: priority.nextTask };
+  }
+
+  if (!options.jevChatReadiness) {
+    return { status: 'ready', findings: [], task: options.task, jev: { selected: false } };
+  }
+
+  const contextFile = options.chatContextFile;
+  if (path.isAbsolute(contextFile) || contextFile.split(/[\\/]/).some((part) => part === '..' || part === '.')) {
+    return { status: 'blocked', findings: ['CHAT_CONTEXT_PATH_INVALID'], task: options.task };
+  }
+  const contextPath = path.resolve(featureDir, contextFile);
+  let contextInfo;
+  try {
+    await assertNoSymlinkPath(featureDir, contextPath);
+    contextInfo = await lstat(contextPath);
+  } catch {
+    return { status: 'blocked', findings: ['CHAT_CONTEXT_FILE_MISSING_OR_INVALID'], task: options.task };
+  }
+  if (!contextInfo.isFile()) return { status: 'blocked', findings: ['CHAT_CONTEXT_FILE_MISSING_OR_INVALID'], task: options.task };
+  if (contextInfo.size > MAX_CONTEXT_FILE_BYTES) {
+    return {
+      status: 'blocked',
+      findings: ['CHAT_CONTEXT_TOO_LARGE'],
+      task: options.task,
+      chatContext: { actualBytes: contextInfo.size, maximumBytes: MAX_CONTEXT_FILE_BYTES },
+    };
+  }
+  let chatContext;
+  try {
+    chatContext = await safeFile(featureDir, contextPath, MAX_CONTEXT_FILE_BYTES, openFile);
+  } catch {
+    return { status: 'blocked', findings: ['CHAT_CONTEXT_FILE_MISSING_OR_INVALID'], task: options.task };
+  }
+  if (!chatContext.trim()) return { status: 'blocked', findings: ['CHAT_CONTEXT_EMPTY'], task: options.task };
+
+  let jev;
+  try {
+    jev = await semanticReview({
+      workspace,
+      featureDir,
+      event: 'chat_readiness',
+      chatContext,
+      onDemand: true,
+    });
+  } catch {
+    return { status: 'blocked', findings: ['JEV_CHAT_READINESS_UNAVAILABLE'], task: options.task, jev: { selected: true, status: 'unavailable' } };
+  }
+  const safeReason = typeof jev.reason === 'string' && /^[a-z0-9_]{1,80}$/.test(jev.reason) ? jev.reason : undefined;
+  const jevSummary = {
+    selected: true,
+    status: jev.status,
+    ...(Number.isFinite(jev.confidence) ? { confidence: jev.confidence } : {}),
+    ...(safeReason ? { reason: safeReason } : {}),
+  };
+  return jev.status === 'aligned'
+    ? { status: 'ready', findings: [], task: options.task, jev: jevSummary }
+    : { status: 'blocked', findings: [`JEV_CHAT_READINESS_${String(jev.status || 'unavailable').toUpperCase()}`], task: options.task, jev: jevSummary };
+}
+
+async function main() {
+  if (process.argv.includes('--help')) {
+    console.log('Usage: gofer-pre-edit-check.mjs --workspace <repo> --feature-dir <path> --task T001 --changed-file <path> [--changed-file <path> [--jev-chat-readiness --chat-context-file <feature-relative-path>]]');
+    return;
+  }
+  const result = await checkPreEdit(parseArgs(process.argv.slice(2)));
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status !== 'ready') process.exitCode = 1;
+}
+
+if (process.argv[1] && import.meta.url === pathToFileURL(path.resolve(process.argv[1])).href) {
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });
+}