opencode-codex-memory 0.5.0 → 0.6.1

package/dist/src/llm.js

@@ -1,12 +1,17 @@
 import fs from "fs";
 import path from "path";
 import { memoryRoot } from "./paths.js";
-import { hostSessionCreate, hostSessionDeletionConfirmed, hostSessionPrompt, hostStructuredOutput, } from "./host-client.js";
-import { pluginShutdownSignal } from "./lifecycle.js";
+import { hostListSessionsGlobal, hostSessionCreate, hostSessionDeletionConfirmed, hostSessionPrompt, hostStructuredOutput, ignoreLateRejection, pluginHttpGet, withHostTimeout, } from "./host-client.js";
+import { isPluginShuttingDown, pluginShutdownSignal } from "./lifecycle.js";
+import { SCAN_LIMIT } from "./store.js";
+import { isProviderCapacityError, ProviderCapacityError } from "./ratelimit.js";
 let inputRef = null;
+let inputGeneration = 0;
 export function setPluginInput(input) {
     inputRef = input;
+    inputGeneration++;
     configModels = null;
+    configModelsInFlight = null;
 }
 export function getPluginInput() {
     return inputRef;
@@ -20,6 +25,25 @@ const SUBSESSION_LIST_TIMEOUT_MS = 5_000;
 const SUBSESSION_ABORT_TIMEOUT_MS = 1_000;
 const SUBSESSION_CONFIRM_TIMEOUT_MS = 1_000;
 const SUBSESSION_DELETE_TIMEOUT_MS = 10_000;
+const SUBSESSION_CREATE_TIMEOUT_MS = 10_000;
+const CONFIG_GET_TIMEOUT_MS = 5_000;
+const SUBSESSION_DELETE_CONCURRENCY = 8;
+const SUBSESSION_DELETE_BATCH_TIMEOUT_MS = 30_000;
+let createTimeoutMs = SUBSESSION_CREATE_TIMEOUT_MS;
+let configGetTimeoutMs = CONFIG_GET_TIMEOUT_MS;
+let staleDeleteBatchTimeoutMs = SUBSESSION_DELETE_BATCH_TIMEOUT_MS;
+/** Test seam. */
+export function setSubSessionCreateTimeoutForTest(ms) {
+    createTimeoutMs = ms ?? SUBSESSION_CREATE_TIMEOUT_MS;
+}
+/** Test seam. */
+export function setConfigGetTimeoutForTest(ms) {
+    configGetTimeoutMs = ms ?? CONFIG_GET_TIMEOUT_MS;
+}
+/** Test seam. */
+export function setStaleDeleteBatchTimeoutForTest(ms) {
+    staleDeleteBatchTimeoutMs = ms ?? SUBSESSION_DELETE_BATCH_TIMEOUT_MS;
+}
 export function isMemorySubSession(sessionId) {
     return activeSubSessions.has(sessionId);
 }
@@ -39,16 +63,20 @@ async function createSession(agent, title) {
     const input = getPluginInput();
     if (!input)
         throw new Error("plugin input not initialized");
+    if (isPluginShuttingDown())
+        throw new SubagentCancelledError();
     const directory = resolveSubSessionDirectory();
     // directory is a query param (not body); without it the client inherits
     // PluginInput.directory, which may be a deleted project path.
-    const res = await hostSessionCreate(input.client, {
+    const controller = new AbortController();
+    const res = await withHostTimeout(hostSessionCreate(input.client, {
         directory,
         body: {
             title: title ?? `codex-memory-${agent}`,
             metadata: { [SUBSESSION_METADATA_KEY]: true },
         },
-    });
+        signal: controller.signal,
+    }), createTimeoutMs, "session.create", controller);
     if (!res.data)
         throw new Error(`session create failed: ${JSON.stringify(res.error ?? {})}`);
     const body = res.data;
@@ -66,23 +94,46 @@ async function createSession(agent, title) {
  * plugin instance — opencode reloads plugins on config change.
  */
 let configModels = null;
+let configModelsInFlight = null;
 async function getConfigModels() {
     if (configModels)
         return configModels;
+    if (configModelsInFlight)
+        return configModelsInFlight;
     const input = getPluginInput();
     if (!input)
         return {};
+    const generation = inputGeneration;
+    const request = (async () => {
+        const controller = new AbortController();
+        try {
+            const res = await withHostTimeout(input.client.config.get({ signal: controller.signal }), configGetTimeoutMs, "config.get", controller);
+            if (res.error || !res.data || generation !== inputGeneration)
+                return {};
+            const resolved = { model: res.data.model, smallModel: res.data.small_model };
+            configModels = resolved;
+            return resolved;
+        }
+        catch {
+            // Config endpoint unavailable: leave models unset so the sub-agent runs
+            // on the session default. Do not cache failures: the next call can recover.
+            return {};
+        }
+    })();
+    configModelsInFlight = request;
     try {
-        const res = await input.client.config.get();
-        const cfg = res?.data;
-        configModels = { model: cfg?.model, smallModel: cfg?.small_model };
+        return await request;
     }
-    catch {
-        // Config endpoint unavailable: leave models unset so the sub-agent runs
-        // on the session default, the previous behavior.
-        configModels = {};
+    finally {
+        if (configModelsInFlight === request)
+            configModelsInFlight = null;
     }
-    return configModels;
+}
+export async function resolveExtractionModel(configured) {
+    return configured ?? (await getConfigModels()).smallModel;
+}
+export async function resolveConsolidationModel(configured) {
+    return configured ?? (await getConfigModels()).model;
 }
 // extract_model / consolidation model strings are "providerID/modelID".
 function parseModelRef(ref) {
@@ -163,9 +214,11 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
             ...(opts.system ? { system: opts.system } : {}),
             ...(model ? { model } : {}),
             ...(opts.format ? { format: opts.format } : {}),
+            ...(opts.variant ? { variant: opts.variant } : {}),
             parts: [{ type: "text", text: prompt }],
         },
     });
+    ignoreLateRejection(promptPromise);
     let timer;
     let onAbort;
     try {
@@ -187,12 +240,21 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
                 timer = setTimeout(() => reject(new SubagentTimeoutError(timeoutMs)), timeoutMs);
             }),
         ]);
-        if (!res.data)
-            throw new Error(`prompt failed: ${JSON.stringify(res.error ?? {})}`);
+        if (!res.data) {
+            const message = `prompt failed: ${JSON.stringify(res.error ?? {})}`;
+            if (isProviderCapacityError(res.error))
+                throw new ProviderCapacityError(message);
+            throw new Error(message);
+        }
         const promptError = res.data.info?.error;
         if (promptError) {
             const detail = promptError.data?.message;
-            throw new Error(`sub-agent prompt failed${promptError.name ? ` (${promptError.name})` : ""}${detail ? `: ${detail}` : ""}`);
+            const status = promptError.data?.statusCode;
+            const message = `sub-agent prompt failed${promptError.name ? ` (${promptError.name})` : ""}` +
+                `${detail ? `: ${detail}` : ""}${status !== undefined ? ` (HTTP ${status})` : ""}`;
+            if (isProviderCapacityError(promptError))
+                throw new ProviderCapacityError(message, status);
+            throw new Error(message);
         }
         return res.data;
     }
@@ -263,7 +325,7 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
     try {
         const prompt = buildExtractionInput(sessionId, opts.cwd ?? "unknown", transcript);
         // extract_model option > opencode small_model > session default.
-        const model = opts.model ?? (await getConfigModels()).smallModel;
+        const model = await resolveExtractionModel(opts.model);
         const data = await runPrompt(subId, prompt, agent, {
             // Mirrors the stage-1 job lease (1h): codex has no per-request timeout,
             // and a near-600k-char transcript on a slow model can easily exceed a
@@ -276,6 +338,9 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
             // call (toolChoice: required) — which is why memorize-extract must allow
             // that one otherwise-denied tool.
             format: { type: "json_schema", schema: EXTRACTION_SCHEMA },
+            // Codex extraction ReasoningEffort::Low. Host maps variant → reasoningEffort;
+            // missing variant on the model is a no-op.
+            variant: "low",
         });
         // The captured JSON lands on AssistantMessage.structured (schema
         // v1/session.ts; absent from the generated SDK type — see host-client.ts).
@@ -306,8 +371,14 @@ export async function consolidateViaSubagent(memoryRoot, diffFileName, model, si
     try {
         const prompt = buildConsolidationPrompt(memoryRoot, diffFileName);
         // consolidation_model option > opencode model (main) > session default.
-        const resolved = model ?? (await getConfigModels()).model;
-        await promptSession(subId, prompt, agent, { model: resolved, timeoutMs: CONSOLIDATION_TIMEOUT_MS, signal });
+        const resolved = await resolveConsolidationModel(model);
+        await promptSession(subId, prompt, agent, {
+            model: resolved,
+            timeoutMs: CONSOLIDATION_TIMEOUT_MS,
+            signal,
+            // Codex consolidation ReasoningEffort::Medium.
+            variant: "medium",
+        });
     }
     catch (err) {
         promptError = err;
@@ -331,46 +402,92 @@ export async function cleanupOldSubSessions(maxAgeMinutes = 90, timeoutMs = SUBS
     const input = getPluginInput();
     if (!input)
         return;
-    let timer;
+    if (!pluginHttpGet(input.client))
+        return;
+    const controller = new AbortController();
+    const staleSessionIds = [];
     try {
-        if (typeof input.client?.session?.list !== "function")
-            return;
-        const res = await Promise.race([
-            input.client.session.list(),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`session.list timed out after ${timeoutMs}ms`)), timeoutMs);
-            }),
-        ]);
-        if (!res.data)
-            return;
-        const list = res.data;
         const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
-        for (const s of list) {
-            if (!s.id)
-                continue;
-            const pluginTitle = isPluginSubSessionTitle(s.title);
-            const owned = s.metadata?.[SUBSESSION_METADATA_KEY] === true && pluginTitle;
-            const legacy = s.metadata?.[SUBSESSION_METADATA_KEY] !== true && pluginTitle;
-            if (!owned && !legacy)
-                continue;
-            // Durable ownership requires marker + generated title; a legacy title
-            // alone can reseed the skip set but never authorizes deletion.
-            activeSubSessions.add(s.id);
-            if (!owned)
+        const deadline = Date.now() + timeoutMs;
+        const seen = new Set();
+        let cursor;
+        let pageLimit = SCAN_LIMIT;
+        while (true) {
+            const remaining = deadline - Date.now();
+            if (remaining <= 0)
+                return;
+            const res = await withHostTimeout(hostListSessionsGlobal(input.client, {
+                limit: pageLimit,
+                cursor,
+                search: "codex-memory-",
+                signal: controller.signal,
+            }), remaining, "experimental.session.list", controller);
+            if (res.error || !Array.isArray(res.data))
+                return;
+            const list = res.data;
+            let newSessionCount = 0;
+            for (const s of list) {
+                if (!s.id || seen.has(s.id))
+                    continue;
+                seen.add(s.id);
+                newSessionCount++;
+                const pluginTitle = isPluginSubSessionTitle(s.title);
+                const owned = s.metadata?.[SUBSESSION_METADATA_KEY] === true && pluginTitle;
+                const legacy = s.metadata?.[SUBSESSION_METADATA_KEY] !== true && pluginTitle;
+                if (!owned && !legacy)
+                    continue;
+                // Durable ownership requires marker + generated title; a legacy title
+                // alone can reseed the skip set but never authorizes deletion.
+                activeSubSessions.add(s.id);
+                if (!owned)
+                    continue;
+                const created = s.time?.created ?? 0;
+                if (created && created < cutoff) {
+                    staleSessionIds.push(s.id);
+                }
+            }
+            if (list.length < pageLimit)
+                return;
+            const updates = list.map((s) => s.time?.updated).filter((updated) => typeof updated === "number" && Number.isFinite(updated) && updated >= 0);
+            if (updates.length === 0)
+                return;
+            // listGlobal uses `updated < cursor`. Add one millisecond so sessions
+            // tied at the page boundary remain visible, then dedupe repeated rows.
+            const nextCursor = updates.reduce((min, updated) => Math.min(min, updated), Infinity) + 1;
+            if (cursor !== undefined && (nextCursor >= cursor || newSessionCount === 0)) {
+                // A full page can consist entirely of the same timestamp. Increase the
+                // page size until unseen tied rows appear or the overall deadline wins.
+                pageLimit += SCAN_LIMIT;
                 continue;
-            const created = s.time?.created ?? 0;
-            if (created && created < cutoff) {
-                void deleteSession(s.id);
             }
+            cursor = nextCursor;
+            pageLimit = SCAN_LIMIT;
         }
     }
     catch {
         // best effort only
     }
     finally {
-        clearTimeout(timer);
+        void deleteStaleSubSessions(staleSessionIds, input, staleDeleteBatchTimeoutMs);
     }
 }
+async function deleteStaleSubSessions(sessionIds, input, timeoutMs) {
+    let cursor = 0;
+    const deadline = Date.now() + timeoutMs;
+    const workers = Array.from({ length: Math.min(SUBSESSION_DELETE_CONCURRENCY, sessionIds.length) }, async () => {
+        while (cursor < sessionIds.length && Date.now() < deadline && !isPluginShuttingDown()) {
+            const id = sessionIds[cursor++];
+            try {
+                await deleteSession(id, input, Math.max(1, Math.min(SUBSESSION_DELETE_TIMEOUT_MS, deadline - Date.now())));
+            }
+            catch {
+                // deleteSession is best-effort; one unexpected failure must not stop
+                // the remaining stale-helper cleanup.
+            }
+        }
+    });
+    await Promise.all(workers);
+}
 function isPluginSubSessionTitle(title) {
     return title === "codex-memory-consolidate" || /^codex-memory-extract-ses_[A-Za-z0-9]+$/.test(title ?? "");
 }
@@ -383,20 +500,21 @@ function isPluginSubSessionTitle(title) {
  * really gone?) and only governs ownership tracking, never the shutdown result:
  * hosts without `session.get` would otherwise never report a clean shutdown.
  */
-async function deleteSession(id) {
-    const input = getPluginInput();
+async function deleteSession(id, input = getPluginInput(), timeoutMs = SUBSESSION_DELETE_TIMEOUT_MS) {
     if (!input)
         return false;
     const controller = new AbortController();
     let timer;
     try {
+        const deletePromise = input.client.session.delete({ path: { id }, signal: controller.signal });
+        ignoreLateRejection(deletePromise);
         const res = await Promise.race([
-            input.client.session.delete({ path: { id }, signal: controller.signal }),
+            deletePromise,
             new Promise((_, reject) => {
                 timer = setTimeout(() => {
                     controller.abort();
-                    reject(new Error(`session.delete timed out after ${SUBSESSION_DELETE_TIMEOUT_MS}ms`));
-                }, SUBSESSION_DELETE_TIMEOUT_MS);
+                    reject(new Error(`session.delete timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
                 timer.unref?.();
             }),
         ]);

package/dist/src/phase1.js

@@ -3,7 +3,7 @@ import { loadTranscript, selectEligibleSessions } from "./capture.js";
 import { redact, isMemoryExcludedFragment } from "./redact.js";
 import { stripCitations } from "./citation.js";
 import { extractViaSubagent, SubagentCancelledError } from "./llm.js";
-import { checkRateLimit, markRateLimitUsed } from "./ratelimit.js";
+import { checkRateLimit, isProviderCapacityBlocked, isProviderCapacityError, markRateLimitUsed, noteProviderCapacityExhausted, ProviderCapacityError, } from "./ratelimit.js";
 import { isPluginShuttingDown } from "./lifecycle.js";
 import { recordDiagnostic } from "./diagnostics.js";
 export const DEFAULT_PHASE1_OPTIONS = {
@@ -26,7 +26,14 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
         return;
     // Prune first (no tokens), matching codex start.rs ordering before the gate.
     store.pruneStage1Outputs(opts.maxUnusedDays ?? 30);
-    const rl = await rateLimitCheck("phase1");
+    // Historical quota-exhausted jobs never get a newer watermark; reopen them
+    // before the gate so a later unblocked pass can claim them.
+    const requeued = store.requeueExhaustedProviderCapacityJobs();
+    if (requeued > 0) {
+        recordDiagnostic("info", "phase1", `requeued ${requeued} quota-exhausted job(s)`);
+    }
+    const extractModel = opts.extractModel;
+    const rl = await rateLimitCheck("phase1", extractModel);
     if (!rl.ok) {
         console.warn("[opencode-codex-memory] skipping phase1 due to rate limit:", rl.reason);
         return;
@@ -54,6 +61,11 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
             store.releaseStage1OnShutdown(sid, claim.ownershipToken);
             return;
         }
+        // Sibling jobs in this pass: do not call the model after quota was observed.
+        if (isProviderCapacityBlocked("phase1", extractModel)) {
+            store.markStage1Failed(sid, claim.ownershipToken, new ProviderCapacityError("provider capacity exhausted"));
+            return;
+        }
         try {
             const session = sessionById.get(sid);
             const sourceUpdatedAt = session?.updated_at ?? Date.now();
@@ -74,7 +86,7 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
             }
             const result = await extractViaSubagent(sid, transcript, {
                 cwd: session?.directory ?? undefined,
-                model: opts.extractModel,
+                model: extractModel,
             });
             // Finalize after a completed model call even if dispose raced, so the
             // claim does not sit `running` until lease expiry. The mark is token +
@@ -103,6 +115,8 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
                 store.releaseStage1OnShutdown(sid, claim.ownershipToken);
             }
             else {
+                if (isProviderCapacityError(err))
+                    noteProviderCapacityExhausted("phase1", extractModel);
                 store.markStage1Failed(sid, claim.ownershipToken, err);
             }
         }

package/dist/src/phase2.d.ts

@@ -12,6 +12,18 @@ export interface Phase2Options {
     heartbeatIntervalMs?: number;
 }
 export declare const DEFAULT_PHASE2_OPTIONS: Phase2Options;
+/**
+ * Codex get_phase2_input_selection re-validates each row against the live
+ * threads table. We only drop a row on a confirmed 404 (same as session.deleted);
+ * timeouts / missing get / other errors keep the row.
+ */
+export declare function dropGonePhase2Inputs(store: MemoryStore, selected: ReturnType<MemoryStore["getPhase2InputSelection"]>): Promise<ReturnType<MemoryStore["getPhase2InputSelection"]>>;
+/**
+ * Codex pages ranked candidates until it has `maxRaw` rows whose threads are
+ * still live. Our thread metadata lives in the host, so confirmed-gone rows
+ * are deleted and the ranking is queried again to backfill their slots.
+ */
+export declare function selectLivePhase2Inputs(store: MemoryStore, maxRaw: number, maxUnusedDays: number): Promise<ReturnType<MemoryStore["getPhase2InputSelection"]>>;
 /** True while THIS process runs a consolidation (memory_reset refuses then). */
 export declare function isPhase2InFlight(): boolean;
 export declare function runPhase2(store: MemoryStore, opts?: Phase2Options): Promise<{

package/dist/src/phase2.js

@@ -1,6 +1,8 @@
+import { checkRateLimit, isProviderCapacityError, noteProviderCapacityExhausted } from "./ratelimit.js";
 import { ensureLayout, rebuildRawMemories, writeRolloutSummaries, pruneExtensionResources, writeWorkspaceDiff, validateConsolidationArtifacts, } from "./workspace.js";
 import { ensureBaseline, captureWorkspaceDiff, resetBaseline, DIFF_ARTIFACT } from "./git-baseline.js";
-import { consolidateViaSubagent, SubagentCancelledError, SubagentShutdownError } from "./llm.js";
+import { consolidateViaSubagent, getPluginInput, SubagentCancelledError, SubagentShutdownError, } from "./llm.js";
+import { hostSessionLiveness } from "./host-client.js";
 import { invalidateCache } from "./source.js";
 import { memoryRoot } from "./paths.js";
 import { abortPhase2Consolidation, beginPhase2AbortScope, endPhase2AbortScope, isPluginShuttingDown, } from "./lifecycle.js";
@@ -13,6 +15,59 @@ export const DEFAULT_PHASE2_OPTIONS = {
 };
 // Export runs only after a successful phase 2 (fresh, validated artifacts) and
 // must never fail the run — Codex's workspace is best-effort foreign territory.
+const PHASE2_LIVE_CHECK_CONCURRENCY = 8;
+/**
+ * Codex get_phase2_input_selection re-validates each row against the live
+ * threads table. We only drop a row on a confirmed 404 (same as session.deleted);
+ * timeouts / missing get / other errors keep the row.
+ */
+export async function dropGonePhase2Inputs(store, selected) {
+    const client = getPluginInput()?.client;
+    if (!client || selected.length === 0)
+        return selected;
+    const kept = [];
+    for (let i = 0; i < selected.length; i += PHASE2_LIVE_CHECK_CONCURRENCY) {
+        const chunk = selected.slice(i, i + PHASE2_LIVE_CHECK_CONCURRENCY);
+        const results = await Promise.all(chunk.map(async (out) => ({ out, live: await hostSessionLiveness(client, out.session_id) })));
+        for (const { out, live } of results) {
+            if (live === "gone")
+                store.deleteSessionMemory(out.session_id);
+            else
+                kept.push(out);
+        }
+    }
+    return kept;
+}
+/**
+ * Codex pages ranked candidates until it has `maxRaw` rows whose threads are
+ * still live. Our thread metadata lives in the host, so confirmed-gone rows
+ * are deleted and the ranking is queried again to backfill their slots.
+ */
+export async function selectLivePhase2Inputs(store, maxRaw, maxUnusedDays) {
+    if (maxRaw <= 0)
+        return [];
+    const selected = [];
+    const seen = new Set();
+    while (selected.length < maxRaw) {
+        // Once most slots are filled, inspect one liveness chunk beyond the
+        // already-selected rows so a single gone row does not force serial probes.
+        const scanLimit = Math.max(maxRaw, selected.length + PHASE2_LIVE_CHECK_CONCURRENCY);
+        const candidates = store
+            .getPhase2InputSelection(scanLimit, maxUnusedDays)
+            .filter((output) => !seen.has(output.session_id));
+        if (candidates.length === 0)
+            break;
+        for (const output of candidates)
+            seen.add(output.session_id);
+        const live = await dropGonePhase2Inputs(store, candidates);
+        for (const output of live) {
+            selected.push(output);
+            if (selected.length >= maxRaw)
+                break;
+        }
+    }
+    return selected;
+}
 function maybeExportToCodex(interop) {
     if (!interop?.exportEnabled)
         return;
@@ -42,9 +97,12 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
         return { status: "already_running" };
     phase2InFlight = true;
     try {
-        // No process-local rate gate: codex serializes phase 2 only via the DB
-        // claim (cooldown / running / retry_at). Empty and cooldown skips must
-        // not delay a later real claim.
+        // No 30s process gate: codex serializes phase 2 only via the DB claim.
+        // An observed quota stamp still skips both phases (Codex start.rs).
+        const consolidationModel = opts.consolidationModel;
+        const rl = await checkRateLimit("phase2", consolidationModel);
+        if (!rl.ok)
+            return { status: "skipped_rate_limit" };
         const claim = store.claimGlobalPhase2Job();
         if (claim.type !== "claimed")
             return { status: claim.type };
@@ -73,7 +131,7 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
             if (releaseIfShuttingDown(store, claim.ownershipToken)) {
                 return { status: "shutting_down" };
             }
-            const outputs = store.getPhase2InputSelection(opts.maxRaw, opts.maxUnusedDays);
+            const outputs = await selectLivePhase2Inputs(store, opts.maxRaw, opts.maxUnusedDays);
             rebuildRawMemories(outputs);
             writeRolloutSummaries(outputs);
             pruneExtensionResources(opts.extensionRetentionDays);
@@ -158,7 +216,7 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
             }
             const heartbeat = setInterval(heartbeatOnce, opts.heartbeatIntervalMs ?? 90_000);
             try {
-                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel, consolidationSignal);
+                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, consolidationModel, consolidationSignal);
             }
             catch (err) {
                 // codex phase2.rs: when the consolidation agent's shutdown fails, keep
@@ -218,6 +276,8 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
                 store.releasePhase2OnShutdown(claim.ownershipToken);
                 return { status: "shutting_down" };
             }
+            if (isProviderCapacityError(err))
+                noteProviderCapacityExhausted("phase2", consolidationModel);
             store.markPhase2Failed(claim.ownershipToken, err);
             return { status: "failed" };
         }

package/dist/src/ratelimit.d.ts

@@ -2,8 +2,24 @@ export interface RateLimitInfo {
     ok: boolean;
     reason?: string;
 }
-export declare function checkRateLimit(kind?: "phase1" | "phase2"): Promise<RateLimitInfo>;
+export type MemoryPhase = "phase1" | "phase2";
+export interface ProviderCapacityBackoff {
+    scope: string;
+    retry_at: number;
+}
+export declare class ProviderCapacityError extends Error {
+    readonly statusCode?: number | undefined;
+    constructor(message: string, statusCode?: number | undefined);
+}
+export declare const PROVIDER_CAPACITY_BACKOFF_MS = 3600000;
+export declare function providerCapacityMessage(error: unknown): string;
+export declare function isProviderCapacityError(error: unknown): boolean;
+export declare function activeProviderCapacityBackoffs(now?: number): ProviderCapacityBackoff[];
+export declare function isProviderCapacityBlocked(phase: MemoryPhase, model?: string, now?: number): boolean;
+/** Call after a quota/rate-limit failure so later passes skip claiming. */
+export declare function noteProviderCapacityExhausted(phase: MemoryPhase, model?: string, now?: number): void;
+export declare function checkRateLimit(kind?: MemoryPhase, model?: string): Promise<RateLimitInfo>;
 /** Call after a phase-1 pass claimed at least one job (token-using work started). */
 export declare function markRateLimitUsed(kind?: "phase1" | "phase2"): void;
-/** Test seam: reset the process-local stamp. */
+/** Test seam: reset the process-local stamps. */
 export declare function resetRateLimitForTest(): void;