opencode-codex-memory 0.5.0 → 0.6.1

package/README.md

@@ -52,7 +52,7 @@ If you want the mental model before the details, jump to
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.5.0"]
+  "plugin": ["opencode-codex-memory@0.6.1"]
 }
 ```
 
@@ -191,6 +191,20 @@ them — it's yours. (The `memories/` folder also holds a few working files and
 an internal `.git/` the plugin uses for change tracking; `memory_reset` wipes
 those too.)
 
+### Backup and restore
+
+Back up the whole OpenCode data directory while OpenCode is stopped. The
+SQLite database and `memories/` workspace are a pair: restoring only one can
+leave job state, Git baseline, and memory files out of sync. Include hidden
+files, especially `memories/.git/`, and SQLite sidecars such as `memory.db-wal`
+or `memory.db-shm` when present.
+
+The directory is `$XDG_DATA_HOME/opencode` when `XDG_DATA_HOME` is set,
+otherwise `~/.local/share/opencode`. Copy that whole directory to a dated
+backup location. To restore, stop OpenCode, replace the current `opencode/`
+data directory with the backup copy, then start OpenCode again. Do not restore
+while OpenCode is running or copy only `memory.db` or only `memories/`.
+
 ## Privacy & safety
 
 - **Local only.** There is no remote storage option to enable, by accident or
@@ -240,7 +254,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.5.0", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.6.1", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -302,7 +316,7 @@ Off by default; no changes to Codex's own config are required.
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.5.0",
+      "opencode-codex-memory@0.6.1",
       { "codex_interop": { "import": true, "export": true } }
     ]
   ]
@@ -359,7 +373,7 @@ from the project memories Claude already keeps on your machine. **One-way only**
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.5.0", { "claude_import": { "enabled": true } }]
+    ["opencode-codex-memory@0.6.1", { "claude_import": { "enabled": true } }]
   ]
 }
 ```
@@ -386,7 +400,7 @@ Claude names each project with an opaque id (a folder under
 {
   "plugin": [
     [
-      "opencode-codex-memory@0.5.0",
+      "opencode-codex-memory@0.6.1",
       {
         "claude_import": {
           "enabled": true,
@@ -471,10 +485,12 @@ mirrors that decision rather than layering scoping back on top.
 When memory does not seem to build, ask the agent to run **`memory_inspect`**.
 It reports:
 
-- stage-1 job counts and recent extraction errors
+- stage-1 job counts, failure classes (`backoff` / `provider_capacity` / `other_exhausted`), and recent extraction errors
+- active provider/model quota backoffs and their retry times
 - phase-2 status / last error / cooldown
 - last session-discovery outcome
 - effective options (after clamping) and config warnings
+- effective memory-agent health, including user overrides and required permissions
 - a short eligibility reminder (`min_rollout_idle_hours`, default **6h**)
 
 Common causes:
@@ -485,6 +501,7 @@ Common causes:
 | Discovery failed | Host API/`experimental/session` unavailable; inspect shows the error. Retry after restarting OpenCode. |
 | Pin stuck on old version | OpenCode freezes bare package specs; pin an explicit version and bump it (see Install). |
 | Consolidation never runs | Check `phase2_status` and `phase2_last_error` in inspect; failed artifacts keep the workspace diff for the next run. |
+| `stage1_error` mentions usage/rate limit | Temporary provider quota. Inspect shows `provider_capacity` or `backoff`; those jobs retry after about an hour once quota returns. Permanent holes are `other_exhausted`. |
 
 Install target: this package runs **inside OpenCode** (Bun). You do not need to
 install it as a standalone Node app; OpenCode resolves the plugin into its own

package/dist/src/agent-health.d.ts

@@ -0,0 +1,21 @@
+declare const AGENT_NAMES: readonly ["memorize", "memorize-extract"];
+type AgentName = (typeof AGENT_NAMES)[number];
+export interface AgentHealthEntry {
+    source: "shipped" | "user_override" | "missing";
+    healthy: boolean;
+    issues: string[];
+}
+export interface AgentHealthSnapshot {
+    observed: boolean;
+    generationEnabled: boolean | null;
+    agents: Record<AgentName, AgentHealthEntry>;
+}
+export declare function loadBundledAgentDefinitions(): Record<string, unknown>;
+/** Record the effective agent config after the plugin config hook runs. */
+export declare function recordAgentConfig(config: {
+    agent?: Record<string, unknown>;
+}, generationEnabled: boolean, shipped: Record<string, unknown>): void;
+export declare function getAgentHealth(): AgentHealthSnapshot;
+/** Test seam and boot boundary. */
+export declare function resetAgentHealth(): void;
+export {};

package/dist/src/agent-health.js

@@ -0,0 +1,133 @@
+import fs from "fs";
+import path from "path";
+import { memoryRoot } from "./paths.js";
+const AGENT_NAMES = ["memorize", "memorize-extract"];
+const REQUIRED_ALLOWS = {
+    memorize: ["read", "edit", "write", "glob", "grep"],
+    "memorize-extract": ["StructuredOutput"],
+};
+const SAFE_ALLOWS = {
+    memorize: new Set(["read", "edit", "write", "glob", "grep", "external_directory"]),
+    "memorize-extract": new Set(["StructuredOutput"]),
+};
+const initialEntry = () => ({ source: "missing", healthy: false, issues: ["config hook has not run"] });
+let snapshot = {
+    observed: false,
+    generationEnabled: null,
+    agents: {
+        memorize: initialEntry(),
+        "memorize-extract": initialEntry(),
+    },
+};
+export function loadBundledAgentDefinitions() {
+    const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
+    return JSON.parse(raw).agent ?? {};
+}
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value) ? value : null;
+}
+function hasNonDenyAction(value) {
+    const rules = asRecord(value);
+    return rules ? Object.values(rules).some((action) => action !== "deny") : value !== "deny";
+}
+/** Structural compare — config reload re-parses shipped defs into new objects. */
+function definitionsEqual(a, b) {
+    try {
+        return JSON.stringify(a) === JSON.stringify(b);
+    }
+    catch {
+        return false;
+    }
+}
+function permissionIssues(name, definition) {
+    const issues = [];
+    const record = asRecord(definition);
+    if (record?.mode !== "subagent")
+        issues.push("agent mode must be 'subagent'");
+    const permission = asRecord(record?.permission);
+    if (!permission) {
+        issues.push("missing permission map");
+        return issues;
+    }
+    const keys = Object.keys(permission);
+    if (keys[0] !== "*")
+        issues.push("permission wildcard '*' must be the first rule");
+    if (permission["*"] !== "deny")
+        issues.push("permission wildcard '*' must be 'deny'");
+    for (const toolName of REQUIRED_ALLOWS[name]) {
+        if (permission[toolName] !== "allow") {
+            issues.push(`required permission '${toolName}: allow' is missing`);
+        }
+    }
+    for (const [toolName, value] of Object.entries(permission)) {
+        if (toolName === "*")
+            continue;
+        if (!SAFE_ALLOWS[name].has(toolName)) {
+            if (hasNonDenyAction(value))
+                issues.push(`unexpected permission '${toolName}' must be denied`);
+        }
+    }
+    if (name === "memorize") {
+        const external = asRecord(permission.external_directory);
+        const expectedPath = path.join(memoryRoot(), "*");
+        if (external?.[expectedPath] !== "allow") {
+            issues.push(`consolidator must allow external_directory '${expectedPath}'`);
+        }
+        if (external) {
+            for (const [grantedPath, action] of Object.entries(external)) {
+                if (grantedPath === expectedPath)
+                    continue;
+                if (hasNonDenyAction(action)) {
+                    issues.push(`consolidator must deny extra external_directory '${grantedPath}'`);
+                }
+            }
+        }
+    }
+    else if (permission.external_directory !== undefined) {
+        issues.push("extractor must not have external_directory access");
+    }
+    return issues;
+}
+function inspectAgent(name, definition, source) {
+    const issues = permissionIssues(name, definition);
+    return { source, healthy: issues.length === 0, issues };
+}
+/** Record the effective agent config after the plugin config hook runs. */
+export function recordAgentConfig(config, generationEnabled, shipped) {
+    const configured = asRecord(config.agent);
+    const agents = {};
+    for (const name of AGENT_NAMES) {
+        const definition = configured?.[name];
+        const source = definition === undefined
+            ? "missing"
+            : definitionsEqual(shipped[name], definition)
+                ? "shipped"
+                : "user_override";
+        agents[name] = inspectAgent(name, definition, source);
+        if (!generationEnabled && definition === undefined) {
+            agents[name] = { source: "missing", healthy: true, issues: ["generation disabled; agent not injected"] };
+        }
+    }
+    snapshot = { observed: true, generationEnabled, agents };
+}
+export function getAgentHealth() {
+    return {
+        observed: snapshot.observed,
+        generationEnabled: snapshot.generationEnabled,
+        agents: {
+            memorize: { ...snapshot.agents.memorize, issues: [...snapshot.agents.memorize.issues] },
+            "memorize-extract": { ...snapshot.agents["memorize-extract"], issues: [...snapshot.agents["memorize-extract"].issues] },
+        },
+    };
+}
+/** Test seam and boot boundary. */
+export function resetAgentHealth() {
+    snapshot = {
+        observed: false,
+        generationEnabled: null,
+        agents: {
+            memorize: initialEntry(),
+            "memorize-extract": initialEntry(),
+        },
+    };
+}

package/dist/src/capture.js

@@ -1,22 +1,8 @@
 import { SCAN_LIMIT } from "./store.js";
 import { getPluginInput } from "./llm.js";
 import { recordDiscoveryStatus } from "./diagnostics.js";
-import { hostPartType, hostSessionMessages, pluginHttpGet } from "./host-client.js";
+import { hostListSessionsGlobal, hostPartType, hostSessionMessages, pluginHttpGet, withHostTimeout } from "./host-client.js";
 const API_TIMEOUT_MS = 60_000;
-async function withTimeout(promise, ms, label) {
-    let timer;
-    try {
-        return await Promise.race([
-            promise,
-            new Promise((_, reject) => {
-                timer = setTimeout(() => reject(new Error(`${label} timed out after ${ms}ms`)), ms);
-            }),
-        ]);
-    }
-    finally {
-        clearTimeout(timer);
-    }
-}
 /**
  * Global session discovery through the official API:
  * `GET /experimental/session?roots=true` (Session.listGlobal) — one call across
@@ -41,22 +27,14 @@ export async function listRecentSessions(limit = SCAN_LIMIT) {
         now - discoveryCache.at < DISCOVERY_CACHE_MS) {
         return discoveryCache.rows.slice(0, limit);
     }
-    const get = pluginHttpGet(getPluginInput()?.client);
-    if (!get) {
+    const client = getPluginInput()?.client;
+    if (!pluginHttpGet(client)) {
         recordDiscoveryStatus({ ok: false, count: 0, error: "plugin HTTP client unavailable" });
         return [];
     }
     try {
-        // Opencode's SDK client injects `directory` from x-opencode-directory on
-        // every GET (sdk client rewrite). The experimental session handler treats
-        // any present directory query as "filter to this instance's project",
-        // which would hide every other project's idle sessions — memory is global.
-        // Pass an empty directory so rewrite does not re-inject, and the handler
-        // sees a falsy value → listGlobal without a directory filter.
-        const res = await withTimeout(get({
-            url: "/experimental/session",
-            query: { roots: true, limit, directory: "" },
-        }), API_TIMEOUT_MS, "experimental.session.list");
+        const controller = new AbortController();
+        const res = await withHostTimeout(hostListSessionsGlobal(client, { limit, signal: controller.signal }), API_TIMEOUT_MS, "experimental.session.list", controller);
         if (!res || res.error || !Array.isArray(res.data)) {
             throw new Error(`experimental.session.list failed: ${JSON.stringify(res?.error ?? {})}`);
         }
@@ -89,7 +67,8 @@ export async function listRecentSessions(limit = SCAN_LIMIT) {
 }
 /** Official transcript surface: GET /session/{id}/message via the plugin's authenticated client. */
 async function fetchMessagesViaApi(sessionId) {
-    const res = await withTimeout(hostSessionMessages(getPluginInput()?.client, sessionId), API_TIMEOUT_MS, "session.messages");
+    const controller = new AbortController();
+    const res = await withHostTimeout(hostSessionMessages(getPluginInput()?.client, sessionId, controller.signal), API_TIMEOUT_MS, "session.messages", controller);
     if (!res || res.error || !Array.isArray(res.data)) {
         throw new Error(`session.messages failed: ${JSON.stringify(res?.error ?? {})}`);
     }

package/dist/src/host-client.d.ts

@@ -6,7 +6,7 @@
  *
  * Current gaps (as of @opencode-ai/plugin ~1.18.10):
  * - session.create body: metadata + title typing
- * - session.prompt body: `format` (json_schema) omitted from PromptInput
+ * - session.prompt body: `format` (json_schema) and `variant` omitted from PromptInput
  * - AssistantMessage.info.structured: structured extraction result
  * - client._client.get: experimental routes (no experimental.* namespace on V1)
  * - mcp.status: present on host client, weakly typed in plugin package
@@ -22,6 +22,25 @@ export type HostHttpGet = (opts: {
 }>;
 /** Hey-api transport on PluginInput.client for routes the V1 surface lags on. */
 export declare function pluginHttpGet(client: PluginInput["client"] | null | undefined): HostHttpGet | null;
+/**
+ * Host-wide session list. The SDK injects `directory` from
+ * x-opencode-directory on every GET; a truthy value makes the experimental
+ * handler filter to that instance's project. Pass `directory:""` so rewrite
+ * does not re-inject and the handler sees a falsy value → listGlobal.
+ * Used by discovery and helper-session cleanup (memory is global).
+ */
+export declare function hostListSessionsGlobal(client: PluginInput["client"] | null | undefined, opts: {
+    limit: number;
+    cursor?: number;
+    search?: string;
+    signal?: AbortSignal;
+}): Promise<{
+    error?: unknown;
+    data?: unknown;
+}>;
+/** Attach a no-op catch so a raced-away promise cannot become unhandled. */
+export declare function ignoreLateRejection(promise: Promise<unknown>): void;
+export declare function withHostTimeout<T>(promise: Promise<T>, ms: number, label: string, abort?: AbortController): Promise<T>;
 export interface SessionCreateBody {
     title?: string;
     metadata?: Record<string, unknown>;
@@ -30,6 +49,7 @@ export interface SessionCreateBody {
 export declare function hostSessionCreate(client: PluginInput["client"], opts: {
     directory: string;
     body: SessionCreateBody;
+    signal?: AbortSignal;
 }): Promise<{
     error?: unknown;
     data?: {
@@ -44,6 +64,7 @@ export interface HostPromptBody {
         modelID: string;
     };
     format?: Record<string, unknown>;
+    variant?: string;
     parts: {
         type: "text";
         text: string;
@@ -64,9 +85,12 @@ export declare function hostMcpStatus(client: PluginInput["client"] | null, sign
     data?: unknown;
 } | null>;
 /** session.messages — weakly typed parts; centralize the cast. */
-export declare function hostSessionMessages(client: PluginInput["client"] | null | undefined, sessionId: string): Promise<{
+export declare function hostSessionMessages(client: PluginInput["client"] | null | undefined, sessionId: string, signal?: AbortSignal): Promise<{
     error?: unknown;
     data?: unknown;
 }>;
 export declare function hostPartType(part: unknown): string;
+export type SessionLiveness = "live" | "gone" | "unknown";
+/** Codex re-checks the live threads table; 404 = gone, anything else stays. */
+export declare function hostSessionLiveness(client: PluginInput["client"] | null | undefined, id: string, timeoutMs?: number): Promise<SessionLiveness>;
 export declare function hostSessionDeletionConfirmed(client: PluginInput["client"], id: string, timeoutMs: number): Promise<boolean>;

package/dist/src/host-client.js

@@ -6,7 +6,7 @@
  *
  * Current gaps (as of @opencode-ai/plugin ~1.18.10):
  * - session.create body: metadata + title typing
- * - session.prompt body: `format` (json_schema) omitted from PromptInput
+ * - session.prompt body: `format` (json_schema) and `variant` omitted from PromptInput
  * - AssistantMessage.info.structured: structured extraction result
  * - client._client.get: experimental routes (no experimental.* namespace on V1)
  * - mcp.status: present on host client, weakly typed in plugin package
@@ -18,11 +18,58 @@ export function pluginHttpGet(client) {
         return null;
     return http.get.bind(http);
 }
+/**
+ * Host-wide session list. The SDK injects `directory` from
+ * x-opencode-directory on every GET; a truthy value makes the experimental
+ * handler filter to that instance's project. Pass `directory:""` so rewrite
+ * does not re-inject and the handler sees a falsy value → listGlobal.
+ * Used by discovery and helper-session cleanup (memory is global).
+ */
+export async function hostListSessionsGlobal(client, opts) {
+    const get = pluginHttpGet(client);
+    if (!get)
+        throw new Error("plugin HTTP client unavailable");
+    return get({
+        url: "/experimental/session",
+        query: {
+            roots: true,
+            limit: opts.limit,
+            directory: "",
+            ...(opts.cursor !== undefined ? { cursor: opts.cursor } : {}),
+            ...(opts.search !== undefined ? { search: opts.search } : {}),
+        },
+        signal: opts.signal,
+    });
+}
+/** Attach a no-op catch so a raced-away promise cannot become unhandled. */
+export function ignoreLateRejection(promise) {
+    void promise.catch(() => { });
+}
+export async function withHostTimeout(promise, ms, label, abort) {
+    ignoreLateRejection(promise);
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    abort?.abort();
+                    reject(new Error(`${label} timed out after ${ms}ms`));
+                }, ms);
+                timer.unref?.();
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
 /** session.create with metadata (SDK body type is incomplete). */
 export async function hostSessionCreate(client, opts) {
     return client.session.create({
         query: { directory: opts.directory },
         body: opts.body,
+        ...(opts.signal ? { signal: opts.signal } : {}),
     });
 }
 /** session.prompt including `format` for json_schema structured output. */
@@ -34,6 +81,7 @@ export async function hostSessionPrompt(client, opts) {
             ...(opts.body.system ? { system: opts.body.system } : {}),
             ...(opts.body.model ? { model: opts.body.model } : {}),
             ...(opts.body.format ? { format: opts.body.format } : {}),
+            ...(opts.body.variant ? { variant: opts.body.variant } : {}),
             parts: opts.body.parts,
         },
     });
@@ -55,15 +103,50 @@ export async function hostMcpStatus(client, signal) {
     return (await mcp.status({ signal }));
 }
 /** session.messages — weakly typed parts; centralize the cast. */
-export async function hostSessionMessages(client, sessionId) {
+export async function hostSessionMessages(client, sessionId, signal) {
     if (!client || typeof client.session?.messages !== "function") {
         throw new Error("plugin client unavailable; cannot load transcript");
     }
-    return client.session.messages({ path: { id: sessionId } });
+    return client.session.messages({
+        path: { id: sessionId },
+        ...(signal ? { signal } : {}),
+    });
 }
 export function hostPartType(part) {
     return typeof part?.type === "string" ? part.type : "unknown";
 }
+function isNotFoundStatus(res) {
+    if (res?.response?.status === 404)
+        return true;
+    const err = res?.error;
+    if (err && typeof err === "object") {
+        const rec = err;
+        if (rec.status === 404)
+            return true;
+        if (typeof rec.name === "string" && rec.name.toLowerCase().includes("notfound"))
+            return true;
+    }
+    return false;
+}
+const SESSION_LIVE_TIMEOUT_MS = 1_000;
+/** Codex re-checks the live threads table; 404 = gone, anything else stays. */
+export async function hostSessionLiveness(client, id, timeoutMs = SESSION_LIVE_TIMEOUT_MS) {
+    const session = client?.session;
+    if (typeof session?.get !== "function")
+        return "unknown";
+    const controller = new AbortController();
+    try {
+        const res = await withHostTimeout(session.get({ path: { id }, signal: controller.signal }), timeoutMs, "session.get", controller);
+        if (isNotFoundStatus(res))
+            return "gone";
+        if (res?.error)
+            return "unknown";
+        return "live";
+    }
+    catch {
+        return "unknown";
+    }
+}
 export async function hostSessionDeletionConfirmed(client, id, timeoutMs) {
     const session = client.session;
     if (typeof session?.get !== "function")

package/dist/src/index.d.ts

@@ -1,5 +1,7 @@
 import { MemoryStore } from "./store.js";
 import type { PluginInput, PluginOptions } from "@opencode-ai/plugin";
+/** Test seam: wait for all hook-launched work, including follow-up phase 2. */
+export declare function waitForBackgroundTasks(): Promise<void>;
 export declare function takeNewCitations(partKey: string, ids: string[]): string[];
 export declare function markTurnSeen(sessionId: string): boolean;
 export declare function shouldHandleIdle(sessionId: string, now?: number): boolean;
@@ -58,11 +60,13 @@ declare const _default: {
                 description: string;
                 args: {
                     path: import("zod").ZodDefault<import("zod").ZodString>;
+                    cursor: import("zod").ZodOptional<import("zod").ZodString>;
                     max_results: import("zod").ZodDefault<import("zod").ZodNumber>;
                 };
                 execute(args: {
                     path: string;
                     max_results: number;
+                    cursor?: string | undefined;
                 }, context: import("@opencode-ai/plugin").ToolContext): Promise<import("@opencode-ai/plugin").ToolResult>;
             };
             memory_add_note: {

package/dist/src/index.js

@@ -11,10 +11,26 @@ import { pluginOptions, recordConfigWarning, clearConfigWarnings, resetPluginOpt
 import { beginPluginShutdown, isPluginShuttingDown, resetPluginLifecycle } from "./lifecycle.js";
 import { hostMcpStatus } from "./host-client.js";
 import { recordDiagnostic } from "./diagnostics.js";
-import fs from "fs";
+import { loadBundledAgentDefinitions, recordAgentConfig, resetAgentHealth } from "./agent-health.js";
 import path from "path";
 let phase1InFlight = false;
 let pluginClient = null;
+const backgroundTasks = new Set();
+function trackBackgroundTask(task) {
+    // Hooks must remain non-blocking, but test teardown needs a way to wait until
+    // work started by a hook has released its DB handle.
+    const tracked = task.catch((err) => {
+        console.error("[opencode-codex-memory] background task error:", err);
+    });
+    backgroundTasks.add(tracked);
+    void tracked.then(() => backgroundTasks.delete(tracked));
+}
+/** Test seam: wait for all hook-launched work, including follow-up phase 2. */
+export async function waitForBackgroundTasks() {
+    while (backgroundTasks.size > 0) {
+        await Promise.all([...backgroundTasks]);
+    }
+}
 // Single-flight guard for mcp.status(); see mcpToolPrefixes below.
 let mcpStatusInFlight = null;
 const MCP_STATUS_TIMEOUT_MS = 1_000;
@@ -83,7 +99,7 @@ export function handleSessionDeleted(sessionId, store = getStore(),
 // enqueued job runs when generation is re-enabled (codex: delete only
 // enqueues; the pipeline itself is gated elsewhere).
 schedulePhase2 = () => { if (pluginOptions.generate_memories)
-    void triggerPhase2(); }) {
+    trackBackgroundTask(triggerPhase2()); }) {
     if (store.deleteSessionMemory(sessionId))
         schedulePhase2();
 }
@@ -94,6 +110,7 @@ export default {
         resetPluginLifecycle();
         setPluginInput(input);
         pluginClient = input.client;
+        resetAgentHealth();
         mcpStatusInFlight = null;
         // Unconditional, like the caches above: a boot WITHOUT options must not
         // inherit the previous boot's warnings (opencode can host several
@@ -320,8 +337,7 @@ async function classifyExternalContextTool(toolName) {
 export function injectAgentDefinitions(config) {
     let defs;
     try {
-        const raw = fs.readFileSync(path.join(import.meta.dirname, "..", "opencode.json"), "utf8");
-        defs = JSON.parse(raw).agent ?? {};
+        defs = loadBundledAgentDefinitions();
     }
     catch (err) {
         console.warn("[opencode-codex-memory] could not load bundled agent definitions:", err);
@@ -339,6 +355,7 @@ export function injectAgentDefinitions(config) {
         if (!config.agent[name])
             config.agent[name] = def;
     }
+    recordAgentConfig(config, true, defs);
 }
 function buildHooks() {
     const base = {
@@ -346,8 +363,15 @@ function buildHooks() {
             try {
                 // The write pipeline is the only consumer of the sub-agents; with
                 // generation off they would just pollute the user's agent list.
-                if (!pluginOptions.generate_memories)
+                if (!pluginOptions.generate_memories) {
+                    try {
+                        recordAgentConfig(input, false, loadBundledAgentDefinitions());
+                    }
+                    catch (err) {
+                        console.warn("[opencode-codex-memory] could not inspect bundled agent definitions:", err);
+                    }
                     return;
+                }
                 injectAgentDefinitions(input);
             }
             catch (err) {
@@ -450,7 +474,7 @@ function buildHooks() {
                 catch (e) {
                     console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
                 }
-                void triggerPhase1(sid);
+                trackBackgroundTask(triggerPhase1(sid));
             }
             catch (err) {
                 console.error("[opencode-codex-memory] chat.message error:", err);
@@ -578,7 +602,7 @@ function buildHooks() {
         catch (e) {
             console.error("[opencode-codex-memory] stampMemoryModeIfAbsent failed:", e);
         }
-        void triggerPhase1(sid);
+        trackBackgroundTask(triggerPhase1(sid));
     }
     // Control tools (reset/inspect/mode) are always available. The memory
     // read/search/list/add-note tools require BOTH use_memories and
@@ -622,7 +646,7 @@ async function triggerPhase1(currentSessionId) {
     finally {
         phase1InFlight = false;
     }
-    void triggerPhase2();
+    trackBackgroundTask(triggerPhase2());
 }
 async function triggerPhase2() {
     if (isPluginShuttingDown())

package/dist/src/llm.d.ts

@@ -6,7 +6,15 @@ export interface ExtractionResult {
 }
 export declare function setPluginInput(input: PluginInput): void;
 export declare function getPluginInput(): PluginInput | null;
+/** Test seam. */
+export declare function setSubSessionCreateTimeoutForTest(ms?: number): void;
+/** Test seam. */
+export declare function setConfigGetTimeoutForTest(ms?: number): void;
+/** Test seam. */
+export declare function setStaleDeleteBatchTimeoutForTest(ms?: number): void;
 export declare function isMemorySubSession(sessionId: string): boolean;
+export declare function resolveExtractionModel(configured?: string): Promise<string | undefined>;
+export declare function resolveConsolidationModel(configured?: string): Promise<string | undefined>;
 /**
  * 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