@retaw106/mmc-oc 0.0.0-stage → 1.2.2

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

@@ -0,0 +1,396 @@
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+
+export type OpenCodeDbPathSource = "OPENCODE_DB" | "channel" | "default" | "discovered";
+export type OpenCodeHostGeneration = "v1" | "v2";
+export type OpenCodeStoreGeneration = OpenCodeHostGeneration | "unknown";
+
+export interface ResolveOpenCodeDbPathOptions {
+    dataHome?: string;
+    channel?: string;
+    env?: NodeJS.ProcessEnv;
+}
+
+/**
+ * Decide the host generation from the version the executable reports, never
+ * from its name (the public installer places OpenCode 2 at
+ * `~/.opencode/bin/opencode` with a tiny `opencode2` shim beside it). The raw
+ * `--version` stdout carries a program-name prefix ("opencode v2.0.12"), so the
+ * major is the first digit run, not `parseInt` of the whole string.
+ *
+ * OpenCode 2's pre-GA betas were published under the old scope as
+ * `@opencode-ai/*@0.0.0-beta-<n>` (verified: `0.0.0-beta-19234` ships the V2
+ * `host`/`promise`/`effect` contract and the `compaction` hook); at GA the line
+ * moved to `@opencode/*@2.0.x`. A major of 0 therefore does not mean 1.x: the
+ * beta and dev pre-release shapes are OpenCode 2.
+ */
+export function openCodeHostGenerationFromVersion(
+    version: string | null | undefined,
+): OpenCodeHostGeneration {
+    const text = version ?? "";
+    if (/(?:^|\s|v)0\.0\.0-(?:beta|dev)-/.test(text)) return "v2";
+    const major = Number.parseInt(text.match(/\d+/)?.[0] ?? "", 10);
+    return Number.isFinite(major) && major >= 2 ? "v2" : "v1";
+}
+
+export interface OpenCodeStoreSchemaDatabase {
+    prepare(sql: string): { all(...params: unknown[]): unknown[] };
+}
+
+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(env: NodeJS.ProcessEnv = process.env, dataHome?: string): string {
+    return join(dataHome ?? env.XDG_DATA_HOME ?? join(homedir(), ".local", "share"), "opencode");
+}
+
+function environmentKey(
+    dataDir: string,
+    hostGeneration: OpenCodeHostGeneration,
+    channel: string | undefined,
+    env: NodeJS.ProcessEnv,
+): string {
+    return [
+        hostGeneration,
+        dataDir,
+        env.OPENCODE_DB ?? "",
+        env.OPENCODE_DISABLE_CHANNEL_DB ?? "",
+        channel ?? 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 resolveV1Fresh(
+    dataDir: string,
+    env: NodeJS.ProcessEnv = process.env,
+): OpenCodeDbPathResolution {
+    const explicit = 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 = env.OPENCODE_DISABLE_CHANNEL_DB;
+    if (disableChannelDb === "1" || disableChannelDb === "true") {
+        return { path: join(dataDir, "opencode.db"), source: "default", channel: null };
+    }
+
+    const channel = env.OPENCODE_CHANNEL;
+    if (channel !== undefined && channel.length > 0) {
+        return { path: channelPath(dataDir, channel), source: "channel", channel };
+    }
+
+    return discoverOpenCodeDb(dataDir);
+}
+
+/** Match OpenCode 2's filename table and strip path separators from custom channels. */
+export function sourceOpenCodeDatabaseFilename(
+    hostGeneration: OpenCodeHostGeneration,
+    channel: string,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    if (hostGeneration === "v1") {
+        const explicit = env.OPENCODE_DB;
+        if (explicit !== undefined && explicit.length > 0) return explicit;
+        if (env.OPENCODE_DISABLE_CHANNEL_DB === "1" || env.OPENCODE_DISABLE_CHANNEL_DB === "true") {
+            return "opencode.db";
+        }
+        return ["latest", "beta", "prod"].includes(channel)
+            ? "opencode.db"
+            : `opencode-${channel}.db`;
+    }
+
+    return (
+        env.OPENCODE_DB ??
+        (["latest", "dev", "beta", "next", "prod"].includes(channel) ||
+        env.OPENCODE_DISABLE_CHANNEL_DB === "1" ||
+        env.OPENCODE_DISABLE_CHANNEL_DB === "true"
+            ? "opencode.db"
+            : `opencode-${channel.replace(/[^a-zA-Z0-9._-]/g, "")}.db`)
+    );
+}
+
+function resolveV2Fresh(
+    dataDir: string,
+    channel: string,
+    env: NodeJS.ProcessEnv,
+): OpenCodeDbPathResolution {
+    const filename = sourceOpenCodeDatabaseFilename("v2", channel, env);
+    const explicit = env.OPENCODE_DB !== undefined;
+    return {
+        // OpenCode 2 uses `path.resolve(data, filename)`: an absolute
+        // OPENCODE_DB is taken as is and a relative one is resolved against
+        // the data directory. `join` would nest an absolute value under it.
+        path: filename === ":memory:" ? filename : resolve(dataDir, filename),
+        source: explicit ? "OPENCODE_DB" : env.OPENCODE_CHANNEL ? "channel" : "default",
+        channel: explicit ? null : channel,
+    };
+}
+
+/**
+ * Resolve the store for one host generation. The default is the historical v1
+ * resolver, including candidate discovery and all existing diagnostic text.
+ */
+export function resolveOpenCodeDbPath(
+    hostGeneration: OpenCodeHostGeneration = "v1",
+    options: ResolveOpenCodeDbPathOptions = {},
+): OpenCodeDbPathResolution {
+    const env = options.env ?? process.env;
+    const dataDir = openCodeDataDir(env, options.dataHome);
+    const channel = options.channel ?? env.OPENCODE_CHANNEL;
+    const key = environmentKey(dataDir, hostGeneration, channel, env);
+    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 =
+        hostGeneration === "v2"
+            ? resolveV2Fresh(dataDir, channel ?? "latest", env)
+            : resolveV1Fresh(dataDir, env);
+    cachedResolution = {
+        key,
+        resolution,
+        existed: resolution.path !== ":memory:" && existsSync(resolution.path),
+    };
+    return resolution;
+}
+
+function schemaTableNames(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): Set<string> {
+    const rows = db
+        .prepare(
+            `SELECT name FROM ${schema}.sqlite_master WHERE type = 'table' AND name IN ('message', 'part', 'session', 'project', 'session_message', 'session_v2')`,
+        )
+        .all() as Array<{ name?: unknown }>;
+    return new Set(rows.flatMap((row) => (typeof row.name === "string" ? [row.name] : [])));
+}
+
+/** Whether the schema has the legacy message tables required by v1-only readers. */
+export function hasV1MessageTables(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): boolean {
+    const tables = schemaTableNames(db, schema);
+    return tables.has("message") && tables.has("part");
+}
+
+/**
+ * Detect the persisted host schema.
+ *
+ * `session_message` does NOT identify v2: OpenCode 1.18.x ships that table beside `message`
+ * and `part` (verified against a live 1.18.30 store, pinned in this module's tests). Only the
+ * ABSENCE of the v1 message tables identifies a v2 store, so a v1 host is never mistaken for
+ * a v2 one. A store carrying neither is a host that has not written its schema yet.
+ */
+export function detectOpenCodeStoreGeneration(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): OpenCodeStoreGeneration {
+    const tables = schemaTableNames(db, schema);
+    const hasV1Messages = tables.has("message") && tables.has("part");
+    if (hasV1Messages) return "v1";
+    if (tables.has("session_message")) return "v2";
+    if (tables.has("session") || tables.has("project")) return "v1";
+    return "unknown";
+}
+
+/**
+ * A store the OpenCode 2 host migrated from a v1 store keeps the v1 `message`/`part` tables
+ * beside its own schema, so it carries BOTH generations and `detectOpenCodeStoreGeneration`
+ * (which must keep calling a 1.18.x store v1) reports v1. `session_v2` is written only by an
+ * OpenCode 2 host (1.18.x never creates it), so a store with it and `session_message` is
+ * readable by v2 readers regardless of any v1 tables it also kept.
+ */
+function hasMigratedV2Schema(tables: Set<string>): boolean {
+    return tables.has("session_message") && tables.has("session_v2");
+}
+
+/** A native OpenCode 2 store, or a v1 store an OpenCode 2 host has migrated. */
+function isOpenCodeV2Store(
+    db: OpenCodeStoreSchemaDatabase,
+    schema: "main" | "oc_backfill" = "main",
+): boolean {
+    return (
+        detectOpenCodeStoreGeneration(db, schema) === "v2" ||
+        hasMigratedV2Schema(schemaTableNames(db, schema))
+    );
+}
+
+/** Refuse before a generation-specific query can read the other host's schema. */
+export function assertOpenCodeStoreGeneration(
+    db: OpenCodeStoreSchemaDatabase,
+    expected: OpenCodeHostGeneration,
+    path: string,
+    schema: "main" | "oc_backfill" = "main",
+): void {
+    const actual = detectOpenCodeStoreGeneration(db, schema);
+    if (actual === expected) return;
+    if (expected === "v2" && isOpenCodeV2Store(db, schema)) return;
+    // A store with none of these tables has no schema YET — a host that has not written its
+    // first row, or a fresh data directory. That is "nothing to read", not a conflicting host,
+    // and readers have always treated it as empty. Refusing here made every reader throw before
+    // OpenCode created its tables, which is how this guard took down 15 host e2e tests.
+    if (actual === "unknown") return;
+    throw new Error(
+        `OpenCode store generation mismatch at ${path}: expected ${expected}, found ${actual}; refusing generation-specific database access`,
+    );
+}
+
+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/opencode-host-generation.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "bun:test";
+import { openCodeHostGenerationFromVersion } from "./opencode-db-path";
+
+// The generation is decided from the version the executable reports, never
+// from its name: the public installer puts OpenCode 2 at ~/.opencode/bin/opencode
+// with a tiny `opencode2` shim beside it, so the name says nothing. The raw
+// `--version` stdout carries a program-name prefix ("opencode v2.0.12"); a
+// parser that feeds that to Number.parseInt reads NaN and demotes every
+// standalone 2.x install to 1.x (AFT hit this on a clean VM, 2026-09-21).
+// OpenCode 2's pre-GA betas were `@opencode-ai/*@0.0.0-beta-<n>` — the V2 line
+// wearing the old scope's version string — so a major of 0 is v2, not v1.
+describe("OpenCode host generation from --version output", () => {
+    it.each([
+        ["opencode v2.0.12", "v2"],
+        ["v2.0.12", "v2"],
+        ["2.0.12", "v2"],
+        ["opencode v2.0.12\n", "v2"],
+        ["opencode 1.18.31", "v1"],
+        ["1.18.31", "v1"],
+        ["0.0.0-beta-19234", "v2"],
+        ["opencode v0.0.0-beta-19234", "v2"],
+        ["0.0.0-dev-42", "v2"],
+        ["0.9.3", "v1"],
+        [null, "v1"],
+        ["", "v1"],
+    ])("%p → %s", (raw, expected) => {
+        expect(openCodeHostGenerationFromVersion(raw)).toBe(expected);
+    });
+});

package/src/shared/pi-executable.ts

@@ -0,0 +1,20 @@
+export type PiExecutableHarnessKind = "pi";
+
+/** Executable images recognized as Pi-compatible hosts. */
+export const PI_IMAGE_NAMES = new Set(["pi", "pi.cmd"]);
+
+/** 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 "pi";
+}

package/src/shared/plugin-package-version.ts

@@ -0,0 +1,52 @@
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const PACKAGE_NAME = "@retaw106/mmc-oc";
+
+let cachedVersion: string | null | undefined;
+
+/**
+ * Version of the Magic Context package this code was loaded from.
+ *
+ * The server and the TUI each call this from their own loaded copy, and the
+ * status RPC carries the server's answer to the TUI. After an update the two
+ * can differ (OpenCode keeps running the copy it started with), and comparing
+ * the two values is how the status dialog tells the user to restart.
+ *
+ * Found by walking up from this module to the nearest `package.json` carrying
+ * the package's name, which works for the source tree, the built `dist/`
+ * bundle and an npm cache install alike. Null when no such file is readable.
+ */
+export function pluginPackageVersion(moduleUrl: string = import.meta.url): string | null {
+    const useCache = moduleUrl === import.meta.url;
+    if (useCache && cachedVersion !== undefined) return cachedVersion;
+    let found: string | null = null;
+    try {
+        let directory = dirname(fileURLToPath(moduleUrl));
+        for (let depth = 0; depth < 10; depth++) {
+            const candidate = join(directory, "package.json");
+            if (existsSync(candidate)) {
+                const parsed: unknown = JSON.parse(readFileSync(candidate, "utf8"));
+                if (
+                    typeof parsed === "object" &&
+                    parsed !== null &&
+                    "name" in parsed &&
+                    parsed.name === PACKAGE_NAME &&
+                    "version" in parsed &&
+                    typeof parsed.version === "string"
+                ) {
+                    found = parsed.version;
+                    break;
+                }
+            }
+            const parent = dirname(directory);
+            if (parent === directory) break;
+            directory = parent;
+        }
+    } catch {
+        // An unreadable or unparsable manifest leaves the version unknown.
+    }
+    if (useCache) cachedVersion = found;
+    return found;
+}

package/src/shared/project-directory-key.test.ts

@@ -0,0 +1,111 @@
+/**
+ * The RPC server files its discovery record under `projectHash(directory)` and
+ * the TUI looks it up with its own spelling of the same directory. Each pair
+ * below is one directory spelled two ways that hosts really produce; both must
+ * hash to the same discovery directory, or the TUI finds no server and the
+ * sidebar reads zero.
+ */
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdirSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+    __setCanonicalDirectoryRealpathForTests,
+    canonicalProjectDirectory,
+    projectDirectoryKey,
+} from "./project-directory-key";
+import { projectHash, rpcPortDirsForLookup } from "./rpc-utils";
+import { createTestTempDirFromPath } from "./test-temp-dir";
+
+const created: string[] = [];
+
+afterEach(() => {
+    __setCanonicalDirectoryRealpathForTests();
+    for (const dir of created.splice(0)) rmSync(dir, { recursive: true, force: true });
+});
+
+const WINDOWS_PAIRS: Array<[string, string, string]> = [
+    [
+        "drive-letter case",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup",
+        "c:\\Users\\Amministratore\\Pictures\\TGroup",
+    ],
+    [
+        "separators",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup",
+        "C:/Users/Amministratore/Pictures/TGroup",
+    ],
+    [
+        "trailing separator",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup\\",
+    ],
+    [
+        "long-path prefix",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup",
+        "\\\\?\\C:\\Users\\Amministratore\\Pictures\\TGroup",
+    ],
+    [
+        "name case",
+        "C:\\Users\\Amministratore\\Pictures\\TGroup",
+        "C:\\USERS\\amministratore\\pictures\\tgroup",
+    ],
+    ["UNC long-path prefix", "\\\\server\\share\\TGroup", "\\\\?\\UNC\\server\\share\\TGroup"],
+];
+
+describe("one discovery directory per project directory", () => {
+    for (const [name, left, right] of WINDOWS_PAIRS) {
+        test(`Windows ${name}`, () => {
+            expect(projectDirectoryKey(left)).toBe(projectDirectoryKey(right));
+            expect(projectHash(left)).toBe(projectHash(right));
+        });
+    }
+
+    test("Windows 8.3 short name resolves through the filesystem's realpath", () => {
+        // realpathSync.native expands short names on Windows; this host cannot
+        // create one, so the realpath is stood in for.
+        const long = "C:\\Users\\Amministratore\\Pictures\\Camera Roll\\VikStudio\\TGroup";
+        const short = "C:\\Users\\AMMINI~1\\Pictures\\CAMERA~1\\VikStudio\\TGroup";
+        __setCanonicalDirectoryRealpathForTests((directory) => {
+            if (directory === short || directory === long) return long;
+            throw new Error("ENOENT");
+        });
+        expect(canonicalProjectDirectory(short)).toBe(canonicalProjectDirectory(long));
+        expect(projectHash(short)).toBe(projectHash(long));
+    });
+
+    test("macOS /var and /private/var", () => {
+        const raw = createTestTempDirFromPath(join(tmpdir(), "mc-key-var-"));
+        created.push(raw);
+        const real = realpathSync(raw);
+        if (process.platform === "darwin") expect(real.startsWith("/private/")).toBe(true);
+        expect(projectHash(raw)).toBe(projectHash(real));
+    });
+
+    test("a symlinked directory and its target", () => {
+        const root = realpathSync(createTestTempDirFromPath(join(tmpdir(), "mc-key-link-")));
+        created.push(root);
+        const target = join(root, "Pictures", "project");
+        mkdirSync(target, { recursive: true });
+        const link = join(root, "linked-project");
+        symlinkSync(target, link);
+        expect(projectHash(link)).toBe(projectHash(target));
+    });
+
+    test("POSIX trailing slash", () => {
+        const root = realpathSync(createTestTempDirFromPath(join(tmpdir(), "mc-key-slash-")));
+        created.push(root);
+        expect(projectHash(`${root}/`)).toBe(projectHash(root));
+    });
+
+    test("different directories still get different discovery directories", () => {
+        expect(projectHash("C:\\Users\\A\\one")).not.toBe(projectHash("C:\\Users\\A\\two"));
+        expect(projectHash("/tmp/does-not-exist-a")).not.toBe(projectHash("/tmp/does-not-exist-b"));
+    });
+
+    test("lookups also read the pre-canonical directory older servers wrote", () => {
+        const dirs = rpcPortDirsForLookup("/storage", "C:\\Users\\A\\Proj\\");
+        expect(dirs).toHaveLength(2);
+        expect(dirs[0]).toBe(join("/storage", "rpc", projectHash("C:\\Users\\A\\Proj\\")));
+    });
+});

package/src/shared/project-directory-key.ts

@@ -0,0 +1,54 @@
+import { realpathSync } from "node:fs";
+import path from "node:path";
+
+/**
+ * Normalize Windows-formatted directory paths consistently, even on a non-Windows OS.
+ *
+ * Spelling only, no filesystem access: separators become `/`, the `\\?\` and
+ * `\\?\UNC\` long-path prefixes are dropped, a trailing separator is removed and
+ * the result is lowercased, because Windows paths are case-insensitive. A POSIX
+ * path is resolved to an absolute path, which also drops a trailing slash.
+ */
+export function projectDirectoryKey(directory: string): string {
+    const slashed = directory
+        .replaceAll("\\", "/")
+        .replace(/^\/\/\?\/UNC\//i, "//")
+        .replace(/^\/\/\?\//, "");
+    if (/^[a-z]:\//i.test(slashed) || slashed.startsWith("//")) {
+        return path.win32.normalize(slashed).replaceAll("\\", "/").replace(/\/$/, "").toLowerCase();
+    }
+    return path.resolve(directory);
+}
+
+let realpathForCanonicalDirectory: (directory: string) => string = (directory) =>
+    realpathSync.native(directory);
+
+/**
+ * One spelling for a project directory, shared by everything that has to agree
+ * on it across processes (the RPC server that writes its discovery file and the
+ * TUI that looks the file up).
+ *
+ * The filesystem's own answer comes first where the directory exists:
+ * `realpathSync.native` resolves symlinks (macOS `/var` → `/private/var`),
+ * junctions, and Windows 8.3 short names (`AMMINI~1` → the long name). The
+ * result then goes through `projectDirectoryKey`, so drive-letter case,
+ * separators, `\\?\` prefixes and trailing separators cannot make two
+ * spellings of one directory differ. A directory that cannot be resolved (it
+ * no longer exists, or access is denied) falls back to its spelling alone.
+ */
+export function canonicalProjectDirectory(directory: string): string {
+    let resolved = directory;
+    try {
+        resolved = realpathForCanonicalDirectory(directory);
+    } catch {
+        // Keep the given spelling; the key below still normalizes it.
+    }
+    return projectDirectoryKey(resolved);
+}
+
+/** Test seam: stand in for the filesystem's realpath (for example Windows 8.3 expansion). */
+export function __setCanonicalDirectoryRealpathForTests(
+    realpath?: (directory: string) => string,
+): void {
+    realpathForCanonicalDirectory = realpath ?? ((directory) => realpathSync.native(directory));
+}