codexteer 0.18.2 → 0.20.0

package/src/cloud-cli.mjs

@@ -1,18 +1,22 @@
-import { desktopCloudProjectDoctor, assignDesktopCloudProject, desktopCloudProjectReceipt } from "./desktop-cloud-project.mjs";
+import { desktopCloudProjectDoctor, assignDesktopCloudProject, desktopCloudProjectReceipt, resolveDesktopCloudProjectAttempt } 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 { isCloudTask, selectedCloudInvocation } from "./task-id.mjs";
 import { cloudTaskId } from "./cloud-id.mjs";
+import { normalizeThreadId } from "./thread-id.mjs";
+import { connectionMismatch } from "./connection-error.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 { rejectRepeatedBinding } from "./prompt-command.mjs";
+import { rejectUnknownOptions } from "./unknown-options.mjs";
 import { supervisorId, registerSupervisor, getSupervisor, assertSupervisor, assertSupervisorRegistration, 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 { sendTrackedMessage, listMessages, getMessage, messageSummary, reconcileMessages, markMessage, resolveUnknownDelivery, 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";
@@ -24,7 +28,6 @@ import { createCheckpoint, listCheckpoints, getCheckpoint, checkpointSummary, ve
 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;
@@ -40,35 +43,26 @@ const repeated = (args, name) => { const result = []; let value; while ((value =
 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) {
+  rejectRepeatedBinding(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 targetId = desktopCloud ? desktopCloudId : value => {
+    try { return cloudTaskId(value); }
+    catch (error) {
+      // Preserve the Web Cloud ID validator's existing error code.
+      if (isDesktopCloudTask(value)) throw connectionMismatch("desktop-cloud", connection, error.code);
+      let local = false;
+      try { normalizeThreadId(value); local = true; } catch {}
+      if (local) throw connectionMismatch("shared", connection, error.code);
+      throw error;
+    }
+  };
+  if (!["cloud", "desktop-cloud"].includes(connection)) throw Object.assign(connectionMismatch(selectedCloudInvocation(argv) || "cloud", connection), { execution_environment: "cloud" });
   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");
@@ -159,11 +153,12 @@ export async function mainCloud(argv) {
       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") } : {};
+    const includeText = flag(args, "--include-text"), pending = flag(args, "--pending"), resolveUnknown = desktopCloud && action === "mark" && flag(args, "--resolve-unknown");
+    const report = resolveUnknown ? { note: option(args, "--note") } : 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.");
+    if (resolveUnknown && supervisor) throw failure("A supervisor cannot release its own unknown delivery. The user must run this without --supervisor.", "SUPERVISOR_CONTROL_FORBIDDEN");
     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);
+      : action === "check" ? await reconcileMessages(id, args[1], { includeText }, dependencies) : resolveUnknown ? await resolveUnknownDelivery(id, args[1], report) : await markMessage(id, args[1], report);
     output(`history.${action}`, data); return;
   }
   if (command === "instructions") {
@@ -225,7 +220,7 @@ export async function mainCloud(argv) {
     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 end = args.includes("--") ? args.indexOf("--") : args.length; rejectUnknownOptions(args.slice(0, end), "cloud creation", "Explicit model/title/permission overrides are not implemented yet.", failure);
     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.");
@@ -271,7 +266,7 @@ export async function mainCloud(argv) {
   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 --.");
+  rejectUnknownOptions(args.slice(0, end), "send", "Put instruction text that starts with -- after --.", failure);
   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);
@@ -296,11 +291,12 @@ async function desktopCloudCommands(command, args, { supervisor, output, bound,
     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.");
+      rejectUnknownOptions(args.slice(0, end), "Desktop Cloud creation", "Put an instruction that starts with -- after --.", failure);
       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);
+    const resolveUnknown = action === "receipt" && flag(args, "--resolve-unknown"), note = resolveUnknown ? option(args, "--note") : undefined; exact(args, 1);
+    if (resolveUnknown) { output("thread.receipt", await resolveDesktopCloudProjectAttempt(args[0], { note })); return true; }
     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.");

package/src/connection-error.mjs

@@ -0,0 +1,7 @@
+// Diagnostics only: callers retain their existing routing and rejection rules.
+export function connectionMismatch(expected, selected, code = "CLOUD_TARGET_CONFLICT") {
+  const message = expected === "shared"
+    ? `For a local task, use --connection shared (the default local connection; got ${selected}).`
+    : `This task requires --connection ${expected} (got ${selected}).`;
+  return Object.assign(new Error(message), { code, expected_connection: expected, connection: selected });
+}

package/src/cursor.mjs

@@ -0,0 +1,370 @@
+// The read cursor format. No other module builds or reads cursor bytes.
+//
+// token = "c1" base64url(check[8] body). The check is SHA-256 over the target
+// binding and the body. It is not a MAC: it binds the token to the thread, host
+// and transport without storing them, and rejects copy errors. Sends stay safe
+// because every --based-on and --since is re-validated against the live server.
+//
+// A v2 body commits to the turn list instead of listing it, so the token does
+// not grow with the thread. parseCursor needs no server and returns a claim.
+// resolveTurns checks the claim against the live turn list and rebuilds the
+// in-memory cursor that readPaged and verifyPagedFreshness use.
+import { createHash } from "node:crypto";
+import { hostFields, targetHost, remoteTransport } from "./target.mjs";
+
+const PREFIX = "c1", MAX_TOKEN = 1024 * 1024, MAX_POSITION = 16384;
+const RUNNING = ["inProgress", "running", "pending"];
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+const HASH = /^[a-f0-9]{64}$/;
+
+/** @typedef {{ kind: "none" } | { kind: "turn", index: number } | { kind: "inline", id: string }} TurnRef */
+/**
+ * What a v2 token proves about the turn list without listing it. `running` holds
+ * the status each running turn had when the token was made.
+ * @typedef {{ count: number, commitment: string | null, running: Map<number, string> }} TurnCommitment
+ */
+/**
+ * Offline view of a v2 cursor. It has no `turns`, so code that skips resolveTurns
+ * fails on first use instead of running a weaker check.
+ * @typedef {{ v: 2, turn_commitment: TurnCommitment, active_turn_id: string | null, state: string, pending: boolean,
+ *   head: { cursor: string | null, id: string | null, turn: TurnRef, hash: string | null }, last_public: string | null,
+ *   groups: { cursor: string | null, turn: TurnRef, count: number,
+ *     items: { index: number, id: string, turn: TurnRef, hash: string, mode: "running" | "tail" }[] }[] }} PagedClaim
+ */
+/**
+ * @typedef {{ v: 1, count: number, open: { index: number, hash: string }[], prefix: string, state: string,
+ *   active_turn_id: string | null, latest_turn_id?: string | null, user_revision?: string }} SnapshotCursor
+ */
+/**
+ * @typedef {{ v: 2, thread_id: string, turns: { id: string, status: string }[],
+ *   head: { cursor: string | null, id: string | null, turn_id: string | null, hash: string | null },
+ *   groups: { cursor: string | null, turn_id: string | null, count: number,
+ *     items: { index: number, id: string, turn_id: string, hash: string, mode: "running" | "tail" }[] }[],
+ *   last_public: string | null, state: string, active_turn_id: string | null, pending: boolean }} PagedCursor
+ */
+
+export function invalidCursor() { return Object.assign(new Error("Cursor is invalid or history changed. Read again without --since."), { code: "STALE_CURSOR" }); }
+
+/**
+ * @param {PagedCursor | SnapshotCursor} cursor
+ * @param {string} threadId
+ */
+export function encodeCursor(cursor, threadId) {
+  const w = new Writer();
+  if (cursor.v === 1) writeSnapshotBody(w, cursor); else writePagedBody(w, claimOf(cursor), threadId);
+  const body = w.done(), token = PREFIX + Buffer.concat([check(threadId, body), body]).toString("base64url");
+  // v1 is the --full-history fallback and has always been uncapped, so only the fast cursor is refused here.
+  if (cursor.v === 2 && token.length > MAX_TOKEN) throw Object.assign(new Error("Too many in-progress items for a fast cursor. Use --full-history."), { code: "CURSOR_TOO_LARGE" });
+  return token;
+}
+
+/**
+ * Parse without the server. Accepts "c1" tokens and the earlier base64url JSON tokens.
+ * @param {unknown} token
+ * @param {string} threadId
+ * @returns {PagedClaim | SnapshotCursor}
+ */
+export function parseCursor(token, threadId) {
+  try {
+    if (typeof token !== "string" || token.length > MAX_TOKEN) throw invalidCursor();
+    if (!token.startsWith(PREFIX)) return parseLegacy(token, threadId);
+    const text = token.slice(PREFIX.length), bytes = Buffer.from(text, "base64url");
+    // Node decodes base64url leniently, so only the canonical spelling of the bytes is accepted.
+    if (bytes.length < 9 || bytes.toString("base64url") !== text) throw invalidCursor();
+    const body = bytes.subarray(8);
+    if (!check(threadId, body).equals(bytes.subarray(0, 8))) throw invalidCursor();
+    const r = new Reader(body), version = r.byte();
+    if (version !== 1 && version !== 2) throw invalidCursor();
+    const claim = version === 1 ? readSnapshotBody(r) : readPagedBody(r, threadId);
+    r.end();
+    return claim;
+  } catch { throw invalidCursor(); }
+}
+
+/**
+ * Check a v2 claim against the live turn list and rebuild the cursor. Accepts a live
+ * list exactly when it extends the committed one with the same ids in order and every
+ * turn that was final keeps its status.
+ * @param {PagedClaim} claim
+ * @param {{ id: string, status: string }[]} liveTurns from turnMetadata, free of duplicates
+ * @param {string} threadId
+ * @returns {PagedCursor}
+ */
+export function resolveTurns(claim, liveTurns, threadId) {
+  const { count, commitment: expected, running } = claim.turn_commitment;
+  if (liveTurns.length < count) throw invalidCursor();
+  const prefix = liveTurns.slice(0, count);
+  if (count && commitment(prefix, running) !== expected) throw invalidCursor();
+  // A running turn keeps its observed status, so the next read reports its change.
+  const turns = prefix.map((t, i) => ({ id: t.id, status: running.get(i) ?? t.status }));
+  const turnId = ref => ref.kind === "none" ? null : ref.kind === "inline" ? ref.id : turns[ref.index].id;
+  return { v: 2, thread_id: threadId, turns,
+    head: { cursor: claim.head.cursor, id: claim.head.id, turn_id: turnId(claim.head.turn), hash: claim.head.hash },
+    groups: claim.groups.map(g => ({ cursor: g.cursor, turn_id: turnId(g.turn), count: g.count,
+      items: g.items.map(i => ({ index: i.index, id: i.id, turn_id: turnId(i.turn), hash: i.hash, mode: i.mode })) })),
+    last_public: claim.last_public, state: claim.state, active_turn_id: claim.active_turn_id, pending: claim.pending };
+}
+
+/**
+ * The output view of a stored record. Its based_on token becomes based_on_sha256,
+ * the hex SHA-256 of the token. Stored records keep the full token.
+ * @template {object} T
+ * @param {T} record
+ */
+export function withCursorReference(record) {
+  if (!record || !Object.hasOwn(record, "based_on")) return record;
+  return Object.fromEntries(Object.entries(record).map(([key, value]) => key !== "based_on" ? [key, value]
+    : ["based_on_sha256", typeof value === "string" ? createHash("sha256").update(value).digest("hex") : null]));
+}
+
+const check = (threadId, body) => createHash("sha256").update(JSON.stringify(["codexteer-cursor", threadId, hostFields()])).update(body).digest().subarray(0, 8);
+const commitment = (turns, running) => createHash("sha256").update(JSON.stringify(turns.map((t, i) => [t.id, running.has(i) ? null : t.status]))).digest("hex");
+
+/** @param {PagedCursor} cursor @returns {PagedClaim} */
+function claimOf(cursor) {
+  const index = new Map(cursor.turns.map((t, i) => [t.id, i]));
+  const running = new Map(cursor.turns.flatMap((t, i) => RUNNING.includes(t.status) ? [[i, t.status]] : []));
+  const turn = id => id === null ? { kind: "none" } : index.has(id) ? { kind: "turn", index: index.get(id) } : { kind: "inline", id };
+  const count = cursor.turns.length;
+  return { v: 2, turn_commitment: { count, commitment: count ? commitment(cursor.turns, running) : null, running },
+    active_turn_id: cursor.active_turn_id, state: cursor.state, pending: cursor.pending,
+    head: { cursor: cursor.head.cursor, id: cursor.head.id, turn: turn(cursor.head.turn_id), hash: cursor.head.hash },
+    last_public: cursor.last_public,
+    groups: cursor.groups.map(g => ({ cursor: g.cursor, turn: turn(g.turn_id), count: g.count,
+      items: g.items.map(i => ({ index: i.index, id: i.id, turn: turn(i.turn_id), hash: i.hash, mode: i.mode })) })) };
+}
+
+// v2 body: 0x02 flags count commitment? running active? state ids head last_public? groups.
+// Flags: 1 pending, 2 active turn, 4 head id, 8 head hash, 16 last public.
+function writePagedBody(w, claim, threadId) {
+  const { count, commitment, running } = claim.turn_commitment, { head } = claim;
+  const ids = [...new Set([head.id, claim.last_public, ...claim.groups.flatMap(g => g.items.map(i => i.id))].filter(id => id !== null))];
+  const idIndex = new Map(ids.map((id, i) => [id, i]));
+  w.byte(2);
+  w.byte((claim.pending ? 1 : 0) | (claim.active_turn_id !== null ? 2 : 0) | (head.id !== null ? 4 : 0) | (head.hash !== null ? 8 : 0) | (claim.last_public !== null ? 16 : 0));
+  w.uint(count);
+  if (count) w.hash(commitment);
+  w.uint(running.size);
+  let previous = -1;
+  for (const [index, status] of running) { w.uint(index - previous - 1); w.byte(RUNNING.indexOf(status)); previous = index; }
+  if (claim.active_turn_id !== null) writeId(w, claim.active_turn_id);
+  w.hash(claim.state);
+  w.uint(ids.length);
+  for (const id of ids) writeId(w, id);
+  writePosition(w, head.cursor, threadId);
+  if (head.id !== null) w.uint(idIndex.get(head.id));
+  writeTurn(w, head.turn);
+  if (head.hash !== null) w.hash(head.hash);
+  if (claim.last_public !== null) w.uint(idIndex.get(claim.last_public));
+  w.uint(claim.groups.length);
+  for (const group of claim.groups) {
+    writePosition(w, group.cursor, threadId); writeTurn(w, group.turn); w.uint(group.count); w.uint(group.items.length);
+    for (const item of group.items) {
+      // Most tracked items are the head itself, so their hash is one bit.
+      const same = item.hash === head.hash;
+      w.uint(item.index * 4 + (item.mode === "tail" ? 2 : 0) + (same ? 1 : 0)); w.uint(idIndex.get(item.id)); writeTurn(w, item.turn);
+      if (!same) w.hash(item.hash);
+    }
+  }
+}
+
+function readPagedBody(r, threadId) {
+  const flags = r.byte();
+  if (flags > 31) throw invalidCursor();
+  const count = r.uint(), commitment = count ? r.hash() : null, running = new Map();
+  for (let n = r.count(), index = -1; n > 0; n--) {
+    index += r.uint() + 1;
+    const status = RUNNING[r.byte()];
+    if (index >= count || !status) throw invalidCursor();
+    running.set(index, status);
+  }
+  const active_turn_id = flags & 2 ? readId(r) : null, state = r.hash(), ids = [];
+  for (let n = r.count(); n > 0; n--) ids.push(readId(r));
+  const id = () => { const k = r.uint(); if (k >= ids.length) throw invalidCursor(); return ids[k]; };
+  const head = { cursor: readPosition(r, threadId), id: flags & 4 ? id() : null, turn: readTurn(r, count), hash: flags & 8 ? r.hash() : null };
+  if (head.id !== null && head.cursor === null) throw invalidCursor();
+  const last_public = flags & 16 ? id() : null, groups = [];
+  for (let n = r.count(); n > 0; n--) {
+    const group = { cursor: readPosition(r, threadId), turn: readTurn(r, count), count: r.uint(), items: [] };
+    if (group.count < 1 || group.count > 100) throw invalidCursor();
+    for (let m = r.count(); m > 0; m--) {
+      const packed = r.uint(), index = Math.floor(packed / 4), same = packed % 2 === 1;
+      const item = { index, id: id(), turn: readTurn(r, count), hash: same ? head.hash : r.hash(), mode: packed % 4 >= 2 ? "tail" : "running" };
+      if (index >= group.count || item.hash === null || item.turn.kind === "none") throw invalidCursor();
+      group.items.push(item);
+    }
+    groups.push(group);
+  }
+  return { v: 2, turn_commitment: { count, commitment, running }, active_turn_id, state, pending: (flags & 1) === 1, head, last_public, groups };
+}
+
+// v1 body: 0x01 flags count open prefix state user_revision active? latest?
+// Flags: 1 active turn, 2 latest turn. readSnapshot always sets every field.
+function writeSnapshotBody(w, cursor) {
+  w.byte(1);
+  w.byte((cursor.active_turn_id !== null ? 1 : 0) | (cursor.latest_turn_id !== null ? 2 : 0));
+  w.uint(cursor.count); w.uint(cursor.open.length);
+  let previous = -1;
+  for (const { index, hash } of cursor.open) { w.uint(index - previous - 1); w.hash(hash); previous = index; }
+  w.hash(cursor.prefix); w.hash(cursor.state); w.hash(cursor.user_revision);
+  if (cursor.active_turn_id !== null) writeId(w, cursor.active_turn_id);
+  if (cursor.latest_turn_id !== null) writeId(w, cursor.latest_turn_id);
+}
+
+function readSnapshotBody(r) {
+  const flags = r.byte();
+  if (flags > 3) throw invalidCursor();
+  const count = r.uint(), open = [];
+  for (let n = r.count(), index = -1; n > 0; n--) {
+    index += r.uint() + 1;
+    if (index >= count) throw invalidCursor();
+    open.push({ index, hash: r.hash() });
+  }
+  const prefix = r.hash(), state = r.hash(), user_revision = r.hash();
+  const active_turn_id = flags & 1 ? readId(r) : null, latest_turn_id = flags & 2 ? readId(r) : null;
+  return { v: 1, count, open, prefix, state, active_turn_id, latest_turn_id, user_revision };
+}
+
+// An id is a tag and a payload: 0 a UUID, 1 a short prefix and a UUID, 2 a prefix and lowercase hex, 3 text.
+const ID_PARTS = /^([a-z]{1,16}[_-])?(.*)$/s;
+const uuid = bytes => bytes.toString("hex").replace(/^(.{8})(.{4})(.{4})(.{4})/, "$1-$2-$3-$4-");
+
+function writeId(w, id) {
+  if (UUID.test(id)) { w.byte(0); w.bytes(Buffer.from(id.replaceAll("-", ""), "hex")); return; }
+  const [, prefix = "", body] = ID_PARTS.exec(id);
+  if (prefix && UUID.test(body)) {
+    w.byte(1); w.text(prefix); w.bytes(Buffer.from(body.replaceAll("-", ""), "hex"));
+  } else if (/^(?:[0-9a-f]{2})+$/.test(body)) {
+    w.byte(2); w.text(prefix); w.uint(body.length / 2); w.bytes(Buffer.from(body, "hex"));
+  } else { w.byte(3); w.text(id); }
+}
+
+function readId(r) {
+  const tag = r.byte();
+  if (tag === 0) return uuid(r.bytes(16));
+  if (tag === 1) return r.text() + uuid(r.bytes(16));
+  if (tag === 2) return r.text() + r.bytes(r.uint()).toString("hex");
+  if (tag === 3) return r.text();
+  throw invalidCursor();
+}
+
+// App Server positions are kept byte for byte. The known form is stored as an
+// ordinal only when rendering it back reproduces the server's exact string, so
+// codexteer never synthesizes a position and a format change only costs size.
+// Tags: 0 null, 1 known form with includeAnchor true, 2 with false, 3 the exact text.
+const position = (threadId, rolloutOrdinal, includeAnchor) => JSON.stringify({ requestedThreadId: threadId, rolloutOrdinal, includeAnchor, scope: { kind: "itemsByCreatedAtOrdinal" } });
+
+function writePosition(w, value, threadId) {
+  if (value === null) return w.byte(0);
+  let known = null;
+  try { known = JSON.parse(value); } catch { /* Not JSON, so it is stored as text. */ }
+  if (Number.isSafeInteger(known?.rolloutOrdinal) && known.rolloutOrdinal >= 0 && typeof known.includeAnchor === "boolean"
+    && position(threadId, known.rolloutOrdinal, known.includeAnchor) === value) {
+    w.byte(known.includeAnchor ? 1 : 2); w.uint(known.rolloutOrdinal);
+  } else { w.byte(3); w.text(value); }
+}
+
+function readPosition(r, threadId) {
+  const tag = r.byte();
+  if (tag === 0) return null;
+  if (tag === 1 || tag === 2) return position(threadId, r.uint(), tag === 1);
+  if (tag !== 3) throw invalidCursor();
+  const value = r.text();
+  if (value.length >= MAX_POSITION) throw invalidCursor();
+  return value;
+}
+
+// A turn reference: 0 none, 1 an inline id, k + 2 the committed turn k.
+function writeTurn(w, ref) {
+  if (ref.kind === "none") w.uint(0);
+  else if (ref.kind === "inline") { w.uint(1); writeId(w, ref.id); }
+  else w.uint(ref.index + 2);
+}
+
+function readTurn(r, count) {
+  const n = r.uint();
+  if (n === 0) return { kind: "none" };
+  if (n === 1) return { kind: "inline", id: readId(r) };
+  if (n - 2 >= count) throw invalidCursor();
+  return { kind: "turn", index: n - 2 };
+}
+
+// The earlier format, base64url(JSON). These are the 0.19 decoder's checks, plus
+// lowercase-hex v1 hashes, which every earlier encoder wrote and the v1 encoder needs.
+function parseLegacy(token, threadId) {
+  const c = JSON.parse(Buffer.from(token, "base64url").toString());
+  if ((c.host_id ?? "local") !== targetHost()) throw invalidCursor();
+  if (targetHost() !== "local" && (c.remote_transport ?? "native") !== remoteTransport()) throw invalidCursor();
+  if (c?.v === 2) {
+    const hash = x => x === null || (typeof x === "string" && HASH.test(x));
+    const pos = x => x === null || (typeof x === "string" && x.length < MAX_POSITION);
+    if (c.thread_id !== threadId || typeof c.state !== "string" || !Array.isArray(c.turns) || !Array.isArray(c.groups)
+      || !c.turns.every(t => typeof t.id === "string" && typeof t.status === "string")
+      || new Set(c.turns.map(t => t.id)).size !== c.turns.length
+      || !c.head || !pos(c.head.cursor) || !hash(c.head.hash) || !(c.head.id === null || typeof c.head.id === "string")
+      || !(c.head.turn_id === null || typeof c.head.turn_id === "string") || (c.head.id !== null && c.head.cursor === null)
+      || !(c.last_public === null || typeof c.last_public === "string")
+      || !(c.active_turn_id === null || typeof c.active_turn_id === "string") || typeof c.pending !== "boolean"
+      || !c.groups.every(g => pos(g.cursor) && (g.turn_id === null || typeof g.turn_id === "string") && Number.isInteger(g.count) && g.count > 0 && g.count <= 100
+        && Array.isArray(g.items) && g.items.every(i => Number.isInteger(i.index) && i.index >= 0 && i.index < g.count && typeof i.id === "string" && typeof i.turn_id === "string" && hash(i.hash) && ["running", "tail"].includes(i.mode)))) throw invalidCursor();
+    return claimOf(c);
+  }
+  if (c.v !== 1 || c.thread_id !== threadId || !Number.isSafeInteger(c.count) || c.count < 0 || !Array.isArray(c.open)
+    || !c.open.every(x => Number.isSafeInteger(x.index) && x.index >= 0 && x.index < c.count && typeof x.hash === "string" && HASH.test(x.hash))
+    || new Set(c.open.map(x => x.index)).size !== c.open.length || typeof c.prefix !== "string"
+    || !(c.latest_turn_id === undefined || c.latest_turn_id === null || (typeof c.latest_turn_id === "string" && c.latest_turn_id))) throw invalidCursor();
+  return c;
+}
+
+class Writer {
+  #parts = [];
+  byte(value) { this.#parts.push(Buffer.of(value)); }
+  // Every integer in a cursor is a count, an index or an ordinal. Anything else is a bug that must not be written.
+  uint(value) {
+    if (!Number.isSafeInteger(value) || value < 0) throw new Error("A cursor integer must be a non-negative safe integer.");
+    const out = [];
+    for (; value >= 128; value = Math.floor(value / 128)) out.push(value % 128 | 128);
+    out.push(value);
+    this.#parts.push(Buffer.from(out));
+  }
+  bytes(value) { this.#parts.push(value); }
+  hash(hex) {
+    if (!HASH.test(hex)) throw new Error("A cursor hash must be 64 lowercase hex characters.");
+    this.#parts.push(Buffer.from(hex, "hex"));
+  }
+  // UTF-8 cannot carry a lone surrogate, so such text is stored as its JSON spelling, marked by the low bit.
+  text(value) {
+    const json = !value.isWellFormed(), bytes = Buffer.from(json ? JSON.stringify(value) : value);
+    this.uint(bytes.length * 2 + (json ? 1 : 0)); this.bytes(bytes);
+  }
+  done() { return Buffer.concat(this.#parts); }
+}
+
+// Every read is bounded by the buffer: a length or count larger than the bytes left fails before any allocation.
+class Reader {
+  #buffer; #at = 0;
+  constructor(buffer) { this.#buffer = buffer; }
+  get #left() { return this.#buffer.length - this.#at; }
+  byte() { if (!this.#left) throw invalidCursor(); return this.#buffer[this.#at++]; }
+  uint() {
+    let value = 0;
+    for (let k = 0, scale = 1; k < 8; k++, scale *= 128) {
+      const x = this.byte();
+      value += (x & 127) * scale;
+      if (x < 128) { if (!Number.isSafeInteger(value)) throw invalidCursor(); return value; }
+    }
+    throw invalidCursor();
+  }
+  // Each counted element takes at least one byte.
+  count() { const n = this.uint(); if (n > this.#left) throw invalidCursor(); return n; }
+  bytes(n) { if (n > this.#left) throw invalidCursor(); return this.#buffer.subarray(this.#at, this.#at += n); }
+  hash() { return this.bytes(32).toString("hex"); }
+  text() {
+    const n = this.uint(), raw = this.bytes(Math.floor(n / 2)).toString();
+    if (n % 2 === 0) return raw;
+    const value = JSON.parse(raw);
+    if (typeof value !== "string") throw invalidCursor();
+    return value;
+  }
+  end() { if (this.#left) throw invalidCursor(); }
+}

package/src/desktop-cloud-id.mjs

@@ -1,11 +1,19 @@
 import { normalizeThreadId } from "./thread-id.mjs";
+import { isCloudTask } from "./cloud-id.mjs";
+import { connectionMismatch } from "./connection-error.mjs";
 export function isDesktopCloudTask(value) {
   if (typeof value !== "string") return false;
   if (value.startsWith("durable_")) return true;
   try { const u = new URL(value); return u.protocol === "codex:" && u.hostname === "threads" && u.searchParams.getAll("hostId").includes("durable"); } catch { return false; }
 }
 export function desktopCloudId(value) {
-  if (!isDesktopCloudTask(value)) throw Object.assign(new Error("Desktop Cloud requires a durable_ ID or a link with hostId=durable."), { code: "CLOUD_TARGET_CONFLICT" });
+  if (!isDesktopCloudTask(value)) {
+    if (isCloudTask(value)) throw connectionMismatch("cloud", "desktop-cloud");
+    let local = false;
+    try { normalizeThreadId(value); local = true; } catch {}
+    if (local) throw connectionMismatch("shared", "desktop-cloud");
+    throw Object.assign(new Error("Desktop Cloud requires a durable_ ID or a link with hostId=durable."), { code: "CLOUD_TARGET_CONFLICT" });
+  }
   let uuid = value.slice(8);
   if (!value.startsWith("durable_")) {
     const url = new URL(value);

package/src/desktop-cloud-project.mjs

@@ -13,6 +13,7 @@ import { listProjects } from "./projects.mjs";
 import { listRecords, readRecord, writeRecord, withStoreLock, storePath } from "./store.mjs";
 const failure = (message, code = "DESKTOP_CLOUD_PROJECT_UNAVAILABLE", uncertain = false) => Object.assign(new Error(message), { code, uncertain });
 const sha = value => createHash("sha256").update(value).digest("hex");
+const shows = (state, projectId) => state?.assignment?.projectKind === "local" && state.assignment.projectId === projectId && state.host_id === "durable";
 
 export async function discoverProjectApi({ discover = discoverRuntime, endpoint = discoverNativeEndpoint, run = spawnSync } = {}) {
   const selected = await discover(), { state } = selected;
@@ -100,7 +101,7 @@ export async function desktopCloudProjectDoctor(target, selector, { connect = co
     const state = await readState(api.paths.home, id);
     report.membership = { status: state.assignment?.projectKind === "local" ? (state.host_id === "durable" ? "registered" : "recorded_host_unverified") : state.projectless ? "projectless" : "source_unknown",
       project_id: state.assignment?.projectId ?? null, host_id: state.host_id, source: "read-only-desktop-profile-state" };
-    if (selected) report.membership.matches_selected_project = state.assignment?.projectKind === "local" && state.assignment.projectId === selected.project_id && state.host_id === "durable";
+    if (selected) report.membership.matches_selected_project = shows(state, selected.project_id);
     return report;
   } finally { try { client?.close(); } catch { /* Preserve diagnostics. */ } }
 }
@@ -109,7 +110,9 @@ export async function assignDesktopCloudProject(target, selector, { connect = co
   const id = desktopCloudId(target);
   if (typeof selector !== "string" || !selector.trim()) throw failure("--project is required.", "PROJECT_REQUIRED");
   return withStoreLock(`desktop-cloud-project-${id}`, async () => {
-    if ((await listRecords("desktop-cloud-projects", storage)).some(row => row.thread_id === id && row.delivery_status === "unknown")) throw failure("An earlier assignment is unknown. Inspect its receipt; do not replay it.", "DESKTOP_CLOUD_PROJECT_PENDING");
+    const pending = (await confirmFromState(id, (await listRecords("desktop-cloud-projects", storage)).filter(row => row.thread_id === id && row.delivery_status === "unknown"), readState, storage)).find(row => !row.resolution);
+    if (pending) throw Object.assign(failure(`An earlier assignment is unknown and is never replayed. Run thread receipt ${pending.attempt_id} --connection desktop-cloud to recheck Desktop's profile state; if it stays unknown, the user (not a supervisor) can release it with --resolve-unknown --note TEXT.`, "DESKTOP_CLOUD_PROJECT_PENDING"),
+      { existing_attempt_id: pending.attempt_id, existing_receipt_path: pending.receipt_path });
     let client, receipt, api, dispatching = false;
     try {
       client = await connect(); const environmentId = await targetEnvironment(client, id); api = await discoverApi();
@@ -129,7 +132,7 @@ export async function assignDesktopCloudProject(target, selector, { connect = co
       receipt.delivery_status = "accepted"; receipt.proof_sha256 = sha(response.payload);
       await writeRecord("desktop-cloud-projects", attempt, receipt, storage); await check(api);
       const stored = await readState(api.paths.home, id);
-      receipt.verification_status = stored.assignment?.projectKind === "local" && stored.assignment.projectId === selected.project_id && stored.host_id === "durable" ? "verified" : "not_observed";
+      receipt.verification_status = shows(stored, selected.project_id) ? "verified" : "not_observed";
       await writeRecord("desktop-cloud-projects", attempt, receipt, storage); return receipt;
     } catch (error) {
       if (receipt) {
@@ -141,8 +144,38 @@ export async function assignDesktopCloudProject(target, selector, { connect = co
     } finally { try { client?.close(); } catch { /* Preserve diagnostics. */ } }
   }, storage);
 }
-export async function desktopCloudProjectReceipt(attempt, storage = {}) {
+// Absence from Desktop state never proves the assignment was not applied, so
+// only a positive observation rewrites an unknown attempt.
+async function confirmFromState(id, rows, readState, storage) {
+  if (!rows.length) return rows;
+  let state; try { state = await readState(storage.home ?? codexHome(), id); } catch { return rows; }
+  const remaining = [];
+  for (const row of rows) {
+    if (!shows(state, row.project_id)) { remaining.push(row); continue; }
+    await writeRecord("desktop-cloud-projects", row.attempt_id, { ...row, delivery_status: "accepted", verification_status: "verified", delivery_verification: "desktop-profile-state", verified_at: new Date().toISOString() }, storage);
+  }
+  return remaining;
+}
+async function readAttempt(attempt, storage) {
   if (typeof attempt !== "string" || !/^[a-f0-9]{8}(?:-[a-f0-9]{4}){3}-[a-f0-9]{12}$/.test(attempt)) throw failure("Invalid assignment attempt ID.");
   const row = await readRecord("desktop-cloud-projects", attempt, storage);
   if (!row || row.type !== "desktop-cloud-project" || row.attempt_id !== attempt) throw failure("Assignment receipt not found."); return row;
 }
+export async function desktopCloudProjectReceipt(attempt, { readState = readDesktopProjectState, ...storage } = {}) {
+  const row = await readAttempt(attempt, storage);
+  if (row.delivery_status !== "unknown") return row;
+  return withStoreLock(`desktop-cloud-project-${row.thread_id}`, async () => {
+    await confirmFromState(row.thread_id, [await readAttempt(attempt, storage)].filter(current => current.delivery_status === "unknown"), readState, storage);
+    return readAttempt(attempt, storage);
+  }, storage);
+}
+export async function resolveDesktopCloudProjectAttempt(attempt, { note, ...storage } = {}) {
+  if (typeof note !== "string" || !note.trim()) throw failure("--resolve-unknown requires a non-empty --note.", "DESKTOP_CLOUD_OPTIONS_INVALID");
+  const { thread_id: id } = await readAttempt(attempt, storage);
+  return withStoreLock(`desktop-cloud-project-${id}`, async () => {
+    const row = await readAttempt(attempt, storage);
+    if (row.delivery_status !== "unknown" || row.resolution) throw failure("This assignment attempt has no unresolved unknown delivery.", "DESKTOP_CLOUD_OPTIONS_INVALID");
+    const updated = { ...row, resolution: { by: "user", at: new Date().toISOString(), note } };
+    await writeRecord("desktop-cloud-projects", attempt, updated, storage); return updated;
+  }, storage);
+}