codexteer 0.18.1 → 0.19.0

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

package/src/desktop-cloud.mjs

@@ -52,8 +52,8 @@ export async function sendDesktopCloudInput(target, text, { dryRun = false, newT
   const plan = { thread_id: id, deep_link: desktopCloudLink(id), client_message_id: clientMessageId, backend: "desktop-cloud", connection_mode: "desktop-cloud", delivery_action: newTurn ? "new-turn" : "steer", dry_run: dryRun, message_characters: [...text].length };
   if (dryRun) return { ...plan, sent: false, delivery_status: "not_sent" };
   return withStoreLock(`desktop-cloud-send-${id}`, async () => {
-    const pending = (await listRecords("desktop-cloud-sends", storage)).find(row => row.thread_id === id && row.delivery_status === "unknown");
-    if (pending) throw failure("An earlier Desktop Cloud delivery is unknown. Inspect history; it must not be replayed automatically.", "DESKTOP_CLOUD_DELIVERY_PENDING");
+    const pending = (await listRecords("desktop-cloud-sends", storage)).find(row => row.thread_id === id && row.delivery_status === "unknown" && !row.resolution);
+    if (pending) throw Object.assign(failure(`An earlier Desktop Cloud delivery is unknown and is never replayed automatically. Run history check ${id} ${pending.client_message_id}; if it stays unconfirmed, the user (not a supervisor) can release it with history mark ${id} ${pending.client_message_id} --resolve-unknown --note TEXT.`, "DESKTOP_CLOUD_DELIVERY_PENDING"), { existing_message_id: pending.client_message_id });
     let client, dispatching = false, receipt = { ...plan, prompt_sha256: hash(text), sent: false, delivery_status: "not_sent" };
     const save = () => writeRecord("desktop-cloud-sends", clientMessageId, receipt, storage);
     try {
@@ -96,3 +96,11 @@ export async function confirmDesktopCloudDelivery(entry, verification, storage =
     await writeRecord("desktop-cloud-sends", entry.client_message_id, { ...receipt, delivery_status: "accepted", sent: true, turn_id: verification.turn_id, delivery_verification: "stored" }, storage);
   }, storage);
 }
+export async function resolveDesktopCloudDelivery(target, clientMessageId, resolution, storage = {}) {
+  const id = desktopCloudId(target);
+  return withStoreLock(`desktop-cloud-send-${id}`, async () => {
+    const receipt = await readRecord("desktop-cloud-sends", clientMessageId, storage);
+    if (receipt?.thread_id !== id || receipt.delivery_status !== "unknown" || receipt.resolution) throw failure("This message has no unresolved unknown Desktop Cloud delivery.");
+    const updated = { ...receipt, resolution }; await writeRecord("desktop-cloud-sends", clientMessageId, updated, storage); return updated;
+  }, storage);
+}

package/src/desktop.mjs

@@ -61,7 +61,7 @@ export function openDesktopThread(threadId, { focusComposer = false, prompt, bac
   const deepLink = focusComposer ? threadComposerDeepLink(threadId, prompt) : threadDeepLink(threadId);
   const result = run(OPEN, buildOpenArgs(deepLink, { background }));
   if (result.status !== 0) {
-    throw new Error(result.stderr.trim() || `Failed to open ${deepLink}`);
+    throw Object.assign(new Error(result.stderr.trim() || `Failed to open ${deepLink}`), { code: "DESKTOP_UI_FAILED" });
   }
   return {
     thread_id: threadId,
@@ -74,7 +74,7 @@ export function openDesktopThread(threadId, { focusComposer = false, prompt, bac
 
 function validateWaitMs(waitMs) {
   if (!Number.isInteger(waitMs) || waitMs < 0 || waitMs > 30000) {
-    throw new Error("--wait-ms must be an integer between 0 and 30000.");
+    throw Object.assign(new Error("--wait-ms must be an integer between 0 and 30000."), { code: "OPTIONS_INVALID" });
   }
 }
 
@@ -85,7 +85,7 @@ function requireReadyDesktop() {
     .filter(([, ok]) => !ok)
     .map(([name]) => name)
     .join(", ");
-  throw new Error(`Desktop backend is not ready: ${missing}. ${doctor.remediation ?? ""}`.trim());
+  throw Object.assign(new Error(`Desktop backend is not ready: ${missing}. ${doctor.remediation ?? ""}`.trim()), { code: "DESKTOP_UI_NOT_READY" });
 }
 
 function frontmostProcessId() {
@@ -96,7 +96,7 @@ function frontmostProcessId() {
   if (result.error) throw result.error;
   const processId = Number.parseInt(result.stdout.trim(), 10);
   if (result.status !== 0 || !Number.isInteger(processId) || processId < 1) {
-    throw new Error(result.stderr.trim() || "Could not identify the previously focused application.");
+    throw Object.assign(new Error(result.stderr.trim() || "Could not identify the previously focused application."), { code: "DESKTOP_UI_FAILED" });
   }
   return processId;
 }
@@ -105,7 +105,7 @@ function enableDesktopAccessibility() {
   const result = run(OSASCRIPT, [ACCESSIBILITY_SCRIPT, "enable"], { timeout: 5000 });
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(result.stderr.trim() || "Could not enable the Codex accessibility tree.");
+    throw Object.assign(new Error(result.stderr.trim() || "Could not enable the Codex accessibility tree."), { code: "DESKTOP_UI_FAILED" });
   }
   return result.stdout.trim() || "unchanged";
 }
@@ -115,7 +115,7 @@ function restoreDesktopAccessibility(mode) {
   const result = run(OSASCRIPT, [ACCESSIBILITY_SCRIPT, "restore", mode], { timeout: 5000 });
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(result.stderr.trim() || "Could not restore the Codex accessibility state.");
+    throw Object.assign(new Error(result.stderr.trim() || "Could not restore the Codex accessibility state."), { code: "DESKTOP_UI_FAILED" });
   }
 }
 
@@ -134,7 +134,7 @@ export function inspectDesktopUi(threadId, { waitMs = 1500 } = {}) {
   }
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(result.stderr.trim() || "Could not inspect the Codex Desktop UI.");
+    throw Object.assign(new Error(result.stderr.trim() || "Could not inspect the Codex Desktop UI."), { code: "DESKTOP_UI_FAILED" });
   }
   return {
     thread_id: threadId,
@@ -181,7 +181,7 @@ export function sendDesktopMessage(
   { dryRun = false, waitMs = 1500, newTurn = false, keepFocus = false } = {},
 ) {
   if ((parseThreadTarget(threadId).hostId ?? targetHost()) !== "local") throw remoteReadOnly();
-  if (message.trim() === "") throw new Error("Message must not be empty.");
+  if (message.trim() === "") throw Object.assign(new Error("Message must not be empty."), { code: "OPTIONS_INVALID" });
   validateWaitMs(waitMs);
 
   const desktopSettings = readDesktopSettings();
@@ -202,7 +202,7 @@ export function sendDesktopMessage(
   });
   if (result.error) throw result.error;
   if (result.status !== 0) {
-    throw new Error(result.stderr.trim() || "Codex Desktop did not accept the steering message.");
+    throw Object.assign(new Error(result.stderr.trim() || "Codex Desktop did not accept the steering message."), { code: "DESKTOP_UI_FAILED" });
   }
 
   return { ...plan, dry_run: false, sent: null, delivery_status: "submitted_unverified" };

package/src/directive.mjs

@@ -11,10 +11,10 @@ export async function prepareDirective(threadId, body, options, id, storage = {}
   if (!source && !kind && !evidence.length && !basedOn && !supersedes && !retracts && !expiresAt && !checkpoint && !finding && !supervisor) return { wireText: body, metadata: null };
   const concern = finding ? await assertFindingSend(threadId, finding, storage) : null;
   if (checkpoint) await getCheckpoint(threadId, checkpoint, storage);
-  if (supersedes && retracts) throw new Error("Use either supersedes or retracts, not both.");
-  if (expiresAt && (!/(Z|[+-]\d{2}:\d{2})$/.test(expiresAt) || !Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= Date.now())) throw new Error("--expires-at must be a future ISO timestamp with timezone.");
-  if (kind && !Object.hasOwn(kindLabels, kind)) throw new Error("--kind must be decision, review, hypothesis, or suggestion.");
-  if (source != null && (!source.trim() || source.length > 80 || /[\r\n\x00-\x1f]/.test(source))) throw new Error("--source must be a non-empty single line (up to 80 characters).");
+  if (supersedes && retracts) throw Object.assign(new Error("Use either supersedes or retracts, not both."), { code: "OPTIONS_INVALID" });
+  if (expiresAt && (!/(Z|[+-]\d{2}:\d{2})$/.test(expiresAt) || !Number.isFinite(Date.parse(expiresAt)) || Date.parse(expiresAt) <= Date.now())) throw Object.assign(new Error("--expires-at must be a future ISO timestamp with timezone."), { code: "OPTIONS_INVALID" });
+  if (kind && !Object.hasOwn(kindLabels, kind)) throw Object.assign(new Error("--kind must be decision, review, hypothesis, or suggestion."), { code: "OPTIONS_INVALID" });
+  if (source != null && (!source.trim() || source.length > 80 || /[\r\n\x00-\x1f]/.test(source))) throw Object.assign(new Error("--source must be a non-empty single line (up to 80 characters)."), { code: "OPTIONS_INVALID" });
   const observed = basedOn ? decodeCursor(basedOn, threadId) : null;
   const refs = await collectEvidence(evidence);
   const metadata = { source: source ?? "external", kind: kind ?? "review", evidence: refs, based_on: basedOn ?? null, supersedes: supersedes ?? null, retracts: retracts ?? null, expires_at: expiresAt ?? null, checkpoint_id: checkpoint ?? null,

package/src/evidence.mjs

@@ -8,11 +8,11 @@ import { remoteFingerprintFile } from "./remote-io.mjs";
 export async function fingerprintFile(input) {
   if (targetHost() !== "local") return remoteFingerprintFile(input);
   const ref = path.resolve(input), canonical = await realpath(ref), before = await stat(canonical);
-  if (!before.isFile()) throw new Error("Evidence must be a file or an http(s)/codex URL.");
+  if (!before.isFile()) throw Object.assign(new Error("Evidence must be a file or an http(s)/codex URL."), { code: "OPTIONS_INVALID" });
   const hash = createHash("sha256");
   for await (const data of createReadStream(canonical)) hash.update(data);
   const after = await stat(canonical);
-  if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || (await realpath(ref)) !== canonical) throw new Error("File changed while being fingerprinted. Try again after editing finishes.");
+  if (before.size !== after.size || before.mtimeMs !== after.mtimeMs || before.ctimeMs !== after.ctimeMs || (await realpath(ref)) !== canonical) throw Object.assign(new Error("File changed while being fingerprinted. Try again after editing finishes."), { code: "STALE_EVIDENCE" });
   return { type: "file", ref, path: canonical, size: after.size, mode: after.mode & 0o777, sha256: hash.digest("hex") };
 }
 
@@ -20,7 +20,7 @@ export async function collectEvidence(refs = []) {
   return Promise.all(refs.map(async ref => {
     if (/^(https?|codex):\/\//i.test(ref)) {
       const url = new URL(ref);
-      if (url.username || url.password) throw new Error("Evidence URLs must not contain credentials.");
+      if (url.username || url.password) throw Object.assign(new Error("Evidence URLs must not contain credentials."), { code: "OPTIONS_INVALID" });
       return { type: "url", ref: url.href, verification: "reference_only" };
     }
     return fingerprintFile(ref);

package/src/findings.mjs

@@ -46,12 +46,15 @@ export async function createFinding(threadInput, { key, title, condition, eviden
   }, storage);
 }
 
+// The user's noted resolution of an unknown delivery releases it; absence alone never does.
+export const releasedDelivery = entry => entry.delivery_status === "unknown" && Boolean(entry.resolution);
+
 export async function assertFindingSend(threadInput, id, storage = {}) {
   const record = await getFinding(threadInput, id, storage);
   if (record.disposition !== "open") throw failure("This finding is closed. Reopen it with new evidence or a changed requirement before sending again.", "FINDING_CLOSED");
   // The journal is the reservation: even a crash before writing a receipt leaves
   // an unknown attempt here. Never infer not-sent from a missing response.
-  const previous = (await findingMessages(record, storage)).find(message => message.delivery_status !== "not_sent");
+  const previous = (await findingMessages(record, storage)).find(message => message.delivery_status !== "not_sent" && !releasedDelivery(message));
   if (previous) throw Object.assign(failure("This finding revision already has a pending or accepted intervention. Check its history; do not resend it.", "DUPLICATE_INTERVENTION"), { existing_message_id: previous.id });
   return record;
 }
@@ -60,7 +63,7 @@ export async function findingStatus(threadInput, id, storage = {}) {
   const record = await getFinding(threadInput, id, storage), entries = await findingMessages(record, storage);
   const messages = entries.map(entry => ({ id: entry.id, delivery_status: entry.delivery_status, attempt_state: entry.attempt_state,
     response: entry.response, stored: entry.verification?.status ?? "unchecked" }));
-  const latest = entries.filter(entry => entry.delivery_status !== "not_sent").at(-1);
+  const latest = entries.filter(entry => entry.delivery_status !== "not_sent" && !releasedDelivery(entry)).at(-1);
   let status = record.disposition, verification = null;
   if (record.disposition === "open" && latest) status = latest.delivery_status === "unknown" ? "delivery_unknown"
     : latest.response?.status === "applied" ? "awaiting_verification" : "awaiting_response";
@@ -100,7 +103,7 @@ async function changeFinding(threadInput, id, update, storage) {
 }
 
 async function knownDelivery(record, storage) {
-  if ((await findingMessages(record, storage)).some(entry => entry.delivery_status === "unknown")) throw failure("Delivery is unknown. Reconcile the existing message before closing or revising this finding.", "FINDING_DELIVERY_UNKNOWN");
+  if ((await findingMessages(record, storage)).some(entry => entry.delivery_status === "unknown" && !releasedDelivery(entry))) throw failure("Delivery is unknown. Reconcile the existing message before closing or revising this finding.", "FINDING_DELIVERY_UNKNOWN");
 }
 
 export async function resolveFinding(threadInput, id, { checkpoint, note, ...storage }) {