Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(daemon): add background lifecycle and canonical logging

Gus119e48df333f
diff --git a/src/daemon/README.md b/src/daemon/README.md
index 773c05f4b..e47c92b9a 100644
--- a/src/daemon/README.md
+++ b/src/daemon/README.md
@@ -155,7 +155,7 @@ src/
credentials/
credentialProxy.ts # CredentialBroker (mint/revoke/check per-voucher vouchers) + local key-swapping proxy
scripts/
- daemon.ts # DAEMON process: thin launcher — wraps `alook daemon start` for local dev
+ daemon.ts # local entry: delegates to the canonical `alook daemon` parser
```
## Host orchestration (manager + server)
@@ -311,11 +311,15 @@ curl -s -X POST http://localhost:3000/api/community/daemon/activate \
-d '{"hostname":"my-laptop","platform":"darwin","arch":"arm64"}'
# → { "credential": "cmk_…", "machineId": "cm_…", "expiresAt": null }
-# 3. Start the daemon with that credential:
-ALOOK_MACHINE_KEY=cmk_… \
-ALOOK_SERVER_URL=http://localhost:3000 \
-ALOOK_SERVER_WS_URL=ws://localhost:8789 \
-pnpm run daemon
+# 3. Start it detached (the default):
+pnpm run daemon -- start --machine-key cmk_… \
+ --server-url http://localhost:3000 \
+ --ws-url ws://localhost:8789
+
+# Keep it attached for local debugging:
+pnpm run daemon -- start --foreground --machine-key cmk_… \
+ --server-url http://localhost:3000 \
+ --ws-url ws://localhost:8789
```
A bot bound to this machine (via the community UI/API) can now be woken by
diff --git a/src/daemon/scripts/daemon.ts b/src/daemon/scripts/daemon.ts
index 0602f39dc..c5bdea13d 100644
--- a/src/daemon/scripts/daemon.ts
+++ b/src/daemon/scripts/daemon.ts
@@ -1,39 +1,23 @@
-/**
- * `pnpm run daemon` — LOCAL-DEV daemon entry.
- *
- * Thin wrapper over the published CLI's `daemon start` command so the same
- * flags work in dev (e.g. `pn daemon start --machine-key … --server-url …
- * --ws-url …`). All three flags are required — set ALOOK_MACHINE_KEY /
- * ALOOK_SERVER_URL / ALOOK_SERVER_WS_URL or pass the matching options.
- */
-import { Command } from "commander";
-import { daemonStart } from "../src/cli/daemonStart";
-import { createLogger } from "../src/logger";
+import { realpathSync } from "node:fs";
+import { pathToFileURL } from "node:url";
+import { main } from "../src/cli/index";
-const log = createLogger({ header: "@alook/daemon" });
+export function packageDaemonArgs(argv: string[]): string[] {
+ return ["daemon", ...argv];
+}
-const program = new Command();
-program
- .name("daemon")
- .description("local-dev daemon entry (wraps `alook daemon …`)");
+export async function runPackageDaemon(argv = process.argv.slice(2)): Promise<number> {
+ process.env.ALOOK_DAEMON_PACKAGE_WRAPPER = "1";
+ return main(packageDaemonArgs(argv));
+}
-program
- .command("start")
- .description("start the daemon")
- .requiredOption("--machine-key <key>", "machine key (or ALOOK_MACHINE_KEY)", process.env.ALOOK_MACHINE_KEY)
- .option("--server-url <url>", "server HTTP URL (or ALOOK_SERVER_URL)", process.env.ALOOK_SERVER_URL)
- .option("--ws-url <url>", "server WebSocket URL (or ALOOK_SERVER_WS_URL)", process.env.ALOOK_SERVER_WS_URL)
- .option("--base-dir <path>", "data directory (or ALOOK_DATA_DIR)", process.env.ALOOK_DATA_DIR)
- .action(async (opts: { machineKey: string; serverUrl?: string; wsUrl?: string; baseDir?: string }) => {
- await daemonStart({
- machineKey: opts.machineKey,
- serverUrl: opts.serverUrl,
- wsUrl: opts.wsUrl,
- baseDir: opts.baseDir,
- });
- });
+let isMainModule = false;
+try {
+ isMainModule = Boolean(process.argv[1]) && import.meta.url === pathToFileURL(realpathSync(process.argv[1]!)).href;
+} catch {
+ isMainModule = false;
+}
-program.parseAsync(process.argv).catch((e) => {
- log.error((e as Error).message ?? String(e));
- process.exit(1);
-});
+if (isMainModule) {
+ runPackageDaemon().then((code) => process.exit(code));
+}
diff --git a/src/daemon/src/cli/daemonLifecycle.real.test.ts b/src/daemon/src/cli/daemonLifecycle.real.test.ts
new file mode 100644
index 000000000..32122a367
--- /dev/null
+++ b/src/daemon/src/cli/daemonLifecycle.real.test.ts
@@ -0,0 +1,344 @@
+import { afterEach, describe, expect, it } from "vitest";
+import { execFileSync, spawn, type ChildProcess } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { daemonStart } from "./daemonStart";
+
+const packageRoot = fileURLToPath(new URL("../..", import.meta.url));
+const tsx = path.join(packageRoot, "node_modules", ".bin", "tsx");
+const cli = path.join(packageRoot, "src", "cli", "index.ts");
+const secret = "cmk_B0_REAL_PROCESS_SECRET";
+const machineId = "cm_machine_real_123456";
+const tempDirs: string[] = [];
+const spawnedProcesses = new Set<ChildProcess>();
+
+function makeBaseDir(): string {
+ const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "alook-b0-real-"));
+ tempDirs.push(baseDir);
+ const daemonsDir = path.join(baseDir, "daemons");
+ fs.mkdirSync(daemonsDir, { recursive: true, mode: 0o700 });
+ fs.writeFileSync(
+ path.join(daemonsDir, `${machineId}.credential.json`),
+ JSON.stringify({ credential: secret, machineId }),
+ { mode: 0o600 },
+ );
+ if (process.platform !== "win32") {
+ fs.chmodSync(daemonsDir, 0o777);
+ fs.chmodSync(path.join(daemonsDir, `${machineId}.credential.json`), 0o644);
+ }
+ return baseDir;
+}
+
+function makeEmptyBaseDir(): string {
+ const baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "alook-b0-real-empty-"));
+ tempDirs.push(baseDir);
+ return baseDir;
+}
+
+function cliArgs(baseDir: string, foreground = false): string[] {
+ return [
+ cli,
+ "daemon",
+ "start",
+ ...(foreground ? ["--foreground"] : []),
+ "--machine-key", secret,
+ "--server-url", "http://127.0.0.1:9",
+ "--ws-url", "ws://127.0.0.1:9",
+ "--base-dir", baseDir,
+ ];
+}
+
+function spawnCli(args: string[], env: NodeJS.ProcessEnv = {}): ChildProcess {
+ const child = spawn(tsx, args, {
+ cwd: packageRoot,
+ env: { ...process.env, ...env },
+ stdio: ["ignore", "pipe", "pipe"],
+ });
+ spawnedProcesses.add(child);
+ return child;
+}
+
+async function collect(child: ChildProcess): Promise<{ code: number | null; output: string }> {
+ let output = "";
+ child.stdout?.on("data", (chunk) => { output += String(chunk); });
+ child.stderr?.on("data", (chunk) => { output += String(chunk); });
+ return await new Promise((resolve, reject) => {
+ child.once("error", reject);
+ child.once("exit", (code) => {
+ spawnedProcesses.delete(child);
+ resolve({ code, output });
+ });
+ });
+}
+
+async function runCli(args: string[], env: NodeJS.ProcessEnv = {}): Promise<{ code: number | null; output: string }> {
+ return collect(spawnCli(args, env));
+}
+
+async function waitFor(predicate: () => boolean, timeoutMs = 30_000): Promise<void> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (predicate()) return;
+ await new Promise((resolve) => setTimeout(resolve, 25));
+ }
+ throw new Error("condition timed out");
+}
+
+function pidfile(baseDir: string): string {
+ return path.join(baseDir, "daemons", machineId, "daemon.pid");
+}
+
+function readOwner(baseDir: string): { pid: number; machineId: string; ownerToken: string } {
+ return JSON.parse(fs.readFileSync(pidfile(baseDir), "utf8"));
+}
+
+function daemonLogRecords(baseDir: string): Array<{ message: string; fields: Record<string, unknown> }> {
+ return fs.readFileSync(path.join(path.dirname(pidfile(baseDir)), "daemon.log"), "utf8")
+ .trimEnd()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+}
+
+function alive(pid: number): boolean {
+ try {
+ process.kill(pid, 0);
+ const state = execFileSync("ps", ["-p", String(pid), "-o", "stat="], { encoding: "utf8" }).trim();
+ return state.length > 0 && !state.startsWith("Z");
+ } catch {
+ return false;
+ }
+}
+
+function isDescendant(pid: number, ancestor: number): boolean {
+ let current = pid;
+ for (let depth = 0; depth < 8; depth++) {
+ if (current === ancestor) return true;
+ try {
+ const parent = Number(execFileSync("ps", ["-p", String(current), "-o", "ppid="], { encoding: "utf8" }).trim());
+ if (!Number.isInteger(parent) || parent <= 1) return false;
+ current = parent;
+ } catch {
+ return false;
+ }
+ }
+ return false;
+}
+
+async function stop(baseDir: string): Promise<void> {
+ await runCli([cli, "daemon", "stop", machineId, "--base-dir", baseDir]);
+}
+
+afterEach(async () => {
+ for (const child of spawnedProcesses) {
+ if (child.pid && alive(child.pid)) process.kill(child.pid, "SIGKILL");
+ }
+ spawnedProcesses.clear();
+ for (const baseDir of tempDirs.splice(0)) {
+ if (fs.existsSync(pidfile(baseDir))) {
+ const owner = readOwner(baseDir);
+ if (alive(owner.pid)) process.kill(owner.pid, "SIGKILL");
+ }
+ for (const file of fs.readdirSync(baseDir).filter((entry) => entry.startsWith("checkpoint-") && entry.endsWith(".json"))) {
+ const checkpoint = JSON.parse(fs.readFileSync(path.join(baseDir, file), "utf8")) as { parentPid: number; childPid: number };
+ for (const pid of [checkpoint.parentPid, checkpoint.childPid]) {
+ if (alive(pid)) process.kill(pid, "SIGKILL");
+ }
+ }
+ fs.rmSync(baseDir, { recursive: true, force: true });
+ }
+});
+
+describe("daemon lifecycle real processes", () => {
+ it("starts detached while offline, persists no secret, and stops by stable machine id", async () => {
+ const baseDir = makeBaseDir();
+ const started = await runCli(cliArgs(baseDir));
+ expect(started.code).toBe(0);
+ expect(started.output).toContain("started in background");
+ const owner = readOwner(baseDir);
+ expect(alive(owner.pid)).toBe(true);
+ expect(owner).toMatchObject({ machineId });
+ expect(JSON.stringify(owner)).not.toContain(secret);
+ expect(execFileSync("ps", ["eww", "-p", String(owner.pid), "-o", "command="], { encoding: "utf8" })).not.toContain(secret);
+ const daemonDir = path.dirname(pidfile(baseDir));
+ const logPath = path.join(daemonDir, "daemon.log");
+ expect(fs.readFileSync(logPath, "utf8")).not.toContain(secret);
+ expect(daemonLogRecords(baseDir)).toEqual(expect.arrayContaining([
+ expect.objectContaining({
+ message: "daemon startup",
+ fields: expect.objectContaining({ machineId, version: expect.any(String) }),
+ }),
+ expect.objectContaining({ message: "daemon up" }),
+ ]));
+ if (process.platform !== "win32") {
+ expect(fs.statSync(daemonDir).mode & 0o777).toBe(0o700);
+ expect(fs.statSync(pidfile(baseDir)).mode & 0o777).toBe(0o600);
+ expect(fs.statSync(logPath).mode & 0o777).toBe(0o600);
+ expect(fs.statSync(path.join(baseDir, "daemons", `${machineId}.credential.json`)).mode & 0o777).toBe(0o600);
+ }
+ await stop(baseDir);
+ await waitFor(() => !alive(owner.pid));
+ expect(fs.existsSync(pidfile(baseDir))).toBe(false);
+ }, 60_000);
+
+ it("fails a fresh bare credential offline without creating a hash-derived machine directory", async () => {
+ const baseDir = makeEmptyBaseDir();
+ const result = await runCli(cliArgs(baseDir));
+ expect(result.output).toContain("fetch failed");
+ const daemonsDir = path.join(baseDir, "daemons");
+ expect(fs.existsSync(daemonsDir) ? fs.readdirSync(daemonsDir) : []).toEqual([]);
+ }, 60_000);
+
+ it("foreground owns the final pidfile with its current pid and rejects a background contender", async () => {
+ const baseDir = makeBaseDir();
+ const foreground = spawnCli(cliArgs(baseDir, true));
+ const foregroundResult = collect(foreground);
+ await waitFor(() => fs.existsSync(pidfile(baseDir)) && fs.existsSync(path.join(path.dirname(pidfile(baseDir)), "daemon.log")));
+ const owner = readOwner(baseDir);
+ expect(isDescendant(owner.pid, foreground.pid!)).toBe(true);
+ const contender = await runCli(cliArgs(baseDir));
+ expect(contender.output).toContain("already running");
+ expect(readOwner(baseDir)).toEqual(owner);
+ foreground.kill("SIGTERM");
+ const completed = await foregroundResult;
+ expect(completed.output).toContain("daemon startup");
+ expect(completed.output).toContain("daemon up");
+ expect(daemonLogRecords(baseDir).map((record) => record.message)).toEqual(expect.arrayContaining([
+ "daemon startup",
+ "daemon up",
+ "shutting down…",
+ ]));
+ await waitFor(() => !fs.existsSync(pidfile(baseDir)));
+ }, 60_000);
+
+ it("allows exactly one winner in background↔background and foreground↔foreground races", async () => {
+ const backgroundBase = makeBaseDir();
+ const backgroundResults = await Promise.all([
+ collect(spawnCli(cliArgs(backgroundBase))),
+ collect(spawnCli(cliArgs(backgroundBase))),
+ ]);
+ expect(backgroundResults.filter((result) => result.output.includes("started in background"))).toHaveLength(1);
+ expect(backgroundResults.filter((result) => result.output.includes("already") || result.output.includes("in progress"))).toHaveLength(1);
+ const backgroundOwner = readOwner(backgroundBase);
+ expect(alive(backgroundOwner.pid)).toBe(true);
+ await stop(backgroundBase);
+
+ const foregroundBase = makeBaseDir();
+ const first = spawnCli(cliArgs(foregroundBase, true));
+ const second = spawnCli(cliArgs(foregroundBase, true));
+ const firstResult = collect(first);
+ const secondResult = collect(second);
+ await waitFor(() => fs.existsSync(pidfile(foregroundBase)));
+ const foregroundOwner = readOwner(foregroundBase);
+ expect([
+ isDescendant(foregroundOwner.pid, first.pid!),
+ isDescendant(foregroundOwner.pid, second.pid!),
+ ].filter(Boolean)).toHaveLength(1);
+ process.kill(foregroundOwner.pid, "SIGTERM");
+ const results = await Promise.all([firstResult, secondResult]);
+ expect(results.filter((result) => result.output.includes("already") || result.output.includes("in progress"))).toHaveLength(1);
+ await waitFor(() => !fs.existsSync(pidfile(foregroundBase)));
+ }, 60_000);
+
+ it("keeps ownership until a timed-out child has actually exited", async () => {
+ const baseDir = makeBaseDir();
+ const shutdownMarker = path.join(baseDir, "delayed-shutdown.marker");
+ const first = spawnCli(cliArgs(baseDir), {
+ NODE_ENV: "test",
+ ALOOK_DAEMON_TEST_RECEIPT_TIMEOUT_MS: "1500",
+ ALOOK_DAEMON_TEST_SKIP_READY: "1",
+ ALOOK_DAEMON_TEST_SHUTDOWN_DELAY_MS: "800",
+ ALOOK_DAEMON_TEST_SHUTDOWN_MARKER: shutdownMarker,
+ });
+ const firstResult = collect(first);
+ await waitFor(() => fs.existsSync(shutdownMarker));
+ const oldOwner = readOwner(baseDir);
+ expect(alive(oldOwner.pid)).toBe(true);
+
+ await expect(daemonStart({
+ machineKey: secret,
+ serverUrl: "http://127.0.0.1:9",
+ wsUrl: "ws://127.0.0.1:9",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("already running");
+ expect(readOwner(baseDir)).toEqual(oldOwner);
+
+ const failedStart = await firstResult;
+ expect(failedStart.output).toContain("timed out");
+ await waitFor(() => !alive(oldOwner.pid) && !fs.existsSync(pidfile(baseDir)));
+ const replacement = await runCli(cliArgs(baseDir));
+ expect(replacement.output).toContain("started in background");
+ await stop(baseDir);
+ }, 60_000);
+
+ it("exits and releases ownership exactly once when fatal teardown rejects", async () => {
+ const baseDir = makeBaseDir();
+ const releaseMarker = path.join(baseDir, "release.marker");
+ const started = await runCli(cliArgs(baseDir), {
+ NODE_ENV: "test",
+ ALOOK_DAEMON_TEST_FATAL_AFTER_READY: "1",
+ ALOOK_DAEMON_TEST_STOP_REJECT: "1",
+ ALOOK_DAEMON_TEST_RELEASE_MARKER: releaseMarker,
+ });
+ expect(started.output).toContain("started in background");
+ const owner = readOwner(baseDir);
+
+ await waitFor(() => !alive(owner.pid) && !fs.existsSync(pidfile(baseDir)));
+
+ const releases = fs.readFileSync(releaseMarker, "utf8").trim().split("\n");
+ expect(releases).toEqual([String(owner.pid)]);
+ const records = daemonLogRecords(baseDir);
+ expect(records.filter((record) => record.message === "unhandled rejection")).toHaveLength(1);
+ expect(records.filter((record) => record.message === "daemon teardown failed")).toHaveLength(1);
+ expect(records.filter((record) => record.message === "shutting down…")).toHaveLength(1);
+ expect(JSON.stringify(records)).not.toContain("cmk_B0_FATAL_SECRET");
+ expect(records).toEqual(expect.arrayContaining([
+ expect.objectContaining({
+ message: "unhandled rejection",
+ fields: expect.objectContaining({ errorClass: "Error", error: "test fatal [redacted-token]" }),
+ }),
+ expect.objectContaining({
+ message: "daemon teardown failed",
+ fields: expect.objectContaining({ errorClass: "Error", error: "test teardown failed [redacted-token]" }),
+ }),
+ ]));
+ }, 60_000);
+
+ for (const checkpoint of ["after_spawn_before_final", "after_final_before_ipc", "after_ipc_send"] as const) {
+ it(`survives parent death at ${checkpoint} with exactly one eventual runner`, async () => {
+ const baseDir = makeBaseDir();
+ const checkpointFile = path.join(baseDir, `checkpoint-${checkpoint}.json`);
+ const parent = spawnCli(cliArgs(baseDir), {
+ NODE_ENV: "test",
+ ALOOK_DAEMON_TEST_PAUSE_AT: checkpoint,
+ ALOOK_DAEMON_TEST_CHECKPOINT_FILE: checkpointFile,
+ });
+ const parentResult = collect(parent);
+ await waitFor(() => fs.existsSync(checkpointFile));
+ const state = JSON.parse(fs.readFileSync(checkpointFile, "utf8")) as { parentPid: number; childPid: number };
+ process.kill(state.parentPid, "SIGKILL");
+ await parentResult;
+
+ if (checkpoint === "after_ipc_send") {
+ await waitFor(() => fs.existsSync(pidfile(baseDir)) && alive(readOwner(baseDir).pid));
+ const owner = readOwner(baseDir);
+ expect(owner.pid).toBe(state.childPid);
+ const contender = await runCli(cliArgs(baseDir));
+ expect(contender.output).toContain("already running");
+ expect(readOwner(baseDir)).toEqual(owner);
+ await stop(baseDir);
+ return;
+ }
+
+ await waitFor(() => !alive(state.childPid));
+ const restarted = await runCli(cliArgs(baseDir));
+ expect(restarted.output).toContain("started in background");
+ const owner = readOwner(baseDir);
+ expect(alive(owner.pid)).toBe(true);
+ expect(owner.pid).not.toBe(state.childPid);
+ await stop(baseDir);
+ }, 60_000);
+ }
+});
diff --git a/src/daemon/src/cli/daemonList.test.ts b/src/daemon/src/cli/daemonList.test.ts
index ac9519746..acf4658db 100644
--- a/src/daemon/src/cli/daemonList.test.ts
+++ b/src/daemon/src/cli/daemonList.test.ts
@@ -39,7 +39,7 @@ describe("daemonList — C3 fields", () => {
});
it("prunes a dead daemon's pidfile and reports nothing alive for it", () => {
- const dir = path.join(baseDir, "daemons", "deadone00000");
+ const dir = path.join(baseDir, "daemons", "dead00000000");
fs.mkdirSync(dir, { recursive: true });
// pid 1 is init — process.kill(1, 0) from a normal user throws EPERM, which
// isProcessAlive treats as... alive. Use a pid that's almost certainly dead.
@@ -48,7 +48,7 @@ describe("daemonList — C3 fields", () => {
fs.writeFileSync(pidfile, JSON.stringify({ pid: deadPid, key: "cmk_x" }));
const list = daemonList({ baseDir });
- const dead = list.find((d) => d.id === "deadone00000");
+ const dead = list.find((d) => d.id === "dead00000000");
if (dead) {
expect(dead.alive).toBe(false);
expect(dead.agents).toBeNull(); // no live agents attributed to a dead daemon
@@ -174,11 +174,19 @@ describe("daemonList — C0 per-daemon subdir layout + multi-daemon isolation",
const dir = path.join(baseDir, "daemons");
fs.mkdirSync(dir, { recursive: true });
fs.writeFileSync(path.join(dir, "straystray00.pid"), JSON.stringify({ pid: process.pid, key: "cmk_stray" }));
- writeDaemon("newnewnewnew", process.pid, 2, Date.now());
+ writeDaemon("eeeeeeeeeeee", process.pid, 2, Date.now());
const list = daemonList({ baseDir });
expect(list.find((d) => d.id === "straystray00")).toBeUndefined(); // flat file ignored
- expect(list.find((d) => d.id === "newnewnewnew")?.agents).toBe(2); // only subdir daemons
+ expect(list.find((d) => d.id === "eeeeeeeeeeee")?.agents).toBe(2); // only subdir daemons
+ });
+
+ it("ignores directories whose names are neither current nor legacy daemon ids", () => {
+ writeDaemon("not-a-daemon-id", process.pid, 2, Date.now());
+ writeDaemon("abcdefabcdef", process.pid, 1, Date.now());
+
+ const list = daemonList({ baseDir });
+ expect(list.map((row) => row.id)).toEqual(["abcdefabcdef"]);
});
});
@@ -200,7 +208,7 @@ describe("daemonList — C0.1 machineId anchor (cmt_ rotation doesn't drift)", (
};
it("two reconnect generations (different cmt_, same machineId) → ONE dir, ONE row (the C0.1 regression)", () => {
- const MACHINE_ID = "mach_stable01";
+ const MACHINE_ID = "cm_machine_stable01";
// First pairing: cmt_ token A.
writeGeneration(MACHINE_ID, "cmt_tokenAAAA");
// Reconnect mints a fresh cmt_ (token B) bound to the SAME machineId — the
@@ -212,14 +220,14 @@ describe("daemonList — C0.1 machineId anchor (cmt_ rotation doesn't drift)", (
const rows = list.filter((d) => d.id === MACHINE_ID);
expect(rows).toHaveLength(1); // no drift: still one daemon dir
// Only one subdir exists on disk (not two hash dirs).
- expect(fs.readdirSync(path.join(baseDir, "daemons")).filter((f) => f.startsWith("mach_"))).toEqual([MACHINE_ID]);
+ expect(fs.readdirSync(path.join(baseDir, "daemons")).filter((f) => f.startsWith("cm_"))).toEqual([MACHINE_ID]);
});
it("the list id IS the machineId (stable, long-term stop-able) — not a per-token hash", () => {
- writeGeneration("mach_stable01", "cmt_whatever");
- const row = daemonList({ baseDir }).find((d) => d.id === "mach_stable01");
+ writeGeneration("cm_machine_stable01", "cmt_whatever");
+ const row = daemonList({ baseDir }).find((d) => d.id === "cm_machine_stable01");
expect(row).toBeTruthy();
- expect(row!.id).toBe("mach_stable01"); // the subdir name = machineId
+ expect(row!.id).toBe("cm_machine_stable01"); // the subdir name = machineId
// A pidfile `key` breadcrumb (the volatile token) never leaks into the id/output.
expect(JSON.stringify(row)).not.toContain("cmt_");
});
diff --git a/src/daemon/src/cli/daemonRunner.security.test.ts b/src/daemon/src/cli/daemonRunner.security.test.ts
new file mode 100644
index 000000000..689618402
--- /dev/null
+++ b/src/daemon/src/cli/daemonRunner.security.test.ts
@@ -0,0 +1,166 @@
+import { afterEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { execFileSync } from "node:child_process";
+
+const createDaemonMock = vi.hoisted(() => vi.fn());
+
+vi.mock("../daemon/createDaemon.js", () => ({ createDaemon: createDaemonMock }));
+
+vi.mock("node:fs", async (importOriginal) => {
+ const actual = await importOriginal<typeof import("node:fs")>();
+ return { ...actual, chmodSync: vi.fn(actual.chmodSync) };
+});
+
+import type { PreparedDaemon } from "./daemonRunner";
+import { runPreparedDaemon } from "./daemonRunner";
+
+describe("daemon runner secure log initialization", () => {
+ const dirs: string[] = [];
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ createDaemonMock.mockReset();
+ for (const dir of dirs.splice(0)) fs.rmSync(dir, { recursive: true, force: true });
+ });
+
+ it("rejects initialization and never reports ready when a log generation cannot be secured", async () => {
+ const daemonDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-security-"));
+ dirs.push(daemonDir);
+ fs.chmodSync(daemonDir, 0o700);
+ fs.writeFileSync(path.join(daemonDir, "daemon.log.1"), "old sensitive log\n");
+ fs.chmodSync(path.join(daemonDir, "daemon.log.1"), 0o644);
+ vi.mocked(fs.chmodSync).mockClear();
+ vi.mocked(fs.chmodSync)
+ .mockImplementationOnce(() => {})
+ .mockImplementationOnce(() => { throw new Error("chmod denied"); });
+ const releaseOwnership = vi.fn();
+ const onReady = vi.fn();
+ const prepared = {
+ machineId: "machine-1",
+ machineKey: "cmk_secret",
+ serverUrl: "http://server",
+ wsUrl: "wss://server/ws?token=secret",
+ baseDir: daemonDir,
+ daemonDir,
+ statusFilePath: path.join(daemonDir, "status.json"),
+ agentCliPath: undefined,
+ runtimeReport: [],
+ healthyRuntimeIds: [],
+ hostname: "host",
+ platform: "test",
+ arch: "test",
+ osRelease: "test",
+ daemonVersion: "1.0.0",
+ ownerToken: "owner",
+ startedAt: new Date().toISOString(),
+ } satisfies PreparedDaemon;
+
+ await expect(runPreparedDaemon(prepared, {
+ foreground: false,
+ releaseOwnership,
+ onReady,
+ })).rejects.toThrow("failed to secure daemon log generations");
+
+ expect(releaseOwnership).toHaveBeenCalledOnce();
+ expect(onReady).not.toHaveBeenCalled();
+ expect(fs.readFileSync(path.join(daemonDir, "daemon.log.1"), "utf8")).toBe("old sensitive log\n");
+ });
+
+ it.each(["daemon.log", "daemon.log.1"])("rejects a %s symlink without touching its target", async (generation) => {
+ if (process.platform === "win32") return;
+ const daemonDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-symlink-"));
+ const outsideDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-outside-"));
+ dirs.push(daemonDir, outsideDir);
+ const outside = path.join(outsideDir, "outside.log");
+ fs.writeFileSync(outside, "outside stays unchanged\n", { mode: 0o644 });
+ const originalMode = fs.statSync(outside).mode & 0o777;
+ fs.symlinkSync(outside, path.join(daemonDir, generation));
+ const releaseOwnership = vi.fn();
+ const onReady = vi.fn();
+
+ await expect(runPreparedDaemon(preparedFor(daemonDir), {
+ foreground: false,
+ releaseOwnership,
+ onReady,
+ })).rejects.toThrow("failed to secure daemon log generations");
+
+ expect(fs.readFileSync(outside, "utf8")).toBe("outside stays unchanged\n");
+ expect(fs.statSync(outside).mode & 0o777).toBe(originalMode);
+ expect(releaseOwnership).toHaveBeenCalledOnce();
+ expect(onReady).not.toHaveBeenCalled();
+ });
+
+ it("rejects a FIFO generation without opening it", async () => {
+ if (process.platform === "win32") return;
+ const daemonDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-fifo-"));
+ dirs.push(daemonDir);
+ execFileSync("mkfifo", [path.join(daemonDir, "daemon.log")]);
+ const releaseOwnership = vi.fn();
+ const onReady = vi.fn();
+
+ await expect(runPreparedDaemon(preparedFor(daemonDir), {
+ foreground: false,
+ releaseOwnership,
+ onReady,
+ })).rejects.toThrow("failed to secure daemon log generations");
+
+ expect(releaseOwnership).toHaveBeenCalledOnce();
+ expect(onReady).not.toHaveBeenCalled();
+ });
+
+ it("scrubs credential, bearer, and absolute-path details from initialization failures", async () => {
+ const daemonDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-init-error-"));
+ dirs.push(daemonDir);
+ const rawError = "init cmk_PRIVATE Bearer bearer-secret at /Users/alice/private/socket";
+ createDaemonMock.mockRejectedValueOnce(new Error(rawError));
+ const releaseOwnership = vi.fn();
+ const onReady = vi.fn();
+
+ await expect(runPreparedDaemon(preparedFor(daemonDir), {
+ foreground: false,
+ releaseOwnership,
+ onReady,
+ })).rejects.toThrow(rawError);
+
+ const records = fs.readFileSync(path.join(daemonDir, "daemon.log"), "utf8")
+ .trimEnd()
+ .split("\n")
+ .map((line) => JSON.parse(line));
+ const failure = records.find((record) => record.message === "daemon runner initialization failed");
+ expect(failure).toMatchObject({
+ fields: { errorClass: "Error" },
+ });
+ expect(failure.fields.error).toContain("[redacted-token]");
+ expect(failure.fields.error).toContain("Bearer [redacted]");
+ expect(failure.fields.error).toContain("[redacted-path]");
+ expect(JSON.stringify(failure)).not.toContain("cmk_PRIVATE");
+ expect(JSON.stringify(failure)).not.toContain("bearer-secret");
+ expect(JSON.stringify(failure)).not.toContain("/Users/alice/private/socket");
+ expect(releaseOwnership).toHaveBeenCalledOnce();
+ expect(onReady).not.toHaveBeenCalled();
+ });
+});
+
+function preparedFor(daemonDir: string): PreparedDaemon {
+ return {
+ machineId: "cm_machine_security_test",
+ machineKey: "cmk_secret",
+ serverUrl: "http://server",
+ wsUrl: "wss://server/ws?token=secret",
+ baseDir: daemonDir,
+ daemonDir,
+ statusFilePath: path.join(daemonDir, "status.json"),
+ agentCliPath: undefined,
+ runtimeReport: [],
+ healthyRuntimeIds: [],
+ hostname: "host",
+ platform: "test",
+ arch: "test",
+ osRelease: "test",
+ daemonVersion: "1.0.0",
+ ownerToken: "owner",
+ startedAt: new Date().toISOString(),
+ };
+}
diff --git a/src/daemon/src/cli/daemonRunner.test.ts b/src/daemon/src/cli/daemonRunner.test.ts
new file mode 100644
index 000000000..0e06a275b
--- /dev/null
+++ b/src/daemon/src/cli/daemonRunner.test.ts
@@ -0,0 +1,110 @@
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import type { PreparedDaemon } from "./daemonRunner";
+import { createDaemonProcessLogger, DAEMON_LOG_MAX_BYTES, logDaemonStartup, logDaemonUp } from "./daemonRunner";
+
+describe("daemon runner logger", () => {
+ let dir: string;
+ beforeEach(() => {
+ dir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-runner-"));
+ });
+ afterEach(() => fs.rmSync(dir, { recursive: true, force: true }));
+
+ it("writes one structured JSON record per physical line with secure modes", () => {
+ const { logger, logPath } = createDaemonProcessLogger(dir, false);
+ logger.info("hostile\nmessage", { header: "spoof", agentId: "a1" });
+ const lines = fs.readFileSync(logPath, "utf8").trimEnd().split("\n");
+ expect(lines).toHaveLength(1);
+ expect(JSON.parse(lines[0]!)).toMatchObject({
+ header: "@alook/daemon",
+ level: "info",
+ message: "hostile\nmessage",
+ fields: { header: "spoof", agentId: "a1" },
+ });
+ if (process.platform !== "win32") {
+ expect(fs.statSync(dir).mode & 0o777).toBe(0o700);
+ expect(fs.statSync(logPath).mode & 0o777).toBe(0o600);
+ }
+ });
+
+ it("keeps active and rotated generations within the hard cap", () => {
+ const { logger, logPath } = createDaemonProcessLogger(dir, false);
+ const payload = "x".repeat(256 * 1024);
+ for (let i = 0; i < 80; i++) logger.info("chunk", { payload, i });
+ for (const file of [logPath, `${logPath}.1`]) {
+ if (!fs.existsSync(file)) continue;
+ expect(fs.statSync(file).size).toBeLessThanOrEqual(DAEMON_LOG_MAX_BYTES);
+ if (process.platform !== "win32") expect(fs.statSync(file).mode & 0o777).toBe(0o600);
+ }
+ });
+
+ it("removes legacy oversized active and rotated generations before startup", () => {
+ const logPath = path.join(dir, "daemon.log");
+ fs.writeFileSync(logPath, "");
+ fs.writeFileSync(`${logPath}.1`, "");
+ fs.truncateSync(logPath, DAEMON_LOG_MAX_BYTES + 1);
+ fs.truncateSync(`${logPath}.1`, DAEMON_LOG_MAX_BYTES + 1);
+
+ createDaemonProcessLogger(dir, false);
+
+ expect(fs.statSync(logPath).size).toBeLessThanOrEqual(DAEMON_LOG_MAX_BYTES);
+ expect(fs.existsSync(`${logPath}.1`)).toBe(false);
+ expect(fs.readFileSync(logPath, "utf8")).toContain("oversize daemon log generation removed");
+ });
+
+ it("drops an oversize event whole and records only one bounded warning", () => {
+ const { logger, logPath } = createDaemonProcessLogger(dir, false);
+ const payload = "x".repeat(DAEMON_LOG_MAX_BYTES);
+ logger.info("oversize", { payload });
+ logger.info("oversize", { payload });
+ const lines = fs.readFileSync(logPath, "utf8").trimEnd().split("\n").map((line) => JSON.parse(line));
+ expect(lines).toEqual([expect.objectContaining({ message: "daemon log record dropped: oversize" })]);
+ });
+
+ it("records a safe startup and runtime probe summary", () => {
+ const { logger, logPath } = createDaemonProcessLogger(dir, false);
+ logDaemonStartup(logger, {
+ machineId: "machine-1",
+ machineKey: "cmk_must_not_log",
+ daemonVersion: "1.2.3",
+ runtimeReport: [
+ { id: "claude", status: "healthy", version: "4", lastError: "secret healthy detail" },
+ { id: "codex", status: "unhealthy", lastError: "secret failure detail" },
+ ],
+ } as PreparedDaemon);
+
+ const record = JSON.parse(fs.readFileSync(logPath, "utf8").trim());
+ expect(record).toMatchObject({
+ level: "info",
+ message: "daemon startup",
+ fields: {
+ machineId: "machine-1",
+ version: "1.2.3",
+ healthyRuntimeIds: ["claude"],
+ unhealthyRuntimeIds: ["codex"],
+ },
+ });
+ expect(JSON.stringify(record)).not.toContain("cmk_must_not_log");
+ expect(JSON.stringify(record)).not.toContain("secret");
+ });
+
+ it("records only URL protocols when the daemon is up", () => {
+ const { logger, logPath } = createDaemonProcessLogger(dir, false);
+ logDaemonUp(
+ logger,
+ "http://user:[email protected]:1234/proxy?token=proxy-secret",
+ "wss://control.example/ws?access_token=control-secret",
+ );
+
+ const record = JSON.parse(fs.readFileSync(logPath, "utf8").trim());
+ expect(record).toMatchObject({
+ message: "daemon up",
+ fields: { proxyProtocol: "http", controlProtocol: "wss" },
+ });
+ expect(JSON.stringify(record)).not.toContain("password");
+ expect(JSON.stringify(record)).not.toContain("secret");
+ expect(JSON.stringify(record)).not.toContain("control.example");
+ });
+});
diff --git a/src/daemon/src/cli/daemonRunner.ts b/src/daemon/src/cli/daemonRunner.ts
new file mode 100644
index 000000000..faadc90d6
--- /dev/null
+++ b/src/daemon/src/cli/daemonRunner.ts
@@ -0,0 +1,239 @@
+import * as fs from "node:fs";
+import * as path from "node:path";
+import { WebSocket } from "ws";
+import { createDaemon } from "../daemon/createDaemon.js";
+import { getDriver, listRuntimeIds } from "../drivers/index.js";
+import type { RuntimeInfo } from "../discovery.js";
+import { createLogger, type Logger } from "../logger.js";
+import { UnknownRuntimeError } from "../manager/agentRouter.js";
+import { scrubRuntimeErrorDiagnosticText } from "../runtime/errorDiagnostics.js";
+import { createRotatingFileSink, type RotatingFileSink } from "../util/rotatingFileSink.js";
+
+const CAPABILITIES = ["send", "read", "mentions", "tasks", "reactions", "server", "channels", "knowledge", "attach", "friend"];
+export const DAEMON_LOG_MAX_BYTES = 8 * 1024 * 1024;
+const DAEMON_ERROR_MESSAGE_MAX_CHARS = 512;
+
+export interface PreparedDaemon {
+ machineId: string;
+ machineKey: string;
+ serverUrl: string;
+ wsUrl: string;
+ baseDir: string;
+ daemonDir: string;
+ statusFilePath: string;
+ agentCliPath: string | undefined;
+ runtimeReport: RuntimeInfo[];
+ healthyRuntimeIds: string[];
+ hostname: string;
+ platform: string;
+ arch: string;
+ osRelease: string;
+ daemonVersion: string;
+ ownerToken: string;
+ startedAt: string;
+}
+
+export interface DaemonReadyReceipt {
+ pid: number;
+ machineId: string;
+ logPath: string;
+ startedAt: string;
+}
+
+export interface RunPreparedDaemonOptions {
+ foreground: boolean;
+ onReady?: (receipt: DaemonReadyReceipt) => void;
+ releaseOwnership: () => void;
+}
+
+export function logDaemonStartup(log: Logger, prepared: PreparedDaemon): void {
+ log.info("daemon startup", {
+ machineId: prepared.machineId,
+ version: prepared.daemonVersion,
+ healthyRuntimeIds: prepared.runtimeReport
+ .filter((runtime) => runtime.status === "healthy")
+ .map((runtime) => runtime.id),
+ unhealthyRuntimeIds: prepared.runtimeReport
+ .filter((runtime) => runtime.status !== "healthy")
+ .map((runtime) => runtime.id),
+ });
+}
+
+function protocolOf(value: string): string {
+ try {
+ return new URL(value).protocol.replace(/:$/, "");
+ } catch {
+ return "unknown";
+ }
+}
+
+export function logDaemonUp(log: Logger, proxyUrl: string, controlUrl: string): void {
+ log.info("daemon up", {
+ proxyProtocol: protocolOf(proxyUrl),
+ controlProtocol: protocolOf(controlUrl),
+ });
+}
+
+function safeDaemonError(error: unknown): { errorClass: string; error: string } {
+ const errorClass = error instanceof Error ? error.name : typeof error;
+ const raw = error instanceof Error ? error.message : String(error);
+ const scrubbed = scrubRuntimeErrorDiagnosticText(raw)
+ .replace(/\b(?:cmk|cmt)_[A-Za-z0-9_-]+\b/g, "[redacted-token]")
+ .slice(0, DAEMON_ERROR_MESSAGE_MAX_CHARS);
+ return { errorClass, error: scrubbed };
+}
+
+export function createDaemonProcessLogger(
+ daemonDir: string,
+ foreground: boolean,
+): { logger: Logger; logPath: string; sink: RotatingFileSink } {
+ fs.mkdirSync(daemonDir, { recursive: true, mode: 0o700 });
+ fs.chmodSync(daemonDir, 0o700);
+ const logPath = path.join(daemonDir, "daemon.log");
+ let warnedOversize = false;
+ const sink: RotatingFileSink = createRotatingFileSink(logPath, DAEMON_LOG_MAX_BYTES, {
+ mode: 0o600,
+ hardMaxBytes: true,
+ onError: ({ operation }) => {
+ if ((operation !== "oversize" && operation !== "oversize_generation") || warnedOversize) return;
+ warnedOversize = true;
+ sink.write(JSON.stringify({
+ time: new Date().toISOString(),
+ header: "@alook/daemon",
+ level: "warn",
+ message: operation === "oversize"
+ ? "daemon log record dropped: oversize"
+ : "oversize daemon log generation removed",
+ fields: {},
+ }));
+ },
+ });
+ if (!sink.secure()) throw new Error("failed to secure daemon log generations");
+ const quiet = () => {};
+ const logger = createLogger({
+ header: "@alook/daemon",
+ out: foreground ? (line) => process.stdout.write(line + "\n") : quiet,
+ err: foreground ? (line) => process.stderr.write(line + "\n") : quiet,
+ record: (record) => sink.write(JSON.stringify(record)),
+ });
+ return { logger, logPath, sink };
+}
+
+export async function runPreparedDaemon(
+ prepared: PreparedDaemon,
+ opts: RunPreparedDaemonOptions,
+): Promise<never> {
+ let processLogger: ReturnType<typeof createDaemonProcessLogger>;
+ try {
+ processLogger = createDaemonProcessLogger(prepared.daemonDir, opts.foreground);
+ } catch (error) {
+ opts.releaseOwnership();
+ throw error;
+ }
+ const { logger: log, logPath } = processLogger;
+ let shuttingDown = false;
+ let daemon: Awaited<ReturnType<typeof createDaemon>> | null = null;
+ const keepAlive = setInterval(() => {}, 24 * 60 * 60 * 1000);
+
+ const testShutdownDelay = async (): Promise<void> => {
+ if (process.env.NODE_ENV !== "test") return;
+ const delayMs = Number(process.env.ALOOK_DAEMON_TEST_SHUTDOWN_DELAY_MS);
+ if (!Number.isFinite(delayMs) || delayMs <= 0) return;
+ const marker = process.env.ALOOK_DAEMON_TEST_SHUTDOWN_MARKER;
+ if (marker) fs.writeFileSync(marker, String(process.pid), { mode: 0o600 });
+ await new Promise((resolve) => setTimeout(resolve, delayMs));
+ };
+
+ const stopDaemon = async (): Promise<void> => {
+ if (process.env.NODE_ENV === "test" && process.env.ALOOK_DAEMON_TEST_STOP_REJECT === "1") {
+ throw new Error("test teardown failed cmk_B0_FATAL_SECRET");
+ }
+ await daemon?.stop();
+ };
+
+ const shutdown = async (exitCode: number): Promise<never> => {
+ if (shuttingDown) return await new Promise<never>(() => {});
+ shuttingDown = true;
+ clearInterval(keepAlive);
+ log.info("shutting down…");
+ try {
+ await testShutdownDelay();
+ await stopDaemon();
+ } catch (error) {
+ log.error("daemon teardown failed", safeDaemonError(error));
+ } finally {
+ try {
+ opts.releaseOwnership();
+ } catch (error) {
+ log.error("daemon ownership release failed", safeDaemonError(error));
+ } finally {
+ process.exit(exitCode);
+ }
+ }
+ };
+
+ process.once("uncaughtException", (error) => {
+ log.error("uncaught exception", safeDaemonError(error));
+ void shutdown(1);
+ });
+ process.once("unhandledRejection", (reason) => {
+ log.error("unhandled rejection", safeDaemonError(reason));
+ void shutdown(1);
+ });
+ process.once("SIGINT", () => { void shutdown(0); });
+ process.once("SIGTERM", () => { void shutdown(0); });
+
+ try {
+ logDaemonStartup(log, prepared);
+ daemon = await createDaemon({
+ machineKey: prepared.machineKey,
+ serverUrl: prepared.serverUrl,
+ serverWsUrl: prepared.wsUrl,
+ webSocketFactory: (url, headers) => new WebSocket(url, { headers }),
+ runtimeReport: prepared.runtimeReport,
+ driverFor: (_agentId, runtimeConfig) => {
+ const requested = runtimeConfig?.runtime;
+ const known: string[] = listRuntimeIds();
+ if (!requested || !known.includes(requested)) {
+ throw new UnknownRuntimeError(requested, prepared.healthyRuntimeIds);
+ }
+ return getDriver(requested as Parameters<typeof getDriver>[0]);
+ },
+ capabilities: CAPABILITIES,
+ agentCliPath: prepared.agentCliPath,
+ workingDirectoryBase: prepared.baseDir,
+ fsmTraceDir: prepared.daemonDir,
+ statusFilePath: prepared.statusFilePath,
+ hostname: prepared.hostname,
+ platform: prepared.platform,
+ arch: prepared.arch,
+ osRelease: prepared.osRelease,
+ daemonVersion: prepared.daemonVersion,
+ logger: log,
+ onAuthRejected: () => {
+ log.error("machine key rejected by server — is it correct / has it expired?");
+ void shutdown(1);
+ },
+ });
+ } catch (error) {
+ clearInterval(keepAlive);
+ log.error("daemon runner initialization failed", safeDaemonError(error));
+ opts.releaseOwnership();
+ throw error;
+ }
+
+ logDaemonUp(log, daemon.proxyUrl, prepared.wsUrl);
+ daemon.onOpen(() => log.info("control plane OPEN"));
+ opts.onReady?.({
+ pid: process.pid,
+ machineId: prepared.machineId,
+ logPath,
+ startedAt: prepared.startedAt,
+ });
+ if (process.env.NODE_ENV === "test" && process.env.ALOOK_DAEMON_TEST_FATAL_AFTER_READY === "1") {
+ setTimeout(() => {
+ void Promise.reject(new Error("test fatal cmk_B0_FATAL_SECRET"));
+ }, 250);
+ }
+ return await new Promise<never>(() => {});
+}
diff --git a/src/daemon/src/cli/daemonStart.lifecycle.test.ts b/src/daemon/src/cli/daemonStart.lifecycle.test.ts
new file mode 100644
index 000000000..b785d7ea4
--- /dev/null
+++ b/src/daemon/src/cli/daemonStart.lifecycle.test.ts
@@ -0,0 +1,269 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+const mockRunPreparedDaemon = vi.hoisted(() => vi.fn());
+
+vi.mock("./daemonRunner", async (importOriginal) => ({
+ ...await importOriginal<typeof import("./daemonRunner")>(),
+ runPreparedDaemon: mockRunPreparedDaemon,
+}));
+
+vi.mock("../discovery", async (importOriginal) => ({
+ ...await importOriginal<typeof import("../discovery")>(),
+ detectRuntimes: vi.fn(async () => []),
+ resolveAlookCliPathWithFallback: vi.fn(() => undefined),
+}));
+
+import { daemonRunFromIpc, daemonStart } from "./daemonStart";
+
+describe("daemon lifecycle ownership cleanup", () => {
+ let baseDir: string;
+
+ beforeEach(() => {
+ baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "daemon-start-lifecycle-"));
+ mockRunPreparedDaemon.mockReset();
+ mockRunPreparedDaemon.mockRejectedValue(new Error("runner init failed"));
+ vi.spyOn(globalThis, "fetch").mockResolvedValue(new Response(
+ JSON.stringify({ machineId: "cm_machine_init_failure" }),
+ { status: 200, headers: { "content-type": "application/json" } },
+ ));
+ });
+
+ afterEach(() => {
+ vi.restoreAllMocks();
+ fs.rmSync(baseDir, { recursive: true, force: true });
+ });
+
+ it("compare-deletes foreground final ownership and launch lock when runner init fails", async () => {
+ const opts = {
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ };
+
+ await expect(daemonStart(opts)).rejects.toThrow("runner init failed");
+ const daemonDir = path.join(baseDir, "daemons", "cm_machine_init_failure");
+ expect(fs.existsSync(path.join(daemonDir, "daemon.pid"))).toBe(false);
+ expect(fs.existsSync(path.join(daemonDir, "daemon.launch.lock"))).toBe(false);
+
+ await expect(daemonStart(opts)).rejects.toThrow("runner init failed");
+ expect(mockRunPreparedDaemon).toHaveBeenCalledTimes(2);
+ });
+
+ it("recovers malformed final and launch files left by a dead writer", async () => {
+ const daemonsDir = path.join(baseDir, "daemons");
+ const daemonDir = path.join(daemonsDir, "cm_machine_init_failure");
+ fs.mkdirSync(daemonDir, { recursive: true });
+ fs.writeFileSync(
+ path.join(daemonsDir, "cm_machine_init_failure.credential.json"),
+ JSON.stringify({ credential: "cmk_test", machineId: "cm_machine_init_failure" }),
+ );
+ fs.writeFileSync(path.join(daemonDir, "daemon.pid"), JSON.stringify({ pid: 2_147_483_646 }));
+ fs.writeFileSync(path.join(daemonDir, "daemon.launch.lock"), '{"pid":2147483646');
+
+ await expect(daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("runner init failed");
+
+ expect(mockRunPreparedDaemon).toHaveBeenCalledOnce();
+ expect(fs.existsSync(path.join(daemonDir, "daemon.pid"))).toBe(false);
+ expect(fs.existsSync(path.join(daemonDir, "daemon.launch.lock"))).toBe(false);
+ });
+
+ it("never deletes a live final owner while recovering stale ownership", async () => {
+ const daemonsDir = path.join(baseDir, "daemons");
+ const daemonDir = path.join(daemonsDir, "cm_machine_init_failure");
+ const finalPath = path.join(daemonDir, "daemon.pid");
+ fs.mkdirSync(daemonDir, { recursive: true });
+ fs.writeFileSync(
+ path.join(daemonsDir, "cm_machine_init_failure.credential.json"),
+ JSON.stringify({ credential: "cmk_test", machineId: "cm_machine_init_failure" }),
+ );
+ const liveOwner = {
+ pid: process.pid,
+ machineId: "cm_machine_init_failure",
+ startedAt: new Date().toISOString(),
+ ownerToken: "live-owner",
+ };
+ fs.writeFileSync(finalPath, JSON.stringify(liveOwner));
+
+ await expect(daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("already running");
+
+ expect(JSON.parse(fs.readFileSync(finalPath, "utf8"))).toEqual(liveOwner);
+ expect(mockRunPreparedDaemon).not.toHaveBeenCalled();
+ });
+
+ it("rejects a live hash-directory legacy owner without exposing its key", async () => {
+ const legacyDir = path.join(baseDir, "daemons", "legacyhash01");
+ const legacyPath = path.join(legacyDir, "daemon.pid");
+ fs.mkdirSync(legacyDir, { recursive: true });
+ fs.writeFileSync(legacyPath, JSON.stringify({ pid: process.pid, key: "cmk_test" }));
+
+ let failure: Error | undefined;
+ try {
+ await daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ });
+ } catch (error) {
+ failure = error as Error;
+ }
+
+ expect(failure?.message).toContain("legacy daemon already running");
+ expect(failure?.message).not.toContain("cmk_test");
+ expect(JSON.parse(fs.readFileSync(legacyPath, "utf8"))).toEqual({ pid: process.pid, key: "cmk_test" });
+ expect(mockRunPreparedDaemon).not.toHaveBeenCalled();
+ });
+
+ it("removes a dead legacy owner before migrating to the stable machine id", async () => {
+ const legacyDir = path.join(baseDir, "daemons", "legacyhash01");
+ const legacyPath = path.join(legacyDir, "daemon.pid");
+ fs.mkdirSync(legacyDir, { recursive: true });
+ fs.writeFileSync(legacyPath, JSON.stringify({ pid: 2_147_483_646, key: "cmk_test" }));
+
+ await expect(daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("runner init failed");
+
+ expect(fs.existsSync(legacyPath)).toBe(false);
+ expect(fs.existsSync(path.join(baseDir, "daemons", "cm_machine_init_failure.credential.json"))).toBe(true);
+ expect(mockRunPreparedDaemon).toHaveBeenCalledOnce();
+ });
+
+ it.each([
+ "../../escape",
+ "/absolute",
+ "cm_bad\\separator",
+ `cm_${"a".repeat(65)}`,
+ ])("rejects an unsafe server machine id before deriving filesystem paths: %s", async (machineId) => {
+ vi.mocked(globalThis.fetch).mockResolvedValue(new Response(
+ JSON.stringify({ machineId }),
+ { status: 200, headers: { "content-type": "application/json" } },
+ ));
+ const derivedCredential = path.join(baseDir, "daemons", `${machineId}.credential.json`);
+ const derivedDir = path.join(baseDir, "daemons", machineId);
+
+ await expect(daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("invalid machine identity");
+
+ expect(fs.existsSync(derivedCredential)).toBe(false);
+ expect(fs.existsSync(derivedDir)).toBe(false);
+ expect(mockRunPreparedDaemon).not.toHaveBeenCalled();
+ });
+
+ it("validates a persisted credential machine id before acquiring its launch lock", async () => {
+ const daemonsDir = path.join(baseDir, "daemons");
+ fs.mkdirSync(daemonsDir, { recursive: true });
+ fs.writeFileSync(
+ path.join(daemonsDir, "stored.credential.json"),
+ JSON.stringify({ credential: "cmk_test", machineId: "../../persisted-escape" }),
+ );
+
+ await expect(daemonStart({
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ foreground: true,
+ })).rejects.toThrow("invalid machine identity");
+
+ expect(fs.existsSync(path.join(baseDir, "persisted-escape"))).toBe(false);
+ expect(mockRunPreparedDaemon).not.toHaveBeenCalled();
+ });
+
+ it("continues the runner when accepted and ready IPC sends throw after validation", async () => {
+ const machineId = "cm_machine_ipc_throw";
+ const daemonDir = path.join(baseDir, "daemons", machineId);
+ fs.mkdirSync(daemonDir, { recursive: true });
+ const prepared = {
+ machineId,
+ machineKey: "cmk_test",
+ serverUrl: "http://server",
+ wsUrl: "ws://server",
+ baseDir,
+ daemonDir,
+ statusFilePath: path.join(daemonDir, "status.json"),
+ agentCliPath: undefined,
+ runtimeReport: [],
+ healthyRuntimeIds: [],
+ hostname: "host",
+ platform: "test",
+ arch: "test",
+ osRelease: "test",
+ daemonVersion: "1.0.0",
+ ownerToken: "ipc-owner",
+ startedAt: new Date().toISOString(),
+ };
+ const fakePid = 424_242;
+ fs.writeFileSync(path.join(daemonDir, "daemon.pid"), JSON.stringify({
+ pid: fakePid,
+ machineId,
+ startedAt: prepared.startedAt,
+ ownerToken: prepared.ownerToken,
+ }));
+ const listeners = new Map<string, (...args: unknown[]) => void>();
+ const ipc = {
+ pid: fakePid,
+ connected: true,
+ send: vi.fn(() => { throw new Error("parent disconnected during send"); }),
+ disconnect: vi.fn(),
+ once: vi.fn((event: string, listener: (...args: unknown[]) => void) => {
+ listeners.set(event, listener);
+ return ipc;
+ }),
+ } as unknown as typeof process;
+ mockRunPreparedDaemon.mockImplementation((_value, options) => {
+ options.onReady?.({
+ pid: fakePid,
+ machineId,
+ logPath: path.join(daemonDir, "daemon.log"),
+ startedAt: prepared.startedAt,
+ });
+ return new Promise<never>(() => {});
+ });
+
+ void daemonRunFromIpc(ipc);
+ listeners.get("message")?.({ type: "daemon:prepared", prepared });
+ await Promise.resolve();
+
+ expect(mockRunPreparedDaemon).toHaveBeenCalledOnce();
+ expect(ipc.send).toHaveBeenCalledTimes(2);
+ });
+});
+
+describe("daemon runner IPC entry", () => {
+ it("fails immediately when the parent disconnected before handlers were installed", async () => {
+ const disconnected = {
+ connected: false,
+ send: vi.fn(),
+ } as unknown as typeof process;
+
+ await expect(daemonRunFromIpc(disconnected)).rejects.toThrow("parent disconnected before prepared payload");
+ });
+});
diff --git a/src/daemon/src/cli/daemonStart.test.ts b/src/daemon/src/cli/daemonStart.test.ts
index 7a16b6e7d..a75addb83 100644
--- a/src/daemon/src/cli/daemonStart.test.ts
+++ b/src/daemon/src/cli/daemonStart.test.ts
@@ -16,7 +16,7 @@ describe("daemonStart — credentialFilePath by machineId", () => {
});
it("derives path from machineId, not from the CLI arg", () => {
- const machineId = "cm_abc123";
+ const machineId = "cm_abc12345";
const p1 = credentialFilePathByMachineId(baseDir, machineId);
const p2 = credentialFilePathByMachineId(baseDir, machineId);
expect(p1).toBe(p2);
@@ -24,7 +24,7 @@ describe("daemonStart — credentialFilePath by machineId", () => {
});
it("same machineId produces the same path across two rotates — no orphaned files", () => {
- const machineId = "cm_abc123";
+ const machineId = "cm_abc12345";
const p = credentialFilePathByMachineId(baseDir, machineId);
fs.mkdirSync(path.dirname(p), { recursive: true });
fs.writeFileSync(p, JSON.stringify({ credential: "cmk_first", machineId }), { mode: 0o600 });
@@ -34,6 +34,17 @@ describe("daemonStart — credentialFilePath by machineId", () => {
const parsed = JSON.parse(fs.readFileSync(p, "utf8"));
expect(parsed).toEqual({ credential: "cmk_second", machineId });
});
+
+ it.each([
+ "../outside",
+ "/tmp/outside",
+ "cm_bad\\segment",
+ `cm_${"a".repeat(65)}`,
+ ])("rejects an unsafe machine id inside the exported path builder: %s", (machineId) => {
+ expect(() => credentialFilePathByMachineId(baseDir, machineId)).toThrow(
+ "invalid machine identity returned by server",
+ );
+ });
});
describe("daemonStatus — reads snapshot + always flags freshness (batch E2)", () => {
@@ -46,7 +57,7 @@ describe("daemonStatus — reads snapshot + always flags freshness (batch E2)",
});
// Per-key layout (C0): status lives at daemons/<id>/status.json.
- const ID = "d0d0d0d0d0d0";
+ const ID = "cm_status_test_123";
const daemonSubdir = () => path.join(baseDir, "daemons", ID);
const writeSnap = (writtenAt: number) => {
const dir = daemonSubdir();
@@ -115,4 +126,24 @@ describe("daemonStatus — reads snapshot + always flags freshness (batch E2)",
expect(r.ambiguous).toBe(true);
expect(r.availableIds?.sort()).toEqual(["aaaaaaaaaaaa", "bbbbbbbbbbbb"]);
});
+
+ it.each([
+ "../outside",
+ "/tmp/outside",
+ "cm_bad\\segment",
+ `cm_${"a".repeat(65)}`,
+ ])("rejects an unsafe explicit id before status-file access: %s", (id) => {
+ expect(() => daemonStatus({ id, baseDir, now: () => 1000 })).toThrow("invalid daemon id");
+ });
+
+ it("ignores unsafe directory names when auto-selecting status", () => {
+ writeSnap(1000);
+ const unsafeDir = path.join(baseDir, "daemons", "not-a-daemon-id");
+ fs.mkdirSync(unsafeDir, { recursive: true });
+ fs.writeFileSync(path.join(unsafeDir, "status.json"), JSON.stringify({ writtenAt: 1000, agents: [] }));
+ const r = daemonStatus({ baseDir, now: () => 1000 });
+ expect(r.found).toBe(true);
+ expect(r.ambiguous).toBeUndefined();
+ expect(r.agents[0]?.agentId).toBe("a1");
+ });
});
diff --git a/src/daemon/src/cli/daemonStart.ts b/src/daemon/src/cli/daemonStart.ts
index a8ab6b8db..cfb2ce578 100644
--- a/src/daemon/src/cli/daemonStart.ts
+++ b/src/daemon/src/cli/daemonStart.ts
@@ -1,25 +1,20 @@
/**
* `alook daemon start|stop|list` — daemon lifecycle commands.
*
- * Multiple daemons can run on one physical machine — each machine key represents
- * one logical machine on the server side. Per-key pidfiles at
- * `<baseDir>/daemons/<keyHash>.pid` prevent the same key from starting twice.
+ * Multiple daemons can run on one physical machine. Each server-issued machine
+ * identity owns one private directory and pidfile under `<baseDir>/daemons/`.
*/
import * as fs from "fs";
import * as path from "path";
import * as crypto from "crypto";
import * as os from "os";
import { homedir } from "os";
-import { WebSocket } from "ws";
-import { createDaemon } from "../daemon/createDaemon.js";
import type { DaemonStatusSnapshot } from "../util/statusFile.js";
-import { getDriver, listRuntimeIds } from "../drivers/index.js";
import { resolveAlookCliPathWithFallback, detectRuntimes, type RuntimeInfo } from "../discovery.js";
import { createLogger } from "../logger.js";
-import { UnknownRuntimeError } from "../manager/agentRouter.js";
import { readDaemonVersion } from "../version.js";
-
-const CAPABILITIES = ["send", "read", "mentions", "tasks", "reactions", "server", "channels", "knowledge", "attach", "friend"];
+import { runPreparedDaemon, type DaemonReadyReceipt, type PreparedDaemon } from "./daemonRunner.js";
+import { spawn, type ChildProcess } from "node:child_process";
/**
* Grace window for a daemon to exit on SIGTERM before we escalate to SIGKILL.
@@ -28,10 +23,14 @@ const CAPABILITIES = ["send", "read", "mentions", "tasks", "reactions", "server"
* window has to contain those.
*/
const STOP_GRACE_MS = 5000;
+const STOP_KILL_GRACE_MS = 2_000;
/** How often `daemonStop` polls `isProcessAlive` while waiting on SIGTERM. */
const POLL_MS = 100;
-/** How many hex chars of the machine-key SHA-256 make up the pidfile name (= the list/stop `id`). */
-const MACHINE_KEY_HASH_PREFIX_LEN = 12;
+const START_RECEIPT_TIMEOUT_MS = 15_000;
+const RUNNER_TERM_GRACE_MS = 2_000;
+const RUNNER_KILL_GRACE_MS = 2_000;
+const MACHINE_ID_PATTERN = /^cm_[A-Za-z0-9_-]{8,64}$/;
+const LEGACY_DAEMON_ID_PATTERN = /^[a-f0-9]{12}$/;
function resolveDefaultBaseDir(): string {
const root = process.env.ALOOK_PROJECT_ROOT || path.join(homedir(), ".alook");
@@ -43,13 +42,9 @@ export const DEFAULT_BASE_DIR = resolveDefaultBaseDir();
const log = createLogger({ header: "@alook/daemon" });
/* ------------------------------------------------------------------ */
-/* Per-key pidfile helpers */
+/* Per-machine pidfile helpers */
/* ------------------------------------------------------------------ */
-function keyHash(machineKey: string): string {
- return crypto.createHash("sha256").update(machineKey).digest("hex").slice(0, MACHINE_KEY_HASH_PREFIX_LEN);
-}
-
function daemonsDir(baseDir: string): string {
return path.join(baseDir, "daemons");
}
@@ -69,7 +64,21 @@ function daemonsDir(baseDir: string): string {
* plans/daemon-c01-machineid-anchor.md.
*/
function daemonDirById(baseDir: string, id: string): string {
- return path.join(daemonsDir(baseDir), id);
+ return path.join(daemonsDir(baseDir), validateDaemonId(id));
+}
+
+function validateMachineId(machineId: string): string {
+ if (!MACHINE_ID_PATTERN.test(machineId)) throw new Error("invalid machine identity returned by server");
+ return machineId;
+}
+
+function isDaemonId(id: string): boolean {
+ return MACHINE_ID_PATTERN.test(id) || LEGACY_DAEMON_ID_PATTERN.test(id);
+}
+
+function validateDaemonId(id: string): string {
+ if (!isDaemonId(id)) throw new Error("invalid daemon id");
+ return id;
}
function pidfilePathById(baseDir: string, id: string): string {
@@ -81,17 +90,6 @@ function statusFilePathById(baseDir: string, id: string): string {
return path.join(daemonDirById(baseDir, id), "status.json");
}
-/**
- * A `cmk_` paste with no persisted credential file has no machineId to anchor
- * on yet. It's a STABLE key (unlike a one-time `cmt_`), so hashing it is a
- * safe fallback id that won't drift across reconnects — the drift bug was
- * `cmt_`-only. Once the server confirms identity and a credential file lands,
- * subsequent starts resolve the real machineId.
- */
-function fallbackIdForStableKey(machineKey: string): string {
- return keyHash(machineKey);
-}
-
function isProcessAlive(pid: number): boolean {
try {
process.kill(pid, 0);
@@ -101,45 +99,158 @@ function isProcessAlive(pid: number): boolean {
}
}
-function readPidFile(filePath: string): { pid: number; key: string } | null {
+async function waitForPidExit(pid: number, timeoutMs: number): Promise<boolean> {
+ const deadline = Date.now() + timeoutMs;
+ while (Date.now() < deadline) {
+ if (!isProcessAlive(pid)) return true;
+ await new Promise((resolve) => setTimeout(resolve, POLL_MS));
+ }
+ return !isProcessAlive(pid);
+}
+
+export interface DaemonPidFile {
+ pid: number;
+ machineId?: string;
+ startedAt?: string;
+ ownerToken?: string;
+ key?: string;
+}
+
+function parsePidFileContent(raw: string): DaemonPidFile | null {
+ try {
+ const content = JSON.parse(raw);
+ if (!Number.isInteger(content.pid) || content.pid <= 0) return null;
+ if (
+ typeof content.machineId === "string" &&
+ typeof content.startedAt === "string" &&
+ typeof content.ownerToken === "string"
+ ) {
+ return {
+ pid: content.pid,
+ machineId: content.machineId,
+ startedAt: content.startedAt,
+ ownerToken: content.ownerToken,
+ };
+ }
+ if (typeof content.key === "string") return { pid: content.pid, key: content.key };
+ } catch { /* malformed */ }
+ return null;
+}
+
+export function readPidFile(filePath: string): DaemonPidFile | null {
if (!fs.existsSync(filePath)) return null;
try {
- const content = JSON.parse(fs.readFileSync(filePath, "utf8"));
- if (typeof content.pid === "number" && typeof content.key === "string") return content;
+ return parsePidFileContent(fs.readFileSync(filePath, "utf8"));
} catch { /* malformed */ }
return null;
}
-function writePidFile(filePath: string, pid: number, machineKey: string): void {
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
- fs.writeFileSync(filePath, JSON.stringify({ pid, key: machineKey }));
+function ensurePrivateDir(dir: string): void {
+ fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+ fs.chmodSync(dir, 0o700);
}
-/**
- * Acquire the FINAL per-daemon lock, keyed on the stable id (machineId). Rejects
- * a double-start if a live process already holds this id's pidfile. `key` is
- * stored in the pidfile only as a human breadcrumb; the LOCK identity is the id.
- */
-function acquireLock(baseDir: string, id: string, key: string): string {
- const pf = pidfilePathById(baseDir, id);
- const existing = readPidFile(pf);
- if (existing && isProcessAlive(existing.pid)) {
- log.error(`daemon '${id}' already running (pid ${existing.pid}). Stop it first or remove ${pf}`);
- process.exit(1);
+function writeExclusive(filePath: string, value: Record<string, unknown>): void {
+ const dir = path.dirname(filePath);
+ ensurePrivateDir(dir);
+ const tempPath = path.join(
+ dir,
+ `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(12).toString("hex")}.tmp`,
+ );
+ let fd: number | null = fs.openSync(tempPath, "wx", 0o600);
+ try {
+ fs.writeFileSync(fd, JSON.stringify(value));
+ fs.fsyncSync(fd);
+ fs.closeSync(fd);
+ fd = null;
+ fs.chmodSync(tempPath, 0o600);
+ fs.linkSync(tempPath, filePath);
+ const dirFd = fs.openSync(dir, "r");
+ try {
+ fs.fsyncSync(dirFd);
+ } finally {
+ fs.closeSync(dirFd);
+ }
+ } finally {
+ if (fd !== null) {
+ try { fs.closeSync(fd); } catch { /* best effort */ }
+ }
+ try { fs.unlinkSync(tempPath); } catch { /* best effort */ }
}
- writePidFile(pf, process.pid, key);
- return pf;
}
-function releaseLock(pf: string): void {
+function secureExistingFile(filePath: string): void {
+ if (!fs.existsSync(filePath)) return;
+ const stat = fs.lstatSync(filePath);
+ if (!stat.isFile()) throw new Error("unsafe daemon ownership file type");
+ fs.chmodSync(filePath, 0o600);
+}
+
+function removeOwnedFile(filePath: string, pid: number, ownerToken: string): void {
try {
- const content = readPidFile(pf);
- if (content && content.pid === process.pid) {
- fs.unlinkSync(pf);
+ const content = readPidFile(filePath);
+ if (content?.pid === pid && content.ownerToken === ownerToken) {
+ fs.unlinkSync(filePath);
}
} catch { /* best effort */ }
}
+function removePidFileIfMatches(filePath: string, expected: DaemonPidFile): void {
+ if (expected.ownerToken) {
+ removeOwnedFile(filePath, expected.pid, expected.ownerToken);
+ return;
+ }
+ try {
+ const current = readPidFile(filePath);
+ if (current?.pid === expected.pid && current.key === expected.key) fs.unlinkSync(filePath);
+ } catch { /* best effort */ }
+}
+
+function malformedPidHint(raw: string): number | null {
+ const match = raw.match(/"pid"\s*:\s*(\d+)/);
+ if (!match) return null;
+ const pid = Number(match[1]);
+ return Number.isInteger(pid) && pid > 0 ? pid : null;
+}
+
+function clearStaleOwnership(filePath: string, liveError: (pid: number) => Error): void {
+ if (!fs.existsSync(filePath)) return;
+ const valid = readPidFile(filePath);
+ if (valid) {
+ if (isProcessAlive(valid.pid)) throw liveError(valid.pid);
+ removePidFileIfMatches(filePath, valid);
+ return;
+ }
+
+ let raw: string;
+ let before: fs.Stats;
+ try {
+ before = fs.statSync(filePath);
+ raw = fs.readFileSync(filePath, "utf8");
+ const afterRead = fs.statSync(filePath);
+ if (
+ afterRead.dev !== before.dev ||
+ afterRead.ino !== before.ino ||
+ afterRead.size !== before.size ||
+ afterRead.mtimeMs !== before.mtimeMs
+ ) return;
+ } catch {
+ return;
+ }
+ const pid = malformedPidHint(raw);
+ if (pid && isProcessAlive(pid)) throw liveError(pid);
+ try {
+ const current = fs.statSync(filePath);
+ if (
+ current.dev !== before.dev ||
+ current.ino !== before.ino ||
+ current.size !== before.size ||
+ current.mtimeMs !== before.mtimeMs
+ ) return;
+ fs.unlinkSync(filePath);
+ } catch { /* best effort */ }
+}
+
/**
* COARSE start-lock for the `cmt_` path (C0.1): the machineId isn't known until
* after async `/activate`, so this baseDir-level lock blocks a concurrent local
@@ -150,17 +261,68 @@ function releaseLock(pf: string): void {
function coarseStartLockPath(baseDir: string): string {
return path.join(daemonsDir(baseDir), ".start.lock");
}
-function acquireCoarseLock(baseDir: string): string {
+function acquireCoarseLock(baseDir: string, ownerToken: string): string {
const lf = coarseStartLockPath(baseDir);
- const existing = readPidFile(lf);
- if (existing && isProcessAlive(existing.pid)) {
- log.error(`another daemon start is in progress on this machine (pid ${existing.pid}). Wait for it, or remove ${lf}`);
- process.exit(1);
- }
- writePidFile(lf, process.pid, "coarse-start-lock");
+ ensurePrivateDir(path.dirname(lf));
+ secureExistingFile(lf);
+ clearStaleOwnership(lf, (pid) => new Error(`another daemon start is in progress on this machine (pid ${pid})`));
+ writeExclusive(lf, { pid: process.pid, machineId: "coarse", startedAt: new Date().toISOString(), ownerToken });
return lf;
}
+function acquireLaunchLock(baseDir: string, machineId: string, ownerToken: string): string {
+ const daemonDir = daemonDirById(baseDir, machineId);
+ ensurePrivateDir(daemonDir);
+ const lockPath = path.join(daemonDir, "daemon.launch.lock");
+ const finalPath = pidfilePathById(baseDir, machineId);
+ secureExistingFile(lockPath);
+ secureExistingFile(finalPath);
+ clearStaleOwnership(finalPath, (pid) => new Error(`daemon '${machineId}' already running (pid ${pid})`));
+ clearStaleOwnership(lockPath, (pid) => new Error(`daemon '${machineId}' start already in progress (pid ${pid})`));
+ writeExclusive(lockPath, { pid: process.pid, machineId, startedAt: new Date().toISOString(), ownerToken });
+ return lockPath;
+}
+
+function commitFinalPidfile(
+ baseDir: string,
+ machineId: string,
+ pid: number,
+ startedAt: string,
+ ownerToken: string,
+): string {
+ const filePath = pidfilePathById(baseDir, machineId);
+ writeExclusive(filePath, { pid, machineId, startedAt, ownerToken });
+ return filePath;
+}
+
+function legacyPidfileCandidates(baseDir: string): string[] {
+ const dir = daemonsDir(baseDir);
+ if (!fs.existsSync(dir)) return [];
+ const candidates: string[] = [];
+ for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+ if (entry.isDirectory()) {
+ candidates.push(path.join(dir, entry.name, "daemon.pid"));
+ } else if (entry.isFile() && entry.name.endsWith(".pid")) {
+ candidates.push(path.join(dir, entry.name));
+ }
+ }
+ return candidates;
+}
+
+function reconcileLegacyMachineKeyOwnership(baseDir: string, machineKey: string): void {
+ for (const candidate of legacyPidfileCandidates(baseDir)) {
+ const owner = readPidFile(candidate);
+ if (!owner?.key || owner.key !== machineKey) continue;
+ secureExistingFile(candidate);
+ const current = readPidFile(candidate);
+ if (!current?.key || current.key !== machineKey) continue;
+ if (isProcessAlive(current.pid)) {
+ throw new Error(`legacy daemon already running (pid ${current.pid})`);
+ }
+ removePidFileIfMatches(candidate, current);
+ }
+}
+
/* ------------------------------------------------------------------ */
/* daemon list */
/* ------------------------------------------------------------------ */
@@ -172,9 +334,9 @@ export interface DaemonListOpts {
export interface DaemonInfo {
/**
* The daemon's addressing id, shown to humans and passed to `daemon stop
- * <id>`. It is the pidfile's keyHash name — NOT the machine key (a credential
- * that must never enter the human operation path, red line 2). list shows it,
- * stop eats it → the two compose (the whole point of C3).
+ * <id>`. It is the server-issued machine id — NOT the machine key (a
+ * credential that must never enter the human operation path). list shows it,
+ * stop accepts it, so the two compose.
*/
id: string;
pid: number;
@@ -208,7 +370,7 @@ export function daemonList(opts: DaemonListOpts): DaemonInfo[] {
const alive = isProcessAlive(data.pid);
if (!alive) {
// Prune the stale pidfile (subdir daemon.pid or legacy flat).
- try { fs.unlinkSync(pidfile); } catch { /* ok */ }
+ removePidFileIfMatches(pidfile, data);
}
// Per-daemon status: read THIS daemon's own snapshot (C0), not a global one.
let agents: number | null = null;
@@ -226,9 +388,9 @@ export function daemonList(opts: DaemonListOpts): DaemonInfo[] {
};
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
- // Per-key subdir layout (C0): daemons/<id>/daemon.pid + status.json. Each
+ // Per-machine subdir layout: daemons/<id>/daemon.pid + status.json. Each
// daemon has its own directory; id = the directory name.
- if (entry.isDirectory()) {
+ if (entry.isDirectory() && isDaemonId(entry.name)) {
const id = entry.name;
pushRow(id, path.join(dir, id, "daemon.pid"), path.join(dir, id, "status.json"));
}
@@ -304,13 +466,17 @@ function daemonStatusFromFile(statusPath: string, nowMs: number): DaemonStatusRe
}
}
-/** The subdir ids of daemons that have a per-key status file (C0). */
+/** The subdir ids of daemons that have a per-machine status file. */
function daemonIdsWithStatus(baseDir: string): string[] {
const dir = daemonsDir(baseDir);
if (!fs.existsSync(dir)) return [];
const ids: string[] = [];
for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
- if (entry.isDirectory() && fs.existsSync(path.join(dir, entry.name, "status.json"))) {
+ if (
+ entry.isDirectory() &&
+ isDaemonId(entry.name) &&
+ fs.existsSync(path.join(dir, entry.name, "status.json"))
+ ) {
ids.push(entry.name);
}
}
@@ -320,7 +486,7 @@ function daemonIdsWithStatus(baseDir: string): string[] {
export function daemonStatus(opts: DaemonStatusOpts): DaemonStatusResult {
const baseDir = opts.baseDir || process.env.ALOOK_DATA_DIR || DEFAULT_BASE_DIR;
const nowMs = (opts.now ?? (() => Date.now()))();
- // Explicit id → that daemon's per-key status.
+ // Explicit id → that daemon's per-machine status.
if (opts.id) {
return daemonStatusFromFile(statusFilePathById(baseDir, opts.id), nowMs);
}
@@ -340,7 +506,7 @@ export function daemonStatus(opts: DaemonStatusOpts): DaemonStatusResult {
/* ------------------------------------------------------------------ */
export interface DaemonStopOpts {
- /** The id shown in `daemon list` (= the daemon's subdir name / keyHash). */
+ /** The id shown in `daemon list` (= the daemon's machine-id subdir name). */
id: string;
baseDir?: string;
}
@@ -361,25 +527,30 @@ async function stopByPidfile(pf: string, notFoundHint: string): Promise<void> {
}
if (!isProcessAlive(data.pid)) {
log.info(`stale pidfile (pid ${data.pid} is not running) — removing`);
- try { fs.unlinkSync(pf); } catch { /* ok */ }
+ removePidFileIfMatches(pf, data);
return;
}
log.info(`sending SIGTERM to daemon (pid ${data.pid})…`);
- process.kill(data.pid, "SIGTERM");
-
- const deadline = Date.now() + STOP_GRACE_MS;
- while (Date.now() < deadline && isProcessAlive(data.pid)) {
- await new Promise((r) => setTimeout(r, POLL_MS));
+ try {
+ process.kill(data.pid, "SIGTERM");
+ } catch (error) {
+ if (isProcessAlive(data.pid)) throw error;
}
- if (isProcessAlive(data.pid)) {
+ if (!await waitForPidExit(data.pid, STOP_GRACE_MS)) {
log.error(`daemon (pid ${data.pid}) did not exit in ${STOP_GRACE_MS / 1000}s — sending SIGKILL`);
- process.kill(data.pid, "SIGKILL");
- } else {
- log.info("daemon stopped");
+ try {
+ process.kill(data.pid, "SIGKILL");
+ } catch (error) {
+ if (isProcessAlive(data.pid)) throw error;
+ }
+ if (!await waitForPidExit(data.pid, STOP_KILL_GRACE_MS)) {
+ throw new Error(`daemon (pid ${data.pid}) is still running after SIGKILL`);
+ }
}
- try { fs.unlinkSync(pf); } catch { /* ok */ }
+ log.info("daemon stopped");
+ removePidFileIfMatches(pf, data);
}
export async function daemonStop(opts: DaemonStopOpts): Promise<void> {
@@ -402,6 +573,7 @@ export interface DaemonStartOpts {
serverUrl?: string;
wsUrl?: string;
baseDir?: string;
+ foreground?: boolean;
}
/**
@@ -411,11 +583,14 @@ export interface DaemonStartOpts {
* files accumulate on disk.
*/
export function credentialFilePathByMachineId(baseDir: string, machineId: string): string {
- return path.join(daemonsDir(baseDir), `${machineId}.credential.json`);
+ return path.join(daemonsDir(baseDir), `${validateMachineId(machineId)}.credential.json`);
}
function readCredentialFile(filePath: string): { credential: string; machineId: string } | null {
if (!fs.existsSync(filePath)) return null;
+ const stat = fs.lstatSync(filePath);
+ if (!stat.isFile()) throw new Error("unsafe daemon credential file type");
+ fs.chmodSync(filePath, 0o600);
try {
const content = JSON.parse(fs.readFileSync(filePath, "utf8"));
if (
@@ -430,8 +605,32 @@ function readCredentialFile(filePath: string): { credential: string; machineId:
}
function writeCredentialFile(filePath: string, credential: string, machineId: string): void {
- fs.mkdirSync(path.dirname(filePath), { recursive: true });
- fs.writeFileSync(filePath, JSON.stringify({ credential, machineId }), { mode: 0o600 });
+ const dir = path.dirname(filePath);
+ ensurePrivateDir(dir);
+ const tempPath = path.join(
+ dir,
+ `.${path.basename(filePath)}.${process.pid}.${crypto.randomBytes(12).toString("hex")}.tmp`,
+ );
+ let fd: number | null = fs.openSync(tempPath, "wx", 0o600);
+ try {
+ fs.writeFileSync(fd, JSON.stringify({ credential, machineId }));
+ fs.fsyncSync(fd);
+ fs.closeSync(fd);
+ fd = null;
+ fs.chmodSync(tempPath, 0o600);
+ fs.renameSync(tempPath, filePath);
+ const dirFd = fs.openSync(dir, "r");
+ try {
+ fs.fsyncSync(dirFd);
+ } finally {
+ fs.closeSync(dirFd);
+ }
+ } finally {
+ if (fd !== null) {
+ try { fs.closeSync(fd); } catch { /* best effort */ }
+ }
+ try { fs.unlinkSync(tempPath); } catch { /* best effort */ }
+ }
}
/**
@@ -488,77 +687,53 @@ async function activatePairingToken(
return { credential: json.credential, machineId: json.machineId };
}
-export async function daemonStart(opts: DaemonStartOpts): Promise<void> {
+async function resolveMachineIdentity(serverUrl: string, credential: string): Promise<string> {
+ const response = await fetch(`${serverUrl}/api/community/daemon/identity`, {
+ headers: { authorization: `Bearer ${credential}` },
+ });
+ const body = await response.json().catch(() => ({})) as { machineId?: string; error?: string };
+ if (!response.ok || typeof body.machineId !== "string" || body.machineId.length === 0) {
+ throw new Error(body.error ?? `identity failed (${response.status})`);
+ }
+ return body.machineId;
+}
+
+interface PreparedStart {
+ prepared: PreparedDaemon;
+ launchLockPath: string;
+}
+
+async function prepareDaemonStart(opts: DaemonStartOpts): Promise<PreparedStart> {
const serverUrl = opts.serverUrl || process.env.ALOOK_SERVER_URL;
const wsUrl = opts.wsUrl || process.env.ALOOK_SERVER_WS_URL;
-
- if (!serverUrl) {
- log.error("Server URL required — pass --server-url or set ALOOK_SERVER_URL");
- process.exit(2);
- }
- if (!wsUrl) {
- log.error("WebSocket URL required — pass --ws-url or set ALOOK_SERVER_WS_URL");
- process.exit(2);
+ if (!serverUrl) throw new Error("Server URL required — pass --server-url or set ALOOK_SERVER_URL");
+ if (!wsUrl) throw new Error("WebSocket URL required — pass --ws-url or set ALOOK_SERVER_WS_URL");
+ if (!opts.machineKey.startsWith("cmt_") && !opts.machineKey.startsWith("cmk_")) {
+ throw new Error("invalid machine key format — expected `cmt_` or `cmk_`");
}
-
const baseDir = opts.baseDir || process.env.ALOOK_DATA_DIR || DEFAULT_BASE_DIR;
-
- // Two-stage locking (C0.1): the daemon dir/pidfile anchor on the stable
- // machineId, which for a `cmt_` start isn't known until after async
- // /activate. So a `cmt_` start takes a COARSE baseDir lock now (blocks a
- // concurrent local start during the activate window), then hands off to the
- // FINAL machineId lock once activate returns — acquire-final-THEN-release-
- // coarse, so there's never an unlocked instant (Claudette 架构#499). A `cmk_`
- // start can resolve machineId up front (credential-file lookup) → one-step
- // final lock, no coarse stage. `coarsePf`/`pf` track which locks are held so
- // any early-exit path releases them.
- const isPairingStart = opts.machineKey.startsWith("cmt_");
- const coarsePf = isPairingStart ? acquireCoarseLock(baseDir) : null;
- let pf: string | null = null;
-
- const agentCliPath = resolveAlookCliPathWithFallback() ?? process.argv[1];
-
- // Detect installed agent CLIs. The list is reported to the server on
- // `ready` so the machine card can show a chip per CLI (with version).
- // We report EVERY runtime we know about (healthy AND unhealthy) so the
- // /community machine card can surface broken installs, not just missing
- // ones. Filtering to healthy-only happens on the reader side (bot picker,
- // server-side bots-POST validator).
- const runtimeDetections: RuntimeInfo[] = await detectRuntimes();
- const healthyRuntimeIds = runtimeDetections.filter((r) => r.status === "healthy").map((r) => r.id);
- log.info(
- healthyRuntimeIds.length === 0
- ? "no agent CLIs detected"
- : `detected agent CLIs: ${healthyRuntimeIds.join(", ")}`
- );
- const unhealthyIds = runtimeDetections
- .filter((r) => r.status === "unhealthy")
- .map((r) => `${r.id}(${r.lastError ?? "unknown"})`);
- if (unhealthyIds.length > 0) log.info(`unhealthy runtimes: ${unhealthyIds.join(", ")}`);
-
- const runtimeReport = runtimeDetections.map((r) => ({
- id: r.id,
- version: r.version,
- status: r.status,
- lastError: r.lastError,
- lastErrorAt: r.lastErrorAt,
- }));
-
- // Resolve the actual credential the daemon will dial with. Ordering:
- // 1. --machine-key starts with `cmt_` — POST /activate, get {cmk_, machineId},
- // write file at <daemonsDir>/<machineId>.credential.json.
- // 2. --machine-key starts with `cmk_` — scan on-disk credential files for
- // one whose stored credential matches; if found, reuse. Otherwise this
- // is a fresh paste with no machineId to key the file on — dial with
- // the plaintext but skip persistence until the server confirms
- // identity on the next boot.
- // 3. else → exit(2) "invalid machine key format".
- let dialingCredential: string;
- // The stable per-daemon id (machineId when known) that anchors the dir/lock.
- let daemonIdentity: string;
- if (opts.machineKey.startsWith("cmt_")) {
- log.info("activating pairing token…");
- try {
+ const ownerToken = crypto.randomBytes(24).toString("base64url");
+ const persisted = opts.machineKey.startsWith("cmk_")
+ ? findExistingCredentialForBearer(baseDir, opts.machineKey)
+ : null;
+ let coarseLockPath: string | null = null;
+ let launchLockPath: string | null = null;
+ try {
+ let machineKey = persisted?.credential;
+ let machineId = persisted ? validateMachineId(persisted.machineId) : undefined;
+ if (machineKey && machineId) {
+ launchLockPath = acquireLaunchLock(baseDir, machineId, ownerToken);
+ } else {
+ coarseLockPath = acquireCoarseLock(baseDir, ownerToken);
+ if (opts.machineKey.startsWith("cmk_")) {
+ reconcileLegacyMachineKeyOwnership(baseDir, opts.machineKey);
+ }
+ }
+ const runtimeReport: RuntimeInfo[] = await detectRuntimes();
+ const healthyRuntimeIds = runtimeReport
+ .filter((runtime) => runtime.status === "healthy")
+ .map((runtime) => runtime.id);
+ if (opts.machineKey.startsWith("cmt_")) {
const activated = await activatePairingToken(
serverUrl,
opts.machineKey,
@@ -569,124 +744,232 @@ export async function daemonStart(opts: DaemonStartOpts): Promise<void> {
readDaemonVersion(),
runtimeReport,
);
- dialingCredential = activated.credential;
- writeCredentialFile(
- credentialFilePathByMachineId(baseDir, activated.machineId),
- dialingCredential,
- activated.machineId
- );
- // Now the stable machineId is known → acquire the FINAL lock, THEN drop
- // the coarse lock (overlap, no unlocked instant — C0.1 invariant). The
- // machineId lock is the real double-start backstop: two different cmt_
- // for the same machine both resolve here to the same machineId, so the
- // second start is rejected regardless of which token it used.
- daemonIdentity = activated.machineId;
- pf = acquireLock(baseDir, daemonIdentity, dialingCredential);
- if (coarsePf) releaseLock(coarsePf);
- log.info("pairing token activated — credential persisted");
- } catch (err) {
- log.error(`activation failed: ${err instanceof Error ? err.message : String(err)}`);
- if (coarsePf) releaseLock(coarsePf);
- process.exit(1);
- }
- } else if (opts.machineKey.startsWith("cmk_")) {
- const match = findExistingCredentialForBearer(baseDir, opts.machineKey);
- if (match) {
- dialingCredential = match.credential;
- // Persisted credential → stable machineId is known up front. One-step
- // final lock, no coarse stage needed.
- daemonIdentity = match.machineId;
- log.info("using persisted daemon credential");
+ machineKey = activated.credential;
+ machineId = validateMachineId(activated.machineId);
} else {
- // No file → dial with the pasted credential; if it works the server
- // owns identity anyway. We don't persist since we can't derive the
- // filename without machineId. `cmk_` is a STABLE key (not a one-time
- // token), so hashing it is a non-drifting fallback id until a credential
- // file lands and a later start resolves the real machineId.
- dialingCredential = opts.machineKey;
- daemonIdentity = fallbackIdForStableKey(opts.machineKey);
- log.info("dialing with provided cmk_ (no on-disk record)");
+ machineKey ??= opts.machineKey;
+ machineId ??= validateMachineId(await resolveMachineIdentity(serverUrl, opts.machineKey));
}
- pf = acquireLock(baseDir, daemonIdentity, dialingCredential);
- } else {
- log.error("invalid machine key format — expected `cmt_` (pairing token) or `cmk_` (credential)");
- if (coarsePf) releaseLock(coarsePf);
- process.exit(2);
+ writeCredentialFile(credentialFilePathByMachineId(baseDir, machineId), machineKey, machineId);
+ launchLockPath ??= acquireLaunchLock(baseDir, machineId, ownerToken);
+ if (coarseLockPath) removeOwnedFile(coarseLockPath, process.pid, ownerToken);
+ const startedAt = new Date().toISOString();
+ return {
+ launchLockPath,
+ prepared: {
+ machineId,
+ machineKey,
+ serverUrl,
+ wsUrl,
+ baseDir,
+ daemonDir: daemonDirById(baseDir, machineId),
+ statusFilePath: statusFilePathById(baseDir, machineId),
+ agentCliPath: resolveAlookCliPathWithFallback() ?? process.argv[1],
+ runtimeReport,
+ healthyRuntimeIds,
+ hostname: os.hostname(),
+ platform: process.platform,
+ arch: process.arch,
+ osRelease: os.release(),
+ daemonVersion: readDaemonVersion(),
+ ownerToken,
+ startedAt,
+ },
+ };
+ } catch (error) {
+ if (launchLockPath) removeOwnedFile(launchLockPath, process.pid, ownerToken);
+ if (coarseLockPath) removeOwnedFile(coarseLockPath, process.pid, ownerToken);
+ throw error;
}
+}
+
+function runnerArguments(): string[] {
+ const command = process.env.ALOOK_DAEMON_PACKAGE_WRAPPER === "1" ? ["run"] : ["daemon", "run"];
+ return [...process.execArgv, process.argv[1]!, ...command];
+}
- const daemon = await createDaemon({
- machineKey: dialingCredential,
- serverUrl,
- serverWsUrl: wsUrl,
- webSocketFactory: (url, headers) => new WebSocket(url, { headers }),
- runtimeReport,
- // Pick the driver for the runtime the agent actually asked for. The
- // request is a hard requirement — if the runtime isn't detected on this
- // host we throw `UnknownRuntimeError`, which `agentRouter` catches and
- // forwards to the server as a `session.error{code:"runtime_not_available"}`
- // so the machine card surfaces the mismatch instead of silently launching
- // a different runtime.
- // driverFor throws UnknownRuntimeError for a runtime the daemon does not
- // know about at all. The router additionally short-circuits dispatch when
- // a KNOWN runtime is currently unhealthy — see AgentRouter wiring in
- // createDaemon. Both throws land in the same catch block in agentRouter
- // and surface as bot_runtime_missing + runtime_not_available.
- driverFor: (_agentId, runtimeConfig) => {
- const requested = runtimeConfig?.runtime;
- // Validate against the FULL registry, NOT the advertised subset:
- // `runtimeReport`/`detectRuntimes` now advertises only SELECTABLE_RUNTIMES
- // (what a user may pick when creating a bot), but a bot created BEFORE a
- // runtime was hidden must still resolve its driver on wake (hide, not
- // delete). "Can this run" (registry) and "can a user select it"
- // (advertised) are different questions — this gate is the former.
- const known: string[] = listRuntimeIds();
- if (!requested || !known.includes(requested)) {
- throw new UnknownRuntimeError(requested, healthyRuntimeIds);
+function spawnBlockedRunner(): ChildProcess {
+ return spawn(process.execPath, runnerArguments(), {
+ detached: true,
+ stdio: ["ignore", "ignore", "ignore", "ipc"],
+ });
+}
+
+function testCheckpoint(name: string, childPid: number): void {
+ if (process.env.NODE_ENV !== "test" || process.env.ALOOK_DAEMON_TEST_PAUSE_AT !== name) return;
+ const checkpointFile = process.env.ALOOK_DAEMON_TEST_CHECKPOINT_FILE;
+ if (!checkpointFile) return;
+ fs.writeFileSync(checkpointFile, JSON.stringify({ name, parentPid: process.pid, childPid }), { mode: 0o600 });
+ const view = new Int32Array(new SharedArrayBuffer(4));
+ while (!fs.existsSync(`${checkpointFile}.continue`)) Atomics.wait(view, 0, 0, 25);
+}
+
+function sendPrepared(child: ChildProcess, prepared: PreparedDaemon): Promise<void> {
+ return new Promise((resolve, reject) => {
+ if (!child.send) {
+ reject(new Error("daemon child has no IPC channel"));
+ return;
+ }
+ child.send({ type: "daemon:prepared", prepared }, (error) => error ? reject(error) : resolve());
+ });
+}
+
+function waitForReceipt(child: ChildProcess, prepared: PreparedDaemon): Promise<DaemonReadyReceipt> {
+ return new Promise((resolve, reject) => {
+ const settle = (error?: Error, receipt?: DaemonReadyReceipt): void => {
+ clearTimeout(timeout);
+ child.removeAllListeners("message");
+ child.removeAllListeners("exit");
+ child.removeAllListeners("error");
+ if (error) reject(error);
+ else resolve(receipt!);
+ };
+ const configuredTestTimeout = process.env.NODE_ENV === "test"
+ ? Number(process.env.ALOOK_DAEMON_TEST_RECEIPT_TIMEOUT_MS)
+ : NaN;
+ const receiptTimeoutMs = Number.isFinite(configuredTestTimeout) && configuredTestTimeout > 0
+ ? configuredTestTimeout
+ : START_RECEIPT_TIMEOUT_MS;
+ const timeout = setTimeout(
+ () => settle(new Error(`daemon start timed out; inspect ${path.join(prepared.daemonDir, "daemon.log")}`)),
+ receiptTimeoutMs,
+ );
+ child.on("message", (message: unknown) => {
+ const accepted = message as { type?: string; pid?: number; machineId?: string };
+ if (accepted.type === "daemon:accepted") {
+ if (accepted.pid !== child.pid || accepted.machineId !== prepared.machineId) {
+ settle(new Error("daemon child returned an invalid prepared acknowledgment"));
+ return;
+ }
+ testCheckpoint("after_ipc_send", child.pid!);
+ return;
}
- // `requested` was just checked to be in the registry, so it's a valid
- // RuntimeId — cast to satisfy the typed factory map.
- return getDriver(requested as Parameters<typeof getDriver>[0]);
- },
- capabilities: CAPABILITIES,
- agentCliPath,
- workingDirectoryBase: baseDir,
- // Default-on bounded FSM trace + periodic status snapshot both live in THIS
- // daemon's per-key subdir `daemons/<keyHash>/` (batch C0), NOT a shared
- // <baseDir> path — so multiple daemons on one baseDir never interleave their
- // traces or clobber each other's status.json, and each daemon's trace gets
- // its OWN rotation budget (restoring T4's ≥12h-per-daemon retention). The
- // ALOOK_FSM_TRACE env override (createDaemon) still wins for deep dives.
- fsmTraceDir: daemonDirById(baseDir, daemonIdentity),
- statusFilePath: statusFilePathById(baseDir, daemonIdentity),
- hostname: os.hostname(),
- platform: process.platform,
- arch: process.arch,
- osRelease: os.release(),
- daemonVersion: readDaemonVersion(),
- logger: log,
- onAuthRejected: () => {
- log.error("machine key rejected by server — is it correct / has it expired?");
- if (pf) releaseLock(pf);
- process.exit(1);
- },
+ const receipt = message as DaemonReadyReceipt;
+ if (receipt?.pid !== child.pid || receipt.machineId !== prepared.machineId || receipt.startedAt !== prepared.startedAt) {
+ settle(new Error("daemon child returned an invalid start receipt"));
+ return;
+ }
+ settle(undefined, receipt);
+ });
+ child.once("exit", (code, signal) => {
+ settle(new Error(`daemon child exited before ready (${signal ?? code}); inspect ${path.join(prepared.daemonDir, "daemon.log")}`));
+ });
+ child.once("error", (error) => settle(error));
});
+}
- log.info(`daemon up — proxy at ${daemon.proxyUrl}, dialing ${wsUrl}`);
+function waitForChildExit(child: ChildProcess, timeoutMs: number): Promise<boolean> {
+ if (child.exitCode !== null || child.signalCode !== null) return Promise.resolve(true);
+ return new Promise((resolve) => {
+ const finish = (exited: boolean): void => {
+ clearTimeout(timeout);
+ child.removeListener("exit", onExit);
+ resolve(exited);
+ };
+ const onExit = (): void => finish(true);
+ const timeout = setTimeout(() => finish(child.exitCode !== null || child.signalCode !== null), timeoutMs);
+ child.once("exit", onExit);
+ if (child.exitCode !== null || child.signalCode !== null) finish(true);
+ });
+}
- // Event-driven "control plane OPEN" — was previously a 200ms setInterval
- // polling `daemon.isOpen()`. `onOpen` fires on every (re)connect including
- // the first one, so we log on subsequent reconnects too.
- daemon.onOpen(() => log.info("control plane OPEN"));
+async function terminateRunnerAndWait(child: ChildProcess): Promise<void> {
+ try { child.kill("SIGTERM"); } catch { /* exit observation below is authoritative */ }
+ if (await waitForChildExit(child, RUNNER_TERM_GRACE_MS)) return;
+ try { child.kill("SIGKILL"); } catch { /* exit observation below is authoritative */ }
+ if (await waitForChildExit(child, RUNNER_KILL_GRACE_MS)) return;
+ throw new Error(`daemon child ${child.pid ?? "unknown"} did not exit after SIGKILL`);
+}
- const shutdown = async () => {
- log.info("shutting down…");
- if (pf) releaseLock(pf);
- await daemon.stop();
- process.exit(0);
- };
- process.on("SIGINT", shutdown);
- process.on("SIGTERM", shutdown);
+export async function daemonStart(opts: DaemonStartOpts): Promise<void> {
+ const { prepared, launchLockPath } = await prepareDaemonStart(opts);
+ const finalPidfile = pidfilePathById(prepared.baseDir, prepared.machineId);
+ if (opts.foreground) {
+ try {
+ commitFinalPidfile(prepared.baseDir, prepared.machineId, process.pid, prepared.startedAt, prepared.ownerToken);
+ return await runPreparedDaemon(prepared, {
+ foreground: true,
+ onReady: () => removeOwnedFile(launchLockPath, process.pid, prepared.ownerToken),
+ releaseOwnership: () => removeOwnedFile(finalPidfile, process.pid, prepared.ownerToken),
+ });
+ } finally {
+ removeOwnedFile(finalPidfile, process.pid, prepared.ownerToken);
+ removeOwnedFile(launchLockPath, process.pid, prepared.ownerToken);
+ }
+ }
+
+ const child = spawnBlockedRunner();
+ if (!child.pid) {
+ removeOwnedFile(launchLockPath, process.pid, prepared.ownerToken);
+ throw new Error("failed to spawn daemon child");
+ }
+ try {
+ testCheckpoint("after_spawn_before_final", child.pid);
+ commitFinalPidfile(prepared.baseDir, prepared.machineId, child.pid, prepared.startedAt, prepared.ownerToken);
+ testCheckpoint("after_final_before_ipc", child.pid);
+ const receiptPromise = waitForReceipt(child, prepared);
+ await sendPrepared(child, prepared);
+ const receipt = await receiptPromise;
+ removeOwnedFile(launchLockPath, process.pid, prepared.ownerToken);
+ child.unref();
+ log.info(`daemon started in background (pid ${receipt.pid}); log ${receipt.logPath}`);
+ } catch (error) {
+ await terminateRunnerAndWait(child);
+ removeOwnedFile(finalPidfile, child.pid, prepared.ownerToken);
+ removeOwnedFile(launchLockPath, process.pid, prepared.ownerToken);
+ throw error;
+ }
+}
- // Keep the process alive.
- await new Promise(() => {});
+export async function daemonRunFromIpc(ipc: typeof process = process): Promise<never> {
+ if (typeof ipc.send !== "function") throw new Error("daemon run requires parent IPC");
+ if (!ipc.connected) throw new Error("daemon parent disconnected before prepared payload");
+ return await new Promise<never>((_resolve, reject) => {
+ let received = false;
+ ipc.once("disconnect", () => {
+ if (!received) reject(new Error("daemon parent disconnected before prepared payload"));
+ });
+ ipc.once("message", (message: unknown) => {
+ received = true;
+ const payload = message as { type?: string; prepared?: PreparedDaemon };
+ const prepared = payload.prepared;
+ payload.prepared = undefined;
+ if (payload.type !== "daemon:prepared" || !prepared) {
+ reject(new Error("invalid daemon prepared payload"));
+ return;
+ }
+ const finalPidfile = pidfilePathById(prepared.baseDir, prepared.machineId);
+ const owner = readPidFile(finalPidfile);
+ if (owner?.pid !== ipc.pid || owner.machineId !== prepared.machineId || owner.ownerToken !== prepared.ownerToken) {
+ reject(new Error("daemon ownership validation failed"));
+ return;
+ }
+ sendIpcBestEffort(ipc, { type: "daemon:accepted", pid: ipc.pid, machineId: prepared.machineId });
+ void runPreparedDaemon(prepared, {
+ foreground: false,
+ onReady: (receipt) => {
+ if (process.env.NODE_ENV === "test" && process.env.ALOOK_DAEMON_TEST_SKIP_READY === "1") return;
+ sendIpcBestEffort(ipc, receipt, true);
+ },
+ releaseOwnership: () => {
+ const marker = process.env.ALOOK_DAEMON_TEST_RELEASE_MARKER;
+ if (process.env.NODE_ENV === "test" && marker) fs.appendFileSync(marker, `${ipc.pid}\n`, { mode: 0o600 });
+ removeOwnedFile(finalPidfile, ipc.pid, prepared.ownerToken);
+ },
+ }).catch(reject);
+ });
+ });
+}
+
+function sendIpcBestEffort(ipc: typeof process, message: unknown, disconnectAfter = false): void {
+ if (!ipc.connected || typeof ipc.send !== "function") return;
+ const disconnect = (): void => {
+ if (!disconnectAfter) return;
+ try { ipc.disconnect?.(); } catch { /* parent notification is best effort */ }
+ };
+ try {
+ ipc.send(message, () => disconnect());
+ } catch {
+ disconnect();
+ }
}
diff --git a/src/daemon/src/cli/daemonStop.test.ts b/src/daemon/src/cli/daemonStop.test.ts
index 41771f7f7..7cb210b4c 100644
--- a/src/daemon/src/cli/daemonStop.test.ts
+++ b/src/daemon/src/cli/daemonStop.test.ts
@@ -35,7 +35,7 @@ describe("daemonStop — event-loop friendly (no spin loop)", () => {
// where the event lags behind the OS process actually being gone).
const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));
- const id = "abc123def456";
+ const id = "cm_abc123def456";
const daemonsDir = path.join(baseDir, "daemons");
// Per-key subdir layout (C0): pidfile is daemons/<id>/daemon.pid.
fs.mkdirSync(path.join(daemonsDir, id), { recursive: true });
@@ -76,8 +76,55 @@ describe("daemonStop — event-loop friendly (no spin loop)", () => {
expect(child.exitCode !== null || child.signalCode !== null).toBe(true);
}, 15_000);
+ it("keeps ownership through SIGKILL until a SIGTERM-ignoring process is dead", async () => {
+ const child = spawn(
+ process.execPath,
+ ["-e", "process.on('SIGTERM',()=>{});process.stdout.write('ready');setInterval(()=>{},1000)"],
+ { stdio: ["ignore", "pipe", "ignore"] },
+ );
+ await new Promise<void>((resolve) => child.stdout!.once("data", () => resolve()));
+ const exited = new Promise<void>((resolve) => child.once("exit", () => resolve()));
+ const id = "cm_sigkill_test_1";
+ const dir = path.join(baseDir, "daemons", id);
+ fs.mkdirSync(dir, { recursive: true });
+ pidfile = path.join(dir, "daemon.pid");
+ fs.writeFileSync(pidfile, JSON.stringify({ pid: child.pid, key: "cmk_test_key" }));
+
+ await daemonStop({ id, baseDir });
+
+ expect(() => process.kill(child.pid!, 0)).toThrow();
+ expect(fs.existsSync(pidfile)).toBe(false);
+ await exited;
+ }, 15_000);
+
it("stop with an unknown id is a no-op (no throw), points at `daemon list`", async () => {
// No pidfile for this id → graceful message, no crash.
await expect(daemonStop({ id: "deadbeef0000", baseDir })).resolves.toBeUndefined();
});
+
+ it.each([
+ "../outside",
+ "/tmp/outside",
+ "cm_bad\\segment",
+ `cm_${"a".repeat(65)}`,
+ ])("rejects an unsafe id before resolving a pidfile: %s", async (id) => {
+ await expect(daemonStop({ id, baseDir })).rejects.toThrow("invalid daemon id");
+ });
+
+ it("does not read or signal a pid from a traversal-selected pidfile", async () => {
+ const child = spawn(process.execPath, ["-e", "setInterval(()=>{}, 1000)"], { stdio: "ignore" });
+ const outsideName = `${path.basename(baseDir)}-outside`;
+ const outsideDir = path.join(path.dirname(baseDir), outsideName);
+ const outsidePidfile = path.join(outsideDir, "daemon.pid");
+ fs.mkdirSync(outsideDir, { recursive: true });
+ fs.writeFileSync(outsidePidfile, JSON.stringify({ pid: child.pid, key: "cmk_outside" }));
+ try {
+ await expect(daemonStop({ id: `../../${outsideName}`, baseDir })).rejects.toThrow("invalid daemon id");
+ expect(() => process.kill(child.pid!, 0)).not.toThrow();
+ expect(fs.readFileSync(outsidePidfile, "utf8")).toContain("cmk_outside");
+ } finally {
+ child.kill("SIGKILL");
+ fs.rmSync(outsideDir, { recursive: true, force: true });
+ }
+ });
});
diff --git a/src/daemon/src/cli/index.test.ts b/src/daemon/src/cli/index.test.ts
index 36c0183be..d0658971f 100644
--- a/src/daemon/src/cli/index.test.ts
+++ b/src/daemon/src/cli/index.test.ts
@@ -1,4 +1,12 @@
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+
+const mockDaemonStart = vi.hoisted(() => vi.fn(async () => {}));
+const mockDaemonRunFromIpc = vi.hoisted(() => vi.fn(async () => new Promise<never>(() => {})));
+vi.mock("./daemonStart", async (importOriginal) => ({
+ ...await importOriginal<typeof import("./daemonStart")>(),
+ daemonStart: mockDaemonStart,
+ daemonRunFromIpc: mockDaemonRunFromIpc,
+}));
import { main, setApiForTesting, decodeTextEscapes } from "./index";
import type { ServerApi } from "../server/contract";
@@ -71,6 +79,30 @@ afterEach(() => {
}
});
+describe("daemon command contract", () => {
+ it("starts in background by default and forwards foreground explicitly", async () => {
+ await main(["daemon", "start", "--machine-key", "cmk_test", "--server-url", "http://server", "--ws-url", "ws://server"]);
+ expect(mockDaemonStart).toHaveBeenLastCalledWith(expect.objectContaining({
+ machineKey: "cmk_test",
+ foreground: false,
+ }));
+ await main(["daemon", "start", "--foreground", "--machine-key", "cmk_test", "--server-url", "http://server", "--ws-url", "ws://server"]);
+ expect(mockDaemonStart).toHaveBeenLastCalledWith(expect.objectContaining({
+ machineKey: "cmk_test",
+ foreground: true,
+ }));
+ });
+
+ it("keeps missing and unknown arguments in the canonical Commander parser", async () => {
+ await main(["daemon", "start"]);
+ expect(parseEnvelope(cap.lines())).toEqual(expect.objectContaining({ error: expect.stringContaining("--machine-key") }));
+ cap.restore();
+ cap = captureStdout();
+ await main(["daemon", "wat"]);
+ expect(parseEnvelope(cap.lines())).toEqual(expect.objectContaining({ error: expect.stringContaining("unknown command") }));
+ });
+});
+
describe("envelope contract", () => {
it("prints exactly one JSON object with only `success` on success", async () => {
setApiForTesting(
diff --git a/src/daemon/src/cli/index.ts b/src/daemon/src/cli/index.ts
index 316b6058f..e6c99a77b 100755
--- a/src/daemon/src/cli/index.ts
+++ b/src/daemon/src/cli/index.ts
@@ -21,7 +21,7 @@ import { pathToFileURL } from "node:url";
import type { ServerApi, Cursor, Message } from "../server/contract.js";
import { parseRef } from "../server/contract.js";
import { proxyServerApiFromEnv } from "./proxyServerApi.js";
-import { daemonStart, daemonStop, daemonList, daemonStatus, type DaemonInfo } from "./daemonStart.js";
+import { daemonRunFromIpc, daemonStart, daemonStop, daemonList, daemonStatus, type DaemonInfo } from "./daemonStart.js";
import { parseInviteToken } from "@alook/shared/lib/invite-link";
import { MAX_EMOJI_BYTES } from "@alook/shared/constants/community";
import { nowLocalISO, toLocalISO } from "../util/localTime.js";
@@ -880,6 +880,7 @@ function buildProgram(): Command {
.option("--server-url <url>", "server HTTP URL (or ALOOK_SERVER_URL env)")
.option("--ws-url <url>", "server WebSocket URL (or ALOOK_SERVER_WS_URL env)")
.option("--base-dir <path>", "data directory for agent workspaces and pidfile (or ALOOK_DATA_DIR env)")
+ .option("--foreground", "run in the current process and tee daemon logs to the terminal")
.exitOverride()
.configureOutput({ writeOut: () => {}, writeErr: () => {} })
.action(async function (this: Command) {
@@ -889,9 +890,18 @@ function buildProgram(): Command {
serverUrl: localOpts.serverUrl as string | undefined,
wsUrl: localOpts.wsUrl as string | undefined,
baseDir: localOpts.baseDir as string | undefined,
+ foreground: localOpts.foreground === true,
});
});
+ daemon
+ .command("run", { hidden: true })
+ .exitOverride()
+ .configureOutput({ writeOut: () => {}, writeErr: () => {} })
+ .action(async () => {
+ await daemonRunFromIpc();
+ });
+
daemon
.command("stop")
.argument("<id>", "daemon id from `alook daemon list` (the ID column)")
diff --git a/src/daemon/src/cli/packageDaemon.test.ts b/src/daemon/src/cli/packageDaemon.test.ts
new file mode 100644
index 000000000..c17097b46
--- /dev/null
+++ b/src/daemon/src/cli/packageDaemon.test.ts
@@ -0,0 +1,22 @@
+import { describe, expect, it } from "vitest";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { packageDaemonArgs } from "../../scripts/daemon";
+
+describe("package-local daemon entry", () => {
+ it("delegates every argument to the canonical daemon parser", () => {
+ expect(packageDaemonArgs(["start", "--machine-key", "cmk_x"])).toEqual([
+ "daemon", "start", "--machine-key", "cmk_x",
+ ]);
+ expect(packageDaemonArgs(["start", "--foreground", "--machine-key", "cmk_x"])).toEqual([
+ "daemon", "start", "--foreground", "--machine-key", "cmk_x",
+ ]);
+ expect(packageDaemonArgs(["unknown"])).toEqual(["daemon", "unknown"]);
+ });
+
+ it("contains no second Commander or direct daemonStart call", () => {
+ const source = readFileSync(fileURLToPath(new URL("../../scripts/daemon.ts", import.meta.url)), "utf8");
+ expect(source).not.toContain('from "commander"');
+ expect(source).not.toContain("daemonStart(");
+ });
+});
diff --git a/src/daemon/src/constants.test.ts b/src/daemon/src/constants.test.ts
index b4aab8ccc..ab13895e4 100644
--- a/src/daemon/src/constants.test.ts
+++ b/src/daemon/src/constants.test.ts
@@ -67,9 +67,6 @@ describe("magic-number extractions", () => {
expect(readSrc("inbox/projection.ts")).toMatch(/MESSAGE_ID_SHORT_LEN\s*=\s*8\b/);
});
- it("MACHINE_KEY_HASH_PREFIX_LEN is set to 12 in cli/daemonStart.ts", () => {
- expect(readSrc("cli/daemonStart.ts")).toMatch(/MACHINE_KEY_HASH_PREFIX_LEN\s*=\s*12\b/);
- });
});
describe("deleted symbols stay deleted", () => {
@@ -77,6 +74,10 @@ describe("deleted symbols stay deleted", () => {
expect(readSrc("cli/daemonStart.ts")).not.toMatch(/\bMACHINE_KEY_DISPLAY_PREFIX_LEN\b/);
});
+ it("machine-key hashing is gone from daemonStart (fresh credentials resolve server identity)", () => {
+ expect(readSrc("cli/daemonStart.ts")).not.toMatch(/MACHINE_KEY_HASH_PREFIX_LEN|fallbackIdForStableKey|function keyHash/);
+ });
+
it("readCommandVersion is no longer exported by drivers/probe.ts", () => {
expect(readSrc("drivers/probe.ts")).not.toMatch(/\breadCommandVersion\b/);
});
diff --git a/src/daemon/src/logger.test.ts b/src/daemon/src/logger.test.ts
index 4242dc74f..86c11b8f3 100644
--- a/src/daemon/src/logger.test.ts
+++ b/src/daemon/src/logger.test.ts
@@ -10,6 +10,25 @@ function capture() {
const FIXED = () => "2026-06-25T12:00:00.000Z";
describe("createLogger", () => {
+ it("emits a nested structured record whose envelope cannot be spoofed", () => {
+ const records: unknown[] = [];
+ const log = createLogger({
+ header: "root",
+ now: FIXED,
+ out: () => {},
+ record: (record) => records.push(record),
+ }).child("child");
+ log.info("line\nmessage", { header: "fake", level: "error", agentId: "a1" });
+ expect(records).toEqual([{
+ time: "2026-06-25T12:00:00.000Z",
+ header: "root:child",
+ level: "info",
+ message: "line\nmessage",
+ fields: { header: "fake", level: "error", agentId: "a1" },
+ }]);
+ expect(JSON.stringify(records[0]).split("\n")).toHaveLength(1);
+ });
+
it("emits `<iso> @alook/daemon <LEVEL> <message>` by default", () => {
const c = capture();
const log = createLogger({ now: FIXED, ...c.sink });
diff --git a/src/daemon/src/logger.ts b/src/daemon/src/logger.ts
index ed0fbbafc..273bacaae 100644
--- a/src/daemon/src/logger.ts
+++ b/src/daemon/src/logger.ts
@@ -44,6 +44,16 @@ export interface LoggerOptions {
/** Injectable sinks (tests). Default stdout/stderr. */
out?: (line: string) => void;
err?: (line: string) => void;
+ /** Structured sink shared by the root logger and every child logger. */
+ record?: (record: LogRecord) => void;
+}
+
+export interface LogRecord {
+ time: string;
+ header: string;
+ level: LogLevel;
+ message: string;
+ fields: Record<string, unknown>;
}
const DEFAULT_HEADER = "@alook/daemon";
@@ -72,16 +82,42 @@ function formatData(data: unknown[]): string {
return " " + parts.join(" ");
}
+function recordFields(data: unknown[]): Record<string, unknown> {
+ const fields: Record<string, unknown> = {};
+ let positional = 0;
+ for (const value of data) {
+ if (value instanceof Error) {
+ fields.error = value.message;
+ continue;
+ }
+ if (value !== null && typeof value === "object" && !Array.isArray(value)) {
+ for (const [key, entry] of Object.entries(value as Record<string, unknown>)) {
+ fields[key] = entry;
+ }
+ continue;
+ }
+ fields[`arg${positional++}`] = value;
+ }
+ return fields;
+}
+
export function createLogger(options: LoggerOptions = {}): Logger {
const header = options.header ?? DEFAULT_HEADER;
const minRank = LEVEL_RANK[options.level ?? envLevel() ?? "info"];
const now = options.now ?? (() => new Date().toISOString());
const out = options.out ?? ((line) => process.stdout.write(line + "\n"));
const err = options.err ?? ((line) => process.stderr.write(line + "\n"));
+ const record = options.record;
const emit = (level: LogLevel, message: string, data: unknown[]): void => {
if (LEVEL_RANK[level] < minRank) return;
- const line = `${now()} ${header} ${level.toUpperCase().padEnd(5)} ${message}${formatData(data)}`;
+ const time = now();
+ const line = `${time} ${header} ${level.toUpperCase().padEnd(5)} ${message}${formatData(data)}`;
+ try {
+ record?.({ time, header, level, message, fields: recordFields(data) });
+ } catch {
+ // Logging must never terminate the daemon.
+ }
(level === "warn" || level === "error" ? err : out)(line);
};
diff --git a/src/daemon/src/util/rotatingFileSink.test.ts b/src/daemon/src/util/rotatingFileSink.test.ts
index fe866849b..d0db30682 100644
--- a/src/daemon/src/util/rotatingFileSink.test.ts
+++ b/src/daemon/src/util/rotatingFileSink.test.ts
@@ -1,5 +1,5 @@
import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
-import { chmodSync, mkdtempSync, mkdirSync, rmSync, existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
+import { chmodSync, mkdtempSync, mkdirSync, readSync, rmSync, existsSync, statSync, readFileSync, writeFileSync } from "node:fs";
import { tmpdir } from "node:os";
import { join } from "node:path";
import { createRotatingFileSink } from "./rotatingFileSink";
@@ -101,6 +101,24 @@ describe("createRotatingFileSink (batch E1 — bounded default trace backing)",
expect(readFileSync(path, "utf8")).toBe("old\nnew\n");
});
+ it("secures pre-existing broad active and rotated generations before appending", () => {
+ const path = join(dir, "daemon.log");
+ const rotatedPath = `${path}.1`;
+ writeFileSync(path, "active-old\n");
+ writeFileSync(rotatedPath, "rotated-old\n");
+ chmodSync(path, 0o644);
+ chmodSync(rotatedPath, 0o644);
+ vi.mocked(chmodSync).mockClear();
+ const sink = createRotatingFileSink(path, 100, { mode: 0o600, hardMaxBytes: true });
+
+ sink.write("new");
+
+ expectSecureMode(path, 0o600);
+ expectSecureMode(rotatedPath, 0o600);
+ expect(readFileSync(path, "utf8")).toBe("active-old\nnew\n");
+ expect(readFileSync(rotatedPath, "utf8")).toBe("rotated-old\n");
+ });
+
it("drops a secure-mode write when chmod fails", () => {
const path = join(dir, "runtime-raw-events-a1.jsonl");
writeFileSync(path, "old\n");
@@ -119,6 +137,49 @@ describe("createRotatingFileSink (batch E1 — bounded default trace backing)",
expect(failures.map(({ operation }) => operation)).toEqual(["chmod"]);
});
+ it("fails closed when a pre-existing rotated generation cannot be secured", () => {
+ const path = join(dir, "daemon.log");
+ const rotatedPath = `${path}.1`;
+ writeFileSync(path, "active\n");
+ writeFileSync(rotatedPath, "rotated\n");
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ vi.mocked(chmodSync).mockImplementationOnce(() => {
+ throw new Error("rotated chmod failed");
+ });
+ const sink = createRotatingFileSink(path, 100, {
+ mode: 0o600,
+ hardMaxBytes: true,
+ onError: (info) => failures.push(info),
+ });
+
+ sink.write("secret");
+
+ expect(readFileSync(path, "utf8")).toBe("active\n");
+ expect(readFileSync(rotatedPath, "utf8")).toBe("rotated\n");
+ expect(failures.map(({ operation }) => operation)).toEqual(["chmod"]);
+ });
+
+ it("omits a snapshot generation that cannot be secured", () => {
+ const path = join(dir, "daemon.log");
+ const rotatedPath = `${path}.1`;
+ writeFileSync(path, "active\n");
+ writeFileSync(rotatedPath, "rotated\n");
+ const failures: Array<{ operation: string; error: unknown }> = [];
+ vi.mocked(chmodSync).mockImplementationOnce(() => {
+ throw new Error("rotated chmod failed");
+ });
+ const sink = createRotatingFileSink(path, 100, {
+ mode: 0o600,
+ onError: (info) => failures.push(info),
+ });
+
+ const snapshot = sink.openSnapshot();
+
+ expect(snapshot.files.map((file) => file.path)).toEqual([path]);
+ expect(failures.map(({ operation }) => operation)).toEqual(["chmod"]);
+ snapshot.close();
+ });
+
it("reports a write failure without throwing", () => {
const failures: Array<{ operation: string; error: unknown }> = [];
const sink = createRotatingFileSink(join(dir, "nope", "trace.jsonl"), 1000, {
@@ -145,7 +206,7 @@ describe("createRotatingFileSink (batch E1 — bounded default trace backing)",
expect(readFileSync(path, "utf8")).toContain("latest\n");
});
- it("drops a hard-capped write when its required rotation fails", () => {
+ it("drops a hard-capped write when the rotated path is not a regular file", () => {
const failures: Array<{ operation: string; error: unknown }> = [];
const path = join(dir, "runtime-raw-events-a1.jsonl");
const sink = createRotatingFileSink(path, 20, {
@@ -156,8 +217,59 @@ describe("createRotatingFileSink (batch E1 — bounded default trace backing)",
mkdirSync(`${path}.1`);
expect(() => sink.write("secret")).not.toThrow();
- expect(failures.map(({ operation }) => operation)).toEqual(["rotate"]);
+ expect(failures.map(({ operation }) => operation)).toEqual(["unsafe_generation"]);
expect(readFileSync(path, "utf8")).toBe(`${"a".repeat(19)}\n`);
expect(statSync(path).size).toBeLessThanOrEqual(20);
});
+
+ it("drops a single record larger than the hard cap", () => {
+ const failures: Array<{ operation: string }> = [];
+ const path = join(dir, "daemon.log");
+ const sink = createRotatingFileSink(path, 20, {
+ hardMaxBytes: true,
+ onError: (info) => failures.push(info),
+ });
+ sink.write("x".repeat(20));
+ expect(existsSync(path)).toBe(false);
+ expect(failures).toEqual([expect.objectContaining({ operation: "oversize" })]);
+ });
+
+ it("removes pre-existing generations above the hard cap during secure preflight", () => {
+ const path = join(dir, "daemon.log");
+ writeFileSync(path, "active is too large");
+ writeFileSync(`${path}.1`, "rotated is too large");
+ const failures: Array<{ operation: string }> = [];
+ const sink = createRotatingFileSink(path, 8, {
+ mode: 0o600,
+ hardMaxBytes: true,
+ onError: (info) => failures.push(info),
+ });
+
+ expect(sink.secure()).toBe(true);
+
+ expect(existsSync(path)).toBe(false);
+ expect(existsSync(`${path}.1`)).toBe(false);
+ expect(failures.map(({ operation }) => operation)).toEqual([
+ "oversize_generation",
+ "oversize_generation",
+ ]);
+ });
+
+ it("opens a stable rotated + active snapshot with pinned sizes", () => {
+ const path = join(dir, "daemon.log");
+ const sink = createRotatingFileSink(path, 8, { hardMaxBytes: true, mode: 0o600 });
+ sink.write("old");
+ sink.write("newer");
+ const snapshot = sink.openSnapshot();
+ sink.write("tail");
+ expect(snapshot.files.map((file) => file.path)).toEqual([`${path}.1`, path]);
+ const contents = snapshot.files.map((file) => {
+ const buffer = Buffer.alloc(file.size);
+ readSync(file.fd, buffer, 0, file.size, 0);
+ return buffer.toString("utf8");
+ });
+ expect(contents).toEqual(["old\n", "newer\n"]);
+ snapshot.close();
+ expect(() => snapshot.close()).not.toThrow();
+ });
});
diff --git a/src/daemon/src/util/rotatingFileSink.ts b/src/daemon/src/util/rotatingFileSink.ts
index a1cd8fd99..55e2f996b 100644
--- a/src/daemon/src/util/rotatingFileSink.ts
+++ b/src/daemon/src/util/rotatingFileSink.ts
@@ -24,11 +24,32 @@
* onFsmTransition callback, after the reduce), and keeping it sync avoids
* interleaving/ordering hazards a per-line async write would add.
*/
-import { appendFileSync, chmodSync, statSync, renameSync, existsSync } from "node:fs";
+import {
+ appendFileSync,
+ chmodSync,
+ closeSync,
+ constants,
+ existsSync,
+ fstatSync,
+ lstatSync,
+ openSync,
+ renameSync,
+ statSync,
+ unlinkSync,
+} from "node:fs";
+
+export interface RotatingFileSnapshot {
+ files: Array<{ path: string; fd: number; size: number }>;
+ close(): void;
+}
export interface RotatingFileSink {
+ /** Tightens every existing generation before a caller starts using the sink. */
+ secure(): boolean;
/** Append one already-serialized line (a trailing newline is added). */
write(line: string): void;
+ /** Opens rotated then active synchronously and pins each generation's size. */
+ openSnapshot(): RotatingFileSnapshot;
}
export interface RotatingFileSinkOptions {
@@ -37,7 +58,7 @@ export interface RotatingFileSinkOptions {
/** Rotate before a write that would make the active generation exceed maxBytes. */
hardMaxBytes?: boolean;
/** Best-effort observability for callers that need to surface sink failure. */
- onError?: (info: { operation: "stat" | "rotate" | "append" | "chmod"; error: unknown }) => void;
+ onError?: (info: { operation: "stat" | "rotate" | "append" | "chmod" | "oversize" | "oversize_generation" | "unsafe_generation" | "snapshot"; error: unknown }) => void;
}
/**
@@ -53,7 +74,7 @@ export function createRotatingFileSink(
maxBytes: number,
opts: RotatingFileSinkOptions = {},
): RotatingFileSink {
- const report = (operation: "stat" | "rotate" | "append" | "chmod", error: unknown): void => {
+ const report = (operation: "stat" | "rotate" | "append" | "chmod" | "oversize" | "oversize_generation" | "unsafe_generation" | "snapshot", error: unknown): void => {
try {
opts.onError?.({ operation, error });
} catch {
@@ -61,10 +82,25 @@ export function createRotatingFileSink(
}
};
- const secureActive = (): boolean => {
- if (opts.mode === undefined || !existsSync(path)) return true;
+ const secureGeneration = (filePath: string): boolean => {
+ if (!existsSync(filePath)) return true;
try {
- chmodSync(path, opts.mode);
+ const stat = lstatSync(filePath);
+ if (!stat.isFile()) {
+ if (opts.mode === undefined && !opts.hardMaxBytes) return true;
+ report("unsafe_generation", new Error("log generation is not a regular file"));
+ return false;
+ }
+ if (opts.mode !== undefined) chmodSync(filePath, opts.mode);
+ if (opts.hardMaxBytes && maxBytes > 0 && stat.size > maxBytes) {
+ try {
+ unlinkSync(filePath);
+ } catch (error) {
+ report("oversize_generation", error);
+ return false;
+ }
+ report("oversize_generation", new Error(`removed generation larger than ${maxBytes} bytes`));
+ }
return true;
} catch (error) {
report("chmod", error);
@@ -76,6 +112,7 @@ export function createRotatingFileSink(
try {
// Overwrite any prior `.1` — we only keep one generation back.
renameSync(path, `${path}.1`);
+ if (opts.mode !== undefined) chmodSync(`${path}.1`, opts.mode);
return true;
} catch (error) {
report("rotate", error);
@@ -93,16 +130,24 @@ export function createRotatingFileSink(
}
};
- return {
+ const sink: RotatingFileSink = {
+ secure(): boolean {
+ return secureGeneration(`${path}.1`) && secureGeneration(path);
+ },
write(line: string): void {
try {
- if (!secureActive()) return;
+ if (!sink.secure()) return;
const serialized = line + "\n";
+ const serializedBytes = Buffer.byteLength(serialized, "utf8");
+ if (opts.hardMaxBytes && maxBytes > 0 && serializedBytes > maxBytes) {
+ report("oversize", new Error(`record exceeds ${maxBytes} bytes`));
+ return;
+ }
const measuredBytes = currentSize();
if (measuredBytes === null && opts.hardMaxBytes) return;
const currentBytes = measuredBytes ?? 0;
const shouldRotate = maxBytes > 0 && (opts.hardMaxBytes
- ? currentBytes > 0 && currentBytes + Buffer.byteLength(serialized, "utf8") > maxBytes
+ ? currentBytes > 0 && currentBytes + serializedBytes > maxBytes
: currentBytes >= maxBytes);
if (shouldRotate && !rotate() && opts.hardMaxBytes) return;
appendFileSync(path, serialized, opts.mode === undefined ? undefined : { mode: opts.mode });
@@ -111,5 +156,42 @@ export function createRotatingFileSink(
/* never let tracing break the daemon */
}
},
+ openSnapshot(): RotatingFileSnapshot {
+ const files: RotatingFileSnapshot["files"] = [];
+ try {
+ for (const candidate of [`${path}.1`, path]) {
+ if (!existsSync(candidate)) continue;
+ if (!secureGeneration(candidate)) continue;
+ const noFollow = "O_NOFOLLOW" in constants ? constants.O_NOFOLLOW : 0;
+ const fd = openSync(candidate, constants.O_RDONLY | noFollow);
+ try {
+ const stat = fstatSync(fd);
+ if (!stat.isFile()) throw new Error("snapshot source is not a regular file");
+ files.push({ path: candidate, fd, size: stat.size });
+ } catch (error) {
+ closeSync(fd);
+ throw error;
+ }
+ }
+ } catch (error) {
+ for (const file of files) {
+ try { closeSync(file.fd); } catch { /* best effort */ }
+ }
+ report("snapshot", error);
+ return { files: [], close: () => {} };
+ }
+ let closed = false;
+ return {
+ files,
+ close(): void {
+ if (closed) return;
+ closed = true;
+ for (const file of files) {
+ try { closeSync(file.fd); } catch { /* best effort */ }
+ }
+ },
+ };
+ },
};
+ return sink;
}
diff --git a/src/web/src/app/api/community/daemon/identity/route.test.ts b/src/web/src/app/api/community/daemon/identity/route.test.ts
new file mode 100644
index 000000000..790bb5a4e
--- /dev/null
+++ b/src/web/src/app/api/community/daemon/identity/route.test.ts
@@ -0,0 +1,48 @@
+import { beforeEach, describe, expect, it, vi } from "vitest"
+import { NextRequest } from "next/server"
+
+vi.mock("@opennextjs/cloudflare", () => ({
+ getCloudflareContext: vi.fn(async () => ({ env: { DB: {} } })),
+}))
+
+vi.mock("@/lib/db", () => ({ getDb: vi.fn(() => ({})) }))
+
+const mockFindActiveCredential = vi.fn()
+vi.mock("@alook/shared", () => ({
+ withD1Retry: (fn: () => Promise<unknown>) => fn(),
+ queries: {
+ communityMachine: {
+ findActiveCredentialByBearer: (...args: unknown[]) => mockFindActiveCredential(...args),
+ },
+ },
+}))
+
+import { GET } from "./route"
+
+function request(authorization?: string): NextRequest {
+ return new NextRequest("http://localhost/api/community/daemon/identity", {
+ headers: authorization ? { authorization } : undefined,
+ })
+}
+
+describe("GET /api/community/daemon/identity", () => {
+ beforeEach(() => vi.clearAllMocks())
+
+ it("returns only the authenticated machine id", async () => {
+ mockFindActiveCredential.mockResolvedValue({
+ credentialId: "cred_1",
+ userId: "user_1",
+ machineId: "machine_1",
+ })
+ const response = await GET(request("Bearer cmk_valid"))
+ expect(response.status).toBe(200)
+ expect(await response.json()).toEqual({ machineId: "machine_1" })
+ })
+
+ it("rejects missing, pairing, and unknown credentials", async () => {
+ expect((await GET(request())).status).toBe(401)
+ expect((await GET(request("Bearer cmt_pairing"))).status).toBe(401)
+ mockFindActiveCredential.mockResolvedValue(null)
+ expect((await GET(request("Bearer cmk_foreign"))).status).toBe(401)
+ })
+})
diff --git a/src/web/src/app/api/community/daemon/identity/route.ts b/src/web/src/app/api/community/daemon/identity/route.ts
new file mode 100644
index 000000000..5a474b417
--- /dev/null
+++ b/src/web/src/app/api/community/daemon/identity/route.ts
@@ -0,0 +1,6 @@
+import { NextResponse } from "next/server"
+import { withCommunityDaemonAuth } from "@/lib/middleware/community-daemon-auth"
+
+export const GET = withCommunityDaemonAuth(async (_req, ctx) =>
+ NextResponse.json({ machineId: ctx.machineId })
+)