opencode-codex-memory 0.4.3 → 0.4.5

package/README.md

@@ -18,6 +18,8 @@ project is a faithful port of the memory system in OpenAI's Codex. It works out
 of the box with zero extra configuration and uses whatever models you already
 have set up in OpenCode.
 
+See the [changelog](./CHANGELOG.md) for release history.
+
 **Local-first by design.** Memory is plain markdown files plus a small SQLite
 database on your own machine — no memory service to sign up for, no MCP server,
 no separate process, no sync. Installing it is one line in your `opencode.json`;
@@ -50,7 +52,7 @@ If you want the mental model before the details, jump to
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.4.3"]
+  "plugin": ["opencode-codex-memory@0.4.5"]
 }
 ```
 
@@ -237,7 +239,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.3", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.4.5", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -296,7 +298,7 @@ directions:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.3", { "codex_interop": { "import": true, "export": true } }]
+    ["opencode-codex-memory@0.4.5", { "codex_interop": { "import": true, "export": true } }]
   ]
 }
 ```

package/dist/src/codex-interop.js

@@ -2,7 +2,7 @@ import fs from "fs";
 import path from "path";
 import os from "os";
 import { memoryRoot } from "./paths.js";
-import { safeResolveUnderRoot } from "./path-guard.js";
+import { readRegularFileNoFollow, safeResolveUnderRoot, writeRegularFileNoFollow } from "./path-guard.js";
 /**
  * Codex interop: memory exchange with an upstream Codex CLI installation on
  * the same machine, in both directions, through the generic extensions
@@ -202,10 +202,7 @@ export function resolveCodexInterop(opts) {
 }
 function readIfFile(file) {
     try {
-        const st = fs.lstatSync(file);
-        if (!st.isFile())
-            return null;
-        return fs.readFileSync(file);
+        return readRegularFileNoFollow(file).content;
     }
     catch {
         return null;
@@ -226,7 +223,7 @@ function writeIfChanged(file, content) {
     }
     catch { }
     fs.mkdirSync(path.dirname(file), { recursive: true });
-    fs.writeFileSync(file, next, { flag: "w" });
+    writeRegularFileNoFollow(file, next);
     return true;
 }
 /**

package/dist/src/db.js

@@ -68,13 +68,17 @@ function runMigrations(db) {
     version INTEGER NOT NULL,
     applied_at INTEGER NOT NULL
   )`);
-    const current = db.prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").get();
-    const currentVersion = current?.version ?? 0;
-    if (currentVersion >= 1)
-        return;
-    for (const stmt of SCHEMA_V1)
-        db.run(stmt);
-    db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (?, ?)").run(1, Date.now());
+    db.transaction(() => {
+        // Read the version only after taking the write lock so concurrent plugin
+        // instances cannot both apply the same ALTER TABLE.
+        const current = db.prepare("SELECT version FROM schema_version ORDER BY version DESC LIMIT 1").get();
+        const currentVersion = current?.version ?? 0;
+        if (currentVersion < 1) {
+            for (const stmt of SCHEMA_V1)
+                db.run(stmt);
+            db.prepare("INSERT INTO schema_version (version, applied_at) VALUES (?, ?)").run(1, Date.now());
+        }
+    }).immediate();
 }
 export function closeDb() {
     if (dbInstance) {

package/dist/src/git-baseline.js

@@ -3,6 +3,7 @@ import path from "path";
 import { memoryRoot } from "./paths.js";
 import * as isogit from "isomorphic-git";
 import { createPatch } from "diff";
+import { readRegularFileNoFollow, safeResolveUnderRoot } from "./path-guard.js";
 const AUTHOR = { name: "opencode-codex-memory", email: "memory@opencode.local" };
 // Generated prompt artifact; removed before diffing and before baseline
 // commits (mirrors codex's remove_workspace_diff) so it never enters the
@@ -120,12 +121,8 @@ async function readBaselineText(dir, headOid, filepath) {
     }
 }
 function readWorkdirText(dir, filepath) {
-    try {
-        return fs.readFileSync(path.join(dir, filepath), "utf8");
-    }
-    catch {
-        return "";
-    }
+    const file = safeResolveUnderRoot(dir, filepath);
+    return readRegularFileNoFollow(file).content.toString("utf8");
 }
 // Throws on failure: codex fails the phase-2 job on workspace-status errors
 // (failed_workspace_status). Swallowing the error here would make an errored

package/dist/src/index.js

@@ -7,7 +7,7 @@ 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, clearConfigWarnings } from "./options.js";
+import { pluginOptions, recordConfigWarning, clearConfigWarnings, resetPluginOptions } from "./options.js";
 import fs from "fs";
 import path from "path";
 let phase1InFlight = false;
@@ -96,6 +96,8 @@ export default {
         clearConfigWarnings();
         if (opts)
             applyPluginOptions(opts);
+        else
+            resetPluginOptions();
         // Finish bounded reseeding before hooks can see a surviving memory
         // sub-session after a plugin reload.
         await cleanupOldSubSessions();
@@ -116,18 +118,23 @@ const KNOWN_OPTION_KEYS = new Set([
     "min_rollout_idle_hours",
     "codex_interop",
 ]);
+const KNOWN_CODEX_INTEROP_KEYS = new Set(["import", "export", "codex_home"]);
 // codex clamps numeric knobs in From<MemoriesToml> for MemoriesConfig
 // (config/src/types.rs); mirror the exact ranges. Non-finite values fall back
 // to the default.
-function clampInt(value, min, max, fallback) {
-    if (typeof value !== "number" || !Number.isFinite(value))
+function clampInt(key, value, min, max, fallback) {
+    if (typeof value !== "number" || !Number.isFinite(value)) {
+        recordConfigWarning(`${key} must be a finite number; using default ${fallback}`);
         return 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();
+    resetPluginOptions();
+    const raw = opts;
     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
@@ -136,32 +143,50 @@ export function applyPluginOptions(opts) {
             recordConfigWarning(`unknown/unsupported option '${key}' ignored`);
         }
     }
-    if (typeof opts.generate_memories === "boolean")
-        pluginOptions.generate_memories = opts.generate_memories;
-    if (typeof opts.use_memories === "boolean")
-        pluginOptions.use_memories = opts.use_memories;
-    if (typeof opts.dedicated_tools === "boolean")
-        pluginOptions.dedicated_tools = opts.dedicated_tools;
-    if (typeof opts.disable_on_external_context === "boolean")
-        pluginOptions.disable_on_external_context = opts.disable_on_external_context;
-    if (typeof opts.extract_model === "string")
-        pluginOptions.extract_model = opts.extract_model;
-    if (typeof opts.consolidation_model === "string")
-        pluginOptions.consolidation_model = opts.consolidation_model;
+    for (const key of ["generate_memories", "use_memories", "dedicated_tools", "disable_on_external_context"]) {
+        if (!(key in raw))
+            continue;
+        if (typeof raw[key] === "boolean")
+            pluginOptions[key] = raw[key];
+        else
+            recordConfigWarning(`${key} must be a boolean; using default ${pluginOptions[key]}`);
+    }
+    for (const key of ["extract_model", "consolidation_model"]) {
+        if (!(key in raw))
+            continue;
+        if (typeof raw[key] === "string")
+            pluginOptions[key] = raw[key];
+        else
+            recordConfigWarning(`${key} must be a string; using the opencode model default`);
+    }
     if ("max_raw_memories_for_consolidation" in opts)
-        pluginOptions.max_raw_memories_for_consolidation = clampInt(opts.max_raw_memories_for_consolidation, 1, 4096, 256);
+        pluginOptions.max_raw_memories_for_consolidation = clampInt("max_raw_memories_for_consolidation", opts.max_raw_memories_for_consolidation, 1, 4096, 256);
     if ("max_unused_days" in opts)
-        pluginOptions.max_unused_days = clampInt(opts.max_unused_days, 0, 365, 30);
+        pluginOptions.max_unused_days = clampInt("max_unused_days", opts.max_unused_days, 0, 365, 30);
     if ("max_rollout_age_days" in opts)
-        pluginOptions.max_rollout_age_days = clampInt(opts.max_rollout_age_days, 0, 90, 10);
+        pluginOptions.max_rollout_age_days = clampInt("max_rollout_age_days", opts.max_rollout_age_days, 0, 90, 10);
     if ("max_rollouts_per_startup" in opts)
-        pluginOptions.max_rollouts_per_startup = clampInt(opts.max_rollouts_per_startup, 1, 128, 2);
+        pluginOptions.max_rollouts_per_startup = clampInt("max_rollouts_per_startup", opts.max_rollouts_per_startup, 1, 128, 2);
     if ("min_rollout_idle_hours" in opts)
-        pluginOptions.min_rollout_idle_hours = clampInt(opts.min_rollout_idle_hours, 1, 48, 6);
+        pluginOptions.min_rollout_idle_hours = clampInt("min_rollout_idle_hours", opts.min_rollout_idle_hours, 1, 48, 6);
     if ("codex_interop" in opts) {
         const raw = opts.codex_interop;
         if (raw && typeof raw === "object" && !Array.isArray(raw)) {
             const o = raw;
+            for (const key of Object.keys(o)) {
+                if (!KNOWN_CODEX_INTEROP_KEYS.has(key)) {
+                    recordConfigWarning(`unknown codex_interop option '${key}' ignored`);
+                }
+            }
+            if ("import" in o && typeof o.import !== "boolean") {
+                recordConfigWarning("codex_interop.import must be a boolean; using false");
+            }
+            if ("export" in o && typeof o.export !== "boolean") {
+                recordConfigWarning("codex_interop.export must be a boolean; using false");
+            }
+            if ("codex_home" in o && (typeof o.codex_home !== "string" || o.codex_home.length === 0)) {
+                recordConfigWarning("codex_interop.codex_home must be a non-empty string; using the default Codex home");
+            }
             pluginOptions.codex_interop = {
                 import: o.import === true,
                 export: o.export === true,

package/dist/src/llm.d.ts

@@ -15,6 +15,10 @@ export declare function isMemorySubSession(sessionId: string): boolean;
 export declare class SubagentTimeoutError extends Error {
     constructor(timeoutMs: number);
 }
+/** Thrown after an external owner cancels a running sub-agent prompt. */
+export declare class SubagentCancelledError extends Error {
+    constructor();
+}
 /**
  * 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
@@ -31,7 +35,7 @@ export interface ExtractOptions {
 }
 /** 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 consolidateViaSubagent(memoryRoot: string, diffFileName: string, model?: string, signal?: AbortSignal): 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

@@ -3,6 +3,7 @@ import path from "path";
 let inputRef = null;
 export function setPluginInput(input) {
     inputRef = input;
+    configModels = null;
 }
 export function getPluginInput() {
     return inputRef;
@@ -15,6 +16,7 @@ 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;
+const SUBSESSION_DELETE_TIMEOUT_MS = 10_000;
 export function isMemorySubSession(sessionId) {
     return activeSubSessions.has(sessionId);
 }
@@ -81,6 +83,13 @@ export class SubagentTimeoutError extends Error {
         this.name = "SubagentTimeoutError";
     }
 }
+/** Thrown after an external owner cancels a running sub-agent prompt. */
+export class SubagentCancelledError extends Error {
+    constructor() {
+        super("sub-agent prompt cancelled");
+        this.name = "SubagentCancelledError";
+    }
+}
 /**
  * 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
@@ -123,6 +132,10 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
     const input = getPluginInput();
     if (!input)
         throw new Error("plugin input not initialized");
+    if (opts.signal?.aborted) {
+        await abortSession(sessionId);
+        throw new SubagentCancelledError();
+    }
     const model = opts.model ? parseModelRef(opts.model) : null;
     const promptPromise = input.client.session.prompt({
         path: { id: sessionId },
@@ -137,9 +150,17 @@ async function runPrompt(sessionId, prompt, agent, opts = {}) {
         },
     });
     let timer;
+    let onAbort;
     try {
+        const cancellation = new Promise((_, reject) => {
+            if (!opts.signal)
+                return;
+            onAbort = () => reject(new SubagentCancelledError());
+            opts.signal.addEventListener("abort", onAbort, { once: true });
+        });
         const res = await Promise.race([
             promptPromise,
+            cancellation,
             new Promise((_, reject) => {
                 timer = setTimeout(() => reject(new SubagentTimeoutError(timeoutMs)), timeoutMs);
             }),
@@ -154,16 +175,18 @@ 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) {
+        // A timeout or owner cancellation can leave the turn running server-side;
+        // other failures mean the request already settled. Stop the live run so
+        // tokens stop burning — deleteSession in the caller is the backup.
+        if (err instanceof SubagentTimeoutError || err instanceof SubagentCancelledError) {
             await abortSession(sessionId);
         }
         throw err;
     }
     finally {
         clearTimeout(timer);
+        if (onAbort)
+            opts.signal?.removeEventListener("abort", onAbort);
     }
 }
 async function promptSession(sessionId, prompt, agent, opts = {}) {
@@ -245,7 +268,7 @@ export async function extractViaSubagent(sessionId, transcript, opts = {}) {
 // its INIT pass is explicitly allowed to run long ("do not be lazy"). A short
 // timeout here would fail the job after the workspace was already synced.
 const CONSOLIDATION_TIMEOUT_MS = 3600_000;
-export async function consolidateViaSubagent(memoryRoot, diffFileName, model) {
+export async function consolidateViaSubagent(memoryRoot, diffFileName, model, signal) {
     const agent = "memorize";
     const subId = await createSession(agent, "codex-memory-consolidate");
     let promptError;
@@ -254,7 +277,7 @@ export async function consolidateViaSubagent(memoryRoot, diffFileName, model) {
         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 });
+        await promptSession(subId, prompt, agent, { model: resolved, timeoutMs: CONSOLIDATION_TIMEOUT_MS, signal });
     }
     catch (err) {
         promptError = err;
@@ -334,8 +357,19 @@ async function deleteSession(id) {
     const input = getPluginInput();
     if (!input)
         return false;
+    const controller = new AbortController();
+    let timer;
     try {
-        const res = await input.client.session.delete({ path: { id } });
+        const res = await Promise.race([
+            input.client.session.delete({ path: { id }, signal: controller.signal }),
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`session.delete timed out after ${SUBSESSION_DELETE_TIMEOUT_MS}ms`));
+                }, SUBSESSION_DELETE_TIMEOUT_MS);
+                timer.unref?.();
+            }),
+        ]);
         if (res.error) {
             console.warn(`[opencode-codex-memory] failed to delete sub-session ${id}: ${JSON.stringify(res.error)}`);
             return false;
@@ -354,6 +388,9 @@ async function deleteSession(id) {
         console.warn(`[opencode-codex-memory] error deleting sub-session ${id}:`, err);
         return false;
     }
+    finally {
+        clearTimeout(timer);
+    }
 }
 async function sessionDeletionConfirmed(client, id) {
     const session = client.session;

package/dist/src/options.d.ts

@@ -24,6 +24,7 @@ export interface PluginOptionsState {
     codex_interop: CodexInteropOptions;
 }
 export declare const pluginOptions: PluginOptionsState;
+export declare function resetPluginOptions(): void;
 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). */

package/dist/src/options.js

@@ -1,4 +1,4 @@
-export const pluginOptions = {
+const DEFAULT_PLUGIN_OPTIONS = {
     generate_memories: true,
     use_memories: true,
     dedicated_tools: true,
@@ -10,6 +10,17 @@ export const pluginOptions = {
     min_rollout_idle_hours: 6,
     codex_interop: { import: false, export: false },
 };
+export const pluginOptions = {
+    ...DEFAULT_PLUGIN_OPTIONS,
+    codex_interop: { ...DEFAULT_PLUGIN_OPTIONS.codex_interop },
+};
+export function resetPluginOptions() {
+    delete pluginOptions.extract_model;
+    delete pluginOptions.consolidation_model;
+    Object.assign(pluginOptions, DEFAULT_PLUGIN_OPTIONS, {
+        codex_interop: { ...DEFAULT_PLUGIN_OPTIONS.codex_interop },
+    });
+}
 /**
  * Config problems noticed while applying plugin options (unknown keys,
  * malformed values). The plugin never hard-fails on bad options — codex uses

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

@@ -1,3 +1,4 @@
+import fs from "fs";
 /**
  * Safe path resolution that cannot escape the memory root, mirroring codex
  * ext/memories/src/local/path.rs + local.rs resolve_scoped_path:
@@ -19,3 +20,17 @@ export declare function assertMemoryRootSafe(): string;
 export declare function safeResolveMemoryPath(rel: string): string;
 /** Resolve a relative path under an arbitrary trusted root without following symlinks. */
 export declare function safeResolveUnderRoot(root: string, rel: string): string;
+/**
+ * Opens a regular file without following its final path component. The lstat
+ * after open is a fallback for platforms without O_NOFOLLOW and also verifies
+ * that a path-swap race did not give us a different inode.
+ */
+export declare function withRegularFileNoFollow<T>(file: string, flags: number, fn: (fd: number, stat: fs.Stats) => T): T;
+export declare function readRegularFileNoFollow(file: string): {
+    content: Buffer;
+    stat: fs.Stats;
+};
+/** Overwrite or exclusively create a regular file without following symlinks. */
+export declare function writeRegularFileNoFollow(file: string, content: string | Uint8Array, options?: {
+    exclusive?: boolean;
+}): void;

package/dist/src/path-guard.js

@@ -81,3 +81,83 @@ export function safeResolveUnderRoot(root, rel) {
     }
     return current;
 }
+function sameFile(a, b) {
+    return a.dev === b.dev && a.ino === b.ino;
+}
+/**
+ * Opens a regular file without following its final path component. The lstat
+ * after open is a fallback for platforms without O_NOFOLLOW and also verifies
+ * that a path-swap race did not give us a different inode.
+ */
+export function withRegularFileNoFollow(file, flags, fn) {
+    const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+    const nonBlock = fs.constants.O_NONBLOCK ?? 0;
+    let fd;
+    try {
+        fd = fs.openSync(file, flags | noFollow | nonBlock);
+    }
+    catch (err) {
+        if (err.code === "ELOOP") {
+            throw new Error(`symlinks are not allowed in the memory workspace: ${file}`);
+        }
+        throw err;
+    }
+    try {
+        const opened = fs.fstatSync(fd);
+        const current = fs.lstatSync(file);
+        if (current.isSymbolicLink() || !current.isFile() || !opened.isFile() || !sameFile(opened, current)) {
+            throw new Error(`refusing non-regular or replaced file: ${file}`);
+        }
+        return fn(fd, opened);
+    }
+    finally {
+        fs.closeSync(fd);
+    }
+}
+export function readRegularFileNoFollow(file) {
+    return withRegularFileNoFollow(file, fs.constants.O_RDONLY, (fd, stat) => ({
+        content: fs.readFileSync(fd),
+        stat,
+    }));
+}
+/** Overwrite or exclusively create a regular file without following symlinks. */
+export function writeRegularFileNoFollow(file, content, options = {}) {
+    const noFollow = fs.constants.O_NOFOLLOW ?? 0;
+    const create = () => {
+        const fd = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | noFollow, 0o666);
+        try {
+            const opened = fs.fstatSync(fd);
+            const current = fs.lstatSync(file);
+            if (!opened.isFile() || !current.isFile() || !sameFile(opened, current)) {
+                throw new Error(`refusing non-regular or replaced file: ${file}`);
+            }
+            fs.writeFileSync(fd, content);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+    };
+    if (options.exclusive) {
+        create();
+        return;
+    }
+    let current;
+    try {
+        current = fs.lstatSync(file);
+    }
+    catch (err) {
+        if (err.code === "ENOENT") {
+            create();
+            return;
+        }
+        throw err;
+    }
+    if (current.isSymbolicLink() || !current.isFile()) {
+        throw new Error(`refusing to overwrite non-regular file: ${file}`);
+    }
+    withRegularFileNoFollow(file, fs.constants.O_WRONLY, (fd) => {
+        // Do not truncate until the descriptor and current path are verified.
+        fs.ftruncateSync(fd, 0);
+        fs.writeFileSync(fd, content);
+    });
+}

package/dist/src/phase1.d.ts

@@ -1,4 +1,5 @@
 import { MemoryStore } from "./store.js";
+import { checkRateLimit } from "./ratelimit.js";
 export interface Phase1Options {
     maxAgeDays: number;
     minIdleHours: number;
@@ -8,5 +9,5 @@ export interface Phase1Options {
     extractModel?: string;
 }
 export declare const DEFAULT_PHASE1_OPTIONS: Phase1Options;
-export declare function runPhase1(store: MemoryStore, opts?: Phase1Options): Promise<void>;
+export declare function runPhase1(store: MemoryStore, opts?: Phase1Options, rateLimitCheck?: typeof checkRateLimit): Promise<void>;
 export declare function buildTranscript(sessionId: string): Promise<string>;

package/dist/src/phase1.js

@@ -19,9 +19,9 @@ const TRANSCRIPT_MAX_CHARS = 600_000;
 // 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) {
+export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS, rateLimitCheck = checkRateLimit) {
     store.pruneStage1Outputs(opts.maxUnusedDays ?? 30);
-    const rl = await checkRateLimit("phase1");
+    const rl = await rateLimitCheck("phase1");
     if (!rl.ok) {
         console.warn("[opencode-codex-memory] skipping phase1 due to rate limit:", rl.reason);
         return;
@@ -40,6 +40,12 @@ export async function runPhase1(store, opts = DEFAULT_PHASE1_OPTIONS) {
             const sourceUpdatedAt = session?.updated_at ?? Date.now();
             const transcript = await buildTranscript(sid);
             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
+                // permanently forgetting memory because of a transient host glitch.
+                if (store.hasStage1Output(sid)) {
+                    throw new Error(`empty transcript for previously extracted session ${sid}`);
+                }
                 store.markStage1SucceededNoOutput(sid, claim.ownershipToken, sourceUpdatedAt);
                 return;
             }

package/dist/src/phase2.d.ts

@@ -7,6 +7,8 @@ export interface Phase2Options {
     extensionRetentionDays: number;
     consolidationModel?: string;
     codexInterop?: CodexInteropOptions;
+    /** Override the 90s heartbeat interval (tests / advanced). */
+    heartbeatIntervalMs?: number;
 }
 export declare const DEFAULT_PHASE2_OPTIONS: Phase2Options;
 /** True while THIS process runs a consolidation (memory_reset refuses then). */

package/dist/src/phase2.js

@@ -89,21 +89,40 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
             }
             writeWorkspaceDiff(diff);
             let heartbeatLost = false;
-            const heartbeat = setInterval(() => {
+            let heartbeatFailure = "ownership lost";
+            const consolidationAbort = new AbortController();
+            const heartbeatOnce = () => {
+                if (heartbeatLost)
+                    return false;
                 try {
                     if (!store.heartbeatPhase2Job(claim.ownershipToken)) {
                         heartbeatLost = true;
+                        consolidationAbort.abort();
+                        return false;
                     }
                 }
                 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);
+                    // Codex stops the consolidation agent on heartbeat Ok(false) OR Err.
+                    // Fail closed: without a refreshed lease, another process may reclaim
+                    // the job while this helper still has live write access.
+                    heartbeatLost = true;
+                    heartbeatFailure = err;
+                    consolidationAbort.abort();
+                    return false;
                 }
-            }, 90_000);
+                return true;
+            };
+            // Workspace preparation can itself be slow. Confirm ownership before
+            // granting a new helper write access, then keep the lease alive while it
+            // runs. This also mirrors tokio::time::interval's immediate first tick.
+            if (!heartbeatOnce()) {
+                store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
+                return { status: "heartbeat_lost" };
+            }
+            const heartbeat = setInterval(heartbeatOnce, opts.heartbeatIntervalMs ?? 90_000);
             try {
-                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel);
+                await consolidateViaSubagent(memoryRoot(), DIFF_ARTIFACT, opts.consolidationModel, consolidationAbort.signal);
             }
             catch (err) {
                 // codex phase2.rs: when the consolidation agent's shutdown fails, keep
@@ -114,6 +133,10 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
                     console.warn(`[opencode-codex-memory] ${err.message}; holding the phase2 lease until it expires`);
                     return { status: "shutdown_failed" };
                 }
+                if (heartbeatLost) {
+                    store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
+                    return { status: "heartbeat_lost" };
+                }
                 throw err;
             }
             finally {
@@ -126,7 +149,7 @@ export async function runPhase2(store, opts = DEFAULT_PHASE2_OPTIONS, rateLimitC
             // heartbeat is token+status guarded, so it fails once ownership is lost;
             // markPhase2Failed is equally guarded and becomes a no-op then.
             if (heartbeatLost || !store.heartbeatPhase2Job(claim.ownershipToken)) {
-                store.markPhase2Failed(claim.ownershipToken, "ownership lost");
+                store.markPhase2Failed(claim.ownershipToken, heartbeatFailure);
                 return { status: "heartbeat_lost" };
             }
             // codex failed_invalid_artifacts: do not reset baseline on bad output so

package/dist/src/source.js

@@ -1,7 +1,7 @@
 import fs from "fs";
 import path from "path";
 import { memoryRoot } from "./paths.js";
-import { assertMemoryRootSafe, safeResolveMemoryPath } from "./path-guard.js";
+import { assertMemoryRootSafe, safeResolveMemoryPath, withRegularFileNoFollow } from "./path-guard.js";
 import { truncateToTokens } from "./token.js";
 import { fillTemplate } from "./llm.js";
 const MEMORY_SUMMARY_TOKEN_LIMIT = 2500;
@@ -31,36 +31,28 @@ function readTemplate() {
     return fs.readFileSync(templatePath, "utf8");
 }
 function readMemorySummary() {
-    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 summaryPath = safeResolveMemoryPath("memory_summary.md");
+        return withRegularFileNoFollow(summaryPath, fs.constants.O_RDONLY, (fd, stat) => {
+            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;
+        });
     }
     catch {
         return null;
     }
-    finally {
-        if (fd !== undefined)
-            fs.closeSync(fd);
-    }
 }
 export function invalidateCache() {
     cached = null;

package/dist/src/store.d.ts

@@ -44,6 +44,7 @@ export declare class MemoryStore {
     private db;
     constructor(db?: Database);
     stage1Outputs(): Stage1Output[];
+    hasStage1Output(sessionId: string): boolean;
     /**
      * Deletes stale rows; snapshots consumed by the last successful Phase 2 are
      * protected. Stalest-first, capped per run (codex PRUNE_BATCH_SIZE).
@@ -69,7 +70,22 @@ 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. */
+    /**
+     * Phase-2 job snapshot for memory_inspect. Always returns the global job row
+     * when it exists (including failed/running), so diagnostics are not limited
+     * to clean successes. `success_finished_at` is set only for a clean success
+     * (never a failure timestamp); `last_success_watermark` follows codex
+     * (preserved across later attempts; zero only counts while clean).
+     */
+    phase2JobSnapshot(): {
+        status: string;
+        last_error: string | null;
+        finished_at: number | null;
+        retry_at: number | null;
+        success_finished_at: number | null;
+        last_success_watermark: number | null;
+    } | null;
+    /** Last recorded phase-2 success info. Null when phase 2 never succeeded. */
     phase2LastSuccess(): {
         finished_at: number | null;
         last_success_watermark: number | null;

package/dist/src/store.js

@@ -37,6 +37,11 @@ export class MemoryStore {
             .prepare("SELECT * FROM memory_stage1_outputs ORDER BY source_updated_at DESC")
             .all();
     }
+    hasStage1Output(sessionId) {
+        return this.db
+            .prepare("SELECT 1 FROM memory_stage1_outputs WHERE session_id = ?")
+            .get(sessionId) !== null;
+    }
     /**
      * Deletes stale rows; snapshots consumed by the last successful Phase 2 are
      * protected. Stalest-first, capped per run (codex PRUNE_BATCH_SIZE).
@@ -306,15 +311,51 @@ export class MemoryStore {
                 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() {
+    /**
+     * Phase-2 job snapshot for memory_inspect. Always returns the global job row
+     * when it exists (including failed/running), so diagnostics are not limited
+     * to clean successes. `success_finished_at` is set only for a clean success
+     * (never a failure timestamp); `last_success_watermark` follows codex
+     * (preserved across later attempts; zero only counts while clean).
+     */
+    phase2JobSnapshot() {
         const row = this.db
-            .prepare(`SELECT finished_at, last_success_watermark FROM memory_jobs
+            .prepare(`SELECT status, finished_at, last_error, retry_at, last_success_watermark FROM memory_jobs
          WHERE kind='memory_consolidate_global' AND job_key='global'`)
             .get();
-        if (!row || !row.last_success_watermark)
+        if (!row)
+            return null;
+        const cleanSuccess = row.last_error === null &&
+            row.finished_at !== null &&
+            (row.status === "done" || row.status === "pending");
+        // Codex initializes pending global jobs with watermark 0, so zero proves a
+        // success only while the row itself is a clean completed attempt.
+        const watermark = row.last_success_watermark === null
+            ? null
+            : row.last_success_watermark === 0 && !cleanSuccess
+                ? null
+                : row.last_success_watermark;
+        return {
+            status: row.status,
+            last_error: row.last_error,
+            finished_at: row.finished_at,
+            retry_at: row.retry_at,
+            // Codex preserves last_success_watermark across later attempts, while the
+            // job finished_at describes only the latest attempt. Never label a failure
+            // timestamp as a success finish time.
+            success_finished_at: cleanSuccess ? row.finished_at : null,
+            last_success_watermark: watermark,
+        };
+    }
+    /** Last recorded phase-2 success info. Null when phase 2 never succeeded. */
+    phase2LastSuccess() {
+        const snap = this.phase2JobSnapshot();
+        if (!snap || snap.last_success_watermark === null)
             return null;
-        return row;
+        return {
+            finished_at: snap.success_finished_at,
+            last_success_watermark: snap.last_success_watermark,
+        };
     }
     markPhase2Failed(ownershipToken, error) {
         const message = failureMessage(error);

package/dist/src/workspace.js

@@ -2,7 +2,7 @@ import { createHash } from "crypto";
 import fs from "fs";
 import path from "path";
 import { memoryRoot } from "./paths.js";
-import { assertMemoryRootSafe, safeResolveMemoryPath } from "./path-guard.js";
+import { assertMemoryRootSafe, readRegularFileNoFollow, safeResolveMemoryPath, writeRegularFileNoFollow, } from "./path-guard.js";
 import { DIFF_ARTIFACT } from "./git-baseline.js";
 const RAW_MEMORIES_FILE = "raw_memories.md";
 const ROLLOUT_DIR = "rollout_summaries";
@@ -38,13 +38,13 @@ export function ensureLayout() {
     }
     const memoryMd = safeResolveMemoryPath("MEMORY.md");
     if (!fs.existsSync(memoryMd))
-        fs.writeFileSync(memoryMd, "# MEMORY.md\n\n_Searchable index of memories._\n", { flag: "w" });
+        writeRegularFileNoFollow(memoryMd, "# MEMORY.md\n\n_Searchable index of memories._\n");
     const summary = safeResolveMemoryPath("memory_summary.md");
     if (!fs.existsSync(summary))
-        fs.writeFileSync(summary, "", { flag: "w" });
+        writeRegularFileNoFollow(summary, "");
     const adhocInstructions = safeResolveMemoryPath(path.join(EXTENSIONS_DIR, "ad_hoc", "instructions.md"));
     if (!fs.existsSync(adhocInstructions))
-        fs.writeFileSync(adhocInstructions, ADHOC_INSTRUCTIONS, { flag: "w" });
+        writeRegularFileNoFollow(adhocInstructions, ADHOC_INSTRUCTIONS);
 }
 /**
  * Mirrors codex `validate_consolidation_artifacts` (workspace.rs): after
@@ -68,7 +68,7 @@ export function validateConsolidationArtifacts(root = memoryRoot()) {
         if (!fs.lstatSync(summaryPath).isFile()) {
             return { ok: false, reason: `memory summary artifact is not a file: ${summaryPath}` };
         }
-        summary = fs.readFileSync(summaryPath, "utf8");
+        summary = readRegularFileNoFollow(summaryPath).content.toString("utf8");
     }
     catch {
         return { ok: false, reason: `missing memory summary artifact: ${summaryPath}` };
@@ -119,7 +119,7 @@ export function rebuildRawMemories(outputs) {
             content += "\n\n";
         }
     }
-    fs.writeFileSync(safeResolveMemoryPath(RAW_MEMORIES_FILE), content, { flag: "w" });
+    writeRegularFileNoFollow(safeResolveMemoryPath(RAW_MEMORIES_FILE), content);
     return content;
 }
 export function writeRolloutSummaries(outputs) {
@@ -142,7 +142,7 @@ export function writeRolloutSummaries(outputs) {
             `usage_count: ${o.usage_count}\n\n` +
             o.rollout_summary +
             "\n";
-        fs.writeFileSync(file, body, { flag: "w" });
+        writeRegularFileNoFollow(file, body);
     }
 }
 // Resource filenames start with an ISO-like timestamp: 2026-07-03T05-11-22_slug.md
@@ -229,6 +229,6 @@ export function writeWorkspaceDiff(diff) {
         rendered += "\n## Diff\n\n```diff\n" + body + (body.endsWith("\n") ? "" : "\n") + "```\n";
     }
     const file = safeResolveMemoryPath(DIFF_ARTIFACT);
-    fs.writeFileSync(file, rendered, { flag: "w" });
+    writeRegularFileNoFollow(file, rendered);
     return file;
 }

package/dist/tools/control.js

@@ -5,7 +5,7 @@ import { memoryRoot, memorySummaryPath } from "../src/paths.js";
 import { MemoryStore } from "../src/store.js";
 import { invalidateCache } from "../src/source.js";
 import { estimateTokens } from "../src/token.js";
-import { assertMemoryRootSafe } from "../src/path-guard.js";
+import { assertMemoryRootSafe, readRegularFileNoFollow } from "../src/path-guard.js";
 import { isPhase2InFlight } from "../src/phase2.js";
 import { pluginOptions, getConfigWarnings } from "../src/options.js";
 import { resolveCodexInterop } from "../src/codex-interop.js";
@@ -150,11 +150,22 @@ export const memory_reset = tool({
         }
     },
 });
+function fmtUnixSec(sec) {
+    return sec ? new Date(sec * 1000).toISOString() : "none";
+}
+function fmtWatermarkMs(ms) {
+    if (ms === 0)
+        return "0 (no consumed inputs)";
+    if (ms === null || ms === undefined)
+        return "none";
+    return new Date(ms).toISOString();
+}
 export const memory_inspect = tool({
-    description: "Inspect the current memory state. Returns: stage1_outputs count, last Phase 2 success watermark, " +
-        "memory_summary token estimate, a listing of the memories directory, the effective plugin options, " +
-        "and any configuration warnings (unknown/malformed options). Use it to verify the plugin " +
-        "configuration took effect. Read-only.",
+    description: "Inspect the current memory state. Returns: stage1_outputs count, Phase 2 job status " +
+        "(including last error / retry time when failed), last Phase 2 success watermark, " +
+        "memory_summary token estimate (on-disk; injection caps at ~2500), a listing of the " +
+        "memories directory, the effective plugin options, and any configuration warnings " +
+        "(unknown/malformed options). Use it to verify the plugin configuration took effect. Read-only.",
     args: {},
     async execute() {
         try {
@@ -166,21 +177,35 @@ export const memory_inspect = tool({
             let summaryChars = 0;
             let summaryTokens = 0;
             if (fs.existsSync(summaryPath)) {
-                const text = fs.readFileSync(summaryPath, "utf8");
+                const text = readRegularFileNoFollow(summaryPath).content.toString("utf8");
                 summaryChars = text.length;
                 summaryTokens = estimateTokens(text);
             }
             const listing = listMemoriesDir();
-            // The tool description promises the last Phase 2 success watermark.
-            const phase2 = store.phase2LastSuccess();
-            const watermark = phase2?.last_success_watermark ? new Date(phase2.last_success_watermark).toISOString() : "none";
-            const finishedAt = phase2?.finished_at ? new Date(phase2.finished_at * 1000).toISOString() : "none";
+            const phase2 = store.phase2JobSnapshot();
+            const phase2Lines = phase2
+                ? [
+                    `phase2_status: ${phase2.status}`,
+                    `phase2_last_error: ${phase2.last_error ?? "none"}`,
+                    `phase2_retry_at: ${fmtUnixSec(phase2.retry_at)}`,
+                    `phase2_last_attempt_finished_at: ${fmtUnixSec(phase2.finished_at)}`,
+                    `phase2_last_success_watermark: ${fmtWatermarkMs(phase2.last_success_watermark)}`,
+                    // Clean-success finish only — never a failure timestamp.
+                    `phase2_last_success_finished_at: ${fmtUnixSec(phase2.success_finished_at)}`,
+                ]
+                : [
+                    "phase2_status: none",
+                    "phase2_last_error: none",
+                    "phase2_retry_at: none",
+                    "phase2_last_attempt_finished_at: none",
+                    "phase2_last_success_watermark: none",
+                    "phase2_last_success_finished_at: none",
+                ];
             const out = [
                 `stage1_outputs: ${outputs.length}`,
-                `phase2_last_success_watermark: ${watermark}`,
-                `phase2_last_finished_at: ${finishedAt}`,
+                ...phase2Lines,
                 `memory_summary_chars: ${summaryChars}`,
-                `memory_summary_tokens_est: ${summaryTokens}`,
+                `memory_summary_tokens_est: ${summaryTokens} (on disk; injection caps at ~2500)`,
                 `memories_dir_entries: ${listing.length}`,
                 "",
                 ...renderEffectiveConfig(),
@@ -192,8 +217,14 @@ export const memory_inspect = tool({
                 output: out,
                 metadata: {
                     stage1_count: outputs.length,
+                    phase2_status: phase2?.status ?? null,
+                    phase2_last_error: phase2?.last_error ?? null,
+                    phase2_retry_at: phase2?.retry_at ?? null,
+                    phase2_last_attempt_finished_at: phase2?.finished_at ?? null,
                     phase2_last_success_watermark: phase2?.last_success_watermark ?? null,
-                    phase2_last_finished_at: phase2?.finished_at ?? null,
+                    phase2_last_success_finished_at: phase2?.success_finished_at ?? null,
+                    // Back-compat aliases used by earlier inspect consumers.
+                    phase2_last_finished_at: phase2?.success_finished_at ?? null,
                     summary_chars: summaryChars,
                     summary_tokens_est: summaryTokens,
                     files: listing,
@@ -208,7 +239,7 @@ export const memory_inspect = tool({
     },
 });
 export const memory_mode = tool({
-    description: "Set the memory mode for the current session. 'enabled' allows Phase 1 extraction. " +
+    description: "Set the memory mode for the target session (current session by default). 'enabled' allows Phase 1 extraction. " +
         "'disabled' excludes this session from extraction. 'polluted' marks it as having external context " +
         "(websearch/webfetch) that should not be trusted for memory.",
     args: {

package/dist/tools/memory.js

@@ -1,6 +1,6 @@
 import fs from "fs";
 import path from "path";
-import { safeResolveMemoryPath, assertMemoryRootSafe } from "../src/path-guard.js";
+import { safeResolveMemoryPath, assertMemoryRootSafe, readRegularFileNoFollow, writeRegularFileNoFollow, } from "../src/path-guard.js";
 import { tool } from "@opencode-ai/plugin";
 const MAX_READ_BYTES = 256 * 1024;
 export const memory_read = tool({
@@ -18,7 +18,7 @@ export const memory_read = tool({
             if (!fs.existsSync(fullPath)) {
                 return { output: `Not found: ${args.path}` };
             }
-            const stat = fs.statSync(fullPath);
+            const stat = fs.lstatSync(fullPath);
             if (stat.isDirectory()) {
                 const entries = fs.readdirSync(fullPath);
                 return {
@@ -29,7 +29,7 @@ export const memory_read = tool({
             // Read the whole file and apply the line window FIRST; the byte cap
             // applies to the WINDOWED output. Capping the raw read used to make
             // lines beyond the first 256 KiB unreachable regardless of line_offset.
-            const text = fs.readFileSync(fullPath, "utf8");
+            const text = readRegularFileNoFollow(fullPath).content.toString("utf8");
             // Line windowing mirrors codex memories/read: 1-indexed offset, bounded
             // line count, and the start line reported so file:line citations work.
             const startLine = args.line_offset ?? 1;
@@ -303,7 +303,7 @@ export const memory_search = tool({
                 const start = safeResolveMemoryPath(args.path);
                 let st;
                 try {
-                    st = fs.statSync(start);
+                    st = fs.lstatSync(start);
                 }
                 catch {
                     return { output: `Not found: ${args.path}` };
@@ -326,7 +326,7 @@ export const memory_search = tool({
                 const listing = files.slice(0, args.max_results).map((f) => {
                     let content = "";
                     try {
-                        content = fs.readFileSync(f.abs, "utf8");
+                        content = readRegularFileNoFollow(f.abs).content.toString("utf8");
                     }
                     catch {
                     }
@@ -350,7 +350,7 @@ export const memory_search = tool({
             for (const f of files) {
                 let content;
                 try {
-                    content = fs.readFileSync(f.abs, "utf8");
+                    content = readRegularFileNoFollow(f.abs).content.toString("utf8");
                 }
                 catch {
                     continue;
@@ -425,7 +425,7 @@ export const memory_add_note = tool({
             let file = safeResolveMemoryPath(path.join(NOTES_DIR, `${stem}.md`));
             for (let i = 2;; i++) {
                 try {
-                    fs.writeFileSync(file, header + args.note + "\n", { flag: "wx" });
+                    writeRegularFileNoFollow(file, header + args.note + "\n", { exclusive: true });
                     break;
                 }
                 catch (err) {

package/package.json

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