codexteer 0.14.1

package/src/desktop.mjs

@@ -0,0 +1,207 @@
+import { existsSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { fileURLToPath } from "node:url";
+import { threadComposerDeepLink, threadDeepLink } from "./thread-id.mjs";
+import { readDesktopSettings } from "./settings.mjs";
+
+const APP_PATH = "/Applications/ChatGPT.app";
+const APP_BUNDLE_ID = "com.openai.codex";
+const OPEN = "/usr/bin/open";
+const OSASCRIPT = "/usr/bin/osascript";
+const SEND_SCRIPT = fileURLToPath(new URL("../scripts/send.applescript", import.meta.url));
+const INSPECT_SCRIPT = fileURLToPath(new URL("../scripts/inspect.applescript", import.meta.url));
+const ACCESSIBILITY_SCRIPT = fileURLToPath(new URL("../scripts/accessibility.applescript", import.meta.url));
+
+function run(command, args, options = {}) {
+  return spawnSync(command, args, {
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+    ...options,
+  });
+}
+
+export function desktopDoctor() {
+  const desktopSettings = readDesktopSettings();
+  const checks = {
+    macos: process.platform === "darwin",
+    chatgpt_app: existsSync(APP_PATH),
+    open_command: existsSync(OPEN),
+    osascript_command: existsSync(OSASCRIPT),
+    send_script: existsSync(SEND_SCRIPT),
+    inspect_script: existsSync(INSPECT_SCRIPT),
+    accessibility_script: existsSync(ACCESSIBILITY_SCRIPT),
+    accessibility: false,
+  };
+
+  if (checks.macos && checks.osascript_command) {
+    const result = run(OSASCRIPT, [
+      "-e",
+      'tell application "System Events" to return UI elements enabled',
+    ], { timeout: 3000 });
+    checks.accessibility = result.status === 0 && result.stdout.trim() === "true";
+  }
+
+  return {
+    ready: Object.values(checks).every(Boolean),
+    backend: "desktop-ui",
+    desktop_settings: desktopSettings,
+    checks,
+    remediation: checks.accessibility
+      ? null
+      : "Enable Accessibility for your terminal app in System Settings > Privacy & Security > Accessibility.",
+  };
+}
+
+export function buildOpenArgs(deepLink, { background = false } = {}) {
+  return [...(background ? ["-g"] : []), "-b", APP_BUNDLE_ID, deepLink];
+}
+
+export function openDesktopThread(threadId, { focusComposer = false, prompt, background = false } = {}) {
+  const deepLink = focusComposer ? threadComposerDeepLink(threadId, prompt) : threadDeepLink(threadId);
+  const result = run(OPEN, buildOpenArgs(deepLink, { background }));
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || `Failed to open ${deepLink}`);
+  }
+  return {
+    thread_id: threadId,
+    deep_link: threadDeepLink(threadId),
+    backend: "desktop-ui",
+    focus_composer: focusComposer,
+    background,
+  };
+}
+
+function validateWaitMs(waitMs) {
+  if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000) {
+    throw new Error("--wait-ms must be an integer between 0 and 30000.");
+  }
+}
+
+function requireReadyDesktop() {
+  const doctor = desktopDoctor();
+  if (doctor.ready) return;
+  const missing = Object.entries(doctor.checks)
+    .filter(([, ok]) => !ok)
+    .map(([name]) => name)
+    .join(", ");
+  throw new Error(`Desktop backend is not ready: ${missing}. ${doctor.remediation ?? ""}`.trim());
+}
+
+function frontmostProcessId() {
+  const result = run(OSASCRIPT, [
+    "-e",
+    'tell application "System Events" to return unix id of first application process whose frontmost is true',
+  ], { timeout: 3000 });
+  if (result.error) throw result.error;
+  const processId = Number.parseInt(result.stdout.trim(), 10);
+  if (result.status !== 0 || !Number.isInteger(processId) || processId < 1) {
+    throw new Error(result.stderr.trim() || "Could not identify the previously focused application.");
+  }
+  return processId;
+}
+
+function enableDesktopAccessibility() {
+  const result = run(OSASCRIPT, [ACCESSIBILITY_SCRIPT, "enable"], { timeout: 5000 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "Could not enable the Codex accessibility tree.");
+  }
+  return result.stdout.trim() || "unchanged";
+}
+
+function restoreDesktopAccessibility(mode) {
+  if (mode !== "manual" && mode !== "enhanced") return;
+  const result = run(OSASCRIPT, [ACCESSIBILITY_SCRIPT, "restore", mode], { timeout: 5000 });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "Could not restore the Codex accessibility state.");
+  }
+}
+
+export function inspectDesktopUi(threadId, { waitMs = 1500 } = {}) {
+  validateWaitMs(waitMs);
+  requireReadyDesktop();
+  const accessibilityMode = enableDesktopAccessibility();
+  let result;
+  try {
+    openDesktopThread(threadId, { focusComposer: true });
+    result = run(OSASCRIPT, [INSPECT_SCRIPT, String(waitMs)], {
+      timeout: waitMs + 15000,
+    });
+  } finally {
+    restoreDesktopAccessibility(accessibilityMode);
+  }
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "Could not inspect the Codex Desktop UI.");
+  }
+  return {
+    thread_id: threadId,
+    backend: "desktop-ui",
+    accessibility_mode: accessibilityMode,
+    diagnostic: result.stdout.trim(),
+  };
+}
+
+function newTurnShortcut(message, composerEnterBehavior) {
+  if (composerEnterBehavior === "cmdAlways") return "command";
+  if (composerEnterBehavior === "cmdIfMultiline" && message.includes("\n")) return "command";
+  return "plain";
+}
+
+export function buildSendPlan(
+  threadId,
+  message,
+  waitMs = 1500,
+  desktopSettings = readDesktopSettings(),
+  { newTurn = false, keepFocus = false } = {},
+) {
+  const submitShortcut = newTurn
+    ? newTurnShortcut(message, desktopSettings.composer_enter_behavior)
+    : desktopSettings.submit_shortcut;
+  return {
+    thread_id: threadId,
+    deep_link: threadDeepLink(threadId),
+    backend: "desktop-ui",
+    delivery_strategy: "deep-link-prefill",
+    delivery_action: newTurn ? "new-turn" : "steer",
+    focus_policy: keepFocus ? "keep-codex-focused" : "restore-previous-app",
+    wait_ms: waitMs,
+    follow_up_mode: desktopSettings.follow_up_mode,
+    composer_enter_behavior: desktopSettings.composer_enter_behavior,
+    submit_shortcut: submitShortcut,
+    message_characters: [...message].length,
+  };
+}
+
+export function sendDesktopMessage(
+  threadId,
+  message,
+  { dryRun = false, waitMs = 1500, newTurn = false, keepFocus = false } = {},
+) {
+  if (message.trim() === "") throw new Error("Message must not be empty.");
+  validateWaitMs(waitMs);
+
+  const desktopSettings = readDesktopSettings();
+  const plan = buildSendPlan(threadId, message, waitMs, desktopSettings, { newTurn, keepFocus });
+  if (dryRun) return { ...plan, dry_run: true, sent: false };
+
+  requireReadyDesktop();
+  const previousProcessId = keepFocus ? 0 : frontmostProcessId();
+  openDesktopThread(threadId, { focusComposer: true, prompt: message, background: true });
+  const result = run(OSASCRIPT, [
+    SEND_SCRIPT,
+    String(waitMs),
+    plan.submit_shortcut,
+    keepFocus ? "keep" : "restore",
+    String(previousProcessId),
+  ], {
+    timeout: waitMs + 15000,
+  });
+  if (result.error) throw result.error;
+  if (result.status !== 0) {
+    throw new Error(result.stderr.trim() || "Codex Desktop did not accept the steering message.");
+  }
+
+  return { ...plan, dry_run: false, sent: null, delivery_status: "submitted_unverified" };
+}

package/src/directive.mjs

@@ -0,0 +1,39 @@
+import { collectEvidence, verifyEvidence } from "./evidence.mjs";
+import { decodeCursor, threadSnapshot, fetchThread } from "./observe.mjs";
+import { getCheckpoint, verifyCheckpoint } from "./checkpoint.mjs";
+import { verifyPagedFreshness } from "./paged-read.mjs";
+
+export const kindLabels = { decision: "ユーザー決定の伝達", review: "レビュー", hypothesis: "仮説（未確定）", suggestion: "任意提案" };
+
+export async function prepareDirective(threadId, body, options, id, storage = {}) {
+  const { source, kind, evidence = [], basedOn, supersedes, retracts, expiresAt, checkpoint } = options;
+  if (!source && !kind && !evidence.length && !basedOn && !supersedes && !retracts && !expiresAt && !checkpoint) return { wireText: body, metadata: null };
+  if (checkpoint) await getCheckpoint(threadId, checkpoint, storage);
+  if (supersedes && retracts) throw new Error("Use either supersedes or retracts, not both.");
+  if (expiresAt && (!/(Z|[+-]\d{2}:\d{2})$/.test(expiresAt) || !Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= Date.now())) throw new Error("--expires-at must be a future ISO timestamp with timezone.");
+  if (kind && !Object.hasOwn(kindLabels, kind)) throw new Error("--kind must be decision, review, hypothesis, or suggestion.");
+  if (source != null && (!source.trim() || source.length > 80 || /[\r\n\x00-\x1f]/.test(source))) throw new Error("--source must be a non-empty single line (up to 80 characters).");
+  const observed = basedOn ? decodeCursor(basedOn, threadId) : null;
+  const refs = await collectEvidence(evidence);
+  const metadata = { source: source ?? "external", kind: kind ?? "review", evidence: refs, based_on: basedOn ?? null, supersedes: supersedes ?? null, retracts: retracts ?? null, expires_at: expiresAt ?? null, checkpoint_id: checkpoint ?? null };
+  const lines = [`[codexteer ${id}]`, `送信者: ${metadata.source}`, `種類: ${kindLabels[metadata.kind]}`];
+  for (const ref of refs) lines.push(`根拠: ${JSON.stringify(ref.ref)}${ref.sha256 ? ` (sha256:${ref.sha256})` : " (参照URL)"}`);
+  if (observed) lines.push(`観測対象ターン: ${observed.active_turn_id ?? "停止中"}`);
+  if (supersedes) lines.push(`置き換える指示: ${supersedes}。この指示を以後の方針として扱ってください。`);
+  if (retracts) lines.push(`撤回する指示: ${retracts}。以後の方針から除外してください。`);
+  if (expiresAt) lines.push(`有効期限: ${expiresAt}`);
+  if (checkpoint) lines.push(`検証チェックポイント: ${checkpoint}`);
+  return { metadata, wireText: lines.join("\n") + "\n\n" + body, async beforeSend(thread, client) {
+    if (expiresAt && Date.parse(expiresAt) <= Date.now()) throw Object.assign(new Error("Directive expired before sending."), { code: "EXPIRED_DIRECTIVE" });
+    if (observed) {
+      if (observed.v === 2) await verifyPagedFreshness(client, threadId, basedOn);
+      else {
+        if (thread.turns?.some(t => t.itemsView && t.itemsView !== "full") || !thread.turns?.length) thread = await fetchThread(client, threadId);
+        const current = threadSnapshot(thread);
+        if (current.user_revision !== observed.user_revision || current.state.active_turn_id !== observed.active_turn_id) throw Object.assign(new Error("New user input or a different turn was observed. Read the task again before sending."), { code: "STALE_OBSERVATION" });
+      }
+    }
+    await verifyEvidence(refs);
+    if (checkpoint && !(await verifyCheckpoint(threadId, checkpoint, storage)).valid) throw Object.assign(new Error("Checkpoint is no longer valid. Verify the inputs and results before sending."), { code: "STALE_CHECKPOINT" });
+  } };
+}

package/src/distribution.mjs

@@ -0,0 +1,192 @@
+import { constants } from "node:fs";
+import { lstat, mkdir, mkdtemp, open, readdir, realpath, rename, rm } from "node:fs/promises";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
+import path from "node:path";
+import { setTimeout as delay } from "node:timers/promises";
+
+export const PACKAGE_ROOT = fileURLToPath(new URL("../", import.meta.url));
+// Preserve the deployed record format and state namespace across the rename.
+const RECORD = ".codex-steer-runtime.json";
+const hash = value => createHash("sha256").update(value).digest("hex");
+const failure = (message, code = "DEPLOYMENT_UNSAFE") => Object.assign(new Error(message), { code });
+const safeName = name => /^[a-zA-Z0-9][a-zA-Z0-9._-]*$/.test(name) && name !== "." && name !== "..";
+const sameFile = (a, b) => a.dev === b.dev && a.ino === b.ino;
+
+function check(info, directory, privateMode) {
+  if (info.isSymbolicLink() || (directory ? !info.isDirectory() : !info.isFile())
+    || (privateMode ? info.uid !== process.getuid() || (info.mode & 0o7077) : ![0, process.getuid()].includes(info.uid) || (info.mode & 0o7022))
+    || (!directory && (info.nlink !== 1 || info.size > 10 * 1024 * 1024))) {
+    throw failure("Distribution has unsafe ownership, permissions, links, size, or file type.");
+  }
+}
+
+async function ownedDirectory(directory, create = false) {
+  if (create) await mkdir(directory, { mode: 0o700 }).catch(e => { if (e.code !== "EEXIST") throw e; });
+  const info = await lstat(directory); check(info, true, true); return info;
+}
+
+async function checkAncestors(directory) {
+  // A private leaf is not enough if somebody else can rename one of its
+  // parents. Root-owned sticky temporary directories are the sole exception.
+  for (let current = directory; ; current = path.dirname(current)) {
+    const info = await lstat(current);
+    const stickyTemp = info.uid === 0 && (info.mode & 0o1000) !== 0;
+    if (!info.isDirectory() || info.isSymbolicLink() || ![0, process.getuid()].includes(info.uid)
+      || (info.mode & 0o6000) || ((info.mode & 0o022) && !stickyTemp)) throw failure("A distribution ancestor can be replaced by another user.");
+    if (path.dirname(current) === current) break;
+  }
+}
+
+async function resolveHome(home) {
+  let existing = path.resolve(home), canonical;
+  const missing = [];
+  while (true) {
+    try { canonical = await realpath(existing); break; }
+    catch (error) {
+      if (error.code !== "ENOENT" || path.dirname(existing) === existing) throw error;
+      missing.unshift(path.basename(existing)); existing = path.dirname(existing);
+    }
+  }
+  await checkAncestors(canonical);
+  for (const part of missing) {
+    canonical = path.join(canonical, part);
+    await ownedDirectory(canonical, true);
+  }
+  return canonical;
+}
+
+async function readSafe(file, privateMode) {
+  const before = await lstat(file); check(before, false, privateMode);
+  // Do not follow a substituted leaf symlink or block on a substituted FIFO.
+  const handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW | constants.O_NONBLOCK);
+  try {
+    const info = await handle.stat(); check(info, false, privateMode);
+    if (!sameFile(before, info)) throw failure("Distribution changed while being read.");
+    const buffer = Buffer.alloc(info.size + 1); let length = 0;
+    while (length < buffer.length) {
+      const { bytesRead } = await handle.read(buffer, length, buffer.length - length, length);
+      if (!bytesRead) break;
+      length += bytesRead;
+    }
+    const bytes = buffer.subarray(0, length), after = await handle.stat();
+    if (bytes.length !== info.size || after.size !== info.size || after.mtimeMs !== info.mtimeMs || after.ctimeMs !== info.ctimeMs) throw failure("Distribution changed while being read.");
+    return { bytes, info };
+  } finally { await handle.close(); }
+}
+
+async function writeExclusive(file, bytes, mode) {
+  const handle = await open(file, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | constants.O_NOFOLLOW, mode);
+  try { await handle.writeFile(bytes); await handle.sync(); } finally { await handle.close(); }
+}
+
+// The source is the installed package currently executing, never a path or
+// manifest taken from task history, runtime state, or a remote response.
+export async function describeDistribution(root = PACKAGE_ROOT) {
+  root = await realpath(root);
+  await checkAncestors(root);
+  check(await lstat(root), true, false);
+  const names = ["package.json", "LICENSE", "bin/codexteer.mjs", "bin/codexteer-wrapper.mjs", "assets/send-pururu.wav",
+    "scripts/send.applescript", "scripts/inspect.applescript", "scripts/accessibility.applescript"];
+  for (const directory of ["bin", "assets", "scripts", "src", "node_modules", "node_modules/ws", "node_modules/ws/lib"]) {
+    check(await lstat(path.join(root, directory)), true, false);
+  }
+  for (const name of await readdir(path.join(root, "src"))) {
+    if (safeName(name) && name.endsWith(".mjs")) names.push(`src/${name}`);
+  }
+  names.push(...["package.json", "LICENSE", "README.md", "index.js", "browser.js", "wrapper.mjs"].map(name => `node_modules/ws/${name}`));
+  for (const name of await readdir(path.join(root, "node_modules/ws/lib"))) {
+    if (!safeName(name) || !name.endsWith(".js")) throw failure("Unexpected file in the bundled ws dependency.");
+    names.push(`node_modules/ws/lib/${name}`);
+  }
+  if (names.length > 256) throw failure("Distribution contains too many files.");
+  const files = [], contents = new Map(); let total = 0;
+  for (const name of names.sort()) {
+    const { bytes, info } = await readSafe(path.join(root, name), false);
+    const mode = name.startsWith("bin/") ? 0o700 : 0o600;
+    if (mode === 0o700 && !(info.mode & 0o100)) throw failure("A distribution executable is missing its executable permission.");
+    total += bytes.length;
+    if (total > 32 * 1024 * 1024) throw failure("Distribution is too large.");
+    files.push({ path: name, size: bytes.length, sha256: hash(bytes), mode }); contents.set(name, bytes);
+  }
+  const pkg = JSON.parse(contents.get("package.json"));
+  if (typeof pkg.version !== "string" || pkg.version.length > 100 || !/^\d+\.\d+\.\d+(?:-[\w.-]+)?(?:\+[\w.-]+)?$/.test(pkg.version)) throw failure("Invalid distribution version.");
+  const ws = JSON.parse(contents.get("node_modules/ws/package.json"));
+  if (ws.name !== "ws" || ws.version !== pkg.dependencies?.ws || Object.keys(ws.dependencies ?? {}).length) throw failure("Bundled dependencies do not match the distribution.");
+  const manifest = { schema: 1, package: pkg.name, version: pkg.version, files };
+  const sha256 = hash(JSON.stringify(manifest));
+  return { root, manifest, sha256, id: `${pkg.version}-${sha256}`, contents };
+}
+
+export async function verifyDeployment(directory, distribution) {
+  await ownedDirectory(directory);
+  const expected = new Map(distribution.manifest.files.map(file => [file.path, file]));
+  const record = Buffer.from(JSON.stringify({ manifest: distribution.manifest, sha256: distribution.sha256 }) + "\n");
+  expected.set(RECORD, { size: record.length, sha256: hash(record), mode: 0o600 });
+  const found = new Set();
+  async function visit(relative = "") {
+    const current = path.join(directory, relative); await ownedDirectory(current);
+    for (const name of await readdir(current)) {
+      if (name !== RECORD && !safeName(name)) throw failure("Unexpected deployment path.");
+      const child = relative ? `${relative}/${name}` : name, file = path.join(directory, child);
+      const info = await lstat(file);
+      if (info.isDirectory()) {
+        if (![...expected.keys()].some(key => key.startsWith(child + "/"))) throw failure("Unexpected deployment directory.");
+        await visit(child); continue;
+      }
+      const entry = expected.get(child);
+      if (!entry) throw failure("Unexpected deployment file.");
+      const { bytes, info: opened } = await readSafe(file, true);
+      if ((opened.mode & 0o777) !== entry.mode || bytes.length !== entry.size || hash(bytes) !== entry.sha256) throw failure("Deployed files differ from the installed distribution.", "DEPLOYMENT_MODIFIED");
+      found.add(child);
+    }
+  }
+  await visit();
+  if (found.size !== expected.size) throw failure("Deployment is incomplete.", "DEPLOYMENT_MODIFIED");
+  return { directory, wrapper_path: path.join(directory, "bin/codexteer-wrapper.mjs"), version: distribution.manifest.version, sha256: distribution.sha256 };
+}
+
+export async function prepareDeployment(home, { sourceRoot = PACKAGE_ROOT } = {}) {
+  const distribution = await describeDistribution(sourceRoot);
+  // CODEX_HOME may itself be a user-configured symlink; only its canonical
+  // owner-writable directory is accepted. Never follow links below that root.
+  const canonicalHome = await resolveHome(home);
+  const homeInfo = await lstat(canonicalHome);
+  if (!homeInfo.isDirectory() || homeInfo.uid !== process.getuid() || (homeInfo.mode & 0o7022)) throw failure("CODEX_HOME must be an owner-controlled directory.");
+  const stateRoot = path.join(canonicalHome, "codex-steer"), root = path.join(stateRoot, "runtimes");
+  await ownedDirectory(stateRoot, true); await ownedDirectory(root, true);
+  const target = path.join(root, distribution.id), lock = path.join(root, `.install-${distribution.id}`);
+  let lockInfo;
+  // An abandoned lock is never stolen. A concurrent caller can reuse the
+  // completed distribution after its installer releases this lock.
+  for (let attempt = 0; attempt < 100; attempt++) {
+    try { await mkdir(lock, { mode: 0o700 }); lockInfo = await ownedDirectory(lock); break; }
+    catch (error) {
+      if (error.code !== "EEXIST") throw error;
+      await ownedDirectory(lock).catch(e => { if (e.code !== "ENOENT") throw e; });
+      await delay(50);
+    }
+  }
+  if (!lockInfo) throw failure("Runtime placement is busy or an earlier installation was interrupted. Inspect the installation lock before retrying.", "DEPLOYMENT_BUSY");
+  let stage, stageInfo;
+  try {
+    const existing = await lstat(target).catch(e => { if (e.code !== "ENOENT") throw e; return null; });
+    if (existing) return { ...await verifyDeployment(target, distribution), codex_home: canonicalHome, reused: true };
+    stage = await mkdtemp(path.join(root, ".stage-")); stageInfo = await ownedDirectory(stage);
+    for (const file of distribution.manifest.files) {
+      const parts = file.path.split("/"); parts.pop(); let parent = stage;
+      for (const part of parts) { parent = path.join(parent, part); await ownedDirectory(parent, true); }
+      await writeExclusive(path.join(stage, file.path), distribution.contents.get(file.path), file.mode);
+    }
+    await writeExclusive(path.join(stage, RECORD), JSON.stringify({ manifest: distribution.manifest, sha256: distribution.sha256 }) + "\n", 0o600);
+    await verifyDeployment(stage, distribution);
+    // All cooperating installers hold the exclusive lock, and the parent is
+    // private. Refuse even an empty existing directory rather than replacing it.
+    if (await lstat(target).catch(e => { if (e.code !== "ENOENT") throw e; return null; })) throw failure("Deployment destination appeared during placement.");
+    await rename(stage, target); stage = null;
+    return { ...await verifyDeployment(target, distribution), codex_home: canonicalHome, reused: false };
+  } finally {
+    if (stage && sameFile(stageInfo, await lstat(stage).catch(() => ({})))) await rm(stage, { recursive: true });
+    if (sameFile(lockInfo, await lstat(lock).catch(() => ({})))) await rm(lock, { recursive: true });
+  }
+}

package/src/evidence.mjs

@@ -0,0 +1,33 @@
+import { stat, realpath } from "node:fs/promises";
+import { createReadStream } from "node:fs";
+import { createHash } from "node:crypto";
+import path from "node:path";
+
+export async function fingerprintFile(input) {
+  const ref = path.resolve(input), canonical = await realpath(ref), before = await stat(canonical);
+  if (!before.isFile()) throw new Error("Evidence must be a file or an http(s)/codex URL.");
+  const hash = createHash("sha256");
+  for await (const data of createReadStream(canonical)) hash.update(data);
+  const after = await stat(canonical);
+  if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || (await realpath(ref)) !== canonical) throw new Error("File changed while being fingerprinted. Try again after editing finishes.");
+  return { type: "file", ref, path: canonical, size: after.size, mode: after.mode & 0o777, sha256: hash.digest("hex") };
+}
+
+export async function collectEvidence(refs = []) {
+  return Promise.all(refs.map(async ref => {
+    if (/^(https?|codex):\/\//i.test(ref)) {
+      const url = new URL(ref);
+      if (url.username || url.password) throw new Error("Evidence URLs must not contain credentials.");
+      return { type: "url", ref: url.href, verification: "reference_only" };
+    }
+    return fingerprintFile(ref);
+  }));
+}
+
+export async function verifyEvidence(evidence = []) {
+  for (const old of evidence.filter(e => e.type === "file")) {
+    let current;
+    try { current = await fingerprintFile(old.ref); } catch { throw Object.assign(new Error("Evidence file is missing or changed. Read it again before sending."), { code: "STALE_EVIDENCE" }); }
+    if (["path", "size", "mode", "sha256"].some(k => old[k] !== current[k])) throw Object.assign(new Error("Evidence file changed. Read it again before sending."), { code: "STALE_EVIDENCE" });
+  }
+}