Files
stack/packages/control-board/tests/scan.test.mjs
T
jason.woltjeandClaude Fable 5.1 b9f59a5903 Add control board status scanner and MVP plan (#1503)
Step 1 of the control board MVP (decision MOSAIC-STACK-D-001): a plan page,
Gitea #1503, and packages/control-board, which reads each agent's newest pi
session log plus tmux liveness and writes one status file per agent under
<dataRoot>/board/. 23/23 tests; independent review approved after three
fixes (length stopReason as error, unknown liveness state, secrets-boundary
test). CURRENT.md now points at step 2, the page.

Co-Authored-By: Claude Fable 5.1 <[email protected]>
2026-09-12 07:26:03 -05:00

467 lines
20 KiB
JavaScript

import { test, after } from "node:test";
import assert from "node:assert/strict";
import {
mkdtempSync,
mkdirSync,
writeFileSync,
rmSync,
utimesSync,
readFileSync,
readdirSync,
existsSync,
} from "node:fs";
import { tmpdir } from "node:os";
import { join, resolve, basename } from "node:path";
import { spawnSync } from "node:child_process";
import {
loadConfig,
ConfigError,
findNewestSession,
readSession,
deriveState,
scanAgent,
discoverRepoAgents,
discoverFleetAgents,
scan,
} from "../src/scan.mjs";
const pkgRoot = resolve(import.meta.dirname, "..");
const cli = join(pkgRoot, "src", "cli.mjs");
// Track every tmpdir we create so a stray failure never leaves fixtures behind.
const roots = [];
function makeRoot() {
const root = mkdtempSync(join(tmpdir(), "control-board-test-"));
roots.push(root);
return root;
}
after(() => {
for (const root of roots) rmSync(root, { recursive: true, force: true });
});
function writeFile(path, content) {
mkdirSync(resolve(path, ".."), { recursive: true });
writeFileSync(path, content);
}
function sessionLine({ id, timestamp, cwd }) {
return JSON.stringify({ type: "session", id, timestamp, cwd });
}
function messageLine({ timestamp, role, stopReason, texts }) {
const message = { role };
if (stopReason !== undefined) message.stopReason = stopReason;
if (texts) message.content = texts.map((text) => ({ type: "text", text }));
return JSON.stringify({ type: "message", timestamp, message });
}
// Same transform readSession applies, kept here as an independent
// expectation rather than importing an unexported helper.
function collapseExpected(text) {
const one = text.replace(/\s+/g, " ").trim();
return one.length > 240 ? one.slice(0, 239) + "…" : one;
}
function writeSessionFile(dir, name, lines, { trailingNewline = true } = {}) {
const path = join(dir, name);
writeFile(path, lines.join("\n") + (trailingNewline ? "\n" : ""));
return path;
}
// ---------------------------------------------------------------------------
// 1. loadConfig fail-closed
// ---------------------------------------------------------------------------
test("loadConfig: missing file throws ConfigError", () => {
const root = makeRoot();
assert.throws(() => loadConfig(join(root, "nope.json")), ConfigError);
});
test("loadConfig: invalid JSON throws ConfigError", () => {
const root = makeRoot();
const path = join(root, "config.json");
writeFile(path, "{ not json");
assert.throws(() => loadConfig(path), ConfigError);
});
test("loadConfig: missing dataRoot throws ConfigError", () => {
const root = makeRoot();
const path = join(root, "config.json");
writeFile(path, JSON.stringify({}));
assert.throws(() => loadConfig(path), ConfigError);
});
test("loadConfig: relative dataRoot throws ConfigError", () => {
const root = makeRoot();
const path = join(root, "config.json");
writeFile(path, JSON.stringify({ dataRoot: "relative/path" }));
assert.throws(() => loadConfig(path), ConfigError);
});
test("loadConfig: valid config returns dataRoot", () => {
const root = makeRoot();
const path = join(root, "config.json");
const dataRoot = join(root, "data");
writeFile(path, JSON.stringify({ dataRoot }));
assert.deepEqual(loadConfig(path), { dataRoot });
});
// ---------------------------------------------------------------------------
// 2. findNewestSession
// ---------------------------------------------------------------------------
test("findNewestSession: picks the newest by mtime among two files", () => {
const root = makeRoot();
const older = join(root, "older.jsonl");
const newer = join(root, "newer.jsonl");
writeFile(older, "{}\n");
writeFile(newer, "{}\n");
utimesSync(older, new Date("2026-01-01T00:00:00Z"), new Date("2026-01-01T00:00:00Z"));
utimesSync(newer, new Date("2026-01-02T00:00:00Z"), new Date("2026-01-02T00:00:00Z"));
assert.equal(findNewestSession(root), newer);
});
test("findNewestSession: finds files in nested subdirectories", () => {
const root = makeRoot();
const nested = join(root, "a", "b");
mkdirSync(nested, { recursive: true });
const top = join(root, "top.jsonl");
const deep = join(nested, "deep.jsonl");
writeFile(top, "{}\n");
writeFile(deep, "{}\n");
utimesSync(top, new Date("2026-01-01T00:00:00Z"), new Date("2026-01-01T00:00:00Z"));
utimesSync(deep, new Date("2026-01-05T00:00:00Z"), new Date("2026-01-05T00:00:00Z"));
assert.equal(findNewestSession(root), deep);
});
test("findNewestSession: returns null for a missing dir", () => {
const root = makeRoot();
assert.equal(findNewestSession(join(root, "does-not-exist")), null);
});
// ---------------------------------------------------------------------------
// 3. readSession
// ---------------------------------------------------------------------------
test("readSession: extracts fields, collapses/truncates text, counts a truncated final line", () => {
const root = makeRoot();
const longText = " Field report: " + "alpha ".repeat(60) + " omega ";
const expectedText = collapseExpected(["First part.", longText].join("\n"));
assert.ok(expectedText.length === 240 && expectedText.endsWith("…"), "fixture text must exceed the 240-char limit");
const lines = [
sessionLine({ id: "sess-1", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/x" }),
messageLine({ timestamp: "2026-09-01T00:05:00.000Z", role: "user", texts: ["hi"] }),
messageLine({
timestamp: "2026-09-01T00:10:00.000Z",
role: "assistant",
stopReason: "stop",
texts: ["First part.", longText],
}),
// Truncated / partially-written final line: not valid JSON, no trailing newline.
'{"type":"message","timestamp":"2026-09-01T00:15:00.000Z","message":{"role":"assistant","stopReaso',
];
const path = writeSessionFile(root, "session.jsonl", lines, { trailingNewline: false });
const result = readSession(path);
assert.equal(result.file, path);
assert.equal(result.sessionId, "sess-1");
assert.equal(result.cwd, "/x");
assert.equal(result.lastTimestamp, "2026-09-01T00:10:00.000Z");
assert.equal(result.lastMessage.role, "assistant");
assert.equal(result.lastMessage.stopReason, "stop");
assert.equal(result.lastAssistantText, expectedText);
assert.equal(result.lastAssistantText.length, 240);
assert.ok(result.lastAssistantText.endsWith("…"));
assert.equal(result.skippedLines, 1);
});
test("readSession: lastError carries the assistant errorMessage only when the last assistant turn errored", () => {
const root = makeRoot();
const errored = JSON.stringify({
type: "message",
timestamp: "2026-09-01T00:10:00.000Z",
message: { role: "assistant", stopReason: "error", errorMessage: "429: usage limit\nreached", content: [] },
});
const path = writeSessionFile(root, "err.jsonl", [
sessionLine({ id: "sess-e", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/x" }),
messageLine({ timestamp: "2026-09-01T00:05:00.000Z", role: "assistant", stopReason: "stop", texts: ["fine"] }),
errored,
]);
const result = readSession(path);
assert.equal(result.lastError, "429: usage limit reached");
assert.equal(result.lastAssistantText, "fine");
const recovered = writeSessionFile(root, "ok.jsonl", [
sessionLine({ id: "sess-o", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/x" }),
errored,
messageLine({ timestamp: "2026-09-01T00:15:00.000Z", role: "assistant", stopReason: "stop", texts: ["back"] }),
]);
assert.equal(readSession(recovered).lastError, null);
const rec = scanAgent({ agent: "a", project: "p", sessionsDir: root, tmux: { socket: null, session: "a" } }, { isAlive: () => true });
assert.equal(rec.lastError, null);
});
test("findNewestSession/scan: never read sibling auth or secrets next to a sessions dir", () => {
const root = makeRoot();
const agentDir = join(root, "agent-x", ".pi", "agent");
const sessionsDir = join(agentDir, "sessions", "nested");
writeFile(join(agentDir, "auth.json"), '{"token":"SECRET-AUTH-TOKEN"}');
writeFile(join(root, "agent-x", "secrets", "seat.json"), '{"token":"SECRET-SEAT-TOKEN"}');
writeSessionFile(sessionsDir, "s.jsonl", [
sessionLine({ id: "sess-s", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/x" }),
messageLine({ timestamp: "2026-09-01T00:05:00.000Z", role: "assistant", stopReason: "stop", texts: ["ok"] }),
]);
assert.equal(findNewestSession(join(agentDir, "sessions")), join(sessionsDir, "s.jsonl"));
const boardDir = join(root, "board");
scan([{ agent: "agent-x", project: "p", sessionsDir: join(agentDir, "sessions"), tmux: { socket: null, session: "agent-x" } }], { boardDir, isAlive: () => true });
const written = [readFileSync(join(boardDir, "index.json"), "utf8"), readFileSync(join(boardDir, "sessions", "p", "agent-x.json"), "utf8")].join("\n");
assert.ok(!written.includes("SECRET-"), "board output must not contain secret material");
assert.ok(!written.includes("auth.json") && !written.includes("secrets/"), "board output must not reference auth or secrets paths");
});
// ---------------------------------------------------------------------------
// 4. deriveState table
// ---------------------------------------------------------------------------
test("deriveState: full state table", () => {
const cases = [
{ name: "alive=false is offline regardless of session", input: { alive: false, session: { lastMessage: { role: "assistant", stopReason: "stop" } } }, expected: "offline" },
{ name: "no session is idle", input: { alive: true, session: null }, expected: "idle" },
{ name: "no lastMessage is idle", input: { alive: true, session: { lastMessage: null } }, expected: "idle" },
{ name: "assistant+stop is waiting", input: { alive: true, session: { lastMessage: { role: "assistant", stopReason: "stop" } } }, expected: "waiting" },
{ name: "assistant+error is error", input: { alive: true, session: { lastMessage: { role: "assistant", stopReason: "error" } } }, expected: "error" },
{ name: "assistant+aborted is error", input: { alive: true, session: { lastMessage: { role: "assistant", stopReason: "aborted" } } }, expected: "error" },
{ name: "assistant+toolUse is working", input: { alive: true, session: { lastMessage: { role: "assistant", stopReason: "toolUse" } } }, expected: "working" },
{ name: "user last is working", input: { alive: true, session: { lastMessage: { role: "user" } } }, expected: "working" },
{ name: "toolResult last is working", input: { alive: true, session: { lastMessage: { role: "toolResult" } } }, expected: "working" },
{ name: "assistant+length (cut off) is error", input: { alive: true, session: { lastMessage: { role: "assistant", stopReason: "length" } } }, expected: "error" },
{ name: "alive=null (liveness not checkable) is unknown, never assumed alive", input: { alive: null, session: { lastMessage: { role: "assistant", stopReason: "stop" } } }, expected: "unknown" },
];
for (const c of cases) {
assert.equal(deriveState(c.input), c.expected, c.name);
}
});
// ---------------------------------------------------------------------------
// 5. scanAgent
// ---------------------------------------------------------------------------
test("scanAgent: waitingOnYou is true for waiting/error and false otherwise", () => {
const root = makeRoot();
const waitingDir = join(root, "waiting", "sessions");
const workingDir = join(root, "working", "sessions");
const errorDir = join(root, "error", "sessions");
mkdirSync(waitingDir, { recursive: true });
mkdirSync(workingDir, { recursive: true });
mkdirSync(errorDir, { recursive: true });
writeSessionFile(waitingDir, "s.jsonl", [
sessionLine({ id: "s1", timestamp: "2026-09-01T00:00:00Z", cwd: "/w" }),
messageLine({ timestamp: "2026-09-01T00:00:01Z", role: "assistant", stopReason: "stop", texts: ["done"] }),
]);
writeSessionFile(workingDir, "s.jsonl", [
sessionLine({ id: "s2", timestamp: "2026-09-01T00:00:00Z", cwd: "/k" }),
messageLine({ timestamp: "2026-09-01T00:00:01Z", role: "assistant", stopReason: "toolUse", texts: ["thinking"] }),
]);
writeSessionFile(errorDir, "s.jsonl", [
sessionLine({ id: "s3", timestamp: "2026-09-01T00:00:00Z", cwd: "/e" }),
messageLine({ timestamp: "2026-09-01T00:00:01Z", role: "assistant", stopReason: "aborted" }),
]);
const opts = { isAlive: () => true, now: () => new Date("2026-09-01T00:01:00Z") };
const waiting = scanAgent({ agent: "a", project: "p", sessionsDir: waitingDir, tmux: {} }, opts);
const working = scanAgent({ agent: "a", project: "p", sessionsDir: workingDir, tmux: {} }, opts);
const errored = scanAgent({ agent: "a", project: "p", sessionsDir: errorDir, tmux: {} }, opts);
assert.equal(waiting.state, "waiting");
assert.equal(waiting.waitingOnYou, true);
assert.equal(working.state, "working");
assert.equal(working.waitingOnYou, false);
assert.equal(errored.state, "error");
assert.equal(errored.waitingOnYou, true);
});
test("scanAgent: ageSeconds is computed from the injected now", () => {
const root = makeRoot();
const sessionsDir = join(root, "sessions");
mkdirSync(sessionsDir, { recursive: true });
writeSessionFile(sessionsDir, "s.jsonl", [
sessionLine({ id: "s1", timestamp: "2026-09-01T00:00:00.000Z", cwd: "/w" }),
messageLine({ timestamp: "2026-09-01T00:00:00.000Z", role: "assistant", stopReason: "stop", texts: ["done"] }),
]);
const now = new Date(Date.parse("2026-09-01T00:00:00.000Z") + 90_000);
const rec = scanAgent({ agent: "a", project: "p", sessionsDir, tmux: {} }, { isAlive: () => true, now: () => now });
assert.equal(rec.ageSeconds, 90);
assert.equal(rec.scannedAt, now.toISOString());
});
test("scanAgent: sessionFile null and state idle when sessions dir is empty but alive", () => {
const root = makeRoot();
const sessionsDir = join(root, "sessions");
mkdirSync(sessionsDir, { recursive: true });
const rec = scanAgent({ agent: "a", project: "p", sessionsDir, tmux: {} }, { isAlive: () => true, now: () => new Date() });
assert.equal(rec.sessionFile, null);
assert.equal(rec.state, "idle");
assert.equal(rec.alive, true);
assert.equal(rec.sessionId, null);
assert.equal(rec.cwd, null);
assert.equal(rec.lastAssistantText, null);
});
// ---------------------------------------------------------------------------
// 6. discoverRepoAgents / discoverFleetAgents
// ---------------------------------------------------------------------------
test("discoverRepoAgents: finds agents with a sessions dir, skips those without, sorted by name", () => {
const root = makeRoot();
const repoRoot = join(root, "repo");
mkdirSync(join(repoRoot, ".pi", "state", "b", "sessions"), { recursive: true });
mkdirSync(join(repoRoot, ".pi", "state", "a", "sessions"), { recursive: true });
mkdirSync(join(repoRoot, ".pi", "state", "c"), { recursive: true }); // no sessions dir: must be skipped
const specs = discoverRepoAgents(repoRoot);
assert.deepEqual(specs.map((s) => s.agent), ["a", "b"]);
const project = basename(resolve(repoRoot));
for (const spec of specs) {
assert.equal(spec.project, project);
assert.equal(spec.sessionsDir, join(repoRoot, ".pi", "state", spec.agent, "sessions"));
assert.deepEqual(spec.tmux, { socket: null, session: spec.agent });
}
});
test("discoverFleetAgents: finds agents with a sessions dir, sorted by name, fleet tmux fields", () => {
const root = makeRoot();
const fleetRoot = join(root, "fleet");
mkdirSync(join(fleetRoot, "y", ".pi", "agent", "sessions"), { recursive: true });
mkdirSync(join(fleetRoot, "x", ".pi", "agent", "sessions"), { recursive: true });
mkdirSync(join(fleetRoot, "z", ".pi"), { recursive: true }); // no sessions dir: must be skipped
const specs = discoverFleetAgents(fleetRoot);
assert.deepEqual(specs.map((s) => s.agent), ["x", "y"]);
for (const spec of specs) {
assert.equal(spec.project, "fleet");
assert.equal(spec.sessionsDir, join(fleetRoot, spec.agent, ".pi", "agent", "sessions"));
assert.deepEqual(spec.tmux, { socket: "mosaic-fleet", session: spec.agent });
}
});
// ---------------------------------------------------------------------------
// 7. scan
// ---------------------------------------------------------------------------
test("scan: writes per-agent files and index.json, rerun overwrites, no leftover tmp files", () => {
const root = makeRoot();
const boardDir = join(root, "board");
const sessionsDir = join(root, "src-sessions");
mkdirSync(sessionsDir, { recursive: true });
const sessionPath = join(sessionsDir, "s.jsonl");
writeFile(
sessionPath,
[
sessionLine({ id: "s1", timestamp: "2026-09-01T00:00:00Z", cwd: "/w" }),
messageLine({ timestamp: "2026-09-01T00:00:01Z", role: "assistant", stopReason: "stop", texts: ["done"] }),
].join("\n") + "\n"
);
const specs = [{ agent: "agent1", project: "proj", sessionsDir, tmux: {} }];
const opts = { boardDir, isAlive: () => true, now: () => new Date("2026-09-01T00:01:00Z") };
const index1 = scan(specs, opts);
const agentFile = join(boardDir, "sessions", "proj", "agent1.json");
const indexFile = join(boardDir, "index.json");
assert.ok(existsSync(agentFile));
assert.ok(existsSync(indexFile));
const rec1 = JSON.parse(readFileSync(agentFile, "utf8"));
assert.equal(rec1.state, "waiting");
assert.equal(index1.counts.waiting, 1);
assert.equal(index1.counts.working, 0);
assert.deepEqual(index1.waitingOnYou, ["proj/agent1"]);
assert.equal(index1.generatedAt, "2026-09-01T00:01:00.000Z");
// Flip the fixture to a "working" state and rescan; files must reflect the new state.
writeFile(
sessionPath,
[
sessionLine({ id: "s1", timestamp: "2026-09-01T00:00:00Z", cwd: "/w" }),
messageLine({ timestamp: "2026-09-01T00:02:00Z", role: "assistant", stopReason: "toolUse", texts: ["thinking"] }),
].join("\n") + "\n"
);
const index2 = scan(specs, { ...opts, now: () => new Date("2026-09-01T00:03:00Z") });
const rec2 = JSON.parse(readFileSync(agentFile, "utf8"));
assert.equal(rec2.state, "working");
assert.equal(index2.counts.working, 1);
assert.equal(index2.counts.waiting, 0);
assert.deepEqual(index2.waitingOnYou, []);
// No leftover *.tmp-* artifacts anywhere under boardDir.
const walk = (dir) => {
const names = readdirSync(dir, { withFileTypes: true });
for (const entry of names) {
const p = join(dir, entry.name);
assert.ok(!entry.name.includes(".tmp-"), `leftover tmp file: ${p}`);
if (entry.isDirectory()) walk(p);
}
};
walk(boardDir);
});
test("scan: relative boardDir throws ConfigError", () => {
assert.throws(() => scan([], { boardDir: "relative/board", isAlive: () => true }), ConfigError);
});
// ---------------------------------------------------------------------------
// 8. CLI
// ---------------------------------------------------------------------------
function runCli(args) {
return spawnSync(process.execPath, [cli, ...args], { encoding: "utf8", timeout: 15000 });
}
test("CLI: scan with assume-alive liveness exits 0, prints board summary, writes board files", () => {
const root = makeRoot();
const dataRoot = join(root, "data");
const configPath = join(root, "config.json");
writeFile(configPath, JSON.stringify({ dataRoot }));
const repoRoot = join(root, "repo");
const sessionsDir = join(repoRoot, ".pi", "state", "agent1", "sessions");
mkdirSync(sessionsDir, { recursive: true });
writeFile(
join(sessionsDir, "s.jsonl"),
[
sessionLine({ id: "s1", timestamp: "2026-09-01T00:00:00Z", cwd: "/w" }),
messageLine({ timestamp: "2026-09-01T00:00:01Z", role: "assistant", stopReason: "stop", texts: ["done"] }),
].join("\n") + "\n"
);
const r = runCli(["scan", "--config", configPath, "--repo", repoRoot, "--fleet", "none", "--liveness", "assume-alive", "--print"]);
assert.equal(r.status, 0, r.stderr);
assert.match(r.stdout, /^board: /m);
const boardDir = join(dataRoot, "board");
assert.ok(existsSync(join(boardDir, "index.json")));
assert.ok(existsSync(join(boardDir, "sessions", "repo", "agent1.json")));
const index = JSON.parse(readFileSync(join(boardDir, "index.json"), "utf8"));
assert.equal(index.sessions.length, 1);
assert.equal(index.counts.waiting, 1);
});
test("CLI: missing config exits 2 with a refused: message", () => {
const root = makeRoot();
const r = runCli(["scan", "--config", join(root, "no-such-config.json")]);
assert.equal(r.status, 2);
assert.match(r.stderr, /^refused:/);
});
test("CLI: unknown command exits 2", () => {
const r = runCli(["bogus"]);
assert.equal(r.status, 2);
assert.match(r.stderr, /^refused:/);
});
test("CLI: unknown --liveness value exits 2", () => {
const r = runCli(["scan", "--liveness", "bogus"]);
assert.equal(r.status, 2);
assert.match(r.stderr, /^refused:/);
});