codexteer 0.14.1

package/node_modules/ws/package.json

@@ -0,0 +1,74 @@
+{
+  "name": "ws",
+  "version": "8.21.3",
+  "description": "Simple to use, blazing fast and thoroughly tested websocket client and server for Node.js",
+  "keywords": [
+    "HyBi",
+    "Push",
+    "RFC-6455",
+    "WebSocket",
+    "WebSockets",
+    "real-time"
+  ],
+  "homepage": "https://github.com/websockets/ws",
+  "bugs": "https://github.com/websockets/ws/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/websockets/ws.git"
+  },
+  "author": "Einar Otto Stangvik <einaros@gmail.com> (http://2x.io)",
+  "license": "MIT",
+  "main": "index.js",
+  "exports": {
+    ".": {
+      "browser": "./browser.js",
+      "import": "./wrapper.mjs",
+      "require": "./index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "browser": "browser.js",
+  "engines": {
+    "node": ">=10.0.0"
+  },
+  "files": [
+    "browser.js",
+    "index.js",
+    "lib/*.js",
+    "wrapper.mjs"
+  ],
+  "scripts": {
+    "test": "nyc --reporter=lcov --reporter=text mocha --throw-deprecation test/*.test.js",
+    "integration": "mocha --throw-deprecation test/*.integration.js",
+    "lint": "eslint . && prettier --check --ignore-path .gitignore \"**/*.{json,md,yaml,yml}\""
+  },
+  "peerDependencies": {
+    "bufferutil": "^4.0.1",
+    "utf-8-validate": ">=5.0.2"
+  },
+  "peerDependenciesMeta": {
+    "bufferutil": {
+      "optional": true
+    },
+    "utf-8-validate": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@eslint/js": "^10.0.1",
+    "benchmark": "^2.1.4",
+    "bufferutil": "^4.0.1",
+    "eslint": "^10.0.1",
+    "eslint-config-prettier": "^10.0.1",
+    "eslint-plugin-prettier": "^5.0.0",
+    "globals": "^17.0.0",
+    "mocha": "^8.4.0",
+    "nyc": "^15.0.0",
+    "prettier": "^3.0.0",
+    "utf-8-validate": "^6.0.0"
+  },
+  "allowScripts": {
+    "bufferutil": true,
+    "utf-8-validate": true
+  }
+}

package/node_modules/ws/wrapper.mjs

@@ -0,0 +1,21 @@
+import createWebSocketStream from './lib/stream.js';
+import extension from './lib/extension.js';
+import PerMessageDeflate from './lib/permessage-deflate.js';
+import Receiver from './lib/receiver.js';
+import Sender from './lib/sender.js';
+import subprotocol from './lib/subprotocol.js';
+import WebSocket from './lib/websocket.js';
+import WebSocketServer from './lib/websocket-server.js';
+
+export {
+  createWebSocketStream,
+  extension,
+  PerMessageDeflate,
+  Receiver,
+  Sender,
+  subprotocol,
+  WebSocket,
+  WebSocketServer
+};
+
+export default WebSocket;

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "codexteer",
+  "version": "0.14.1",
+  "description": "Send steering messages to running Codex Desktop threads from a terminal.",
+  "type": "module",
+  "bin": {
+    "codexteer": "bin/codexteer.mjs"
+  },
+  "scripts": {
+    "check": "node scripts/check-syntax.mjs",
+    "test": "node --test",
+    "test:protocol": "node scripts/probe-app-server.mjs",
+    "benchmark:read": "node scripts/benchmark-read.mjs",
+    "test:package": "node scripts/test-package.mjs"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "dependencies": {
+    "ws": "8.21.3"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/vinhphatfsg/codexteer.git"
+  },
+  "files": [
+    "bin/*.mjs",
+    "src/*.mjs",
+    "scripts/*.applescript",
+    "assets/send-pururu.wav",
+    "docs/distribution.md"
+  ],
+  "bundleDependencies": [
+    "ws"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}

package/scripts/accessibility.applescript

@@ -0,0 +1,43 @@
+on run argv
+  if (count of argv) is less than 1 then error "Expected enable or restore." number 64
+  set operation to item 1 of argv
+
+  tell application "System Events"
+    set appProcess to first application process whose bundle identifier is "com.openai.codex"
+    tell appProcess
+      if operation is "enable" then
+        try
+          set manualWasEnabled to (value of attribute "AXManualAccessibility") as boolean
+          if manualWasEnabled is false then
+            set value of attribute "AXManualAccessibility" to true
+            return "manual"
+          end if
+          return "unchanged"
+        on error
+          set enhancedWasEnabled to false
+          try
+            set enhancedWasEnabled to (value of attribute "AXEnhancedUserInterface") as boolean
+          end try
+          if enhancedWasEnabled is false then
+            set value of attribute "AXEnhancedUserInterface" to true
+            return "enhanced"
+          end if
+          return "unchanged"
+        end try
+      end if
+
+      if operation is "restore" then
+        if (count of argv) is not 2 then error "Expected accessibility mode to restore." number 64
+        set accessibilityMode to item 2 of argv
+        if accessibilityMode is "manual" then
+          set value of attribute "AXManualAccessibility" to false
+        else if accessibilityMode is "enhanced" then
+          set value of attribute "AXEnhancedUserInterface" to false
+        end if
+        return "restored"
+      end if
+    end tell
+  end tell
+
+  error "Expected enable or restore." number 64
+end run

package/scripts/inspect.applescript

@@ -0,0 +1,72 @@
+on run argv
+  if (count of argv) is not 1 then error "Expected wait time in milliseconds." number 64
+  set waitSeconds to ((item 1 of argv) as integer) / 1000
+
+  tell application "ChatGPT" to activate
+  delay waitSeconds
+
+  tell application "System Events"
+    set appProcess to first application process whose bundle identifier is "com.openai.codex"
+    tell appProcess
+      set frontmost to true
+      if not (exists front window) then error "Codex Desktop has no front window." number 69
+      set focusedElement to missing value
+      set focusedRole to "missing"
+      set focusedSubrole to ""
+      set focusedDescription to ""
+      set focusedTitle to ""
+      set focusedHelp to ""
+      set windowTitle to ""
+      try
+        set focusedElement to value of attribute "AXFocusedUIElement"
+      end try
+      if focusedElement is not missing value then
+        try
+          set focusedRole to role of focusedElement as text
+        end try
+        try
+          set focusedSubrole to (value of attribute "AXSubrole" of focusedElement) as text
+        end try
+        try
+          set focusedDescription to (value of attribute "AXDescription" of focusedElement) as text
+        end try
+        try
+          set focusedTitle to (value of attribute "AXTitle" of focusedElement) as text
+        end try
+        try
+          set focusedHelp to (value of attribute "AXHelp" of focusedElement) as text
+        end try
+      end if
+      try
+        set windowTitle to (value of attribute "AXTitle" of front window) as text
+      end try
+
+      set textAreaCount to 0
+      set textFieldCount to 0
+      set webAreaCount to 0
+      set windowContents to entire contents of front window
+      repeat with candidate in windowContents
+        try
+          set candidateRole to role of candidate
+          if candidateRole is "AXTextArea" then
+            set textAreaCount to textAreaCount + 1
+          else if candidateRole is "AXTextField" then
+            set textFieldCount to textFieldCount + 1
+          else if candidateRole is "AXWebArea" then
+            set webAreaCount to webAreaCount + 1
+          end if
+        end try
+      end repeat
+    end tell
+  end tell
+
+  return "window_title=" & windowTitle & linefeed & ¬
+    "focused_role=" & focusedRole & linefeed & ¬
+    "focused_subrole=" & focusedSubrole & linefeed & ¬
+    "focused_description=" & focusedDescription & linefeed & ¬
+    "focused_title=" & focusedTitle & linefeed & ¬
+    "focused_help=" & focusedHelp & linefeed & ¬
+    "text_area_count=" & textAreaCount & linefeed & ¬
+    "text_field_count=" & textFieldCount & linefeed & ¬
+    "web_area_count=" & webAreaCount
+end run

package/scripts/send.applescript

@@ -0,0 +1,45 @@
+on run argv
+  if (count of argv) is not 4 then error "Expected wait time, submit shortcut, focus policy, and previous process ID." number 64
+  set waitSeconds to ((item 1 of argv) as integer) / 1000
+  set submitShortcut to item 2 of argv
+  set focusPolicy to item 3 of argv
+  set previousProcessId to (item 4 of argv) as integer
+  if submitShortcut is not "plain" and submitShortcut is not "command" and submitShortcut is not "command-shift" then error "Invalid submit shortcut." number 64
+  if focusPolicy is not "restore" and focusPolicy is not "keep" then error "Invalid focus policy." number 64
+
+  if focusPolicy is "restore" then my restoreFocus(previousProcessId)
+  delay waitSeconds
+
+  try
+    tell application "System Events"
+      set appProcess to first application process whose bundle identifier is "com.openai.codex"
+      tell appProcess
+        set frontmost to true
+        if not (exists front window) then error "Codex Desktop has no front window." number 69
+      end tell
+
+      if submitShortcut is "command" then
+        key code 36 using {command down}
+      else if submitShortcut is "command-shift" then
+        key code 36 using {command down, shift down}
+      else
+        key code 36
+      end if
+    end tell
+
+    if focusPolicy is "restore" then my restoreFocus(previousProcessId)
+  on error errorMessage number errorNumber
+    if focusPolicy is "restore" then my restoreFocus(previousProcessId)
+    error errorMessage number errorNumber
+  end try
+
+  return "sent"
+end run
+
+on restoreFocus(processId)
+  if processId is 0 then return
+  tell application "System Events"
+    set matchingProcesses to application processes whose unix id is processId
+    if (count of matchingProcesses) > 0 then set frontmost of item 1 of matchingProcesses to true
+  end tell
+end restoreFocus

package/src/app-server.mjs

@@ -0,0 +1,117 @@
+import { mkdir, rm, readFile, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import path from "node:path";
+import { discoverRuntime, verifyControlEndpoint } from "./runtime.mjs";
+import { RpcClient, RpcFailure } from "./rpc.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { ensureDesktopSubscription } from "./subscription.mjs";
+import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
+
+export class SendFailure extends Error {
+  constructor(message, { code = "NOT_SENT", uncertain = false, threadId, rpcCode, capability, operation } = {}) {
+    super(message);
+    this.code = code;
+    this.delivery_status = uncertain ? "unknown" : "not_sent";
+    this.sent = uncertain ? null : false;
+    this.thread_id = threadId;
+    this.rpc_code = rpcCode;
+    this.capability = capability;
+    this.operation = operation;
+  }
+}
+
+function activeTurn(thread) {
+  const turns = thread.turns?.filter(turn => turn.status === "inProgress") ?? [];
+  return thread.status?.type === "active" && turns.length === 1 ? turns[0] : null;
+}
+
+function verifyThread(thread, threadId) {
+  if (thread?.id !== threadId) throw new Error("App Server returned a different task ID. Nothing was sent.");
+  if (thread.canAcceptDirectInput === false) throw new Error("This task does not accept direct input.");
+  if (!Array.isArray(thread.turns)) throw new Error("App Server did not return the task's turn state.");
+}
+
+export async function sendOnClient(client, threadId, message, { newTurn = false, subscribe, clientMessageId = randomUUID(), beforeSend } = {}) {
+  const { thread } = await client.request("thread/read", { threadId, includeTurns: true });
+  verifyThread(thread, threadId);
+  const input = [{ type: "text", text: message }];
+  if (!newTurn) {
+    const turn = activeTurn(thread);
+    if (!turn) throw new Error("The task has no unambiguous active turn. Use --new-turn for an idle task.");
+    await beforeSend?.(thread, client);
+    // Desktop uses clientId on the resulting userMessage to render external
+    // steering as a user bubble instead of just an anonymous "steered" marker.
+    // This is a presentation/correlation ID, not a retry/idempotency guarantee.
+    const clientUserMessageId = clientMessageId;
+    const accepted = await client.request("turn/steer", { threadId, expectedTurnId: turn.id, input, clientUserMessageId }, { mutation: true });
+    if (accepted?.turnId !== turn.id) throw new RpcFailure("App Server returned an unexpected turn ID. Do not retry automatically.", { code: "PROTOCOL_ERROR", uncertain: true });
+    return { turn_id: accepted.turnId, client_message_id: clientUserMessageId };
+  }
+  if (!["idle", "notLoaded"].includes(thread.status?.type)) throw new Error("--new-turn requires an idle task. Nothing was sent.");
+  // Resume through Desktop's long-lived connection so approval ownership
+  // survives the short-lived sender. Never resume only on the sender connection.
+  if (!subscribe) throw new Error("Desktop subscription support is required for --new-turn.");
+  // Optional safety checks (e.g. a paged --based-on cursor) must be usable before
+  // resuming, too. Validate again after resume to catch intervening user input.
+  await beforeSend?.(thread, client);
+  await subscribe(threadId);
+  const resumed = await client.request("thread/read", { threadId, includeTurns: true });
+  verifyThread(resumed.thread, threadId);
+  if (resumed.thread.status?.type !== "idle") throw new Error("Task became active while resuming. Nothing was sent.");
+  await beforeSend?.(resumed.thread, client);
+  const clientUserMessageId = clientMessageId;
+  const accepted = await client.request("turn/start", { threadId, input, clientUserMessageId }, { mutation: true });
+  if (typeof accepted?.turn?.id !== "string") throw new RpcFailure("App Server did not confirm a turn ID. Do not retry automatically.", { code: "PROTOCOL_ERROR", uncertain: true });
+  return { turn_id: accepted.turn.id, client_message_id: clientUserMessageId };
+}
+
+export async function sendAppServerMessage(threadInput, message, { dryRun = false, newTurn = false, clientMessageId = randomUUID(), beforeSend, connect = RpcClient.connect, discover = discoverRuntime, subscribe = ensureDesktopSubscription, inspectControl = verifyControlEndpoint } = {}) {
+  const threadId = normalizeThreadId(threadInput);
+  if (typeof message !== "string" || !message.trim()) throw new Error("Message must not be empty.");
+  const plan = { thread_id: threadId, backend: "app-server", delivery_action: newTurn ? "new-turn" : "steer", message_characters: [...message].length, dry_run: dryRun };
+  if (dryRun) return { ...plan, sent: false, delivery_status: "not_sent" };
+  let client;
+  let lock;
+  let result;
+  const token = randomUUID();
+  const operation = newTurn ? "send_new_turn" : "send";
+  try {
+    const { paths, state } = await discover();
+    assertRuntimeOperation(state, operation);
+    if (newTurn) await inspectControl(paths);
+    const candidate = path.join(paths.lease, `send-${threadId}`);
+    try { await mkdir(candidate, { mode: 0o700 }); } catch (error) {
+      if (error.code === "EEXIST") throw new Error("Another send is in progress for this task, or a previous sender exited unexpectedly. Restart the shared Desktop after checking delivery before retrying.");
+      throw error;
+    }
+    lock = candidate;
+    await writeFile(path.join(lock, "owner"), token, { mode: 0o600 });
+    client = compatibleClient(await connect(paths.socket), state);
+    const checkRuntime = async () => {
+      const current = await discover(); assertRuntimeOperation(current.state, operation);
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || (newTurn && current.paths.control !== paths.control)) {
+        throw Object.assign(new Error("Runtime changed before delivery. Read the target again before sending."), { code: "RUNTIME_CHANGED" });
+      }
+      if (newTurn) await inspectControl(current.paths);
+    };
+    const receipt = await sendOnClient(client, threadId, message, { newTurn, clientMessageId,
+      beforeSend: async (...args) => { await beforeSend?.(...args); await checkRuntime(); },
+      subscribe: async id => { await checkRuntime(); return subscribe(paths.control, id); },
+    });
+    result = { ...plan, ...receipt, sent: true, delivery_status: "accepted" };
+    return result;
+  } catch (error) {
+    throw new SendFailure(error.uncertain
+      ? "Delivery is unknown because App Server did not confirm receipt. Check the target task before retrying."
+      : error.message, { code: error.code ?? "NOT_SENT", uncertain: error.uncertain, threadId, rpcCode: error.rpcCode, capability: error.capability, operation: error.operation });
+  } finally {
+    // Cleanup failure must never turn an acknowledged send into a retryable
+    // error. Keep its acceptance receipt and leave any stale lock fail-closed.
+    try {
+      client?.close();
+      if (lock && await readFile(path.join(lock, "owner"), "utf8").catch(() => null) === token) {
+        await rm(lock, { recursive: true, force: true });
+      }
+    } catch { if (result) result.runtime_cleanup_required = true; }
+  }
+}

package/src/bridge.mjs

@@ -0,0 +1,79 @@
+import { StringDecoder } from "node:string_decoder";
+import { once } from "node:events";
+import WebSocket from "ws";
+
+const MAX_MESSAGE = 64 * 1024 * 1024;
+
+// Desktop owns initialization and every server-initiated approval/tool response.
+// The subscription adapter may consume its own thread/resume response; all other
+// responses and every notification/request are forwarded to Desktop unchanged.
+export async function relay(input, output, socket, { onDesktopMessage = () => {}, onServerMessage = () => {} } = {}) {
+  const decoder = new StringDecoder("utf8");
+  let pending = "";
+  let outputQueue = Promise.resolve();
+  let outputBytes = 0;
+  let fail;
+  let finished = false;
+  const failure = new Promise((_, reject) => { fail = reject; });
+  // Attach before asynchronous iteration starts; errors must also break blocked reads.
+  const onError = () => fail(new Error("Desktop relay connection failed."));
+  const onClose = () => { if (!finished) fail(new Error("Desktop relay connection closed.")); };
+  const onMessage = (buffer, binary) => {
+    try {
+      if (binary) throw new Error("Unexpected binary App Server frame.");
+      const text = buffer.toString();
+      const parsed = JSON.parse(text);
+      if (onServerMessage(parsed) === false) return;
+      // JSON.parse is only for routing. Preserve number literals (including
+      // integers above JS's safe range), escaping and unknown fields on the wire.
+      // Actual CR/LF in valid JSON can only be whitespace outside strings.
+      const line = text.replace(/[\r\n]/g, "") + "\n";
+      outputBytes += Buffer.byteLength(line);
+      if (outputBytes > MAX_MESSAGE * 2) throw new Error("Desktop relay output buffer limit exceeded.");
+      socket.pause();
+      outputQueue = outputQueue.then(async () => {
+        if (!output.write(line)) await once(output, "drain");
+        outputBytes -= Buffer.byteLength(line);
+        if (outputBytes === 0 && socket.readyState === WebSocket.OPEN) socket.resume();
+      });
+      outputQueue.catch(fail);
+    } catch { fail(new Error("Invalid or oversized App Server relay message.")); }
+  };
+  socket.on("message", onMessage);
+  socket.on("error", onError);
+  socket.on("close", onClose);
+  output.on("error", onError);
+  const send = async line => {
+    if (!line.trim()) return;
+    if (Buffer.byteLength(line) > MAX_MESSAGE) throw new Error("Desktop relay input limit exceeded.");
+    let parsed;
+    try { parsed = JSON.parse(line); } catch { throw new Error("Invalid Desktop protocol message."); }
+    onDesktopMessage(parsed);
+    await new Promise((resolve, reject) => socket.send(line, error => error ? reject(new Error("Desktop relay send failed.")) : resolve()));
+  };
+  const copyInput = async () => {
+    for await (const chunk of input) {
+      pending += decoder.write(chunk);
+      let end;
+      while ((end = pending.indexOf("\n")) !== -1) {
+        const line = pending.slice(0, end);
+        pending = pending.slice(end + 1);
+        await send(line);
+      }
+      if (Buffer.byteLength(pending) > MAX_MESSAGE) throw new Error("Desktop relay input limit exceeded.");
+    }
+    pending += decoder.end();
+    if (pending.trim()) await send(pending);
+    await outputQueue;
+  };
+  try { await Promise.race([copyInput(), failure]); } finally {
+    finished = true;
+    socket.off("message", onMessage);
+    socket.off("error", onError);
+    socket.off("close", onClose);
+    output.off("error", onError);
+    socket.terminate();
+    // Unblock a pending stdin read when the server dies.
+    input.destroy();
+  }
+}

package/src/checkpoint.mjs

@@ -0,0 +1,128 @@
+import { lstat, readdir, realpath, readlink } from "node:fs/promises";
+import { watch } from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+import { fingerprintFile, collectEvidence, verifyEvidence } from "./evidence.mjs";
+import { digest } from "./observe.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { readRecord, writeRecord, listRecords, withStoreLock } from "./store.mjs";
+import { runCommand } from "./runner.mjs";
+
+const within = (file, root) => file === root || file.startsWith(root + path.sep);
+function excluded(file, excludes) { return file.split(path.sep).includes(".git") || excludes.some(x => within(file, x)); }
+
+export async function captureInputs(roots, excludes = [], { allowMissing = false } = {}) {
+  const records = new Map();
+  async function visit(file) {
+    if (excluded(file, excludes) || records.has(file)) return;
+    let info;
+    try { info = await lstat(file); } catch (e) { if (e.code === "ENOENT" && allowMissing) return; throw e; }
+    if (info.isSymbolicLink()) {
+      const target = await realpath(file), targetInfo = await lstat(target);
+      if (targetInfo.isDirectory()) throw new Error("Directory symlinks are not snapshot inputs. Specify the real directory explicitly.");
+      records.set(file, { ...await fingerprintFile(file), link: await readlink(file), mtime_ms: targetInfo.mtimeMs, ctime_ms: targetInfo.ctimeMs });
+    } else if (info.isDirectory()) {
+      records.set(file, { type: "directory", ref: file, mode: info.mode & 0o777 });
+      for (const name of (await readdir(file)).sort()) await visit(path.join(file, name));
+    } else if (info.isFile()) records.set(file, { ...await fingerprintFile(file), mtime_ms: info.mtimeMs, ctime_ms: info.ctimeMs });
+    else throw new Error("Snapshot inputs must be files or directories.");
+  }
+  for (const root of roots) await visit(root);
+  const files = [...records.values()].sort((a, b) => a.ref.localeCompare(b.ref));
+  return { roots, excludes, files, digest: digest(files) };
+}
+
+function differences(before, after) {
+  const a = new Map(before.files.map(f => [f.ref, digest(f)])), b = new Map(after.files.map(f => [f.ref, digest(f)]));
+  return { added: [...b.keys()].filter(k => !a.has(k)), removed: [...a.keys()].filter(k => !b.has(k)), changed: [...a.keys()].filter(k => b.has(k) && a.get(k) !== b.get(k)) };
+}
+
+export async function getCheckpoint(threadInput, id, storage = {}) {
+  const threadId = normalizeThreadId(threadInput), entry = await readRecord("checkpoints", id, storage);
+  if (!entry || entry.thread_id !== threadId || entry.id !== id) throw new Error("Checkpoint not found for this task.");
+  return entry;
+}
+
+export async function createCheckpoint(threadInput, name, { paths, excludes = [], cwd = process.cwd(), ...storage }) {
+  const threadId = normalizeThreadId(threadInput);
+  if (!name?.trim() || !paths?.length) throw new Error("capture requires a name and at least one --path.");
+  const roots = [...new Set(paths.map(p => path.resolve(cwd, p)))], omit = excludes.map(p => path.resolve(cwd, p));
+  const snapshot = await captureInputs(roots, omit);
+  if (!snapshot.files.some(f => f.type === "file")) throw new Error("No input files were selected.");
+  const entry = { schema: 1, id: randomUUID(), thread_id: threadId, name, cwd: path.resolve(cwd), created_at: new Date().toISOString(), snapshot, runs: [], artifacts: [] };
+  await writeRecord("checkpoints", entry.id, entry, storage);
+  return checkpointSummary(entry);
+}
+
+const withoutOutput = ({ output_tail, ...rest }) => rest;
+export function checkpointSummary(entry, includeOutput = false) {
+  return { ...entry, runs: includeOutput ? entry.runs : entry.runs.map(withoutOutput), snapshot: { ...entry.snapshot, files: undefined, file_count: entry.snapshot.files.filter(f => f.type === "file").length, directory_count: entry.snapshot.files.filter(f => f.type === "directory").length } };
+}
+
+export async function verifyCheckpoint(threadInput, id, storage = {}) {
+  const entry = await getCheckpoint(threadInput, id, storage);
+  const current = await captureInputs(entry.snapshot.roots, entry.snapshot.excludes, { allowMissing: true });
+  const inputsCurrent = current.digest === entry.snapshot.digest;
+  const latest = entry.runs.at(-1) ?? null;
+  const artifacts = await Promise.all(entry.artifacts.map(async a => {
+    try { await verifyEvidence([a]); return { ...a, current: true }; } catch { return { ...a, current: false }; }
+  }));
+  return { ...checkpointSummary(entry), inputs_current: inputsCurrent, differences: differences(entry.snapshot, current), artifacts,
+    latest_run: latest ? withoutOutput(latest) : null, valid: inputsCurrent && latest?.status === "completed" && latest.exit_code === 0 && !latest.error && !latest.timed_out && latest.inputs_unchanged === true && artifacts.filter(a => a.run_id === latest.id).every(a => a.current) };
+}
+
+function watchInputs(snapshot) {
+  const touched = new Set(), watchers = []; let error = null;
+  const files = new Map(snapshot.files.map(f => [f.ref, f]));
+  const dirs = [...new Set(snapshot.roots.map(r => files.get(r)?.type === "directory" ? r : path.dirname(r)))];
+  try {
+    for (const dir of dirs) {
+      const watcher = watch(dir, { recursive: true }, (_, filename) => {
+        const file = filename ? path.resolve(dir, filename.toString()) : dir;
+        if (!excluded(file, snapshot.excludes) && (!filename || snapshot.roots.some(r => within(file, r)))) { if (touched.size < 100) touched.add(file); }
+      });
+      watcher.on("error", e => { error = e.message; }); watchers.push(watcher);
+    }
+  } catch (e) { for (const w of watchers) w.close(); throw e; }
+  return { touched, get error() { return error; }, close() { for (const w of watchers) w.close(); } };
+}
+
+export async function runCheckpoint(threadInput, id, argv, { timeoutMs = 0, ...storage } = {}) {
+  if (!argv.length || !argv[0] || !Number.isInteger(timeoutMs) || timeoutMs < 0 || timeoutMs > 86400000) throw new Error("A command and timeout-ms between 0 and 86400000 are required.");
+  const threadId = normalizeThreadId(threadInput);
+  return withStoreLock(`checkpoint-${id}`, async () => {
+    const entry = await getCheckpoint(threadId, id, storage), watcher = watchInputs(entry.snapshot);
+    try {
+      const before = await captureInputs(entry.snapshot.roots, entry.snapshot.excludes, { allowMissing: true });
+      if (before.digest !== entry.snapshot.digest) throw new Error("Inputs changed since capture. Capture a new checkpoint before running.");
+      const run = { id: randomUUID(), argv, status: "running", started_at: new Date().toISOString() };
+      entry.runs.push(run); await writeRecord("checkpoints", id, entry, storage);
+      const result = await runCommand(argv, { cwd: entry.cwd, timeoutMs, onStart: async pid => { run.pid = pid; await writeRecord("checkpoints", id, entry, storage); } });
+      let after, snapshotError;
+      try { after = await captureInputs(entry.snapshot.roots, entry.snapshot.excludes, { allowMissing: true }); } catch (e) { snapshotError = e.message; }
+      Object.assign(run, result, { status: "completed", inputs_unchanged: after?.digest === entry.snapshot.digest && !watcher.touched.size && !watcher.error,
+        touched_paths: [...watcher.touched], observation_error: watcher.error ?? snapshotError ?? null, differences: after ? differences(entry.snapshot, after) : null });
+      await writeRecord("checkpoints", id, entry, storage);
+      return { checkpoint_id: id, ...run, valid: run.exit_code === 0 && !run.error && !run.timed_out && run.inputs_unchanged };
+    } finally { watcher.close(); }
+  }, storage);
+}
+
+export async function attachArtifacts(threadInput, id, refs, storage = {}) {
+  if (!refs.length) throw new Error("At least one --artifact file is required.");
+  return withStoreLock(`checkpoint-${id}`, async () => {
+    const verified = await verifyCheckpoint(threadInput, id, storage);
+    if (!verified.valid) throw new Error("A successful run against unchanged inputs is required before attaching artifacts.");
+    const artifacts = await collectEvidence(refs);
+    if (artifacts.some(a => a.type !== "file")) throw new Error("Artifacts must be local files.");
+    const entry = await getCheckpoint(threadInput, id, storage);
+    entry.artifacts.push(...artifacts.map(a => ({ ...a, run_id: entry.runs.at(-1).id, attached_at: new Date().toISOString() })));
+    await writeRecord("checkpoints", id, entry, storage);
+    return checkpointSummary(entry);
+  }, storage);
+}
+
+export async function listCheckpoints(threadInput, storage = {}) {
+  const threadId = normalizeThreadId(threadInput);
+  return (await listRecords("checkpoints", storage)).filter(c => c?.thread_id === threadId).sort((a, b) => a.created_at.localeCompare(b.created_at)).map(entry => checkpointSummary(entry));
+}