opencode-codex-memory 0.4.6 → 0.4.8

package/dist/src/lifecycle.js

@@ -0,0 +1,45 @@
+/**
+ * Plugin process lifecycle: shutdown flag + phase-2 abort signal shared by
+ * the entry dispose hook and the write pipeline.
+ *
+ * Opencode can reload plugins while a consolidator helper still holds write
+ * access to the memory root. dispose() sets the flag (so new pumps stop),
+ * aborts the in-flight consolidation prompt, and best-effort aborts active
+ * sub-sessions (llm.ts).
+ */
+let shuttingDown = false;
+let phase2Abort = null;
+export function isPluginShuttingDown() {
+    return shuttingDown;
+}
+/** Begin shutdown: no new phase work, abort any in-flight consolidator. */
+export function beginPluginShutdown() {
+    shuttingDown = true;
+    phase2Abort?.abort();
+}
+/**
+ * Test / re-boot seam: a fresh server() call clears the previous dispose.
+ * Abort any live consolidator controller before dropping the reference so a
+ * glitched boot order cannot orphan a still-running phase-2 prompt.
+ */
+export function resetPluginLifecycle() {
+    phase2Abort?.abort();
+    phase2Abort = null;
+    shuttingDown = false;
+}
+/**
+ * AbortSignal for the current phase-2 consolidation run. Created when the job
+ * is claimed; aborted on heartbeat loss, dispose, or run end.
+ */
+export function beginPhase2AbortScope() {
+    phase2Abort?.abort();
+    phase2Abort = new AbortController();
+    return phase2Abort.signal;
+}
+export function endPhase2AbortScope() {
+    phase2Abort = null;
+}
+/** Abort the current consolidator from outside phase2 (dispose). */
+export function abortPhase2Consolidation() {
+    phase2Abort?.abort();
+}

package/dist/src/llm.d.ts

@@ -37,6 +37,8 @@ export interface ExtractOptions {
 export declare function extractViaSubagent(sessionId: string, transcript: string, opts?: ExtractOptions): Promise<ExtractionResult | null>;
 export declare function consolidateViaSubagent(memoryRoot: string, diffFileName: string, model?: string, signal?: AbortSignal): Promise<void>;
 export declare function cleanupOldSubSessions(maxAgeMinutes?: number, timeoutMs?: number): Promise<void>;
+/** Best-effort abort of every memory sub-session (plugin dispose / reload). */
+export declare function abortActiveSubSessions(): Promise<void>;
 export declare function fillTemplate(tmpl: string, vars: Record<string, string>): string;
 export declare function buildConsolidationPrompt(memoryRoot: string, diffFileName: string): string;
 /**

package/dist/src/llm.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { memoryRoot } from "./paths.js";
+import { hostSessionCreate, hostSessionDeletionConfirmed, hostSessionPrompt, hostStructuredOutput, } from "./host-client.js";
 let inputRef = null;
 export function setPluginInput(input) {
     inputRef = input;
@@ -38,10 +39,10 @@ async function createSession(agent, title) {
     if (!input)
         throw new Error("plugin input not initialized");
     const directory = resolveSubSessionDirectory();
-    const res = await input.client.session.create({
-        // directory is a query param (not body); without it the client inherits
-        // PluginInput.directory, which may be a deleted project path.
-        query: { directory },
+    // 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, {
+        directory,
         body: {
             title: title ?? `codex-memory-${agent}`,
             metadata: { [SUBSESSION_METADATA_KEY]: true },
@@ -154,10 +155,8 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
         throw new SubagentCancelledError();
     }
     const model = opts.model ? parseModelRef(opts.model) : null;
-    const promptPromise = input.client.session.prompt({
-        path: { id: sessionId },
-        // `format` lives in the server's PromptInput but not the generated SDK body
-        // type yet (same OpenAPI lag as session.list scope/roots), hence the cast.
+    const promptPromise = hostSessionPrompt(input.client, {
+        sessionId,
         body: {
             agent,
             ...(opts.system ? { system: opts.system } : {}),
@@ -265,11 +264,11 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
             format: { type: "json_schema", schema: EXTRACTION_SCHEMA },
         });
         // The captured JSON lands on AssistantMessage.structured (schema
-        // v1/session.ts; absent from the generated SDK type, so read it untyped).
+        // v1/session.ts; absent from the generated SDK type — see host-client.ts).
         // Fall back to text parsing when structured output is unavailable (a host
         // without the feature, or a model that emitted JSON as plain text).
-        const structured = data?.info?.structured;
-        if (structured && typeof structured === "object") {
+        const structured = hostStructuredOutput(data);
+        if (structured) {
             return validateExtraction(structured);
         }
         return parseExtraction(extractAssistantText(data));
@@ -396,7 +395,7 @@ async function deleteSession(id) {
         // session is gone; otherwise retain ownership so hooks keep skipping it.
         // codex runtime.rs drops the thread from its manager the same way: only
         // after shutdown succeeded.
-        if (await sessionDeletionConfirmed(input.client, id)) {
+        if (await hostSessionDeletionConfirmed(input.client, id, SUBSESSION_CONFIRM_TIMEOUT_MS)) {
             activeSubSessions.delete(id);
         }
         return true;
@@ -409,30 +408,10 @@ async function deleteSession(id) {
         clearTimeout(timer);
     }
 }
-async function sessionDeletionConfirmed(client, id) {
-    const session = client.session;
-    if (typeof session?.get !== "function")
-        return false;
-    const controller = new AbortController();
-    let timer;
-    try {
-        const res = await Promise.race([
-            session.get({ path: { id }, signal: controller.signal }),
-            new Promise((_, reject) => {
-                timer = setTimeout(() => {
-                    controller.abort();
-                    reject(new Error(`session.get timed out after ${SUBSESSION_CONFIRM_TIMEOUT_MS}ms`));
-                }, SUBSESSION_CONFIRM_TIMEOUT_MS);
-            }),
-        ]);
-        return res?.response?.status === 404;
-    }
-    catch {
-        return false;
-    }
-    finally {
-        clearTimeout(timer);
-    }
+/** Best-effort abort of every memory sub-session (plugin dispose / reload). */
+export async function abortActiveSubSessions() {
+    const ids = [...activeSubSessions];
+    await Promise.all(ids.map((id) => abortSession(id)));
 }
 // Substitute with a function so `$&`/`$'` sequences in the value are not
 // expanded as String.replace replacement patterns.

package/dist/src/phase1.js

@@ -3,7 +3,9 @@ import { loadTranscript, selectEligibleSessions } from "./capture.js";
 import { redact, isMemoryExcludedFragment } from "./redact.js";
 import { stripCitations } from "./citation.js";
 import { extractViaSubagent } from "./llm.js";
-import { checkRateLimit } from "./ratelimit.js";
+import { checkRateLimit, markRateLimitUsed } from "./ratelimit.js";
+import { isPluginShuttingDown } from "./lifecycle.js";
+import { recordDiagnostic } from "./diagnostics.js";
 export const DEFAULT_PHASE1_OPTIONS = {
     maxAgeDays: 10,
     minIdleHours: 6,
@@ -20,6 +22,9 @@ const TRANSCRIPT_MAX_CHARS = 600_000;
 const TRANSCRIPT_HEAD_CHARS = 300_000;
 const TRANSCRIPT_TAIL_CHARS = 300_000;
 export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitCheck = checkRateLimit) {
+    if (isPluginShuttingDown())
+        return;
+    // Prune first (no tokens), matching codex start.rs ordering before the gate.
     store.pruneStage1Outputs(opts.maxUnusedDays ?? 30);
     const rl = await rateLimitCheck("phase1");
     if (!rl.ok) {
@@ -30,15 +35,31 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
     if (eligible.length === 0)
         return;
     const claimed = store.claimStage1Jobs(eligible, opts.excludeSession, opts.maxClaimed);
-    if (claimed.length === 0)
+    // Empty claim: do not stamp the process timer (codex only metrics
+    // skipped_no_candidates and leaves the next startup free to try again).
+    if (claimed.length === 0) {
+        recordDiagnostic("info", "phase1", `no claims (eligible=${eligible.length})`);
         return;
+    }
+    markRateLimitUsed("phase1");
+    recordDiagnostic("info", "phase1", `claimed ${claimed.length} session(s)`);
     const sessionById = new Map(eligible.map((s) => [s.id, s]));
     await runPool(claimed, STAGE1_CONCURRENCY, async (claim) => {
         const sid = claim.sessionId;
+        // dispose mid-pass: release the claim without burning a retry or waiting
+        // for the 1h lease — otherwise jobs stay `running` until lease expiry.
+        if (isPluginShuttingDown()) {
+            store.releaseStage1OnShutdown(sid, claim.ownershipToken);
+            return;
+        }
         try {
             const session = sessionById.get(sid);
             const sourceUpdatedAt = session?.updated_at ?? Date.now();
             const transcript = await buildTranscript(sid);
+            if (isPluginShuttingDown()) {
+                store.releaseStage1OnShutdown(sid, claim.ownershipToken);
+                return;
+            }
             if (!transcript.trim()) {
                 // A newly empty chat is a legitimate no-output result. An existing
                 // extraction plus an empty API success is anomalous: retry instead of
@@ -53,6 +74,10 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
                 cwd: session?.directory ?? undefined,
                 model: opts.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 +
+            // status guarded: if shutdown already released the job and a new process
+            // reclaimed it, this becomes a no-op (paid work dropped, never double-written).
             if (!result) {
                 // Extractor judged the session not worth remembering.
                 store.markStage1SucceededNoOutput(sid, claim.ownershipToken, sourceUpdatedAt);
@@ -70,7 +95,14 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitC
             });
         }
         catch (err) {
-            store.markStage1Failed(sid, claim.ownershipToken, err);
+            // Aborted mid-extract on dispose: release for immediate reclaim, do not
+            // burn a retry or impose the 1h failure backoff.
+            if (isPluginShuttingDown()) {
+                store.releaseStage1OnShutdown(sid, claim.ownershipToken);
+            }
+            else {
+                store.markStage1Failed(sid, claim.ownershipToken, err);
+            }
         }
     });
 }

package/dist/src/phase2.d.ts

@@ -1,5 +1,4 @@
 import { MemoryStore } from "./store.js";
-import { checkRateLimit } from "./ratelimit.js";
 import { type CodexInteropOptions } from "./codex-interop.js";
 export interface Phase2Options {
     maxRaw: number;
@@ -13,6 +12,6 @@ export interface Phase2Options {
 export declare const DEFAULT_PHASE2_OPTIONS: Phase2Options;
 /** True while THIS process runs a consolidation (memory_reset refuses then). */
 export declare function isPhase2InFlight(): boolean;
-export declare function runPhase2(store: MemoryStore, opts?: Phase2Options, rateLimitCheck?: typeof checkRateLimit): Promise<{
+export declare function runPhase2(store: MemoryStore, opts?: Phase2Options): Promise<{
     status: string;
 }>;

package/dist/src/phase2.js

@@ -1,9 +1,9 @@
 import { ensureLayout, rebuildRawMemories, writeRolloutSummaries, pruneExtensionResources, writeWorkspaceDiff, validateConsolidationArtifacts, } from "./workspace.js";
 import { ensureBaseline, captureWorkspaceDiff, resetBaseline, DIFF_ARTIFACT } from "./git-baseline.js";
-import { consolidateViaSubagent, SubagentShutdownError } from "./llm.js";
+import { consolidateViaSubagent, SubagentCancelledError, SubagentShutdownError } from "./llm.js";
 import { invalidateCache } from "./source.js";
 import { memoryRoot } from "./paths.js";
-import { checkRateLimit } from "./ratelimit.js";
+import { abortPhase2Consolidation, beginPhase2AbortScope, endPhase2AbortScope, isPluginShuttingDown, } from "./lifecycle.js";
 import { resolveCodexInterop, syncCodexImport, exportToCodexMemory } from "./codex-interop.js";
 export const DEFAULT_PHASE2_OPTIONS = {
     maxRaw: 256,
@@ -27,18 +27,33 @@ let phase2InFlight = false;
 export function isPhase2InFlight() {
     return phase2InFlight;
 }
-export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitCheck = checkRateLimit) {
+/** Release the claim when dispose raced the prep path; return true if released. */
+function releaseIfShuttingDown(store, ownershipToken) {
+    if (!isPluginShuttingDown())
+        return false;
+    store.releasePhase2OnShutdown(ownershipToken);
+    return true;
+}
+export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
+    if (isPluginShuttingDown())
+        return { status: "shutting_down" };
     if (phase2InFlight)
         return { status: "already_running" };
     phase2InFlight = true;
     try {
-        const rl = await rateLimitCheck("phase2");
-        if (!rl.ok)
-            return { status: "skipped_rate_limit" };
+        // 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.
         const claim = store.claimGlobalPhase2Job();
         if (claim.type !== "claimed")
             return { status: claim.type };
+        // Abort scope covers prep + consolidator so dispose during baseline/diff
+        // sets the flag that releaseIfShuttingDown / consolidator cancel observe.
+        const consolidationSignal = beginPhase2AbortScope();
         try {
+            if (releaseIfShuttingDown(store, claim.ownershipToken)) {
+                return { status: "shutting_down" };
+            }
             // Resolved once per claimed job (not per attempt): resolution warns on
             // misconfiguration, and warning on every skipped attempt would be noise.
             // Keep this inside the claimed-job try so resolution failures release
@@ -54,6 +69,9 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                 store.markPhase2Failed(claim.ownershipToken, "git baseline failed");
                 return { status: "baseline_failed" };
             }
+            if (releaseIfShuttingDown(store, claim.ownershipToken)) {
+                return { status: "shutting_down" };
+            }
             const outputs = store.getPhase2InputSelection(opts.maxRaw, opts.maxUnusedDays);
             rebuildRawMemories(outputs);
             writeRolloutSummaries(outputs);
@@ -75,6 +93,9 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                 }
             }
             const diff = await captureWorkspaceDiff();
+            if (releaseIfShuttingDown(store, claim.ownershipToken)) {
+                return { status: "shutting_down" };
+            }
             // codex: early succeed only when there are no changes AND artifacts are
             // already valid. Invalid/empty summary (e.g. ensureLayout's empty file)
             // falls through so the consolidator can INIT/repair.
@@ -90,14 +111,13 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
             writeWorkspaceDiff(diff);
             let heartbeatLost = false;
             let heartbeatFailure = "ownership lost";
-            const consolidationAbort = new AbortController();
             const heartbeatOnce = () => {
                 if (heartbeatLost)
                     return false;
                 try {
                     if (!store.heartbeatPhase2Job(claim.ownershipToken)) {
                         heartbeatLost = true;
-                        consolidationAbort.abort();
+                        abortPhase2Consolidation();
                         return false;
                     }
                 }
@@ -108,7 +128,7 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                     // the job while this helper still has live write access.
                     heartbeatLost = true;
                     heartbeatFailure = err;
-                    consolidationAbort.abort();
+                    abortPhase2Consolidation();
                     return false;
                 }
                 return true;
@@ -120,9 +140,12 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                 store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
                 return { status: "heartbeat_lost" };
             }
+            if (releaseIfShuttingDown(store, claim.ownershipToken)) {
+                return { status: "shutting_down" };
+            }
             const heartbeat = setInterval(heartbeatOnce, opts.heartbeatIntervalMs ?? 90_000);
             try {
-                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel, consolidationAbort.signal);
+                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel, consolidationSignal);
             }
             catch (err) {
                 // codex phase2.rs: when the consolidation agent's shutdown fails, keep
@@ -137,6 +160,12 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                     store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
                     return { status: "heartbeat_lost" };
                 }
+                // dispose() / beginPluginShutdown aborted the consolidator: release
+                // without the 1h failure backoff so the next boot can reclaim.
+                if (err instanceof SubagentCancelledError || isPluginShuttingDown()) {
+                    store.releasePhase2OnShutdown(claim.ownershipToken);
+                    return { status: "shutting_down" };
+                }
                 throw err;
             }
             finally {
@@ -152,6 +181,9 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                 store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
                 return { status: "heartbeat_lost" };
             }
+            if (releaseIfShuttingDown(store, claim.ownershipToken)) {
+                return { status: "shutting_down" };
+            }
             // codex failed_invalid_artifacts: do not reset baseline on bad output so
             // the next run still sees a diff / can re-INIT.
             const artifacts = validateConsolidationArtifacts();
@@ -169,9 +201,16 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
             return { status: "succeeded" };
         }
         catch (err) {
+            if (isPluginShuttingDown()) {
+                store.releasePhase2OnShutdown(claim.ownershipToken);
+                return { status: "shutting_down" };
+            }
             store.markPhase2Failed(claim.ownershipToken, err);
             return { status: "failed" };
         }
+        finally {
+            endPhase2AbortScope();
+        }
     }
     finally {
         phase2InFlight = false;

package/dist/src/ratelimit.d.ts

@@ -3,3 +3,7 @@ export interface RateLimitInfo {
     reason?: string;
 }
 export declare function checkRateLimit(kind?: "phase1" | "phase2"): 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. */
+export declare function resetRateLimitForTest(): void;

package/dist/src/ratelimit.js

@@ -1,20 +1,37 @@
-let lastPhase1 = 0;
-let lastPhase2 = 0;
+/**
+ * Process-local anti-stampede for phase 1 only.
+ *
+ * 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.
+ *
+ * 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)
+ * - 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)
+ */
+let lastPhase1Work = 0;
 const MIN_PHASE1_INTERVAL_MS = 30_000;
-const MIN_PHASE2_INTERVAL_MS = 5 * 60 * 1000;
 export async function checkRateLimit(kind = "phase1") {
+    // Phase 2: no process-local gate (codex relies on DB claim/cooldown only).
+    if (kind === "phase2")
+        return { ok: true };
     const now = Date.now();
-    if (kind === "phase1") {
-        if (now - lastPhase1 < MIN_PHASE1_INTERVAL_MS) {
-            return { ok: false, reason: "phase1 rate limit (30s)" };
-        }
-        lastPhase1 = now;
-    }
-    else {
-        if (now - lastPhase2 < MIN_PHASE2_INTERVAL_MS) {
-            return { ok: false, reason: "phase2 rate limit (5min)" };
-        }
-        lastPhase2 = now;
+    if (now - lastPhase1Work < MIN_PHASE1_INTERVAL_MS) {
+        return { ok: false, reason: "phase1 rate limit (30s since last claimed work)" };
     }
     return { ok: true };
 }
+/** Call after a phase-1 pass claimed at least one job (token-using work started). */
+export function markRateLimitUsed(kind = "phase1") {
+    if (kind === "phase1")
+        lastPhase1Work = Date.now();
+}
+/** Test seam: reset the process-local stamp. */
+export function resetRateLimitForTest() {
+    lastPhase1Work = 0;
+}

package/dist/src/store.d.ts

@@ -57,6 +57,12 @@ 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;
+    /**
+     * 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
+     * reclaim immediately (unlike markStage1Failed). Ownership-token guarded.
+     */
+    releaseStage1OnShutdown(sessionId: string, ownershipToken: string): void;
     /**
      * Enqueues global consolidation after stage-1 state changes. If phase 2 is
      * already running, preserve its lease and advance only the input watermark.
@@ -91,6 +97,11 @@ export declare class MemoryStore {
         last_success_watermark: number | null;
     } | null;
     markPhase2Failed(ownershipToken: string, error: unknown): void;
+    /**
+     * Plugin dispose/reload: release the global phase-2 job without retry backoff
+     * so the next process can reclaim immediately. Ownership-token guarded.
+     */
+    releasePhase2OnShutdown(ownershipToken: string): void;
     /**
      * Phase 2 input set, mirroring codex get_phase2_input_selection:
      * - excludes sessions marked disabled/polluted (their summary files then
@@ -109,6 +120,13 @@ export declare class MemoryStore {
      * codex clear_memory_data deletes extracted memories and jobs but explicitly
      * preserves per-session memory modes: a reset must not re-enable sessions
      * the user disabled or that were marked polluted.
+     *
+     * After the wipe, leave a phase-2 cooldown marker (status=done, finished_at
+     * now, last_error NULL). Without it, the next idle/chat hook first-run-claims
+     * phase 2 on an empty DB and ensureLayout re-seeds the just-wiped root —
+     * memory_reset then looks like a no-op to the caller. Codex avoids this
+     * because reset is a client RPC outside the write-pipeline pump; the plugin
+     * surface is model-invoked mid-session, so hooks can race the wipe.
      */
     clearMemoryData(): void;
     setMemoryMode(sessionId: string, mode: "enabled" | "disabled" | "polluted"): void;
@@ -122,4 +140,17 @@ export declare class MemoryStore {
     getMemoryMode(sessionId: string): "enabled" | "disabled" | "polluted" | null;
     markPolluted(sessionId: string): void;
     isPolluted(sessionId: string): boolean;
+    /**
+     * Stage-1 job counts + recent failures for memory_inspect. Helps diagnose
+     * "nothing is learning" without reading the raw jobs table.
+     */
+    stage1JobSnapshot(): {
+        by_status: Record<string, number>;
+        recent_errors: {
+            session_id: string;
+            last_error: string;
+            retry_at: number | null;
+            status: string;
+        }[];
+    };
 }

package/dist/src/store.js

@@ -202,6 +202,22 @@ export class MemoryStore {
          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);
     }
+    /**
+     * 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
+     * reclaim immediately (unlike markStage1Failed). Ownership-token guarded.
+     */
+    releaseStage1OnShutdown(sessionId, ownershipToken) {
+        this.db
+            .prepare(`UPDATE memory_jobs SET
+           status = 'pending',
+           last_error = ?,
+           retry_at = NULL,
+           finished_at = ?,
+           lease_until = NULL
+         WHERE kind='memory_stage1' AND job_key=? AND status='running' AND ownership_token=?`)
+            .run("plugin shutting down", nowSec(), sessionId, ownershipToken);
+    }
     /**
      * Enqueues global consolidation after stage-1 state changes. If phase 2 is
      * already running, preserve its lease and advance only the input watermark.
@@ -385,6 +401,21 @@ export class MemoryStore {
          WHERE kind='memory_consolidate_global' AND job_key='global' AND status='running' AND ownership_token IS NULL`)
             .run(message.slice(0, 4000), nowSec() + PHASE2_RETRY_DELAY_SECONDS, nowSec());
     }
+    /**
+     * Plugin dispose/reload: release the global phase-2 job without retry backoff
+     * so the next process can reclaim immediately. Ownership-token guarded.
+     */
+    releasePhase2OnShutdown(ownershipToken) {
+        this.db
+            .prepare(`UPDATE memory_jobs SET
+           status = 'pending',
+           last_error = ?,
+           retry_at = NULL,
+           finished_at = ?,
+           lease_until = NULL
+         WHERE kind='memory_consolidate_global' AND job_key='global' AND ownership_token=? AND status='running'`)
+            .run("plugin shutting down", nowSec(), ownershipToken);
+    }
     /**
      * Phase 2 input set, mirroring codex get_phase2_input_selection:
      * - excludes sessions marked disabled/polluted (their summary files then
@@ -430,11 +461,23 @@ export class MemoryStore {
      * codex clear_memory_data deletes extracted memories and jobs but explicitly
      * preserves per-session memory modes: a reset must not re-enable sessions
      * the user disabled or that were marked polluted.
+     *
+     * After the wipe, leave a phase-2 cooldown marker (status=done, finished_at
+     * now, last_error NULL). Without it, the next idle/chat hook first-run-claims
+     * phase 2 on an empty DB and ensureLayout re-seeds the just-wiped root —
+     * memory_reset then looks like a no-op to the caller. Codex avoids this
+     * because reset is a client RPC outside the write-pipeline pump; the plugin
+     * surface is model-invoked mid-session, so hooks can race the wipe.
      */
     clearMemoryData() {
         this.db.transaction(() => {
             this.db.run("DELETE FROM memory_stage1_outputs");
             this.db.run("DELETE FROM memory_jobs");
+            this.db
+                .prepare(`INSERT INTO memory_jobs
+            (kind, job_key, status, finished_at, last_error, retry_remaining, last_success_watermark)
+           VALUES ('memory_consolidate_global', 'global', 'done', ?, NULL, ?, 0)`)
+                .run(nowSec(), DEFAULT_RETRY_REMAINING);
         }).immediate();
     }
     setMemoryMode(sessionId, mode) {
@@ -475,4 +518,23 @@ export class MemoryStore {
             .get(sessionId);
         return row?.p === 1;
     }
+    /**
+     * Stage-1 job counts + recent failures for memory_inspect. Helps diagnose
+     * "nothing is learning" without reading the raw jobs table.
+     */
+    stage1JobSnapshot() {
+        const rows = this.db
+            .prepare("SELECT status, COUNT(*) AS c FROM memory_jobs WHERE kind='memory_stage1' GROUP BY status")
+            .all();
+        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
+         WHERE kind='memory_stage1' AND last_error IS NOT NULL
+         ORDER BY COALESCE(finished_at, started_at, 0) DESC
+         LIMIT 5`)
+            .all();
+        return { by_status, recent_errors };
+    }
 }