opencode-codex-memory 0.1.8 → 0.2.0

package/dist/src/index.js

@@ -1,4 +1,5 @@
 import { ensureMemoryLayout, buildMemorySystemPrompt, invalidateCache } from "./source.js";
+import { memoryRoot } from "./paths.js";
 import { stripCitations, extractCitedSessionIds } from "./citation.js";
 import { memory_read, memory_search, memory_list, memory_add_note } from "../tools/memory.js";
 import { memory_reset, memory_inspect, memory_mode } from "../tools/control.js";
@@ -31,9 +32,10 @@ let pluginOptions = {
 function getStore() {
     return new MemoryStore();
 }
-// Citation blocks arrive via message.part.updated once per streaming delta,
-// so the same completed block is seen many times. Track which session ids
-// were already recorded per part to count each citation once.
+// Citation blocks are seen by both the text.complete hook (once, at
+// completion) and message.part.updated (once per streaming delta), so the
+// same block surfaces many times. Track which session ids were already
+// recorded per part to count each citation exactly once across both paths.
 const recordedCitations = new Map();
 const MAX_TRACKED_PARTS = 500;
 export function takeNewCitations(partKey, ids) {
@@ -52,7 +54,47 @@ export function takeNewCitations(partKey, ids) {
         seen.add(id);
     return fresh;
 }
-export function handleSessionDeleted(sessionId, store = getStore(), schedulePhase2 = () => { void triggerPhase2(); }) {
+// One stamp+pump per session per process from the chat.message hook; later
+// messages in the same session add nothing (stamp is idempotent, the pump
+// re-fires on idle anyway).
+const seenTurnSessions = new Set();
+const MAX_TRACKED_TURN_SESSIONS = 1000;
+export function markTurnSeen(sessionId) {
+    if (seenTurnSessions.has(sessionId))
+        return false;
+    seenTurnSessions.add(sessionId);
+    if (seenTurnSessions.size > MAX_TRACKED_TURN_SESSIONS) {
+        const oldest = seenTurnSessions.keys().next().value;
+        if (oldest !== undefined)
+            seenTurnSessions.delete(oldest);
+    }
+    return true;
+}
+// opencode 1.17 publishes BOTH session.status {type:"idle"} and the
+// deprecated session.idle for the same transition, back to back. Handle
+// whichever arrives first and swallow the twin within a short window.
+const recentIdle = new Map();
+const IDLE_DEDUP_MS = 5000;
+const MAX_TRACKED_IDLE = 500;
+export function shouldHandleIdle(sessionId, now = Date.now()) {
+    const last = recentIdle.get(sessionId);
+    if (last !== undefined && now - last < IDLE_DEDUP_MS)
+        return false;
+    recentIdle.set(sessionId, now);
+    if (recentIdle.size > MAX_TRACKED_IDLE) {
+        const oldest = recentIdle.keys().next().value;
+        if (oldest !== undefined)
+            recentIdle.delete(oldest);
+    }
+    return true;
+}
+export function handleSessionDeleted(sessionId, store = getStore(), 
+// With generation off the memorize agent is not injected, so a consolidation
+// attempt could only fail; the row deletion above still happens, and the
+// enqueued job runs when generation is re-enabled (codex: delete only
+// enqueues; the pipeline itself is gated elsewhere).
+schedulePhase2 = () => { if (pluginOptions.generate_memories)
+    void triggerPhase2(); }) {
     if (store.deleteSessionMemory(sessionId))
         schedulePhase2();
 }
@@ -166,6 +208,18 @@ export function injectAgentDefinitions(config) {
         console.warn("[opencode-codex-memory] could not load bundled agent definitions:", err);
         return;
     }
+    // opencode gates file tools outside the session's project behind the
+    // `external_directory` permission, and the memory workspace is global —
+    // outside every project — so the consolidator's reads/writes there always
+    // trigger that ask. The bundled `"*": "deny"` matches it (permission rules
+    // are wildcard-on-name, last match wins), which would block consolidation
+    // entirely. Grant the memory root here rather than in opencode.json: the
+    // path is homedir/env-dependent (src/paths.ts is its single source of
+    // truth). Appended last so it out-ranks the wildcard deny.
+    const memorize = defs["memorize"];
+    if (memorize?.permission && !("external_directory" in memorize.permission)) {
+        memorize.permission["external_directory"] = { [path.join(memoryRoot(), "*")]: "allow" };
+    }
     config.agent ??= {};
     for (const [name, def] of Object.entries(defs)) {
         if (!config.agent[name])
@@ -193,7 +247,7 @@ function buildHooks() {
                 if (input.sessionID && isMemorySubSession(input.sessionID))
                     return;
                 ensureMemoryLayout();
-                const memoryPrompt = buildMemorySystemPrompt();
+                const memoryPrompt = buildMemorySystemPrompt(pluginOptions.dedicated_tools);
                 if (memoryPrompt) {
                     output.system.push(memoryPrompt);
                 }
@@ -202,6 +256,41 @@ function buildHooks() {
                 console.error("[opencode-codex-memory] system.transform error:", err);
             }
         },
+        /**
+         * Fires at text-end, before opencode persists the final part text
+         * (session/processor.ts): the returned text replaces the stored one.
+         * Primary citation seam — records usage and strips the block so neither
+         * the UI nor history ever shows citation markup (matches codex, which
+         * strips from the displayed/persisted message). The event and
+         * messages.transform paths below stay as fallbacks for older opencode
+         * hosts and for history persisted before this hook existed.
+         */
+        async "experimental.text.complete"(input, output) {
+            try {
+                if (isMemorySubSession(input.sessionID))
+                    return;
+                if (!output.text.includes("<memory-citation>"))
+                    return;
+                try {
+                    const ids = extractCitedSessionIds(output.text);
+                    // Same part key as the event path: whichever hook sees the ids first
+                    // records them; the other becomes a no-op.
+                    const fresh = takeNewCitations(`${input.sessionID}:${input.partID}`, ids);
+                    if (fresh.length > 0)
+                        getStore().recordUsage(fresh);
+                }
+                catch (e) {
+                    console.error("[opencode-codex-memory] citation recording failed:", e);
+                }
+                output.text = stripCitations(output.text);
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] text.complete error:", err);
+            }
+        },
+        // Fallback strip for history that still carries citation blocks (messages
+        // persisted by plugin versions before the text.complete seam, or hosts
+        // without it). Keeps citation markup out of the model-facing transcript.
         async "experimental.chat.messages.transform"(_input, output) {
             try {
                 for (const msg of output.messages) {
@@ -222,6 +311,51 @@ function buildHooks() {
                 console.error("[opencode-codex-memory] messages.transform error:", err);
             }
         },
+        /**
+         * Turn start. codex stamps memory_mode at thread creation (session.rs) and
+         * schedules memory work per startup/turn; the first user message is the
+         * closest plugin-visible moment. Stamping here (instead of waiting for the
+         * first idle) means a session created while generate_memories=false keeps
+         * its 'disabled' stamp even if the option flips mid-session, and the
+         * phase-1 pump no longer depends on idle events at all. The idle path
+         * below stays as a second pump trigger; both are cheap (stamp is INSERT OR
+         * IGNORE, the pump is gated by in-flight/rate/claim guards).
+         */
+        async "chat.message"(input) {
+            try {
+                const sid = input?.sessionID;
+                if (!sid || isMemorySubSession(sid))
+                    return;
+                if (!markTurnSeen(sid))
+                    return;
+                try {
+                    getStore().stampMemoryModeIfAbsent(sid, pluginOptions.generate_memories ? "enabled" : "disabled");
+                }
+                catch (e) {
+                    console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
+                }
+                void triggerPhase1(sid);
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] chat.message error:", err);
+            }
+        },
+        // Dedicated plugin hook (NOT an event-bus type): fires after every tool
+        // call. Mirrors codex: external context (web search or any MCP tool) only
+        // pollutes the session's memory when disable_on_external_context is
+        // enabled. Off by default.
+        async "tool.execute.after"(input) {
+            try {
+                if (!pluginOptions.disable_on_external_context)
+                    return;
+                if (input.sessionID && (await isExternalContextTool(input.tool))) {
+                    getStore().markPolluted(input.sessionID);
+                }
+            }
+            catch (err) {
+                console.error("[opencode-codex-memory] tool.execute.after error:", err);
+            }
+        },
         async event(input) {
             try {
                 const ev = input.event;
@@ -251,24 +385,6 @@ function buildHooks() {
                     }
                     return;
                 }
-                if (ev.type === "tool.execute.after") {
-                    // Mirrors codex: external context (web search or any MCP tool) only
-                    // pollutes the session's memory when disable_on_external_context is
-                    // enabled. Off by default.
-                    if (!pluginOptions.disable_on_external_context)
-                        return;
-                    const props = ev.properties;
-                    const toolName = props?.tool ?? "";
-                    if (props.sessionID && (await isExternalContextTool(toolName))) {
-                        try {
-                            getStore().markPolluted(props.sessionID);
-                        }
-                        catch (e) {
-                            console.error("[opencode-codex-memory] markPolluted failed:", e);
-                        }
-                    }
-                    return;
-                }
                 if (ev.type === "session.deleted") {
                     // Mirrors codex delete_thread_memory: drop the extracted memory and
                     // its job when the session is deleted. If phase 2 had consumed it,
@@ -285,21 +401,19 @@ function buildHooks() {
                     }
                     return;
                 }
+                // session.idle is deprecated in opencode 1.17 in favor of
+                // session.status {type:"idle"}; both are still emitted. Support both so
+                // the pipeline keeps triggering when the legacy event disappears.
+                if (ev.type === "session.status") {
+                    const props = ev.properties;
+                    if (props?.status?.type === "idle" && props.sessionID)
+                        handleSessionIdle(props.sessionID);
+                    return;
+                }
                 if (ev.type === "session.idle") {
                     const props = ev.properties;
-                    const sid = props?.sessionID;
-                    if (!sid || isMemorySubSession(sid))
-                        return;
-                    // codex stamps memory_mode at thread creation from generate_memories:
-                    // sessions seen while generation is off stay excluded permanently,
-                    // even if the option is re-enabled later.
-                    try {
-                        getStore().stampMemoryModeIfAbsent(sid, pluginOptions.generate_memories ? "enabled" : "disabled");
-                    }
-                    catch (e) {
-                        console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
-                    }
-                    void triggerPhase1(sid);
+                    if (props?.sessionID)
+                        handleSessionIdle(props.sessionID);
                     return;
                 }
             }
@@ -311,6 +425,22 @@ function buildHooks() {
             invalidateCache();
         },
     };
+    function handleSessionIdle(sid) {
+        if (isMemorySubSession(sid))
+            return;
+        if (!shouldHandleIdle(sid))
+            return;
+        // codex stamps memory_mode at thread creation from generate_memories:
+        // sessions first seen while generation is off keep that stamp when the
+        // option is re-enabled (manual override: the memory_mode tool).
+        try {
+            getStore().stampMemoryModeIfAbsent(sid, pluginOptions.generate_memories ? "enabled" : "disabled");
+        }
+        catch (e) {
+            console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
+        }
+        void triggerPhase1(sid);
+    }
     // Control tools (reset/inspect/mode) are always available. The memory
     // read/search/list/add-note tools require BOTH use_memories and
     // dedicated_tools, mirroring codex's MemoriesExtension: use_memories=false
@@ -341,6 +471,7 @@ async function triggerPhase1(currentSessionId) {
             maxAgeDays: pluginOptions.max_rollout_age_days,
             minIdleHours: pluginOptions.min_rollout_idle_hours,
             maxClaimed: pluginOptions.max_rollouts_per_startup,
+            maxUnusedDays: pluginOptions.max_unused_days,
             excludeSession: currentSessionId,
             extractModel: pluginOptions.extract_model,
         });

package/dist/src/llm.d.ts

@@ -5,6 +5,7 @@ export interface ExtractionResult {
     rollout_slug: string | null;
 }
 export declare function setPluginInput(input: PluginInput): void;
+export declare function getPluginInput(): PluginInput | null;
 export declare function isMemorySubSession(sessionId: string): boolean;
 export interface ExtractOptions {
     cwd?: string;

package/dist/src/llm.js

@@ -4,7 +4,7 @@ let inputRef = null;
 export function setPluginInput(input) {
     inputRef = input;
 }
-function getPluginInput() {
+export function getPluginInput() {
     return inputRef;
 }
 // Sessions this plugin spawned for extraction/consolidation. The main
@@ -125,7 +125,10 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
         // extract_model option > opencode small_model > session default.
         const model = opts.model ?? (await getConfigModels()).smallModel;
         const raw = await promptSession(subId, prompt, agent, {
-            timeoutMs: 180_000,
+            // 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
+            // short one — repeated timeouts would exhaust the job's retries.
+            timeoutMs: 3600_000,
             system: readTemplate("stage_one_system.md"),
             model,
         });

package/dist/src/path-guard.d.ts

@@ -7,4 +7,13 @@
  * - every existing component is lstat-checked: symlinks are rejected, so a
  *   link placed inside the workspace cannot lead reads outside it
  */
+/**
+ * The memory root itself must not be a symlink: every scoped resolution and
+ * every workspace walk starts there, so a symlinked root would redirect ALL
+ * memory reads/writes elsewhere on disk. codex rejects a symlinked root when
+ * clearing (control.rs clear_memory_root_contents); the model-facing tools
+ * here extend that check to every memory operation. Returns the root path.
+ * A missing root is fine — callers create it as a real directory.
+ */
+export declare function assertMemoryRootSafe(): string;
 export declare function safeResolveMemoryPath(rel: string): string;

package/dist/src/path-guard.js

@@ -10,8 +10,30 @@ import { memoryRoot } from "./paths.js";
  * - every existing component is lstat-checked: symlinks are rejected, so a
  *   link placed inside the workspace cannot lead reads outside it
  */
-export function safeResolveMemoryPath(rel) {
+/**
+ * The memory root itself must not be a symlink: every scoped resolution and
+ * every workspace walk starts there, so a symlinked root would redirect ALL
+ * memory reads/writes elsewhere on disk. codex rejects a symlinked root when
+ * clearing (control.rs clear_memory_root_contents); the model-facing tools
+ * here extend that check to every memory operation. Returns the root path.
+ * A missing root is fine — callers create it as a real directory.
+ */
+export function assertMemoryRootSafe() {
     const root = memoryRoot();
+    let st = null;
+    try {
+        st = fs.lstatSync(root);
+    }
+    catch {
+        return root;
+    }
+    if (st.isSymbolicLink()) {
+        throw new Error(`memory root is a symlink; refusing memory operations: ${root}`);
+    }
+    return root;
+}
+export function safeResolveMemoryPath(rel) {
+    const root = assertMemoryRootSafe();
     if (path.isAbsolute(rel)) {
         throw new Error(`path escapes memory root: ${rel}`);
     }

package/dist/src/paths.d.ts

@@ -1,4 +1,3 @@
 export declare function memoryRoot(): string;
 export declare function memoryDbPath(): string;
-export declare function opencodeDbPath(): string;
 export declare function memorySummaryPath(): string;

package/dist/src/paths.js

@@ -15,9 +15,6 @@ export function memoryRoot() {
 export function memoryDbPath() {
     return path.join(dataRoot(), MEMORY_DB_NAME);
 }
-export function opencodeDbPath() {
-    return path.join(dataRoot(), "opencode.db");
-}
 export function memorySummaryPath() {
     return path.join(memoryRoot(), "memory_summary.md");
 }

package/dist/src/phase1.d.ts

@@ -9,3 +9,4 @@ export interface Phase1Options {
 }
 export declare const DEFAULT_PHASE1_OPTIONS: Phase1Options;
 export declare function runPhase1(store: MemoryStore, opts?: Phase1Options): Promise<void>;
+export declare function buildTranscript(sessionId: string): Promise<string>;

package/dist/src/phase1.js

@@ -15,9 +15,10 @@ export const DEFAULT_PHASE1_OPTIONS = {
 // char-estimate equivalent at 600k.
 const TRANSCRIPT_MAX_CHARS = 600_000;
 // When truncating, keep the head and the tail: the start carries the user's
-// framing, the end carries the final outcome and feedback.
-const TRANSCRIPT_HEAD_CHARS = 360_000;
-const TRANSCRIPT_TAIL_CHARS = 240_000;
+// framing, the end carries the final outcome and feedback. codex splits the
+// budget 50/50 between head and tail (truncate.rs split_budget).
+const TRANSCRIPT_HEAD_CHARS = 300_000;
+const TRANSCRIPT_TAIL_CHARS = 300_000;
 export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
     store.pruneStage1Outputs(opts.maxUnusedDays ?? 30);
     const rl = await checkRateLimit("phase1");
@@ -25,7 +26,7 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
         console.warn("[opencode-codex-memory] skipping phase1 due to rate limit:", rl.reason);
         return;
     }
-    const eligible = selectEligibleSessions(store, opts);
+    const eligible = await selectEligibleSessions(store, opts);
     if (eligible.length === 0)
         return;
     const claimed = store.claimStage1Jobs(eligible, opts.excludeSession, opts.maxClaimed);
@@ -37,7 +38,7 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
         try {
             const session = sessionById.get(sid);
             const sourceUpdatedAt = session?.updated_at ?? Date.now();
-            const transcript = buildTranscript(sid);
+            const transcript = await buildTranscript(sid);
             if (!transcript.trim()) {
                 store.markStage1SucceededNoOutput(sid, claim.ownershipToken, sourceUpdatedAt);
                 return;
@@ -67,14 +68,19 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
         }
     });
 }
-function buildTranscript(sessionId) {
-    const msgs = loadTranscript(sessionId);
+export async function buildTranscript(sessionId) {
+    const msgs = await loadTranscript(sessionId);
     if (msgs.length === 0)
         return "";
     const lines = [];
     for (const m of msgs) {
         if (m.type === "system")
             continue;
+        // codex sanitize_response_item_for_memories drops developer-role messages
+        // entirely (injected instructions, not conversation). opencode 1.17 only
+        // stores user/assistant roles; this guards future role additions.
+        if (m.role === "developer")
+            continue;
         const role = m.role ?? m.type;
         const text = m.text ?? "";
         if (!text.trim())

package/dist/src/phase2.d.ts

@@ -6,6 +6,8 @@ export interface Phase2Options {
     consolidationModel?: string;
 }
 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): Promise<{
     status: string;
 }>;

package/dist/src/phase2.js

@@ -10,6 +10,10 @@ export const DEFAULT_PHASE2_OPTIONS = {
     extensionRetentionDays: 7,
 };
 let phase2InFlight = false;
+/** True while THIS process runs a consolidation (memory_reset refuses then). */
+export function isPhase2InFlight() {
+    return phase2InFlight;
+}
 export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
     if (phase2InFlight)
         return { status: "already_running" };
@@ -51,8 +55,16 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS) {
             writeWorkspaceDiff(diff);
             let heartbeatLost = false;
             const heartbeat = setInterval(() => {
-                if (!store.heartbeatPhase2Job(claim.ownershipToken)) {
-                    heartbeatLost = true;
+                try {
+                    if (!store.heartbeatPhase2Job(claim.ownershipToken)) {
+                        heartbeatLost = true;
+                    }
+                }
+                catch (err) {
+                    // Transient DB error (e.g. SQLITE_BUSY): don't treat as ownership
+                    // loss — the token+status-guarded final confirmation below stays
+                    // authoritative. Uncaught, this would kill the interval silently.
+                    console.warn("[opencode-codex-memory] phase2 heartbeat error:", err);
                 }
             }, 90_000);
             let agentCompleted = false;

package/dist/src/redact.js

@@ -10,8 +10,11 @@ const REDACTIONS = [
         re: /-----BEGIN [A-Z]+ PRIVATE KEY-----[\s\S]*?-----END [A-Z]+ PRIVATE KEY-----/g,
         replacement: "[REDACTED:private-key]",
     },
-    { re: /(password|passwd|pwd|secret|api[_-]?key|token|access[_-]?token)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
-    { re: /(?:aws_secret_access_key|aws_access_key_id)\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
+    // Optional quotes around the KEY cover JSON/YAML forms like
+    // "password": "value" — codex's SECRET_ASSIGNMENT_REGEX misses those (it
+    // allows a quote only before the value); this is a deliberate superset.
+    { re: /["']?(password|passwd|pwd|secret|api[_-]?key|token|access[_-]?token)["']?\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
+    { re: /["']?(aws_secret_access_key|aws_access_key_id)["']?\s*[:=]\s*["']?[^\s"']{4,}["']?/gi, replacement: "$1=[REDACTED]" },
 ];
 export function redact(text) {
     let out = text;

package/dist/src/source.d.ts

@@ -1,3 +1,3 @@
 export declare function invalidateCache(): void;
-export declare function buildMemorySystemPrompt(): string | null;
+export declare function buildMemorySystemPrompt(dedicatedTools: boolean): string | null;
 export declare function ensureMemoryLayout(): void;

package/dist/src/source.js

@@ -5,6 +5,25 @@ import { truncateToTokens } from "./token.js";
 import { fillTemplate } from "./llm.js";
 const MEMORY_SUMMARY_TOKEN_LIMIT = 2500;
 const READ_PATH_TEMPLATE = "read_path.md";
+// Tool-dependent guidance for read_path.md. With dedicated_tools on, the
+// prompt points at the memory_* tools (our platform adaptation — the memory
+// dir lives outside the workspace). With them off, it falls back to codex's
+// own wording: the agent reads/writes the memory files directly.
+const SEARCH_STEP_TOOLS = `2. Search {{ base_path }}/MEMORY.md for those keywords with the \`memory_search\`
+   tool, or read it with \`memory_read\`.
+   - For time-scoped recall ("what was I working on last week / around date X"),
+     pass \`since\`/\`until\` to \`memory_search\` — with a query it searches only that
+     period's sessions/notes; without a query it lists them chronologically.`;
+const SEARCH_STEP_FILES = `2. Search {{ base_path }}/MEMORY.md using those keywords.`;
+const UPDATE_INSTRUCTIONS_TOOLS = `Use the \`memory_add_note\` tool, which writes
+one small note file under \`extensions/ad_hoc/notes/\` describing what to
+add/delete/update. Do not edit the memory files yourself; the consolidation
+pass will integrate the note.`;
+const UPDATE_INSTRUCTIONS_FILES = `- Write your update in {{ base_path }}/extensions/ad_hoc/notes/
+- Each update must be one small file containing what you want to add/delete/update from the memories.
+- The name of this file must be \`<timestamp>-<short slug>.md\`
+- Do not edit the other memory files yourself; the consolidation pass will
+  integrate the note.`;
 let cached = null;
 function readTemplate() {
     const templatePath = path.join(import.meta.dirname, "templates", READ_PATH_TEMPLATE);
@@ -31,12 +50,15 @@ function readMemorySummary() {
 export function invalidateCache() {
     cached = null;
 }
-export function buildMemorySystemPrompt() {
+export function buildMemorySystemPrompt(dedicatedTools) {
     const summary = readMemorySummary();
     if (!summary)
         return null;
     const template = readTemplate();
     return fillTemplate(template, {
+        search_step: dedicatedTools ? SEARCH_STEP_TOOLS : SEARCH_STEP_FILES,
+        update_instructions: dedicatedTools ? UPDATE_INSTRUCTIONS_TOOLS : UPDATE_INSTRUCTIONS_FILES,
+        // Filled last so {{ base_path }} nested inside the snippets above resolves.
         base_path: memoryRoot(),
         memory_summary: summary,
     });

package/dist/src/store.d.ts

@@ -69,6 +69,11 @@ export declare class MemoryStore {
      * still back the consolidated artifacts.
      */
     markPhase2Succeeded(ownershipToken: string, selected?: Pick<Stage1Output, "session_id" | "source_updated_at">[]): void;
+    /** Last recorded phase-2 success info (memory_inspect). Null when phase 2 never succeeded. */
+    phase2LastSuccess(): {
+        finished_at: number | null;
+        last_success_watermark: number | null;
+    } | null;
     markPhase2Failed(ownershipToken: string, error: string): void;
     /**
      * Phase 2 input set, mirroring codex get_phase2_input_selection:

package/dist/src/store.js

@@ -78,10 +78,11 @@ export class MemoryStore {
     }
     claimStage1Jobs(sessions, excludeSession, maxClaimed) {
         const workerId = newId();
-        // Cap per-pass claims at codex's max_rollouts_per_startup (max_claimed) when
-        // provided, never exceeding the hard concurrency ceiling. codex also uses
-        // max_claimed as the cross-process running-jobs cap.
-        const claimCap = Math.max(1, Math.min(maxClaimed ?? STAGE1_CONCURRENCY, STAGE1_CONCURRENCY));
+        // Cap per-pass claims at codex's max_rollouts_per_startup (max_claimed,
+        // default 2, clamp 1-128). codex also uses max_claimed as the
+        // cross-process running-jobs cap; execution concurrency is limited
+        // separately (STAGE1_CONCURRENCY, codex buffer_unordered(8)).
+        const claimCap = Math.max(1, maxClaimed ?? 2);
         const claimed = [];
         const claimOne = this.db.transaction((s, ownershipToken, lease) => {
             const activeRow = this.db
@@ -268,22 +269,38 @@ export class MemoryStore {
         // codex stores the completion watermark = max source_updated_at consumed;
         // the 6h cooldown is keyed on finished_at, not on this value.
         const watermark = selected.reduce((max, s) => Math.max(max, s.source_updated_at), 0);
-        const res = this.db
-            .prepare(`UPDATE memory_jobs SET status='done', finished_at=?, lease_until=NULL, last_error=NULL, retry_remaining=?,
-           last_success_watermark=MAX(COALESCE(last_success_watermark, 0), ?), retry_at=NULL
-         WHERE kind='memory_consolidate_global' AND job_key='global' AND ownership_token=? AND status='running'`)
-            .run(nowSec(), DEFAULT_RETRY_REMAINING, watermark, ownershipToken);
-        if (res.changes === 0)
-            return;
-        this.db.exec("UPDATE memory_stage1_outputs SET selected_for_phase2 = 0, selected_for_phase2_source_updated_at = NULL");
-        const mark = this.db.prepare(`UPDATE memory_stage1_outputs
-       SET selected_for_phase2 = 1, selected_for_phase2_source_updated_at = ?
-       WHERE session_id = ? AND source_updated_at = ?`);
-        for (const s of selected)
-            mark.run(s.source_updated_at, s.session_id, s.source_updated_at);
+        // One transaction for the job row + the selected-input flags (codex
+        // mark_global_phase2_job_succeeded does the same): a crash between them
+        // must not leave a done job whose retention flags still describe the
+        // previous run — pruning could then delete inputs backing the artifacts.
+        this.db.transaction(() => {
+            const res = this.db
+                .prepare(`UPDATE memory_jobs SET status='done', finished_at=?, lease_until=NULL, last_error=NULL, retry_remaining=?,
+             last_success_watermark=MAX(COALESCE(last_success_watermark, 0), ?), retry_at=NULL
+           WHERE kind='memory_consolidate_global' AND job_key='global' AND ownership_token=? AND status='running'`)
+                .run(nowSec(), DEFAULT_RETRY_REMAINING, watermark, ownershipToken);
+            if (res.changes === 0)
+                return;
+            this.db.exec("UPDATE memory_stage1_outputs SET selected_for_phase2 = 0, selected_for_phase2_source_updated_at = NULL");
+            const mark = this.db.prepare(`UPDATE memory_stage1_outputs
+         SET selected_for_phase2 = 1, selected_for_phase2_source_updated_at = ?
+         WHERE session_id = ? AND source_updated_at = ?`);
+            for (const s of selected)
+                mark.run(s.source_updated_at, s.session_id, s.source_updated_at);
+        }).immediate();
+    }
+    /** Last recorded phase-2 success info (memory_inspect). Null when phase 2 never succeeded. */
+    phase2LastSuccess() {
+        const row = this.db
+            .prepare(`SELECT finished_at, last_success_watermark FROM memory_jobs
+         WHERE kind='memory_consolidate_global' AND job_key='global'`)
+            .get();
+        if (!row || !row.last_success_watermark)
+            return null;
+        return row;
     }
     markPhase2Failed(ownershipToken, error) {
-        this.db
+        const res = this.db
             .prepare(`UPDATE memory_jobs SET
            status = 'failed',
            retry_remaining = MAX(0, retry_remaining - 1),
@@ -293,6 +310,21 @@ export class MemoryStore {
            lease_until = NULL
          WHERE kind='memory_consolidate_global' AND job_key='global' AND ownership_token=? AND status='running'`)
             .run(error.slice(0, 4000), nowSec() + PHASE2_RETRY_DELAY_SECONDS, nowSec(), ownershipToken);
+        if (res.changes > 0)
+            return;
+        // codex mark_global_phase2_job_failed_if_unowned: if the owned update
+        // matched nothing, recover a stuck running row that lost its owner
+        // (ownership_token NULL) so it does not linger until lease expiry.
+        this.db
+            .prepare(`UPDATE memory_jobs SET
+           status = 'failed',
+           retry_remaining = MAX(0, retry_remaining - 1),
+           last_error = ?,
+           retry_at = ?,
+           finished_at = ?,
+           lease_until = NULL
+         WHERE kind='memory_consolidate_global' AND job_key='global' AND status='running' AND ownership_token IS NULL`)
+            .run(error.slice(0, 4000), nowSec() + PHASE2_RETRY_DELAY_SECONDS, nowSec());
     }
     /**
      * Phase 2 input set, mirroring codex get_phase2_input_selection: