codexteer 0.17.0 → 0.18.0

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();
+}

package/src/update.mjs

@@ -0,0 +1,158 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, lstat, readFile, writeFile, rename, rmdir, realpath } from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { setTimeout as delay } from "node:timers/promises";
+import { codexHome } from "./runtime.mjs";
+import { prepareCodexHome, prepareDeployment } from "./distribution.mjs";
+import { APP_PATH, startDesktop, appServerDoctor } from "./launcher.mjs";
+
+const script = fileURLToPath(new URL("../scripts/update-desktop.applescript", import.meta.url));
+const error = (code, message) => Object.assign(new Error(message), { code });
+function run(command, args) {
+  const result = spawnSync(command, args, { encoding: "utf8", timeout: 10000 });
+  if (result.error || result.status !== 0) throw error("UPDATE_COMMAND_FAILED", result.error?.message ?? result.stderr?.trim() ?? `${command} failed`);
+  return result.stdout.trim();
+}
+export function updateUi(operation) { return run("/usr/bin/osascript", [script, operation]); }
+export function updateBuild() {
+  return run("/usr/libexec/PlistBuddy", ["-c", "Print :CFBundleVersion", `${APP_PATH}/Contents/Info.plist`]);
+}
+export function desktopPids() {
+  return run("/bin/ps", ["-axo", "pid=,comm="]).split("\n").flatMap(line => {
+    const match = line.trim().match(/^(\d+)\s+(.+)$/);
+    return match?.[2] === `${APP_PATH}/Contents/MacOS/ChatGPT` ? [Number(match[1])] : [];
+  });
+}
+
+// Separate orchestration from platform effects to exercise restarts/failures without
+// updating the developer's app. No signal-based termination or task resumption.
+export async function performUpdate({ timeoutMs = 600000, initialBuild, initialPids }, {
+  build = updateBuild, pids = desktopPids, ui = updateUi,
+  quit = () => run("/usr/bin/osascript", ["-e", 'tell application id "com.openai.codex" to quit']),
+  start = startDesktop, doctor = appServerDoctor, save = async () => {}, sleep = delay, now = Date.now,
+} = {}) {
+  const deadline = now() + timeoutMs;
+  let lastPhase = "checking", newBuild;
+  await save({ phase: lastPhase, initial_build: initialBuild });
+  await ui("check");
+  while (now() < deadline) {
+    const running = await pids();
+    try { newBuild = await build(); }
+    catch (e) {
+      // Sparkle can temporarily move the bundle away during installation.
+      if (!running.length && ["downloading", "installing"].includes(lastPhase)) { await sleep(1000); continue; }
+      throw e;
+    }
+    // Both the on-disk build and process generation must change before quitting
+    // the relaunched app. Do not interrupt Sparkle's installation or its old app.
+    if (newBuild !== initialBuild && running.length && running.every(pid => !initialPids.includes(pid))) break;
+    if (running.length && newBuild === initialBuild && lastPhase !== "installing") {
+      let phase;
+      try { phase = await ui("advance"); }
+      catch (e) {
+        // The app can exit between the process snapshot and the AX request.
+        if (!(await pids()).length) { await sleep(1000); continue; }
+        throw e;
+      }
+      if (phase === "up_to_date") return { phase, initial_build: initialBuild, final_build: newBuild, wrapper_verified: false };
+      if (["downloading", "installing"].includes(phase) && phase !== lastPhase) {
+        lastPhase = phase; await save({ phase });
+      }
+    }
+    await sleep(1000);
+  }
+  if (now() >= deadline) throw error("UPDATE_TIMEOUT", "Update/relaunch did not complete in time. Inspect Codex or its updater for dialogs. No processes were forcibly stopped.");
+  await save({ phase: "restoring_wrapper", final_build: newBuild });
+  await quit();
+  const quitDeadline = now() + 30000;
+  while ((await pids()).length) {
+    if (now() >= quitDeadline) throw error("UPDATE_QUIT_TIMEOUT", "Codex did not quit normally. Finish its work, quit it, and run codexteer desktop start.");
+    await sleep(500);
+  }
+  await start();
+  const report = await doctor();
+  if (!report.ready || report.connection?.mode !== "shared" || !report.checks?.bundled_wrapper_node || report.cli_version_status !== "matched") {
+    throw error("UPDATE_WRAPPER_UNVERIFIED", "Update installed, but wrapper verification failed. Run codexteer doctor --json.");
+  }
+  return { phase: "complete", initial_build: initialBuild, final_build: newBuild, wrapper_verified: true, doctor: report };
+}
+
+async function privateDirectory(directory) {
+  await mkdir(directory, { mode: 0o700 }).catch(e => { if (e.code !== "EEXIST") throw e; });
+  const info = await lstat(directory);
+  if (!info.isDirectory() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077)) throw error("UPDATE_STATE_UNSAFE", `Unsafe update state directory: ${directory}`);
+}
+async function stateRoot(requestedHome = codexHome()) {
+  const home = await prepareCodexHome(requestedHome);
+  const parent = path.join(home, "codex-steer");
+  await privateDirectory(parent);
+  const root = path.join(parent, "desktop-update");
+  await privateDirectory(root);
+  return { home, root };
+}
+async function writeStatus(root, state) {
+  const temporary = path.join(root, `status-${process.pid}.tmp`);
+  await writeFile(temporary, JSON.stringify({ ...state, updated_at: new Date().toISOString() }) + "\n", { mode: 0o600, flag: "wx" });
+  await rename(temporary, path.join(root, "status.json"));
+}
+export async function desktopUpdateStatus() {
+  const { root } = await stateRoot();
+  try {
+    const file = path.join(root, "status.json"), info = await lstat(file);
+    if (!info.isFile() || info.isSymbolicLink() || info.uid !== process.getuid() || (info.mode & 0o077)) throw error("UPDATE_STATE_UNSAFE", "Unsafe update status file.");
+    const state = JSON.parse(await readFile(file, "utf8"));
+    if (state.worker_pid && !["complete", "up_to_date", "failed"].includes(state.phase)) {
+      try { process.kill(state.worker_pid, 0); state.worker_alive = true; }
+      catch (e) { if (e.code !== "ESRCH") throw e; state.worker_alive = false; }
+    }
+    return state;
+  } catch (e) { if (e.code === "ENOENT") return { phase: "not_started" }; throw e; }
+}
+export async function launchDesktopUpdate({ dryRun = false, timeoutMs = 600000 } = {}, {
+  platform = process.platform, executablePath = process.execPath, pids = desktopPids,
+  ui = updateUi, build = updateBuild, prepare = prepareDeployment, spawnWorker = spawn,
+  home: requestedHome = codexHome(),
+} = {}) {
+  if (!Number.isSafeInteger(timeoutMs) || timeoutMs < 10000 || timeoutMs > 3600000) throw error("UPDATE_ARGUMENT", "--timeout-ms must be an integer between 10000 and 3600000.");
+  if (dryRun) return { dry_run: true, started: false, timeout_ms: timeoutMs, steps: ["official_update_ui", "wait_for_new_build_and_relaunch", "normal_quit", "wrapper_start", "doctor"] };
+  if (platform !== "darwin") throw error("UPDATE_PLATFORM", "Desktop update requires macOS.");
+  if (process.env.CODEX_APP_SERVER_WS_URL?.trim()) throw error("UPDATE_ENVIRONMENT", "Remove CODEX_APP_SERVER_WS_URL before updating with a shared wrapper.");
+  const executable = await realpath(executablePath);
+  if (executable.includes(".app/Contents/")) throw error("UPDATE_NODE", "Run desktop update with an external Node installation, so replacing the app cannot remove the worker runtime.");
+  const initialPids = pids();
+  if (initialPids.length !== 1) throw error("UPDATE_APP_STATE", "Exactly one running Codex Desktop is required.");
+  if (ui("preflight") !== "checking") throw error("UPDATE_UI_UNAVAILABLE", "Codex update menu is unavailable. Allow Accessibility/Automation for your terminal and retry.");
+  const initialBuild = build();
+  const { home, root } = await stateRoot(requestedHome);
+  const deployment = await prepare(home);
+  const lock = path.join(root, "lock");
+  await mkdir(lock, { mode: 0o700 }).catch(e => {
+    if (e.code === "EEXIST") throw error("UPDATE_BUSY", `An update lock exists. Check desktop update-status; if its worker has stopped, inspect the app before manually removing ${lock}.`);
+    throw e;
+  });
+  try {
+    await writeStatus(root, { phase: "starting", initial_build: initialBuild });
+    const child = spawnWorker(executable, [path.join(deployment.directory, "bin/codexteer-update.mjs"), JSON.stringify({ root, timeoutMs, initialBuild, initialPids })], {
+      detached: true, stdio: "ignore", cwd: deployment.directory, env: { ...process.env, CODEX_HOME: home },
+    });
+    await new Promise((resolve, reject) => { child.once("spawn", resolve); child.once("error", reject); });
+    child.unref();
+    return { started: true, worker_pid: child.pid, status_command: "codexteer desktop update-status --json", status_path: path.join(root, "status.json") };
+  } catch (e) { await writeStatus(root, { phase: "failed", error: e.message }); await rmdir(lock); throw e; }
+}
+export async function updateWorker(options) {
+  let state = { phase: "starting", worker_pid: process.pid, initial_build: options.initialBuild };
+  const save = async patch => { state = { ...state, ...patch }; await writeStatus(options.root, state); };
+  try {
+    await save({});
+    const running = desktopPids();
+    if (updateBuild() !== options.initialBuild || running.length !== 1 || running[0] !== options.initialPids[0]) {
+      throw error("UPDATE_APP_CHANGED", "Codex changed after preflight. Inspect its update state before retrying.");
+    }
+    await save(await performUpdate(options, { save }));
+  } catch (e) {
+    await save({ phase: "failed", error: { code: e.code ?? "UPDATE_FAILED", message: e.message }, recovery: "Inspect Codex and the updater. After installation finishes, quit normally and run codexteer desktop start, then codexteer doctor --json." });
+    process.exitCode = 1;
+  } finally { await rmdir(path.join(options.root, "lock")); }
+}

package/docs/thread-create-native-investigation.md

@@ -1,136 +0,0 @@
-# 中継AIなしのDesktopチャット作成経路の調査
-
-実装・直接作成・承認往復の後続結果は[現在の運用と実機検証](thread-create.md)を参照。以下は実装前の調査時点の記録です。
-
-調査日: 2026-10-14 JST。対象はインストール済みDesktop `26.1007.30912` (build `20156`, bundle ID `com.openai.codex`) と同梱CLI `0.162.0-alpha.17.2`。この調査ではチャット作成、指示送信、所属変更、Desktop再起動、実装の置換を行っていない。
-
-## 結論と検証の境界
-
-モデル推論を伴わずにDesktopのnative toolを実行できる接続経路がある。認証されたnative RPCの `tools/list` に `create_thread`、`move_thread_to_project`、`list_projects` が存在し、`tools/call` で `list_projects` を実行できた。追加のAIターンや中継指示は不要だった。
-
-native `create_thread` はDesktop内でプロジェクトの全フォルダを解決し、スケジュールと同じ `threadProjectAssignments.setAssignment` を使って所属を保存する。実装候補は既存Desktop wrapperからこのnative toolを直接呼ぶ方法である。ただし、今回の直接RPC検証は読み取りまで。直接RPCによる作成、所属の実機反映、初回指示、CLI終了後の承認往復は未検証であり、現行のAI中継実装はまだ置換していない。
-
-以前の「複数フォルダ・重複フォルダにはAI中継が必要」という判断は、native RPCの直接呼出しを調べきる前だった。native RPCの存在と読み取り実測により、その判断は修正する必要がある。
-
-## スケジュールが正しい所属になる理由
-
-スケジュールの `Ll` は新しいthreadを作成した後、初回ターン開始前にDesktopの所属サービスを呼ぶ。
-
-```js
-await threadProjectAssignments.setAssignment({
-  threadId,
-  assignment: { projectKind: "local", projectId: project.projectId },
-});
-```
-
-Desktopの所属ストアは `thread-project-assignments` / `projectless-thread-ids` であり、更新時に `thread-project-memberships-updated` を通知する。App Serverのcanonical `projectId` だけを設定する経路と一致しないため、同じcwdを持つ「競馬」と `prediction_model` で分類の差が生じていた。直接global stateを書き換える方法は採用しない。Desktop自身も汎用 `set-global-state` によるこの所属ストアの変更を拒否している。
-
-native toolの作成処理は次の経路を通る。
-
-1. `create_thread` handler (`execution-fde3a4937b6a.js` の `sp`) が引数を検証し、Desktopのチャット作成処理へ渡す。
-2. `sso` → `MZr` が指定したDesktopプロジェクトIDからcwd、全workspace roots、`projectAssignment` を取得する。
-3. `HGi` → manager `startConversation` → `zln` がthreadを作成し、初回ターン前のcallbackで `saveThreadProjectAssignment` を呼ぶ。
-4. このcallbackはDesktop hostの `threadProjectAssignments.setAssignment` を呼び、所属ストアと表示へ反映する。callbackがない構成でも `threadWorkspaceStorage.setProjectAssignment` が同サービスを呼ぶ。
-5. Desktopが初回指示とターン開始を担当する。明示的なsourceThreadIdがあるnative toolでは指示が `codex_delegation` として保存される。
-
-`CAr` はプロジェクト内の手動表示順を保存する処理であり、所属登録の本体ではない。所属登録は上記の `setAssignment`。
-
-native `move_thread_to_project` もDesktopのsidebar移動処理から所属サービスの `setMembership` を呼ぶ。これは既存のApp Server作成経路に所属登録だけ追加する候補だが、作成と移動の部分成功や初回ターンの順序を別に管理する必要がある。
-
-## native RPCと認証
-
-Desktopは子プロセスに `CODEX_APP_TOOLS_PIPE_PATH` を渡す。既存shared wrapperがこの値を継承していることを、選択中wrapperの環境の該当キーだけを読み取って確認した。環境全体や秘密値は出力していない。
-
-native pipeはUnix domain socket。macOSでは長さ4バイトのnative endian (今回LE) + UTF-8 JSONのframeを使い、frame上限は8 MiB。newline JSONのApp Server protocolとは別物である。socketは所有者専用で、接続時にnativeのsocket peer認証が行われる。既存wrapperはDesktop同梱の署名付きNodeを直接使う。認証を無効化・迂回する方法は使っていない。
-
-native serverの `Vae` は `tools/call` を `callDynamicAppTool` に渡す。mainのdispatcherは準備済みDesktop windowを選び、rendererの `canCallTool` / `dispatchToolCall` がnative handlerを実行する。ここに中継AIの推論はない。
-
-```json
-{
-  "id": "request-uuid",
-  "jsonrpc": "2.0",
-  "method": "tools/call",
-  "params": {
-    "arguments": {},
-    "callerSource": "codex",
-    "callId": "unique-call-uuid",
-    "hostId": "local",
-    "namespace": "codex_app",
-    "threadId": "existing-caller-thread-id",
-    "turnId": "actual-stored-caller-turn-id",
-    "tool": "list_projects"
-  }
-}
-```
-
-`threadId` / `turnId` は呼出し元の監査・関連付け用contextであり、モデルを起動するための指示ではない。今回のprobeは実在するチャットとその保存済みターンだけを使用した。架空IDは使用していない。rendererは呼出し元threadを読み込めることを確認し、callIdの実行claimを取る。idleの保存済みターンを使った読み取りも成功したが、作成toolで同じcontextが使えるかは未検証。
-
-`taskProject/assign` という別RPCもあるが、これはWorkのlocal executorの実在environmentIdとthreadのenvironment一致が必要な経路である。通常のCodexチャットに `environmentId: "local"` を付ければ使えるAPIではない。この候補では使用しない。
-
-## 読み取りの実測
-
-一時probe `/private/tmp/codexteer-native-read-probe.mjs` を同梱Node `/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node` で実行した。選択中shared runtimeのプロセス確認とローカルIPC読み取りのみ、sandbox外で実施した。
-
-| 確認 | 結果 |
-| --- | --- |
-| `tools/list` (`threadStartKind: all`) | 57 native tools。作成・所属移動・プロジェクト一覧のschemaを取得 |
-| `tools/call list_projects`、現在の実在activeターン | `success: true`、23プロジェクト |
-| 同呼出し、既存idleチャットの保存済みcompletedターン | `success: true`、23プロジェクト |
-| idleチャットの後続読取り | idle、latest turnは同じcompletedターン、turn数4。新しいターンは発生していない |
-
-idle contextは既存検証チャット `01a135bf-1087-7902-8b78-0fb683b025d6`、保存済みターン `01a135cb-47ba-73a0-befe-6eb41452655e`。現在のcontextはthread `01a135a4-c1ea-7081-be4c-3c5ab7b11193`、turn `01a135d2-9375-78f0-8f39-ced3c29a5d98`。
-
-native一覧は次のDesktop IDを返した。作成先にはnative一覧のIDを使う。App Serverのcanonical IDと混ぜない。
-
-| label | projectKind | Desktop projectId |
-| --- | --- | --- |
-| codex-steer | local | `8b8c19b2-5a36-4683-8b2f-28a489e03724` |
-| 競馬 | local | `ad16728e-81d9-499f-81c8-fdf13f0f9d89` |
-| prediction_model | local | `cad845a7-dfb1-45b8-8503-b9aca1ee89d6` |
-| 競馬 | chatgpt | `g-p-69379d229d7081918b1efb6f5c107d17` |
-
-localの「競馬」と `prediction_model` は両方ともpathが `/Users/phat/Desktop/app_race-calc_h/prediction_model` だが、IDは異なる。同名ChatGPTプロジェクトも存在するので、プロジェクト解決ではkindとIDを確認する。
-
-## codexteerへの組込み候補
-
-```text
-terminal CLI → 共有App Serverのcommand/exec
-  → 固定の署名付きNode helper（thread/turnやモデル推論なし）
-  → Desktop native RPC tools/call create_thread
-  → Desktopでproject roots解決・setAssignment・初回ターン開始
-```
-
-実装時には、wrapper自身のnative接続では署名情報検証に失敗することを確認したため、既存App Serverの正規の子としてhelperを起動する経路を採用した。command/execは独立したコマンド実行APIで、チャットやAIターンを作らない。matching CLI schemaで対応を確認し、固定の署名付きNodeとhelperに限定する。詳細と実測は現在の運用文書を参照。
-
-端末からの呼出しには実在するcaller contextの明示または確実な解決が必要である。context用チャットのモデル起動や追加ターンは不要な見込みだが、作成toolで検証してから契約にする。現在の `--via-thread` のようなAIへのメッセージ配送は廃止候補となる。
-
-nativeの作成引数は以下で、promptと指定プロジェクトをそのまま渡せる。
-
-```json
-{
-  "prompt": "initial instruction",
-  "title": "optional title",
-  "target": {
-    "type": "project",
-    "projectId": "Desktop projectId",
-    "environment": { "type": "local" }
-  }
-}
-```
-
-モデル・thinkingはnative schemaの対応範囲内で指定可能。cwd・sandbox・approval policy等を任意に上書きする引数はこのnative toolにないため、既存CLIのオプションをそのまま対応済みとは扱わない。native経路でDesktopの設定を使うか、所属移動だけを使う別経路が必要。
-
-組込み後の必須検証は、単一フォルダと「競馬」の全7フォルダ、共有cwdでの正しいDesktop所属、初回指示の完全一致、短命CLI終了後のDesktop承認継続・承認往復、途中失敗の同一attemptでの照合である。tool callIdがあることを作成のidempotency保証と解釈せず、不明結果を自動再送しない。
-
-native RPCはこのDesktop内部のversion依存interfaceであり、公開App Server互換契約ではない。wrapperのcapabilityとnative schema/接続を確認し、未対応なら作成前に止める。AI中継へ自動fallbackしない。稼働中wrapperへコードを追加するには対応版で起動し直す必要があるが、この調査では再起動していない。
-
-## 調査に使用したインストール済みコード
-
-ASARは読み取り専用で展開し、bundleや署名は変更していない。minified名はこのbuildに限る。
-
-| ASAR resource | SHA-256 |
-| --- | --- |
-| `.vite/build/main-CqEoQDOU.js` | `09d19386e1f23cf4ccbc950fc40d85a1e8a064a08be588b2a4be6a89f6ada9e6` |
-| `webview/assets/app-initial-6350d04672d0.js` | `604b5d2de4fbb41f3d0dc5b3662129c558e1c7b8aac8cc87225286f58dcfaf8f` |
-| `webview/assets/app-shared-8bd9d0399038.js` | `607ad0866dd25ed3764711b4467a9b60708353a599485b5249ff4cbe0e870245` |
-| `webview/assets/execution-fde3a4937b6a.js` | `5c300497b7331bfa317231251e1097385405b70f2746b1fe8959c74e56735811` |