Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(daemon): daemon status snapshot for out-of-band FSM inspection (batch E2)

Gus9ed6e200bbb6
diff --git a/src/daemon/src/cli/daemonStart.test.ts b/src/daemon/src/cli/daemonStart.test.ts
index 6eeada4f4..48b374442 100644
--- a/src/daemon/src/cli/daemonStart.test.ts
+++ b/src/daemon/src/cli/daemonStart.test.ts
@@ -2,7 +2,7 @@ import { describe, it, expect, beforeEach, afterEach } from "vitest";
import * as fs from "fs";
import * as path from "path";
import * as os from "os";
-import { credentialFilePathByMachineId } from "./daemonStart";
+import { credentialFilePathByMachineId, daemonStatus } from "./daemonStart";
describe("daemonStart — credentialFilePath by machineId", () => {
let baseDir: string;
@@ -35,3 +35,57 @@ describe("daemonStart — credentialFilePath by machineId", () => {
expect(parsed).toEqual({ credential: "cmk_second", machineId });
});
});
+
+describe("daemonStatus — reads snapshot + always flags freshness (batch E2)", () => {
+ let baseDir: string;
+ beforeEach(() => {
+ baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "alook-status-test-"));
+ });
+ afterEach(() => {
+ fs.rmSync(baseDir, { recursive: true, force: true });
+ });
+
+ const writeSnap = (writtenAt: number) => {
+ fs.writeFileSync(
+ path.join(baseDir, "status.json"),
+ JSON.stringify({
+ writtenAt,
+ agents: [
+ { agentId: "a1", status: "running", derivedActivity: "idle", turnActive: false, inbox: 0, sinceProgressMs: 10, stoppingSince: null },
+ ],
+ }),
+ );
+ };
+
+ it("missing file → freshness 'missing', found false, no throw", () => {
+ const r = daemonStatus({ baseDir, now: () => 1000 });
+ expect(r.found).toBe(false);
+ expect(r.freshness).toBe("missing");
+ expect(r.agents).toEqual([]);
+ });
+
+ it("recent snapshot → 'fresh' with the agent projection + age", () => {
+ writeSnap(1000);
+ const r = daemonStatus({ baseDir, now: () => 3000 }); // 2s old
+ expect(r.found).toBe(true);
+ expect(r.freshness).toBe("fresh");
+ expect(r.ageMs).toBe(2000);
+ expect(r.agents[0]?.agentId).toBe("a1");
+ expect(r.agents[0]?.derivedActivity).toBe("idle");
+ });
+
+ it("old snapshot → 'stale' (never mistaken for live truth)", () => {
+ writeSnap(1000);
+ const r = daemonStatus({ baseDir, now: () => 1000 + 60_000 }); // 60s old
+ expect(r.freshness).toBe("stale");
+ expect(r.ageMs).toBe(60_000);
+ expect(r.found).toBe(true); // still returns the last-known frame
+ });
+
+ it("corrupt/half-written file → treated as missing, no throw", () => {
+ fs.writeFileSync(path.join(baseDir, "status.json"), "{ not valid json");
+ const r = daemonStatus({ baseDir, now: () => 1000 });
+ expect(r.found).toBe(false);
+ expect(r.freshness).toBe("missing");
+ });
+});
diff --git a/src/daemon/src/cli/daemonStart.ts b/src/daemon/src/cli/daemonStart.ts
index 4b25f7ffb..01314ac53 100644
--- a/src/daemon/src/cli/daemonStart.ts
+++ b/src/daemon/src/cli/daemonStart.ts
@@ -12,6 +12,7 @@ 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 } from "../drivers/index.js";
import { resolveAlookCliPathWithFallback, detectRuntimes, type RuntimeInfo } from "../discovery.js";
import { createLogger } from "../logger.js";
@@ -145,6 +146,61 @@ export function daemonList(opts: DaemonListOpts): DaemonInfo[] {
return results;
}
+/* ------------------------------------------------------------------ */
+/* daemon status */
+/* ------------------------------------------------------------------ */
+
+export interface DaemonStatusOpts {
+ baseDir?: string;
+ /** Injectable clock for tests; defaults to Date.now. */
+ now?: () => number;
+}
+
+export interface DaemonStatusResult {
+ /** true if status.json was found and parsed. */
+ found: boolean;
+ /** ms since the snapshot was written (null if not found). */
+ ageMs: number | null;
+ /**
+ * Freshness verdict: "fresh" (< a few write intervals), "stale" (older —
+ * daemon may be paused/down; the frame is a last-known state), or "missing".
+ * The CLI ALWAYS surfaces this so a stale snapshot is never mistaken for
+ * live truth — an unflagged stale read would be exactly the "state unsynced"
+ * blind spot this whole feature exists to kill.
+ */
+ freshness: "fresh" | "stale" | "missing";
+ /** The snapshot's own writtenAt (ms epoch), or null. */
+ writtenAt: number | null;
+ agents: DaemonStatusSnapshot["agents"];
+}
+
+/** Older than this ⇒ "stale" (a few status-write intervals of slack). */
+const STATUS_STALE_MS = 20_000;
+
+export function daemonStatus(opts: DaemonStatusOpts): DaemonStatusResult {
+ const baseDir = opts.baseDir || process.env.ALOOK_DATA_DIR || DEFAULT_BASE_DIR;
+ const now = opts.now ?? (() => Date.now());
+ const statusPath = path.join(baseDir, "status.json");
+ if (!fs.existsSync(statusPath)) {
+ return { found: false, ageMs: null, freshness: "missing", writtenAt: null, agents: [] };
+ }
+ try {
+ const snap = JSON.parse(fs.readFileSync(statusPath, "utf8")) as DaemonStatusSnapshot;
+ const ageMs = now() - snap.writtenAt;
+ return {
+ found: true,
+ ageMs,
+ freshness: ageMs <= STATUS_STALE_MS ? "fresh" : "stale",
+ writtenAt: snap.writtenAt,
+ agents: Array.isArray(snap.agents) ? snap.agents : [],
+ };
+ } catch {
+ // File present but unreadable/half-written/corrupt → treat as missing
+ // rather than crash (a `daemon status` must never throw on a bad file).
+ return { found: false, ageMs: null, freshness: "missing", writtenAt: null, agents: [] };
+ }
+}
+
/* ------------------------------------------------------------------ */
/* daemon stop */
/* ------------------------------------------------------------------ */
@@ -413,6 +469,8 @@ export async function daemonStart(opts: DaemonStartOpts): Promise<void> {
// is what makes "the last wedge's FSM history" always available without
// pre-setting ALOOK_FSM_TRACE. The env var, if set, overrides this.
fsmTraceDir: path.join(baseDir, "logs"),
+ // Periodic `daemon status` snapshot (batch E2) → <baseDir>/status.json.
+ statusFilePath: path.join(baseDir, "status.json"),
hostname: os.hostname(),
platform: process.platform,
arch: process.arch,
diff --git a/src/daemon/src/cli/index.ts b/src/daemon/src/cli/index.ts
index 38919e783..6360177d1 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 } from "./daemonStart.js";
+import { daemonStart, daemonStop, daemonList, daemonStatus } 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";
@@ -798,6 +798,21 @@ function buildProgram(): Command {
printEnvelope({ success: { daemons } });
});
+ daemon
+ .command("status")
+ .description("dump each agent's current FSM state from the daemon's status snapshot")
+ .option("--base-dir <path>", "data directory (or ALOOK_DATA_DIR env)")
+ .exitOverride()
+ .configureOutput({ writeOut: () => {}, writeErr: () => {} })
+ .action(function (this: Command) {
+ const localOpts = this.opts();
+ const status = daemonStatus({ baseDir: localOpts.baseDir as string | undefined });
+ // ALWAYS surface freshness — a stale snapshot must never read as live
+ // truth (the "state unsynced" blind spot this feature kills). The reader
+ // gets the raw fields + an explicit freshness verdict + snapshot age.
+ printEnvelope({ success: { status } });
+ });
+
return program;
}
diff --git a/src/daemon/src/daemon/createDaemon.ts b/src/daemon/src/daemon/createDaemon.ts
index ce6622b7d..ed2968f37 100644
--- a/src/daemon/src/daemon/createDaemon.ts
+++ b/src/daemon/src/daemon/createDaemon.ts
@@ -28,6 +28,7 @@
import { homedir } from "os";
import { appendFileSync, mkdirSync } from "node:fs";
import { createRotatingFileSink } from "../util/rotatingFileSink.js";
+import { writeStatusFile } from "../util/statusFile.js";
import { WsControlChannel } from "../server/wsControlChannel.js";
import { CredentialBroker, startCredentialProxy } from "../credentials/index.js";
import { AgentProcessManager, AgentRouter, createTypingScopeTracker } from "../manager/index.js";
@@ -52,6 +53,8 @@ const WARMUP_CEILING_MS = 30_000;
* enough to hold the last wedge. The `ALOOK_FSM_TRACE` override is unbounded.
*/
const FSM_TRACE_MAX_BYTES = 8 * 1024 * 1024;
+/** How often the daemon rewrites the `daemon status` snapshot file (batch E2). */
+const STATUS_WRITE_INTERVAL_MS = 5_000;
/**
* Derive the audit-log `cli_invocation` subcommand from a proxy request
@@ -145,6 +148,13 @@ export interface CreateDaemonOptions {
* append (deep-investigation mode). See plans/daemon-fsm-desync.md batch E.
*/
fsmTraceDir?: string;
+ /**
+ * Absolute path for the periodic `daemon status` snapshot file (batch E2).
+ * The running daemon writes a slim per-agent FSM projection here (atomic
+ * tmp→rename) on a timer; the `daemon status` CLI reads it. Omit for test
+ * stubs → no snapshot writing. See plans/daemon-fsm-desync.md batch E2.
+ */
+ statusFilePath?: string;
/**
* Absolute path to the host's agent CLI entrypoint. Real deployments point this
* at the shim/binary the agent subprocess invokes (via a symlink in PATH).
@@ -652,6 +662,22 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
managerRef = manager;
manager.start();
+ // Periodic `daemon status` snapshot (batch E2): the daemon has no IPC, so it
+ // writes a slim per-agent FSM projection to a file that the out-of-band
+ // `daemon status` CLI reads. Best-effort + atomic (inside writeStatusFile).
+ // Interval a bit slower than the tick — this is for human/agent diagnosis,
+ // not a hot path; staleness is bounded by this interval and the reader always
+ // flags the snapshot's age via `writtenAt`.
+ let statusTimer: ReturnType<typeof setInterval> | null = null;
+ if (opts.statusFilePath) {
+ const statusPath = opts.statusFilePath;
+ const writeStatus = () =>
+ writeStatusFile(statusPath, { writtenAt: Date.now(), agents: manager.statusProjection(Date.now()) });
+ writeStatus(); // one immediately so `daemon status` works right after boot
+ statusTimer = setInterval(writeStatus, STATUS_WRITE_INTERVAL_MS);
+ statusTimer.unref?.();
+ }
+
router = new AgentRouter({
manager,
channel,
@@ -730,6 +756,7 @@ export async function createDaemon(opts: CreateDaemonOptions): Promise<RunningDa
for (const agentId of [...typingHeartbeats.keys()]) {
emitTypingStopsAndClear(agentId);
}
+ if (statusTimer) clearInterval(statusTimer);
channel.close();
await proxy.close();
await manager.stopAll();
diff --git a/src/daemon/src/manager/managerRuntime.ts b/src/daemon/src/manager/managerRuntime.ts
index 7a24a544f..624e711a9 100644
--- a/src/daemon/src/manager/managerRuntime.ts
+++ b/src/daemon/src/manager/managerRuntime.ts
@@ -20,6 +20,7 @@ import {
type AgentRuntimeCaps,
type AgentMsg,
type AgentState,
+ type AgentStatus,
isActivelyWorking,
} from "./managerPolicy.js";
import type { Driver, LaunchContext, SdkDriverDeps } from "../types.js";
@@ -951,6 +952,36 @@ export class AgentProcessManager {
return agent ? this.deriveActivity(agent) : null;
}
+ /**
+ * Slim per-agent FSM projection for the `daemon status` snapshot file (batch
+ * E2). Metadata only — NO message content, NO PII. Exposes BOTH the raw FSM
+ * `status` AND the `derivedActivity` (the running/idle display) so a reader
+ * can tell apart the three idle-looking states the frontend's coarse marker
+ * conflates: between-turns idle (running + !turnActive), a real turn in
+ * flight, and a wedge (climbing `sinceProgressMs` / non-null `stoppingSince`).
+ * `nowMs` is passed in so the caller stamps a single consistent `writtenAt`.
+ * See plans/daemon-fsm-desync.md batch E2.
+ */
+ statusProjection(nowMs: number): Array<{
+ agentId: string;
+ status: AgentStatus;
+ derivedActivity: AgentActivityState;
+ turnActive: boolean;
+ inbox: number;
+ sinceProgressMs: number;
+ stoppingSince: number | null;
+ }> {
+ return Object.values(this.state.agents).map((a) => ({
+ agentId: a.agentId,
+ status: a.status,
+ derivedActivity: this.deriveActivity(a),
+ turnActive: a.turnActive,
+ inbox: a.inbox.length,
+ sinceProgressMs: nowMs - a.lastProgressAt,
+ stoppingSince: a.stoppingSince,
+ }));
+ }
+
/* --------------------------------------------------------------- */
/* Core dispatch: reduce → apply effects */
/* --------------------------------------------------------------- */
diff --git a/src/daemon/src/util/statusFile.test.ts b/src/daemon/src/util/statusFile.test.ts
new file mode 100644
index 000000000..2882228b2
--- /dev/null
+++ b/src/daemon/src/util/statusFile.test.ts
@@ -0,0 +1,38 @@
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { mkdtempSync, rmSync, existsSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { writeStatusFile, type DaemonStatusSnapshot } from "./statusFile";
+
+describe("writeStatusFile (batch E2 — atomic daemon status snapshot)", () => {
+ let dir: string;
+ beforeEach(() => {
+ dir = mkdtempSync(join(tmpdir(), "status-"));
+ });
+ afterEach(() => {
+ rmSync(dir, { recursive: true, force: true });
+ });
+
+ const snap: DaemonStatusSnapshot = {
+ writtenAt: 1000,
+ agents: [
+ { agentId: "a1", status: "running", derivedActivity: "idle", turnActive: false, inbox: 0, sinceProgressMs: 42, stoppingSince: null },
+ ],
+ };
+
+ it("writes valid JSON that round-trips", () => {
+ const path = join(dir, "status.json");
+ writeStatusFile(path, snap);
+ expect(JSON.parse(readFileSync(path, "utf8"))).toEqual(snap);
+ });
+
+ it("leaves no .tmp behind (rename completed)", () => {
+ const path = join(dir, "status.json");
+ writeStatusFile(path, snap);
+ expect(existsSync(`${path}.tmp`)).toBe(false);
+ });
+
+ it("never throws when the target dir does not exist (best-effort)", () => {
+ expect(() => writeStatusFile(join(dir, "nope", "status.json"), snap)).not.toThrow();
+ });
+});
diff --git a/src/daemon/src/util/statusFile.ts b/src/daemon/src/util/statusFile.ts
new file mode 100644
index 000000000..19d2f083a
--- /dev/null
+++ b/src/daemon/src/util/statusFile.ts
@@ -0,0 +1,44 @@
+/**
+ * Atomic status-file writer for the `daemon status` snapshot (batch E2).
+ *
+ * The FSM daemon has NO IPC — `daemon stop`/`list`/`status` are separate CLI
+ * processes, and `manager.snapshot()` lives only inside the running daemon. So
+ * to answer "what is each agent's FSM state right now" out-of-band, the running
+ * daemon periodically writes a slim projection to `<baseDir>/status.json` and
+ * the `daemon status` CLI reads that file (Cecilia's ruling (a): snapshot-file,
+ * not a control listener — zero new network/attack surface, crash-safe: if the
+ * daemon dies the last frame is still readable). See plans/daemon-fsm-desync.md.
+ *
+ * ATOMIC: write to `<path>.tmp` then `rename` over `<path>`, so a concurrent
+ * `daemon status` read never sees a half-written file (rename is atomic on the
+ * same filesystem). Best-effort: a status write must NEVER break the daemon, so
+ * failures are swallowed — a missing/stale status file is a tolerable "unknown",
+ * far better than a crash.
+ */
+import { writeFileSync, renameSync } from "node:fs";
+
+/** Shape persisted to status.json. Metadata only — no message content, no PII. */
+export interface DaemonStatusSnapshot {
+ /** ms epoch when this snapshot was written — the reader flags its age. */
+ writtenAt: number;
+ agents: Array<{
+ agentId: string;
+ status: string;
+ derivedActivity: string;
+ turnActive: boolean;
+ inbox: number;
+ sinceProgressMs: number;
+ stoppingSince: number | null;
+ }>;
+}
+
+/** Write the snapshot atomically. Best-effort — never throws. */
+export function writeStatusFile(path: string, snapshot: DaemonStatusSnapshot): void {
+ try {
+ const tmp = `${path}.tmp`;
+ writeFileSync(tmp, JSON.stringify(snapshot));
+ renameSync(tmp, path);
+ } catch {
+ /* never let status writing break the daemon */
+ }
+}