@bitkyc08/opencodex 2.81.0 → 2.83.0

package/src/grok/reset-coupon-ledger.ts

@@ -1,9 +1,10 @@
-import { existsSync, readFileSync } from "node:fs";
-import { join } from "node:path";
-import { atomicWriteFile } from "../config/atomic-write";
+import { closeSync, fsyncSync, openSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { atomicWriteFileStreamed } from "../config/atomic-write";
+import { withConfigMutationLockSync } from "../config/mutation-lock";
 import { getConfigDir } from "../config/paths";
 
-export type GrokResetCouponOperationKind = "execute" | "replay" | "identity-mismatch" | "capacity";
+export type GrokResetCouponOperationKind = "execute" | "replay" | "identity-mismatch" | "token-mismatch" | "capacity";
 
 export interface GrokResetCouponOperationIdentity {
   accountId: string;
@@ -16,6 +17,12 @@ export interface GrokResetCouponOperationRecord {
   operationId: string;
   accountId?: string;
   tokenId?: string;
+  /** Token expiry (ms) captured at claim time as journal metadata. Remaining
+   * availability or expiry cannot establish this operation's outcome. */
+  tokenValidityEnd?: number;
+  /** When the attempt was marked (ms) — set only on an "attempted" replay so
+   * the route can defer inspection while the attempt may still be in flight. */
+  attemptedAt?: number;
   code?: string;
   settledAt?: number;
 }
@@ -23,14 +30,18 @@ export interface GrokResetCouponOperationRecord {
 interface GrokResetCouponOperationState {
   accountId: string;
   tokenId?: string;
-  status: "open" | "settled" | "failed";
+  // "attempted" sits between open and settled: the spend call may have fired,
+  // so the operation must never execute again. Its replay carries no code —
+  // the route reconciles it against upstream instead of trusting a status.
+  status: "open" | "attempted" | "settled" | "failed";
   code?: string;
+  tokenValidityEnd?: number;
   createdAt: number;
   updatedAt: number;
 }
 
 interface GrokResetCouponLedger {
-  version: 1;
+  version: 2;
   operations: Record<string, GrokResetCouponOperationState>;
 }
 
@@ -40,95 +51,249 @@ export function grokCouponJournalPath(customDir?: string): string {
 }
 
 function readGrokCouponLedger(filePath: string): GrokResetCouponLedger {
-  if (!existsSync(filePath)) {
-    return { version: 1, operations: {} };
+  let raw: string;
+  try { raw = readFileSync(filePath, "utf-8"); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === "ENOENT") return { version: 2, operations: {} };
+    throw new Error("Grok coupon ledger is unavailable; existing records were preserved.");
   }
   try {
-    const raw = readFileSync(filePath, "utf-8");
-    const parsed = JSON.parse(raw) as GrokResetCouponLedger;
-    return parsed && parsed.version === 1 && parsed.operations && typeof parsed.operations === "object"
-      ? parsed
-      : { version: 1, operations: {} };
+    const parsed = JSON.parse(raw) as Omit<GrokResetCouponLedger, "version"> & { version: unknown };
+    if (!parsed || (parsed.version !== 1 && parsed.version !== 2) || !parsed.operations
+      || typeof parsed.operations !== "object" || Array.isArray(parsed.operations)) throw new Error();
+    for (const op of Object.values(parsed.operations)) {
+      if (!op || typeof op.accountId !== "string" || !op.accountId
+        || !["open", "attempted", "settled", "failed"].includes(op.status)
+        || !Number.isFinite(op.createdAt) || !Number.isFinite(op.updatedAt)
+        || (op.tokenId !== undefined && typeof op.tokenId !== "string")
+        || (op.code !== undefined && typeof op.code !== "string")
+        || (op.tokenValidityEnd !== undefined && !Number.isFinite(op.tokenValidityEnd))) throw new Error();
+    }
+    if (parsed.version === 1) {
+      for (const op of Object.values(parsed.operations)) {
+        // Old opens (and transport failures recorded as failed) may already
+        // have dispatched. Only version-two opens prove pre-dispatch state.
+        if (op.status === "open" || (op.status === "failed" && op.code === "redeem_failed")) {
+          op.status = "attempted";
+          delete op.code;
+        }
+      }
+    }
+    return { version: 2, operations: parsed.operations };
   } catch {
-    return { version: 1, operations: {} };
+    throw new Error("Grok coupon ledger is unreadable; existing records were preserved.");
   }
 }
 
 function writeGrokCouponLedger(filePath: string, ledger: GrokResetCouponLedger, now = Date.now()): void {
-  // Prune settled/failed operations older than 30 days to avoid unbounded growth
+  // Prune every record past the 30-day window — including "open" and
+  // "attempted". Idempotency retention is explicitly bounded to 30 days;
+  // operations are not retry authorities after that window.
   const retentionCutoff = now - 30 * 24 * 60 * 60_000;
   ledger.operations = Object.fromEntries(
-    Object.entries(ledger.operations).filter(
-      ([, op]) => op.status === "open" || op.updatedAt > retentionCutoff,
-    ),
+    Object.entries(ledger.operations).filter(([, op]) => op.updatedAt > retentionCutoff),
   );
-  atomicWriteFile(filePath, JSON.stringify(ledger, null, 2));
+  atomicWriteFileStreamed(filePath, descriptor => writeFileSync(descriptor, JSON.stringify(ledger, null, 2)), {
+    afterRename: target => {
+      // The shared streamed writer flushes the temp. A spend claim must also
+      // refuse on a POSIX directory-sync failure before dispatch, rather than
+      // relying on that writer's best-effort parent sync. Windows has no
+      // portable directory descriptor and retains the writer's platform contract.
+      if (process.platform === "win32") return;
+      const descriptor = openSync(dirname(target), "r");
+      try { fsyncSync(descriptor); }
+      finally { closeSync(descriptor); }
+    },
+  });
 }
 
 const MAX_GROK_RESET_COUPON_OPERATION_IDS = 256;
 
+/** Resolve an omitted-account retry from its durable identity, within retention. */
+export function getGrokResetCouponOperationAccountId(
+  operationId: string,
+  now = Date.now(),
+  journalPath?: string,
+): string | undefined {
+  return withConfigMutationLockSync(() => {
+    const record = readGrokCouponLedger(journalPath ?? grokCouponJournalPath()).operations[operationId];
+    if (!record || record.updatedAt <= now - 30 * 24 * 60 * 60_000) return undefined;
+    return record.accountId;
+  });
+}
+
 export function openGrokResetCouponOperation(
   identity: GrokResetCouponOperationIdentity,
   now = Date.now(),
   journalPath?: string,
 ): GrokResetCouponOperationRecord {
-  const filePath = journalPath ?? grokCouponJournalPath();
-  const ledger = readGrokCouponLedger(filePath);
+  // Read→decide→write under the shared config mutation lock: two concurrent
+  // coupon requests on the same home must not lose an operation record — the
+  // ledger exists precisely to make an irreversible spend replay-safe.
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    const ledger = readGrokCouponLedger(filePath);
 
-  if (Object.keys(ledger.operations).length >= MAX_GROK_RESET_COUPON_OPERATION_IDS) {
-    return { kind: "capacity", operationId: identity.operationId };
-  }
+    // Prune BEFORE the capacity check: expiry is enforced on write, so a ledger
+    // full of stale records would otherwise reject every new operation forever
+    // (the prune path inside writeGrokCouponLedger is never reached when all
+    // openings are rejected).
+    const retentionCutoff = now - 30 * 24 * 60 * 60_000;
+    ledger.operations = Object.fromEntries(
+      Object.entries(ledger.operations).filter(([, op]) => op.updatedAt > retentionCutoff),
+    );
 
-  const existing = ledger.operations[identity.operationId];
-  if (existing) {
-    if (existing.accountId !== identity.accountId) {
-      return { kind: "identity-mismatch", operationId: identity.operationId };
-    }
-    if (existing.status !== "open") {
-      // Durably settled already: replay the recorded outcome instead of
-      // trusting upstream idempotency for an irreversible spend.
+    const existing = ledger.operations[identity.operationId];
+    if (existing) {
+      if (existing.accountId !== identity.accountId) {
+        return { kind: "identity-mismatch", operationId: identity.operationId };
+      }
+      if (identity.tokenId !== undefined && existing.tokenId !== undefined && existing.tokenId !== identity.tokenId) {
+        return { kind: "token-mismatch", operationId: identity.operationId };
+      }
+      if (existing.status !== "open") {
+        // Non-open: replay the recorded outcome. "attempted" records carry no
+        // code — the caller must reconcile them against upstream, never re-run.
+        return {
+          kind: "replay",
+          operationId: identity.operationId,
+          accountId: existing.accountId,
+          tokenId: existing.tokenId,
+          tokenValidityEnd: existing.tokenValidityEnd,
+          attemptedAt: existing.status === "attempted" ? existing.updatedAt : undefined,
+          code: existing.code,
+          settledAt: existing.updatedAt,
+        };
+      }
       return {
-        kind: "replay",
+        kind: "execute",
         operationId: identity.operationId,
         accountId: existing.accountId,
         tokenId: existing.tokenId,
-        code: existing.code,
-        settledAt: existing.updatedAt,
       };
     }
+
+    if (Object.keys(ledger.operations).length >= MAX_GROK_RESET_COUPON_OPERATION_IDS) {
+      return { kind: "capacity", operationId: identity.operationId };
+    }
+
+    ledger.operations[identity.operationId] = {
+      accountId: identity.accountId,
+      ...(identity.tokenId === undefined ? {} : { tokenId: identity.tokenId }),
+      status: "open",
+      createdAt: now,
+      updatedAt: now,
+    };
+    writeGrokCouponLedger(filePath, ledger, now);
     return {
       kind: "execute",
       operationId: identity.operationId,
-      accountId: existing.accountId,
-      tokenId: existing.tokenId,
+      accountId: identity.accountId,
+      tokenId: identity.tokenId,
     };
-  }
+  });
+}
 
-  ledger.operations[identity.operationId] = {
-    accountId: identity.accountId,
-    ...(identity.tokenId === undefined ? {} : { tokenId: identity.tokenId }),
-    status: "open",
-    createdAt: now,
-    updatedAt: now,
-  };
-  writeGrokCouponLedger(filePath, ledger, now);
-  return {
-    kind: "execute",
-    operationId: identity.operationId,
-    accountId: identity.accountId,
-    tokenId: identity.tokenId,
-  };
+/**
+ * Flip an open operation to `attempted` BEFORE the upstream spend call. The
+ * write happens while nothing is irreversible yet: if it throws, the caller
+ * aborts without spending; if a later settle write dies instead, the
+ * operation still refuses blind re-execution — the next open returns a
+ * code-less replay the route resolves via the upstream remaining-resets list.
+ */
+export function markGrokResetCouponAttempt(
+  operationId: string,
+  tokenId: string,
+  now = Date.now(),
+  journalPath?: string,
+  tokenValidityEnd?: number,
+): boolean {
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    const ledger = readGrokCouponLedger(filePath);
+    const existing = ledger.operations[operationId];
+    if (!existing || existing.status !== "open"
+      || (existing.tokenId !== undefined && existing.tokenId !== tokenId)) return false;
+    existing.status = "attempted";
+    existing.tokenId = tokenId;
+    if (tokenValidityEnd !== undefined) existing.tokenValidityEnd = tokenValidityEnd;
+    existing.updatedAt = now;
+    writeGrokCouponLedger(filePath, ledger, now);
+    return true;
+  });
+}
+
+type GrokResetCouponSettlement = { operationId: string; accountId: string; code: string } & (
+  | { tokenId?: string; status: "failed"; expectedStatus: "open" }
+  | { tokenId: string; status: "success"; expectedStatus: "attempted" }
+);
+
+type GrokResetCouponPreflightResult =
+  | { kind: "recorded" | "changed" }
+  | { kind: "replay"; code: string; tokenId?: string; settledAt: number };
+
+const UNRESOLVED_COUPON_CODES = new Set(["redeem_failed", "attempt_unresolved", "attempt_in_progress", "attempt_reconcile_failed", "operation_state_changed"]);
+
+/** The durable definitive outcome for this account and token, if the operation has one. */
+function terminalReplay(
+  ledger: GrokResetCouponLedger, operationId: string, accountId: string, tokenId: string | undefined,
+): Extract<GrokResetCouponPreflightResult, { kind: "replay" }> | null {
+  const existing = ledger.operations[operationId];
+  if (!existing || existing.accountId !== accountId) return null;
+  if (tokenId !== undefined && existing.tokenId !== undefined && existing.tokenId !== tokenId) return null;
+  if ((existing.status !== "settled" && existing.status !== "failed") || !existing.code || UNRESOLVED_COUPON_CODES.has(existing.code)) return null;
+  return { kind: "replay", code: existing.code, tokenId: existing.tokenId, settledAt: existing.updatedAt };
 }
 
+/** Settle a refusal or inspect its winner without releasing the mutation transaction. */
+export function settleGrokResetCouponPreflightRefusal(
+  settlement: Extract<GrokResetCouponSettlement, { status: "failed" }>,
+  now = Date.now(),
+  journalPath?: string,
+): GrokResetCouponPreflightResult {
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    const ledger = readGrokCouponLedger(filePath);
+    if (recordSettlement(ledger, filePath, settlement, now)) return { kind: "recorded" };
+    return terminalReplay(ledger, settlement.operationId, settlement.accountId, settlement.tokenId) ?? { kind: "changed" };
+  });
+}
+
+/**
+ * After a lost claim: the definitive winner to replay, or null while the
+ * operation is still unresolved. Terminal states never revert, so reading after
+ * the failed claim cannot replay an outcome that is later replaced.
+ */
+export function readGrokResetCouponTerminalReplay(
+  operationId: string, accountId: string, tokenId?: string, journalPath?: string,
+): Extract<GrokResetCouponPreflightResult, { kind: "replay" }> | null {
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    return terminalReplay(readGrokCouponLedger(filePath), operationId, accountId, tokenId);
+  });
+}
+
+/** A preflight refusal cannot replace a claim or a terminal result. */
 export function recordGrokResetCouponSettlement(
-  settlement: { operationId: string; tokenId?: string; code: string; status: "success" | "failed" },
+  settlement: GrokResetCouponSettlement,
   now = Date.now(),
   journalPath?: string,
-): void {
-  const filePath = journalPath ?? grokCouponJournalPath();
-  const ledger = readGrokCouponLedger(filePath);
+): boolean {
+  return withConfigMutationLockSync(() => {
+    const filePath = journalPath ?? grokCouponJournalPath();
+    const ledger = readGrokCouponLedger(filePath);
+    return recordSettlement(ledger, filePath, settlement, now);
+  });
+}
+
+function recordSettlement(
+  ledger: GrokResetCouponLedger, filePath: string, settlement: GrokResetCouponSettlement, now: number,
+): boolean {
   const existing = ledger.operations[settlement.operationId];
-  if (!existing) return;
+  if (!existing || existing.status !== settlement.expectedStatus
+    || existing.accountId !== settlement.accountId
+    || (settlement.tokenId !== undefined && existing.tokenId !== undefined && existing.tokenId !== settlement.tokenId)
+    || (settlement.status === "success" && existing.tokenId !== settlement.tokenId)) return false;
 
   existing.status = settlement.status === "success" ? "settled" : "failed";
   existing.code = settlement.code;
@@ -136,4 +301,5 @@ export function recordGrokResetCouponSettlement(
   existing.updatedAt = now;
 
   writeGrokCouponLedger(filePath, ledger, now);
+  return true;
 }

package/src/grok/reset-coupons.ts

@@ -230,6 +230,17 @@ function buildGrokHeaders(accessToken: string): Record<string, string> {
 /**
  * Reads available Grok reset tokens for the authenticated xAI account.
  */
+function assertConfirmedCouponStatus(decoded: ReturnType<typeof decodeGrpcWebResponse>): void {
+  const rawStatus = decoded.trailers?.metadata["grpc-status"];
+  // The shared decoder defaults a missing/malformed status to zero. Coupon
+  // availability and an irreversible redemption need affirmative confirmation.
+  if (rawStatus === undefined || !/^\d+$/.test(rawStatus) || !Number.isSafeInteger(Number(rawStatus))) {
+    throw new Error("Grok coupon response has no confirmed gRPC status");
+  }
+  const status = Number(rawStatus);
+  if (status !== 0) throw new GrpcWebError(status, decoded.statusMessage ?? "Unknown gRPC error");
+}
+
 export async function getGrokRemainingResets(options: GetRemainingResetsOptions): Promise<{ tokens: GrokResetCoupon[] }> {
   const fetchImpl = options.fetchFn ?? globalThis.fetch;
   const endpoint = options.endpoint ?? GROK_GET_REMAINING_RESETS_ENDPOINT;
@@ -251,9 +262,7 @@ export async function getGrokRemainingResets(options: GetRemainingResetsOptions)
   const rawBytes = new Uint8Array(await res.arrayBuffer());
   const decoded = decodeGrpcWebResponse(rawBytes);
 
-  if (decoded.status !== 0) {
-    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
-  }
+  assertConfirmedCouponStatus(decoded);
 
   if (decoded.messages.length === 0) {
     return { tokens: [] };
@@ -285,9 +294,7 @@ export async function redeemGrokResetCoupon(options: RedeemResetOptions): Promis
   const rawBytes = new Uint8Array(await res.arrayBuffer());
   const decoded = decodeGrpcWebResponse(rawBytes);
 
-  if (decoded.status !== 0) {
-    throw new GrpcWebError(decoded.status, decoded.statusMessage ?? "Unknown gRPC error");
-  }
+  assertConfirmedCouponStatus(decoded);
 
   return {
     success: true,

package/src/grok/sync.ts

@@ -31,7 +31,7 @@ async function defaultFetchAllModels(config: OcxConfig): Promise<CatalogModel[]>
 export async function syncGrokConfig(
   port: number,
   config: OcxConfig,
-  opts: { hostname?: string; grokHome?: string } = {},
+  opts: { hostname?: string; grokHome?: string; refreshOnly?: { admit: () => boolean } } = {},
   deps: GrokSyncDeps = { fetchAllModels: defaultFetchAllModels, injectGrokConfig },
 ): Promise<GrokInjectResult> {
   let projection: ReturnType<typeof projectGrokCatalog>;
@@ -58,6 +58,7 @@ export async function syncGrokConfig(
       ? (opts.hostname ?? config.hostname)
       : targetUrl.hostname,
     ...(opts.grokHome !== undefined ? { grokHome: opts.grokHome } : {}),
+    ...opts.refreshOnly ? { refreshOnly: opts.refreshOnly } : {},
     excluded: new Set(config.grokExcludedModels ?? []),
     catalogModelIds: projection.catalogModelIds,
     disabledProviderNamespaces: projection.disabledProviderNamespaces,

package/src/images/loop.ts

@@ -300,6 +300,11 @@ export interface ImageBridgeDeps {
   onRequestBuilt?: (request: AdapterRequest) => void;
   abortSignal?: AbortSignal;
   onFirstOutput?: () => void;
+  /** Transfer prepaid cleanup before asynchronous inference can outlive Response construction. */
+  onProducerStart?: () => void;
+  onProducerEnd?: () => void;
+  /** Release a prepaid recovery that did not dispatch during this fetch iteration. */
+  onIterationEnd?: () => void;
   /** Max image-generation rounds before forcing a final answer. Defaults to 3; clamped to [0, 10]. */
   maxRounds?: number;
   /** Connect / response-header budget for non-runTurn iterations. */
@@ -309,7 +314,7 @@ export interface ImageBridgeDeps {
   /** Provider-specific fetch (e.g. xAI transport wrapper). Falls back to global fetch. */
   fetchImpl?: typeof globalThis.fetch;
   /** Bind physical dispatch to this iteration's built request; pacing remains owned by the loop. */
-  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest) => typeof globalThis.fetch;
+  fetchForRequest?: (request: AdapterRequest, parsed: OcxParsedRequest, adapter: ProviderAdapter) => typeof globalThis.fetch;
   /** Reserve the routed provider's next request-start slot before each adapter dispatch. */
   waitForRequestSlot?: (signal?: AbortSignal) => Promise<ProviderRequestSlot | void>;
   /** Raw adapter usage at the terminal event, pre wire-normalization (see bridgeToResponsesSSE onUsage). */
@@ -372,6 +377,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   let paidImageCalls = 0;
   let paidVideoCalls = 0;
   let hiddenUsage: OcxUsage | undefined;
+  let activeProducers = 0;
 
   const addUsage = (a: OcxUsage | undefined, b: OcxUsage | undefined): OcxUsage | undefined => {
     if (!a) return b;
@@ -514,19 +520,25 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       try {
         // Attempt telemetry must fire at dispatch time, not after collection.
         deps.onAttemptSend?.();
-        void adapter.runTurn(iterParsed, {
-          headers: deps.forwardHeaders ? new Headers(deps.forwardHeaders) : new Headers(),
-          ...(deps.incomingMeta.providerName ? { providerName: deps.incomingMeta.providerName } : {}),
-          abortSignal: signal,
-          translatorBudget,
-          pacingSlot,
-        }, emit).then(closeOnAbort).catch(err => {
+        activeProducers++;
+        let producer: Promise<void>;
+        try {
+          producer = adapter.runTurn(iterParsed, {
+            ...deps.incomingMeta,
+            headers: deps.forwardHeaders ? new Headers(deps.forwardHeaders) : new Headers(),
+            ...(deps.incomingMeta.providerName ? { providerName: deps.incomingMeta.providerName } : {}),
+            abortSignal: signal,
+            translatorBudget,
+            pacingSlot,
+          }, emit);
+        } catch (err) { producer = Promise.reject(err); }
+        void producer.then(closeOnAbort).catch(err => {
           if (accepting) {
             collectionError = err;
             if (isTranslatorBudgetExceededError(err)) internalAbort.abort(err);
           }
           closeOnAbort();
-        });
+        }).finally(() => { activeProducers--; deps.onProducerEnd?.(); });
         idle.reset();
         for await (const event of queue.stream()) {
           if (timedOut) break;
@@ -602,7 +614,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
           cachedRequest = request;
           cachedAdapter = requestAdapter;
         }
-        const requestFetch = deps.fetchForRequest?.(request, iterParsed) ?? fetchImpl;
+        const requestFetch = deps.fetchForRequest?.(request, iterParsed, requestAdapter) ?? fetchImpl;
         let response: Response;
         try {
           if (requestAdapter.fetchResponse) {
@@ -615,6 +627,9 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
                 returnRawErrors: true,
                 stream: true,
                 executor: requestFetch,
+                sendBudget: deps.incomingMeta.sendBudget,
+                onPhysicalSend: deps.incomingMeta.onPhysicalSend,
+                onRecoveryWithheld: deps.incomingMeta.onRecoveryWithheld,
               }));
             } finally {
               releaseProviderRequestSlot(slot);
@@ -689,7 +704,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       }
       // 429 key-failover parity with web-search / normal routed path.
       while ((prepared.response.status === 429
-        || (prepared.response.status === 403 && isAnthropicInstanceId(deps.incomingMeta?.providerName))
+        || ((prepared.response.status === 403 || prepared.response.status === 401) && isAnthropicInstanceId(deps.incomingMeta?.providerName))
         || (iterParsed._kiroAuthContext && (prepared.response.status === 400 || prepared.response.status === 403))) && deps.on429) {
         const rotated = await deps.on429(prepared.response.headers.get("retry-after"), prepared.response.headers,
           iterParsed, prepared.response);
@@ -734,6 +749,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
       throw new LoopError(502, `Provider unreachable: ${error instanceof Error ? error.message : String(error)}`);
     } finally {
       headerDeadline.clear();
+      deps.onIterationEnd?.();
     }
   };
 
@@ -796,6 +812,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
   // non-2xx JSON. Skip for runTurn adapters: their "headers" are synthetic, and awaiting
   // queue.collect() before returning SSE starves clients of headers/heartbeats on slow first turns.
   const skipEagerDrain = !!adapter.runTurn;
+  if (skipEagerDrain) deps.onProducerStart?.();
   let firstPrepared: IterationResponse | undefined;
   if (!skipEagerDrain) {
     try {
@@ -1056,6 +1073,7 @@ export async function runWithImageBridge(deps: ImageBridgeDeps): Promise<Respons
         }
       }
     } finally {
+      if (skipEagerDrain && activeProducers === 0) deps.onProducerEnd?.();
       if (abortSignal) abortSignal.removeEventListener("abort", linkAbort);
     }
   }

package/src/integrations/aside-profiles.ts

@@ -8,7 +8,7 @@ import { readIntegrationState, type IntegrationState, type IntegrationStatus } f
 import {
   applyIntegrationCoordinated, disableIntegrationCoordinated,
   overwriteIntegrationCoordinated, refreshIntegrationCoordinated,
-  type IntegrationWriteInput,
+  type CoordinatedIntegrationOptions, type IntegrationWriteInput,
 } from "./writer";
 import {
   asideProfileEnabled, asideProfileFailure, asideProfileScope, asideWriteInput,
@@ -260,7 +260,10 @@ export function mutateAsideProfiles(
   });
 }
 
-export function refreshAsideProfiles(input: AsideProfilesInput): Promise<Array<OwnedIntegrationRefreshOutcome & { profileId: number }>> {
+export function refreshAsideProfiles(
+  input: AsideProfilesInput,
+  options?: { refreshOnly?: boolean; guard?: CoordinatedIntegrationOptions["guard"] },
+): Promise<Array<OwnedIntegrationRefreshOutcome & { profileId: number }>> {
   const policy = input.config.asideProfileSync;
   const selected = Object.values(policy?.profiles ?? {}).some(enabled => enabled === true);
   if (!selected && (policy?.allProfiles === false
@@ -272,11 +275,15 @@ export function refreshAsideProfiles(input: AsideProfilesInput): Promise<Array<O
       try {
         const scope = asideProfileScope(ctx, profile);
         const owned = scope.store.readRecords().aside !== undefined;
+        if (options?.refreshOnly && !owned) continue;
         const bound = await asideWriteInput(ctx, scope);
         // A surviving ownership record means a removed block stays removed.
         // A newly discovered, enabled profile may receive its first safe apply.
         const operation = owned ? refreshIntegrationCoordinated : applyIntegrationCoordinated;
-        const result = await operation(bound, { lockSeams: input.lockSeams });
+        const result = await operation(bound, {
+          lockSeams: input.lockSeams,
+          ...(options?.guard ? { guard: options.guard } : {}),
+        });
         outcomes.push({
           client: "aside", profileId: profile.id, ok: result.ok,
           ...(result.ok ? { changed: result.changed } : {}),

package/src/integrations/catalog-refresh.ts

@@ -2,6 +2,7 @@ import { siblingOfLivePort } from "../codex/sibling-start";
 import { redactSecretString } from "../lib/redact";
 import type { ExportModel } from "../clients/config-export";
 import type { IntegrationClientId } from "./registry";
+import type { CoordinatedIntegrationOptions, WriteOutcome } from "./writer";
 import {
   refreshOwnedIntegration,
   type OwnedIntegrationRefreshInput,
@@ -12,6 +13,7 @@ import {
 export async function refreshOwnedCatalogIntegrations(
   input: Omit<OwnedIntegrationRefreshInput, "clientId">,
   clientIds: readonly IntegrationClientId[] = ["pi", "aside", "raycast", "omo", "commandcode", "droid", "opencode", "kilo"],
+  options: { refreshOnly?: boolean; admit?: () => boolean } = {},
 ): Promise<OwnedIntegrationRefreshOutcome[]> {
   // Client files are shared with the live proxy a sibling instance runs beside; their entries
   // point at the owner's port, and refreshing them here would re-point them at this one.
@@ -20,14 +22,28 @@ export async function refreshOwnedCatalogIntegrations(
   const loadModels = () => models ??= Promise.resolve().then(() =>
     typeof input.models === "function" ? input.models() : input.models);
   const outcomes: OwnedIntegrationRefreshOutcome[] = [];
+  const admit = options.admit;
+  const writeOptions: CoordinatedIntegrationOptions | undefined = admit ? {
+    guard: (frozen): WriteOutcome | null => admit() ? null : {
+      ok: false, reason: "superseded_store", state: "current", clientId: frozen.clientId,
+      message: "Background refresh superseded",
+    },
+  } : undefined;
   for (const clientId of clientIds) {
+    if (admit?.() === false) break;
     try {
       if (clientId === "aside") {
         const { refreshAsideProfiles } = await import("./aside-profiles");
-        outcomes.push(...await refreshAsideProfiles({ ...input, models: loadModels }));
+        const asideOptions = options.refreshOnly === undefined ? writeOptions
+          : { ...writeOptions, refreshOnly: options.refreshOnly };
+        const bound = { ...input, models: loadModels };
+        outcomes.push(...await (asideOptions === undefined
+          ? refreshAsideProfiles(bound) : refreshAsideProfiles(bound, asideOptions)));
         continue;
       }
-      const result = await refreshOwnedIntegration({ ...input, clientId, models: loadModels });
+      const bound = { ...input, clientId, models: loadModels };
+      const result = await (writeOptions === undefined
+        ? refreshOwnedIntegration(bound) : refreshOwnedIntegration(bound, writeOptions));
       if (result) outcomes.push(result);
     } catch (error) {
       const busy = error !== null && typeof error === "object"

package/src/integrations/cursor-detect.ts

@@ -9,7 +9,7 @@
  *
  * Detection is read-only and injectable: the proxy never writes anything into a Cursor
  * install, its state database, or its keychain entries (the T20 exclusion in
- * devlog/_plan/260822_senpi_cursor_transfer/090), and the tests run against a temp tree.
+ * devlog/_fin/260822_senpi_cursor_transfer/090), and the tests run against a temp tree.
  */
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";