Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
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.tsindex 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.tsindex 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.tsindex 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.tsindex 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<RunningDamanagerRef = 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<RunningDafor (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.tsindex 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.tsnew file mode 100644index 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.tsnew file mode 100644index 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 */+ }+}