opencode-codex-memory 0.6.0 → 0.6.1

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;

package/dist/src/ratelimit.js

@@ -1,23 +1,103 @@
+export class ProviderCapacityError extends Error {
+    statusCode;
+    constructor(message, statusCode) {
+        super(message);
+        this.statusCode = statusCode;
+        this.name = "ProviderCapacityError";
+    }
+}
 /**
- * Process-local anti-stampede for phase 1 only.
+ * Process-local anti-stampede for phase 1, plus an observed-quota circuit
+ * breaker that stands in for Codex guard.rs.
  *
  * Codex has no wall-clock throttle: it reads live provider quota once per
  * startup (memories/write/src/guard.rs) and fails open when unknown. Opencode
- * does not expose provider rate limits to plugins, so this stub keeps
- * chat.message/idle from hammering discovery + claim when many sessions go
- * idle at once.
+ * does not expose provider rate limits to plugins, so this stub:
+ * - keeps chat.message/idle from hammering discovery + claim (30s, phase 1)
+ * - after a quota/rate-limit API error, skips further claims until the same
+ *   1h window Codex uses for job retry_at — so a quota outage cannot burn
+ *   every eligible session's retry budget
  *
  * Semantics deliberately match "do not start another token-using run too
  * often", not "do not look often":
- * - checkRateLimit only reads the clock (empty/no-claim passes do not stamp)
+ * - checkRateLimit only reads clocks (empty/no-claim passes do not stamp)
  * - markRateLimitUsed stamps after a stage-1 claim actually succeeds
- * - phase 2 has no process timer; the DB claim + 6h cooldown serialize it
- *   (same as codex phase2 job outcomes)
+ * - noteProviderCapacityExhausted stamps after an observed quota error
+ * - phase 2 has no 30s timer; the DB claim + 6h cooldown serialize it.
+ *   The observed-quota stamp still skips phase 2 (Codex start.rs skips both).
  */
 let lastPhase1Work = 0;
+const providerCapacityUntil = new Map();
 const MIN_PHASE1_INTERVAL_MS = 30_000;
-export async function checkRateLimit(kind = "phase1") {
-    // Phase 2: no process-local gate (codex relies on DB claim/cooldown only).
+export const PROVIDER_CAPACITY_BACKOFF_MS = 3_600_000;
+const PROVIDER_CAPACITY_RE = /usage limit|free usage exceeded|provider capacity exhausted|rate[\s_-]?limit|quota(?:\s+(?:exceeded|exhausted|reached))?|too many requests|\b429\b|resource_exhausted|insufficient_quota|billing.?hard.?limit/i;
+function errorRecord(error) {
+    return error && typeof error === "object" ? error : null;
+}
+function providerCapacityStatusCode(error) {
+    const record = errorRecord(error);
+    const data = errorRecord(record?.data);
+    const value = record?.statusCode ?? data?.statusCode;
+    if (typeof value === "number")
+        return value;
+    if (typeof value === "string" && /^\d+$/.test(value))
+        return Number(value);
+    return null;
+}
+export function providerCapacityMessage(error) {
+    try {
+        if (typeof error === "string")
+            return error;
+        if (error instanceof Error)
+            return String(error.message ?? "unknown error");
+        const record = errorRecord(error);
+        const data = errorRecord(record?.data);
+        const message = record?.message ?? data?.message;
+        if (typeof message === "string")
+            return message;
+        return String(error ?? "unknown error");
+    }
+    catch {
+        return "unknown error";
+    }
+}
+export function isProviderCapacityError(error) {
+    if (error instanceof ProviderCapacityError)
+        return true;
+    if (providerCapacityStatusCode(error) === 429)
+        return true;
+    return PROVIDER_CAPACITY_RE.test(providerCapacityMessage(error));
+}
+function providerCapacityScope(phase, model) {
+    return model ? `model:${model}` : `phase:${phase}:default`;
+}
+export function activeProviderCapacityBackoffs(now = Date.now()) {
+    const active = [];
+    for (const [scope, until] of providerCapacityUntil) {
+        if (until <= now) {
+            providerCapacityUntil.delete(scope);
+            continue;
+        }
+        active.push({ scope, retry_at: Math.floor(until / 1000) });
+    }
+    return active.sort((a, b) => a.scope.localeCompare(b.scope));
+}
+export function isProviderCapacityBlocked(phase, model, now = Date.now()) {
+    const until = providerCapacityUntil.get(providerCapacityScope(phase, model));
+    return until !== undefined && until > now;
+}
+/** Call after a quota/rate-limit failure so later passes skip claiming. */
+export function noteProviderCapacityExhausted(phase, model, now = Date.now()) {
+    providerCapacityUntil.set(providerCapacityScope(phase, model), now + PROVIDER_CAPACITY_BACKOFF_MS);
+}
+export async function checkRateLimit(kind = "phase1", model) {
+    if (isProviderCapacityBlocked(kind, model)) {
+        return {
+            ok: false,
+            reason: `provider capacity exhausted for ${providerCapacityScope(kind, model)} (observed quota/rate-limit)`,
+        };
+    }
+    // Phase 2: no 30s gate (codex relies on DB claim/cooldown only).
     if (kind === "phase2")
         return { ok: true };
     const now = Date.now();
@@ -31,7 +111,8 @@ export function markRateLimitUsed(kind = "phase1") {
     if (kind === "phase1")
         lastPhase1Work = Date.now();
 }
-/** Test seam: reset the process-local stamp. */
+/** Test seam: reset the process-local stamps. */
 export function resetRateLimitForTest() {
     lastPhase1Work = 0;
+    providerCapacityUntil.clear();
 }

package/dist/src/store.d.ts

@@ -57,6 +57,13 @@ export declare class MemoryStore {
     /** Extraction succeeded but produced nothing worth keeping: finish the job and drop any stale output. */
     markStage1SucceededNoOutput(sessionId: string, ownershipToken: string, sourceUpdatedAt: number): void;
     markStage1Failed(sessionId: string, ownershipToken: string, error: unknown): void;
+    /**
+     * Re-open stage-1 jobs that exhausted their retry budget solely because of
+     * a quota/rate-limit error. Historical completed sessions never get a newer
+     * watermark, so without this they stay failed forever after a quota outage.
+     * Leaves retry_at alone so an active backoff still holds.
+     */
+    requeueExhaustedProviderCapacityJobs(): number;
     /**
      * Plugin dispose/reload: release a claimed stage-1 job without burning a retry
      * or imposing the 1h backoff. Leaves status=pending so the next process can
@@ -146,11 +153,20 @@ export declare class MemoryStore {
      */
     stage1JobSnapshot(): {
         by_status: Record<string, number>;
-        recent_errors: {
-            session_id: string;
-            last_error: string;
-            retry_at: number | null;
-            status: string;
-        }[];
+        by_failure_class: {
+            backoff: number;
+            provider_capacity: number;
+            other_exhausted: number;
+        };
+        recent_errors: Stage1RecentError[];
     };
 }
+export type Stage1FailureClass = "backoff" | "provider_capacity" | "other_exhausted";
+export interface Stage1RecentError {
+    session_id: string;
+    last_error: string;
+    retry_at: number | null;
+    status: string;
+    retry_remaining: number;
+    failure_class: Stage1FailureClass | null;
+}

package/dist/src/store.js

@@ -1,4 +1,5 @@
 import { openDb } from "./db.js";
+import { isProviderCapacityError } from "./ratelimit.js";
 export const DEFAULT_RETRY_REMAINING = 3;
 export const STAGE1_LEASE_SECONDS = 3600;
 export const PHASE2_LEASE_SECONDS = 3600;
@@ -191,6 +192,24 @@ export class MemoryStore {
     }
     markStage1Failed(sessionId, ownershipToken, error) {
         const message = failureMessage(error);
+        const tNow = nowSec();
+        const retryAt = tNow + STAGE1_RETRY_DELAY_SECONDS;
+        // Quota/rate-limit is transient provider capacity, not a bad transcript.
+        // Codex avoids claiming in that state via guard.rs; we cannot read quota,
+        // so keep the job pending and do not burn retry_remaining. Claim still
+        // honors retry_at, so this cannot tight-loop while quota is down.
+        if (isProviderCapacityError(error)) {
+            this.db
+                .prepare(`UPDATE memory_jobs SET
+             status = 'pending',
+             last_error = ?,
+             retry_at = ?,
+             finished_at = ?,
+             lease_until = NULL
+           WHERE kind='memory_stage1' AND job_key=? AND status='running' AND ownership_token=?`)
+                .run(message.slice(0, 4000), retryAt, tNow, sessionId, ownershipToken);
+            return;
+        }
         this.db
             .prepare(`UPDATE memory_jobs SET
            status = CASE WHEN retry_remaining > 1 THEN 'pending' ELSE 'failed' END,
@@ -200,7 +219,30 @@ export class MemoryStore {
            finished_at = ?,
            lease_until = NULL
          WHERE kind='memory_stage1' AND job_key=? AND status='running' AND ownership_token=?`)
-            .run(message.slice(0, 4000), nowSec() + STAGE1_RETRY_DELAY_SECONDS, nowSec(), sessionId, ownershipToken);
+            .run(message.slice(0, 4000), retryAt, tNow, sessionId, ownershipToken);
+    }
+    /**
+     * Re-open stage-1 jobs that exhausted their retry budget solely because of
+     * a quota/rate-limit error. Historical completed sessions never get a newer
+     * watermark, so without this they stay failed forever after a quota outage.
+     * Leaves retry_at alone so an active backoff still holds.
+     */
+    requeueExhaustedProviderCapacityJobs() {
+        const rows = this.db
+            .prepare(`SELECT job_key, last_error FROM memory_jobs
+         WHERE kind='memory_stage1' AND status='failed' AND last_error IS NOT NULL`)
+            .all();
+        let n = 0;
+        const stmt = this.db.prepare(`UPDATE memory_jobs SET status='pending', retry_remaining=?
+       WHERE kind='memory_stage1' AND job_key=? AND status='failed'`);
+        this.db.transaction(() => {
+            for (const row of rows) {
+                if (!isProviderCapacityError(row.last_error))
+                    continue;
+                n += stmt.run(DEFAULT_RETRY_REMAINING, row.job_key).changes;
+            }
+        }).immediate();
+        return n;
     }
     /**
      * Plugin dispose/reload: release a claimed stage-1 job without burning a retry
@@ -529,12 +571,39 @@ export class MemoryStore {
         const by_status = {};
         for (const r of rows)
             by_status[r.status] = r.c;
-        const recent_errors = this.db
-            .prepare(`SELECT job_key AS session_id, last_error, retry_at, status FROM memory_jobs
+        const tNow = nowSec();
+        const errorRows = this.db
+            .prepare(`SELECT job_key AS session_id, last_error, retry_at, status, retry_remaining FROM memory_jobs
          WHERE kind='memory_stage1' AND last_error IS NOT NULL
-         ORDER BY COALESCE(finished_at, started_at, 0) DESC
-         LIMIT 5`)
+         ORDER BY COALESCE(finished_at, started_at, 0) DESC`)
             .all();
-        return { by_status, recent_errors };
+        const by_failure_class = { backoff: 0, provider_capacity: 0, other_exhausted: 0 };
+        const recent_errors = [];
+        for (const row of errorRows) {
+            const failure_class = classifyStage1Failure(row, tNow);
+            if (failure_class)
+                by_failure_class[failure_class]++;
+            if (recent_errors.length < 5) {
+                recent_errors.push({
+                    session_id: row.session_id,
+                    last_error: row.last_error,
+                    retry_at: row.retry_at,
+                    status: row.status,
+                    retry_remaining: row.retry_remaining,
+                    failure_class,
+                });
+            }
+        }
+        return { by_status, by_failure_class, recent_errors };
+    }
+}
+function classifyStage1Failure(row, nowSec) {
+    if (row.status === "failed" || row.retry_remaining <= 0) {
+        return isProviderCapacityError(row.last_error) ? "provider_capacity" : "other_exhausted";
     }
+    if (row.retry_at != null && row.retry_at > nowSec)
+        return "backoff";
+    if (isProviderCapacityError(row.last_error))
+        return "provider_capacity";
+    return null;
 }

package/dist/tools/control.js

@@ -13,6 +13,7 @@ import { claudeImportStatus, resolveClaudeHome } from "../src/claude-import.js";
 import { formatDiagnosticLine, getDiscoveryStatus, getRecentDiagnostics, } from "../src/diagnostics.js";
 import { isPluginShuttingDown } from "../src/lifecycle.js";
 import { getAgentHealth } from "../src/agent-health.js";
+import { activeProviderCapacityBackoffs } from "../src/ratelimit.js";
 function isSymlinkedRoot() {
     try {
         assertMemoryRootSafe();
@@ -200,7 +201,8 @@ function fmtWatermarkMs(ms) {
 }
 export const memory_inspect = tool({
     description: "Inspect the current memory state. Returns: stage1_outputs count, stage-1 job status " +
-        "breakdown and recent errors, Phase 2 job status (including last error / retry time), " +
+        "breakdown, failure classes (backoff / provider_capacity / other_exhausted), recent errors, " +
+        "Phase 2 job status (including last error / retry time), " +
         "last discovery outcome, pipeline diagnostics, memory_summary token estimate " +
         "(on-disk; injection caps at ~2500), a listing of the memories directory, the " +
         "effective plugin options, and any configuration warnings. Use it to verify " +
@@ -244,9 +246,20 @@ export const memory_inspect = tool({
             const stage1StatusParts = Object.entries(stage1Jobs.by_status)
                 .sort(([a], [b]) => a.localeCompare(b))
                 .map(([s, c]) => `${s}=${c}`);
+            const fc = stage1Jobs.by_failure_class;
+            const failureParts = [
+                fc.backoff > 0 ? `backoff=${fc.backoff}` : "",
+                fc.provider_capacity > 0 ? `provider_capacity=${fc.provider_capacity}` : "",
+                fc.other_exhausted > 0 ? `other_exhausted=${fc.other_exhausted}` : "",
+            ].filter(Boolean);
             const stage1Lines = [
                 `stage1_jobs: ${stage1StatusParts.length > 0 ? stage1StatusParts.join(" ") : "none"}`,
-                ...stage1Jobs.recent_errors.map((e) => `  stage1_error ${e.session_id} (${e.status}): ${e.last_error.slice(0, 200)}${e.retry_at ? ` retry_at=${fmtUnixSec(e.retry_at)}` : ""}`),
+                `stage1_failures: ${failureParts.length > 0 ? failureParts.join(" ") : "none"}`,
+                ...stage1Jobs.recent_errors.map((e) => {
+                    const klass = e.failure_class ? `, ${e.failure_class}` : "";
+                    const retry = e.retry_at ? ` retry_at=${fmtUnixSec(e.retry_at)}` : "";
+                    return `  stage1_error ${e.session_id} (${e.status}${klass}): ${e.last_error.slice(0, 200)}${retry}`;
+                }),
             ];
             const discovery = getDiscoveryStatus();
             const discoveryLine = discovery
@@ -260,6 +273,10 @@ export const memory_inspect = tool({
                 `phase2_in_flight: ${isPhase2InFlight()}`,
                 `plugin_shutting_down: ${isPluginShuttingDown()}`,
             ];
+            const capacityBackoffs = activeProviderCapacityBackoffs();
+            const capacityLines = capacityBackoffs.length > 0
+                ? capacityBackoffs.map((b) => `provider_capacity_backoff ${b.scope}: retry_at=${fmtUnixSec(b.retry_at)}`)
+                : ["provider_capacity_backoff: none"];
             const diagnostics = getRecentDiagnostics(12);
             const diagnosticLines = diagnostics.length > 0
                 ? ["recent_events:", ...diagnostics.map((e) => `  ${formatDiagnosticLine(e)}`)]
@@ -271,6 +288,7 @@ export const memory_inspect = tool({
                 discoveryLine,
                 eligibilityHint,
                 ...processLines,
+                ...capacityLines,
                 `memory_summary_chars: ${summaryChars}`,
                 `memory_summary_tokens_est: ${summaryTokens} (on disk; injection caps at ~2500)`,
                 `memories_dir_entries: ${listing.length}`,
@@ -289,6 +307,7 @@ export const memory_inspect = tool({
                 metadata: {
                     stage1_count: outputs.length,
                     stage1_jobs: stage1Jobs.by_status,
+                    stage1_failures: stage1Jobs.by_failure_class,
                     stage1_recent_errors: stage1Jobs.recent_errors,
                     phase2_status: phase2?.status ?? null,
                     phase2_last_error: phase2?.last_error ?? null,
@@ -296,6 +315,7 @@ export const memory_inspect = tool({
                     phase2_last_attempt_finished_at: phase2?.finished_at ?? null,
                     phase2_last_success_watermark: phase2?.last_success_watermark ?? null,
                     phase2_last_success_finished_at: phase2?.success_finished_at ?? null,
+                    provider_capacity_backoffs: capacityBackoffs,
                     // Back-compat aliases used by earlier inspect consumers.
                     phase2_last_finished_at: phase2?.success_finished_at ?? null,
                     discovery,

package/dist/tools/memory.js

@@ -20,7 +20,9 @@ export const memory_read = tool({
             }
             const stat = fs.lstatSync(fullPath);
             if (stat.isDirectory()) {
-                const entries = fs.readdirSync(fullPath);
+                const entries = visibleEntries(fullPath)
+                    .sort((a, b) => comparePathNames(a.name, b.name))
+                    .map((e) => e.name);
                 return {
                     output: `Directory ${args.path}/\n` + entries.map((e) => `- ${e}`).join("\n") + "\n(use memory_list for sorted, typed listings)",
                     metadata: { kind: "directory", entries },
@@ -194,7 +196,7 @@ function parseDateArg(value, endOfDay) {
 function collectSearchFiles(start, prefix) {
     const files = [];
     const walk = (dir, rel) => {
-        const entries = visibleEntries(dir).sort((a, b) => a.name.localeCompare(b.name));
+        const entries = visibleEntries(dir).sort((a, b) => comparePathNames(a.name, b.name));
         for (const { name, isDir } of entries) {
             const abs = path.join(dir, name);
             const relPath = rel ? `${rel}/${name}` : name;
@@ -366,7 +368,21 @@ export const memory_search = tool({
             }
             const rangeLabel = timeFiltered ? ` in ${args.since ?? "..."}..${args.until ?? "..."}` : "";
             if (queries.length === 0) {
-                const listing = files.slice(0, args.max_results).map((f) => {
+                let startIndex = 0;
+                if (args.cursor !== undefined) {
+                    startIndex = Number.parseInt(args.cursor, 10);
+                    if (!Number.isInteger(startIndex) || startIndex < 0 || String(startIndex) !== args.cursor.trim()) {
+                        return { output: `memory_search error: invalid cursor "${args.cursor}" (must be a non-negative integer).` };
+                    }
+                    if (startIndex > files.length) {
+                        return { output: `memory_search error: cursor ${startIndex} exceeds result count ${files.length}.` };
+                    }
+                }
+                const endIndex = Math.min(startIndex + (args.max_results ?? SEARCH_MAX_RESULTS), files.length);
+                const page = files.slice(startIndex, endIndex);
+                const nextCursor = endIndex < files.length ? String(endIndex) : null;
+                const truncated = nextCursor !== null;
+                const listing = page.map((f) => {
                     let content = "";
                     try {
                         content = readRegularFileNoFollow(f.abs).content.toString("utf8");
@@ -375,11 +391,25 @@ export const memory_search = tool({
                     }
                     return `${new Date(f.ts).toISOString()} ${f.rel} — ${firstContentLine(content)}`;
                 });
-                if (listing.length === 0)
+                if (files.length === 0)
                     return { output: `No time-anchored memory files${rangeLabel}.` };
+                if (listing.length === 0) {
+                    return {
+                        output: `No memory files at cursor ${startIndex}${rangeLabel}.`,
+                        metadata: { count: 0, next_cursor: nextCursor, truncated, since: args.since, until: args.until },
+                    };
+                }
                 return {
-                    output: `${listing.length} memory file(s)${rangeLabel}:\n${listing.join("\n")}`,
-                    metadata: { count: listing.length, since: args.since, until: args.until },
+                    output: `${listing.length} of ${files.length} memory file(s)${rangeLabel}` +
+                        `${truncated ? ` (more available; pass cursor=${nextCursor})` : ""}:\n` +
+                        listing.join("\n"),
+                    metadata: {
+                        count: listing.length,
+                        next_cursor: nextCursor,
+                        truncated,
+                        since: args.since,
+                        until: args.until,
+                    },
                 };
             }
             const caseSensitive = args.case_sensitive ?? true;
@@ -402,7 +432,7 @@ export const memory_search = tool({
                     continue; // binary, like codex's InvalidData skip
                 searchFileContent(f, content.split(/\r?\n/), queries, preparedQueries, mode, args.line_count ?? 1, args.context_lines ?? 0, caseSensitive, normalized, all);
             }
-            all.sort((a, b) => a.path.localeCompare(b.path) || a.match_line_number - b.match_line_number);
+            all.sort((a, b) => comparePathNames(a.path, b.path) || a.match_line_number - b.match_line_number);
             let startIndex = 0;
             if (args.cursor !== undefined) {
                 startIndex = Number.parseInt(args.cursor, 10);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Persistent memory plugin for opencode — ports codex's two-phase memory system (extraction → consolidation → injection → citation feedback)",
   "type": "module",
   "main": "./dist/src/index.js",