@bitkyc08/opencodex 2.83.0 → 2.86.0

package/src/server/management/codex-prompt-routes.ts

@@ -30,11 +30,14 @@ import {
   composeProjection,
   computePromptProbeStateFingerprint,
   findInvalidCharacter,
+  importBaseVariant,
   inspectOwnership,
   normalizeBody,
   previewAdopt,
+  previewBaseImport,
   previewSalvage,
   readPromptLayers,
+  recoverPromptJournal,
   salvageProjection,
   selectBaseVariant,
   setToggle,
@@ -76,6 +79,7 @@ const WRITE_ERROR_STATUS: Record<WriteError, number> = {
   unknown_layer: 400,
   store_unreadable: 409,
   invalid_characters: 400,
+  body_too_large: 400,
   write_superseded: 409,
   // Not the caller's fault and not a race: the filesystem refused the write and the
   // transaction rolled itself back. 500 rather than 409 — retrying the same request
@@ -84,6 +88,8 @@ const WRITE_ERROR_STATUS: Record<WriteError, number> = {
   recovery_required: 409,
   locked: 409,
   unsafe: 422,
+  import_body_changed: 409,
+  unsupported_form: 409,
 };
 
 /** Read-only view for the route test that asserts every mapping is a client error. */
@@ -335,7 +341,12 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
     if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
     const id = body.id;
     if (typeof id !== "string") return fail(ctx, "invalid_body", 400, "id must be a string");
-    if (typeof body.enabled !== "boolean") return fail(ctx, "invalid_body", 400, "enabled must be a boolean");
+    // `null` is the restore-the-default verb: it deletes the line instead of
+    // writing the documented default back as a literal, so a later upstream
+    // change to the default still reaches this file.
+    if (typeof body.enabled !== "boolean" && body.enabled !== null) {
+      return fail(ctx, "invalid_body", 400, "enabled must be a boolean or null");
+    }
     const revision = revisionOf(body);
     if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
 
@@ -388,6 +399,109 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
     return settle(ctx, selectBaseVariant(selection, revision, paths(ctx)));
   }
 
+  if (url.pathname === "/api/codex-prompt/base/import" && req.method === "POST") {
+    // The adopt flow for `model_instructions_file`: preview first, write only on
+    // confirmation. The verb exists because /base/select refuses the `external`
+    // state by design — that refusal is about SILENT retargeting, and an
+    // explicit, previewed import is precisely the opt-in it protects.
+    //
+    // The preview carries the SERIALIZED variant file — `# {title}\n{body}` —
+    // not just the body: the heading is part of what Codex will read, so the
+    // thing confirmed must be the whole stored text, title included. Both byte
+    // counts are reported and separately named: `bodyBytes` is the budget the
+    // 64 KiB cap applies to, `serializedBytes` is the complete file.
+    const body = await readBody(ctx);
+    if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
+    const readState = readPromptLayers(paths(ctx));
+    if (!readState.readable) {
+      return fail(ctx, "config_unreadable", 409, "the configuration file exists but could not be read", { path: readState.configPath });
+    }
+    // The title is validated before anything is previewed or written: a caller
+    // that supplies one gets the same contract as a custom-layer title —
+    // 1-80 characters on a single line.
+    if (body.title !== undefined) {
+      const t = body.title;
+      if (typeof t !== "string" || t.trim().length === 0
+        || t.length > MAX_TITLE_CHARS || /[\r\n]/.test(t)) {
+        return fail(ctx, "invalid_title", 400, "title must be 1-80 characters on a single line");
+      }
+    }
+    const preview = previewBaseImport(paths(ctx), typeof body.title === "string" ? body.title : undefined);
+    if (preview.reason === "nothing_to_import") {
+      return fail(ctx, "nothing_to_import", 409,
+        "model_instructions_file is absent or already points at a managed variant");
+    }
+    if (preview.reason === "unsupported_form") {
+      return fail(ctx, "import_unsupported_form", 409, preview.detail, {
+        path: preview.rawPath,
+      });
+    }
+    if (preview.reason === "file_unreadable") {
+      return fail(ctx, "import_file_unreadable", 409, preview.detail, {
+        path: preview.resolvedPath ?? preview.rawPath,
+      });
+    }
+    if (preview.reason === "invalid_characters") {
+      return fail(ctx, "invalid_characters", 400, preview.detail, { path: preview.resolvedPath });
+    }
+    // Same boundary as every other write to this key: the 64 KiB cap applies to
+    // the BODY alone — the title heading lives outside that budget, unchanged
+    // from the managed-variant contract.
+    if (preview.reason === "body_too_large" || utf8Bytes(preview.body!) > MAX_BODY_BYTES) {
+      return fail(ctx, "body_too_large", 400, `the file body exceeds ${MAX_BODY_BYTES} bytes`, {
+        path: preview.resolvedPath,
+      });
+    }
+    if (preview.reason === "slots_full") {
+      return fail(ctx, "variant_slots_full", 409,
+        `at most ${MAX_BASE_VARIANTS} base variants; delete one first`, {
+          maxBaseVariants: MAX_BASE_VARIANTS,
+          serialized: preview.serialized,
+          resolvedPath: preview.resolvedPath,
+        });
+    }
+    if (body.confirm !== true) {
+      // Preview writes nothing, by construction: previewBaseImport is a pure read.
+      return jsonResponse({
+        ok: true,
+        changed: false,
+        preview: {
+          rawPath: preview.rawPath,
+          resolvedPath: preview.resolvedPath,
+          serialized: preview.serialized,
+          serializedBytes: utf8Bytes(preview.serialized!),
+          bodyBytes: utf8Bytes(preview.body!),
+          suggestedTitle: preview.suggestedTitle,
+          effectiveTitle: preview.effectiveTitle,
+          previewSha256: preview.previewSha256,
+        },
+      }, 200, req, ctx.config);
+    }
+    const revision = revisionOf(body);
+    if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
+    // The preview hash is REQUIRED — a confirm that does not name exactly what
+    // was previewed (serialized text, title included) cannot be checked against
+    // it and is refused without writing.
+    const previewSha256 = body.previewSha256;
+    if (typeof previewSha256 !== "string" || !/^[0-9a-f]{64}$/.test(previewSha256)) {
+      return fail(ctx, "import_preview_required", 400,
+        "confirm requires the previewSha256 returned by a preview of the same title");
+    }
+    if (previewSha256 !== preview.previewSha256) {
+      // The file or the selected title moved between preview and confirm. Refuse
+      // rather than import a serialization nobody previewed.
+      return fail(ctx, "import_body_changed", 409,
+        "the preview no longer matches; preview it again", {
+          resolvedPath: preview.resolvedPath,
+        });
+    }
+    return settle(ctx, importBaseVariant(
+      { title: typeof body.title === "string" ? body.title : undefined, previewSha256 },
+      revision,
+      paths(ctx),
+    ));
+  }
+
   if (url.pathname === "/api/codex-prompt/base" && req.method === "PUT") {
     const body = await readBody(ctx);
     if (!body) return fail(ctx, "invalid_body", 400, "expected a JSON object");
@@ -568,11 +682,28 @@ export async function handleCodexPromptRoutes(ctx: ManagementContext): Promise<R
       return settle(ctx, adoptDeveloperInstructions(revision, paths(ctx)));
     }
 
-    // journal-present: recovery lives inside WP1's commit and is not exported.
-    // Any ordinary mutation replays it on its own path, so the honest answer is
-    // to name the state rather than duplicate the transaction here.
+    if (drift === "journal-present") {
+      // Recovery as its own locked operation — never a disguised layers write.
+      // The GUI used to replay recovery through a byte-identical custom PUT,
+      // which projected custom=[] over a config still carrying instructions
+      // whenever the store file was missing.
+      if (!confirm) {
+        return jsonResponse({
+          ok: true,
+          changed: false,
+          preview: { drift, storePath: snapshot.storePath },
+        }, 200, req, ctx.config);
+      }
+      if (!revision) return fail(ctx, "stale_revision", 409, "revision required");
+      if (revision !== snapshot.revision) {
+        return fail(ctx, "stale_revision", 409, "the configuration moved since it was read");
+      }
+      return settle(ctx, recoverPromptJournal(paths(ctx)));
+    }
+
+    // A drift kind this build does not repair: name it rather than guess.
     return fail(ctx, "repair_unsupported", 409,
-      "a write journal is present; recovery runs automatically on the next write", {
+      "this drift has no repair on this route", {
         drift, storePath: snapshot.storePath,
       });
   }

package/src/server/management/codex-role-auto-assign.ts

@@ -209,7 +209,7 @@ export async function proposeDelegationModel(options: {
     role: DELEGATED_WORK_ROLE,
     model: options.config.injectionModel ?? null,
     effort: options.config.injectionEffort ?? null,
-  }], outcomes, classified, { alwaysProposeEffort: true });
+  }], outcomes, classified);
   return {
     sizingModel,
     sizingError,

package/src/server/management/companion-routes.ts

@@ -27,6 +27,10 @@ function response(): Response {
 }
 
 export async function handleCompanionRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname === "/api/advisor/settings") {
+    const { handleAdvisorRoutes } = await import("./advisor-routes");
+    return handleAdvisorRoutes(ctx);
+  }
   if (ctx.url.pathname === "/api/companion/open-in-browser" && ctx.req.method === "POST") {
     let body: unknown;
     try {

package/src/server/management/config-routes.ts

@@ -329,8 +329,8 @@ export async function syncEnabledClientIntegrations(
     config,
     port,
   }, unattended
-    ? ["mcode", "pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo"]
-    : ["mcode", "pi", "aside", "raycast", "omo", "cline", "commandcode", "droid", "opencode", "kilo"],
+    ? ["mcode", "pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo", "qoder"]
+    : ["mcode", "pi", "aside", "raycast", "omo", "cline", "commandcode", "droid", "opencode", "kilo", "qoder"],
   ...unattended ? [{ refreshOnly: true, admit }] as const : []));
 
   return out;

package/src/server/management/context.ts

@@ -45,6 +45,10 @@ export interface ManagementRequestIngress {
 }
 
 export interface ManagementApiDeps {
+  desktopStartupSettings?: import("../../codex/desktop-compatibility/startup-settings").DesktopStartupSettingsService;
+  desktopCertificateService?: import("../../codex/desktop-compatibility/certificate-service").DesktopCertificateService;
+  desktopCompatibilityRuntime?: import("../../codex/desktop-compatibility/runtime").DesktopCompatibilityRuntime;
+  onDesktopCompatibilityShutdown?: (shutdown: () => Promise<void>) => void;
   /** Bound to this server's lifecycle owner; absent in direct route tests. */
   listLowQuotaEvents?: (limit?: number) => LowQuotaEvent[];
   /** Bound Claude intercept state, injectable for isolated management-route tests. */

package/src/server/management/desktop-compatibility-routes.ts

@@ -0,0 +1,46 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+import type { DesktopCertificateService } from "../../codex/desktop-compatibility/certificate-service";
+
+const PATH = "/api/codex/desktop-compatibility/certificate";
+let service: DesktopCertificateService | undefined;
+
+export async function handleDesktopCompatibilityRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  // A local dashboard confirmation precedes any persisted key or CurrentUser Root mutation.
+  // This is caller provenance, not protection against an arbitrary same-user process.
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) {
+    return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  }
+  let action: "prepare" | "trust" | "remove-trust" | "renew" | undefined, fingerprint: string | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["action", "fingerprint", "confirmed"].includes(key)) || value.confirmed !== true
+      || typeof value.action !== "string" || !["prepare", "trust", "remove-trust", "renew"].includes(value.action)) return jsonResponse({ error: "invalid_request" }, 400);
+    action = value.action as typeof action;
+    if (action !== "prepare" && (typeof value.fingerprint !== "string" || !/^[A-F0-9]{64}$/.test(value.fingerprint))) {
+      return jsonResponse({ error: "certificate_fingerprint_required" }, 400);
+    }
+    if (action === "prepare" && value.fingerprint !== undefined) return jsonResponse({ error: "unexpected_fingerprint" }, 400);
+    fingerprint = value.fingerprint as string | undefined;
+  }
+  const controller = ctx.deps.desktopCertificateService ?? (service ??= (await import("../../codex/desktop-compatibility/certificate-service")).createDesktopCertificateService());
+  try {
+    const status = action === "prepare" ? await controller.prepare()
+      : action === "trust" ? await controller.trust(fingerprint!)
+      : action === "renew" ? await controller.renew(fingerprint!)
+      : action === "remove-trust" ? await controller.removeTrust(fingerprint!) : await controller.status();
+    return jsonResponse({ ok: true, certificate: status });
+  } catch (error) {
+    const code = error && typeof error === "object" && "code" in error ? String(error.code) : "operation_failed";
+    const allowed = new Set(["unsupported", "busy", "not_prepared", "fingerprint_changed", "app_running", "runtime_running", "app_state_unknown", "trust_unknown", "trust_not_applied",
+      "unsafe_path", "unreadable", "expired", "renewal_required", "protection_failed"]);
+    return jsonResponse({ ok: false, error: allowed.has(code) ? code : "operation_failed" }, 409);
+  }
+}

package/src/server/management/desktop-compatibility-runtime-routes.ts

@@ -0,0 +1,46 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+import type { DesktopCompatibilityRuntime } from "../../codex/desktop-compatibility/runtime";
+
+const PATH = "/api/codex/desktop-compatibility/runtime";
+const ERROR_CODES = new Set(["busy", "unsupported", "test_environment", "stopping", "build_unverified", "egress_proxy_invalid",
+  "trust_required", "certificate_expiring", "certificate_not_prepared", "certificate_invalid", "certificate_expired",
+  "native_identity_unverified", "native_routing_unverified", "cleanup_incomplete", "not_running", "connection_invalid", "connection_changed", "connection_cleanup_required", "connection_unavailable"]);
+
+export async function handleDesktopCompatibilityRuntimeRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  let action: "start" | "stop" | "observe" | "apply" | "launch" | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["action", "confirmed", "accountWideConsent"].includes(key)) || value.confirmed !== true
+      || typeof value.action !== "string" || !["start", "stop", "observe", "apply", "launch"].includes(value.action)) return jsonResponse({ error: "invalid_request" }, 400);
+    if (value.action === "apply" ? value.accountWideConsent !== true : value.accountWideConsent !== undefined) return jsonResponse({ error: "invalid_consent_scope" }, 400);
+    action = value.action as typeof action;
+  }
+  const module = ctx.deps.desktopCompatibilityRuntime ? null : await import("../../codex/desktop-compatibility/service");
+  const service: DesktopCompatibilityRuntime = ctx.deps.desktopCompatibilityRuntime ?? module!.getDesktopCompatibilityRuntime();
+  if (module) ctx.deps.onDesktopCompatibilityShutdown?.(module.shutdownDesktopCompatibility);
+  try {
+    if (action === "apply") {
+      const result = await service.apply(true);
+      return jsonResponse({ ok: result.accepted, activation: result, runtime: service.status() }, result.accepted ? 202 : 409);
+    }
+    if (action === "launch") {
+      const result = await service.launch();
+      return jsonResponse({ ok: result.status === "started", launch: result, runtime: service.status() }, result.status === "started" ? 200 : 409);
+    }
+    const result = action === "start" ? await service.start() : action === "stop" ? await service.stop()
+      : action === "observe" ? await service.observe() : service.status();
+    return jsonResponse({ ok: true, runtime: result });
+  } catch (error) {
+    const code = error instanceof Error ? error.message.replace(/^desktop_compatibility_/, "") : "operation_failed";
+    return jsonResponse({ ok: false, error: ERROR_CODES.has(code) ? code : "operation_failed", runtime: service.status() }, 409);
+  }
+}

package/src/server/management/desktop-compatibility-settings-routes.ts

@@ -0,0 +1,27 @@
+import { jsonResponse } from "../auth-cors";
+import { readManagementJsonBody, rethrowManagementBodyTooLarge } from "./body";
+import type { ManagementContext } from "./context";
+
+const PATH = "/api/codex/desktop-compatibility/settings";
+export async function handleDesktopCompatibilitySettingsRoutes(ctx: ManagementContext): Promise<Response | null> {
+  if (ctx.url.pathname !== PATH) return null;
+  if (ctx.req.method !== "GET" && ctx.req.method !== "POST") return jsonResponse({ error: "method_not_allowed" }, 405);
+  if (ctx.req.method === "POST" && (ctx.principal !== "gui-session" || !ctx.trustedLoopbackIngress)) return jsonResponse({ error: "local_dashboard_confirmation_required" }, 403);
+  let update: { startOnProxyStart: boolean; revision: string } | undefined;
+  if (ctx.req.method === "POST") {
+    let body: unknown;
+    try { body = await readManagementJsonBody(ctx.req); }
+    catch (error) { rethrowManagementBodyTooLarge(error); return jsonResponse({ error: "invalid_json" }, 400); }
+    if (!body || typeof body !== "object" || Array.isArray(body)) return jsonResponse({ error: "invalid_request" }, 400);
+    const value = body as Record<string, unknown>;
+    if (Object.keys(value).some(key => !["startOnProxyStart", "revision", "confirmed"].includes(key)) || value.confirmed !== true
+      || typeof value.startOnProxyStart !== "boolean" || typeof value.revision !== "string" || !/^[a-f0-9]{64}$/.test(value.revision)) return jsonResponse({ error: "invalid_request" }, 400);
+    update = { startOnProxyStart: value.startOnProxyStart, revision: value.revision };
+  }
+  const service = ctx.deps.desktopStartupSettings ?? (await import("../../codex/desktop-compatibility/startup-settings")).createDesktopStartupSettings({ liveConfig: ctx.config });
+  try { return jsonResponse({ ok: true, settings: update ? service.set(update.startOnProxyStart, update.revision) : service.status() }); }
+  catch (error) {
+    const code = error instanceof Error ? error.message.replace(/^desktop_compatibility_settings_/, "") : "operation_unconfirmed";
+    return jsonResponse({ ok: false, error: ["unavailable", "invalid", "changed", "invalid_request"].includes(code) ? `settings_${code}` : "settings_operation_unconfirmed" }, 409);
+  }
+}

package/src/server/management/grok-coupon-routes.ts

@@ -22,10 +22,12 @@ import {
 } from "../../grok/reset-coupons";
 import {
   getGrokResetCouponOperationAccountId,
+  isTerminalGrokCouponReplay,
   markGrokResetCouponAttempt,
   openGrokResetCouponOperation,
   recordGrokResetCouponSettlement,
   readGrokResetCouponTerminalReplay,
+  refuseGrokResetCouponBeforeOpen,
   settleGrokResetCouponPreflightRefusal,
   type GrokResetCouponOperationRecord,
 } from "../../grok/reset-coupon-ledger";
@@ -140,10 +142,6 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     const { accountId: rawAccountId, tokenId: requestedTokenId, operationId } = body;
 
-    if (requestedTokenId !== undefined && (typeof requestedTokenId !== "string" || requestedTokenId.trim() === "")) {
-      return jsonResponse({ error: { code: "invalid_token_id", message: "tokenId must be a non-empty string" } }, 400, req, config);
-    }
-
     if (operationId !== undefined && !isCodexResetCreditOperationId(operationId)) {
       return jsonResponse(
         { error: { code: "invalid_operation_id", message: "operationId must be a valid UUIDv4" } },
@@ -153,47 +151,87 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       );
     }
 
+    /**
+     * Once a caller supplies an operationId, that id may already name an operation that
+     * another request is spending. A refusal from this request must not read as
+     * definitive then, or the caller drops its hold and mints a replacement.
+     */
+    const uncertain = (id: string): Response => jsonResponse({ operationId: id, error: {
+      code: "attempt_in_progress",
+      message: "This request did not attempt a redemption, but another request may hold this operation; retry the same operationId to read its durable state",
+    } }, 409, req, config);
+    /** Refuse before open: definitive only when the supplied id is durably reserved as failed. */
+    const preOpenRefusal = (definitive: Response, code: string, knownAccountId?: string): Response => {
+      if (operationId === undefined) return definitive;
+      if (knownAccountId === undefined) return uncertain(operationId);
+      try {
+        const result = refuseGrokResetCouponBeforeOpen({
+          operationId, accountId: knownAccountId, code,
+          tokenId: typeof requestedTokenId === "string" ? requestedTokenId : undefined,
+        });
+        if (result.kind === "recorded") return definitive;
+        if (result.kind === "replay") return jsonResponse({
+          code: result.code, replayed: true, tokenId: result.tokenId, settledAt: result.settledAt,
+        }, 200, req, config);
+        if (result.kind === "identity-mismatch") return jsonResponse({ error: {
+          code: "operation_id_owned_by_another_account",
+          message: "Operation ID was previously registered with a different account or token",
+        } }, 409, req, config);
+        return uncertain(operationId);
+      } catch {
+        return uncertain(operationId);
+      }
+    };
+
+    if (requestedTokenId !== undefined && (typeof requestedTokenId !== "string" || requestedTokenId.trim() === "")) {
+      return preOpenRefusal(jsonResponse({ error: { code: "invalid_token_id", message: "tokenId must be a non-empty string" } }, 400, req, config), "invalid_token_id");
+    }
+
     let recordedAccountId: string | undefined;
     if (rawAccountId === undefined && operationId !== undefined) {
       try { recordedAccountId = getGrokResetCouponOperationAccountId(operationId); }
       catch {
-        return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+        return uncertain(operationId);
       }
     }
     let accountId: string;
     try {
       accountId = resolveTargetAccountId(rawAccountId ?? recordedAccountId);
     } catch (err) {
-      return jsonResponse(
+      return preOpenRefusal(jsonResponse(
         { error: { code: "no_account", message: err instanceof Error ? err.message : String(err) } },
         400,
         req,
         config,
-      );
+      ), "no_account");
     }
 
     let tokenSnapshot;
     try {
       tokenSnapshot = await getValidAccessSnapshotForAccount("xai", accountId, { requireUsableAccount: true });
     } catch (err) {
-      return jsonResponse(
+      return preOpenRefusal(jsonResponse(
         { error: { code: "auth_failed", message: "Failed to resolve valid xAI credentials for account" } },
         401,
         req,
         config,
-      );
+      ), "auth_failed", accountId);
     }
 
     // Journaling and Idempotency settlement check
     const effectiveOpId = operationId ?? crypto.randomUUID();
-    if (grokCouponInFlightAttempts.has(effectiveOpId)) return jsonResponse({ error: {
+    if (grokCouponInFlightAttempts.has(effectiveOpId)) return jsonResponse({ operationId: effectiveOpId, error: {
       code: "attempt_in_progress", message: "This operation still has an active request; retry later",
     } }, 409, req, config);
     let opRecord: GrokResetCouponOperationRecord;
     try {
       opRecord = openGrokResetCouponOperation({ accountId, tokenId: requestedTokenId, operationId: effectiveOpId });
     } catch {
-      return jsonResponse({ error: { code: "ledger_unavailable", message: "Coupon ledger could not be read or locked; no redemption was attempted" } }, 503, req, config);
+      // A failed open cannot prove that no earlier request already opened this id.
+      return jsonResponse({ operationId: effectiveOpId, error: {
+        code: "ledger_unavailable",
+        message: "Coupon ledger could not be read or locked; this request did not attempt a redemption. Retry the same operationId",
+      } }, 503, req, config);
     }
 
     let resolvedTokenId = requestedTokenId ?? opRecord.tokenId;
@@ -201,6 +239,14 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     if (opRecord.kind === "replay") {
       if (opRecord.code !== undefined) {
+        // Replay only a definitive outcome; a recorded code that means "unconfirmed"
+        // must keep the caller on this operation.
+        if (!isTerminalGrokCouponReplay(opRecord, accountId, requestedTokenId)) {
+          return jsonResponse({ operationId: effectiveOpId, error: {
+            code: "attempt_unresolved",
+            message: "This operation's recorded outcome is unconfirmed; preserve this operationId and do not create a replacement attempt",
+          } }, 409, req, config);
+        }
         return jsonResponse(
           {
             code: opRecord.code,
@@ -230,6 +276,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         // retry with the recorded token and preserve the operationId.
         return jsonResponse(
           {
+            operationId: effectiveOpId,
             error: {
               code: "operation_token_mismatch",
               message: "Operation was attempted with a different coupon; preserve the operationId and retry with the recorded tokenId",
@@ -282,7 +329,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       } }, 409, req, config);
     }
 
-    if (opRecord.kind === "token-mismatch") return jsonResponse({ error: {
+    if (opRecord.kind === "token-mismatch") return jsonResponse({ operationId: effectiveOpId, error: {
       code: "operation_token_mismatch", message: "Operation ID was previously registered with a different coupon",
     } }, 409, req, config);
 
@@ -301,11 +348,14 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
     }
 
     if (opRecord.kind !== "execute") {
+      // A capacity refusal cannot reserve the id, so an earlier same-id request still in
+      // credential resolution may open it once records expire: keep the caller on the id.
       return jsonResponse(
         {
+          ...(operationId !== undefined ? { operationId: effectiveOpId } : {}),
           error: {
             code: opRecord.kind,
-            message: "Coupon ledger capacity or unavailable failure",
+            message: "Coupon ledger is at capacity; this request did not attempt a redemption. Retry the same operationId later",
           },
         },
         503,
@@ -324,14 +374,13 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         if (result.kind === "replay") return jsonResponse({
           code: result.code, replayed: true, tokenId: result.tokenId, settledAt: result.settledAt,
         }, 200, req, config);
-        return jsonResponse({ error: {
+        return jsonResponse({ operationId: effectiveOpId, error: {
           code: "operation_state_changed",
           message: "Another request changed this operation during inspection; retry the same operationId to read its durable state",
         } }, 409, req, config);
       } catch {
-        return jsonResponse({ error: {
-          code: "ledger_unavailable", message: "Coupon refusal could not be recorded; no redemption was attempted",
-        } }, 503, req, config);
+        // The refusal could not be recorded, so the operation may still be claimed elsewhere.
+        return uncertain(effectiveOpId);
       }
     };
 
@@ -345,6 +394,10 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
         const remaining = await getGrokRemainingResets({ accessToken: tokenSnapshot.accessToken });
         tokens = remaining.tokens ?? [];
       } catch (err) {
+        // Close the still-open operation before reporting a definitive failure: once it is
+        // recorded as failed it can never be claimed, so the caller may safely start over.
+        const changed = settlePreflightRefusal("fetch_resets_failed", resolvedTokenId);
+        if (changed) return changed;
         return jsonResponse(
           { error: { code: "fetch_resets_failed", message: err instanceof Error ? err.message : String(err) } },
           502,
@@ -389,6 +442,8 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
 
     if (resolvedTokenId === undefined) {
       // Unreachable: every path above either resolves a token or returns.
+      const changed = settlePreflightRefusal("token_unresolved");
+      if (changed) return changed;
       return jsonResponse(
         { error: { code: "token_unresolved", message: "No reset coupon token could be resolved" } },
         500,
@@ -403,6 +458,7 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
       // on this operationId again regardless of how stale the mark looks.
       return jsonResponse(
         {
+          operationId: effectiveOpId,
           error: {
             code: "attempt_in_progress",
             message: "A redemption attempt for this operation is still running; retry later",
@@ -433,17 +489,12 @@ export async function handleGrokCouponRoutes(ctx: ManagementContext): Promise<Re
           if (winner) return jsonResponse({
             code: winner.code, replayed: true, tokenId: winner.tokenId, settledAt: winner.settledAt,
           }, 200, req, config);
-          return jsonResponse({ error: {
-            code: "attempt_in_progress", message: "Another request already claimed this operation; no redemption was attempted",
-          } }, 409, req, config);
+          return uncertain(effectiveOpId);
         }
-      } catch (err) {
-        return jsonResponse(
-          { error: { code: "attempt_mark_failed", message: err instanceof Error ? err.message : String(err) } },
-          500,
-          req,
-          config,
-        );
+      } catch {
+        // The claim write failed or was contended: this request dispatched nothing, but a
+        // concurrent holder of this operation may be spending, so keep the caller on it.
+        return uncertain(effectiveOpId);
       }
 
       try {