codexteer 0.16.0 → 0.18.0

package/src/thread-create.mjs

@@ -0,0 +1,128 @@
+import { createHash, randomUUID } from "node:crypto";
+import { isDeepStrictEqual } from "node:util";
+import { setTimeout as delay } from "node:timers/promises";
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
+import { normalizeThreadId, threadDeepLink } from "./thread-id.mjs";
+import { projectsOnClient, projectAliases, resolveProject, projectWorkspace, validateProject } from "./projects.mjs";
+import { readSendState } from "./app-server.mjs";
+import { fetchThread } from "./observe.mjs";
+import { discoverNativeEndpoint, inspectNativeEndpoint, nativeToolJson } from "./native-rpc.mjs";
+import { nativeOnAppServer, inspectNativeCommandProtocol, mutationOutcomeUnknown } from "./native-command.mjs";
+import { desktopMembership, initialInstructionMatches, validateMembershipCatalog } from "./creation-verification.mjs";
+import { writeRecord, storePath } from "./store.mjs";
+import { createStandaloneProjectThread } from "./standalone-create.mjs";
+
+const failure = (message, code = "CREATION_FAILED") => Object.assign(new Error(message), { code });
+
+export function creationOptions(options = {}) {
+  if (["cwd", "permissions", "sandbox", "approvalPolicy", "approvalsReviewer", "viaThread"].some(key => options[key] !== undefined)) throw failure("Native creation uses Desktop's project and permission settings. cwd/permission overrides and --via-thread are unsupported.", "INVALID_CREATION_OPTIONS");
+  for (const key of ["title", "model"]) if (options[key] !== undefined && (typeof options[key] !== "string" || !options[key].trim())) throw failure(`${key} must not be empty.`, "INVALID_CREATION_OPTIONS");
+  if (options.thinking !== undefined && !["none", "minimal", "low", "medium", "high", "xhigh", "max", "ultra"].includes(options.thinking)) throw failure("Invalid --thinking.", "INVALID_CREATION_OPTIONS");
+  const timeoutMs = options.timeoutMs ?? 120000;
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) throw failure("--timeout-ms must be 1000..600000.", "INVALID_CREATION_OPTIONS");
+  return { timeoutMs, ...Object.fromEntries(["title", "model", "thinking"].filter(key => options[key] !== undefined).map(key => [key, options[key]])) };
+}
+
+export function validateNativeCreationCatalog(catalog) {
+  const membership = validateMembershipCatalog(catalog);
+  const schemas = ["list_projects", "create_thread"].map(name => catalog?.tools?.find(tool => tool.name === name && tool.namespace === "codex_app")?.inputSchema);
+  const creation = schemas[1], project = creation?.properties?.target?.anyOf?.find(target => target.properties?.type?.enum?.includes("project"));
+  const local = project?.properties?.environment?.anyOf?.find(environment => environment.properties?.type?.enum?.includes("local"));
+  if (schemas[0]?.type !== "object" || creation?.properties?.prompt?.type !== "string" || !creation.required?.includes("prompt") || !creation.required.includes("target") || project?.properties?.projectId?.type !== "string" || !project.required?.includes("projectId") || !local) throw failure("Desktop native tools do not expose the required local creation schema.", "NATIVE_CREATION_UNSUPPORTED");
+  return { status: "verified", source: "desktop-native-schema", schema_sha256: createHash("sha256").update(JSON.stringify([...schemas, membership])).digest("hex") };
+}
+
+export async function createProjectThread(selector, prompt, options = {}, dependencies = {}) {
+  const settings = creationOptions(options);
+  if (typeof selector !== "string" || !selector.trim()) throw failure("--project is required.", "PROJECT_REQUIRED");
+  if (typeof prompt !== "string" || !prompt.trim()) throw failure("An initial instruction is required.", "INITIAL_INSTRUCTION_REQUIRED");
+  // An environment variable must not silently turn standalone user work into
+  // delegated work or inherit another task's permissions.
+  if (options.contextThread === undefined) return createStandaloneProjectThread(selector, prompt, { ...settings, dryRun: !!options.dryRun }, dependencies);
+  const {
+  discover = discoverRuntime, connect = RpcClient.connect, aliases = projectAliases,
+  endpoint = discoverNativeEndpoint, inspectEndpoint = inspectNativeEndpoint, inspectCommand = inspectNativeCommandProtocol, native,
+  workspace = projectWorkspace, caller = readSendState, history = fetchThread,
+  membership = desktopMembership, write = writeRecord, sleep = delay,
+  } = dependencies;
+  const sourceId = options.contextThread;
+  const contextId = normalizeThreadId(sourceId), attemptId = randomUUID();
+  let client, receipt, storage, dispatched = false, accepted = false;
+  try {
+    const { paths, state } = await discover(); storage = { home: paths.home };
+    assertRuntimeOperation(state, "read");
+    const nativeEndpoint = await endpoint(state);
+    const commandProtocol = await inspectCommand(state);
+    client = compatibleClient(await connect(paths.socket, { timeoutMs: settings.timeoutMs + 5000 }), state);
+    const invokeNative = native ?? ((...args) => nativeOnAppServer(client, ...args));
+    const source = await caller(client, contextId), turn = source.turns.at(-1);
+    if (!turn?.id || source.ephemeral || source.environments?.some(environment => environment.environmentId !== "local")) throw failure("A local, persisted caller chat with a stored turn is required.", "CREATION_CONTEXT_INVALID");
+    const context = { threadId: contextId, turnId: turn.id }, nativeOptions = { timeoutMs: settings.timeoutMs };
+    const protocol = { ...validateNativeCreationCatalog(await invokeNative(nativeEndpoint, "catalog", undefined, undefined, nativeOptions)), command: commandProtocol };
+    const mapping = await aliases(paths.home), project = resolveProject(await projectsOnClient(client), selector, mapping), scope = await workspace(project);
+    const listNative = async () => {
+      const inventory = nativeToolJson(await invokeNative(nativeEndpoint, "list_projects", {}, context, nativeOptions));
+      if (!Array.isArray(inventory.projects)) throw failure("Desktop returned an invalid project catalog.", "NATIVE_PROTOCOL_ERROR");
+      const matches = inventory.projects.filter(item => item.projectKind === "local" && item.hostId === "local" && (mapping[item.projectId] === project.id || item.projectId === project.id));
+      if (matches.length !== 1 || matches[0].label !== project.name || matches[0].path !== project.roots[0].path) throw failure("Selected App Server project does not match exactly one native Desktop project.", "DESKTOP_PROJECT_MAPPING_UNVERIFIED");
+      return matches[0];
+    };
+    const selected = await listNative();
+    const check = async () => {
+      const current = await discover();
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || current.state.cli_version !== state.cli_version) throw failure("Runtime changed. Inspect the receipt before retrying.", "RUNTIME_CHANGED");
+      await inspectEndpoint(nativeEndpoint.socketPath, nativeEndpoint.fingerprint);
+      const live = validateProject((await client.request("project/read", { projectId: project.id })).project);
+      if (!isDeepStrictEqual(live.roots, project.roots) || live.name !== project.name) throw failure("Project source folders changed before creation.", "PROJECT_CHANGED");
+      if ((await listNative()).projectId !== selected.projectId) throw failure("Native project changed before creation.", "PROJECT_CHANGED");
+    };
+    await check();
+    receipt = { schema: 2, creation_mode: "delegated", attempt_id: attemptId, native_call_id: attemptId, project_id: project.id, desktop_project_id: selected.projectId, project_name: project.name,
+      context_thread_id: contextId, context_turn_id: turn.id, cwd: scope.cwd, runtime_workspace_roots: scope.runtimeWorkspaceRoots,
+      title: settings.title ?? null, backend: "desktop-native-rpc", connection_mode: "shared", protocol, creation_status: "not_created", sent: false, delivery_status: "not_sent",
+      verification_status: "not_started", message_characters: [...prompt].length, prompt_sha256: createHash("sha256").update(prompt).digest("hex"), dry_run: !!options.dryRun };
+    if (options.dryRun) return receipt;
+    receipt.receipt_path = storePath("creations", attemptId, paths.home);
+    await write("creations", attemptId, { ...receipt, creation_status: "dispatching" }, storage);
+    await check();
+    dispatched = true;
+    const args = { prompt, target: { type: "project", projectId: selected.projectId, environment: { type: "local" } }, ...Object.fromEntries(["title", "model", "thinking"].filter(key => settings[key] !== undefined).map(key => [key, settings[key]])) };
+    const raw = await invokeNative(nativeEndpoint, "create_thread", args, context, { ...nativeOptions, callId: attemptId });
+    if (raw.native_request_cleanup_required) receipt.native_request_cleanup_required = true;
+    const result = nativeToolJson(raw);
+    const id = result.threadId ?? (result.status === "created" ? result.conversationId : undefined);
+    if (!id) throw Object.assign(failure("Native creation returned no child ID. Do not retry automatically.", "NATIVE_CREATION_UNKNOWN"), { uncertain: true });
+    const threadId = normalizeThreadId(id);
+    accepted = !!result.threadId || result.firstTurn?.status === "accepted";
+    Object.assign(receipt, { thread_id: threadId, deep_link: threadDeepLink(threadId), creation_status: "created", sent: accepted ? true : null, delivery_status: accepted ? "accepted" : "unknown" });
+    await write("creations", attemptId, receipt, storage);
+    if (!accepted) throw failure("Child exists but its initial turn was not confirmed. Inspect the child before resending.", "INITIAL_TURN_UNCONFIRMED");
+    const thread = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    if (thread?.id !== threadId || thread.cwd !== scope.cwd || !await membership(invokeNative, nativeEndpoint, threadId, selected.projectId, context, nativeOptions)) throw failure("Created child did not confirm the selected Desktop project.", "DESKTOP_MEMBERSHIP_MISMATCH");
+    const roots = thread.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
+    if (!Array.isArray(roots) || roots.length !== scope.runtimeWorkspaceRoots.length || !scope.runtimeWorkspaceRoots.every(root => roots.includes(root))) throw failure("Created child did not confirm all project source folders.", "CREATION_SCOPE_MISMATCH");
+    let saved = await history(client, threadId), named = thread;
+    // Native acceptance can precede the first input's persisted history item.
+    // Wait only for read-side materialization; never repeat create or turn/start.
+    const ready = () => saved.turns?.[0]?.items?.some(item => item.type === "userMessage" || (item.type === "functionCallOutput" && item.namespace === "codex_app" && item.name === "create_thread"));
+    for (let retry = 0; retry < 20 && (!ready() || (settings.title !== undefined && named.name == null)); retry++) {
+      await sleep(250);
+      saved = await history(client, threadId);
+      named = (await client.request("thread/read", { threadId, includeTurns: false })).thread;
+    }
+    if (!initialInstructionMatches(saved, prompt, contextId) || (settings.title !== undefined && named.name !== settings.title)) throw failure("Created child did not preserve the initial instruction/title.", "CREATION_INSTRUCTION_MISMATCH");
+    if (thread.projectId !== project.id) await client.request("thread/metadata/update", { threadId, projectId: project.id }, { mutation: true });
+    if ((await client.request("thread/read", { threadId, includeTurns: false })).thread?.projectId !== project.id) throw failure("Canonical project assignment was not confirmed.", "CREATION_SCOPE_MISMATCH");
+    Object.assign(receipt, { verification_status: "verified", desktop_project_membership: "verified", app_server_project_membership: "verified", initial_instruction: "verified", desktop_subscription: "native-owned" });
+    try { await write("creations", attemptId, receipt, storage); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  } catch (error) {
+    const created = !!receipt?.thread_id, unknown = !accepted && (created || (dispatched && mutationOutcomeUnknown(error)));
+    Object.assign(error, { attempt_id: attemptId, native_call_id: attemptId, thread_id: receipt?.thread_id, receipt_path: receipt?.receipt_path,
+      creation_status: created ? "created" : unknown ? "unknown" : "not_created", sent: accepted ? true : unknown ? null : false, delivery_status: accepted ? "accepted" : unknown ? "unknown" : "not_sent" });
+    if (receipt?.receipt_path) try { await write("creations", attemptId, { ...receipt, creation_status: error.creation_status, sent: error.sent, delivery_status: error.delivery_status, verification_status: "failed", error_code: error.code ?? "CREATION_FAILED" }, storage); } catch { error.receipt_update_required = true; }
+    throw error;
+  } finally { try { client?.close(); } catch { if (accepted && receipt) receipt.runtime_cleanup_required = true; } }
+}

package/src/thread-id.mjs

@@ -1,11 +1,12 @@
+import { targetHost, validateHostId } from "./target.mjs";
 const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-export function normalizeThreadId(input) {
+export function parseThreadTarget(input) {
   if (typeof input !== "string" || input.trim() === "") {
     throw new Error("Thread ID is required.");
   }
 
-  let value = input.trim();
+  let value = input.trim(), hostId;
   if (value.startsWith("codex://")) {
     let url;
     try {
@@ -16,20 +17,34 @@ export function normalizeThreadId(input) {
     if (url.hostname !== "threads") {
       throw new Error(`Expected codex://threads/<thread-id>: ${input}`);
     }
+    const hosts = url.searchParams.getAll("hostId");
+    if (hosts.length > 1) throw new Error("A thread link must have only one hostId.");
+    if (hosts.length) hostId = validateHostId(hosts[0]);
     value = decodeURIComponent(url.pathname.replace(/^\/+/, ""));
   }
 
   if (!UUID_PATTERN.test(value)) {
     throw new Error(`Invalid local Codex thread ID: ${input}`);
   }
-  return value.toLowerCase();
+  return { threadId: value.toLowerCase(), hostId };
+}
+
+export function normalizeThreadId(input) {
+  const { threadId, hostId } = parseThreadTarget(input);
+  if (hostId !== undefined && hostId !== targetHost()) {
+    throw Object.assign(new Error("Thread link belongs to another host. Select its host with --host or the host-aware CLI entry point."), { code: "HOST_MISMATCH" });
+  }
+  return threadId;
 }
 
 export function threadDeepLink(threadId) {
-  return `codex://threads/${normalizeThreadId(threadId)}`;
+  const target = parseThreadTarget(threadId), host = target.hostId ?? targetHost();
+  const link = `codex://threads/${target.threadId}`;
+  return host === "local" ? link : `${link}?${new URLSearchParams({ hostId: host })}`;
 }
 
 export function threadComposerDeepLink(threadId, prompt = "") {
-  const query = new URLSearchParams({ prompt });
-  return `${threadDeepLink(threadId)}?${query}`;
+  const link = new URL(threadDeepLink(threadId));
+  link.searchParams.set("prompt", prompt);
+  return link.toString();
 }

package/src/thread-verify.mjs

@@ -0,0 +1,108 @@
+import { createHash } from "node:crypto";
+import path from "node:path";
+import { discoverRuntime } from "./runtime.mjs";
+import { RpcClient } from "./rpc.mjs";
+import { assertRuntimeOperation, compatibleClient } from "./compatibility.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { projectAliases, projectWorkspace, validateProject } from "./projects.mjs";
+import { fetchThread } from "./observe.mjs";
+import { discoverNativeEndpoint, inspectNativeEndpoint } from "./native-rpc.mjs";
+import { nativeOnAppServer, inspectNativeCommandProtocol } from "./native-command.mjs";
+import { desktopMembership, initialInstructionText, validateMembershipCatalog } from "./creation-verification.mjs";
+import { readRecord, writeRecord, storePath, withStoreLock } from "./store.mjs";
+
+const failure = (message, code = "CREATION_VERIFICATION_FAILED") => Object.assign(new Error(message), { code });
+const sameRoots = (actual, expected) => Array.isArray(actual) && actual.length === expected.length && expected.every(root => actual.includes(root));
+const text = value => typeof value === "string" && !!value.trim();
+
+function validateReceipt(receipt, attemptId) {
+  if (!receipt || receipt.attempt_id !== attemptId || receipt.dry_run
+    || !((receipt.schema === 3 && receipt.creation_mode === "standalone") || (receipt.schema === 2 && receipt.creation_mode === "delegated"))
+    || receipt.creation_status !== "created" || receipt.sent !== true || receipt.delivery_status !== "accepted"
+    || !text(receipt.thread_id) || normalizeThreadId(receipt.thread_id) !== receipt.thread_id
+    || !text(receipt.project_id) || !text(receipt.desktop_project_id) || !text(receipt.cwd) || !path.isAbsolute(receipt.cwd)
+    || !Array.isArray(receipt.runtime_workspace_roots) || !receipt.runtime_workspace_roots.length
+    || receipt.runtime_workspace_roots.some(root => !text(root) || !path.isAbsolute(root))
+    || new Set(receipt.runtime_workspace_roots).size !== receipt.runtime_workspace_roots.length
+    || !/^[a-f0-9]{64}$/.test(receipt.prompt_sha256 ?? "") || !Number.isSafeInteger(receipt.message_characters) || receipt.message_characters < 1
+    || (receipt.creation_mode === "standalone" ? !text(receipt.turn_id) || !text(receipt.title) : !text(receipt.context_thread_id))) {
+    throw failure("A valid created/accepted receipt is required. Inspect the existing task; this command never creates or resends.", "CREATION_RECEIPT_UNVERIFIED");
+  }
+}
+
+// Recovery of a known created/accepted attempt. Only the codexteer receipt is
+// written. No create, subscribe, move, metadata update, start or steer API is
+// available in this operation; native access is restricted to two read tools.
+export async function verifyProjectThread(attempt, { timeoutMs = 120000 } = {}, {
+  discover = discoverRuntime, connect = RpcClient.connect, aliases = projectAliases,
+  endpoint = discoverNativeEndpoint, inspectEndpoint = inspectNativeEndpoint, inspectCommand = inspectNativeCommandProtocol, native,
+  workspace = projectWorkspace, history = fetchThread, membership = desktopMembership,
+  read = readRecord, write = writeRecord, lock = withStoreLock,
+} = {}) {
+  const attemptId = normalizeThreadId(attempt);
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 1000 || timeoutMs > 600000) throw failure("--timeout-ms must be 1000..600000.", "INVALID_CREATION_OPTIONS");
+  const { paths, state } = await discover(), storage = { home: paths.home };
+  assertRuntimeOperation(state, "read");
+  return lock(`creation-${attemptId}`, async () => {
+    const receipt = await read("creations", attemptId, storage);
+    validateReceipt(receipt, attemptId);
+    let client;
+    try {
+      const nativeEndpoint = await endpoint(state);
+      await inspectCommand(state);
+      client = compatibleClient(await connect(paths.socket, { timeoutMs: timeoutMs + 5000 }), state);
+      const invoke = native ?? ((...args) => nativeOnAppServer(client, ...args));
+      const readNative = (...args) => {
+        if (!["catalog", "list_threads"].includes(args[1])) throw failure("Verification permits only native reads.");
+        return invoke(...args);
+      };
+      validateMembershipCatalog(await readNative(nativeEndpoint, "catalog", undefined, undefined, { timeoutMs }));
+      const project = validateProject((await client.request("project/read", { projectId: receipt.project_id })).project);
+      const scope = await workspace(project, receipt.cwd);
+      const thread = (await client.request("thread/read", { threadId: receipt.thread_id, includeTurns: false })).thread;
+      const saved = await history(client, receipt.thread_id), first = saved.turns?.[0];
+      const instruction = initialInstructionText(saved, receipt.creation_mode === "delegated" ? receipt.context_thread_id : undefined);
+      const roots = thread?.environments?.find(environment => environment.environmentId === "local")?.runtimeWorkspaceRoots;
+      const checks = {
+        thread_id: thread?.id === receipt.thread_id,
+        project_mapping: (await aliases(paths.home))[receipt.desktop_project_id] === receipt.project_id,
+        project_roots: project.id === receipt.project_id && sameRoots(scope.runtimeWorkspaceRoots, receipt.runtime_workspace_roots),
+        canonical_project_id: thread?.projectId === receipt.project_id,
+        cwd: thread?.cwd === receipt.cwd && scope.cwd === receipt.cwd,
+        roots: sameRoots(roots, receipt.runtime_workspace_roots),
+        title: receipt.title == null || thread?.name === receipt.title,
+        initial_turn: text(first?.id) && (receipt.creation_mode !== "standalone" || first.id === receipt.turn_id),
+        initial_instruction: typeof instruction === "string" && [...instruction].length === receipt.message_characters
+          && createHash("sha256").update(instruction).digest("hex") === receipt.prompt_sha256,
+        desktop_membership: text(first?.id) && await membership(readNative, nativeEndpoint, receipt.thread_id, receipt.desktop_project_id,
+          { threadId: receipt.thread_id, turnId: first.id }, { timeoutMs }),
+      };
+      const current = await discover(); assertRuntimeOperation(current.state, "read");
+      if (current.state.instance !== state.instance || current.paths.socket !== paths.socket || current.paths.home !== paths.home || current.state.cli_version !== state.cli_version) {
+        throw failure("Runtime changed during verification. No task was changed.", "RUNTIME_CHANGED");
+      }
+      await inspectEndpoint(nativeEndpoint.socketPath, nativeEndpoint.fingerprint);
+      const verified = Object.values(checks).every(value => value === true), status = verified ? "verified" : "failed";
+      const updated = { ...receipt, receipt_path: storePath("creations", attemptId, paths.home), verification_status: status,
+        verification_history: [...(receipt.verification_history ?? []), { checked_at: new Date().toISOString(), status, checks,
+          source: "desktop-native-list_threads", desktop_reads_only: true,
+          previous_status: receipt.verification_status, ...(receipt.error_code ? { previous_error_code: receipt.error_code } : {}) }] };
+      if (verified) {
+        Object.assign(updated, { desktop_project_membership: "verified", app_server_project_membership: "verified", initial_instruction: "verified" });
+        delete updated.error_code;
+      } else {
+        updated.error_code = "CREATION_VERIFICATION_FAILED";
+        // Never leave earlier certification flags on a failed fresh check.
+        delete updated.desktop_project_membership; delete updated.app_server_project_membership; delete updated.initial_instruction;
+      }
+      try { await write("creations", attemptId, updated, storage); }
+      catch { throw Object.assign(failure("Verification finished but its receipt could not be saved. Do not recreate or resend.", "CREATION_RECEIPT_UPDATE_FAILED"), { receipt_update_required: true, verification_checks: checks }); }
+      if (!verified) throw Object.assign(failure("Existing task did not pass all creation checks. No task was changed; do not recreate or resend."), { verification_checks: checks });
+      return updated;
+    } catch (error) {
+      Object.assign(error, { attempt_id: attemptId, thread_id: receipt.thread_id, creation_status: receipt.creation_status,
+        sent: receipt.sent, delivery_status: receipt.delivery_status, receipt_path: storePath("creations", attemptId, paths.home) });
+      throw error;
+    } finally { client?.close(); }
+  }, storage);
+}

package/src/turn-repair.mjs

@@ -0,0 +1,228 @@
+import { createHash, randomUUID } from "node:crypto";
+import { constants } from "node:fs";
+import { copyFile, lstat, mkdir, open, readdir, realpath, rename } from "node:fs/promises";
+import { execFileSync } from "node:child_process";
+import path from "node:path";
+import { codexHome } from "./runtime.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { withStoreLock } from "./store.mjs";
+import { BUNDLED_CLI } from "./wrapper.mjs";
+
+// This is an offline rollout-format repair, not an App Server interrupt API.
+// Only enable a version after the isolated replay test has verified its parser.
+export const REPAIR_CLI_VERSIONS = Object.freeze(["0.162.0-alpha.17.2", "0.164.0-alpha.11.1"]);
+const failure = (message, code) => Object.assign(new Error(message), { code });
+const invalid = message => failure(message, "REPAIR_HISTORY_UNSUPPORTED");
+const stamp = s => [s.dev, s.ino, s.size, s.mtimeMs, s.ctimeMs].join(":");
+const identity = s => [s.dev, s.ino, s.size, s.uid, s.gid, s.mode, s.nlink].join(":");
+const uuid = value => typeof value === "string" && /^[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}$/.test(value);
+
+async function owned(file, directory = false) {
+  const s = await lstat(file);
+  if (s.isSymbolicLink() || s.uid !== process.getuid() || (s.mode & 0o022)
+    || (directory ? !s.isDirectory() : !s.isFile() || s.nlink !== 1)) {
+    throw failure("Unsafe history path, ownership, permissions, or hard link.", "REPAIR_UNSAFE_PATH");
+  }
+  return s;
+}
+
+export async function findRepairRollout(home, threadId) {
+  const found = [];
+  async function walk(dir) {
+    await owned(dir, true);
+    for (const entry of await readdir(dir, { withFileTypes: true })) {
+      const file = path.join(dir, entry.name);
+      if (entry.name.endsWith(`-${threadId}.jsonl`)) { await owned(file); found.push(file); }
+      else if (entry.isDirectory()) await walk(file);
+      else if (entry.isSymbolicLink()) throw failure("A history directory contains a symbolic link; inspect it before repair.", "REPAIR_UNSAFE_PATH");
+    }
+  }
+  for (const root of ["sessions", "archived_sessions"]) {
+    try { await walk(path.join(home, root)); } catch (e) { if (e.code !== "ENOENT") throw e; }
+  }
+  if (found.length !== 1) throw failure(`Expected one rollout for this thread; found ${found.length}.`, "REPAIR_ROLLOUT_AMBIGUOUS");
+  return found[0];
+}
+
+// Stream JSONL, parsing each record transiently. Return turn metadata and hashes,
+// without including conversation item contents in the inspection report.
+export async function scanRepairRollout(file, threadId) {
+  const before = await owned(file), handle = await open(file, constants.O_RDONLY | constants.O_NOFOLLOW);
+  const hash = createHash("sha256"), turns = new Map();
+  let carry = Buffer.alloc(0), ordinal = 0, metadata, lastRoot;
+  const parse = line => {
+    let r;
+    try { r = JSON.parse(line.toString("utf8")); } catch { throw invalid("History contains invalid JSON; nothing can be repaired automatically."); }
+    if (r.ordinal !== ordinal++) throw invalid("History ordinals are missing or discontinuous.");
+    if (ordinal === 1) {
+      if (r.type !== "session_meta" || r.payload?.id !== threadId || r.payload?.history_mode !== "paginated") throw invalid("Repair requires this thread's paginated rollout metadata.");
+      metadata = r.payload;
+    } else if (r.type === "session_meta") throw invalid("Multiple session metadata records are not supported.");
+    if (r.type !== "event_msg") return;
+    const p = r.payload;
+    if (p?.type === "task_started") {
+      if (!uuid(p.turn_id) || turns.has(p.turn_id)) throw invalid("Repeated or unidentified turn starts cannot be repaired automatically.");
+      const independent = (p.root_turn_id == null || p.root_turn_id === p.turn_id)
+        && (!p.turn_attribution || (p.turn_attribution.turn_id === p.turn_id && (p.turn_attribution.root_turn_id == null || p.turn_attribution.root_turn_id === p.turn_id) && p.turn_attribution.parent_turn_id == null));
+      const turn = { turn_id: p.turn_id, start_ordinal: r.ordinal, started_at: p.started_at ?? null, successor_id: null, terminal: null, independent };
+      if (independent) { if (lastRoot) lastRoot.successor_id = p.turn_id; lastRoot = turn; }
+      turns.set(p.turn_id, turn);
+    } else if (["task_complete", "turn_aborted"].includes(p?.type)) {
+      const t = turns.get(p.turn_id);
+      if (!t || t.terminal) throw invalid("Unmatched or repeated terminal records need manual inspection.");
+      t.terminal = p.type;
+    }
+  };
+  try {
+    if (stamp(await handle.stat()) !== stamp(before)) throw failure("History changed before inspection.", "REPAIR_HISTORY_CHANGED");
+    for await (const chunk of handle.createReadStream({ autoClose: false, highWaterMark: 1024 * 1024 })) {
+      hash.update(chunk);
+      const buffer = carry.length ? Buffer.concat([carry, chunk]) : chunk;
+      let from = 0, end;
+      while ((end = buffer.indexOf(10, from)) !== -1) {
+        if (end - from > 64 * 1024 * 1024) throw invalid("A history record exceeds the repair size limit.");
+        parse(buffer.subarray(from, end)); from = end + 1;
+      }
+      carry = Buffer.from(buffer.subarray(from));
+      if (carry.length > 64 * 1024 * 1024) throw invalid("A history record exceeds the repair size limit.");
+    }
+    if (carry.length || !metadata) throw invalid("History is empty or ends with an incomplete record. Nothing was changed.");
+    if (stamp(await handle.stat()) !== stamp(before) || stamp(await owned(file)) !== stamp(before)) throw failure("History changed during inspection. Retry after work has stopped.", "REPAIR_HISTORY_CHANGED");
+    const unclosed = [...turns.values()].filter(t => !t.terminal);
+    return { file, thread_id: threadId, source: before, sha256: hash.copy().digest("hex"), hash,
+      next_ordinal: ordinal, candidates: unclosed.filter(t => t.independent && t.successor_id), unresolved_latest: unclosed.filter(t => !t.successor_id) };
+  } finally { await handle.close(); }
+}
+
+export function repairProcessBlockers(stdout) {
+  if (!stdout.trim()) throw failure("Empty process inventory; repair is blocked.", "REPAIR_OFFLINE_UNVERIFIED");
+  return stdout.split("\n").filter(Boolean).flatMap(line => {
+    const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+    if (!match) throw failure("Cannot parse process inventory; repair is blocked.", "REPAIR_OFFLINE_UNVERIFIED");
+    const name = path.basename(match[2].trim());
+    return /^(?:codex(?:[-_].*)?|chatgpt|codex desktop)$/i.test(name) ? [{ pid: Number(match[1]), executable: name }] : [];
+  });
+}
+
+export function requireRepairOffline() {
+  if (process.platform !== "darwin") throw failure("Offline repair is currently verified on macOS only.", "REPAIR_OFFLINE_UNVERIFIED");
+  let output;
+  try { output = execFileSync("/bin/ps", ["-axo", "pid=,comm="], { encoding: "utf8", timeout: 5000, maxBuffer: 4 * 1024 * 1024 }); }
+  catch { throw failure("Cannot inspect processes. Run repair from an external terminal after quitting Codex.", "REPAIR_OFFLINE_UNVERIFIED"); }
+  const blockers = repairProcessBlockers(output);
+  if (blockers.length) throw failure(`Quit Codex/ChatGPT and all Codex CLI/app-server processes first (${blockers.map(p => `${p.executable} PID ${p.pid}`).join(", ")}). Run --apply from an external terminal; this command does not stop them.`, "REPAIR_REQUIRES_OFFLINE");
+}
+
+export function repairRuntimeVersion() {
+  let version;
+  try { version = execFileSync(BUNDLED_CLI, ["--version"], { encoding: "utf8", timeout: 5000 }).trim().replace(/^codex-cli /, ""); }
+  catch { throw failure("Cannot verify the bundled Codex parser version.", "REPAIR_RUNTIME_UNVERIFIED"); }
+  if (!REPAIR_CLI_VERSIONS.includes(version)) throw failure(`Offline repair has not been verified with Codex ${version}. No history was changed.`, "REPAIR_RUNTIME_UNVERIFIED");
+  return version;
+}
+
+function report(scan, apply) {
+  return { thread_id: scan.thread_id, rollout_path: scan.file, mode: apply ? "apply" : "dry-run", status: scan.candidates.length ? "residual_candidates" : "no_residual_candidates",
+    candidates: scan.candidates, unresolved_latest: scan.unresolved_latest, source_sha256: scan.sha256,
+    history_changed: false, verification: "persisted-rollout-only", requires_offline: true,
+    note: "Candidates have a later top-level turn start and no terminal record. The latest unfinished turn is never repaired. Live API idle/interrupted alone does not prove persisted repair." };
+}
+
+async function privateDirectory(dir) {
+  await mkdir(dir, { mode: 0o700 }).catch(e => { if (e.code !== "EEXIST") throw e; });
+  const s = await owned(dir, true);
+  if (s.mode & 0o077) throw failure("Repair backup directories must be private (0700).", "REPAIR_UNSAFE_PATH");
+}
+
+async function saveManifest(file, data) {
+  const temp = `${file}.tmp`;
+  const h = await open(temp, "wx", 0o600);
+  try { await h.writeFile(JSON.stringify(data, null, 2) + "\n"); await h.sync(); } finally { await h.close(); }
+  await rename(temp, file);
+}
+
+// Opening a writable descriptor can coincide with metadata-only changes (for
+// example filesystem/provenance bookkeeping). A timestamp mismatch alone does
+// not establish a content change. Hash the exact descriptor we will append to,
+// while requiring stable identity, permissions and metadata throughout the read.
+export async function verifyRepairAppendHandle(handle, file, scan) {
+  const before = await handle.stat(), pathBefore = await owned(file);
+  const details = { expected: stamp(scan.source), descriptor: stamp(before), path: stamp(pathBefore) };
+  const changed = message => Object.assign(failure(message, "REPAIR_HISTORY_CHANGED"), { repair_stat: details });
+  if (identity(before) !== identity(scan.source) || identity(pathBefore) !== identity(scan.source) || stamp(before) !== stamp(pathBefore)) {
+    throw changed("History identity, size or permissions changed before append.");
+  }
+  const hash = createHash("sha256");
+  for await (const chunk of handle.createReadStream({ start: 0, autoClose: false, highWaterMark: 1024 * 1024 })) hash.update(chunk);
+  if (hash.digest("hex") !== scan.sha256) throw changed("History contents changed before append.");
+  const after = await handle.stat(), pathAfter = await owned(file);
+  if (stamp(after) !== stamp(before) || stamp(pathAfter) !== stamp(before) || identity(after) !== identity(before) || identity(pathAfter) !== identity(before)) {
+    throw changed("History changed while verifying the append descriptor.");
+  }
+  return { source: after, metadata_revalidated: stamp(before) !== stamp(scan.source) };
+}
+
+const openAppendHandle = file => open(file, constants.O_RDWR | constants.O_APPEND | constants.O_NOFOLLOW);
+
+export async function repairTurns(threadInput, { apply = false, home = codexHome() } = {},
+  { offline = requireRepairOffline, runtimeVersion = repairRuntimeVersion, now = () => new Date(), openForAppend = openAppendHandle } = {}) {
+  const threadId = normalizeThreadId(threadInput);
+  home = await realpath(home); await owned(home, true);
+  if (apply) { await offline(); await runtimeVersion(); }
+  const work = async () => {
+    const file = await findRepairRollout(home, threadId), scan = await scanRepairRollout(file, threadId), data = report(scan, apply);
+    if (!apply || !scan.candidates.length) return data;
+    // The trailing live/unfinished turn needs its own proper shutdown first.
+    if (scan.unresolved_latest.length) throw failure("The latest turn also lacks a terminal record. Stop it normally before repairing older turns.", "REPAIR_LATEST_UNFINISHED");
+    await offline();
+    const version = await runtimeVersion(), repairedAt = now().toISOString();
+    const append = Buffer.from(scan.candidates.map((t, i) => JSON.stringify({ timestamp: repairedAt, ordinal: scan.next_ordinal + i, type: "event_msg",
+      payload: { type: "turn_aborted", turn_id: t.turn_id, root_turn_id: t.turn_id, reason: "interrupted", ...(t.started_at == null ? {} : { started_at: t.started_at }) },
+    })).join("\n") + "\n");
+    // Do not invent completed_at/duration_ms: the historical stop time is unknown.
+    const expectedHash = scan.hash.copy().update(append).digest("hex");
+    const root = path.join(home, "codex-steer"), backups = path.join(root, "turn-repairs");
+    await privateDirectory(root); await privateDirectory(backups);
+    const directory = path.join(backups, randomUUID()); await privateDirectory(directory);
+    const backup = path.join(directory, "rollout.jsonl"), manifestFile = path.join(directory, "repair.json");
+    await copyFile(file, backup, constants.COPYFILE_EXCL | constants.COPYFILE_FICLONE);
+    const backupHandle = await open(backup, "r+");
+    try { await backupHandle.chmod(0o600); await backupHandle.sync(); } finally { await backupHandle.close(); }
+    const saved = await scanRepairRollout(backup, threadId);
+    if (saved.sha256 !== scan.sha256) throw failure("Backup does not match inspected history. Original history was not changed.", "REPAIR_HISTORY_CHANGED");
+    const manifest = { schema: 1, thread_id: threadId, rollout_path: file, backup_path: backup, repaired_at: repairedAt, cli_version: version,
+      original_sha256: scan.sha256, expected_sha256: expectedHash, original_bytes: scan.source.size, append_utf8: append.toString("utf8"),
+      repaired_turn_ids: scan.candidates.map(t => t.turn_id), status: "prepared" };
+    await saveManifest(manifestFile, manifest);
+    const dirHandle = await open(directory, "r"); try { await dirHandle.sync(); } finally { await dirHandle.close(); }
+    let changed = false;
+    try {
+      await offline();
+      if (await runtimeVersion() !== version || stamp(await owned(file)) !== stamp(scan.source)) throw failure("Runtime or history changed before repair.", "REPAIR_HISTORY_CHANGED");
+      const h = await openForAppend(file);
+      try {
+        const verified = await verifyRepairAppendHandle(h, file, scan);
+        // Hashing a large rollout takes time. Recheck process liveness and the
+        // exact file immediately before the write, not just before the hash.
+        await offline();
+        if (stamp(await h.stat()) !== stamp(verified.source) || stamp(await owned(file)) !== stamp(verified.source)) throw failure("History changed after append verification.", "REPAIR_HISTORY_CHANGED");
+        manifest.append_descriptor_sha256_verified = true;
+        manifest.metadata_revalidated = verified.metadata_revalidated;
+        changed = true; // A partial write is also a mutation and must be reported.
+        await h.writeFile(append); await h.sync();
+      } finally { await h.close(); }
+      await offline();
+      const after = await scanRepairRollout(file, threadId);
+      if (after.sha256 !== expectedHash || after.candidates.length || after.unresolved_latest.length) throw failure("Post-repair history differs from the expected append. Inspect the backup and history before restarting Codex.", "REPAIR_VERIFICATION_FAILED");
+      manifest.status = "verified"; await saveManifest(manifestFile, manifest);
+      return { ...data, status: "repaired", history_changed: true, repaired_turn_ids: manifest.repaired_turn_ids,
+        backup_path: backup, receipt_path: manifestFile, repaired_sha256: expectedHash, verification: "append-and-sha256-verified",
+        note: "Missing terminal records were appended; prior bytes and ordinals are unchanged. Codex will project them on reload. Desktop rendering and the next live turn still need verification. Read/watch cursors should be refreshed." };
+    } catch (e) {
+      e.history_changed = changed; e.backup_path = backup; e.receipt_path = manifestFile;
+      e.message += ` Backup: ${backup}. Do not retry or overwrite history blindly.`;
+      throw e;
+    }
+  };
+  return apply ? withStoreLock(`turn-repair-${threadId}`, work, { home }) : work();
+}