opencode-codex-memory 0.4.7 → 0.4.9

package/README.md

@@ -52,7 +52,7 @@ If you want the mental model before the details, jump to
 
 ```json
 {
-  "plugin": ["opencode-codex-memory@0.4.7"]
+  "plugin": ["opencode-codex-memory@0.4.9"]
 }
 ```
 
@@ -239,7 +239,7 @@ To set options, turn the plugin entry into a `[name, options]` pair:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.7", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
+    ["opencode-codex-memory@0.4.9", { "disable_on_external_context": true, "min_rollout_idle_hours": 2 }]
   ]
 }
 ```
@@ -298,7 +298,7 @@ directions:
 ```json
 {
   "plugin": [
-    ["opencode-codex-memory@0.4.7", { "codex_interop": { "import": true, "export": true } }]
+    ["opencode-codex-memory@0.4.9", { "codex_interop": { "import": true, "export": true } }]
   ]
 }
 ```
@@ -351,6 +351,30 @@ The cost is real: with one store, an unrelated project's details can surface in
 the summary. Codex judged that cheaper than the alternative, and this port
 mirrors that decision rather than layering scoping back on top.
 
+## Troubleshooting
+
+When memory does not seem to build, ask the agent to run **`memory_inspect`**.
+It reports:
+
+- stage-1 job counts and recent extraction errors
+- phase-2 status / last error / cooldown
+- last session-discovery outcome
+- effective options (after clamping) and config warnings
+- a short eligibility reminder (`min_rollout_idle_hours`, default **6h**)
+
+Common causes:
+
+| Symptom | Likely cause |
+|---|---|
+| No stage-1 outputs yet | Sessions must stay idle ≥ `min_rollout_idle_hours` (default 6). For a quick local check, set `"min_rollout_idle_hours": 1`. |
+| 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. |
+
+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 cache.
+
 ## Contributing
 
 The port follows Codex closely: same two-phase pipeline, same on-disk artifacts,
@@ -360,6 +384,8 @@ guidance lives in [`CONTRIBUTING.md`](./CONTRIBUTING.md) and
 [`AGENTS.md`](./AGENTS.md) — in short: this repo exists to port Codex's memory
 system to OpenCode, and PRs that break that parity will be rejected.
 
+CI runs `bun test`, typecheck, build, and the packaging smoke test on every PR.
+
 ## License
 
 Apache 2.0 — the same license as [OpenAI Codex](https://github.com/openai/codex),

package/dist/opencode.json

@@ -3,7 +3,7 @@
   "agent": {
     "memorize": {
       "mode": "subagent",
-      "prompt": "You are a memory consolidation agent. Read the workspace diff file and update MEMORY.md, memory_summary.md, and skills/ to reflect the latest memories. Keep memory_summary.md under 10000 chars (2500 tokens). Prune stale entries. Do not access the network.",
+      "prompt": "You are a memory consolidation agent. Read the workspace diff file and update MEMORY.md, memory_summary.md, and skills/ under the memory workspace only. Do not read or edit project source files outside that memory root. Keep memory_summary.md under 10000 chars (2500 tokens). Prune stale entries. Do not access the network.",
       "permission": {
         "*": "deny",
         "bash": "deny",

package/dist/src/capture.d.ts

@@ -4,13 +4,8 @@ export interface SessionRow {
     updated_at: number;
     directory: string | null;
 }
-/**
- * Global session discovery through the official API:
- * `GET /experimental/session?roots=true` (Session.listGlobal) — one call across
- * all projects, sorted by most-recently-updated. Available since opencode
- * 1.17.x. Fail-safe: any error skips the pass ([]); never finalizes a job.
- * Transcript loading must NOT be fail-safe — see loadTranscript.
- */
+/** Test seam. */
+export declare function resetDiscoveryCacheForTest(): void;
 export declare function listRecentSessions(limit?: number): Promise<SessionRow[]>;
 export interface TranscriptMessage {
     type: string;

package/dist/src/capture.js

@@ -1,5 +1,7 @@
 import { SCAN_LIMIT } from "./store.js";
 import { getPluginInput } from "./llm.js";
+import { recordDiscoveryStatus } from "./diagnostics.js";
+import { hostPartType, hostSessionMessages, pluginHttpGet } from "./host-client.js";
 const API_TIMEOUT_MS = 60_000;
 async function withTimeout(promise, ms, label) {
     let timer;
@@ -15,19 +17,6 @@ async function withTimeout(promise, ms, label) {
         clearTimeout(timer);
     }
 }
-/**
- * Hey-api transport on PluginInput.client. The V1 SDK has no
- * `experimental.*` namespace, but the host-built client already carries
- * baseUrl + auth headers; `_client.get` is the supported escape hatch for
- * routes the generated surface lags on (same pattern as the scope/roots casts
- * we used to need on session.list).
- */
-function pluginHttp() {
-    const http = getPluginInput()?.client?._client;
-    if (!http || typeof http.get !== "function")
-        return null;
-    return http;
-}
 /**
  * Global session discovery through the official API:
  * `GET /experimental/session?roots=true` (Session.listGlobal) — one call across
@@ -35,12 +24,30 @@ function pluginHttp() {
  * 1.17.x. Fail-safe: any error skips the pass ([]); never finalizes a job.
  * Transcript loading must NOT be fail-safe — see loadTranscript.
  */
+// Empty phase-1 passes no longer stamp the process rate-limit timer, so idle/
+// chat.message can re-enter often. Coalesce discovery API calls to avoid
+// hammering the host on every no-claim pass (load only; eligibility still
+// uses a fresh filter over this short-lived snapshot).
+const DISCOVERY_CACHE_MS = 30_000;
+let discoveryCache = null;
+/** Test seam. */
+export function resetDiscoveryCacheForTest() {
+    discoveryCache = null;
+}
 export async function listRecentSessions(limit = SCAN_LIMIT) {
-    const http = pluginHttp();
-    if (!http)
+    const now = Date.now();
+    if (discoveryCache &&
+        discoveryCache.limit >= limit &&
+        now - discoveryCache.at < DISCOVERY_CACHE_MS) {
+        return discoveryCache.rows.slice(0, limit);
+    }
+    const get = pluginHttpGet(getPluginInput()?.client);
+    if (!get) {
+        recordDiscoveryStatus({ ok: false, count: 0, error: "plugin HTTP client unavailable" });
         return [];
+    }
     try {
-        const res = await withTimeout(http.get({
+        const res = await withTimeout(get({
             url: "/experimental/session",
             query: { roots: true, limit },
         }), API_TIMEOUT_MS, "experimental.session.list");
@@ -61,20 +68,22 @@ export async function listRecentSessions(limit = SCAN_LIMIT) {
         // Server already orders by time_updated DESC; re-sort so a lagging host
         // cannot invert eligibility order.
         all.sort((a, b) => b.updated_at - a.updated_at);
-        return all.slice(0, limit);
+        const out = all.slice(0, limit);
+        discoveryCache = { at: now, limit, rows: out };
+        recordDiscoveryStatus({ ok: true, count: out.length });
+        return out;
     }
     catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
         console.warn("[opencode-codex-memory] session discovery failed; skipping pass:", err);
+        recordDiscoveryStatus({ ok: false, count: 0, error: message });
+        // Do not cache failures — next pass should retry the host.
         return [];
     }
 }
 /** Official transcript surface: GET /session/{id}/message via the plugin's authenticated client. */
 async function fetchMessagesViaApi(sessionId) {
-    const client = getPluginInput()?.client;
-    if (typeof client?.session?.messages !== "function") {
-        throw new Error("plugin client unavailable; cannot load transcript");
-    }
-    const res = await withTimeout(client.session.messages({ path: { id: sessionId } }), API_TIMEOUT_MS, "session.messages");
+    const res = await withTimeout(hostSessionMessages(getPluginInput()?.client, sessionId), API_TIMEOUT_MS, "session.messages");
     if (!res || res.error || !Array.isArray(res.data)) {
         throw new Error(`session.messages failed: ${JSON.stringify(res?.error ?? {})}`);
     }
@@ -104,7 +113,7 @@ export async function loadTranscript(sessionId) {
         const role = row?.info?.role;
         for (const part of row?.parts ?? []) {
             out.push({
-                type: part?.type ?? "unknown",
+                type: hostPartType(part),
                 role,
                 text: extractText(part),
             });

package/dist/src/codex-interop.d.ts

@@ -36,3 +36,11 @@ export declare function syncCodexImport(codexMemoryRoot: string): boolean;
  * placeholder MEMORY.md / empty summary would just be noise.
  */
 export declare function exportToCodexMemory(codexMemoryRoot: string): boolean;
+export interface CodexInteropMtimes {
+    importMemoryMd: number | null;
+    importSummary: number | null;
+    exportMemoryMd: number | null;
+    exportSummary: number | null;
+}
+/** Last mtimes of interop resource copies (for memory_inspect). */
+export declare function codexInteropMtimes(codexMemoryRoot: string): CodexInteropMtimes;

package/dist/src/codex-interop.js

@@ -311,3 +311,25 @@ export function exportToCodexMemory(codexMemoryRoot) {
         return false;
     return syncExtension(memoryRoot(), codexMemoryRoot, EXPORT_EXTENSION, "opencode", EXPORT_INSTRUCTIONS);
 }
+function mtimeMs(file) {
+    try {
+        const st = fs.lstatSync(file);
+        if (!st.isFile())
+            return null;
+        return st.mtimeMs;
+    }
+    catch {
+        return null;
+    }
+}
+/** Last mtimes of interop resource copies (for memory_inspect). */
+export function codexInteropMtimes(codexMemoryRoot) {
+    const importRes = path.join(memoryRoot(), "extensions", IMPORT_EXTENSION, "resources", "codex");
+    const exportRes = path.join(codexMemoryRoot, "extensions", EXPORT_EXTENSION, "resources", "opencode");
+    return {
+        importMemoryMd: mtimeMs(path.join(importRes, "MEMORY.md")),
+        importSummary: mtimeMs(path.join(importRes, "memory_summary.md")),
+        exportMemoryMd: mtimeMs(path.join(exportRes, "MEMORY.md")),
+        exportSummary: mtimeMs(path.join(exportRes, "memory_summary.md")),
+    };
+}

package/dist/src/diagnostics.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Process-local diagnostics for memory_inspect: a small ring buffer of
+ * pipeline events plus the last discovery outcome. Not metrics infrastructure
+ * (codex OTEL) — just enough to answer "why isn't memory building?" without
+ * digging through TUI-invisible console logs.
+ */
+export type DiagnosticLevel = "info" | "warn" | "error";
+export interface DiagnosticEvent {
+    at: number;
+    level: DiagnosticLevel;
+    kind: string;
+    message: string;
+}
+export interface DiscoveryStatus {
+    at: number;
+    ok: boolean;
+    count: number;
+    error?: string;
+}
+export declare function recordDiagnostic(level: DiagnosticLevel, kind: string, message: string): void;
+export declare function recordDiscoveryStatus(status: Omit<DiscoveryStatus, "at">): void;
+export declare function getRecentDiagnostics(limit?: number): readonly DiagnosticEvent[];
+export declare function getDiscoveryStatus(): DiscoveryStatus | null;
+/** Test seam. */
+export declare function resetDiagnosticsForTest(): void;
+export declare function formatDiagnosticLine(e: DiagnosticEvent): string;

package/dist/src/diagnostics.js

@@ -0,0 +1,37 @@
+/**
+ * Process-local diagnostics for memory_inspect: a small ring buffer of
+ * pipeline events plus the last discovery outcome. Not metrics infrastructure
+ * (codex OTEL) — just enough to answer "why isn't memory building?" without
+ * digging through TUI-invisible console logs.
+ */
+const MAX_EVENTS = 40;
+const events = [];
+let discovery = null;
+export function recordDiagnostic(level, kind, message) {
+    events.push({ at: Date.now(), level, kind, message });
+    while (events.length > MAX_EVENTS)
+        events.shift();
+}
+export function recordDiscoveryStatus(status) {
+    discovery = { ...status, at: Date.now() };
+    if (!status.ok) {
+        recordDiagnostic("warn", "discovery", status.error ?? "session discovery failed");
+    }
+    else {
+        recordDiagnostic("info", "discovery", `listed ${status.count} session(s)`);
+    }
+}
+export function getRecentDiagnostics(limit = 12) {
+    return events.slice(-limit);
+}
+export function getDiscoveryStatus() {
+    return discovery;
+}
+/** Test seam. */
+export function resetDiagnosticsForTest() {
+    events.length = 0;
+    discovery = null;
+}
+export function formatDiagnosticLine(e) {
+    return `${new Date(e.at).toISOString()} [${e.level}] ${e.kind}: ${e.message}`;
+}

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

@@ -0,0 +1,72 @@
+/**
+ * Narrow adapters for host SDK surfaces where the generated OpenAPI types lag
+ * the server (see BACKLOG "opencode release ritual"). Keep every intentional
+ * cast in this file so grepping for `as any` in pipeline code stays clean and
+ * each cast can be dropped when `types.gen.d.ts` catches up.
+ *
+ * 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
+ * - 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
+ */
+import type { PluginInput } from "@opencode-ai/plugin";
+export type HostHttpGet = (opts: {
+    url: string;
+    query?: Record<string, unknown>;
+    signal?: AbortSignal;
+}) => Promise<{
+    error?: unknown;
+    data?: unknown;
+}>;
+/** Hey-api transport on PluginInput.client for routes the V1 surface lags on. */
+export declare function pluginHttpGet(client: PluginInput["client"] | null | undefined): HostHttpGet | null;
+export interface SessionCreateBody {
+    title?: string;
+    metadata?: Record<string, unknown>;
+}
+/** session.create with metadata (SDK body type is incomplete). */
+export declare function hostSessionCreate(client: PluginInput["client"], opts: {
+    directory: string;
+    body: SessionCreateBody;
+}): Promise<{
+    error?: unknown;
+    data?: {
+        id?: string;
+    };
+}>;
+export interface HostPromptBody {
+    agent: string;
+    system?: string;
+    model?: {
+        providerID: string;
+        modelID: string;
+    };
+    format?: Record<string, unknown>;
+    parts: {
+        type: "text";
+        text: string;
+    }[];
+}
+/** session.prompt including `format` for json_schema structured output. */
+export declare function hostSessionPrompt(client: PluginInput["client"], opts: {
+    sessionId: string;
+    body: HostPromptBody;
+}): Promise<{
+    error?: unknown;
+    data?: unknown;
+}>;
+/** Read AssistantMessage.structured when the host captured json_schema output. */
+export declare function hostStructuredOutput(data: unknown): Record<string, unknown> | null;
+export declare function hostMcpStatus(client: PluginInput["client"] | null, signal?: AbortSignal): Promise<{
+    error?: unknown;
+    data?: unknown;
+} | null>;
+/** session.messages — weakly typed parts; centralize the cast. */
+export declare function hostSessionMessages(client: PluginInput["client"] | null | undefined, sessionId: string): Promise<{
+    error?: unknown;
+    data?: unknown;
+}>;
+export declare function hostPartType(part: unknown): string;
+export declare function hostSessionDeletionConfirmed(client: PluginInput["client"], id: string, timeoutMs: number): Promise<boolean>;

package/dist/src/host-client.js

@@ -0,0 +1,91 @@
+/**
+ * Narrow adapters for host SDK surfaces where the generated OpenAPI types lag
+ * the server (see BACKLOG "opencode release ritual"). Keep every intentional
+ * cast in this file so grepping for `as any` in pipeline code stays clean and
+ * each cast can be dropped when `types.gen.d.ts` catches up.
+ *
+ * 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
+ * - 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
+ */
+/** Hey-api transport on PluginInput.client for routes the V1 surface lags on. */
+export function pluginHttpGet(client) {
+    const http = client?._client;
+    if (!http || typeof http.get !== "function")
+        return null;
+    return http.get.bind(http);
+}
+/** 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,
+    });
+}
+/** session.prompt including `format` for json_schema structured output. */
+export async function hostSessionPrompt(client, opts) {
+    return client.session.prompt({
+        path: { id: opts.sessionId },
+        body: {
+            agent: opts.body.agent,
+            ...(opts.body.system ? { system: opts.body.system } : {}),
+            ...(opts.body.model ? { model: opts.body.model } : {}),
+            ...(opts.body.format ? { format: opts.body.format } : {}),
+            parts: opts.body.parts,
+        },
+    });
+}
+/** Read AssistantMessage.structured when the host captured json_schema output. */
+export function hostStructuredOutput(data) {
+    const structured = data?.info?.structured;
+    if (structured && typeof structured === "object" && !Array.isArray(structured)) {
+        return structured;
+    }
+    return null;
+}
+export async function hostMcpStatus(client, signal) {
+    if (!client)
+        return null;
+    const mcp = client.mcp;
+    if (typeof mcp?.status !== "function")
+        return null;
+    return (await mcp.status({ signal }));
+}
+/** session.messages — weakly typed parts; centralize the cast. */
+export async function hostSessionMessages(client, sessionId) {
+    if (!client || typeof client.session?.messages !== "function") {
+        throw new Error("plugin client unavailable; cannot load transcript");
+    }
+    return client.session.messages({ path: { id: sessionId } });
+}
+export function hostPartType(part) {
+    return typeof part?.type === "string" ? part.type : "unknown";
+}
+export async function hostSessionDeletionConfirmed(client, id, timeoutMs) {
+    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 ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+        return res?.response?.status === 404;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/dist/src/index.js

@@ -6,8 +6,11 @@ import { memory_reset, memory_inspect, memory_mode } from "../tools/control.js";
 import { MemoryStore } from "./store.js";
 import { runPhase1 } from "./phase1.js";
 import { runPhase2 } from "./phase2.js";
-import { setPluginInput, cleanupOldSubSessions, isMemorySubSession } from "./llm.js";
+import { setPluginInput, cleanupOldSubSessions, isMemorySubSession, abortActiveSubSessions } from "./llm.js";
 import { pluginOptions, recordConfigWarning, clearConfigWarnings, resetPluginOptions } from "./options.js";
+import { beginPluginShutdown, isPluginShuttingDown, resetPluginLifecycle } from "./lifecycle.js";
+import { hostMcpStatus } from "./host-client.js";
+import { recordDiagnostic } from "./diagnostics.js";
 import fs from "fs";
 import path from "path";
 let phase1InFlight = false;
@@ -87,6 +90,8 @@ schedulePhase2 = () => { if (pluginOptions.generate_memories)
 export default {
     id: "opencode-codex-memory",
     async server(input, opts) {
+        // A reload after dispose must be able to run the pipeline again.
+        resetPluginLifecycle();
         setPluginInput(input);
         pluginClient = input.client;
         mcpStatusInFlight = null;
@@ -222,7 +227,7 @@ async function mcpToolPrefixes() {
             let timer;
             try {
                 const res = await Promise.race([
-                    pluginClient.mcp.status({ signal: controller.signal }),
+                    hostMcpStatus(pluginClient, controller.signal),
                     new Promise((_, reject) => {
                         timer = setTimeout(() => {
                             controller.abort();
@@ -230,9 +235,9 @@ async function mcpToolPrefixes() {
                         }, MCP_STATUS_TIMEOUT_MS);
                     }),
                 ]);
-                if (res?.error)
+                if (!res || res.error)
                     return null;
-                const servers = res?.data;
+                const servers = res.data;
                 if (!servers || typeof servers !== "object" || Array.isArray(servers))
                     return null;
                 const prefixes = [];
@@ -516,6 +521,15 @@ function buildHooks() {
             }
         },
         async dispose() {
+            // Stop new pumps, abort the consolidator helper if it is mid-write, and
+            // best-effort abort extract sessions so a reload cannot leave two writers.
+            beginPluginShutdown();
+            try {
+                await abortActiveSubSessions();
+            }
+            catch (err) {
+                console.warn("[opencode-codex-memory] dispose abort of sub-sessions failed:", err);
+            }
             invalidateCache();
         },
     };
@@ -557,7 +571,7 @@ function buildHooks() {
     return { ...base, tool };
 }
 async function triggerPhase1(currentSessionId) {
-    if (phase1InFlight || !pluginOptions.generate_memories)
+    if (phase1InFlight || !pluginOptions.generate_memories || isPluginShuttingDown())
         return;
     phase1InFlight = true;
     try {
@@ -572,6 +586,7 @@ async function triggerPhase1(currentSessionId) {
     }
     catch (err) {
         console.error("[opencode-codex-memory] phase1 error:", err);
+        recordDiagnostic("error", "phase1", err instanceof Error ? err.message : String(err));
     }
     finally {
         phase1InFlight = false;
@@ -579,17 +594,23 @@ async function triggerPhase1(currentSessionId) {
     void triggerPhase2();
 }
 async function triggerPhase2() {
+    if (isPluginShuttingDown())
+        return;
     try {
         // runPhase2 has its own in-flight guard
-        await runPhase2(getStore(), {
+        const result = await runPhase2(getStore(), {
             maxRaw: pluginOptions.max_raw_memories_for_consolidation,
             maxUnusedDays: pluginOptions.max_unused_days,
             extensionRetentionDays: 7,
             consolidationModel: pluginOptions.consolidation_model,
             codexInterop: pluginOptions.codex_interop,
         });
+        if (result.status !== "already_running" && result.status !== "skipped_cooldown" && result.status !== "skipped_running") {
+            recordDiagnostic(result.status === "succeeded" || result.status === "no_workspace_changes" ? "info" : "warn", "phase2", result.status);
+        }
     }
     catch (err) {
         console.error("[opencode-codex-memory] phase2 error:", err);
+        recordDiagnostic("error", "phase2", err instanceof Error ? err.message : String(err));
     }
 }

package/dist/src/lifecycle.d.ts

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

package/dist/src/lifecycle.js

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

package/dist/src/llm.d.ts

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