Skip to content

A personal assistant that lives on your desktop, remembers what matters, and can use your Mac for you.

TypeScript

feat(daemon): managed Windows fd3 startup and CLI shutdown exit code

Marcelitobf609b4dbcef
diff --git a/packages/daemon/src/windows-stop.ts b/packages/daemon/src/windows-stop.ts
index 00194c2..d75fbac 100644
--- a/packages/daemon/src/windows-stop.ts
+++ b/packages/daemon/src/windows-stop.ts
@@ -1,6 +1,7 @@
import { timingSafeEqual } from "node:crypto";
import { createRequire } from "node:module";
import { fileURLToPath } from "node:url";
+import { WindowsAppChannel, type WindowsAppChannelCloseResult } from "./windows-app-channel.ts";
interface StopListener {
capability: Buffer;
@@ -54,6 +55,81 @@ async function closeDaemonAndListener(daemon: Stoppable, listener: StopListener)
if (daemonFailed) throw originalError;
}
+interface AppTransport {
+ close(mode: "drain" | "abort"): Promise<WindowsAppChannelCloseResult>;
+}
+
+/** Supported Windows CLI route: native stop-record validation precedes fd3
+ * adoption, and BOTH precede start/privateMemory/descendants. The record only
+ * admits the managed launch route; the adopted connection authenticates app IPC.
+ * Injection replaces orchestration participants, never production startup facts. */
+export async function startWithWindowsAppChannel<
+ T extends Stoppable,
+ C extends AppTransport = WindowsAppChannel,
+>(
+ recordPath: string,
+ start: (channel: C) => Promise<T>,
+ options: StopOptions & { createAppChannel?: () => C } = {},
+): Promise<{ daemon: T; close(): Promise<void>; closed: Promise<void> }> {
+ const managed = await startWithWindowsStop(
+ recordPath,
+ async () => {
+ const channel = options.createAppChannel
+ ? options.createAppChannel()
+ : (new WindowsAppChannel({ exclusiveFd3Startup: true }) as unknown as C);
+ let daemon: T;
+ try {
+ daemon = await start(channel);
+ } catch (error) {
+ try {
+ await channel.close("abort");
+ } catch {
+ failedWindowsOwners.add(channel);
+ }
+ throw error;
+ }
+ let stopping: Promise<void> | undefined;
+ const owner = {
+ daemon,
+ closed: daemon.closed,
+ close(): Promise<void> {
+ if (!stopping)
+ stopping = Promise.resolve().then(async () => {
+ let failed = false;
+ let firstError: unknown;
+ try {
+ await daemon.close();
+ } catch (error) {
+ failed = true;
+ firstError = error;
+ }
+ // Real daemon.close also drains its AppChannel. Idempotence keeps
+ // this independent fallback safe, including partial close failure.
+ try {
+ const result = await channel.close("drain");
+ if (result.mode !== "drain" || result.drained !== true)
+ throw new Error("Windows app channel was not drained.");
+ } catch (error) {
+ if (!failed) {
+ failed = true;
+ firstError = error;
+ }
+ }
+ if (failed) {
+ failedWindowsOwners.add(owner);
+ throw firstError;
+ }
+ });
+ return stopping;
+ },
+ };
+ return owner;
+ },
+ options,
+ );
+ return { daemon: managed.daemon.daemon, close: managed.close, closed: managed.closed };
+}
+
/** Source lives in src/, while the bundle lives directly in daemon/. */
export function windowsStopArtifact(entry = new URL(import.meta.url)): URL {
return new URL(
@@ -62,6 +138,29 @@ export function windowsStopArtifact(entry = new URL(import.meta.url)): URL {
);
}
+/** The CLI's Windows exit arbiter observes the combined close/drain result, not daemon.closed. */
+export function windowsShutdownExitCode(owner: { closed: Promise<void> }): Promise<0 | 1> {
+ return owner.closed.then(
+ () => 0,
+ () => 1,
+ );
+}
+
+/** Failure sets status and retains ownership; it must not force process termination. */
+export async function finishWindowsShutdown(
+ owner: { closed: Promise<void> },
+ processLike: { exit(code: number): void; exitCode: NodeJS.Process["exitCode"] } = process,
+ log: (line: string) => void = () => {},
+): Promise<void> {
+ if ((await windowsShutdownExitCode(owner)) === 0) {
+ processLike.exit(0);
+ } else {
+ failedWindowsOwners.add(owner);
+ processLike.exitCode = 1;
+ log("the assistant did not stop cleanly; retaining failed owner");
+ }
+}
+
/**
* Install the authenticated listener before start() can create descendants. Windows startup
* always requires the private, exact-current-process record validated by the native module.
@@ -97,7 +196,12 @@ export async function startWithWindowsStop<T extends Stoppable>(
void startup.catch(() => {});
const close = (): Promise<void> => {
if (!stopping) {
- stopping = startup.then((daemon) => closeDaemonAndListener(daemon, listener as StopListener));
+ stopping = startup.then((daemon) => {
+ // startup resolves only after the listener is assigned, so this guard never fires.
+ const activeListener = listener;
+ if (!activeListener) throw new Error("Windows stop listener missing after startup");
+ return closeDaemonAndListener(daemon, activeListener);
+ });
void stopping.then(stopped, (error) => {
failedWindowsOwners.add(lifetimeOwner);
failed(error);
diff --git a/packages/daemon/test/windows-stop.test.ts b/packages/daemon/test/windows-stop.test.ts
index e7543c9..66ae100 100644
--- a/packages/daemon/test/windows-stop.test.ts
+++ b/packages/daemon/test/windows-stop.test.ts
@@ -1,5 +1,7 @@
import { describe, expect, it, vi } from "vitest";
-import { startWithWindowsStop, windowsStopArtifact } from "../src/windows-stop.ts";
+import type { WindowsAppChannelCloseResult } from "../src/windows-app-channel.ts";
+import * as stopModule from "../src/windows-stop.ts";
+import { startWithWindowsStop, windowsShutdownExitCode, windowsStopArtifact } from "../src/windows-stop.ts";
function deferred<T>() {
let resolve!: (value: T) => void;
@@ -36,6 +38,176 @@ function fixture() {
};
}
+describe("managed Windows fd3 startup orchestration", () => {
+ it("a first abort cannot become successful managed drain or CLI exit zero", async () => {
+ const f = fixture();
+ let first: Promise<WindowsAppChannelCloseResult> | undefined;
+ const channel = {
+ close: vi.fn(
+ (mode: "drain" | "abort") => (first ??= Promise.resolve({ mode, drained: mode === "drain" })),
+ ),
+ };
+ await channel.close("abort");
+ const owner = await stopModule.startWithWindowsAppChannel("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ createAppChannel: () => channel,
+ });
+ const processLike = { exit: vi.fn(), exitCode: undefined as number | undefined };
+ const exitObserved = stopModule.finishWindowsShutdown(owner, processLike);
+ await expect(owner.close()).rejects.toThrow("not drained");
+ await expect(owner.closed).rejects.toThrow("not drained");
+ await exitObserved;
+ expect(channel.close.mock.calls.map((call) => call[0])).toEqual(["abort", "drain"]);
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ expect(processLike.exit).not.toHaveBeenCalled();
+ expect(processLike.exitCode).toBe(1);
+ });
+ it.each<WindowsAppChannelCloseResult>([
+ { mode: "drain", drained: false },
+ { mode: "abort", drained: true },
+ ])("refuses incomplete or non-drain close result %j", async (result) => {
+ const f = fixture();
+ const channel = { close: vi.fn(async () => result) };
+ const owner = await stopModule.startWithWindowsAppChannel("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ createAppChannel: () => channel,
+ });
+ await expect(owner.close()).rejects.toThrow("not drained");
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("preserves daemon failure over an earlier abort result and listener failure", async () => {
+ const f = fixture();
+ const failure = new Error("first daemon failure");
+ f.daemon.close.mockRejectedValue(failure);
+ f.listenerClose.mockRejectedValue(new Error("listener failure"));
+ const aborted: WindowsAppChannelCloseResult = { mode: "abort", drained: false };
+ const channel = { close: vi.fn(async () => aborted) };
+ const owner = await stopModule.startWithWindowsAppChannel("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ createAppChannel: () => channel,
+ });
+ await expect(owner.close()).rejects.toBe(failure);
+ await expect(owner.closed).rejects.toBe(failure);
+ expect(channel.close).toHaveBeenCalledExactlyOnceWith("drain");
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("startup failure may abort successfully without certifying drain", async () => {
+ const f = fixture();
+ const failure = new Error("startup failure");
+ const channel = {
+ close: vi.fn(async (): Promise<WindowsAppChannelCloseResult> => ({ mode: "abort", drained: false })),
+ };
+ await expect(
+ stopModule.startWithWindowsAppChannel(
+ "data/daemon.pid",
+ async () => {
+ throw failure;
+ },
+ { platform: "win32", loadNative: f.loadNative, createAppChannel: () => channel },
+ ),
+ ).rejects.toBe(failure);
+ expect(channel.close).toHaveBeenCalledExactlyOnceWith("abort");
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("validates listener, adopts, then starts; waits for channel and listener drain", async () => {
+ const f = fixture();
+ const order: string[] = [];
+ const drain = deferred<WindowsAppChannelCloseResult>();
+ const channel = { close: vi.fn(() => drain.promise) };
+ const owner = await stopModule.startWithWindowsAppChannel(
+ "data/daemon.pid",
+ async (stream) => {
+ order.push("start");
+ expect(stream).toBe(channel);
+ return f.daemon;
+ },
+ {
+ platform: "win32",
+ loadNative: () => {
+ order.push("listener");
+ return f.loadNative();
+ },
+ createAppChannel: () => {
+ order.push("adopt");
+ return channel;
+ },
+ },
+ );
+ expect(order).toEqual(["listener", "adopt", "start"]);
+ const closed = owner.close();
+ let finished = false;
+ void closed.then(() => {
+ finished = true;
+ });
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(finished).toBe(false);
+ drain.resolve({ mode: "drain", drained: true });
+ await closed;
+ expect(channel.close).toHaveBeenCalledExactlyOnceWith("drain");
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("adoption failure refuses startup, drains listener, and preserves first failure", async () => {
+ const f = fixture();
+ const failure = new Error("missing or invalid fd3");
+ const start = vi.fn();
+ f.listenerClose.mockRejectedValue(new Error("listener drain failed"));
+ await expect(
+ stopModule.startWithWindowsAppChannel("data/daemon.pid", start, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ createAppChannel: () => {
+ throw failure;
+ },
+ }),
+ ).rejects.toBe(failure);
+ expect(start).not.toHaveBeenCalled();
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("startup failure independently aborts adopted channel and drains listener", async () => {
+ const f = fixture();
+ const failure = new Error("startup failed");
+ const channel = {
+ close: vi.fn(async () => {
+ throw new Error("channel cleanup failed");
+ }),
+ };
+ await expect(
+ stopModule.startWithWindowsAppChannel(
+ "data/daemon.pid",
+ async () => {
+ throw failure;
+ },
+ { platform: "win32", loadNative: f.loadNative, createAppChannel: () => channel },
+ ),
+ ).rejects.toBe(failure);
+ expect(channel.close).toHaveBeenCalledExactlyOnceWith("abort");
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+ it("attempts channel and listener cleanup after daemon failure and preserves it", async () => {
+ const f = fixture();
+ const failure = new Error("daemon failed");
+ f.daemon.close.mockRejectedValue(failure);
+ const channel = {
+ close: vi.fn(async () => {
+ throw new Error("channel drain failed");
+ }),
+ };
+ const owner = await stopModule.startWithWindowsAppChannel("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ createAppChannel: () => channel,
+ });
+ await expect(owner.close()).rejects.toBe(failure);
+ await expect(owner.closed).rejects.toBe(failure);
+ expect(channel.close).toHaveBeenCalledTimes(1);
+ expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ });
+});
+
describe("Windows production stop bootstrap (S8, S10, S11)", () => {
it("does not load native code on Unix", async () => {
const f = fixture();
@@ -64,6 +236,7 @@ describe("Windows production stop bootstrap (S8, S10, S11)", () => {
await owner.closed;
expect(f.daemon.close).toHaveBeenCalledTimes(1);
expect(f.listenerClose).toHaveBeenCalledTimes(1);
+ expect(await windowsShutdownExitCode(owner)).toBe(0);
});
it("rejects wrong capability, version, short and extra frames without shutdown", async () => {
const f = fixture();
@@ -126,6 +299,7 @@ describe("Windows production stop bootstrap (S8, S10, S11)", () => {
});
f.done.resolve();
await expect(owner.closed).rejects.toThrow("close failed");
+ expect(await windowsShutdownExitCode(owner)).toBe(1);
expect(f.listenerClose).toHaveBeenCalledTimes(1);
});
it("attempts drain after daemon failure and preserves the original error when both fail", async () => {
@@ -220,6 +394,78 @@ describe("Windows production stop bootstrap (S8, S10, S11)", () => {
await owner.close();
expect(f.listenerClose).toHaveBeenCalledTimes(1);
});
+ it("sets a failing CLI status without forcing exit, and exits zero only after success", async () => {
+ const exit = vi.fn();
+ const processLike = { exit, exitCode: undefined as number | undefined };
+ const log = vi.fn();
+ expect(stopModule.finishWindowsShutdown).toBeTypeOf("function");
+ const f = fixture();
+ f.daemon.close.mockRejectedValue(new Error("close failed"));
+ const owner = await startWithWindowsStop("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ });
+ const observed = stopModule.finishWindowsShutdown(owner, processLike, log);
+ await expect(owner.close()).rejects.toThrow("close failed");
+ await observed;
+ expect(processLike.exitCode).toBe(1);
+ expect(exit).not.toHaveBeenCalled();
+ expect(log).toHaveBeenCalledWith("the assistant did not stop cleanly; retaining failed owner");
+ const good = fixture();
+ const success = await startWithWindowsStop("data/daemon.pid", async () => good.daemon, {
+ platform: "win32",
+ loadNative: good.loadNative,
+ });
+ const completed = stopModule.finishWindowsShutdown(success, processLike, log);
+ await success.close();
+ await completed;
+ expect(exit).toHaveBeenCalledExactlyOnceWith(0);
+ });
+ it("does not force exit when native drain rejects", async () => {
+ const f = fixture();
+ f.listenerClose.mockRejectedValue(new Error("drain failed"));
+ const owner = await startWithWindowsStop("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ });
+ const processLike = { exit: vi.fn(), exitCode: undefined as number | undefined };
+ const observed = stopModule.finishWindowsShutdown(owner, processLike);
+ await expect(owner.close()).rejects.toThrow("drain failed");
+ await observed;
+ expect(processLike.exitCode).toBe(1);
+ expect(processLike.exit).not.toHaveBeenCalled();
+ });
+ it("propagates native drain failure instead of claiming shutdown succeeded", async () => {
+ const f = fixture();
+ f.listenerClose.mockRejectedValue(new Error("drain failed"));
+ const owner = await startWithWindowsStop("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ });
+ await expect(owner.close()).rejects.toThrow("drain failed");
+ await expect(owner.closed).rejects.toThrow("drain failed");
+ expect(await windowsShutdownExitCode(owner)).toBe(1);
+ });
+ it("does not report success while native drain remains pending", async () => {
+ const f = fixture();
+ const drain = deferred<void>();
+ f.listenerClose.mockImplementation(() => drain.promise);
+ const owner = await startWithWindowsStop("data/daemon.pid", async () => f.daemon, {
+ platform: "win32",
+ loadNative: f.loadNative,
+ });
+ let exited = false;
+ void windowsShutdownExitCode(owner).then(() => {
+ exited = true;
+ });
+ const stopping = owner.close();
+ await Promise.resolve();
+ await Promise.resolve();
+ expect(exited).toBe(false);
+ drain.resolve();
+ await stopping;
+ expect(await windowsShutdownExitCode(owner)).toBe(0);
+ });
it.each(["missing module", "unsafe record"])("fails closed before startup: %s", async (reason) => {
const start = vi.fn();
await expect(