@cortexkit/opencode-magic-context 0.41.3 → 0.42.0

package/src/shared/model-suggestion-retry.ts

@@ -3,6 +3,7 @@ import type { createOpencodeClient } from "@opencode-ai/sdk";
 import { detectOverflow } from "../features/magic-context/overflow-detection";
 import { log } from "./logger";
 import type { ModelInput } from "./model-resolution";
+import { sanitizeDiagnosticText } from "./redaction";
 import { parseProviderModel, toModelEntry } from "./resolve-fallbacks";
 
 type Client = ReturnType<typeof createOpencodeClient>;
@@ -70,7 +71,7 @@ export interface PromptRetryOptions {
     fallbackModels?: readonly ModelInput[];
     /**
      * Identifier for structured logging (e.g. "dreamer:consolidate",
-     * "historian", "compressor", "sidekick"). Helps correlate fallback
+     * "historian", "compressor", "dreamer"). Helps correlate fallback
      * attempts to a specific call site in `magic-context.log`. Defaults to
      * "subagent" if not provided.
      */
@@ -100,6 +101,33 @@ export interface ValidatedPromptRetryResult<TOutput, TValidated> {
     attempt: PromptAttemptInfo;
 }
 
+export type PromptFailureClass =
+    | "provider_timeout"
+    | "provider_error"
+    | "empty_completion"
+    | "no_models"
+    | "child_aborted"
+    | "parse_failed"
+    | "unknown";
+
+/** Diagnostic facts retained when a validated child prompt ultimately fails. */
+export interface PromptFailureDetail {
+    failureClass: PromptFailureClass;
+    modelAttempted: string | null;
+    modelsTried: string[];
+    providerError: string | null;
+    timeoutMs: number | null;
+    childSessionId: string | null;
+}
+
+const promptFailureDetails = new WeakMap<object, PromptFailureDetail>();
+
+export function getPromptFailureDetail(error: unknown): PromptFailureDetail | null {
+    return error !== null && typeof error === "object"
+        ? (promptFailureDetails.get(error) ?? null)
+        : null;
+}
+
 export interface ModelSuggestionInfo {
     providerID: string;
     modelID: string;
@@ -279,6 +307,61 @@ function shortErr(error: unknown): string {
     return extractMessage(error);
 }
 
+type PromptFailurePhase = "prompt" | "output" | "validation";
+
+interface FailedAttempt {
+    error: unknown;
+    failureClass: PromptFailureClass;
+    attempt: PromptAttemptInfo;
+}
+
+function classifyPromptFailure(
+    error: unknown,
+    phase: PromptFailurePhase,
+    externalSignal?: AbortSignal,
+): PromptFailureClass {
+    const message = extractMessage(error);
+    if (externalSignal?.aborted || message === "prompt aborted by external signal") {
+        return "child_aborted";
+    }
+    if (/^prompt timed out after \d+ms$/.test(message)) return "provider_timeout";
+    if (phase === "validation") {
+        if (/returned no (?:assistant )?output|no assistant output/i.test(message)) {
+            return "empty_completion";
+        }
+        if (error instanceof Error && error.name === "DreamerProviderOutputFailureError") {
+            return "provider_error";
+        }
+        return "parse_failed";
+    }
+    return phase === "prompt" || phase === "output" ? "provider_error" : "unknown";
+}
+
+function throwWithPromptFailure(
+    legacyError: unknown,
+    failedAttempts: FailedAttempt[],
+    args: PromptArgs,
+    timeoutMs: number,
+): never {
+    const error =
+        legacyError instanceof Error ? legacyError : new Error(extractMessage(legacyError));
+    const last = failedAttempts.at(-1);
+    const failureClass = last?.failureClass ?? "unknown";
+    const providerError =
+        failureClass === "provider_error"
+            ? sanitizeDiagnosticText(shortErr(last?.error ?? legacyError)).slice(0, 500)
+            : null;
+    promptFailureDetails.set(error, {
+        failureClass,
+        modelAttempted: last?.attempt.label ?? null,
+        modelsTried: failedAttempts.map((failure) => failure.attempt.label),
+        providerError,
+        timeoutMs: failureClass === "provider_timeout" ? timeoutMs : null,
+        childSessionId: args.path.id || null,
+    });
+    throw error;
+}
+
 /**
  * Try a single prompt attempt against the supplied body, with the existing
  * single-suggestion retry layered inside (so "did you mean X?" still self-heals
@@ -449,23 +532,43 @@ async function attemptAndValidate<TOutput, TValidated>(
     attempt: PromptAttemptInfo,
     options: ValidatedPromptRetryOptions<TOutput, TValidated>,
 ): Promise<ValidatedPromptRetryResult<TOutput, TValidated>> {
-    await attemptOnce(client, args, timeoutMs, signal, callContext, attempt.label);
-    const output = await options.fetchOutput(args, attempt);
-    const validated = await options.validateOutput(output, attempt);
-    return { output, validated, attempt };
+    try {
+        await attemptOnce(client, args, timeoutMs, signal, callContext, attempt.label);
+    } catch (error) {
+        throw {
+            error,
+            failureClass: classifyPromptFailure(error, "prompt", signal),
+            attempt,
+        } satisfies FailedAttempt;
+    }
+
+    let output: TOutput;
+    try {
+        output = await options.fetchOutput(args, attempt);
+    } catch (error) {
+        throw {
+            error,
+            failureClass: classifyPromptFailure(error, "output", signal),
+            attempt,
+        } satisfies FailedAttempt;
+    }
+
+    try {
+        const validated = await options.validateOutput(output, attempt);
+        return { output, validated, attempt };
+    } catch (error) {
+        throw {
+            error,
+            failureClass: classifyPromptFailure(error, "validation", signal),
+            attempt,
+        } satisfies FailedAttempt;
+    }
 }
 
 /**
- * Run a prompt with model fallback support, but accept an attempt only after the
- * caller validates the model's actual output. This covers "empty success" cases
- * where the provider/OpenCode prompt call completes successfully but the subagent
- * produced no usable assistant text / JSON.
- *
- * The happy path is still one prompt + one caller-owned output fetch: callers
- * should use the returned output instead of fetching messages a second time.
- * Validation failures are retryable across configured fallback models. If every
- * attempt produces invalid output (or otherwise fails retryably), the first
- * failure is re-thrown so callers surface the original failure semantics.
+ * Run a prompt across the configured model chain and retain which attempt failed.
+ * Output validation remains caller-owned so empty completions and malformed
+ * responses can be distinguished from provider transport failures.
  */
 export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = TOutput>(
     client: Client,
@@ -486,7 +589,7 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
             ? `${baseBody.model.providerID}/${baseBody.model.modelID}`
             : "primary";
     const totalAttempts = fallbacks.length + 1;
-
+    const failedAttempts: FailedAttempt[] = [];
     let firstError: unknown = null;
     let lastError: unknown = null;
 
@@ -506,17 +609,21 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
             },
             options,
         );
-    } catch (error) {
-        firstError = error;
-        lastError = error;
-        if (isNonRetryable(error, options.signal)) throw error;
+    } catch (caught) {
+        const failure = caught as FailedAttempt;
+        failedAttempts.push(failure);
+        firstError = failure.error;
+        lastError = failure.error;
+        if (isNonRetryable(failure.error, options.signal)) {
+            throwWithPromptFailure(failure.error, failedAttempts, args, timeoutMs);
+        }
 
         if (fallbacks.length === 0) {
-            throw error;
+            throwWithPromptFailure(failure.error, failedAttempts, args, timeoutMs);
         }
 
         log(
-            `[${callContext}] primary (${explicitPrimaryLabel}) failed validation/prompt: ${shortErr(error)}; trying ${fallbacks.length} fallback(s)`,
+            `[${callContext}] primary (${explicitPrimaryLabel}) failed validation/prompt: ${shortErr(failure.error)}; trying ${fallbacks.length} fallback(s)`,
         );
     }
 
@@ -557,22 +664,30 @@ export async function promptSyncWithValidatedOutputRetry<TOutput, TValidated = T
                 `[${callContext}] fallback succeeded with ${label} (attempt ${i + 2}/${fallbacks.length + 1})`,
             );
             return result;
-        } catch (error) {
-            if (firstError === null) firstError = error;
-            lastError = error;
-            if (isNonRetryable(error, options.signal)) throw error;
+        } catch (caught) {
+            const failure = caught as FailedAttempt;
+            failedAttempts.push(failure);
+            lastError = failure.error;
+            if (isNonRetryable(failure.error, options.signal)) {
+                throwWithPromptFailure(failure.error, failedAttempts, args, timeoutMs);
+            }
 
             const remaining = fallbacks.length - i - 1;
             if (remaining > 0) {
                 log(
-                    `[${callContext}] ${label} failed validation/prompt: ${shortErr(error)}; ${remaining} fallback(s) left`,
+                    `[${callContext}] ${label} failed validation/prompt: ${shortErr(failure.error)}; ${remaining} fallback(s) left`,
                 );
             }
         }
     }
 
     log(
-        `[${callContext}] all models exhausted; tried: ${[explicitPrimaryLabel, ...fallbacks.map((fallback) => toModelEntry(fallback)?.model ?? String(fallback))].join(", ")}; original error: ${shortErr(firstError)}; last error: ${shortErr(lastError)}`,
+        `[${callContext}] all models exhausted; tried: ${failedAttempts.map((failure) => failure.attempt.label).join(", ")}; original error: ${shortErr(firstError)}; last error: ${shortErr(lastError)}`,
+    );
+    throwWithPromptFailure(
+        firstError ?? lastError ?? new Error("All fallback models failed validation"),
+        failedAttempts,
+        args,
+        timeoutMs,
     );
-    throw firstError ?? lastError ?? new Error("All fallback models failed validation");
 }

package/src/shared/opencode-db-path.test.ts

@@ -0,0 +1,196 @@
+/// <reference types="bun-types" />
+
+import { afterEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, unlinkSync, utimesSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    formatOpenCodeDbDoctorLine,
+    formatOpenCodeDbMissingBanner,
+    formatOpenCodeDbMissingStatusLine,
+    openCodeDbPathExists,
+    resetOpenCodeDbPathStateForTesting,
+    resolveOpenCodeDbPath,
+} from "./opencode-db-path";
+
+const ORIGINAL_ENV = {
+    XDG_DATA_HOME: process.env.XDG_DATA_HOME,
+    OPENCODE_DB: process.env.OPENCODE_DB,
+    OPENCODE_DISABLE_CHANNEL_DB: process.env.OPENCODE_DISABLE_CHANNEL_DB,
+    OPENCODE_CHANNEL: process.env.OPENCODE_CHANNEL,
+};
+const tempDirs: string[] = [];
+
+function restore(name: keyof typeof ORIGINAL_ENV): void {
+    const value = ORIGINAL_ENV[name];
+    if (value === undefined) delete process.env[name];
+    else process.env[name] = value;
+}
+
+afterEach(() => {
+    restore("XDG_DATA_HOME");
+    restore("OPENCODE_DB");
+    restore("OPENCODE_DISABLE_CHANNEL_DB");
+    restore("OPENCODE_CHANNEL");
+    resetOpenCodeDbPathStateForTesting();
+    for (const directory of tempDirs.splice(0)) rmSync(directory, { recursive: true, force: true });
+});
+
+function useDataHome(): { dataHome: string; openCodeDir: string } {
+    const dataHome = mkdtempSync(join(tmpdir(), "opencode-db-path-"));
+    const openCodeDir = join(dataHome, "opencode");
+    mkdirSync(openCodeDir, { recursive: true });
+    tempDirs.push(dataHome);
+    process.env.XDG_DATA_HOME = dataHome;
+    delete process.env.OPENCODE_DB;
+    delete process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    delete process.env.OPENCODE_CHANNEL;
+    resetOpenCodeDbPathStateForTesting();
+    return { dataHome, openCodeDir };
+}
+
+function createCandidate(openCodeDir: string, name: string, mtimeMs: number): string {
+    const path = join(openCodeDir, name);
+    writeFileSync(path, "sqlite fixture");
+    const time = new Date(mtimeMs);
+    utimesSync(path, time, time);
+    return path;
+}
+
+describe("resolveOpenCodeDbPath", () => {
+    it("honors absolute and relative OPENCODE_DB overrides before every other source", () => {
+        const { openCodeDir } = useDataHome();
+        const absolute = join(openCodeDir, "elsewhere.db");
+        process.env.OPENCODE_DB = absolute;
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "true";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: absolute,
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+
+        process.env.OPENCODE_DB = "relative.db";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "relative.db"),
+            source: "OPENCODE_DB",
+            channel: null,
+        });
+    });
+
+    it("treats OPENCODE_DB=:memory: as an explicit but absent store", () => {
+        useDataHome();
+        process.env.OPENCODE_DB = ":memory:";
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({ path: ":memory:", source: "OPENCODE_DB", channel: null });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("uses the default DB when channel databases are disabled", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_DISABLE_CHANNEL_DB = "1";
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+    });
+
+    it("honors an OPENCODE_CHANNEL visible to the plugin", () => {
+        const { openCodeDir } = useDataHome();
+        process.env.OPENCODE_CHANNEL = "dev";
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode-dev.db"),
+            source: "channel",
+            channel: "dev",
+        });
+    });
+
+    for (const selectedName of [
+        "opencode.db",
+        "opencode-local.db",
+        "opencode-dev.db",
+        "opencode-nightly.db",
+    ]) {
+        it(`discovers ${selectedName} when it is the newest existing candidate`, () => {
+            const { openCodeDir } = useDataHome();
+            const names = [
+                "opencode.db",
+                "opencode-local.db",
+                "opencode-dev.db",
+                "opencode-nightly.db",
+            ];
+            for (const [index, name] of names.entries()) {
+                createCandidate(openCodeDir, name, name === selectedName ? 10_000 : 1_000 + index);
+            }
+
+            expect(resolveOpenCodeDbPath()).toEqual({
+                path: join(openCodeDir, selectedName),
+                source: "discovered",
+                channel:
+                    selectedName === "opencode.db"
+                        ? null
+                        : selectedName.slice("opencode-".length, -".db".length),
+            });
+        });
+    }
+
+    it("uses candidate order as the deterministic tie-breaker for equal mtimes", () => {
+        const { openCodeDir } = useDataHome();
+        for (const name of ["opencode-local.db", "opencode-dev.db", "opencode.db"]) {
+            createCandidate(openCodeDir, name, 5_000);
+        }
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("returns the default path by value when no candidate exists", () => {
+        const { openCodeDir } = useDataHome();
+        const resolution = resolveOpenCodeDbPath();
+        expect(resolution).toEqual({
+            path: join(openCodeDir, "opencode.db"),
+            source: "default",
+            channel: null,
+        });
+        expect(openCodeDbPathExists(resolution)).toBe(false);
+    });
+
+    it("re-probes discovery when the memoized chosen file disappears", () => {
+        const { openCodeDir } = useDataHome();
+        const primary = createCandidate(openCodeDir, "opencode-local.db", 2_000);
+        const fallback = createCandidate(openCodeDir, "opencode.db", 1_000);
+        expect(resolveOpenCodeDbPath().path).toBe(primary);
+
+        unlinkSync(primary);
+        expect(resolveOpenCodeDbPath()).toEqual({
+            path: fallback,
+            source: "discovered",
+            channel: null,
+        });
+    });
+
+    it("formats the missing banner, status, and doctor lines by value", () => {
+        const { openCodeDir } = useDataHome();
+        const lookedFor = [
+            join(openCodeDir, "opencode.db"),
+            join(openCodeDir, "opencode-local.db"),
+            join(openCodeDir, "opencode-dev.db"),
+            join(openCodeDir, "opencode-<channel>.db"),
+        ].join(", ");
+        const resolution = resolveOpenCodeDbPath();
+
+        expect(formatOpenCodeDbMissingBanner(resolution)).toBe(
+            `Magic Context cannot find OpenCode's session database (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled until it is found; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbMissingStatusLine(resolution)).toBe(
+            `OpenCode DB: MISSING (looked for ${lookedFor}). History compaction (historian) and the mid-turn valve are disabled; set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+        expect(formatOpenCodeDbDoctorLine(resolution)).toBe(
+            `FAIL OpenCode session database: not found (looked for ${lookedFor}); set OPENCODE_DB if OpenCode stores it elsewhere.`,
+        );
+    });
+});

package/src/shared/opencode-db-path.ts

@@ -0,0 +1,215 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join } from "node:path";
+
+export type OpenCodeDbPathSource = "OPENCODE_DB" | "channel" | "default" | "discovered";
+
+export interface OpenCodeDbPathResolution {
+    path: string;
+    source: OpenCodeDbPathSource;
+    channel: string | null;
+}
+
+export interface OpenCodeDbReadFailure extends OpenCodeDbPathResolution {
+    message: string;
+}
+
+interface CachedResolution {
+    key: string;
+    resolution: OpenCodeDbPathResolution;
+    existed: boolean;
+}
+
+let cachedResolution: CachedResolution | null = null;
+let lastReadFailure: OpenCodeDbReadFailure | null = null;
+const claimedDiagnostics = new Set<string>();
+
+function openCodeDataDir(): string {
+    return join(process.env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode");
+}
+
+function environmentKey(dataDir: string): string {
+    return [
+        dataDir,
+        process.env.OPENCODE_DB ?? "",
+        process.env.OPENCODE_DISABLE_CHANNEL_DB ?? "",
+        process.env.OPENCODE_CHANNEL ?? "",
+    ].join("\0");
+}
+
+function channelPath(dataDir: string, channel: string): string {
+    return ["latest", "beta", "prod"].includes(channel)
+        ? join(dataDir, "opencode.db")
+        : join(dataDir, `opencode-${channel}.db`);
+}
+
+function discoveredCandidateNames(dataDir: string): string[] {
+    const names = ["opencode.db", "opencode-local.db", "opencode-dev.db"];
+    try {
+        const discovered = readdirSync(dataDir, { withFileTypes: true })
+            .filter((entry) => /^opencode-.+\.db$/.test(entry.name) && !names.includes(entry.name))
+            .map((entry) => entry.name)
+            .sort();
+        names.push(...discovered);
+    } catch {
+        // A missing or unreadable data directory has no discovered candidates.
+    }
+    return names;
+}
+
+function discoverOpenCodeDb(dataDir: string): OpenCodeDbPathResolution {
+    const candidates = discoveredCandidateNames(dataDir).map((name, order) => {
+        const path = join(dataDir, name);
+        try {
+            const metadata = statSync(path);
+            return metadata.isFile() ? { path, order, mtimeMs: metadata.mtimeMs } : null;
+        } catch {
+            return null;
+        }
+    });
+    const existing = candidates
+        .filter((candidate): candidate is NonNullable<typeof candidate> => candidate !== null)
+        .sort((left, right) => right.mtimeMs - left.mtimeMs || left.order - right.order)[0];
+
+    if (!existing) {
+        return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
+    }
+
+    const name = existing.path.slice(dataDir.length + 1);
+    const channel =
+        name === "opencode.db" ? null : name.slice("opencode-".length, -".db".length) || null;
+    return { path: existing.path, source: "discovered", channel };
+}
+
+function resolveFresh(dataDir: string): OpenCodeDbPathResolution {
+    const explicit = process.env.OPENCODE_DB;
+    if (explicit !== undefined && explicit.length > 0) {
+        if (explicit === ":memory:") {
+            return { path: explicit, source: "OPENCODE_DB", channel: null };
+        }
+        return {
+            path: isAbsolute(explicit) ? explicit : join(dataDir, explicit),
+            source: "OPENCODE_DB",
+            channel: null,
+        };
+    }
+
+    const disableChannelDb = process.env.OPENCODE_DISABLE_CHANNEL_DB;
+    if (disableChannelDb === "1" || disableChannelDb === "true") {
+        return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
+    }
+
+    const channel = process.env.OPENCODE_CHANNEL;
+    if (channel !== undefined && channel.length > 0) {
+        return { path: channelPath(dataDir, channel), source: "channel", channel };
+    }
+
+    return discoverOpenCodeDb(dataDir);
+}
+
+/** Resolve an explicit DB override first, then channel paths; discover candidates when the compiled channel is unknown. */
+export function resolveOpenCodeDbPath(): OpenCodeDbPathResolution {
+    const dataDir = openCodeDataDir();
+    const key = environmentKey(dataDir);
+    if (
+        cachedResolution?.key === key &&
+        (!cachedResolution.existed || existsSync(cachedResolution.resolution.path))
+    ) {
+        if (cachedResolution.existed) return cachedResolution.resolution;
+        // An absent result is re-probed so a DB created after plugin boot is detected.
+    }
+
+    const resolution = resolveFresh(dataDir);
+    cachedResolution = {
+        key,
+        resolution,
+        existed: resolution.path !== ":memory:" && existsSync(resolution.path),
+    };
+    return resolution;
+}
+
+export function openCodeDbPathExists(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): boolean {
+    return resolution.path !== ":memory:" && existsSync(resolution.path);
+}
+
+export function getOpenCodeDbProbeDescriptions(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string[] {
+    if (resolution.source === "OPENCODE_DB") return [resolution.path];
+    if (
+        resolution.source === "channel" ||
+        process.env.OPENCODE_DISABLE_CHANNEL_DB === "1" ||
+        process.env.OPENCODE_DISABLE_CHANNEL_DB === "true"
+    ) {
+        return [resolution.path];
+    }
+    const dataDir = openCodeDataDir();
+    return [
+        join(dataDir, "opencode.db"),
+        join(dataDir, "opencode-local.db"),
+        join(dataDir, "opencode-dev.db"),
+        join(dataDir, "opencode-<channel>.db"),
+    ];
+}
+
+function lookedForText(resolution: OpenCodeDbPathResolution): string {
+    return getOpenCodeDbProbeDescriptions(resolution).join(", ");
+}
+
+export function formatOpenCodeDbMissingBanner(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `Magic Context cannot find OpenCode's session database (looked for ${lookedForText(resolution)}). History compaction (historian) and the mid-turn valve are disabled until it is found; set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbMissingStatusLine(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `OpenCode DB: MISSING (looked for ${lookedForText(resolution)}). History compaction (historian) and the mid-turn valve are disabled; set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbDoctorLine(
+    resolution: OpenCodeDbPathResolution = resolveOpenCodeDbPath(),
+): string {
+    return `FAIL OpenCode session database: not found (looked for ${lookedForText(resolution)}); set OPENCODE_DB if OpenCode stores it elsewhere.`;
+}
+
+export function formatOpenCodeDbReadFailureStatusLine(failure: OpenCodeDbReadFailure): string {
+    return `OpenCode DB: READ FAILED (path=${failure.path}, source=${failure.source}) — ${failure.message}`;
+}
+
+export function recordOpenCodeDbReadFailure(
+    resolution: OpenCodeDbPathResolution,
+    error: unknown,
+): OpenCodeDbReadFailure {
+    const message = error instanceof Error ? error.message : String(error);
+    lastReadFailure = { ...resolution, message };
+    return lastReadFailure;
+}
+
+export function clearOpenCodeDbReadFailure(path?: string): void {
+    if (path === undefined || lastReadFailure?.path === path) lastReadFailure = null;
+}
+
+export function getOpenCodeDbReadFailure(): OpenCodeDbReadFailure | null {
+    return lastReadFailure;
+}
+
+export function claimOpenCodeDbDiagnosticOnce(
+    surface: string,
+    resolution: OpenCodeDbPathResolution,
+): boolean {
+    const key = `${surface}\0${resolution.path}\0${resolution.source}`;
+    if (claimedDiagnostics.has(key)) return false;
+    claimedDiagnostics.add(key);
+    return true;
+}
+
+/** Test-only reset for process memoization and once-only diagnostics. */
+export function resetOpenCodeDbPathStateForTesting(): void {
+    cachedResolution = null;
+    lastReadFailure = null;
+    claimedDiagnostics.clear();
+}

package/src/shared/pi-executable.ts

@@ -0,0 +1,20 @@
+export type PiExecutableHarnessKind = "pi" | "omp";
+
+/** Executable images recognized as Pi-compatible hosts. */
+export const PI_IMAGE_NAMES = new Set(["pi", "pi.cmd", "omp", "oh-my-pi"]);
+
+/** Classify a process title or executable path using the shared Pi image vocabulary. */
+export function piHarnessKindFromExecutable(
+    value: string | undefined,
+): PiExecutableHarnessKind | undefined {
+    const executable = (value ?? "")
+        .trim()
+        .replace(/^['"]|['"]$/g, "")
+        .replaceAll("\\", "/")
+        .split("/")
+        .at(-1)
+        ?.toLowerCase()
+        .replace(/\.(?:exe|cmd)$/, "");
+    if (!executable || !PI_IMAGE_NAMES.has(executable)) return undefined;
+    return executable === "pi" ? "pi" : "omp";
+}