@cortexkit/opencode-magic-context 0.36.0 → 0.37.0

package/src/shared/rpc-utils.test.ts

@@ -6,6 +6,9 @@ import type { readFileSync } from "node:fs";
 import {
     __resetRpcIdentityTestHooks,
     __setRpcIdentityTestHooks,
+    discoverLivePiProcessIds,
+    inspectLivePiProcesses,
+    isPidAlive,
     isPidIdentityPlausible,
     type RpcPortFileRecord,
 } from "./rpc-utils";
@@ -40,10 +43,148 @@ function psOutput(output: string | Error): typeof execFileSync {
     }) as typeof execFileSync;
 }
 
+function tasklistOutput(entries: Array<[number, string]>): string {
+    return [
+        '"Image Name","PID","Session Name","Session#","Mem Usage"',
+        ...entries.map(([pid, command]) => `"${command}","${pid}","Console","1","10,000 K"`),
+    ].join("\r\n");
+}
+
 afterEach(() => {
     __resetRpcIdentityTestHooks();
 });
 
+describe("discoverLivePiProcessIds", () => {
+    test("finds Pi-family harness commands while excluding the current process", () => {
+        __setRpcIdentityTestHooks({
+            processListExecFileSync: (() =>
+                [
+                    ` ${process.pid} /usr/local/bin/pi`,
+                    " 41001 /usr/local/bin/pi --model test",
+                    " 41002 node /opt/node_modules/@mariozechner/pi-coding-agent/dist/cli.js",
+                    " 41003 bun /opt/node_modules/@oh-my-pi/pi-coding-agent/dist/cli.js",
+                    " 41004 /Applications/OpenCode.app/Contents/MacOS/opencode",
+                    " 41005 node /workspace/pi-plugin/src/index.ts",
+                    " 41006 npm install @earendil-works/pi-coding-agent",
+                    " 41007 /usr/local/bin/omp --model test",
+                ].join("\n")) as typeof execFileSync,
+        });
+
+        expect(discoverLivePiProcessIds()).toEqual([41001, 41002, 41003, 41007]);
+    });
+
+    test("reports uncertainty instead of treating an unavailable process list as empty", () => {
+        __setRpcIdentityTestHooks({
+            processListExecFileSync: (() => {
+                throw new Error("ps unavailable");
+            }) as typeof execFileSync,
+        });
+
+        expect(inspectLivePiProcesses()).toEqual({
+            state: "unreadable",
+            processIds: [],
+            error: "ps unavailable",
+        });
+    });
+
+    test("uses tasklist instead of ps on Windows", () => {
+        const calls: string[] = [];
+        __setRpcIdentityTestHooks({
+            platform: "win32",
+            processListExecFileSync: ((file: string | URL) => {
+                calls.push(String(file));
+                return tasklistOutput([
+                    [process.pid, "pi.exe"],
+                    [41001, "pi.exe"],
+                    [41002, "opencode.exe"],
+                ]);
+            }) as typeof execFileSync,
+        });
+
+        expect(inspectLivePiProcesses()).toEqual({
+            state: "known",
+            processIds: [41001],
+        });
+        expect(calls).toEqual(["tasklist"]);
+    });
+});
+
+describe("isPidAlive", () => {
+    test("distinguishes confirmed, dead, and inaccessible PID probes", () => {
+        const probeFailure = (code: string): NodeJS.ErrnoException => {
+            const error = new Error(`kill failed: ${code}`) as NodeJS.ErrnoException;
+            error.code = code;
+            return error;
+        };
+
+        __setRpcIdentityTestHooks({
+            processKill: (() => true) as typeof process.kill,
+        });
+        expect(isPidAlive(PID)).toBe("alive");
+
+        __setRpcIdentityTestHooks({
+            processKill: (() => {
+                throw probeFailure("ESRCH");
+            }) as typeof process.kill,
+        });
+        expect(isPidAlive(PID)).toBe("dead");
+
+        __setRpcIdentityTestHooks({
+            processKill: (() => {
+                throw probeFailure("EPERM");
+            }) as typeof process.kill,
+        });
+        expect(isPidAlive(PID)).toBe("inconclusive");
+    });
+
+    test("uses tasklist for Windows liveness and captures probe stderr", () => {
+        const calls: Array<{ file: string; args: readonly string[]; stdio: unknown }> = [];
+        __setRpcIdentityTestHooks({
+            platform: "win32",
+            execFileSync: ((
+                file: string | URL,
+                args: readonly string[] = [],
+                options: { stdio?: unknown } = {},
+            ) => {
+                calls.push({ file: String(file), args, stdio: options.stdio });
+                if (String(file) === "ps") throw new Error("ps must not run on Windows");
+                return tasklistOutput([[PID, "OpenCode.exe"]]);
+            }) as typeof execFileSync,
+        });
+
+        expect(isPidAlive(PID)).toBe("alive");
+        expect(calls).toEqual([
+            {
+                file: "tasklist",
+                args: ["/FO", "CSV", "/FI", `PID eq ${PID}`],
+                stdio: ["ignore", "pipe", "pipe"],
+            },
+        ]);
+    });
+
+    test("treats a successful tasklist no-match response as dead", () => {
+        __setRpcIdentityTestHooks({
+            platform: "win32",
+            execFileSync: (() =>
+                "INFO: No tasks are running which match the specified criteria.") as typeof execFileSync,
+        });
+
+        expect(isPidAlive(PID)).toBe("dead");
+    });
+
+    test("returns inconclusive when the Windows tasklist probe cannot spawn", () => {
+        __setRpcIdentityTestHooks({
+            platform: "win32",
+            execFileSync: (() => {
+                throw new Error("tasklist unavailable");
+            }) as typeof execFileSync,
+        });
+
+        expect(isPidAlive(PID)).toBe("inconclusive");
+        expect(isPidIdentityPlausible(record(0))).toBe("inconclusive");
+    });
+});
+
 describe("isPidIdentityPlausible", () => {
     test("rejects a reused Linux PID when proc start time is substantially newer", () => {
         const readPaths: string[] = [];
@@ -63,7 +204,7 @@ describe("isPidIdentityPlausible", () => {
             }) as typeof execFileSync,
         });
 
-        expect(isPidIdentityPlausible(record(500_000))).toBe(false);
+        expect(isPidIdentityPlausible(record(500_000))).toBe("implausible");
         expect(readPaths).toEqual([`/proc/${PID}/stat`, "/proc/uptime"]);
     });
 
@@ -79,10 +220,10 @@ describe("isPidIdentityPlausible", () => {
 
         // The mocked process start is 1,100,000ms. The 120s tolerance is part of
         // the contract because port-file creation follows process startup.
-        expect(isPidIdentityPlausible(record(1_000_000))).toBe(true);
+        expect(isPidIdentityPlausible(record(1_000_000))).toBe("plausible");
     });
 
-    test("treats an unreadable Linux start-time probe as live", () => {
+    test("reports an unreadable Linux start-time probe as inconclusive", () => {
         __setRpcIdentityTestHooks({
             platform: "linux",
             readFileSync: linuxFiles({
@@ -90,17 +231,17 @@ describe("isPidIdentityPlausible", () => {
             }),
         });
 
-        expect(isPidIdentityPlausible(record(500_000))).toBe(true);
+        expect(isPidIdentityPlausible(record(500_000))).toBe("inconclusive");
     });
 
-    test("uses the legacy Linux command fallback and fails closed on probe errors", () => {
+    test("uses the legacy Linux command fallback and distinguishes probe errors", () => {
         __setRpcIdentityTestHooks({
             platform: "linux",
             readFileSync: linuxFiles({
                 [`/proc/${PID}/cmdline`]: "/usr/sbin/opendkim --config /etc/opendkim.conf",
             }),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(false);
+        expect(isPidIdentityPlausible(record(0))).toBe("implausible");
 
         __setRpcIdentityTestHooks({
             platform: "linux",
@@ -108,7 +249,7 @@ describe("isPidIdentityPlausible", () => {
                 [`/proc/${PID}/cmdline`]: "/usr/local/bin/opencode serve",
             }),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(true);
+        expect(isPidIdentityPlausible(record(0))).toBe("plausible");
 
         __setRpcIdentityTestHooks({
             platform: "linux",
@@ -116,7 +257,7 @@ describe("isPidIdentityPlausible", () => {
                 [`/proc/${PID}/cmdline`]: new Error("procfs unavailable"),
             }),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(true);
+        expect(isPidIdentityPlausible(record(0))).toBe("inconclusive");
     });
 
     test("uses ps start time and command probes on non-Linux platforms", () => {
@@ -126,7 +267,7 @@ describe("isPidIdentityPlausible", () => {
         });
         expect(
             isPidIdentityPlausible(record(Date.parse("Mon Aug  7 00:00:00 1970") - 121_000)),
-        ).toBe(false);
+        ).toBe("implausible");
 
         __setRpcIdentityTestHooks({
             platform: "darwin",
@@ -134,24 +275,43 @@ describe("isPidIdentityPlausible", () => {
         });
         expect(
             isPidIdentityPlausible(record(Date.parse("Mon Aug  7 00:00:00 1970") - 120_000)),
-        ).toBe(true);
+        ).toBe("plausible");
 
         __setRpcIdentityTestHooks({
             platform: "darwin",
             execFileSync: psOutput("/usr/sbin/opendkim -f"),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(false);
+        expect(isPidIdentityPlausible(record(0))).toBe("implausible");
 
         __setRpcIdentityTestHooks({
             platform: "darwin",
             execFileSync: psOutput("/Applications/OpenCode.app/Contents/MacOS/opencode"),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(true);
+        expect(isPidIdentityPlausible(record(0))).toBe("plausible");
 
         __setRpcIdentityTestHooks({
             platform: "darwin",
             execFileSync: psOutput(new Error("ps unavailable")),
         });
-        expect(isPidIdentityPlausible(record(0))).toBe(true);
+        expect(isPidIdentityPlausible(record(0))).toBe("inconclusive");
+    });
+
+    test("uses tasklist for the Windows command fallback and skips unavailable start time", () => {
+        const calls: Array<{ file: string; args: readonly string[] }> = [];
+        __setRpcIdentityTestHooks({
+            platform: "win32",
+            execFileSync: ((file: string | URL, args: readonly string[] = []) => {
+                calls.push({ file: String(file), args });
+                if (String(file) === "ps") throw new Error("ps must not run on Windows");
+                return tasklistOutput([[PID, "OpenCode.exe"]]);
+            }) as typeof execFileSync,
+        });
+
+        expect(isPidIdentityPlausible(record(0))).toBe("plausible");
+        expect(calls).toEqual([{ file: "tasklist", args: ["/FO", "CSV", "/FI", `PID eq ${PID}`] }]);
+
+        calls.length = 0;
+        expect(isPidIdentityPlausible(record(NOW_MS))).toBe("inconclusive");
+        expect(calls).toEqual([]);
     });
 });

package/src/shared/rpc-utils.ts

@@ -50,13 +50,22 @@ export function legacyRpcPortFilePath(storageDir: string, directory: string): st
     return join(rpcPortDir(storageDir, directory), "port");
 }
 
-export function isPidAlive(pid: number): boolean {
-    if (!Number.isInteger(pid) || pid <= 0) return false;
+export type PidLiveness = "alive" | "dead" | "inconclusive";
+
+/**
+ * Check whether the platform confirms a PID is live without treating a denied
+ * probe as confirmation. Windows uses tasklist because MSYS2/Cygwin ps does not
+ * support the options used by the Unix probe. Sandboxes commonly reject
+ * `kill(pid, 0)` with EPERM even when the PID does not exist outside their view.
+ */
+export function isPidAlive(pid: number): PidLiveness {
+    if (!Number.isInteger(pid) || pid <= 0) return "dead";
+    if (rpcIdentityPlatform === "win32") return readWindowsProcess(pid).state;
     try {
-        process.kill(pid, 0);
-        return true;
-    } catch (err) {
-        return (err as NodeJS.ErrnoException).code === "EPERM";
+        rpcIdentityProcessKill(pid, 0);
+        return "alive";
+    } catch (error) {
+        return (error as NodeJS.ErrnoException).code === "ESRCH" ? "dead" : "inconclusive";
     }
 }
 
@@ -64,9 +73,14 @@ const RPC_IDENTITY_SKEW_TOLERANCE_MS = 120_000;
 const LINUX_CLOCK_TICKS_PER_SECOND = 100;
 const PS_PROBE_TIMEOUT_MS = 1_000;
 const OPEN_CODE_COMMAND_MARKERS = ["opencode", "node", "bun", "electron"];
+const TASKLIST_NO_TASKS_PATTERN =
+    /^INFO:\s+No tasks are running which match the specified criteria\.?$/im;
 
 let rpcIdentityReadFileSync: typeof readFileSync = readFileSync;
 let rpcIdentityExecFileSync: typeof execFileSync = execFileSync;
+let rpcIdentityProcessKill: typeof process.kill = process.kill;
+let rpcProcessListExecFileSync: typeof execFileSync = execFileSync;
+let rpcProcessListTestOverride = false;
 let rpcIdentityPlatform: NodeJS.Platform = process.platform;
 let rpcIdentityNowMs: () => number = () => Date.now();
 
@@ -114,6 +128,7 @@ function readPsProcessStartTime(pid: number): number | null {
         const output = rpcIdentityExecFileSync("ps", ["-p", String(pid), "-o", "lstart="], {
             encoding: "utf8",
             timeout: PS_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
         });
         const processStartTime = Date.parse(String(output).trim());
         return Number.isFinite(processStartTime) ? processStartTime : null;
@@ -122,6 +137,72 @@ function readPsProcessStartTime(pid: number): number | null {
     }
 }
 
+interface ProcessListEntry {
+    pid: number;
+    command: string;
+}
+
+function parseCsvLine(line: string): string[] | null {
+    const fields: string[] = [];
+    let field = "";
+    let quoted = false;
+    for (let index = 0; index < line.length; index += 1) {
+        const character = line[index];
+        if (character === '"') {
+            if (quoted && line[index + 1] === '"') {
+                field += '"';
+                index += 1;
+            } else {
+                quoted = !quoted;
+            }
+        } else if (character === "," && !quoted) {
+            fields.push(field);
+            field = "";
+        } else {
+            field += character;
+        }
+    }
+    if (quoted) return null;
+    fields.push(field);
+    return fields;
+}
+
+function parseTasklistOutput(output: string): ProcessListEntry[] | null {
+    const entries: ProcessListEntry[] = [];
+    let sawHeader = false;
+    for (const rawLine of output.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line) continue;
+        if (TASKLIST_NO_TASKS_PATTERN.test(line)) return [];
+        const fields = parseCsvLine(line);
+        if (!fields) continue;
+        if (fields[1]?.trim().toLowerCase() === "pid") {
+            sawHeader = true;
+            continue;
+        }
+        const pid = Number(fields[1]);
+        if (!Number.isInteger(pid) || pid <= 0 || !fields[0]) continue;
+        entries.push({ pid, command: fields[0] });
+    }
+    return entries.length > 0 || sawHeader ? entries : null;
+}
+
+function readWindowsProcess(pid: number): { state: PidLiveness; command?: string } {
+    try {
+        const output = rpcIdentityExecFileSync("tasklist", ["/FO", "CSV", "/FI", `PID eq ${pid}`], {
+            encoding: "utf8",
+            timeout: PS_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const entries = parseTasklistOutput(String(output));
+        if (entries === null) return { state: "inconclusive" };
+        const process = entries.find((entry) => entry.pid === pid);
+        return process ? { state: "alive", command: process.command } : { state: "dead" };
+    } catch {
+        return { state: "inconclusive" };
+    }
+}
+
 function readLinuxProcessCommand(pid: number): string | null {
     try {
         return String(rpcIdentityReadFileSync(`/proc/${pid}/cmdline`, "utf8"));
@@ -135,6 +216,7 @@ function readPsProcessCommand(pid: number): string | null {
         const output = rpcIdentityExecFileSync("ps", ["-p", String(pid), "-o", "command="], {
             encoding: "utf8",
             timeout: PS_PROBE_TIMEOUT_MS,
+            stdio: ["ignore", "pipe", "pipe"],
         });
         return String(output);
     } catch {
@@ -151,39 +233,53 @@ function commandLooksLikeOpenCode(command: string): boolean {
  * Verify that a live PID still belongs to the process that wrote a port record.
  *
  * A PID can be reused after its original process exits. On Linux, procfs gives
- * us a process start time without spawning a helper; other platforms use `ps`
- * only on this cold database-open guard path. Legacy records without a start
- * time use a weaker command-name check, and every probe failure stays live so
- * this identity check cannot weaken the migration guard on uncertainty.
+ * us a process start time without spawning a helper; macOS and other Unix-like
+ * platforms use `ps`, while Windows uses `tasklist`, only on this cold
+ * database-open guard path. Legacy records without a start time use a weaker
+ * command-name check. A failed filesystem or process probe is inconclusive,
+ * not proof that this port record still belongs to OpenCode.
  */
-export function isPidIdentityPlausible(record: RpcPortFileRecord): boolean {
-    if (!Number.isInteger(record.pid) || record.pid <= 0) return false;
+export type PidIdentityPlausibility = "plausible" | "implausible" | "inconclusive";
+
+export function isPidIdentityPlausible(record: RpcPortFileRecord): PidIdentityPlausibility {
+    if (!Number.isInteger(record.pid) || record.pid <= 0) return "implausible";
 
     if (Number.isFinite(record.started_at) && record.started_at > 0) {
         const processStartTime =
             rpcIdentityPlatform === "linux"
                 ? readLinuxProcessStartTime(record.pid)
-                : readPsProcessStartTime(record.pid);
-        if (processStartTime === null) return true;
-        return processStartTime <= record.started_at + RPC_IDENTITY_SKEW_TOLERANCE_MS;
+                : rpcIdentityPlatform === "win32"
+                  ? null
+                  : readPsProcessStartTime(record.pid);
+        if (processStartTime === null) return "inconclusive";
+        return processStartTime <= record.started_at + RPC_IDENTITY_SKEW_TOLERANCE_MS
+            ? "plausible"
+            : "implausible";
     }
 
     const command =
         rpcIdentityPlatform === "linux"
             ? readLinuxProcessCommand(record.pid)
-            : readPsProcessCommand(record.pid);
-    if (command === null) return true;
-    return commandLooksLikeOpenCode(command);
+            : rpcIdentityPlatform === "win32"
+              ? (readWindowsProcess(record.pid).command ?? null)
+              : readPsProcessCommand(record.pid);
+    if (command === null) return "inconclusive";
+    return commandLooksLikeOpenCode(command) ? "plausible" : "implausible";
 }
 
 export function __setRpcIdentityTestHooks(hooks: {
     readFileSync?: typeof readFileSync;
     execFileSync?: typeof execFileSync;
+    processKill?: typeof process.kill;
+    processListExecFileSync?: typeof execFileSync;
     platform?: NodeJS.Platform;
     nowMs?: () => number;
 }): void {
     rpcIdentityReadFileSync = hooks.readFileSync ?? readFileSync;
     rpcIdentityExecFileSync = hooks.execFileSync ?? execFileSync;
+    rpcIdentityProcessKill = hooks.processKill ?? process.kill;
+    rpcProcessListExecFileSync = hooks.processListExecFileSync ?? execFileSync;
+    rpcProcessListTestOverride = hooks.processListExecFileSync !== undefined;
     rpcIdentityPlatform = hooks.platform ?? process.platform;
     rpcIdentityNowMs = hooks.nowMs ?? (() => Date.now());
 }
@@ -191,10 +287,98 @@ export function __setRpcIdentityTestHooks(hooks: {
 export function __resetRpcIdentityTestHooks(): void {
     rpcIdentityReadFileSync = readFileSync;
     rpcIdentityExecFileSync = execFileSync;
+    rpcIdentityProcessKill = process.kill;
+    rpcProcessListExecFileSync = execFileSync;
+    rpcProcessListTestOverride = false;
     rpcIdentityPlatform = process.platform;
     rpcIdentityNowMs = () => Date.now();
 }
 
+function commandLooksLikePi(command: string): boolean {
+    const normalized = command.trim().toLowerCase().replaceAll("\\", "/");
+    const tokens = normalized.split(/\s+/).filter(Boolean);
+    const executableName = (token: string | undefined): string =>
+        (token ?? "").split("/").at(-1) ?? "";
+    const first = executableName(tokens[0]).replace(/\.exe$/, "");
+    if (["pi", "pi.cmd", "omp", "oh-my-pi"].includes(first)) return true;
+    if (["node", "bun", "deno"].includes(first)) {
+        const script = executableName(tokens[1]);
+        return (
+            ["pi", "pi.js", "pi.mjs", "pi.cjs"].includes(script) ||
+            normalized.includes("pi-coding-agent")
+        );
+    }
+    return false;
+}
+
+/** Result of checking whether Pi/OMP processes may currently hold the shared database. */
+export interface PiProcessDiscovery {
+    state: "known" | "unreadable";
+    processIds: number[];
+    error?: string;
+}
+
+/**
+ * Inspect Pi/OMP processes without converting a failed process-list probe into
+ * false evidence that no harness is running. Callers choose their own policy
+ * for the unreadable state: destructive maintenance can fail closed, while a
+ * migration guard can proceed after reporting that no live Pi process was confirmed.
+ */
+export function inspectLivePiProcesses(): PiProcessDiscovery {
+    if (process.env.NODE_ENV === "test" && !rpcProcessListTestOverride) {
+        return { state: "known", processIds: [] };
+    }
+    try {
+        const isWindows = rpcIdentityPlatform === "win32";
+        const output = String(
+            rpcProcessListExecFileSync(
+                isWindows ? "tasklist" : "ps",
+                isWindows ? ["/FO", "CSV"] : ["-axo", "pid=,command="],
+                {
+                    encoding: "utf8",
+                    timeout: PS_PROBE_TIMEOUT_MS,
+                    stdio: ["ignore", "pipe", "pipe"],
+                },
+            ),
+        );
+        const pids = new Set<number>();
+        if (isWindows) {
+            const entries = parseTasklistOutput(output);
+            if (entries === null) {
+                return {
+                    state: "unreadable",
+                    processIds: [],
+                    error: "tasklist output unavailable",
+                };
+            }
+            for (const entry of entries) {
+                if (entry.pid === process.pid) continue;
+                if (commandLooksLikePi(entry.command)) pids.add(entry.pid);
+            }
+        } else {
+            for (const line of output.split(/\r?\n/)) {
+                const match = /^\s*(\d+)\s+(.+)$/.exec(line);
+                if (!match) continue;
+                const pid = Number(match[1]);
+                if (!Number.isInteger(pid) || pid <= 0 || pid === process.pid) continue;
+                if (commandLooksLikePi(match[2])) pids.add(pid);
+            }
+        }
+        return { state: "known", processIds: [...pids].sort((left, right) => left - right) };
+    } catch (error) {
+        return {
+            state: "unreadable",
+            processIds: [],
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+
+/** Enumerate live Pi/OMP harness processes before deciding whether migration can proceed. */
+export function discoverLivePiProcessIds(): number[] {
+    return inspectLivePiProcesses().processIds;
+}
+
 export function parseRpcPortFile(content: string, fallbackPid = 0): RpcPortFileRecord | null {
     const trimmed = content.trim();
     if (!trimmed) return null;

package/src/shared/tui-preferences.test.ts

@@ -1,9 +1,11 @@
 import { afterEach, beforeEach, describe, expect, test } from "bun:test";
-import { mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
+import { mkdtemp, readFile, rename, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { join } from "node:path";
+import { basename, join } from "node:path";
 import { parse } from "comment-json";
 import {
+    __resetTuiPreferencesWatchTestHooks,
+    __setTuiPreferencesWatchTestHooks,
     computeEffectiveOrder,
     DEFAULT_PREFS,
     DEFAULT_SLOT_ORDER,
@@ -13,6 +15,7 @@ import {
     readTuiPreferencesFile,
     resolveMagicContextPrefs,
     TUI_PREFS_FILE_ENV,
+    watchTuiPreferences,
 } from "./tui-preferences";
 
 let dir: string;
@@ -28,6 +31,7 @@ beforeEach(async () => {
 });
 
 afterEach(async () => {
+    __resetTuiPreferencesWatchTestHooks();
     for (const key of ENV_KEYS) {
         if (savedEnv[key] === undefined) delete process.env[key];
         else process.env[key] = savedEnv[key];
@@ -79,6 +83,52 @@ describe("readTuiPreferencesFile (tolerant)", () => {
     });
 });
 
+describe("watchTuiPreferences", () => {
+    test("notifies when the initial read resolves after an atomic replacement", async () => {
+        const previous = `{"magic-context":{"sections":{"memory":true}}}\n`;
+        const next = `{"magic-context":{"sections":{"memory":false}}}\n`;
+        await writeFile(file, previous, "utf8");
+
+        let resolveInitialRead!: (text: string) => void;
+        const pendingInitialRead = new Promise<string>((resolve) => {
+            resolveInitialRead = resolve;
+        });
+        let emitWatchEvent!: (event: string, filename: string | null) => void;
+        let readCount = 0;
+        __setTuiPreferencesWatchTestHooks({
+            readFile: () => {
+                readCount += 1;
+                return readCount === 1 ? pendingInitialRead : Promise.resolve(next);
+            },
+            watch: (_directory, listener) => {
+                emitWatchEvent = listener;
+                return { close() {} };
+            },
+        });
+
+        const observed = new Promise<{ memory: boolean }>((resolve) => {
+            const stop = watchTuiPreferences(() => {
+                void readTuiPreferencesFile().then((root) => {
+                    stop();
+                    resolve({ memory: resolveMagicContextPrefs(root).sections.memory });
+                });
+            });
+        });
+
+        const replacement = `${file}.external.tmp`;
+        await writeFile(replacement, next, "utf8");
+        await rename(replacement, file);
+        emitWatchEvent("rename", basename(file));
+        resolveInitialRead(next);
+
+        const result = await Promise.race([
+            observed,
+            new Promise<"timeout">((resolve) => setTimeout(() => resolve("timeout"), 300)),
+        ]);
+        expect(result).toEqual({ memory: false });
+    });
+});
+
 describe("resolveMagicContextPrefs (per-key validation)", () => {
     test("missing key → full defaults clone", () => {
         expect(resolveMagicContextPrefs({})).toEqual(DEFAULT_PREFS);