codexteer 0.17.0 → 0.18.0

package/src/cloud-cli.mjs

@@ -0,0 +1,319 @@
+import { desktopCloudProjectDoctor, assignDesktopCloudProject, desktopCloudProjectReceipt } from "./desktop-cloud-project.mjs";
+import { listProjects as listDesktopProjects } from "./projects.mjs";
+import { isDesktopCloudTask, desktopCloudId, desktopCloudLink } from "./desktop-cloud-id.mjs";
+import { desktopCloudConnection, desktopCloudEnvironments } from "./desktop-cloud-api.mjs";
+import { createDesktopCloudTask, listDesktopCloudTasks, desktopCloudReceipt } from "./desktop-cloud.mjs";
+import { isCloudTask } from "./task-id.mjs";
+import { cloudTaskId } from "./cloud-id.mjs";
+import { cloudConnection } from "./cloud-connection.mjs";
+import { observeThread, printObservation } from "./observe.mjs";
+import { monitorCommand } from "./monitor.mjs";
+import { notificationOptions } from "./notify.mjs";
+import { prepareSupervisorPrompt, superviseAgent } from "./supervise.mjs";
+import { supervisorId, registerSupervisor, getSupervisor, assertSupervisor, controlSupervisor, supervisorStatus, listSupervisors } from "./supervision.mjs";
+import { createFinding, findingStatus, listFindings, resolveFinding, dismissFinding, reopenFinding, evaluateFinding, findingStats } from "./findings.mjs";
+import { sendTrackedMessage, listMessages, getMessage, messageSummary, reconcileMessages, markMessage, listInstructions } from "./journal.mjs";
+import { createCloudTask, cloudTaskDiff, listCloudTasks, cloudCreationReceipt } from "./cloud.mjs";
+import { cloudSendReceipt, reconcileCloudSend } from "./cloud-observe.mjs";
+import { cloudEnvironments } from "./cloud-api.mjs";
+import { readFileSync } from "node:fs";
+import { spawnSync } from "node:child_process";
+import { playSendSound } from "./sound.mjs";
+import { VERSION } from "./version.mjs";
+import { createCheckpoint, listCheckpoints, getCheckpoint, checkpointSummary, verifyCheckpoint, runCheckpoint, attachArtifacts } from "./checkpoint.mjs";
+import { acquireResource, resourceStatus, renewResource, releaseResource, listResources, runWithResource } from "./resource.mjs";
+
+const failure = (message, code = "CLOUD_OPTIONS_INVALID") => Object.assign(new Error(message), { code, execution_environment: "cloud" });
+const values = new Set("--environment --connection --supervisor --require-node-version --host --remote-transport --context-thread --thread --backend --source --kind --evidence --based-on --finding --expires-at --supersedes --checkpoint --limit --max-chars --since --poll-ms --timeout-ms --until --notify --settle-ms --max-hold-ms --owner --key --condition --note --rating --reason --root --path --exclude --command --cwd --artifact --status --by --token --ttl-ms --agent --project --env --branch --title --model --thinking --cursor --attempt".split(" "));
+function option(args, name, fallback) {
+  const index = args.indexOf(name), stop = args.indexOf("--");
+  if (index < 0 || (stop >= 0 && index > stop)) return fallback;
+  const value = args[index + 1]; if (value == null || value.startsWith("--")) throw failure(`${name} requires a value.`);
+  args.splice(index, 2); return value;
+}
+function flag(args, name) {
+  const index = args.indexOf(name), stop = args.indexOf("--");
+  if (index < 0 || (stop >= 0 && index > stop)) return false;
+  args.splice(index, 1); return true;
+}
+const repeated = (args, name) => { const result = []; let value; while ((value = option(args, name)) !== undefined) result.push(value); return result; };
+const message = args => { if (args[0] === "--") args.shift(); return args.length === 1 && args[0] === "-" ? readFileSync(0, "utf8") : args.join(" "); };
+function exact(args, count) { if (args.length !== count || args.some(arg => arg.startsWith("--"))) throw failure("Unexpected arguments. See the command's help."); }
+
+function selectedCloudInvocation(argv) {
+  const end = argv.indexOf("--"), own = end < 0 ? argv : argv.slice(0, end);
+  const connection = own.indexOf("--connection");
+  const positional = [];
+  for (let i = 0; i < own.length; i++) {
+    if (values.has(own[i])) { i++; continue; }
+    if (!own[i].startsWith("--")) positional.push(own[i]);
+  }
+  const [command, action] = positional;
+  if (["help", "--help", "--version"].includes(command) || own.includes("--help") || own.includes("--version")) return false;
+  if (connection >= 0 && ["cloud", "desktop-cloud"].includes(own[connection + 1])) return own[connection + 1];
+  const thread = own.indexOf("--thread");
+  if (["doctor", "resource"].includes(command) && thread >= 0) return isDesktopCloudTask(own[thread + 1]) ? "desktop-cloud" : isCloudTask(own[thread + 1]) ? "cloud" : false;
+  if (command === "thread" && action === "create") return false;
+  const nested = ["history", "instructions", "findings", "checkpoint", "thread"].includes(command)
+    || (command === "supervise" && ["prompt", "register", "status", "pause", "resume", "stop", "list"].includes(action));
+  const target = isCloudTask(command) || isDesktopCloudTask(command) ? command : positional[nested ? 2 : 1];
+  return isDesktopCloudTask(target) ? "desktop-cloud" : isCloudTask(target) ? "cloud" : false;
+}
+
+export const cloudInvocation = argv => !!selectedCloudInvocation(argv);
+
+// Only parsing/routing is backend-specific. Supervision, monitoring, directives,
+// findings, journaling and saved-agent launch use the same local implementation.
+export async function mainCloud(argv) {
+  const args = [...argv], json = flag(args, "--json"), connection = option(args, "--connection", selectedCloudInvocation(argv) || "cloud");
+  const desktopCloud = connection === "desktop-cloud";
+  const targetId = desktopCloud ? desktopCloudId : cloudTaskId;
+  if (!["cloud", "desktop-cloud"].includes(connection)) throw failure("A cloud task requires the cloud connection.", "CLOUD_TARGET_CONFLICT");
+  const own = args.slice(0, args.includes("--") ? args.indexOf("--") : args.length);
+  if (own.some(value => ["--host", "--remote-transport", "--context-thread"].includes(value))) throw failure("Desktop host routes cannot select a cloud task.", "CLOUD_TARGET_CONFLICT");
+  const requiredNode = option(args, "--require-node-version");
+  if (requiredNode !== undefined && requiredNode !== process.version) throw failure("The saved supervisor requires its original Node version. Regenerate its prompt.", "NODE_VERSION_MISMATCH");
+  const session = option(args, "--supervisor"), supervisor = session === undefined ? undefined : supervisorId(session);
+  let command = args.shift();
+  if (isCloudTask(command) || isDesktopCloudTask(command)) { args.unshift(command); command = "send"; }
+  const output = (name, data) => {
+    if (json) console.log(JSON.stringify({ ok: true, command: name, data }));
+    else console.log(JSON.stringify(data, null, 2));
+    return data;
+  };
+  const bound = async (target, { allowUnregistered = false } = {}) => {
+    const id = targetId(target);
+    if (supervisor) {
+      const record = allowUnregistered ? await getSupervisor(id) : null;
+      if (!allowUnregistered || record?.session_id === supervisor) await assertSupervisor(id, supervisor, { connection });
+      else if (record && record.state !== "stopped") throw failure("Another supervisor owns this cloud task.", "SUPERVISOR_CONFLICT");
+    }
+    return id;
+  };
+  const dependencies = desktopCloud ? desktopCloudConnection() : cloudConnection();
+  if (desktopCloud && await desktopCloudCommands(command, args, { supervisor, output, bound, dependencies })) return;
+
+  if (["read", "status", "watch"].includes(command)) {
+    const options = { supervisor, connection, fullHistory: flag(args, "--full-history"), since: option(args, "--since"),
+      limit: Number(option(args, "--limit", "50")), maxChars: Number(option(args, "--max-chars", "2000")), includeOutput: flag(args, "--include-output") };
+    const stream = command === "watch" && flag(args, "--stream");
+    if (command === "watch") {
+      const until = option(args, "--until"), timeout = option(args, "--timeout-ms");
+      if (stream && (until !== undefined || timeout !== undefined)) throw failure("--stream runs until cancelled; do not combine it with --until or --timeout-ms.");
+      Object.assign(options, { watch: true, until: until ?? "change", timeoutMs: Number(timeout ?? "30000"), pollMs: Number(option(args, "--poll-ms", "5000")) });
+      const notify = option(args, "--notify", stream ? "digest" : "all"), settle = option(args, "--settle-ms"), maxHold = option(args, "--max-hold-ms");
+      if (!stream && (notify === "digest" || settle !== undefined || maxHold !== undefined)) throw failure("Digest options require --stream.");
+      Object.assign(options, notificationOptions({ notify, ...(settle === undefined ? {} : { settleMs: Number(settle) }), ...(maxHold === undefined ? {} : { maxHoldMs: Number(maxHold) }) }));
+    }
+    exact(args, 1); const id = await bound(args[0]);
+    if (stream) return monitorCommand(id, options, dependencies);
+    const data = await observeThread(id, options, dependencies); data.connection_mode = connection;
+    if (command === "status") delete data.events;
+    if (json) output(command, data); else printObservation(data, command === "status");
+    return;
+  }
+  if (command === "supervise") {
+    const action = args[0];
+    if (["register", "status", "list", "pause", "resume", "stop"].includes(action)) {
+      args.shift(); const owner = action === "register" ? option(args, "--owner", "external") : undefined;
+      exact(args, action === "list" ? 0 : 1);
+      const id = action === "list" ? null : targetId(args[0]); let data;
+      if (action === "register") {
+        if (!supervisor) throw failure("supervise register requires the generated --supervisor ID.");
+        data = await registerSupervisor(id, supervisor, { owner, connection });
+      } else {
+        if (supervisor && action !== "status") throw failure("A supervisor cannot change its own control state.", "SUPERVISOR_CONTROL_FORBIDDEN");
+        if (supervisor && id && (await getSupervisor(id))?.session_id !== supervisor) throw failure("This command belongs to another supervisor.", "SUPERVISOR_MISMATCH");
+        data = action === "list" ? (await listSupervisors()).filter(record => record.connection === connection) : action === "status" ? await supervisorStatus(id) : await controlSupervisor(id, action);
+        if (action === "status") { const pending = await listFindings(id, { limit: 20 }); data.unresolved_findings = { total: pending.total, has_more: pending.has_more, findings: pending.findings.map(f => ({ id: f.id, title: f.title, status: f.status, revision: f.revision })) }; }
+      }
+      output(`supervise.${action}`, data); return;
+    }
+    if (supervisor) throw failure("A supervisor cannot start a replacement session.", "SUPERVISOR_CONTROL_FORBIDDEN");
+    const promptOnly = action === "prompt"; if (promptOnly) args.shift();
+    const separator = args.indexOf("--"), ownArgs = separator < 0 ? args : args.slice(0, separator), forwarded = separator < 0 ? [] : args.slice(separator + 1);
+    const agent = option(ownArgs, "--agent", "claude"), usePathCli = flag(ownArgs, "--use-path-cli");
+    if (ownArgs.length < 1 || ownArgs.length > 2 || ownArgs.some(a => a.startsWith("--"))) throw failure("Expected: supervise [prompt] <TASK> [POLICY] [--agent claude|codex].");
+    const id = targetId(ownArgs[0]);
+    if (promptOnly) { const data = await prepareSupervisorPrompt(id, ownArgs[1], { agent, usePathCli, connection }); if (json) output("supervise.prompt", data); else console.log(data.prompt); }
+    else { if (json) throw failure("supervise inherits agent output and does not support --json."); process.exitCode = await superviseAgent(id, { policy: ownArgs[1], agent, usePathCli, agentArgs: forwarded, connection }); }
+    return;
+  }
+  if (command === "findings") {
+    const action = args.shift(), options = {};
+    const names = { key: "--key", title: "--title", condition: "--condition", basedOn: "--based-on", checkpoint: "--checkpoint", note: "--note", reason: "--reason", rating: "--rating" };
+    const allowed = { create: ["key", "title", "condition", "basedOn"], resolve: ["checkpoint", "note"], dismiss: ["reason"], reopen: ["reason", "condition", "basedOn"], evaluate: ["rating", "reason"] }[action] ?? [];
+    for (const key of allowed) { const value = option(args, names[key]); if (value !== undefined) options[key] = value; }
+    if (["create", "reopen"].includes(action)) { const evidence = repeated(args, "--evidence"); if (evidence.length) options.evidence = evidence; }
+    if (action === "list") { options.all = flag(args, "--all"); options.limit = Number(option(args, "--limit", "50")); }
+    const handlers = { create: createFinding, show: findingStatus, list: listFindings, resolve: resolveFinding, dismiss: dismissFinding, reopen: reopenFinding, evaluate: evaluateFinding, stats: findingStats };
+    if (!Object.hasOwn(handlers, action)) throw failure("Unknown findings operation.");
+    const single = ["create", "list", "stats"].includes(action); exact(args, single ? 1 : 2); const id = await bound(args[0]);
+    output(`findings.${action}`, single ? await handlers[action](id, options) : await handlers[action](id, args[1], options)); return;
+  }
+  if (command === "history") {
+    const action = args.shift(), attempt = option(args, "--attempt");
+    if (attempt !== undefined) {
+      if (desktopCloud) throw failure("Use the common history check with a message ID for Desktop Cloud.");
+      if (!["show", "check"].includes(action)) throw failure("--attempt requires history show or history check.");
+      exact(args, 1); const id = await bound(args[0]);
+      const settings = { taskId: id };
+      output(`history.${action}`, action === "show" ? await cloudSendReceipt(attempt, settings) : await reconcileCloudSend(attempt, settings)); return;
+    }
+    const includeText = flag(args, "--include-text"), pending = flag(args, "--pending");
+    const report = action === "mark" ? { status: option(args, "--status"), note: option(args, "--note"), evidence: repeated(args, "--evidence"), by: option(args, "--by", "local") } : {};
+    if (!args[0] || args.length > 2 || !["list", "show", "check", "mark"].includes(action) || (["show", "mark"].includes(action) && !args[1]) || (action === "list" && args[1])) throw failure("Invalid history arguments.");
+    const id = await bound(args[0]); const data = action === "list" ? await listMessages(id, { includeText, pending }) : action === "show" ? messageSummary(await getMessage(id, args[1]), includeText)
+      : action === "check" ? await reconcileMessages(id, args[1], { includeText }, dependencies) : await markMessage(id, args[1], report);
+    output(`history.${action}`, data); return;
+  }
+  if (command === "instructions") {
+    const action = args.shift();
+    if (action === "list") { const all = flag(args, "--all"); exact(args, 1); output("instructions.list", await listInstructions(await bound(args[0]), { all })); return; }
+    if (action !== "retract") throw failure("Expected instructions list|retract.");
+    const source = option(args, "--source", "external"), reason = option(args, "--reason"), basedOn = option(args, "--based-on"), dryRun = flag(args, "--dry-run"), newTurn = flag(args, "--new-turn");
+    exact(args, 2); if (!reason) throw failure("Retraction requires --reason.");
+    output("instructions.retract", await sendTrackedMessage(await bound(args[0]), reason, { source, retracts: args[1], basedOn, dryRun, newTurn, supervisor, connection })); return;
+  }
+  if (command === "checkpoint") {
+    const action = args.shift(), includeOutput = flag(args, "--include-output"); let data;
+    if (action === "capture") {
+      const paths = repeated(args, "--path"), excludes = repeated(args, "--exclude"); exact(args, 2);
+      data = await createCheckpoint(await bound(args[0]), args[1], { paths, excludes });
+    } else if (action === "run") {
+      const timeoutMs = Number(option(args, "--timeout-ms", "0"));
+      if (args[2] !== "--" || args.length < 4) throw failure("Expected checkpoint run <TASK> <ID> -- <COMMAND> [ARGS...].");
+      data = await runCheckpoint(await bound(args[0]), args[1], args.slice(3), { timeoutMs });
+      if (!includeOutput) delete data.output_tail; if (!data.valid) process.exitCode = 1;
+    } else if (action === "attach") { const refs = repeated(args, "--artifact"); exact(args, 2); data = await attachArtifacts(await bound(args[0]), args[1], refs); }
+    else if (action === "list") { exact(args, 1); data = await listCheckpoints(await bound(args[0])); }
+    else if (["show", "verify"].includes(action)) { exact(args, 2); const id = await bound(args[0]); data = action === "verify" ? await verifyCheckpoint(id, args[1]) : checkpointSummary(await getCheckpoint(id, args[1]), includeOutput); if (action === "verify" && !data.valid) process.exitCode = 1; }
+    else throw failure("Unknown checkpoint operation.");
+    output(`checkpoint.${action}`, Array.isArray(data) ? data.map(item => ({ ...item, execution_environment: "local" })) : { ...data, execution_environment: "local", verification_target: "explicit local input/artifact paths; cloud files are not mounted" }); return;
+  }
+  if (command === "resource") {
+    const action = args.shift(), threadInput = option(args, "--thread");
+    const threadId = threadInput === undefined ? undefined : await bound(threadInput);
+    if (supervisor && !threadId) throw failure("A supervisor resource command requires its --thread target.", "SUPERVISOR_CONTROL_FORBIDDEN");
+    let data;
+    if (["acquire", "run"].includes(action)) {
+      const settings = { owner: option(args, "--owner"), ttlMs: Number(option(args, "--ttl-ms", "600000")), reason: option(args, "--reason", ""), condition: option(args, "--condition", ""), threadId };
+      if (action === "run") {
+        const timeoutMs = Number(option(args, "--timeout-ms", "0")), includeOutput = flag(args, "--include-output");
+        if (args[1] !== "--" || args.length < 3) throw failure("Expected resource run <NAME> --owner NAME -- <COMMAND> [ARGS...].");
+        data = await runWithResource(args[0], args.slice(2), { ...settings, timeoutMs }); if (!includeOutput) delete data.output_tail; if (!data.valid) process.exitCode = 1;
+      } else { exact(args, 1); data = await acquireResource(args[0], settings); }
+    } else if (["renew", "release"].includes(action)) {
+      const token = option(args, "--token"), ttlMs = Number(option(args, "--ttl-ms", "600000")); exact(args, 1);
+      data = action === "renew" ? await renewResource(args[0], token, { ttlMs }) : await releaseResource(args[0], token);
+    } else if (action === "status") { exact(args, 1); data = await resourceStatus(args[0]); }
+    else if (action === "list") { exact(args, 0); data = await listResources(); }
+    else throw failure("Unknown resource operation.");
+    output(`resource.${action}`, Array.isArray(data) ? data.map(item => ({ ...item, execution_environment: "local" })) : { ...data, execution_environment: "local", scope: "local coordination and explicitly supplied local commands" }); return;
+  }
+  if (command === "threads") {
+    if (args.shift() !== "list") throw failure("Expected threads list.");
+    const limit = Number(option(args, "--limit", "20")), cursor = option(args, "--cursor"), environment = option(args, "--env"); exact(args, 0);
+    if (supervisor) throw failure("A bound supervisor cannot enumerate unrelated cloud tasks.", "SUPERVISOR_CONTROL_FORBIDDEN");
+    output("threads.list", await listCloudTasks({ limit, cursor, environment })); return;
+  }
+  if (command === "thread" && args[0] === "receipt") {
+    args.shift(); exact(args, 1);
+    if (supervisor) throw failure("A bound supervisor cannot inspect unrelated creation attempts.", "SUPERVISOR_CONTROL_FORBIDDEN");
+    output("thread.receipt", await cloudCreationReceipt(args[0])); return;
+  }
+  if (command === "thread" && args[0] === "create") {
+    args.shift(); if (supervisor) throw failure("A bound supervisor cannot create another task.", "SUPERVISOR_CONTROL_FORBIDDEN");
+    const project = option(args, "--project"), requestedBranch = option(args, "--branch"), dryRun = flag(args, "--dry-run");
+    if (project === undefined) throw failure("Cloud creation requires --project with an environment ID or exact name.");
+    const end = args.includes("--") ? args.indexOf("--") : args.length; if (args.slice(0, end).some(arg => arg.startsWith("--"))) throw failure("Unknown cloud creation option; explicit model/title/permission overrides are not implemented yet.");
+    const body = message(args); if (!body.trim()) throw failure("A non-empty initial instruction is required.");
+    const rows = (await cloudEnvironments()).environments, selector = project, matches = rows.filter(e => e.id === selector || e.name === selector);
+    if (matches.length !== 1) throw failure("The cloud environment selector must match one accessible ID or exact name.");
+    const selected = matches[0], branch = requestedBranch ?? (selected.repositories.length === 1 ? selected.repositories[0].default_branch : null);
+    if (!branch) throw failure("Specify --branch: this environment does not identify one repository default branch.");
+    const data = await createCloudTask(selected.id, branch, body, { dryRun });
+    output("thread.create", { ...data, thread_id: data.task_id ?? null, project_id: selected.id, project_name: selected.name, deep_link: data.url ?? null,
+      branch_source: requestedBranch === undefined ? "environment-default" : "explicit" }); return;
+  }
+  if (command === "projects") { exact(args, 1); if (args[0] !== "list") throw failure("Expected projects list."); if (supervisor) throw failure("A bound supervisor cannot enumerate unrelated cloud environments.", "SUPERVISOR_CONTROL_FORBIDDEN"); const data = await cloudEnvironments(); output("projects.list", { projects: data.environments.map(e => ({ ...e, project_id: e.id, execution_environment: "cloud" })) }); return; }
+  if (command === "doctor") {
+    const target = option(args, "--thread"), backend = option(args, "--backend", "app-server"); exact(args, 0);
+    if (backend !== "app-server") throw failure("Cloud cannot use Desktop UI.", "CLOUD_TARGET_CONFLICT");
+    if (target) {
+      const id = await bound(target, { allowUnregistered: true });
+      await observeThread(id, { connection, limit: 1 }, dependencies);
+    } else { if (supervisor) throw failure("A bound supervisor doctor requires its target task.", "SUPERVISOR_CONTROL_FORBIDDEN"); await cloudEnvironments(); }
+    output("doctor", { ready: true, backend: "codex-api", execution_environment: "cloud", version: VERSION,
+      codex_steer_compatibility: { status: "compatible" }, connection: { status: "connected", mode: "cloud" },
+      observation_compatibility: { status: target ? "verified" : "unverified" },
+      runtime_compatibility: { operations: Object.fromEntries(["read", "watch", "monitor", "history_check", "send", "send_new_turn"].map(name => [name, { status: "supported" }])) },
+      active_send_semantics: "interrupt-and-follow-up; same task, new turn", unverified_features: ["approval_roundtrip", "atomic_server_freshness"] }); return;
+  }
+  if (command === "thread" && args[0] === "resolve") { args.shift(); exact(args, 1); const id = targetId(args[0]); output("thread.resolve", { thread_id: id, task_id: id, deep_link: `https://chatgpt.com/codex/tasks/${id}`, execution_environment: "cloud" }); return; }
+  if (command === "open") {
+    exact(args, 1); const id = await bound(args[0]), url = `https://chatgpt.com/codex/tasks/${id}`;
+    if (process.platform !== "darwin") throw failure("Open this task URL in your browser; native browser launch is only implemented on macOS.", "CLOUD_CAPABILITY_UNSUPPORTED");
+    const result = spawnSync("/usr/bin/open", [url], { encoding: "utf8", timeout: 5000 }); if (result.status !== 0) throw failure("Could not open the cloud task in the browser.", "CLOUD_OPEN_FAILED");
+    output("open", { thread_id: id, deep_link: url, execution_environment: "cloud" }); return;
+  }
+  if (command === "diff") {
+    const attempt = option(args, "--attempt"), timeout = option(args, "--timeout-ms"); exact(args, 1);
+    const data = await cloudTaskDiff(await bound(args[0]), { ...(attempt === undefined ? {} : { attempt: Number(attempt) }), ...(timeout === undefined ? {} : { timeoutMs: Number(timeout) }) });
+    if (json) output("diff", data);
+    else if (data.diff === null) console.error("No server-recorded patch is available. This does not prove the cloud working copy has no changes; inspect read command evidence.");
+    else process.stdout.write(data.diff);
+    return;
+  }
+  if (command !== "send") throw failure("This cloud operation is not implemented yet. No Desktop fallback was attempted.", "CLOUD_CAPABILITY_UNSUPPORTED");
+  const dryRun = flag(args, "--dry-run"), newTurn = flag(args, "--new-turn"), backend = option(args, "--backend", "app-server");
+  const noSound = flag(args, "--no-sound"), explicitSound = flag(args, "--sound"); if (noSound && explicitSound) throw failure("--sound and --no-sound cannot be combined.");
+  if (backend !== "app-server") throw failure("Cloud cannot send through Desktop UI.", "CLOUD_TARGET_CONFLICT");
+  const options = { dryRun, newTurn, supervisor, connection, evidence: repeated(args, "--evidence") };
+  for (const [key, name] of Object.entries({ source: "--source", kind: "--kind", basedOn: "--based-on", supersedes: "--supersedes", expiresAt: "--expires-at", checkpoint: "--checkpoint", finding: "--finding" })) { const value = option(args, name); if (value !== undefined) options[key] = value; }
+  const id = targetId(args.shift()), end = args.includes("--") ? args.indexOf("--") : args.length;
+  if (args.slice(0, end).some(arg => arg.startsWith("--"))) throw failure("Unknown send option. Use -- before instruction text starting with --.");
+  const body = message(args); if (!body.trim()) throw failure("send requires a non-empty message.");
+  const receipt = await sendTrackedMessage(id, body, options);
+  receipt.sound = noSound ? { played: false, reason: "disabled" } : playSendSound(receipt);
+  output("send", receipt);
+}
+
+async function desktopCloudCommands(command, args, { supervisor, output, bound, dependencies }) {
+  if (!["projects", "environments", "threads", "thread", "doctor", "diff", "open"].includes(command)) return false;
+  if (supervisor && ["projects", "environments", "threads", "thread"].includes(command)) throw failure("A supervisor cannot enumerate or create other tasks.", "SUPERVISOR_CONTROL_FORBIDDEN");
+  if (["projects", "environments"].includes(command)) {
+    exact(args, 1); if (args[0] !== "list") throw failure("Expected list.");
+    if (command === "projects") { output("projects.list", { projects: (await listDesktopProjects()).flatMap(row => row.desktop_project_ids.map(id => ({ project_id: id, canonical_project_id: row.project_id, name: row.name, roots: row.roots }))), catalog_source: "desktop-app-server", assignment_requires_exact_desktop_executor: true }); return true; }
+    output("environments.list", await desktopCloudEnvironments()); return true;
+  }
+  if (command === "threads") {
+    if (args.shift() !== "list") throw failure("Expected threads list.");
+    const limit = Number(option(args, "--limit", "20")), cursor = option(args, "--cursor"); exact(args, 0);
+    output("threads.list", await listDesktopCloudTasks({ limit, cursor })); return true;
+  }
+  if (command === "thread") {
+    const action = args.shift();
+    if (action === "create") {
+      const environment = option(args, "--environment"), project = option(args, "--project"), title = option(args, "--title"), dryRun = flag(args, "--dry-run");
+      const end = args.includes("--") ? args.indexOf("--") : args.length;
+      if (args.slice(0, end).some(arg => arg.startsWith("--"))) throw failure("Unknown Desktop Cloud creation option.");
+      output("thread.create", await createDesktopCloudTask(environment, message(args), { project, title, dryRun })); return true;
+    }
+    if (action === "assign") { const project = option(args, "--project"); exact(args, 1); const data = await assignDesktopCloudProject(await bound(args[0]), project); output("thread.assign", data); if (data.verification_status !== "verified") process.exitCode = 1; return true; }
+    exact(args, 1);
+    if (action === "receipt") { let data; try { data = await desktopCloudReceipt(args[0]); } catch (error) { if (error.code !== "DESKTOP_CLOUD_CREATION_RECEIPT_NOT_FOUND") throw error; data = await desktopCloudProjectReceipt(args[0]); } output("thread.receipt", data); return true; }
+    if (action === "resolve") { const id = await bound(args[0]); output("thread.resolve", { thread_id: id, deep_link: desktopCloudLink(id) }); return true; }
+    throw failure("Expected thread create|assign|receipt|resolve.");
+  }
+  if (command === "doctor") {
+    const target = option(args, "--thread"), project = option(args, "--project"); exact(args, 0);
+    if (project !== undefined && !target) throw failure("--project diagnostics require --thread.");
+    const id = target ? await bound(target, { allowUnregistered: true }) : null;
+    if (id) await observeThread(id, { connection: "desktop-cloud", limit: 1 }, dependencies);
+    else { if (supervisor) throw failure("A supervisor doctor needs its target."); await desktopCloudEnvironments(); }
+    output("doctor", { ready: true, connection_mode: "desktop-cloud", observation: target ? "verified" : "unverified", project_membership: id ? await desktopCloudProjectDoctor(id, project) : { membership: { status: "unverified" }, assignment_api: { status: "unverified" } }, approval_roundtrip: "unverified", atomic_server_freshness: "unverified" }); return true;
+  }
+  if (command === "open") { exact(args, 1); output("open", { deep_link: desktopCloudLink(await bound(args[0])) }); return true; }
+  throw failure("Desktop Cloud diff retrieval is not verified. Inspect file-change events with read --include-output.", "CAPABILITY_UNVERIFIED");
+}

package/src/cloud-connection.mjs

@@ -0,0 +1,64 @@
+import { cloudTaskId } from "./cloud-id.mjs";
+import { readCloudTask } from "./cloud-observe.mjs";
+import { codexHome } from "./runtime.mjs";
+
+const status = value => ["in_progress", "pending", "running", "queued"].includes(value) ? "inProgress"
+  : value === "cancelled" ? "interrupted" : value === "failed" || value === "error" ? "failed" : value === "completed" ? "completed" : "unknown";
+
+// Adapt public cloud history into the same observation model used by the local
+// monitor, freshness checks and directive journal. Keep backend IDs unchanged.
+export function cloudThread(snapshot) {
+  const taskId = cloudTaskId(snapshot.task_id);
+  const turns = snapshot.turns.map(turn => ({ id: turn.turn_id, status: turn.role === "user" ? "completed" : status(turn.status), items: [
+    ...turn.commands.map(command => ({ id: command.id, type: "commandExecution", command: command.command, cwd: null,
+      status: status(command.status === "inProgress" ? "in_progress" : command.status), exitCode: command.exit_code, aggregatedOutput: command.output ?? "" })),
+    ...(turn.progress ?? []).map((message, index) => ({ id: `${turn.turn_id}:progress:${message.id === undefined ? `index:${index}` : `id:${message.id}`}`, type: "agentMessage",
+      phase: "commentary", status: status(turn.status), text: message.text })),
+    ...turn.messages.map((message, index) => turn.role === "user"
+      ? { id: `${turn.turn_id}:message:${index}`, type: "userMessage", clientId: null, cloudParentTurnId: turn.parent_turn_id,
+        content: [{ type: "text", text: message.text }] }
+      : { id: `${turn.turn_id}:message:${index}`, type: "agentMessage", phase: "final_answer", status: status(turn.status), text: message.text }),
+  ] }));
+  const active = turns.filter(turn => turn.status === "inProgress");
+  return { id: taskId, name: snapshot.title ?? null, cwd: null, historyMode: "aggregate", canAcceptDirectInput: true,
+    status: { type: active.length ? "active" : status(snapshot.status) === "unknown" ? "systemError" : "idle", activeFlags: [] },
+    turns, cloud_snapshot: snapshot };
+}
+
+export class CloudReadClient {
+  constructor({ read = readCloudTask, timeoutMs = 30000, signal } = {}) {
+    this.read = read; this.timeoutMs = timeoutMs; this.controller = new AbortController();
+    this.cancel = () => this.close(); signal?.addEventListener("abort", this.cancel, { once: true });
+    this.signal = signal; if (signal?.aborted) this.close();
+  }
+  async request(method, params = {}, options = {}) {
+    if (this.controller.signal.aborted) throw Object.assign(new Error("Cloud observation was cancelled."), { code: "CANCELLED" });
+    if (method !== "thread/read" || options.mutation) throw Object.assign(new Error("Unsupported cloud observation method."), { code: "CAPABILITY_UNSUPPORTED" });
+    const id = cloudTaskId(params.threadId);
+    try {
+      if (!params.includeTurns || this.cached?.task_id !== id) this.cached = await this.read(id, { timeoutMs: this.timeoutMs, signal: this.controller.signal });
+      const thread = cloudThread(this.cached);
+      if (params.includeTurns) this.cached = null;
+      return { thread };
+    } catch (error) {
+      const mapped = { CLOUD_CONNECTION_FAILED: "CONNECTION_FAILED", CLOUD_RATE_LIMITED: "CONNECTION_FAILED", CLOUD_TIMEOUT: "TIMEOUT", CLOUD_AUTH_TIMEOUT: "TIMEOUT", CLOUD_STATE_CHANGED: "OBSERVATION_CHANGED", CLOUD_CANCELLED: "CANCELLED" }[error.code];
+      if (mapped) throw Object.assign(new Error(error.message), { code: mapped, cause_code: error.code,
+        ...(error.retry_after_ms === undefined ? {} : { retry_after_ms: error.retry_after_ms }) });
+      throw error;
+    }
+  }
+  close() { this.controller.abort(); this.signal?.removeEventListener("abort", this.cancel); this.cached = null; }
+}
+
+export function cloudConnection(dependencies = {}) {
+  return {
+    async discover(home = codexHome()) {
+      return { paths: { home, socket: "codex-cloud" }, state: { codex_home: home, cloud_connection: true,
+        codex_steer_protocol: 1, codex_steer_capabilities: { thread_read: [1], history_pagination: [], turn_steer: [], turn_start: [], desktop_subscribe: [] } } };
+    },
+    async connect(endpoint, options = {}) {
+      if (endpoint !== "codex-cloud") throw Object.assign(new Error("Invalid cloud observation endpoint."), { code: "CLOUD_TARGET_CONFLICT" });
+      return new CloudReadClient({ ...dependencies, ...options });
+    },
+  };
+}

package/src/cloud-id.mjs

@@ -0,0 +1,16 @@
+const pattern = /^task_[A-Za-z0-9][A-Za-z0-9_-]{0,199}$/;
+const failure = () => Object.assign(new Error("Invalid Codex Cloud task. Use a task ID or an official chatgpt.com/codex/tasks link."), { code: "CLOUD_OPTIONS_INVALID" });
+
+export function isCloudTask(value) {
+  return typeof value === "string" && (value.startsWith("task_") || /^https:\/\/chatgpt\.com\/codex\/tasks\//.test(value));
+}
+
+export function cloudTaskId(value) {
+  if (typeof value !== "string") throw failure();
+  if (pattern.test(value)) return value;
+  try {
+    const url = new URL(value), id = url.pathname.slice("/codex/tasks/".length);
+    if (url.origin === "https://chatgpt.com" && !url.username && !url.password && url.pathname.startsWith("/codex/tasks/") && pattern.test(id)) return id;
+  } catch {}
+  throw failure();
+}

package/src/cloud-observe.mjs

@@ -0,0 +1,178 @@
+import { createHash, randomUUID } from "node:crypto";
+import { cloudApi, cloudCredentials } from "./cloud-api.mjs";
+import { cloudTaskId } from "./cloud-id.mjs";
+import { readRecord, storePath, withStoreLock, writeRecord } from "./store.mjs";
+
+const failure = (code, message) => Object.assign(new Error(message), { code, execution_environment: "cloud" });
+const digest = value => createHash("sha256").update(JSON.stringify(value)).digest("hex");
+const validTurn = (task, value) => typeof value === "string" && value.startsWith(`${task}~`) && /^(?:usertrn|assttrn)_[A-Za-z0-9_-]{1,200}$/.test(value.slice(task.length + 1));
+export const cloudUserRevision = snapshot => digest(snapshot.turns.filter(turn => turn.role === "user").map(turn => ({ id: turn.turn_id, parent: turn.parent_turn_id, messages: turn.messages })));
+
+function texts(items) {
+  return (Array.isArray(items) ? items : []).filter(item => item?.type === "message").map(item => ({
+    role: typeof item.role === "string" ? item.role : null,
+    text: (Array.isArray(item.content) ? item.content : []).flatMap(part => typeof part === "string" ? [part]
+      : part?.content_type === "text" && typeof part.text === "string" ? [part.text] : []).join("\n"),
+  })).filter(item => item.text);
+}
+
+function publicProgress(items) {
+  return (Array.isArray(items) ? items : []).flatMap(item => {
+    const role = item?.role ?? item?.author?.role;
+    if (role !== "assistant" || ![undefined, null, "commentary"].includes(item.channel)
+      || item.type === "reasoning" || (item.recipient != null && item.recipient !== "all") || item.metadata?.is_visually_hidden_from_conversation === true
+      || (item.metadata?.reasoning_status != null && item.metadata?.is_thinking_preamble_message !== true)) return [];
+    let text;
+    if (Array.isArray(item.content)) text = texts([{ ...item, type: "message" }])[0]?.text;
+    else if (["text", "multimodal_text"].includes(item.content?.content_type) && Array.isArray(item.content.parts)) text = item.content.parts.filter(part => typeof part === "string").join("");
+    if (!text) return [];
+    return [{ ...(typeof item.id === "string" && item.id.length <= 512 && !/[\x00-\x1f]/u.test(item.id) ? { id: item.id } : {}), role: "assistant", text }];
+  });
+}
+
+function progress(turn) {
+  const items = publicProgress(turn.worklog?.messages), seen = new Set(items.flatMap(item => item.id === undefined ? [] : [item.id]));
+  const latest = new Map();
+  for (const event of [...(turn.thread_events?.events ?? []), ...(turn.app_server_events?.events ?? [])]) {
+    const item = event?.params?.item;
+    if (!["item/started", "item/completed"].includes(event?.method) || item?.type !== "agentMessage" || item.phase !== "commentary"
+      || typeof item.id !== "string" || !item.id || item.id.length > 512 || /[\x00-\x1f]/u.test(item.id) || typeof item.text !== "string" || !item.text) continue;
+    latest.set(item.id, { id: item.id, role: "assistant", text: item.text });
+  }
+  return [...items, ...[...latest.values()].filter(item => !seen.has(item.id))];
+}
+
+function commands(turn) {
+  const latest = new Map();
+  for (const event of [...(turn.thread_events?.events ?? []), ...(turn.app_server_events?.events ?? [])]) {
+    const item = event?.params?.item;
+    if (!["item/started", "item/completed"].includes(event?.method) || item?.type !== "commandExecution" || typeof item.id !== "string") continue;
+    latest.set(item.id, { id: item.id, status: typeof item.status === "string" ? item.status : "unknown",
+      command: typeof item.command === "string" ? item.command : null, output: typeof item.aggregatedOutput === "string" ? item.aggregatedOutput : null,
+      exit_code: Number.isInteger(item.exitCode) ? item.exitCode : null });
+  }
+  return [...latest.values()];
+}
+
+export async function readCloudTask(target, settings = {}, { request = cloudApi } = {}) {
+  const taskId = cloudTaskId(target);
+  if (settings.timeoutMs !== undefined && (!Number.isSafeInteger(settings.timeoutMs) || settings.timeoutMs < 1000 || settings.timeoutMs > 600000)) throw failure("CLOUD_OPTIONS_INVALID", "--timeout-ms must be 1000..600000.");
+  const timeoutMs = settings.timeoutMs ?? 120000, deadline = Date.now() + timeoutMs;
+  const details = await request(`tasks/${taskId}`, { timeoutMs, ...(settings.signal ? { signal: settings.signal } : {}) });
+  if (deadline - Date.now() < 1) throw failure("CLOUD_TIMEOUT", "Cloud history deadline expired.");
+  const history = await request(`tasks/${taskId}/turns`, { timeoutMs: deadline - Date.now(), ...(settings.signal ? { signal: settings.signal } : {}) });
+  const current = details.current_assistant_turn;
+  if (details.task?.id !== taskId || current?.role !== "assistant" || !validTurn(taskId, current?.id) || !current.id.startsWith(`${taskId}~assttrn_`) || !history.turn_mapping || typeof history.turn_mapping !== "object" || Array.isArray(history.turn_mapping)) {
+    throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud did not confirm the requested task and its turn history.");
+  }
+  if (details.task.current_turn_id !== history.current_turn_id || !history.turn_mapping[current.id]) throw failure("CLOUD_STATE_CHANGED", "Cloud changed while reading. Read again before sending.");
+  const nodes = Object.entries(history.turn_mapping);
+  if (nodes.length > 10000 || nodes.some(([id, node]) => !validTurn(taskId, id) || node?.turn?.id !== id || (node.parent != null && !validTurn(taskId, node.parent)))) {
+    throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud history contains an unrecognized turn identity.");
+  }
+  const turns = nodes.map(([id, node]) => ({ turn_id: id, parent_turn_id: node.parent ?? null,
+    role: node.turn.role, status: node.turn.turn_status ?? null, created_at: node.turn.created_at ?? null,
+    messages: texts(node.turn.input_items ?? node.turn.output_items),
+    progress: progress(node.turn),
+    commands: commands(node.turn),
+  })).sort((a, b) => (a.created_at ?? 0) - (b.created_at ?? 0) || a.turn_id.localeCompare(b.turn_id));
+  const snapshot = { task_id: taskId, turn_id: current.id, current_turn_id: history.current_turn_id, status: current.turn_status ?? "unknown",
+    title: typeof details.task.title === "string" && details.task.title.length <= 2000 ? details.task.title : null, turns };
+  return { backend: "codex-api", execution_environment: "cloud", ...snapshot,
+    history_scope: "all-returned-turns", url: `https://chatgpt.com/codex/tasks/${taskId}` };
+}
+
+export async function sendCloudTask(target, expectedTurn, prompt, settings = {}, dependencies = {}) {
+  const taskId = cloudTaskId(target);
+  if (settings.timeoutMs !== undefined && (!Number.isSafeInteger(settings.timeoutMs) || settings.timeoutMs < 1000 || settings.timeoutMs > 600000)) throw failure("CLOUD_OPTIONS_INVALID", "--timeout-ms must be 1000..600000.");
+  if (!validTurn(taskId, expectedTurn) || typeof settings.expectedUserRevision !== "string" || !/^[a-f0-9]{64}$/.test(settings.expectedUserRevision) || !["steer", "new-turn"].includes(settings.deliveryMode)) throw failure("CLOUD_OPTIONS_INVALID", "Cloud delivery requires the exact parent turn, user-input revision and delivery mode.");
+  if (typeof prompt !== "string" || !prompt.trim() || prompt.includes("\0") || Buffer.byteLength(prompt) > 1024 * 1024) throw failure("CLOUD_OPTIONS_INVALID", "A non-empty instruction of at most 1 MiB is required.");
+  const request = dependencies.request ?? cloudApi, read = dependencies.read ?? readCloudTask;
+  const write = dependencies.write ?? writeRecord, load = dependencies.load ?? readRecord, lock = dependencies.lock ?? withStoreLock;
+  // Pin one official account for the read/compare/send sequence. Never refresh
+  // or automatically retry an unknown submission against a different account.
+  const auth = dependencies.request ? null : await cloudCredentials();
+  const api = (route, options = {}) => request(route, { ...options, ...(auth ? { credentials: async () => auth } : {}) });
+  try { return await lock(`cloud-send-${taskId}`, async () => {
+    const observation = await read(taskId, { timeoutMs: settings.timeoutMs }, { request: api });
+    if (observation.turn_id !== expectedTurn || cloudUserRevision(observation) !== settings.expectedUserRevision) throw failure("CLOUD_STATE_CHANGED", "Cloud task or user input changed after observation. Read again; no message was sent.");
+    const active = ["in_progress", "pending", "queued", "running"].includes(observation.status);
+    if (settings.deliveryMode === "steer" ? !active : !["completed", "failed", "cancelled"].includes(observation.status)) {
+      throw failure(active ? "CLOUD_TASK_BUSY" : "CLOUD_TASK_IDLE", settings.deliveryMode === "steer"
+        ? "The task has no active turn. Use --new-turn to continue an idle cloud task."
+        : "A new turn requires a finished cloud turn. Nothing was sent.");
+    }
+    const previous = await load("cloud-send-heads", taskId);
+    const safelyUnsent = previous?.submission_status === "not_sent" && previous.dispatch_started === false;
+    if (previous && !safelyUnsent && (previous.submission_status !== "accepted" || previous.parent_turn_id === expectedTurn)) throw Object.assign(failure("CLOUD_DUPLICATE_SEND", "An accepted or uncertain send needs inspection before another send. Use history check <TASK> --attempt <ATTEMPT_ID>; do not resend."), { existing_attempt_id: previous.attempt_id, existing_receipt_path: previous.receipt_path });
+    const attemptId = randomUUID();
+    const receipt = { execution_environment: "cloud", backend: "codex-api", task_id: taskId, parent_turn_id: expectedTurn,
+      attempt_id: attemptId, receipt_path: storePath("cloud-messages", attemptId), user_revision: settings.expectedUserRevision,
+      prompt_sha256: createHash("sha256").update(prompt).digest("hex"), prompt_hash_encoding: "utf8", message_characters: [...prompt].length,
+      delivery_action: active ? "interrupt-and-follow-up" : "new-turn", parent_status: observation.status, submission_status: "not_sent", dry_run: !!settings.dryRun };
+    await settings.beforeSend?.(observation);
+    if (settings.dryRun) return receipt;
+    const dispatched = { ...receipt, submission_status: "dispatching" };
+    try {
+      await write("cloud-messages", attemptId, receipt);
+      // Finish receipt persistence before reserving the head. There must be no
+      // fallible persistence between the reservation and the single POST.
+      await write("cloud-messages", attemptId, dispatched);
+      await write("cloud-send-heads", taskId, dispatched);
+    } catch {
+      const unsent = { ...receipt, dispatch_started: false, error_code: "CLOUD_PERSISTENCE_FAILED" };
+      try { await write("cloud-send-heads", taskId, previous ?? unsent); }
+      catch { unsent.reservation_cleanup_required = true; unsent.receipt_update_required = true; }
+      try { await write("cloud-messages", attemptId, unsent); }
+      catch { unsent.receipt_update_required = true; }
+      throw Object.assign(failure("CLOUD_PERSISTENCE_FAILED", "Cloud send records could not be prepared. No request was sent. Inspect the receipt and reservation before an explicit retry."), unsent, { uncertain: false });
+    }
+    let response;
+    try {
+      response = await api("tasks", { timeoutMs: settings.timeoutMs, body: {
+        follow_up: { task_id: taskId, turn_id: expectedTurn, environment_mode: "code" },
+        input_items: [{ type: "message", role: "user", content: [{ content_type: "text", text: prompt }] }],
+      } });
+      if ((response.task?.id ?? response.id) !== taskId) throw failure("CLOUD_PROTOCOL_UNVERIFIED", "Cloud did not confirm the same task after follow-up.");
+      receipt.submission_status = "accepted";
+    } catch (error) {
+      receipt.submission_status = "unknown";
+      receipt.error_code = error.code ?? "CLOUD_SEND_FAILED";
+      try { await write("cloud-messages", attemptId, receipt); } catch { receipt.receipt_update_required = true; }
+      throw Object.assign(failure(receipt.error_code, "Cloud follow-up outcome is unknown. Read this task and inspect the receipt before retrying; no automatic retry was made."), receipt, { uncertain: true });
+    }
+    try { await write("cloud-messages", attemptId, receipt); await write("cloud-send-heads", taskId, receipt); } catch { receipt.receipt_update_required = true; }
+    return receipt;
+  }); } finally { if (auth) auth.token = ""; }
+}
+
+export async function cloudSendReceipt(attemptId, { load = readRecord, taskId } = {}) {
+  if (typeof attemptId !== "string" || !/^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(attemptId)) throw failure("CLOUD_OPTIONS_INVALID", "A cloud send attempt UUID is required.");
+  const receipt = await load("cloud-messages", attemptId);
+  if (!receipt) throw failure("CLOUD_RECEIPT_NOT_FOUND", "Cloud send receipt was not found.");
+  if (taskId !== undefined && cloudTaskId(receipt.task_id) !== cloudTaskId(taskId)) throw failure("CLOUD_TARGET_CONFLICT", "The send attempt belongs to another cloud task.");
+  return receipt;
+}
+
+export async function reconcileCloudSend(attemptId, { read = readCloudTask, load = readRecord, write = writeRecord, lock = withStoreLock, taskId: expectedTask, expectedPromptSha256, expectedParentTurnId } = {}) {
+  const receipt = await cloudSendReceipt(attemptId, { load, taskId: expectedTask });
+  const taskId = cloudTaskId(receipt.task_id);
+  if ((expectedPromptSha256 !== undefined && receipt.prompt_sha256 !== expectedPromptSha256)
+    || (expectedParentTurnId !== undefined && receipt.parent_turn_id !== expectedParentTurnId)) {
+    return { ...receipt, delivery_verification: "conflict", retry_safe: false };
+  }
+  return lock(`cloud-send-${taskId}`, async () => {
+    if (receipt.submission_status === "not_sent" && receipt.dispatch_started === false) {
+      if ((await load("cloud-send-heads", taskId))?.attempt_id === attemptId) await write("cloud-send-heads", taskId, receipt);
+      return { ...receipt, delivery_verification: "not_sent", retry_safe: true, reservation_cleanup_required: false };
+    }
+    const snapshot = await read(taskId);
+    const matches = snapshot.turns.filter(turn => turn.role === "user" && turn.parent_turn_id === receipt.parent_turn_id
+      && turn.messages.some(message => createHash("sha256").update(message.text).digest("hex") === receipt.prompt_sha256));
+    if (matches.length !== 1) return { ...receipt, delivery_verification: "not_observed", retry_safe: false };
+    Object.assign(receipt, { submission_status: "accepted", delivery_verification: "stored", user_turn_id: matches[0].turn_id });
+    await write("cloud-messages", attemptId, receipt);
+    if ((await load("cloud-send-heads", taskId))?.attempt_id === attemptId) await write("cloud-send-heads", taskId, receipt);
+    return receipt;
+  });
+}