Skip to content

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.yml
index 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.ts
diff --git a/packages/daemon/src/isolation.ts b/packages/daemon/src/isolation.ts
index 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.ts
index 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();
+ },
+ );
+});