gentle-pi 4.3.0 → 4.4.0

package/tests/design-comments.test.ts

@@ -0,0 +1,201 @@
+import assert from "node:assert/strict";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { TestContext } from "node:test";
+import test from "node:test";
+import { DesignCommentsError, MAX_DESIGN_COMMENTS, MAX_DESIGN_SCREENSHOT_BYTES, createDesignCommentStore } from "../lib/design-comments.ts";
+
+// design/<slug>/comments.json has one owner: every read and write goes through
+// lib/design-comments.ts, so the canvas server and the agent tool serialize.
+
+function scratch(t: TestContext, prefix: string): string {
+	const dir = mkdtempSync(join(tmpdir(), prefix));
+	t.after(() => rmSync(dir, { recursive: true, force: true }));
+	return dir;
+}
+
+function designRoot(t: TestContext) {
+	const root = join(scratch(t, "gentle-design-comments-"), "design");
+	mkdirSync(join(root, "alpha"), { recursive: true });
+	return root;
+}
+
+const INPUT = { file: "01-hero.html", selector: "body > h1", excerpt: "Hero", comment: "Make it bigger" };
+const FIXED = new Date("2026-10-26T10:00:00.000Z");
+
+function fixedStore(root: string) {
+	let next = 0;
+	return createDesignCommentStore(root, { now: () => FIXED, randomId: () => `id${String(next++).padStart(4, "0")}` });
+}
+
+test("a missing comments.json reads as an empty document, and add appends an open, unsent comment", async (t) => {
+	const root = designRoot(t);
+	const store = fixedStore(root);
+	assert.deepEqual(await store.read("alpha"), { version: 1, comments: [] });
+	const added = await store.add("alpha", INPUT);
+	assert.deepEqual(added, { id: "id0000", ...INPUT, createdAt: FIXED.toISOString(), status: "open", sentAt: null, resolvedAt: null });
+	const onDisk = JSON.parse(readFileSync(join(root, "alpha", "comments.json"), "utf8"));
+	assert.deepEqual(onDisk, { version: 1, comments: [added] });
+	assert.deepEqual(await store.read("alpha"), onDisk);
+	assert.deepEqual(readdirSync(join(root, "alpha")), ["comments.json"], "no temp file is left behind");
+});
+
+test("generated ids are short, URL-safe and unique within the design", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignCommentStore(root);
+	const ids = new Set<string>();
+	for (let index = 0; index < 30; index++) ids.add((await store.add("alpha", INPUT)).id);
+	assert.equal(ids.size, 30);
+	for (const id of ids) assert.match(id, /^[a-z0-9]{6,12}$/);
+	// A colliding generator still yields unique ids.
+	const colliding = createDesignCommentStore(root, { randomId: () => [...ids][0] });
+	await assert.rejects(colliding.add("alpha", INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "id-exhausted");
+});
+
+test("setStatus resolves and reopens by id, and reports unknown ids", async (t) => {
+	const root = designRoot(t);
+	const store = fixedStore(root);
+	const a = await store.add("alpha", INPUT);
+	const b = await store.add("alpha", { ...INPUT, file: "02-bold.html" });
+	const resolved = await store.setStatus("alpha", [a.id, "nope00"], "resolved");
+	assert.deepEqual(resolved.updated.map((comment) => [comment.id, comment.status, comment.resolvedAt]), [[a.id, "resolved", FIXED.toISOString()]]);
+	assert.deepEqual(resolved.unknown, ["nope00"]);
+	assert.deepEqual((await store.listOpen("alpha")).map((comment) => comment.id), [b.id]);
+	assert.deepEqual((await store.listOpen("alpha", "02-bold.html")).map((comment) => comment.id), [b.id]);
+	assert.deepEqual(await store.listOpen("alpha", "01-hero.html"), []);
+	const reopened = await store.setStatus("alpha", [a.id], "open");
+	assert.equal(reopened.updated[0].status, "open");
+	assert.equal(reopened.updated[0].resolvedAt, null);
+	await assert.rejects(store.setStatus("alpha", [a.id], "done" as never), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-input");
+});
+
+test("markSent stamps sentAt once and leaves other comments alone", async (t) => {
+	const root = designRoot(t);
+	let clock = FIXED.getTime();
+	const store = createDesignCommentStore(root, { now: () => new Date(clock) });
+	const a = await store.add("alpha", INPUT);
+	const b = await store.add("alpha", INPUT);
+	await store.markSent("alpha", [a.id]);
+	clock += 60_000;
+	await store.markSent("alpha", [a.id]);
+	const { comments } = await store.read("alpha");
+	assert.equal(comments.find((comment) => comment.id === a.id)!.sentAt, FIXED.toISOString());
+	assert.equal(comments.find((comment) => comment.id === b.id)!.sentAt, null);
+});
+
+test("concurrent adds through separate stores keep every comment in valid JSON", async (t) => {
+	const root = designRoot(t);
+	// Two stores, as the server and the agent tool would have.
+	const server = createDesignCommentStore(root);
+	const tool = createDesignCommentStore(root);
+	const added = await Promise.all(Array.from({ length: 20 }, (_, index) => (index % 2 ? server : tool).add("alpha", { ...INPUT, comment: `c${index}` })));
+	const onDisk = JSON.parse(readFileSync(join(root, "alpha", "comments.json"), "utf8"));
+	assert.equal(onDisk.comments.length, 20);
+	assert.deepEqual(new Set(onDisk.comments.map((comment: { id: string }) => comment.id)), new Set(added.map((comment) => comment.id)));
+	await Promise.all([server.setStatus("alpha", [added[0].id], "resolved"), tool.markSent("alpha", [added[1].id]), server.add("alpha", INPUT)]);
+	const after = await tool.read("alpha");
+	assert.equal(after.comments.length, 21);
+	assert.equal(after.comments.find((comment) => comment.id === added[0].id)!.status, "resolved");
+	assert.notEqual(after.comments.find((comment) => comment.id === added[1].id)!.sentAt, null);
+});
+
+test("an unparsable or invalid comments.json is a typed error and is never overwritten", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignCommentStore(root);
+	const path = join(root, "alpha", "comments.json");
+	for (const bytes of ["{ not json", JSON.stringify({ version: 2, comments: [] }), JSON.stringify({ version: 1, comments: [{ id: "x" }] }), "[]"]) {
+		writeFileSync(path, bytes);
+		await assert.rejects(store.read("alpha"), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-file", bytes);
+		await assert.rejects(store.add("alpha", INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-file");
+		await assert.rejects(store.setStatus("alpha", ["x"], "resolved"));
+		assert.equal(readFileSync(path, "utf8"), bytes, "bytes unchanged");
+	}
+});
+
+test("a design holds at most 500 comments; the next one is refused with a clear error", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignCommentStore(root);
+	assert.equal(MAX_DESIGN_COMMENTS, 500);
+	const comments = Array.from({ length: 500 }, (_, index) => ({ id: `c${String(index).padStart(5, "0")}`, ...INPUT, createdAt: FIXED.toISOString(), status: "open", sentAt: null, resolvedAt: null }));
+	writeFileSync(join(root, "alpha", "comments.json"), JSON.stringify({ version: 1, comments }));
+	await assert.rejects(store.add("alpha", INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "limit" && /500/.test(error.message));
+	assert.equal((await store.read("alpha")).comments.length, 500);
+});
+
+test("inputs are validated before anything is written", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignCommentStore(root);
+	const invalid = [
+		{ ...INPUT, file: "../beta/01.html" },
+		{ ...INPUT, file: "styles.css" },
+		{ ...INPUT, comment: "" },
+		{ ...INPUT, comment: "x".repeat(2001) },
+		{ ...INPUT, selector: "" },
+		{ ...INPUT, selector: "a".repeat(501) },
+		{ ...INPUT, excerpt: "e".repeat(301) },
+	];
+	for (const input of invalid) await assert.rejects(store.add("alpha", input), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-input");
+	for (const slug of ["Alpha", "../alpha", "", "missing"]) await assert.rejects(store.add(slug, INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "not-found", slug);
+	assert.deepEqual(readdirSync(join(root, "alpha")), []);
+});
+
+test("a design directory or comments.json that escapes the root by symlink is refused", async (t) => {
+	const root = designRoot(t);
+	const outside = scratch(t, "gentle-design-comments-outside-");
+	writeFileSync(join(outside, "comments.json"), JSON.stringify({ version: 1, comments: [] }));
+	symlinkSync(outside, join(root, "escape"));
+	const store = createDesignCommentStore(root);
+	await assert.rejects(store.read("escape"), (error: unknown) => error instanceof DesignCommentsError && error.code === "not-found");
+	await assert.rejects(store.add("escape", INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "not-found");
+	mkdirSync(join(root, "beta"));
+	symlinkSync(join(outside, "comments.json"), join(root, "beta", "comments.json"));
+	await assert.rejects(store.add("beta", INPUT), (error: unknown) => error instanceof DesignCommentsError && error.code === "not-found");
+	assert.equal(readFileSync(join(outside, "comments.json"), "utf8"), JSON.stringify({ version: 1, comments: [] }), "the outside file is untouched");
+});
+
+const PNG = Buffer.concat([Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]), Buffer.from("frame")]);
+
+test("a comment with a screenshot stores the image beside comments.json and reads it back", async (t) => {
+	const root = designRoot(t);
+	const store = fixedStore(root);
+	const added = await store.add("alpha", { ...INPUT, screenshot: { mimeType: "image/png", data: PNG } });
+	assert.deepEqual(added, { id: "id0000", ...INPUT, screenshot: ".screenshots/id0000.png", createdAt: FIXED.toISOString(), status: "open", sentAt: null, resolvedAt: null });
+	assert.deepEqual(readFileSync(join(root, "alpha", ".screenshots", "id0000.png")), PNG);
+	assert.deepEqual(JSON.parse(readFileSync(join(root, "alpha", "comments.json"), "utf8")).comments, [added]);
+	assert.deepEqual(await store.read("alpha"), { version: 1, comments: [added] });
+	assert.deepEqual(await store.readScreenshot("alpha", "id0000"), { path: ".screenshots/id0000.png", mimeType: "image/png", data: PNG });
+	const plain = await store.add("alpha", INPUT);
+	assert.equal("screenshot" in plain, false, "a comment without a screenshot keeps the old shape");
+	assert.equal(await store.readScreenshot("alpha", plain.id), undefined);
+	assert.equal(await store.readScreenshot("alpha", "nope"), undefined);
+	assert.deepEqual(readdirSync(join(root, "alpha", ".screenshots")), ["id0000.png"], "no temp file is left behind");
+});
+
+test("a screenshot of an unknown type, a mismatched signature, or over the size limit is refused and writes nothing", async (t) => {
+	const root = designRoot(t);
+	const store = fixedStore(root);
+	const refused = [
+		{ mimeType: "image/svg+xml", data: PNG },
+		{ mimeType: "image/jpeg", data: PNG },
+		{ mimeType: "image/png", data: Buffer.alloc(0) },
+		{ mimeType: "image/png", data: Buffer.concat([PNG, Buffer.alloc(MAX_DESIGN_SCREENSHOT_BYTES)]) },
+	];
+	for (const screenshot of refused) {
+		await assert.rejects(store.add("alpha", { ...INPUT, screenshot }), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-input");
+	}
+	assert.deepEqual(readdirSync(join(root, "alpha")), []);
+});
+
+test("a stored screenshot path outside .screenshots makes comments.json invalid, and a linked .screenshots is refused", async (t) => {
+	const root = designRoot(t);
+	const store = fixedStore(root);
+	const entry = { id: "a1", ...INPUT, screenshot: "../secret.png", createdAt: FIXED.toISOString(), status: "open", sentAt: null, resolvedAt: null };
+	writeFileSync(join(root, "alpha", "comments.json"), JSON.stringify({ version: 1, comments: [entry] }));
+	await assert.rejects(store.read("alpha"), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-file");
+	rmSync(join(root, "alpha", "comments.json"));
+	const outside = scratch(t, "gentle-design-shots-outside-");
+	symlinkSync(outside, join(root, "alpha", ".screenshots"));
+	await assert.rejects(store.add("alpha", { ...INPUT, screenshot: { mimeType: "image/png", data: PNG } }), (error: unknown) => error instanceof DesignCommentsError && error.code === "invalid-file");
+	assert.deepEqual(readdirSync(outside), []);
+});

package/tests/design-handoffs.test.ts

@@ -0,0 +1,282 @@
+import assert from "node:assert/strict";
+import { createHash } from "node:crypto";
+import { mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, symlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { TestContext } from "node:test";
+import test from "node:test";
+import { DESIGN_HANDOFF_NOTE_LIMIT, DesignHandoffsError, createDesignHandoffStore, designPreviewUrlProblem, sendDesignHandoff } from "../lib/design-handoffs.ts";
+
+// design/<slug>/handoffs.json has one owner (S15): the canvas server, the
+// command and the gentle_design tool all write through lib/design-handoffs.ts,
+// in the same per-file queue as comments.json.
+
+function scratch(t: TestContext, prefix: string): string {
+	const dir = mkdtempSync(join(tmpdir(), prefix));
+	t.after(() => rmSync(dir, { recursive: true, force: true }));
+	return dir;
+}
+
+function designRoot(t: TestContext) {
+	const root = join(scratch(t, "gentle-design-handoffs-"), "design");
+	mkdirSync(join(root, "alpha"), { recursive: true });
+	return root;
+}
+
+/** A clock that advances one second per call, so every timestamp is distinct and predictable. */
+function ticking() {
+	let seconds = 0;
+	return () => new Date(Date.UTC(2026, 9, 26, 10, 0, seconds++));
+}
+
+const at = (seconds: number) => new Date(Date.UTC(2026, 9, 26, 10, 0, seconds)).toISOString();
+const onDisk = (root: string) => JSON.parse(readFileSync(join(root, "alpha", "handoffs.json"), "utf8"));
+const hash = (path: string) => createHash("sha256").update(readFileSync(path)).digest("hex");
+const isCode = (code: string) => (error: unknown) => error instanceof DesignHandoffsError && error.code === code;
+
+test("a missing handoffs.json reads as an empty document with nothing chosen", async (t) => {
+	const root = designRoot(t);
+	assert.deepEqual(await createDesignHandoffStore(root).read("alpha"), { version: 1, chosen: null, handoffs: {} });
+});
+
+test("markSent records a sent handoff, sets chosen, and a second handoff moves chosen", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	const first = await store.markSent("alpha", "01-a.html", { queued: true, feature: "odd/tasks/login.md" });
+	assert.deepEqual(first.entry, { status: "sent", queued: true, sentAt: at(0), startedAt: null, implementedAt: null, feature: "odd/tasks/login.md" });
+	assert.deepEqual(onDisk(root), { version: 1, chosen: "01-a.html", handoffs: { "01-a.html": first.entry } });
+	assert.deepEqual(readdirSync(join(root, "alpha")), ["handoffs.json"], "no temp file is left behind");
+
+	const second = await store.markSent("alpha", "02-b.html", { queued: false });
+	assert.equal(onDisk(root).chosen, "02-b.html", "one chosen artboard per design; the new handoff moves it");
+	assert.deepEqual(onDisk(root).handoffs["01-a.html"], first.entry, "the earlier handoff keeps its state");
+	assert.deepEqual(second.entry, { status: "sent", queued: false, sentAt: at(1), startedAt: null, implementedAt: null });
+	assert.deepEqual(await store.read("alpha"), onDisk(root));
+});
+
+test("setStatus moves a handoff to in_progress and implemented with timestamps, note and previewUrl", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	await store.markSent("alpha", "01-a.html", { queued: false });
+	const started = await store.setStatus("alpha", "01-a.html", "in_progress", { note: "  Starting with the header  " });
+	assert.deepEqual(started, { status: "in_progress", queued: false, sentAt: at(0), startedAt: at(1), implementedAt: null, note: "Starting with the header" });
+	const done = await store.setStatus("alpha", "01-a.html", "implemented", { previewUrl: "http://localhost:5173/login" });
+	assert.deepEqual(done, { status: "implemented", queued: false, sentAt: at(0), startedAt: at(1), implementedAt: at(2), previewUrl: "http://localhost:5173/login" }, "note and previewUrl are exactly what each update passes");
+	assert.deepEqual(onDisk(root).handoffs["01-a.html"], done);
+
+	// A new handoff of the same artboard starts over.
+	const again = await store.markSent("alpha", "01-a.html", { queued: true });
+	assert.deepEqual(again.entry, { status: "sent", queued: true, sentAt: at(3), startedAt: null, implementedAt: null });
+	const restarted = await store.setStatus("alpha", "01-a.html", "in_progress", {});
+	assert.equal(restarted.implementedAt, null);
+	assert.equal(restarted.startedAt, at(4));
+});
+
+test("setStatus on an artboard never handed off records it and makes it chosen; it never moves chosen otherwise", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	const entry = await store.setStatus("alpha", "02-b.html", "in_progress", {});
+	assert.deepEqual(entry, { status: "in_progress", queued: false, sentAt: at(0), startedAt: at(0), implementedAt: null });
+	assert.equal(onDisk(root).chosen, "02-b.html");
+	await store.markSent("alpha", "01-a.html", { queued: false });
+	await store.setStatus("alpha", "02-b.html", "implemented", {});
+	assert.equal(onDisk(root).chosen, "01-a.html", "an update of an earlier handoff keeps the latest handoff chosen");
+});
+
+test("setStatus and markSent refuse bad input with a typed error and write nothing", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root);
+	await assert.rejects(store.setStatus("alpha", "01-a.html", "sent" as never, {}), isCode("invalid-input"));
+	await assert.rejects(store.setStatus("alpha", "01-a.html", "done" as never, {}), isCode("invalid-input"));
+	await assert.rejects(store.setStatus("alpha", "../x.html", "in_progress", {}), isCode("invalid-input"));
+	await assert.rejects(store.setStatus("alpha", "01-a.html", "in_progress", { note: "x".repeat(DESIGN_HANDOFF_NOTE_LIMIT + 1) }), isCode("invalid-input"));
+	await assert.rejects(store.setStatus("alpha", "01-a.html", "in_progress", { note: 7 as never }), isCode("invalid-input"));
+	await assert.rejects(store.markSent("alpha", "01-a.html", { queued: "yes" as never }), isCode("invalid-input"));
+	await assert.rejects(store.markSent("alpha", "01-a.html", { queued: false, feature: "../x.md" }), isCode("invalid-input"));
+	await assert.rejects(store.markSent("alpha", "notes.txt", { queued: false }), isCode("invalid-input"));
+	await assert.rejects(store.setStatus("Bad_Slug", "01-a.html", "in_progress", {}), isCode("not-found"));
+	await assert.rejects(store.setStatus("missing", "01-a.html", "in_progress", {}), isCode("not-found"));
+	const ok = await store.setStatus("alpha", "01-a.html", "in_progress", { note: "x".repeat(DESIGN_HANDOFF_NOTE_LIMIT) });
+	assert.equal(ok.note?.length, DESIGN_HANDOFF_NOTE_LIMIT, "a note at the limit is kept");
+	assert.equal(Object.keys(onDisk(root).handoffs).length, 1);
+});
+
+const ACCEPTED = [
+	"http://localhost:3000/",
+	"http://localhost:5173/login?tab=a#top",
+	"https://localhost:8443/",
+	"http://127.0.0.1:8080/app",
+	"https://127.0.0.1:1/",
+	"http://[::1]:3000/",
+	"https://[::1]:4443/x",
+	"http://localhost/",
+	"http://LOCALHOST:3000/",
+];
+
+const REJECTED = [
+	"http://example.com",
+	"http://localhost.evil.test",
+	"http://localhost.evil.test:3000/",
+	"http://evil.localhost:3000/",
+	"http://user:pw@localhost:3000/",
+	"http://user@localhost:3000/",
+	"javascript:alert(1)",
+	"file:///etc/passwd",
+	"data:text/html,hi",
+	"ftp://localhost/",
+	"ws://localhost:3000/",
+	"http://127.0.0.2/",
+	"http://0.0.0.0:3000/",
+	"http://[::2]:3000/",
+	"http://localhost:3000/\nInjected",
+	" http://localhost:3000/",
+	"//localhost:3000/",
+	"localhost:3000",
+	"",
+	`http://localhost:3000/${"a".repeat(2048 - "http://localhost:3000/".length + 1)}`,
+];
+
+test("previewUrl accepts only loopback http(s) URLs without credentials, at most 2048 characters", () => {
+	for (const url of ACCEPTED) assert.equal(designPreviewUrlProblem(url), undefined, url);
+	assert.equal(designPreviewUrlProblem(`http://localhost:3000/${"a".repeat(2048 - "http://localhost:3000/".length)}`), undefined, "exactly 2048 characters");
+	for (const url of REJECTED) assert.equal(typeof designPreviewUrlProblem(url), "string", url);
+	assert.equal(REJECTED.at(-1)!.length, 2049);
+	for (const value of [7, null, undefined, {}]) assert.equal(typeof designPreviewUrlProblem(value), "string", String(value));
+});
+
+test("setStatus stores a valid previewUrl and refuses an invalid one with a typed error", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root);
+	await store.markSent("alpha", "01-a.html", { queued: false });
+	const before = hash(join(root, "alpha", "handoffs.json"));
+	for (const url of REJECTED) {
+		await assert.rejects(store.setStatus("alpha", "01-a.html", "implemented", { previewUrl: url }), isCode("invalid-preview-url"), url);
+	}
+	assert.equal(hash(join(root, "alpha", "handoffs.json")), before, "a refused update writes nothing");
+	for (const url of ACCEPTED) {
+		const entry = await store.setStatus("alpha", "01-a.html", "implemented", { previewUrl: url });
+		assert.equal(entry.previewUrl, new URL(url).href, url);
+	}
+});
+
+test("20 parallel markSent and setStatus calls leave valid JSON and lose nothing", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root);
+	// A second store over the same root shares the process-wide queue.
+	const other = createDesignHandoffStore(root);
+	const files = Array.from({ length: 20 }, (_, index) => `${String(index).padStart(2, "0")}-a.html`);
+	await Promise.all(files.map((file, index) => index % 2 === 0
+		? store.markSent("alpha", file, { queued: index % 4 === 0 })
+		: other.setStatus("alpha", file, "implemented", { previewUrl: `http://localhost:${3000 + index}/` })));
+	const document = onDisk(root);
+	assert.deepEqual(Object.keys(document.handoffs).sort(), files);
+	for (const [index, file] of files.entries()) {
+		const entry = document.handoffs[file];
+		if (index % 2 === 0) assert.equal(entry.status, "sent", file);
+		else assert.deepEqual([entry.status, entry.previewUrl], ["implemented", `http://localhost:${3000 + index}/`], file);
+	}
+	assert.ok(files.includes(document.chosen));
+	assert.deepEqual(readdirSync(join(root, "alpha")), ["handoffs.json"]);
+
+	// Racing updates of one artboard each land whole: the last one in queue order wins, never a mix.
+	const results = await Promise.all(Array.from({ length: 20 }, (_, index) => store.setStatus("alpha", "00-a.html", index % 2 ? "implemented" : "in_progress", { note: `n${index}` })));
+	const final = onDisk(root).handoffs["00-a.html"];
+	const index = Number(/^n(\d+)$/.exec(final.note)![1]);
+	assert.equal(final.status, index % 2 ? "implemented" : "in_progress");
+	assert.ok(results.some((entry) => JSON.stringify(entry) === JSON.stringify(final)), "the file holds one complete update");
+});
+
+test("an invalid handoffs.json is reported and never overwritten", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root);
+	const path = join(root, "alpha", "handoffs.json");
+	const broken = [
+		"{ not json",
+		"[]",
+		JSON.stringify({ version: 2, chosen: null, handoffs: {} }),
+		JSON.stringify({ version: 1, chosen: null, handoffs: [] }),
+		JSON.stringify({ version: 1, chosen: "01-a.html", handoffs: {} }),
+		JSON.stringify({ version: 1, chosen: null, handoffs: { "../x.html": { status: "sent", queued: false, sentAt: "t", startedAt: null, implementedAt: null } } }),
+		JSON.stringify({ version: 1, chosen: null, handoffs: { "01-a.html": { status: "done", queued: false, sentAt: "t", startedAt: null, implementedAt: null } } }),
+		JSON.stringify({ version: 1, chosen: null, handoffs: { "01-a.html": { status: "sent", queued: false, sentAt: "t", startedAt: null, implementedAt: null, previewUrl: "http://example.com/" } } }),
+		JSON.stringify({ version: 1, chosen: null, handoffs: { "01-a.html": { status: "sent", queued: 1, sentAt: "t", startedAt: null, implementedAt: null } } }),
+	];
+	for (const content of broken) {
+		writeFileSync(path, content);
+		const before = hash(path);
+		await assert.rejects(store.read("alpha"), isCode("invalid-file"), content);
+		await assert.rejects(store.markSent("alpha", "01-a.html", { queued: false }), isCode("invalid-file"), content);
+		await assert.rejects(store.setStatus("alpha", "01-a.html", "implemented", {}), isCode("invalid-file"), content);
+		assert.equal(hash(path), before, `${content} is never overwritten`);
+	}
+	assert.deepEqual(readdirSync(join(root, "alpha")), ["handoffs.json"]);
+});
+
+test("a symlinked handoffs.json is refused, and so is a design that escapes design/", async (t) => {
+	const root = designRoot(t);
+	const outside = scratch(t, "gentle-design-handoffs-outside-");
+	const target = join(outside, "handoffs.json");
+	writeFileSync(target, JSON.stringify({ version: 1, chosen: null, handoffs: {} }));
+	const before = hash(target);
+	symlinkSync(target, join(root, "alpha", "handoffs.json"));
+	const store = createDesignHandoffStore(root);
+	await assert.rejects(store.read("alpha"), isCode("not-found"));
+	await assert.rejects(store.markSent("alpha", "01-a.html", { queued: false }), isCode("not-found"));
+	await assert.rejects(store.setStatus("alpha", "01-a.html", "in_progress", {}), isCode("not-found"));
+	assert.equal(hash(target), before, "the link target is untouched");
+
+	mkdirSync(join(outside, "escaped"));
+	symlinkSync(join(outside, "escaped"), join(root, "escaped"));
+	await assert.rejects(store.markSent("escaped", "01-a.html", { queued: false }), isCode("not-found"));
+	for (const slug of ["..", ".", "../design", "alpha/..", ""]) await assert.rejects(store.read(slug), isCode("not-found"), slug);
+	assert.deepEqual(readdirSync(join(outside, "escaped")), [], "nothing is written outside design/");
+});
+
+test("sendDesignHandoff records the handoff before delivery, then the queued answer of the delivery", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	const seen: unknown[] = [];
+	const result = await sendDesignHandoff(store, { slug: "alpha", file: "01-a.html", feature: "odd/tasks/login.md" }, () => {
+		seen.push(onDisk(root));
+		return { queued: true };
+	});
+	assert.deepEqual(result, { queued: true });
+	assert.deepEqual(seen, [{ version: 1, chosen: "01-a.html", handoffs: { "01-a.html": { status: "sent", queued: false, sentAt: at(0), startedAt: null, implementedAt: null, feature: "odd/tasks/login.md" } } }], "recorded before delivery");
+	assert.equal(onDisk(root).handoffs["01-a.html"].queued, true);
+
+	const idle = await sendDesignHandoff(store, { slug: "alpha", file: "02-b.html" }, () => undefined);
+	assert.deepEqual(idle, { queued: false });
+	assert.equal(onDisk(root).handoffs["02-b.html"].queued, false);
+	assert.equal(onDisk(root).chosen, "02-b.html");
+});
+
+test("a failed delivery takes the handoff back and restores the previous chosen artboard", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	await sendDesignHandoff(store, { slug: "alpha", file: "01-a.html" }, () => ({ queued: false }));
+	const before = onDisk(root);
+	await assert.rejects(sendDesignHandoff(store, { slug: "alpha", file: "02-b.html" }, () => { throw new Error("boom"); }), /boom/);
+	assert.deepEqual(onDisk(root), before, "the failed handoff leaves no trace");
+
+	await store.setStatus("alpha", "01-a.html", "implemented", {});
+	const implemented = onDisk(root);
+	await assert.rejects(sendDesignHandoff(store, { slug: "alpha", file: "01-a.html" }, async () => { throw new Error("late"); }), /late/);
+	assert.deepEqual(onDisk(root), implemented, "a failed re-handoff restores the earlier state of that artboard");
+});
+
+test("a delivery answer never overwrites a state the agent already changed", async (t) => {
+	const root = designRoot(t);
+	const store = createDesignHandoffStore(root, { now: ticking() });
+	await sendDesignHandoff(store, { slug: "alpha", file: "01-a.html" }, async () => {
+		// The agent picks the handoff up before the delivery returns.
+		await store.setStatus("alpha", "01-a.html", "in_progress", {});
+		return { queued: true };
+	});
+	assert.equal(onDisk(root).handoffs["01-a.html"].status, "in_progress");
+	assert.equal(onDisk(root).handoffs["01-a.html"].queued, false);
+	await assert.rejects(sendDesignHandoff(store, { slug: "alpha", file: "02-b.html" }, async () => {
+		await store.setStatus("alpha", "02-b.html", "in_progress", {});
+		throw new Error("boom");
+	}), /boom/);
+	assert.equal(onDisk(root).handoffs["02-b.html"].status, "in_progress", "a failure after the agent took it over keeps the agent's state");
+});

package/tests/design-open-browser.test.ts

@@ -0,0 +1,70 @@
+import assert from "node:assert/strict";
+import { EventEmitter } from "node:events";
+import test from "node:test";
+import { openInBrowser } from "../lib/design-open-browser.ts";
+
+type Call = { command: string; args: readonly string[]; options: Record<string, unknown> };
+const URL_ = "http://127.0.0.1:4321/abc/";
+
+function fakeSpawn(outcome: "spawn" | "error" | "throw") {
+	const calls: Call[] = [];
+	let unrefs = 0;
+	const spawn = (command: string, args: readonly string[], options: Record<string, unknown>) => {
+		calls.push({ command, args, options });
+		if (outcome === "throw") throw new Error("spawn exploded");
+		const child = Object.assign(new EventEmitter(), { unref: () => { unrefs++; } });
+		queueMicrotask(() => outcome === "spawn" ? child.emit("spawn") : child.emit("error", Object.assign(new Error("spawn xdg-open ENOENT"), { code: "ENOENT" })));
+		return child;
+	};
+	return { spawn: spawn as never, calls, unrefs: () => unrefs };
+}
+
+const OPTIONS = { detached: true, stdio: "ignore", windowsHide: true, shell: false };
+
+test("darwin opens the URL with /usr/bin/open, detached and hidden", async () => {
+	const fake = fakeSpawn("spawn");
+	assert.deepEqual(await openInBrowser(URL_, { platform: "darwin", spawn: fake.spawn }), { opened: true });
+	assert.deepEqual(fake.calls, [{ command: "/usr/bin/open", args: [URL_], options: OPTIONS }]);
+	assert.equal(fake.unrefs(), 1);
+});
+
+test("win32 uses the absolute rundll32 FileProtocolHandler", async () => {
+	const fake = fakeSpawn("spawn");
+	assert.deepEqual(await openInBrowser(URL_, { platform: "win32", spawn: fake.spawn, env: { SystemRoot: "C:\\Windows" } }), { opened: true });
+	assert.deepEqual(fake.calls, [{ command: "C:\\Windows\\System32\\rundll32.exe", args: ["url.dll,FileProtocolHandler", URL_], options: OPTIONS }]);
+	const missing = fakeSpawn("spawn");
+	const result = await openInBrowser(URL_, { platform: "win32", spawn: missing.spawn, env: {} });
+	assert.equal(result.opened, false);
+	assert.match(String(result.error), /SystemRoot/);
+	assert.deepEqual(missing.calls, []);
+});
+
+test("other platforms use xdg-open", async () => {
+	for (const platform of ["linux", "freebsd"] as const) {
+		const fake = fakeSpawn("spawn");
+		assert.deepEqual(await openInBrowser(URL_, { platform, spawn: fake.spawn }), { opened: true });
+		assert.deepEqual(fake.calls, [{ command: "xdg-open", args: [URL_], options: OPTIONS }]);
+	}
+});
+
+test("spawn failures resolve opened:false and never throw", async () => {
+	const failing = fakeSpawn("error");
+	const result = await openInBrowser(URL_, { platform: "linux", spawn: failing.spawn });
+	assert.equal(result.opened, false);
+	assert.match(String(result.error), /ENOENT/);
+	const throwing = fakeSpawn("throw");
+	const thrown = await openInBrowser(URL_, { platform: "darwin", spawn: throwing.spawn });
+	assert.equal(thrown.opened, false);
+	assert.match(String(thrown.error), /spawn exploded/);
+});
+
+test("only loopback http URLs are opened", async () => {
+	for (const url of ["https://example.com/", "file:///etc/passwd", "-flag", "http://evil.example:1/", "javascript:alert(1)"]) {
+		const fake = fakeSpawn("spawn");
+		const result = await openInBrowser(url, { platform: "linux", spawn: fake.spawn });
+		assert.equal(result.opened, false, url);
+		assert.deepEqual(fake.calls, [], url);
+	}
+	const localhost = fakeSpawn("spawn");
+	assert.equal((await openInBrowser("http://localhost:4321/t/", { platform: "linux", spawn: localhost.spawn })).opened, true);
+});