opencode-codex-memory 0.4.1 → 0.4.3

package/README.md

@@ -1,5 +1,14 @@
 # OpenCode Codex Memory
 
+<p align="center">
+  <a href="https://www.npmjs.com/package/opencode-codex-memory">
+    <img src="https://img.shields.io/npm/v/opencode-codex-memory?logo=npm&amp;label=latest" alt="Latest npm version" />
+  </a>
+  <a href="https://www.npmjs.com/package/opencode-codex-memory">
+    <img src="https://img.shields.io/npm/dt/opencode-codex-memory?logo=npm&amp;label=downloads" alt="npm downloads" />
+  </a>
+</p>
+
 Persistent memory for [OpenCode](https://opencode.ai): your agent remembers what
 it learned in past sessions — your conventions, your projects, the decisions you
 made — and brings that context into new conversations automatically.
@@ -39,11 +48,11 @@ If you want the mental model before the details, jump to
 
 1. Add the plugin to your `~/.config/opencode/opencode.json`:
 
-   ```json
-   {
-     "plugin": ["opencode-codex-memory@0.4.1"]
-   }
-   ```
+```json
+{
+  "plugin": ["opencode-codex-memory@0.4.3"]
+}
+```
 
    **Pin the version** (here and for any OpenCode plugin). OpenCode installs a
    plugin spec once into its package cache and never re-resolves it, so a bare
@@ -228,7 +237,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.1", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.4.3", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -287,7 +296,7 @@ directions:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.1", { "codex_interop": { "import": true, "export": true } }]
+    ["opencode-codex-memory@0.4.3", { "codex_interop": { "import": true, "export": true } }]
   ]
 }
 ```

package/dist/src/capture.js

@@ -127,6 +127,11 @@ function extractText(msg) {
     // parts carry `text`, so they must be dropped before the text check.
     if (msg.type === "reasoning")
         return undefined;
+    // opencode itself drops `ignored` text parts when building model messages
+    // (session/message-v2.ts), e.g. ACP content addressed only to the user.
+    // The assistant never saw them, so they are not conversation.
+    if (msg.ignored === true)
+        return undefined;
     if (typeof msg.text === "string")
         return msg.text;
     if (msg.type === "tool") {
@@ -135,8 +140,16 @@ function extractText(msg) {
         // the extractor's strongest evidence — do not slice them per call.
         const tool = msg.tool ?? "unknown";
         const input = msg.state?.input ? JSON.stringify(msg.state.input) : "";
-        const output = typeof msg.state?.output === "string" ? msg.state.output : "";
-        return `[tool: ${tool}] ${input}${output ? "\n" + output : ""}`;
+        // `output` exists only on status:"completed"; a failed call carries
+        // `error` instead (schema v1/session.ts ToolStateError). codex persists
+        // failed calls too (rollout policy: FunctionCallOutput => true), and "X
+        // failed with Y" is often the most memorable part of a session.
+        const result = typeof msg.state?.output === "string"
+            ? msg.state.output
+            : typeof msg.state?.error === "string"
+                ? `[error] ${msg.state.error}`
+                : "";
+        return `[tool: ${tool}] ${input}${result ? "\n" + result : ""}`;
     }
     if (msg.type === "step-start" || msg.type === "step-finish")
         return undefined;

package/dist/src/index.d.ts

@@ -189,16 +189,27 @@ declare const _default: {
         "chat.message"(input: {
             sessionID?: string;
         }): Promise<void>;
+        /**
+         * Dedicated plugin hook (NOT an event-bus type). Marks the session polluted
+         * at INVOCATION, mirroring codex: mcp_tool_call.rs calls
+         * maybe_mark_thread_memory_mode_polluted inside handle_approved_mcp_tool_call
+         * BEFORE the call runs, and web search marks on the completed response item
+         * (stream_events_utils.rs response_item_may_include_external_context).
+         *
+         * Deliberately not tool.execute.after: opencode does not guarantee that hook
+         * (session/tools.ts awaits execute() with no ensuring/catchAll, and an abort
+         * interrupts the fiber), so a failed or cancelled websearch/webfetch/MCP call
+         * left the session unmarked while its output had already entered the
+         * transcript. Marking early over-marks a permission-denied call, which is the
+         * safe direction for an opt-in guard.
+         *
+         * Pollution remains gated by disable_on_external_context, off by default.
+         */
         "tool.execute.before"(input: {
             tool: string;
             sessionID: string;
             callID: string;
         }): Promise<void>;
-        "tool.execute.after"(input: {
-            tool: string;
-            sessionID: string;
-            callID: string;
-        }): Promise<void>;
         event(input: {
             event: {
                 type: string;

package/dist/src/index.js

@@ -7,16 +7,14 @@ import { MemoryStore } from "./store.js";
 import { runPhase1 } from "./phase1.js";
 import { runPhase2 } from "./phase2.js";
 import { setPluginInput, cleanupOldSubSessions, isMemorySubSession } from "./llm.js";
-import { pluginOptions, recordConfigWarning } from "./options.js";
+import { pluginOptions, recordConfigWarning, clearConfigWarnings } from "./options.js";
 import fs from "fs";
 import path from "path";
 let phase1InFlight = false;
 let pluginClient = null;
-const externalContextCalls = new Map();
-const MAX_TRACKED_TOOL_CALLS = 500;
-function externalContextCallKey(sessionID, callID) {
-    return `${sessionID}\0${callID}`;
-}
+// Single-flight guard for mcp.status(); see mcpToolPrefixes below.
+let mcpStatusInFlight = null;
+const MCP_STATUS_TIMEOUT_MS = 1_000;
 // Deliberately uncached: openDb() is already a singleton, and caching a store
 // here would hold a stale handle across closeDb() (e.g. after memory_reset).
 function getStore() {
@@ -28,17 +26,25 @@ function getStore() {
 // 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) {
-    let seen = recordedCitations.get(partKey);
-    if (!seen) {
-        seen = new Set();
-        recordedCitations.set(partKey, seen);
-        if (recordedCitations.size > MAX_TRACKED_PARTS) {
-            const oldest = recordedCitations.keys().next().value;
-            if (oldest !== undefined)
-                recordedCitations.delete(oldest);
-        }
+/**
+ * Inserts `key` at the most-recently-used end and evicts the oldest entry
+ * beyond `max`. Map.set alone does NOT reorder an existing key, so the
+ * delete is what makes eviction least-recently-*used* rather than
+ * first-inserted — long-lived sessions must not age out mid-use.
+ */
+function lruSet(map, key, value, max) {
+    map.delete(key);
+    map.set(key, value);
+    if (map.size > max) {
+        const oldest = map.keys().next().value;
+        if (oldest !== undefined)
+            map.delete(oldest);
     }
+    return value;
+}
+export function takeNewCitations(partKey, ids) {
+    const seen = recordedCitations.get(partKey) ?? new Set();
+    lruSet(recordedCitations, partKey, seen, MAX_TRACKED_PARTS);
     const fresh = ids.filter((id) => !seen.has(id));
     for (const id of fresh)
         seen.add(id);
@@ -46,19 +52,13 @@ export function takeNewCitations(partKey, ids) {
 }
 // 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();
+// re-fires on idle anyway). Value = first-seen timestamp (debugging only).
+const seenTurnSessions = new Map();
 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;
+    const first = seenTurnSessions.get(sessionId);
+    lruSet(seenTurnSessions, sessionId, first ?? Date.now(), MAX_TRACKED_TURN_SESSIONS);
+    return first === undefined;
 }
 // opencode 1.17 publishes BOTH session.status {type:"idle"} and the
 // deprecated session.idle for the same transition, back to back. Handle
@@ -68,15 +68,11 @@ 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;
+    const deduped = last !== undefined && now - last < IDLE_DEDUP_MS;
+    // Keep the original stamp while deduping so the window cannot be extended
+    // indefinitely by a stream of twins; refresh LRU order either way.
+    lruSet(recentIdle, sessionId, deduped ? last : now, MAX_TRACKED_IDLE);
+    return !deduped;
 }
 export function handleSessionDeleted(sessionId, store = getStore(), 
 // With generation off the memorize agent is not injected, so a consolidation
@@ -93,10 +89,16 @@ export default {
     async server(input, opts) {
         setPluginInput(input);
         pluginClient = input.client;
-        externalContextCalls.clear();
+        mcpStatusInFlight = null;
+        // Unconditional, like the caches above: a boot WITHOUT options must not
+        // inherit the previous boot's warnings (opencode can host several
+        // instances in one process — see the ARCHITECTURE known-gaps table).
+        clearConfigWarnings();
         if (opts)
             applyPluginOptions(opts);
-        void cleanupOldSubSessions().catch(() => { });
+        // Finish bounded reseeding before hooks can see a surviving memory
+        // sub-session after a plugin reload.
+        await cleanupOldSubSessions();
         return buildHooks();
     },
 };
@@ -123,6 +125,9 @@ function clampInt(value, min, max, fallback) {
     return Math.min(max, Math.max(min, Math.floor(value)));
 }
 export function applyPluginOptions(opts) {
+    // Fresh pass per apply so memory_inspect never shows warnings for keys the
+    // caller has since fixed. server() clears too, for boots without options.
+    clearConfigWarnings();
     for (const key of Object.keys(opts)) {
         if (!KNOWN_OPTION_KEYS.has(key)) {
             // codex uses deny_unknown_fields; a plugin can only warn (recorded for
@@ -174,33 +179,69 @@ export function applyPluginOptions(opts) {
  * as "<server>_<tool>", so match tool names against the configured server
  * list. Query live status so runtime MCP changes cannot escape pollution
  * marking. Falls back to the web-tools-only check when status is unavailable.
+ *
+ * Concurrent tool calls coalesce on one in-flight status fetch. Deliberately
+ * NOT cached with a TTL: a stale list would miss servers connected
+ * mid-session and silently stop marking their calls as polluting, which is
+ * the failure this classification exists to prevent. The accepted cost is one
+ * status round trip per tool call — bounded to sessions that opt in with
+ * disable_on_external_context (off by default), and paid only in
+ * tool.execute.before.
  */
-async function classifyExternalContextTool(toolName) {
-    if (toolName === "websearch" || toolName === "webfetch")
-        return true;
+async function mcpToolPrefixes() {
     if (!pluginClient)
         return null;
-    try {
-        const res = await pluginClient.mcp.status();
-        if (res?.error)
-            return null;
-        const servers = res?.data;
-        if (!servers || typeof servers !== "object" || Array.isArray(servers))
-            return null;
-        for (const [server, status] of Object.entries(servers)) {
-            if (!status || typeof status !== "object" || typeof status.status !== "string")
-                continue;
-            // Mirrors OpenCode's McpCatalog.sanitize when constructing tool names.
-            const toolPrefix = server.replace(/[^a-zA-Z0-9_-]/g, "_");
-            if (toolName.startsWith(`${toolPrefix}_`))
-                return true;
-        }
-        return false;
+    if (!mcpStatusInFlight) {
+        mcpStatusInFlight = (async () => {
+            const controller = new AbortController();
+            let timer;
+            try {
+                const res = await Promise.race([
+                    pluginClient.mcp.status({ signal: controller.signal }),
+                    new Promise((_, reject) => {
+                        timer = setTimeout(() => {
+                            controller.abort();
+                            reject(new Error(`mcp.status timed out after ${MCP_STATUS_TIMEOUT_MS}ms`));
+                        }, MCP_STATUS_TIMEOUT_MS);
+                    }),
+                ]);
+                if (res?.error)
+                    return null;
+                const servers = res?.data;
+                if (!servers || typeof servers !== "object" || Array.isArray(servers))
+                    return null;
+                const prefixes = [];
+                for (const [server, status] of Object.entries(servers)) {
+                    if (!status || typeof status !== "object" || typeof status.status !== "string")
+                        continue;
+                    // Mirrors OpenCode's McpCatalog.sanitize when constructing tool names.
+                    prefixes.push(server.replace(/[^a-zA-Z0-9_-]/g, "_"));
+                }
+                return prefixes;
+            }
+            catch {
+                // MCP status unavailable (older OpenCode); keep web-tools-only checks.
+                return null;
+            }
+            finally {
+                clearTimeout(timer);
+                mcpStatusInFlight = null;
+            }
+        })();
     }
-    catch {
-        // MCP status unavailable (older OpenCode); keep web-tools-only checks.
+    return mcpStatusInFlight;
+}
+async function classifyExternalContextTool(toolName) {
+    if (toolName === "websearch" || toolName === "webfetch")
+        return true;
+    const prefixes = await mcpToolPrefixes();
+    if (prefixes === null)
         return null;
+    for (const prefix of prefixes) {
+        if (toolName.startsWith(`${prefix}_`))
+            return true;
     }
+    return false;
 }
 /**
  * Registers the memorize / memorize-extract sub-agents through the config
@@ -354,50 +395,36 @@ function buildHooks() {
                 console.error("[opencode-codex-memory] chat.message error:", err);
             }
         },
-        // Dedicated plugin hooks (NOT event-bus types): capture external-context
-        // classification before each call and mark memory after successful calls.
-        // Pollution remains gated by disable_on_external_context, which is off by
-        // default.
+        /**
+         * Dedicated plugin hook (NOT an event-bus type). Marks the session polluted
+         * at INVOCATION, mirroring codex: mcp_tool_call.rs calls
+         * maybe_mark_thread_memory_mode_polluted inside handle_approved_mcp_tool_call
+         * BEFORE the call runs, and web search marks on the completed response item
+         * (stream_events_utils.rs response_item_may_include_external_context).
+         *
+         * Deliberately not tool.execute.after: opencode does not guarantee that hook
+         * (session/tools.ts awaits execute() with no ensuring/catchAll, and an abort
+         * interrupts the fiber), so a failed or cancelled websearch/webfetch/MCP call
+         * left the session unmarked while its output had already entered the
+         * transcript. Marking early over-marks a permission-denied call, which is the
+         * safe direction for an opt-in guard.
+         *
+         * Pollution remains gated by disable_on_external_context, off by default.
+         */
         async "tool.execute.before"(input) {
             try {
-                if (!pluginOptions.disable_on_external_context || !input.callID)
+                if (!pluginOptions.disable_on_external_context || !input.sessionID)
                     return;
-                const key = externalContextCallKey(input.sessionID, input.callID);
-                externalContextCalls.delete(key);
-                const classification = await classifyExternalContextTool(input.tool);
-                if (classification === null)
+                // null = MCP status unavailable; websearch/webfetch still classify true
+                // without it, so only MCP-prefixed tools go unmarked.
+                if ((await classifyExternalContextTool(input.tool)) !== true)
                     return;
-                externalContextCalls.set(key, classification);
-                if (externalContextCalls.size > MAX_TRACKED_TOOL_CALLS) {
-                    const oldest = externalContextCalls.keys().next().value;
-                    if (oldest !== undefined)
-                        externalContextCalls.delete(oldest);
-                }
+                getStore().markPolluted(input.sessionID);
             }
             catch (err) {
                 console.error("[opencode-codex-memory] tool.execute.before error:", err);
             }
         },
-        async "tool.execute.after"(input) {
-            try {
-                const key = externalContextCallKey(input.sessionID, input.callID);
-                const hasCapturedClassification = Boolean(input.callID) && externalContextCalls.has(key);
-                const capturedClassification = input.callID ? externalContextCalls.get(key) : undefined;
-                if (input.callID)
-                    externalContextCalls.delete(key);
-                if (!pluginOptions.disable_on_external_context)
-                    return;
-                const isExternal = hasCapturedClassification
-                    ? capturedClassification === true
-                    : (await classifyExternalContextTool(input.tool)) === true;
-                if (input.sessionID && isExternal) {
-                    getStore().markPolluted(input.sessionID);
-                }
-            }
-            catch (err) {
-                console.error("[opencode-codex-memory] tool.execute.after error:", err);
-            }
-        },
         async event(input) {
             try {
                 const ev = input.event;

package/dist/src/llm.d.ts

@@ -7,14 +7,32 @@ export interface ExtractionResult {
 export declare function setPluginInput(input: PluginInput): void;
 export declare function getPluginInput(): PluginInput | null;
 export declare function isMemorySubSession(sessionId: string): boolean;
+/**
+ * Thrown when a sub-agent prompt exceeds its budget. A distinct type (rather
+ * than matching on the message text) is what tells the catch below that the
+ * run is still executing server-side and must be aborted.
+ */
+export declare class SubagentTimeoutError extends Error {
+    constructor(timeoutMs: number);
+}
+/**
+ * Thrown when a sub-agent session could not be closed. Codex treats a failed
+ * consolidation-agent shutdown as "the agent may still be alive", so the caller
+ * must keep its job lease instead of completing the job (phase2.rs).
+ */
+export declare class SubagentShutdownError extends Error {
+    constructor(sessionId: string);
+}
 export interface ExtractOptions {
     cwd?: string;
     model?: string;
+    /** Override the default 1h extract timeout (tests / advanced). */
+    timeoutMs?: number;
 }
 /** Returns null when the extractor reported a no-op (nothing worth remembering). */
 export declare function extractViaSubagent(sessionId: string, transcript: string, opts?: ExtractOptions): Promise<ExtractionResult | null>;
 export declare function consolidateViaSubagent(memoryRoot: string, diffFileName: string, model?: string): Promise<void>;
-export declare function cleanupOldSubSessions(maxAgeMinutes?: number): Promise<void>;
+export declare function cleanupOldSubSessions(maxAgeMinutes?: number, timeoutMs?: number): 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

@@ -11,6 +11,10 @@ export function getPluginInput() {
 // hooks skip these so the plugin never injects memory into (or memorizes) its
 // own sub-agents.
 const activeSubSessions = new Set();
+const SUBSESSION_METADATA_KEY = "opencode-codex-memory";
+const SUBSESSION_LIST_TIMEOUT_MS = 5_000;
+const SUBSESSION_ABORT_TIMEOUT_MS = 1_000;
+const SUBSESSION_CONFIRM_TIMEOUT_MS = 1_000;
 export function isMemorySubSession(sessionId) {
     return activeSubSessions.has(sessionId);
 }
@@ -19,7 +23,10 @@ async function createSession(agent, title) {
     if (!input)
         throw new Error("plugin input not initialized");
     const res = await input.client.session.create({
-        body: { title: title ?? `codex-memory-${agent}` },
+        body: {
+            title: title ?? `codex-memory-${agent}`,
+            metadata: { [SUBSESSION_METADATA_KEY]: true },
+        },
     });
     if (!res.data)
         throw new Error(`session create failed: ${JSON.stringify(res.error ?? {})}`);
@@ -63,6 +70,53 @@ function parseModelRef(ref) {
         return null;
     return { providerID: ref.slice(0, slash), modelID: ref.slice(slash + 1) };
 }
+/**
+ * Thrown when a sub-agent prompt exceeds its budget. A distinct type (rather
+ * than matching on the message text) is what tells the catch below that the
+ * run is still executing server-side and must be aborted.
+ */
+export class SubagentTimeoutError extends Error {
+    constructor(timeoutMs) {
+        super(`sub-agent prompt timed out after ${timeoutMs}ms`);
+        this.name = "SubagentTimeoutError";
+    }
+}
+/**
+ * Thrown when a sub-agent session could not be closed. Codex treats a failed
+ * consolidation-agent shutdown as "the agent may still be alive", so the caller
+ * must keep its job lease instead of completing the job (phase2.rs).
+ */
+export class SubagentShutdownError extends Error {
+    constructor(sessionId) {
+        super(`failed to close memory sub-session ${sessionId}`);
+        this.name = "SubagentShutdownError";
+    }
+}
+async function abortSession(sessionId) {
+    const input = getPluginInput();
+    const session = input?.client?.session;
+    if (typeof session?.abort !== "function")
+        return;
+    const controller = new AbortController();
+    let timer;
+    try {
+        await Promise.race([
+            session.abort({ path: { id: sessionId }, signal: controller.signal }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`session.abort timed out after ${SUBSESSION_ABORT_TIMEOUT_MS}ms`));
+                }, SUBSESSION_ABORT_TIMEOUT_MS);
+            }),
+        ]);
+    }
+    catch {
+        // Best-effort: deleteSession is the backup cancel path.
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** Runs a sub-agent prompt and returns the raw response data (`{ info, parts }`). */
 async function runPrompt(sessionId, prompt, agent, opts = {}) {
     const timeoutMs = opts.timeoutMs ?? 300_000;
@@ -87,7 +141,7 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
         const res = await Promise.race([
             promptPromise,
             new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`sub-agent prompt timed out after ${timeoutMs}ms`)), timeoutMs);
+                timer = setTimeout(() => reject(new SubagentTimeoutError(timeoutMs)), timeoutMs);
             }),
         ]);
         if (!res.data)
@@ -99,6 +153,15 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
         }
         return res.data;
     }
+    catch (err) {
+        // Only a timeout leaves the turn running server-side; every other failure
+        // here means the request already settled. Stop the run so tokens stop
+        // burning — deleteSession in the caller finally is the backup.
+        if (err instanceof SubagentTimeoutError) {
+            await abortSession(sessionId);
+        }
+        throw err;
+    }
     finally {
         clearTimeout(timer);
     }
@@ -153,7 +216,7 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
             // 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,
+            timeoutMs: opts.timeoutMs ?? 3600_000,
             system: readTemplate("stage_one_system.md"),
             model,
             // opencode enforces json_schema output via a forced StructuredOutput tool
@@ -172,6 +235,9 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
         return parseExtraction(extractAssistantText(data));
     }
     finally {
+        // Fire-and-forget on purpose (unlike consolidation): stage 1 has no codex
+        // agent-shutdown step, and memorize-extract has no write tools, so a
+        // lingering extract session cannot touch the memory root.
         void deleteSession(subId).catch(() => { });
     }
 }
@@ -182,55 +248,136 @@ const CONSOLIDATION_TIMEOUT_MS = 3600_000;
 export async function consolidateViaSubagent(memoryRoot, diffFileName, model) {
     const agent = "memorize";
     const subId = await createSession(agent, "codex-memory-consolidate");
+    let promptError;
+    let promptFailed = false;
     try {
         const prompt = buildConsolidationPrompt(memoryRoot, diffFileName);
         // consolidation_model option > opencode model (main) > session default.
         const resolved = model ?? (await getConfigModels()).model;
         await promptSession(subId, prompt, agent, { model: resolved, timeoutMs: CONSOLIDATION_TIMEOUT_MS });
     }
-    finally {
-        void deleteSession(subId).catch(() => { });
+    catch (err) {
+        promptError = err;
+        promptFailed = true;
     }
+    // codex phase2.rs awaits the consolidation agent's shutdown BEFORE artifacts
+    // are validated and the job is finished, and a failed shutdown outranks the
+    // run result: the caller must keep its lease rather than release it to a
+    // worker that could race a consolidator which is still alive. The
+    // consolidation agent holds write access to the memory root, so this is the
+    // difference between one writer and two.
+    if (!(await deleteSession(subId)))
+        throw new SubagentShutdownError(subId);
+    if (promptFailed)
+        throw promptError;
 }
 // Must exceed the longest legitimate sub-session lifetime (consolidation may
 // run up to CONSOLIDATION_TIMEOUT_MS = 60min), or a second opencode instance /
 // plugin reload would delete a working sub-session mid-run.
-export async function cleanupOldSubSessions(maxAgeMinutes = 90) {
+export async function cleanupOldSubSessions(maxAgeMinutes = 90, timeoutMs = SUBSESSION_LIST_TIMEOUT_MS) {
     const input = getPluginInput();
     if (!input)
         return;
+    let timer;
     try {
-        const res = await input.client.session.list();
+        if (typeof input.client?.session?.list !== "function")
+            return;
+        const res = await Promise.race([
+            input.client.session.list(),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`session.list timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
         if (!res.data)
             return;
         const list = res.data;
         const cutoff = Date.now() - maxAgeMinutes * 60 * 1000;
         for (const s of list) {
-            if (s.title && s.title.startsWith("codex-memory-")) {
-                const created = s.time?.created ?? 0;
-                if (created && created < cutoff) {
-                    await deleteSession(s.id);
-                }
+            if (!s.id)
+                continue;
+            const pluginTitle = isPluginSubSessionTitle(s.title);
+            const owned = s.metadata?.[SUBSESSION_METADATA_KEY] === true && pluginTitle;
+            const legacy = s.metadata?.[SUBSESSION_METADATA_KEY] !== true && pluginTitle;
+            if (!owned && !legacy)
+                continue;
+            // Durable ownership requires marker + generated title; a legacy title
+            // alone can reseed the skip set but never authorizes deletion.
+            activeSubSessions.add(s.id);
+            if (!owned)
+                continue;
+            const created = s.time?.created ?? 0;
+            if (created && created < cutoff) {
+                void deleteSession(s.id);
             }
         }
     }
     catch {
         // best effort only
     }
+    finally {
+        clearTimeout(timer);
+    }
+}
+function isPluginSubSessionTitle(title) {
+    return title === "codex-memory-consolidate" || /^codex-memory-extract-ses_[A-Za-z0-9]+$/.test(title ?? "");
 }
+/**
+ * Closes a sub-session. Returns true when the delete call itself succeeded —
+ * the port's equivalent of codex's `shutdown_consolidation_agent` returning Ok
+ * (runtime.rs). A false return means the sub-agent may still be running.
+ *
+ * The 404 confirmation below is a separate, stricter question (is the session
+ * really gone?) and only governs ownership tracking, never the shutdown result:
+ * hosts without `session.get` would otherwise never report a clean shutdown.
+ */
 async function deleteSession(id) {
-    activeSubSessions.delete(id);
     const input = getPluginInput();
     if (!input)
-        return;
+        return false;
     try {
         const res = await input.client.session.delete({ path: { id } });
         if (res.error) {
             console.warn(`[opencode-codex-memory] failed to delete sub-session ${id}: ${JSON.stringify(res.error)}`);
+            return false;
         }
+        // OpenCode's Session.remove logs and swallows some internal failures while
+        // the HTTP route still returns success. Only a confirmed 404 proves the
+        // 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)) {
+            activeSubSessions.delete(id);
+        }
+        return true;
     }
     catch (err) {
         console.warn(`[opencode-codex-memory] error deleting sub-session ${id}:`, err);
+        return false;
+    }
+}
+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);
     }
 }
 // Substitute with a function so `$&`/`$'` sequences in the value are not

package/dist/src/options.d.ts

@@ -26,5 +26,7 @@ export interface PluginOptionsState {
 export declare const pluginOptions: PluginOptionsState;
 export declare function recordConfigWarning(message: string): void;
 export declare function getConfigWarnings(): readonly string[];
+/** Drop warnings from a previous apply pass (server boot / option re-apply). */
+export declare function clearConfigWarnings(): void;
 /** Test seam: options/warnings are module state, tests need a clean slate. */
 export declare function resetConfigWarningsForTest(): void;

package/dist/src/options.js

@@ -25,7 +25,11 @@ export function recordConfigWarning(message) {
 export function getConfigWarnings() {
     return configWarnings;
 }
+/** Drop warnings from a previous apply pass (server boot / option re-apply). */
+export function clearConfigWarnings() {
+    configWarnings.length = 0;
+}
 /** Test seam: options/warnings are module state, tests need a clean slate. */
 export function resetConfigWarningsForTest() {
-    configWarnings.length = 0;
+    clearConfigWarnings();
 }

package/dist/src/phase2.js

@@ -1,6 +1,6 @@
 import { ensureLayout, rebuildRawMemories, writeRolloutSummaries, pruneExtensionResources, writeWorkspaceDiff, validateConsolidationArtifacts, } from "./workspace.js";
 import { ensureBaseline, captureWorkspaceDiff, resetBaseline, DIFF_ARTIFACT } from "./git-baseline.js";
-import { consolidateViaSubagent } from "./llm.js";
+import { consolidateViaSubagent, SubagentShutdownError } from "./llm.js";
 import { invalidateCache } from "./source.js";
 import { memoryRoot } from "./paths.js";
 import { checkRateLimit } from "./ratelimit.js";
@@ -105,6 +105,17 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
             try {
                 await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel);
             }
+            catch (err) {
+                // codex phase2.rs: when the consolidation agent's shutdown fails, keep
+                // the existing lease until it expires so another worker cannot race a
+                // consolidator whose shutdown has not completed. Neither succeed nor
+                // fail the job — marking it failed would release the lease immediately.
+                if (err instanceof SubagentShutdownError) {
+                    console.warn(`[opencode-codex-memory] ${err.message}; holding the phase2 lease until it expires`);
+                    return { status: "shutdown_failed" };
+                }
+                throw err;
+            }
             finally {
                 clearInterval(heartbeat);
             }

package/dist/src/redact.d.ts

@@ -4,5 +4,13 @@ export declare function redact(text: string): string;
  * injected AGENTS.md instruction blocks and <skill> payloads inside user
  * content are contextual boilerplate, not conversation — they must not be
  * mined for memories.
+ *
+ * NOTE: inert on opencode today, kept for codex parity and future-proofing.
+ * opencode delivers both of these through the SYSTEM prompt, never as a user
+ * text part: AGENTS.md is joined into `system[0]` and skills are a
+ * `<available_skills>` catalog (skill/index.ts `fmt`), so neither shape ever
+ * reaches this check. Do not treat it as an active safeguard — the structural
+ * filters in capture.ts (`ignored` parts) are what actually exclude
+ * non-conversation content on this platform.
  */
 export declare function isMemoryExcludedFragment(text: string): boolean;

package/dist/src/redact.js

@@ -10,18 +10,214 @@ const REDACTIONS = [
         re: /-----BEGIN [A-Z]+ PRIVATE KEY-----[\s\S]*?-----END [A-Z]+ PRIVATE KEY-----/g,
         replacement: "[REDACTED:private-key]",
     },
-    // 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]" },
 ];
+// Optional quotes around the key cover JSON/YAML forms that codex's bare-key
+// assignment regex misses. Value boundaries are scanned instead of guessed by
+// one regex so escaped strings and nested JSON remain intact.
+const SECRET_ASSIGNMENT_START = /(["']?)(password|passwd|pwd|secret|api[_-]?key|token|access[_-]?token|aws_secret_access_key|aws_access_key_id)\1([ \t]*[:=][ \t]*)/gi;
+const JSON_PRIMITIVE = /^(?:-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?|true|false|null)(?=\s*[,}\]])/i;
 export function redact(text) {
     let out = text;
     for (const { re, replacement } of REDACTIONS) {
         out = out.replace(re, replacement);
     }
-    return out;
+    return redactAssignments(out);
+}
+function redactAssignments(text) {
+    let cursor = 0;
+    let out = "";
+    let flowCursor = 0;
+    const matchedOpeners = findMatchedFlowOpeners(text);
+    const flowState = { closers: [], quote: null, escaped: false };
+    SECRET_ASSIGNMENT_START.lastIndex = 0;
+    for (let match = SECRET_ASSIGNMENT_START.exec(text); match; match = SECRET_ASSIGNMENT_START.exec(text)) {
+        advanceFlowState(text, flowCursor, match.index, flowState, matchedOpeners);
+        flowCursor = match.index;
+        const valueStart = SECRET_ASSIGNMENT_START.lastIndex;
+        const value = scanAssignmentValue(text, valueStart, match[1], match[3], flowState.closers.length > 0, flowState.quote);
+        if (!value)
+            continue;
+        out += text.slice(cursor, value.start) + value.replacement;
+        cursor = value.end;
+        SECRET_ASSIGNMENT_START.lastIndex = value.end;
+    }
+    return out + text.slice(cursor);
+}
+function scanAssignmentValue(text, start, keyQuote, separator, flowCollection, enclosingQuote) {
+    let valueStart = start;
+    if (enclosingQuote) {
+        const end = scanEnclosingQuote(text, valueStart, enclosingQuote);
+        return end > valueStart ? { start: valueStart, end, replacement: "[REDACTED]" } : null;
+    }
+    if (flowCollection && separator.includes(":")) {
+        while (/\s/.test(text[valueStart] ?? ""))
+            valueStart++;
+    }
+    const first = text[valueStart];
+    if (!first || first === "\r" || first === "\n")
+        return null;
+    if (first === '"' || first === "'") {
+        const end = scanQuoted(text, valueStart, first) ?? plainValueEnd(text, valueStart, flowCollection);
+        return end > valueStart ? { start: valueStart, end, replacement: `${first}[REDACTED]${first}` } : null;
+    }
+    if (first === "{" || first === "[") {
+        const end = scanStructuredJson(text, valueStart) ?? plainValueEnd(text, valueStart, flowCollection);
+        return end > valueStart ? { start: valueStart, end, replacement: '"[REDACTED]"' } : null;
+    }
+    if (keyQuote === '"' && separator.includes(":")) {
+        const primitive = JSON_PRIMITIVE.exec(text.slice(valueStart));
+        if (primitive)
+            return { start: valueStart, end: valueStart + primitive[0].length, replacement: '"[REDACTED]"' };
+    }
+    const end = plainValueEnd(text, valueStart, flowCollection);
+    return end > valueStart ? { start: valueStart, end, replacement: '"[REDACTED]"' } : null;
+}
+function scanEnclosingQuote(text, start, quote) {
+    for (let i = start; i < text.length; i++) {
+        if (quote === '"' && text[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (text[i] !== quote)
+            continue;
+        if (quote === "'" && text[i + 1] === "'") {
+            i++;
+            continue;
+        }
+        return i;
+    }
+    return plainValueEnd(text, start, false);
+}
+function scanQuoted(text, start, quote) {
+    for (let i = start + 1; i < text.length; i++) {
+        if (quote === '"' && text[i] === "\\") {
+            i++;
+            continue;
+        }
+        if (text[i] !== quote)
+            continue;
+        if (quote === "'" && text[i + 1] === "'") {
+            i++;
+            continue;
+        }
+        return i + 1;
+    }
+    return null;
+}
+function scanStructuredJson(text, start) {
+    const closers = [text[start] === "{" ? "}" : "]"];
+    let quote = null;
+    for (let i = start + 1; i < text.length; i++) {
+        const char = text[i];
+        if (quote) {
+            if (quote === '"' && char === "\\")
+                i++;
+            else if (char === quote) {
+                if (quote === "'" && text[i + 1] === "'")
+                    i++;
+                else
+                    quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            continue;
+        }
+        if (char === "{")
+            closers.push("}");
+        else if (char === "[")
+            closers.push("]");
+        else if (char === closers[closers.length - 1]) {
+            closers.pop();
+            if (closers.length === 0)
+                return i + 1;
+        }
+    }
+    return null;
+}
+function findMatchedFlowOpeners(text) {
+    const matched = new Set();
+    const stack = [];
+    let quote = null;
+    let escaped = false;
+    for (let i = 0; i < text.length; i++) {
+        const char = text[i];
+        if (quote) {
+            if (escaped)
+                escaped = false;
+            else if (quote === '"' && char === "\\")
+                escaped = true;
+            else if (char === quote) {
+                if (quote === "'" && text[i + 1] === "'")
+                    i++;
+                else
+                    quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'")
+            quote = char;
+        else if (char === "{")
+            stack.push({ index: i, closer: "}" });
+        else if (char === "[")
+            stack.push({ index: i, closer: "]" });
+        else if (char === stack[stack.length - 1]?.closer) {
+            const opener = stack.pop();
+            if (opener)
+                matched.add(opener.index);
+        }
+    }
+    return matched;
+}
+function advanceFlowState(text, start, end, state, matchedOpeners) {
+    for (let i = start; i < end; i++) {
+        const char = text[i];
+        if (state.quote) {
+            if (state.escaped) {
+                state.escaped = false;
+            }
+            else if (state.quote === '"' && char === "\\") {
+                state.escaped = true;
+            }
+            else if (char === state.quote) {
+                if (state.quote === "'" && text[i + 1] === "'")
+                    i++;
+                else
+                    state.quote = null;
+            }
+            continue;
+        }
+        if (char === '"' || char === "'")
+            state.quote = char;
+        else if (char === "{" && matchedOpeners.has(i))
+            state.closers.push("}");
+        else if (char === "[" && matchedOpeners.has(i))
+            state.closers.push("]");
+        else if (char === state.closers[state.closers.length - 1])
+            state.closers.pop();
+    }
+}
+function plainValueEnd(text, start, flowCollection) {
+    let end = text.length;
+    for (let i = start; i < text.length; i++) {
+        const char = text[i];
+        if (char === "\n") {
+            end = i;
+            break;
+        }
+        if (flowCollection && (char === "," || char === "}" || char === "]")) {
+            end = i;
+            break;
+        }
+        if (char === "#" && i > start && /\s/.test(text[i - 1])) {
+            end = i;
+            break;
+        }
+    }
+    while (end > start && /\s/.test(text[end - 1]))
+        end--;
+    return end;
 }
 function matchesMarkedFragment(text, startMarker, endMarker) {
     const trimmed = text.trim();
@@ -33,6 +229,14 @@ function matchesMarkedFragment(text, startMarker, endMarker) {
  * injected AGENTS.md instruction blocks and <skill> payloads inside user
  * content are contextual boilerplate, not conversation — they must not be
  * mined for memories.
+ *
+ * NOTE: inert on opencode today, kept for codex parity and future-proofing.
+ * opencode delivers both of these through the SYSTEM prompt, never as a user
+ * text part: AGENTS.md is joined into `system[0]` and skills are a
+ * `<available_skills>` catalog (skill/index.ts `fmt`), so neither shape ever
+ * reaches this check. Do not treat it as an active safeguard — the structural
+ * filters in capture.ts (`ignored` parts) are what actually exclude
+ * non-conversation content on this platform.
  */
 export function isMemoryExcludedFragment(text) {
     return (matchesMarkedFragment(text, "# AGENTS.md instructions", "</INSTRUCTIONS>") ||

package/dist/src/source.js

@@ -1,6 +1,7 @@
 import fs from "fs";
 import path from "path";
-import { memorySummaryPath, memoryRoot } from "./paths.js";
+import { memoryRoot } from "./paths.js";
+import { assertMemoryRootSafe, safeResolveMemoryPath } from "./path-guard.js";
 import { truncateToTokens } from "./token.js";
 import { fillTemplate } from "./llm.js";
 const MEMORY_SUMMARY_TOKEN_LIMIT = 2500;
@@ -30,22 +31,36 @@ function readTemplate() {
     return fs.readFileSync(templatePath, "utf8");
 }
 function readMemorySummary() {
-    const summaryPath = memorySummaryPath();
-    if (!fs.existsSync(summaryPath))
-        return null;
-    const stat = fs.statSync(summaryPath);
-    if (cached && cached.mtime === stat.mtimeMs) {
-        return cached.content;
+    let summaryPath;
+    let fd;
+    try {
+        // Use the same component-by-component symlink refusal as the memory tools:
+        // neither the root nor memory_summary.md may redirect outside the workspace.
+        summaryPath = safeResolveMemoryPath("memory_summary.md");
+        fd = fs.openSync(summaryPath, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        const stat = fs.fstatSync(fd);
+        if (!stat.isFile())
+            return null;
+        if (cached && cached.mtime === stat.mtimeMs) {
+            return cached.content;
+        }
+        const raw = fs.readFileSync(fd, "utf8").trim();
+        if (!raw)
+            return null;
+        const truncated = truncateToTokens(raw, MEMORY_SUMMARY_TOKEN_LIMIT);
+        cached = {
+            content: truncated,
+            mtime: stat.mtimeMs,
+        };
+        return truncated;
     }
-    const raw = fs.readFileSync(summaryPath, "utf8").trim();
-    if (!raw)
+    catch {
         return null;
-    const truncated = truncateToTokens(raw, MEMORY_SUMMARY_TOKEN_LIMIT);
-    cached = {
-        content: truncated,
-        mtime: stat.mtimeMs,
-    };
-    return truncated;
+    }
+    finally {
+        if (fd !== undefined)
+            fs.closeSync(fd);
+    }
 }
 export function invalidateCache() {
     cached = null;
@@ -64,5 +79,6 @@ export function buildMemorySystemPrompt(dedicatedTools) {
     });
 }
 export function ensureMemoryLayout() {
-    fs.mkdirSync(memoryRoot(), { recursive: true });
+    const root = assertMemoryRootSafe();
+    fs.mkdirSync(root, { recursive: true });
 }

package/dist/src/store.js

@@ -81,10 +81,16 @@ export class MemoryStore {
     recordUsage(sessionIds) {
         if (sessionIds.length === 0)
             return;
+        // One transaction for the whole batch (codex record_stage1_output_usage).
+        // .immediate() like every other write transaction here: take the write
+        // lock up front so busy_timeout applies instead of risking a mid-txn
+        // upgrade failure under cross-process access.
         const ts = now();
         const stmt = this.db.prepare("UPDATE memory_stage1_outputs SET usage_count = usage_count + 1, last_usage = ? WHERE session_id = ?");
-        for (const id of sessionIds)
-            stmt.run(ts, id);
+        this.db.transaction(() => {
+            for (const id of sessionIds)
+                stmt.run(ts, id);
+        }).immediate();
     }
     claimStage1Jobs(sessions, excludeSession, maxClaimed) {
         const workerId = newId();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-codex-memory",
-  "version": "0.4.1",
+  "version": "0.4.3",
   "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",