Skip to content

Claude Code. Any Model. The most powerful AI coding agent now speaks every language.

test(team): add the run-registry contract and CLI SIGINT suites

Jack Rudenkod8859a98d296
diff --git a/packages/cli/src/team-cli-signal.test.ts b/packages/cli/src/team-cli-signal.test.ts
new file mode 100644
index 00000000..6ba69f2f
--- /dev/null
+++ b/packages/cli/src/team-cli-signal.test.ts
@@ -0,0 +1,101 @@
+/**
+ * `claudish team run` (json mode) runs every slot as an interactive pane, so Ctrl-C must
+ * reap them: SIGINT → every pane closed in ≤ 3 s → exit 130 (128 + SIGINT), with no
+ * process and no socket, record or launcher dir left behind (§6.3, D15 layer 3).
+ *
+ * The real CLI entry under bun, the fake interactive child as every pane (CLAUDISH_BIN),
+ * a hermetic environment and its own pane root.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import {
+ MAGMUX,
+ NO_MAGMUX_MESSAGE,
+ type PaneTestEnv,
+ finishPaneTest,
+ makePaneTestEnv,
+ waitUntil,
+} from "./test-helpers/team-pane.js";
+
+if (!MAGMUX) console.warn(NO_MAGMUX_MESSAGE);
+
+const ENTRY = join(import.meta.dir, "index.ts");
+
+let t: PaneTestEnv;
+
+beforeEach(() => {
+ t = makePaneTestEnv({ CONTRACT_FAKE_MAX_MS: "60000" });
+});
+
+afterEach(async () => {
+ const report = await finishPaneTest(t);
+ expect(report).toEqual({ processes: [], files: [] });
+});
+
+function slotStates(sessionPath: string): string[] {
+ try {
+ const status = JSON.parse(readFileSync(join(sessionPath, "status.json"), "utf8")) as {
+ models: Record<string, { state: string }>;
+ };
+ return Object.values(status.models).map((m) => m.state);
+ } catch {
+ return [];
+ }
+}
+
+describe.skipIf(!MAGMUX)("claudish team run — signals", () => {
+ it("SIGINT reaps every pane and exits 130", async () => {
+ // validateSessionPath wants the session under the cwd: run the CLI from the temp dir.
+ const cwd = join(t.tmp, "work");
+ mkdirSync(cwd, { recursive: true });
+ const sessionPath = join(cwd, "review");
+ const proc = Bun.spawn(
+ [
+ process.execPath,
+ ENTRY,
+ "team",
+ "run",
+ "--mode",
+ "json",
+ "--path",
+ sessionPath,
+ "--models",
+ "contract-fake-a,contract-fake-b",
+ "--input",
+ "@@HANG@@ hold until interrupted",
+ ],
+ { cwd, env: t.env, stdin: "ignore", stdout: "pipe", stderr: "pipe" }
+ );
+ let stderr = "";
+ void new Response(proc.stderr).text().then((s) => {
+ stderr = s;
+ });
+
+ try {
+ await waitUntil(
+ () => {
+ const states = slotStates(sessionPath);
+ return states.length === 2 && states.every((s) => s === "RUNNING");
+ },
+ "both slots RUNNING",
+ 30_000,
+ 100
+ );
+ expect(existsSync(join(t.sockRoot, "panes"))).toBe(true);
+
+ const sentAt = Date.now();
+ proc.kill("SIGINT");
+ const code = await Promise.race([proc.exited, Bun.sleep(10_000).then(() => "hung")]);
+
+ expect(code).toBe(130);
+ // ≤ 3 s reap budget, plus process start-up slack.
+ expect(Date.now() - sentAt).toBeLessThan(6_000);
+ } finally {
+ if (proc.exitCode === null) proc.kill("SIGKILL");
+ await proc.exited;
+ if (proc.exitCode !== 130) console.error(stderr.slice(-3000));
+ }
+ }, 60_000);
+});
diff --git a/packages/cli/src/team-list-contract.test.ts b/packages/cli/src/team-list-contract.test.ts
new file mode 100644
index 00000000..70a5499c
--- /dev/null
+++ b/packages/cli/src/team-list-contract.test.ts
@@ -0,0 +1,257 @@
+/**
+ * The team run registry behind `team(mode="list"|"status"|"cancel"|"capture")` (§3.2,
+ * §8 A–D, CA-13): runs are keyed by run_id with a newest-by-path index, ACTIVE runs list
+ * first, SETTLED runs stay for 30 minutes (at most 20), two runs whose paths share a
+ * basename are both listed (F6), a superseded run stays addressable by its run_id, and a
+ * path holds at most one ACTIVE run.
+ *
+ * Orchestrator + the pane fake in a real headless magmux; the §8 verbs are driven through
+ * the MCP handler's own functions so their JSON and ContractError envelopes are pinned.
+ */
+
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { teamContractVerb, teamStatusAnswer } from "./mcp-server.js";
+import { CAPABILITIES, type CaptureResult, type TeamRunRow } from "./pane/index.js";
+import {
+ MAX_SETTLED_RUNS,
+ type TeamHandle,
+ cancelTeamRun,
+ listTeamRuns,
+ preflightTeamRun,
+ pruneTeamRunsForTests,
+ resetTeamRegistryForTests,
+ setupSession,
+ startModels,
+} from "./team-orchestrator.js";
+import {
+ MAGMUX,
+ NO_MAGMUX_MESSAGE,
+ type PaneTestEnv,
+ finishPaneTest,
+ makePaneTestEnv,
+ paneRunOptions,
+} from "./test-helpers/team-pane.js";
+
+if (!MAGMUX) console.warn(NO_MAGMUX_MESSAGE);
+
+const HANG = "@@HANG@@ hold until cancelled";
+let t: PaneTestEnv;
+/** Session dirs live under the cwd: the §8 verbs validate `path` the way the server does. */
+let base: string;
+let handles: TeamHandle[];
+
+beforeEach(() => {
+ resetTeamRegistryForTests();
+ t = makePaneTestEnv();
+ base = mkdtempSync(join(process.cwd(), ".tmp-team-list-"));
+ handles = [];
+});
+
+afterEach(async () => {
+ for (const h of handles) {
+ await cancelTeamRun(h.sessionPath, undefined, h.runId).catch(() => undefined);
+ await h.done;
+ }
+ resetTeamRegistryForTests();
+ rmSync(base, { recursive: true, force: true });
+ const report = await finishPaneTest(t);
+ expect(report).toEqual({ processes: [], files: [] });
+});
+
+async function start(path: string, models: string[], input: string): Promise<TeamHandle> {
+ setupSession(path, models, input);
+ const h = await startModels(path, paneRunOptions(t));
+ handles.push(h);
+ return h;
+}
+
+function json(answer: { content: Array<{ text: string }>; isError?: boolean }) {
+ return { isError: answer.isError === true, body: JSON.parse(answer.content[0]?.text ?? "{}") };
+}
+
+describe.skipIf(!MAGMUX)("team run registry (list / status / cancel / capture)", () => {
+ it("lists ACTIVE runs first, then SETTLED by finished_at desc, with contract meta", async () => {
+ const a = await start(join(base, "a"), ["fake-answer"], "Reply with exactly PEAR");
+ await a.done;
+ const b = await start(join(base, "b"), ["fake-answer"], "Reply with exactly PEAR");
+ await b.done;
+ const c = await start(join(base, "c"), ["contract-fake-model"], HANG);
+
+ const listed = listTeamRuns();
+ expect(listed.contract_version).toBe(1);
+ expect(listed.capabilities).toEqual([...CAPABILITIES]);
+ expect(listed.runs.map((r) => [r.run_id, r.state])).toEqual([
+ [c.runId, "ACTIVE"],
+ [b.runId, "SETTLED"],
+ [a.runId, "SETTLED"],
+ ]);
+ const settled = listed.runs[1] as TeamRunRow;
+ expect(settled.outcome).toBe("ok");
+ expect(settled.finished_at).not.toBeNull();
+ expect(listed.runs[0]?.outcome).toBeNull();
+ expect(listed.runs[0]?.finished_at).toBeNull();
+ // run_id format: <team_session_id>-<base36 start ms>-<6 hex>
+ expect(c.runId).toMatch(/^c-[0-9a-z]+-[0-9a-f]{6}$/);
+
+ // The MCP list verb answers the same object.
+ const viaMcp = json(await teamContractVerb("list", {}));
+ expect(viaMcp.isError).toBe(false);
+ expect(viaMcp.body.runs.map((r: TeamRunRow) => r.run_id)).toEqual(
+ listed.runs.map((r) => r.run_id)
+ );
+ }, 60_000);
+
+ it("lists two runs whose paths share a basename, each addressable by path (F6)", async () => {
+ const p1 = join(base, "one", "review");
+ const p2 = join(base, "two", "review");
+ mkdirSync(join(base, "one"));
+ mkdirSync(join(base, "two"));
+ const r1 = await start(p1, ["contract-fake-model"], HANG);
+ const r2 = await start(p2, ["contract-fake-model"], HANG);
+
+ const paths = listTeamRuns()
+ .runs.map((r) => r.path)
+ .sort();
+ expect(paths).toEqual([p1, p2].sort());
+ expect(json(await teamContractVerb("status", { path: p1 })).body.run.run_id).toBe(r1.runId);
+ expect(json(await teamContractVerb("status", { path: p2 })).body.run.run_id).toBe(r2.runId);
+ }, 60_000);
+
+ it("keeps a superseded run addressable by run_id: listed, capturable, cancel changed:false, status without legacy keys", async () => {
+ const path = join(base, "reused");
+ const first = await start(path, ["fake-answer"], "Reply with exactly PEAR");
+ await first.done;
+ const slot = Object.values(first.slots)[0] as string;
+ // The next round reuses the path (its directory is cleared, as /dev:dev does).
+ rmSync(path, { recursive: true, force: true });
+ const second = await start(path, ["contract-fake-model"], HANG);
+
+ const runs = listTeamRuns().runs;
+ expect(runs.map((r) => r.run_id).sort()).toEqual([first.runId, second.runId].sort());
+
+ // status by the old run_id: `run` + contract keys, never the newer run's legacy keys.
+ const old = teamStatusAnswer(path, first.runId);
+ expect(Object.keys(old).sort()).toEqual(["capabilities", "contract_version", "run"]);
+ expect((old.run as TeamRunRow).run_id).toBe(first.runId);
+ expect((old.run as TeamRunRow).state).toBe("SETTLED");
+ // status by path: the newest run, with the legacy keys.
+ const newest = teamStatusAnswer(path);
+ expect((newest.run as TeamRunRow).run_id).toBe(second.runId);
+ expect(newest).toHaveProperty("models");
+
+ // capture of the superseded run's slot: its retained final screen.
+ const cap = json(await teamContractVerb("capture", { path, slot, run_id: first.runId }));
+ expect(cap.isError).toBe(false);
+ expect((cap.body as CaptureResult).final).toBe(true);
+ expect((cap.body as CaptureResult).lines).toHaveLength(50);
+
+ // cancel of the superseded run: every slot changed:false.
+ const cancel = json(await teamContractVerb("cancel", { path, run_id: first.runId }));
+ expect(cancel.body).toEqual({
+ run_id: first.runId,
+ path,
+ results: [{ slot, state: "COMPLETED", changed: false }],
+ });
+ }, 60_000);
+
+ it("refuses a second run on a path whose newest run is ACTIVE", async () => {
+ const path = join(base, "busy");
+ const active = await start(path, ["contract-fake-model"], HANG);
+ const message = `invalid_args: a team run is already ACTIVE at ${path} (run_id ${active.runId}); cancel it or wait for it`;
+
+ await expect(preflightTeamRun({ path, slots: 1 })).rejects.toThrow(message);
+ await expect(startModels(path, paneRunOptions(t))).rejects.toThrow(message);
+ }, 60_000);
+
+ it("answers unknown runs and slots with ContractError JSON", async () => {
+ const path = join(base, "nothing-here");
+ const unknownStatus = json(await teamContractVerb("status", { path }));
+ expect(unknownStatus).toEqual({
+ isError: true,
+ body: { error: { code: "unknown_run", message: expect.any(String) } },
+ });
+ const unknownId = json(
+ await teamContractVerb("capture", { path, slot: "01", run_id: "x-1-abcdef" })
+ );
+ expect(unknownId.body.error.code).toBe("unknown_run");
+ const noPath = json(await teamContractVerb("cancel", {}));
+ expect(noPath.body.error.code).toBe("invalid_args");
+
+ const r = await start(join(base, "known"), ["contract-fake-model"], HANG);
+ const badSlot = json(await teamContractVerb("capture", { path: r.sessionPath, slot: "99" }));
+ expect(badSlot.body.error.code).toBe("unknown_slot");
+ const noSlot = json(await teamContractVerb("capture", { path: r.sessionPath }));
+ expect(noSlot.body.error.code).toBe("invalid_args");
+ }, 60_000);
+
+ it("captures a live slot with since_seq and spans, and answers unchanged at the same seq", async () => {
+ const r = await start(join(base, "cap"), ["contract-fake-model"], HANG);
+ const slot = Object.values(r.slots)[0] as string;
+ const full = json(
+ await teamContractVerb("capture", { path: r.sessionPath, slot, spans: true })
+ );
+ const screen = full.body as CaptureResult;
+ expect(screen.seq).toBeGreaterThan(0);
+ expect(screen.cols).toBe(160);
+ expect(screen.rows).toBe(50);
+ expect(screen.final).toBe(false);
+ expect(Array.isArray(screen.spans)).toBe(true);
+ const same = json(
+ await teamContractVerb("capture", { path: r.sessionPath, slot, since_seq: screen.seq })
+ );
+ if (same.body.unchanged)
+ expect(same.body).toEqual({ unchanged: true, seq: screen.seq, final: false });
+ else expect(same.body.seq).toBeGreaterThan(screen.seq); // the screen moved in between
+ }, 60_000);
+
+ it("drops a settled run after 30 minutes; status then answers from status.json", async () => {
+ const path = join(base, "old");
+ const r = await start(path, ["fake-answer"], "Reply with exactly PEAR");
+ await r.done;
+ expect(listTeamRuns().runs.map((x) => x.run_id)).toEqual([r.runId]);
+
+ pruneTeamRunsForTests(Date.now() + 31 * 60_000);
+
+ expect(listTeamRuns().runs).toEqual([]);
+ const fromDisk = teamStatusAnswer(path);
+ const run = fromDisk.run as TeamRunRow;
+ expect(run.run_id).toBe(r.runId); // persisted in status.json
+ expect(run.state).toBe("SETTLED");
+ expect(run.slots.every((s) => s.idle_seconds === null && s.activity === null)).toBe(true);
+ const slot = Object.values(r.slots)[0] as string;
+ const cap = json(await teamContractVerb("capture", { path, slot }));
+ expect(cap.body.error.code).toBe("unknown_run");
+ }, 60_000);
+
+ it(`keeps at most ${MAX_SETTLED_RUNS} settled runs, evicting the oldest first`, async () => {
+ // Slots whose pane never spawns settle at once (FAILED pane_lost, no pane): a
+ // claudish subcommand name is refused as a model before anything starts.
+ const ids: string[] = [];
+ for (let i = 0; i < MAX_SETTLED_RUNS + 2; i++) {
+ const h = await start(join(base, `r${i}`), ["update"], "Reply with exactly PEAR");
+ await h.done;
+ ids.push(h.runId);
+ await Bun.sleep(2); // distinct finished_at
+ }
+ const listed = listTeamRuns().runs;
+ expect(listed).toHaveLength(MAX_SETTLED_RUNS);
+ expect(listed.map((r) => r.run_id)).not.toContain(ids[0]);
+ expect(listed.map((r) => r.run_id)).not.toContain(ids[1]);
+ expect(listed[0]?.run_id).toBe(ids.at(-1) as string);
+ const row = listed[0] as TeamRunRow;
+ expect(row.slots[0]).toMatchObject({ state: "FAILED", reason: "pane_lost", pane: null });
+ const cap = json(
+ await teamContractVerb("capture", { path: row.path, slot: row.slots[0]?.slot })
+ );
+ expect(cap.body).toEqual({
+ seq: 0,
+ cols: 160,
+ rows: 50,
+ cursor: { x: 0, y: 0 },
+ lines: Array.from({ length: 50 }, () => ""),
+ final: true,
+ });
+ }, 60_000);
+});