A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.
TypeScript
feat(daemon): private memory listener ownership on Windows
Marcelito700e70a19f40
diff --git a/.github/workflows/windows.yml b/.github/workflows/windows.ymlindex 87aabc7..b7fdcd1 100644--- a/.github/workflows/windows.yml+++ b/.github/workflows/windows.yml@@ -94,7 +94,7 @@ jobs:pnpm --filter @gentle-dot/daemon run build:windows-stop -- --compiler "$compiler" --headers "$inputs/node-$version/include/node" --node-lib "$inputs/node.lib"if ($LASTEXITCODE -ne 0) { throw 'Native addon build failed' }- # The portable adapter tests, the real-addon refusal tests, the agent shutdown tests, and the engine environment tests.+ # The portable adapter tests, the real-addon refusal tests, the agent shutdown tests, the engine environment tests, and the private memory lookup tests.- name: Daemon tests- run: pnpm exec vitest run packages/daemon/test/windows-stop.test.ts packages/daemon/test/windows-app-channel.test.ts packages/daemon/test/app-channel-platform.test.ts packages/daemon/test/app-channel.test.ts packages/daemon/test/app-channel-fd.test.ts packages/daemon/test/windows-app-channel-addon.test.ts packages/daemon/test/process-tree.test.ts packages/daemon/test/supervisor.test.ts packages/daemon/test/runtime.test.ts packages/daemon/test/config.test.ts packages/daemon/test/isolation.test.ts+ run: pnpm exec vitest run packages/daemon/test/windows-stop.test.ts packages/daemon/test/windows-app-channel.test.ts packages/daemon/test/app-channel-platform.test.ts packages/daemon/test/app-channel.test.ts packages/daemon/test/app-channel-fd.test.ts packages/daemon/test/windows-app-channel-addon.test.ts packages/daemon/test/process-tree.test.ts packages/daemon/test/supervisor.test.ts packages/daemon/test/runtime.test.ts packages/daemon/test/config.test.ts packages/daemon/test/isolation.test.ts packages/daemon/test/private-memory.test.tsdiff --git a/packages/daemon/src/isolation.ts b/packages/daemon/src/isolation.tsindex 332a588..3bc4286 100644--- a/packages/daemon/src/isolation.ts+++ b/packages/daemon/src/isolation.ts@@ -220,26 +220,55 @@ export function isolatedAgentEnv(return env;}+type Listener = { kind: "empty" | "failed" | "ambiguous" } | { kind: "one"; pid: number };++interface PrivateMemoryOptions {+ platform?: NodeJS.Platform;+ /** Bounded command execution seam; errors must not be reported as empty output. */+ runListenerCommand?: (+ command: string,+ args: readonly string[],+ ) => Promise<{ code: number; stdout: string; stderr: string }>;+ kill?: (pid: number, signal: "SIGTERM") => void;+ health?: (port: string) => Promise<{ instance_id?: unknown } | undefined>;+}+/**- * In private memory mode (`GENTLE_DOT_ENGRAM=private`) the engine's memory plugin starts a memory- * server on the private port, and it outlives the engine. When nothing listened on that port as the- * daemon started, the daemon caused it, so `stop()` ends it when the daemon closes: the PID that- * listens on the port, and only after its `/health` instance id matches the private data folder's- * (`<dataDir>/home/.engram/.instance-id`). Undefined outside private mode or when it already ran.+ * Owns cleanup only after confirming an empty private port before startup.+ * A failed or ambiguous lookup refuses ownership. Before termination, both the+ * private data identity and a repeated stable listener PID must match.+ * PID reuse after the final check remains possible; nothing is killed by name.*/export async function privateMemory(base: NodeJS.ProcessEnv,dataDir: string,log: (line: string) => void,access: EngineAccess = directAccess,+ options: PrivateMemoryOptions = {},): Promise<{ stop(): Promise<void> } | undefined> {if (base.GENTLE_DOT_ENGRAM !== "private") return undefined;const port = base.GENTLE_DOT_ENGRAM_PORT || PRIVATE_ENGRAM_PORT;- if ((await listeningPid(port)) !== undefined) return undefined;+ if (+ !/^\d+$/.test(port) ||+ !Number.isSafeInteger(Number(port)) ||+ Number(port) < 1 ||+ Number(port) > 65535+ ) {+ throw new Error("Cannot start private memory: port must be an integer from 1 to 65535");+ }+ const before = await listeningPid(port, options);+ if (before.kind === "one") return undefined;+ if (before.kind !== "empty") {+ throw new Error(`Cannot start private memory: ${before.kind} listener lookup on port ${port}`);+ }return {async stop() {- const pid = await listeningPid(port);- if (pid === undefined) return;+ const listener = await listeningPid(port, options);+ if (listener.kind !== "one") {+ if (listener.kind !== "empty")+ log(`cannot verify private memory listener on port ${port}; left running`);+ return;+ }let expected: string;try {const file = join(dataDir, "home", ".engram", ".instance-id");@@ -247,27 +276,91 @@ export async function privateMemory(} catch {return;}- const health = await fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2000) })- .then((response) => response.json() as Promise<{ instance_id?: unknown }>)- .catch(() => undefined);+ const health = await (options.health ?? memoryHealth)(port).catch(() => undefined);if (!expected || health?.instance_id !== expected) {log(`the memory server on port ${port} serves other data; left running`);return;}+ const again = await listeningPid(port, options);+ if (again.kind !== "one" || again.pid !== listener.pid) {+ log(`the private memory listener changed on port ${port}; left running`);+ return;+ }try {- process.kill(pid, "SIGTERM");- log(`stopped the private memory server (pid ${pid})`);- } catch {}+ (options.kill ?? process.kill)(listener.pid, "SIGTERM");+ log(`stopped the private memory server (pid ${listener.pid})`);+ } catch (error) {+ log(`could not stop private memory server (pid ${listener.pid}): ${String(error)}`);+ }},};}-/** The one PID listening on `port` on this computer (`lsof`), if any. */-function listeningPid(port: string): Promise<number | undefined> {+function memoryHealth(port: string): Promise<{ instance_id?: unknown } | undefined> {+ return fetch(`http://127.0.0.1:${port}/health`, { signal: AbortSignal.timeout(2000) })+ .then((response) => response.json() as Promise<{ instance_id?: unknown }>)+ .catch(() => undefined);+}++/**+ * How long the listener lookup may take. Windows starts PowerShell and queries CIM, which can take+ * several seconds on a busy machine (startup, many processes); a lookup that runs out is a failed+ * lookup, and private memory then refuses to start.+ */+export function listenerLookupTimeoutMs(platform: NodeJS.Platform): number {+ return platform === "win32" ? 15_000 : 5000;+}++function runListenerCommand(+ command: string,+ args: readonly string[],+): Promise<{ code: number; stdout: string; stderr: string }> {return new Promise((resolve) => {- execFile("lsof", ["-t", "-n", "-P", `-iTCP:${port}`, "-sTCP:LISTEN"], (error, stdout) => {- const pids = [...new Set(String(stdout).trim().split("\n").filter(Boolean))];- resolve(!error && pids.length === 1 && /^\d+$/.test(pids[0] ?? "") ? Number(pids[0]) : undefined);- });+ execFile(+ command,+ [...args],+ {+ encoding: "utf8",+ timeout: listenerLookupTimeoutMs(command === "powershell.exe" ? "win32" : process.platform),+ windowsHide: true,+ },+ (error, stdout, stderr) => {+ resolve({+ code: error ? (typeof error.code === "number" ? error.code : -1) : 0,+ stdout: String(stdout),+ stderr: String(stderr),+ });+ },+ );});}++/** Enumerate Windows listeners before filtering, so an unused port is not a query error. */+async function listeningPid(port: string, options: PrivateMemoryOptions): Promise<Listener> {+ const windows = (options.platform ?? process.platform) === "win32";+ const command = windows ? "powershell.exe" : "lsof";+ const args = windows+ ? [+ "-NoLogo",+ "-NoProfile",+ "-NonInteractive",+ "-Command",+ `$ErrorActionPreference='Stop'; $ProgressPreference='SilentlyContinue'; try { Get-NetTCPConnection -State Listen -ErrorAction Stop | Where-Object { $_.LocalPort -eq ${Number(port)} } | Select-Object -ExpandProperty OwningProcess } catch { [Console]::Error.WriteLine($_.Exception.Message); exit 1 }`,+ ]+ : ["-t", "-n", "-P", `-iTCP:${port}`, "-sTCP:LISTEN"];+ try {+ const result = await (options.runListenerCommand ?? runListenerCommand)(command, args);+ const text = result.stdout.trim();+ // lsof exits 1 for no matches. Missing commands, diagnostics and timeouts are failures.+ if (!windows && result.code === 1 && !text && !result.stderr.trim()) return { kind: "empty" };+ if (result.code !== 0 || result.stderr.trim()) return { kind: "failed" };+ if (!text) return { kind: "empty" };+ const values = text.split(/\r?\n/).map((value) => value.trim());+ if (values.some((value) => !/^[1-9]\d*$/.test(value) || !Number.isSafeInteger(Number(value))))+ return { kind: "failed" };+ const pids = [...new Set(values.map(Number))];+ return pids.length === 1 ? { kind: "one", pid: pids[0] as number } : { kind: "ambiguous" };+ } catch {+ return { kind: "failed" };+ }+}diff --git a/packages/daemon/test/private-memory.test.ts b/packages/daemon/test/private-memory.test.tsindex 0b600ec..0d203dd 100644--- a/packages/daemon/test/private-memory.test.ts+++ b/packages/daemon/test/private-memory.test.ts@@ -4,10 +4,11 @@// free port; nothing is stopped by name, only the PIDs this test started.import { type ChildProcess, execFileSync, spawn } from "node:child_process";import { mkdirSync, writeFileSync } from "node:fs";-import { createServer } from "node:net";+import { type AddressInfo, createServer } from "node:net";import { join } from "node:path";-import { afterEach, describe, expect, it } from "vitest";+import { afterEach, describe, expect, it, vi } from "vitest";import { startDaemon } from "../src/daemon.ts";+import { listenerLookupTimeoutMs, privateMemory } from "../src/isolation.ts";import { FAKE_AGENT, tempDir, waitFor } from "./helpers.ts";const hasLsof = (() => {@@ -99,3 +100,148 @@ describe.skipIf(!hasLsof)("private memory server (A4)", () => {expect(running(foreign)).toBe(true);});});++describe("private memory listener lookup", () => {+ it("gives Windows' PowerShell lookup time to start on a busy machine, and lsof the usual bound", () => {+ expect(listenerLookupTimeoutMs("win32")).toBe(15_000);+ expect(listenerLookupTimeoutMs("linux")).toBe(5000);+ expect(listenerLookupTimeoutMs("darwin")).toBe(5000);+ });+});++describe.runIf(process.platform === "win32")("private memory listener lookup on Windows", () => {+ it("finds a real listener through PowerShell and reports a free port as empty", async () => {+ const server = createServer();+ await new Promise<void>((done) => server.listen(0, "127.0.0.1", done));+ const port = String((server.address() as AddressInfo).port);+ const env = { GENTLE_DOT_ENGRAM: "private", GENTLE_DOT_ENGRAM_PORT: port };+ try {+ // Someone already listens (this process): private memory claims nothing.+ expect(await privateMemory(env, tempDir(), () => {})).toBeUndefined();+ } finally {+ await new Promise<void>((done) => server.close(() => done()));+ }+ // Nothing listens now: the daemon would own the server it causes to start.+ expect(await privateMemory(env, tempDir(), () => {})).toBeDefined();+ }, 60_000);+});++describe("private memory ownership safeguards", () => {+ async function fixture(+ outputs: Array<{ code: number; stdout: string; stderr?: string }>,+ instance = "owned",+ ) {+ const dataDir = tempDir();+ mkdirSync(join(dataDir, "home", ".engram"), { recursive: true });+ writeFileSync(join(dataDir, "home", ".engram", ".instance-id"), "owned\n");+ const runListenerCommand = vi.fn(async (_command: string, _args: readonly string[]) => {+ const next = outputs.shift();+ if (!next) throw new Error("unexpected lookup");+ return { stderr: "", ...next };+ });+ const kill = vi.fn();+ const health = vi.fn(async () => ({ instance_id: instance }));+ const port = String(await freePort());+ const base = { GENTLE_DOT_ENGRAM: "private", GENTLE_DOT_ENGRAM_PORT: port };+ const options = { platform: "win32" as const, runListenerCommand, kill, health };+ return { dataDir, base, options, kill, runListenerCommand, port };+ }+ const empty = { code: 0, stdout: "" };+ const one = { code: 0, stdout: "12345\r\n12345\r\n" };++ it("terminates only a stable positive PID with matching health identity", async () => {+ const f = await fixture([empty, one, one]);+ const owned = await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options);+ expect(owned).toBeDefined();+ await owned?.stop();+ expect(f.kill).toHaveBeenCalledExactlyOnceWith(12345, "SIGTERM");+ expect(f.runListenerCommand).toHaveBeenCalledTimes(3);+ expect(f.runListenerCommand.mock.calls[0]?.[0]).toBe("powershell.exe");+ });++ it.each([+ { code: 2, stdout: "", stderr: "lookup failed" },+ { code: 0, stdout: "0" },+ { code: 0, stdout: "garbage" },+ { code: 0, stdout: "12345\n12346" },+ ])("refuses uncertain startup ownership: %j", async (output) => {+ const f = await fixture([output]);+ await expect(privateMemory(f.base, f.dataDir, () => {}, undefined, f.options)).rejects.toThrow(+ "private memory",+ );+ expect(f.kill).not.toHaveBeenCalled();+ });++ it("does not claim a pre-existing listener", async () => {+ const f = await fixture([one]);+ expect(await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options)).toBeUndefined();+ expect(f.kill).not.toHaveBeenCalled();+ });++ it.each([+ { code: 2, stdout: "", stderr: "lookup failed" },+ { code: 0, stdout: "0" },+ { code: 0, stdout: "12345\n12346" },+ ])("leaves a listener alone when close lookup is uncertain: %j", async (output) => {+ const f = await fixture([empty, output]);+ await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();+ expect(f.kill).not.toHaveBeenCalled();+ });++ it("does not terminate when the PID changes after the health check", async () => {+ const f = await fixture([empty, one, { code: 0, stdout: "12346" }]);+ await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();+ expect(f.kill).not.toHaveBeenCalled();+ });++ it("does not terminate another memory instance", async () => {+ const f = await fixture([empty, one], "foreign");+ await (await privateMemory(f.base, f.dataDir, () => {}, undefined, f.options))?.stop();+ expect(f.kill).not.toHaveBeenCalled();+ });++ it("rejects a failed command instead of assuming an empty port", async () => {+ const f = await fixture([]);+ f.runListenerCommand.mockRejectedValueOnce(new Error("spawn failed"));+ await expect(privateMemory(f.base, f.dataDir, () => {}, undefined, f.options)).rejects.toThrow(+ "private memory",+ );+ expect(f.kill).not.toHaveBeenCalled();+ });++ it("preserves the Unix no-match exit code and verifies stable ownership before stopping", async () => {+ const f = await fixture([{ code: 1, stdout: "" }, one, one]);+ await (+ await privateMemory(f.base, f.dataDir, () => {}, undefined, { ...f.options, platform: "linux" })+ )?.stop();+ expect(f.kill).toHaveBeenCalledExactlyOnceWith(12345, "SIGTERM");+ expect(f.runListenerCommand.mock.calls[0]?.[0]).toBe("lsof");+ });++ it("does not terminate when health is unavailable or the stored instance id is empty", async () => {+ const f = await fixture([empty, one]);+ await (+ await privateMemory(f.base, f.dataDir, () => {}, undefined, {+ ...f.options,+ health: async () => undefined,+ })+ )?.stop();+ expect(f.kill).not.toHaveBeenCalled();+ const other = await fixture([empty, one]);+ writeFileSync(join(other.dataDir, "home", ".engram", ".instance-id"), "\n");+ await (await privateMemory(other.base, other.dataDir, () => {}, undefined, other.options))?.stop();+ expect(other.kill).not.toHaveBeenCalled();+ });++ it.each(["0", "65536", "123;exit"])(+ "rejects invalid port %s before querying or terminating anything",+ async (port) => {+ const f = await fixture([]);+ await expect(+ privateMemory({ ...f.base, GENTLE_DOT_ENGRAM_PORT: port }, f.dataDir, () => {}, undefined, f.options),+ ).rejects.toThrow("private memory");+ expect(f.runListenerCommand).not.toHaveBeenCalled();+ expect(f.kill).not.toHaveBeenCalled();+ },+ );+});