oxedyne/daimond — dev/harness.mjs

oxedyne/daimond/dev/harness.mjs

44.8 KiB, 1 run

created by r2519314175:21, which is this file's identity for as long as the history lasts, whatever it is later renamed to

download · who wrote it · its history

1	// A browser harness for driving Daimond the way a user does.
2	//
3	// Every flow worth testing runs through the real page: the wasm, the panels,
4	// the agent loop, the tools. This opens a browser on the dev server, gets
5	// past the passphrase gate, points the app at the mock provider, and hands
6	// back a page you can drive. Console errors and page crashes are collected
7	// throughout, because a flow that "works" while throwing is not working.
8	//
9	// import { open, chat, newChat, shot, errors } from './harness.mjs';
10	// const s = await open(); // signed in, model connected
11	// await newChat(s); // …and now in a chat of its own
12	// const dir = await s.page.evaluate(() => {
13	// const f = window.DaimondAttach.focus();
14	// return window.DaimondAttach.chatScratch(f.id); // chats/<id>/work
15	// });
16	// await chat(s, `@tool file_write {"path":"${dir}/a.txt","content":"hi"}`);
17	// await shot(s, 'after-write');
18	// await s.close();
19	//
20	// A WORKSPACE-ROOT PATH DOES NOT WORK, and it fails silently, which is why the
21	// example above is longer than it used to be. This said `{"path":"a.txt"}` until
22	// 2026-08-14. Since the chat fence landed on 2026-08-12 every chat is confined to
23	// `chats/<id>/work` (`scopeChatTo`, www/js/daimond.js), and `Tool::guard`
24	// (src/tools.rs) refuses anything outside it BEFORE the tool runs. The refusal comes
25	// back as an ordinary tool result: nothing is written, nothing throws, and the turn
26	// finishes normally — so a fixture built on a root path leaves the test measuring an
27	// apology. Six verifiers were seeding that way, and two of them were reporting a
28	// user's data safe without ever touching a file.
29	//
30	// `chatScratch` is where the chat may ALWAYS write. For a path elsewhere in the
31	// workspace, mark a folder in the way a user does — `DaimondAttach.chatToggle` then
32	// `DaimondAttach.chatWs`, the mark being the permission (see dev/verify_viewer.mjs).
33	// For a fixture that is not ABOUT a turn, write it through the engine's own door
34	// instead: `(await import('/pkg/oxedyne_daimond.js')).write_file(path, body)`, which
35	// is not fenced because it is not a chat (see dev/verify_backup.mjs).
36	//
37	// A FAILED REQUEST NAMES ITS SERVER. `errors(s)` pairs every "Failed to load
38	// resource" with the URL behind it, and drops the ones from hosts outside this
39	// world after printing them. See `open()`'s response hook and `errors()` below
40	// for the gate that made this necessary.
41	//
42	// Headless by default. Pass { headed: true } for the extension flows, which
43	// need real rendering — and run those under xvfb, never on the user's display.
44
45	import fs from 'node:fs';
46	import crypto from 'node:crypto';
47	import os from 'node:os';
48	import path from 'node:path';
49	import { fileURLToPath, pathToFileURL } from 'node:url';
50	import { extDev, isExtSource } from './extdev.mjs';
51
52	// playwright-core lives outside the repo, so it is resolved by path, not by
53	// package name — nothing here is installed into the app.
54	/// Where playwright-core is, since it lives outside the repo and is resolved by
55	/// path rather than by package name.
56	///
57	/// Exported because a file that launches a browser of its own -- rather than
58	/// through `open()` -- would otherwise write this path down a second time, and a
59	/// second copy of a path is a second thing to move.
60	export const PW = process.env.DAIMOND_PW
61	\|\| path.join(os.homedir(), '.red-pw/node_modules/playwright-core/index.mjs');
62	const { chromium } = await import(pathToFileURL(PW).href);
63
64	const HERE = path.dirname(fileURLToPath(import.meta.url));
65	const SHOTS = path.join(HERE, 'shots');
66
67	/// The dev server, the mock provider and the mock's log together make one
68	/// "world". They are all settable so several agents can each hold one and drive
69	/// their own browser; `dev/world.sh N` prints a consistent set. A shared mock log
70	/// is the trap the ports alone do not close -- two suites appending to one file
71	/// make every `mockLog` assertion read another agent's traffic.
72	export const APP = process.env.DAIMOND_APP
73	\|\| `http://localhost:${process.env.DAIMOND_PORT \|\| 8777}`;
74	export const MOCK = process.env.DAIMOND_MOCK
75	\|\| `http://127.0.0.1:${process.env.DAIMOND_MOCK_PORT \|\| 9099}/v1/chat/completions`;
76	export const MODEL = 'mock/fast';
77	export const PASS = 'testpass1234';
78	export const CHROME = process.env.DAIMOND_CHROME
79	\|\| `${process.env.HOME}/.cache/ms-playwright/chromium-1229/chrome-linux64/chrome`;
80
81	const MOCK_LOG = process.env.DAIMOND_MOCK_LOG \|\| path.join(HERE, 'mockllm.log');
82
83	/// Scratch root for browser profiles and test artefacts.
84	///
85	/// NOT `/tmp`: that is a tmpfs, so anything left there is RAM, charged to the
86	/// cgroup of whichever agent ran the suite. tmpfs pages are shmem and cannot be
87	/// dropped under pressure -- only swapped -- so stale profiles silently consume
88	/// the agent fleet's whole swap budget and unrelated sessions are OOM-killed for
89	/// it. That has now happened three times (2026-07-24, 2026-07-27, 2026-07-28:
90	/// 803 profile dirs, 5.1 GB, five of six gigabytes of fleet swap). Disk is
91	/// where this belongs. Override with DAIMOND_SCRATCH.
92	export const SCRATCH = process.env.DAIMOND_SCRATCH
93	\|\| path.join(os.homedir(), '.cache/daimond');
94
95	/// A path under the scratch root, with its parent created.
96	export function scratch(...parts) {
97	const p = path.join(SCRATCH, ...parts);
98	fs.mkdirSync(path.dirname(p), { recursive: true });
99	return p;
100	}
101
102	/// The mock answering this world's port must be THIS world's mock.
103	///
104	/// `mockLog()` below is how eighteen or more verifiers ask what the model was
105	/// shown, and every one of them asks it by READING A FILE. So a mock that answers
106	/// the port while appending somewhere else does not break anything visibly: the
107	/// turns happen, the page behaves, and the assertions read an empty file and
108	/// report that the provider was never reached.
109	///
110	/// That is not a hypothetical. The gate of 2026-08-17 found world 9's ports
111	/// already held by a gate started three hours earlier, left them alone -- which is
112	/// `world.sh --up`'s deliberate and correct behaviour when a person is sharing a
113	/// world -- and ran for two hours against that mock, which was appending 2.6 MB
114	/// into a worktree of commit b536d60 while the log this run read stayed at zero
115	/// bytes. `verify_concise` reported "the mock provider was reached: no";
116	/// `verify_toolmemory` reported "two turns really reached the model — 0
117	/// request(s)"; `verify_triggers` reported that the daimon was never sent the
118	/// user's message. All three were false, and each was a claim about a feature made
119	/// by a check that had not been able to look.
120	///
121	/// So it is asked ONCE per process, here, rather than in eighteen copies: the mock
122	/// is made to name the file it writes, and a mock that names another one -- or
123	/// that cannot answer the question, which is what an older mockllm from another
124	/// tree does -- stops the run before a single check has been made.
125	///
126	/// AND IT IS ASKED WHICH REVISION IT IS, which is a different question from which
127	/// world it belongs to, and the two came apart on 2026-08-28. `world.sh --up`
128	/// adopts a mock already listening -- correctly, so a person can share a world --
129	/// and a world brought up BEFORE a merge keeps answering after it. Same port, same
130	/// log path, so every guard above passed; a directive the merge had added meant
131	/// nothing to it, so it fell through to `Mock reply to: <the directive line>`.
132	///
133	/// That is worse than a mock that is not there. `dev/verify_thinking.mjs` went red
134	/// on twelve checks, and one of them said the model's reasoning had been stored as
135	/// its answer -- the most serious thing this suite can report. It had not been. The
136	/// echo put the check's own markers into the assistant message, so a fixture
137	/// produced a data-defect report about a product that was working.
138	///
139	/// This is the workflow that manufactures it: bring a world up, run the gate, merge,
140	/// run the gate again. A release lane does exactly that, all day.
141
142	/// The SHA-256 of THIS tree's mock, or '' when it cannot be read.
143	///
144	/// Empty rather than fatal: running the harness from somewhere its mock's source is
145	/// not is a thing that works today, and this check must not be why it stops.
146	let _mockSha = null;
147	function mockSha() {
148	if (_mockSha === null) {
149	try {
150	_mockSha = crypto.createHash('sha256')
151	.update(fs.readFileSync(path.join(HERE, 'mockllm.mjs'))).digest('hex');
152	} catch (e) { _mockSha = ''; }
153	}
154	return _mockSha;
155	}
156
157	/// The directive names this tree's mock switches on, read the way the mock reads them
158	/// of itself, so the two lists cannot drift apart.
159	function ourDirectives() {
160	try {
161	const src = fs.readFileSync(path.join(HERE, 'mockllm.mjs'), 'utf8');
162	return [...new Set([...src.matchAll(/^\t\tcase '([a-z0-9]+)':/gm)].map(m => m[1]))].sort();
163	} catch (e) { return []; }
164	}
165
166	let mockIdentity = null;
167	async function requireOwnMock() {
168	if (mockIdentity) return mockIdentity;
169	const url = new URL('/__world', MOCK).href;
170	let said;
171	try {
172	const r = await fetch(url, { cache: 'no-store' });
173	said = r.ok ? await r.json() : { log: null, status: r.status };
174	} catch (e) {
175	// Nothing is listening. The verifier's own checks will say what it could
176	// not do, and this says why -- but it is not made fatal here, because a
177	// session opened with `connect: true` that never speaks to a model is a
178	// legitimate thing and was working before this check existed.
179	console.log(` note no mock provider answering ${MOCK} — anything below that reads`
180	+ ' mockLog() is reading a file nothing is writing');
181	mockIdentity = { log: null };
182	return mockIdentity;
183	}
184	// WHICH REVISION, asked before which world: a mock from another tree can name the
185	// right log by nothing but a shared directory layout, and then every answer it
186	// gives is a revision behind and nothing says so.
187	const ours = mockSha();
188	if (ours && said.sha !== ours) {
189	const knows = Array.isArray(said.directives);
190	const missing = knows ? ourDirectives().filter(d => !said.directives.includes(d)) : [];
191	// Three cases, and they are not the same diagnosis. It listed its directives and
192	// some are absent; it listed them and none are, so a directive's MEANING moved;
193	// or it is old enough not to list them at all, in which case nothing is known
194	// about what it understands and the sha is the whole of the evidence.
195	const what = !knows
196	? ' it does not say which directives it knows, so nothing can be said about\n'
197	+ ' what it understands -- only that it is not this file.\n'
198	: missing.length
199	? ` it does not answer to: ${missing.map(d => '@' + d).join(', ')}\n`
200	: ' it answers to the same directive names, so what differs is what they MEAN.\n';
201	throw new Error(
202	`the provider on ${MOCK} is not built from this tree's dev/mockllm.mjs.\n`
203	+ ` it is: ${said.sha \|\| '(no sha in its /__world — a mockllm from before this '
204	+ 'check existed)'}\n`
205	+ ` we want: ${ours}\n`
206	+ what
207	+ ' A world adopts a mock already listening, so one started before a merge keeps\n'
208	+ ' answering after it -- same port, same log, silently a revision behind. Each\n'
209	+ ' directive it does not know becomes `Mock reply to: <the line>`, which is the\n'
210	+ ' fixture echoing the prompt and reads exactly like the product being broken.\n'
211	+ ' Restart it: dev/world.sh N --down && dev/world.sh N --up');
212	}
213	if (said.log !== MOCK_LOG) {
214	throw new Error(
215	`the provider on ${MOCK} is not this world's.\n`
216	+ ` it logs to: ${said.log \|\| `(no /__world answer — status ${said.status}; an older `
217	+ 'mockllm.mjs from another tree, or not mockllm.mjs at all)'}\n`
218	+ ` this run reads: ${MOCK_LOG}\n`
219	+ ' Every check that asks what the model was sent reads THAT file, so this run\n'
220	+ ' would report turns as never having happened. Free the port, or pick another\n'
221	+ ' world (dev/world.sh N --status now says who holds one).');
222	}
223	mockIdentity = said;
224	return mockIdentity;
225	}
226
227	/// Everything the model was sent, since `clearMockLog()` was last called.
228	export const mockLog = () => {
229	if (!fs.existsSync(MOCK_LOG)) return [];
230	return fs.readFileSync(MOCK_LOG, 'utf8').split('\n')
231	.filter(Boolean).map(l => { try { return JSON.parse(l); } catch { return null; } })
232	.filter(Boolean);
233	};
234	export const clearMockLog = () => { try { fs.writeFileSync(MOCK_LOG, ''); } catch {} };
235
236	/// The text of a message's `content`, whichever shape it arrived in.
237	///
238	/// A message's content is a plain string in the simple case and an ARRAY OF
239	/// PARTS whenever the request carries anything else -- a cache marker, an image.
240	/// A check written as `/x/.test(m.content \|\| '')` sees `[object Object]` for the
241	/// second kind and quietly matches nothing.
242	///
243	/// That is not hypothetical: it is why `verify_credits` reported "0 copies of
244	/// the user message on the wire" and "0 worker request(s) landed" for weeks. The
245	/// wire was fine and the app was fine; the assertion was reading the message in
246	/// one shape and the app was sending it in the other. Use this rather than
247	/// touching `content` directly.
248	export const contentText = (content) => {
249	if (typeof content === 'string') return content;
250	if (Array.isArray(content)) {
251	return content.map((p) => (p && typeof p.text === 'string') ? p.text : '').join('');
252	}
253	return '';
254	};
255
256	/// Launch a browser, sign in, and connect the mock model.
257	///
258	/// `name` seeds a distinct identity so parallel sessions never share state;
259	/// each gets its own browser profile, so OPFS and localStorage are its own.
260	// Where a headed browser is allowed to paint lives in `dev/display.mjs`, which
261	// has no imports so that the twelve headed launchers in this directory which do
262	// NOT import this file can have it for nothing. Re-exported here because this is
263	// where it was, and `dev/verify_harness.mjs` puts the cases to it through this
264	// door.
265	//
266	// The import is what strips `WAYLAND_DISPLAY` and `XDG_SESSION_TYPE` from this
267	// process, so it is load-bearing even where nothing below names it.
268	export { displayFault, cleanDisplayEnv, WAYLAND_VARS, INHERITED_ENV,
269	UNATTENDED_VAR, OWNED_VAR, SEAT_DISPLAY } from './display.mjs';
270	import { displayFault, cleanDisplayEnv, INHERITED_ENV } from './display.mjs';
271
272	export async function open(opts = {}) {
273	const {
274	headed = false,
275	name = 'tester',
276	extension = null, // path to an unpacked extension, headed only
277	connect = true, // skip to test the disconnected state
278	signIn = true, // skip to test the gate itself
279	// The two default Diamonds the app seeds on a first boot. Pass false when
280	// the test COUNTS Diamonds, or pause leaves, and needs to own the set --
281	// see `clearDiamonds` below for why they are removed rather than skipped.
282	defaults = true,
283	// A fixed profile directory, so a run keeps the identity — and therefore the
284	// GATEWAY ACCOUNT — of the run before it. Without one, every run mints a new
285	// account, and nothing that needs an entitlement (mail, a pack) can be tested
286	// twice: the grant would land on an account the next run does not have.
287	profile = null,
288	// A TOUCH context: `pointer: coarse` and `any-pointer: coarse` in the media
289	// queries, which is what a tablet reports and what several of the app's
290	// touch-target rules are written against. Without it a 900px window is a
291	// mouse, and a rule that only lifts a control for a finger looks absent.
292	touch = false,
293	// Called with the page before it is navigated, for a verifier that serves
294	// a damaged file through `page.route`. It has to run BEFORE `goto`, which
295	// is the whole reason it cannot be done by the caller afterwards.
296	route = null,
297	// Let the transparency log be fetched from its real, foreign origin. See
298	// the route below for why the default is not to. Almost nothing wants this:
299	// what it buys is a dependency on GitHub's rate limiter.
300	publicLog = false,
301	} = opts;
302
303	// Before a browser is even launched: is the mock this run will read the mock
304	// this run will talk to? See `requireOwnMock` for the gate that made this
305	// necessary. Only when the session is going to be pointed at one.
306	if (connect) await requireOwnMock();
307
308	const args = ['--no-sandbox', '--disable-dev-shm-usage'];
309	if (extension) {
310	// `ext/` is the SHIPPED extension and names one origin, which is not this
311	// dev server. A test that asked for it wants the build that will talk to
312	// localhost, so it is handed the generated one -- see dev/extdev.mjs for
313	// why the dev origins are not in the file that ships.
314	const dir = isExtSource(extension) ? await extDev() : extension;
315	args.push(`--disable-extensions-except=${dir}`, `--load-extension=${dir}`);
316	}
317	if (!headed) args.push('--headless=new');
318
319	// A persistent context per session, on its own profile: OPFS, localStorage
320	// and identity are that session's alone, so sessions may run in parallel.
321	const profileDir = profile \|\| scratch('pw', `${name}-${process.pid}`);
322	fs.mkdirSync(profileDir, { recursive: true });
323	// DISPLAY is dropped for a headless run, and it is the reason half the
324	// clicks in this tree are forced.
325	//
326	// This session's DISPLAY is an X display forwarded over SSH to a laptop that
327	// is usually asleep. A headless Chrome still consults it, and when nothing
328	// answers the compositor never produces a frame -- so requestAnimationFrame
329	// never fires, Playwright's "stable" actionability check waits forever for a
330	// second frame, and every ordinary click times out on a button that is
331	// perfectly fine. Measured on a blank page: with DISPLAY set, no frames in
332	// either headless mode; with it unset, frames, clicks and screenshots all
333	// work.
334	//
335	// A HEADED RUN NEEDS A DISPLAY AND MUST NOT BE GIVEN THAT ONE. The sentence
336	// here used to read "a headed run genuinely needs the display, so it keeps
337	// it", and the display it kept was the forwarded one -- so a headed verifier
338	// started from an rc session PAINTED ITSELF ON THE OWNER'S LAPTOP, across the
339	// network, in front of whatever he was doing. He reported it happening more
340	// than once before anybody looked at this line.
341	//
342	// A forwarded display is decidable and is not guessed at: X names a remote
343	// display with a HOST PART before the colon (`localhost:10.0`, `gilgamesh:0`),
344	// and a local one has none (`:0`, and `:99` from `xvfb-run`). So a headed
345	// launch refuses a display carrying a host part rather than quietly using it.
346	// Watching a headed run on argonaut's own seat still works -- that is `:0`,
347	// which has no host part and is allowed.
348	// The Wayland variables go for a headless run as well as a headed one. A
349	// headless Chromium that finds a compositor still talks to it, and the frame
350	// stalls this comment is about are the same stalls in a different costume.
351	const env = cleanDisplayEnv(process.env);
352	if (!headed) {
353	delete env.DISPLAY;
354	} else {
355	// `INHERITED_ENV` and not `env`: the question is what this run was
356	// STARTED with, and both the strip above and the one at import time have
357	// taken the answer out of everything else.
358	const shown = displayFault(INHERITED_ENV);
359	if (shown) {
360	throw new Error(shown);
361	}
362	}
363
364	const browser = await chromium.launchPersistentContext(profileDir, {
365	executablePath: CHROME,
366	headless: false, // the flag above decides; MV3 needs a real browser
367	args,
368	env,
369	viewport: { width: 1500, height: 950 },
370	hasTouch: touch,
371	});
372
373	const page = browser.pages()[0] \|\| await browser.newPage();
374	const errs = [];
375	const logs = [];
376	// Every answer of 400 or worse, and every request that got no answer at all,
377	// WITH ITS URL.
378	//
379	// Chrome's console line for a failed subresource is `Failed to load resource:
380	// the server responded with a status of 429 ()` -- a status, no URL, no host.
381	// Twenty-three verifiers failed the 2026-08-17 gate on exactly that line and
382	// not one of them could say which server had answered it. A day went into
383	// attributing it to the gateway rate-limiting its own test suite; it was
384	// raw.githubusercontent.com refusing an unauthenticated scrape, which
385	// `verify_releases` -- the one file in the tree that happened to record URLs
386	// beside statuses -- had been printing in full the whole time. So the URL is
387	// kept here, once, for everybody, and `errors()` below puts the two back
388	// together.
389	const net = [];
390	page.on('response', (r) => {
391	if (r.status() >= 400) net.push({ status: r.status(), url: r.url() });
392	});
393	page.on('requestfailed', (r) => {
394	const f = r.failure();
395	net.push({ status: 0, url: r.url(), why: (f && f.errorText) \|\| 'no answer' });
396	});
397	page.on('console', m => {
398	logs.push(`${m.type()}: ${m.text()}`);
399	if (m.type() === 'error') errs.push(m.text());
400	});
401	page.on('pageerror', e => errs.push(`pageerror: ${e.message}`));
402	page.on('crash', () => errs.push('PAGE CRASHED'));
403
404	// CHATS EXPIRE ON THEIR OWN NOW, and almost every fixture in this suite
405	// seeds `updatedAt` at a date in the past — because it is testing an
406	// ordering, or a transcript, or a merge, and the stamp was only ever there
407	// to make the ordering deterministic. With the shipped three-day window
408	// those chats are all overdue, so twenty seconds into any run the app would
409	// correctly move the entire fixture to the trash and the verifier would fail
410	// on something it is not about.
411	//
412	// So the harness pins a long window for every run, into the same cached key
413	// the app reads (`daimond-policy`), before any script on the page has run. A
414	// verifier that IS about expiry sets its own figures at the moment it needs
415	// them — `DaimondPolicy.set` writes this key — so this is a default and not
416	// a gag.
417	//
418	// The retention is left at thirty days: nothing here depends on it, and a
419	// figure invented for the tests is a figure the tests would then be proving
420	// things about.
421	await page.addInitScript(() => {
422	try { localStorage.setItem('daimond-policy',
423	JSON.stringify({ v: 1, expire: 3650, retain: 30, high: 30 })); }
424	catch (e) { /* private mode: the shipped window stands */ }
425	});
426
427	// THE TRANSPARENCY LOG IS ON SOMEBODY ELSE'S SERVER, and that is the point of
428	// it: `js/verify.js` and `js/release.js` both read the published chain from
429	// raw.githubusercontent.com, an origin this project does not control, because a
430	// page that verified itself against a file it also served would prove nothing.
431	//
432	// A suite is a different matter. Two hundred and fifty verifiers, several page
433	// loads each, is a few hundred unauthenticated fetches of one file inside two
434	// hours, and GitHub answers that with 429 and a link to its scraping terms.
435	// That is what reddened twenty-three verifiers on 2026-08-17: not the app, not
436	// the gateway, a third party quite correctly declining to be scraped.
437	//
438	// So the log is served from the repo's own copy -- the same bytes GitHub would
439	// return for this commit, since that file is what gets pushed. Pass
440	// `{ publicLog: true }` for a run that genuinely means to ask the real origin.
441	// A verifier registering its own route after `open()` still wins: Playwright
442	// matches handlers in reverse order of registration, which is how
443	// dev/verify_delivery.mjs has served its own chain here since it was written.
444	if (!publicLog) {
445	const chain = path.join(HERE, '..', 'verify/transparency.jsonl');
446	// Missing (a worktree between seals, a fork): let the real origin answer and
447	// let `errors()` name it, rather than inventing an empty log for the page to
448	// draw conclusions from.
449	if (fs.existsSync(chain)) {
450	const body = fs.readFileSync(chain, 'utf8');
451	await page.route('https://raw.githubusercontent.com/**', r => r.fulfill({
452	status: 200,
453	contentType: 'text/plain',
454	headers: { 'access-control-allow-origin': '*' },
455	body,
456	}));
457	}
458	}
459
460	if (route) await route(page);
461	await page.goto(APP, { waitUntil: 'domcontentloaded' });
462
463	const s = { browser, page, errs, logs, net, name, foreign: [] };
464
465	if (signIn) await signInAs(s, name);
466	if (signIn && !defaults) await clearDiamonds(s);
467	if (signIn && connect) await connectMock(s);
468
469	s.close = async () => { await browser.close(); };
470	return s;
471	}
472
473	/// Empty the rail, for a test that owns the Diamond set.
474	///
475	/// A FRESH PROFILE IS NO LONGER EMPTY. The app seeds two default Diamonds on the
476	/// first boot of an account (`seedDefaultDiamonds`), which notes2 asks for: an
477	/// arriving user should not face a blank rail. A verifier that builds a fixture
478	/// and then COUNTS — the graph pane's stats line, the tag filter, the pause
479	/// parcel, "the rail did not gain a Diamond nothing lists" — was written when a
480	/// new account held nothing, and two it did not create read as a defect in
481	/// whatever it was measuring.
482	///
483	/// Deleting them AFTER the boot that made them is deliberate: the app records
484	/// that it has already offered them, so nothing offers again and the rail stays
485	/// empty for the rest of the run. Suppressing the seed instead would mean a flag
486	/// in shipped code that exists only for tests, and would have to be written into
487	/// the account's own localStorage namespace before a boot that has not happened.
488	///
489	/// The pause tree is cleared with them. The defaults are seeded PAUSED, at the
490	/// leaf, so their ids travel in the sync parcel and outlive the Diamonds that
491	/// named them.
492	export async function clearDiamonds(s) {
493	const { page } = s;
494	const gone = await page.evaluate(async () => {
495	const m = await import('/pkg/oxedyne_daimond.js');
496	const app = new m.DaimondApp('http://127.0.0.1/v1/chat/completions', '', 'none', 4096, '', true);
497	let list = [];
498	try { list = JSON.parse(await app.list_diamonds()); } catch (e) { return 0; }
499	for (const d of list) { try { await app.delete_diamond(d.id); } catch (e) { /* already gone */ } }
500	try { window.DaimondPause.forget('root'); } catch (e) { /* module not up */ }
501	return list.length;
502	});
503	if (!gone) return 0;
504	// Redrawn from the store the way a person would see it, rather than by poking
505	// the rail: a reload is the one path guaranteed to agree with what is on disk.
506	// It lands on the lock screen, hence the second sign-in.
507	await page.reload({ waitUntil: 'domcontentloaded' });
508	await signInAs(s, s.name);
509	return gone;
510	}
511
512	/// The chats as they are actually stored.
513	///
514	/// IndexedDB, not localStorage: transcripts moved there when a day of tool results
515	/// stopped fitting in the origin's five megabytes and `setItem` began throwing into
516	/// a swallowed catch. Read from outside the app, so what a test asserts on is what
517	/// is on disk rather than what the page believes it wrote.
518	export function storedChats(s) {
519	return s.page.evaluate(() => new Promise((res) => {
520	const req = indexedDB.open('daimond-chats', 1);
521	req.onsuccess = () => {
522	const db = req.result;
523	let t;
524	try { t = db.transaction('chats', 'readonly'); } catch (e) { res([]); return; }
525	const all = t.objectStore('chats').getAll();
526	all.onsuccess = () => res(all.result \|\| []);
527	all.onerror = () => res([]);
528	};
529	req.onerror = () => res([]);
530	}));
531	}
532
533	/// Empty the chat store, for a test that wants a clean rail.
534	///
535	/// Both places: the store itself, and the old localStorage key, which the app
536	/// migrates back in on the next boot if it is left sitting there.
537	export function clearChats(s) {
538	return s.page.evaluate(() => new Promise((res) => {
539	try {
540	localStorage.removeItem('daimond-chats');
541	localStorage.removeItem('daimond-chats-legacy');
542	} catch (e) { /* private mode, or full */ }
543	const req = indexedDB.open('daimond-chats', 1);
544	req.onsuccess = () => {
545	const db = req.result;
546	let t;
547	try { t = db.transaction('chats', 'readwrite'); } catch (e) { res(); return; }
548	t.objectStore('chats').clear();
549	t.oncomplete = () => res();
550	t.onerror = () => res();
551	};
552	req.onerror = () => res();
553	}));
554	}
555
556	/// Get past the passphrase gate, creating the identity on first run.
557	export async function signInAs(s, name) {
558	const { page } = s;
559	await page.waitForSelector('#id-primary', { timeout: 15000 });
560	// The name field is present in BOTH modes now — it doubles as the username a
561	// password manager files the entry under — but it is readonly when unlocking,
562	// where it names the account rather than choosing one. isEditable, not
563	// isVisible: fill() throws on a readonly input.
564	const nameBox = await page.$('#id-name');
565	if (nameBox && await nameBox.isVisible() && await nameBox.isEditable()) await nameBox.fill(name);
566	await page.fill('#id-pass', PASS);
567	const confirm = await page.$('#id-pass2');
568	if (confirm && await confirm.isVisible()) await confirm.fill(PASS); // first run only
569	// Creating an account now starts from a GENERATED passphrase, and the create
570	// button stays disabled until the user says they have written it down. The
571	// harness overwrites the generated phrase with its own fixed one (so a run can
572	// reproduce the account), then ticks the acknowledgement the same way a person
573	// would. Absent on the unlock screen, hence the visibility check.
574	const wrote = await page.$('#id-wrote');
575	if (wrote && await wrote.isVisible() && !(await wrote.isChecked())) {
576	await wrote.check({ force: true });
577	}
578	// A direct DOM click, not page.click: the modal's fade keeps failing
579	// Playwright's "stable" actionability check, so the normal click can hang
580	// on a button that is perfectly clickable. The gate has no interception to
581	// worry about (verified), so bypassing actionability is safe here.
582	await page.evaluate(() => document.getElementById('id-primary').click());
583	// The identity modal closes when it takes; if it does not, say why.
584	await page.waitForSelector('#identity-modal', { state: 'hidden', timeout: 15000 })
585	.catch(async () => {
586	const why = await page.evaluate(() =>
587	(document.getElementById('id-error') \|\| {}).textContent \|\| '(no message)');
588	throw new Error(`sign-in did not take: ${why}`);
589	});
590	await page.waitForTimeout(400);
591	}
592
593	/// Start a chat, which is what makes the composer appear.
594	///
595	/// A new chat is a pending tile: it carries a model and a Start button, and
596	/// becomes a live chat only when Start is pressed. The harness presses it.
597	/// Say something to the Diamond on screen, through the composer it now uses.
598	///
599	/// The crystal used to carry its own `#steer-input`, and every test typed into
600	/// that. It is gone: a Diamond's daimon is a persistent chat, so there is ONE
601	/// composer for it and it lives in the chat face. `sendUserMessage` routes a
602	/// Diamond's message to `doSteer`, so this is the same code path the steer box
603	/// drove -- only reached the way a person now reaches it.
604	///
605	/// Selects the chat face first, because the composer is not on screen while the
606	/// crystal face is up.
607	export async function steerDiamond(s, text) {
608	const p = s.page;
609	const chat = await p.$('#dview-chat');
610	if (chat) { await chat.click({ force: true }); await p.waitForTimeout(400); }
611	await p.waitForSelector('#chat-input', { timeout: 10000 });
612	await p.fill('#chat-input', text);
613	await p.click('#chat-send', { force: true });
614	}
615
616	/// Start a NEW chat, and answer with its id.
617	///
618	/// `{ reuse: true }` asks only that SOME chat be in focus, and is what `chat()`
619	/// wants: a message per chat is not what any test means by "say this".
620	///
621	/// THE DEFAULT REALLY MAKES ONE, and says so if it cannot. This used to return
622	/// early whenever a chat was already on screen, which is the same request read as
623	/// the weaker one -- and after a reload it is a different chat entirely, because
624	/// the app restores the one that was open. dev/verify_attachfocus.mjs asked for a
625	/// fresh chat after a reload, was handed back the PRE-RELOAD chat, and then
626	/// called `chatToggle` on an attachment that chat already held: a toggle, so the
627	/// check REMOVED the attachment and read zero rows. It reported
628	/// `{"icons":0,"rows":0,"name":""}` for five gates as a footer that would not
629	/// draw. A silent no-op is what let that stand; a caller that asks for a new chat
630	/// and is handed an old one now gets a throw with both ids in it.
631	export async function newChat(s, { reuse = false } = {}) {
632	const { page } = s;
633	/// The chat in focus, or '' when the focus is a Diamond or nothing.
634	const focusId = () => page.evaluate(() => {
635	try {
636	const f = window.DaimondAttach && window.DaimondAttach.focus();
637	return (f && f.kind === 'chat') ? String(f.id) : '';
638	} catch (e) { return ''; }
639	});
640	const before = await focusId();
641	// "A composer is on screen" is NOT "we are in a chat", and the difference
642	// arrived when a Diamond's crystal face gained the shared composer. Before
643	// that, a visible `#chat-input` could only mean a chat; now it also means a
644	// Diamond, whose composer talks to its daimon. Returning early there sent
645	// every `chat()` call to the daimon instead of to a chat -- silently, with
646	// the turns landing somewhere the test never looked.
647	//
648	// The face switch is the honest test: it is drawn for a Diamond and for
649	// nothing else.
650	const inChat = await page.evaluate(() => {
651	const ci = document.getElementById('chat-input');
652	const vis = e => !!e && !!(e.offsetWidth \|\| e.offsetHeight \|\| e.getClientRects().length);
653	const sw = document.getElementById('diamond-view');
654	return vis(ci) && !vis(sw);
655	});
656	if (inChat && reuse) return before;
657	// The Admin drawer opens over the rail on a not-connected profile
658	// ("Connect a model"), and since the rail gained its Diamonds/Chats
659	// divider the + button sits under it. A force-click dispatches at the
660	// button's coordinates, so the DRAWER receives it and nothing happens.
661	// Close it the way a user would before reaching for the rail.
662	const drawerClose = page.locator('#admin-close');
663	if (await drawerClose.isVisible().catch(() => false)) {
664	await drawerClose.click({ force: true });
665	await page.waitForTimeout(200);
666	}
667	// force:true throughout — a page animation keeps failing Playwright's
668	// "stable" actionability check, hanging otherwise-fine clicks.
669	await page.click('#new-session-btn', { force: true });
670	await page.waitForTimeout(500);
671	// `.tile-start` by class, NOT `button:has-text("Start")`: has-text is a
672	// case-insensitive SUBSTRING match, so it also matches the BYOK form's
673	// "Save & start" -- which sits earlier in the document, so `.first()`
674	// returned that hidden button and the click failed as "not visible" in any
675	// test whose settings form happened to be in the DOM.
676	const start = page.locator('.tile-start').first();
677	if (await start.count()) {
678	await start.click({ force: true });
679	}
680	await page.waitForSelector('#chat-input', { state: 'visible', timeout: 10000 });
681	await page.waitForTimeout(300);
682	const after = await focusId();
683	// Only when both ids are readable: with no `DaimondAttach` there is nothing to
684	// compare, and a harness that threw on that would be inventing a failure.
685	if (!reuse && before && after && before === after) {
686	throw new Error(`newChat: still in chat ${after} — no new chat was made. `
687	+ 'Pass { reuse: true } if any chat will do.');
688	}
689	return after;
690	}
691
692	/// Point the app at a provider through the real Settings form.
693	///
694	/// `apiKey` is a parameter because `dev/reflux.mjs` drives this whole stack against a
695	/// REAL provider, and a probe that had to edit this function to do it would be measuring
696	/// a build nobody ships. It defaults to the mock's sentinel, so every existing caller is
697	/// unchanged.
698	///
699	/// **Nothing here ever reads a credential from a file, and none is written down in this
700	/// tree.** What a caller passes is whatever it holds; `reflux.mjs` passes a per-run token
701	/// its own relay mints, so the provider key never enters the page's storage at all.
702	export async function connectMock(s, { baseUrl = MOCK, model = MODEL, apiKey = 'mock-key' } = {}) {
703	const { page } = s;
704	// THE OTHER DOOR ONTO A MOCK, and until 2026-08-28 the guard was only on the first
705	// one. `open()` asks `requireOwnMock` when it is told `connect: true` -- and 142 of
706	// the 305 verifiers pass `connect: false` and reach a provider through here instead,
707	// which is the ordinary pattern rather than an unusual one. So the check written
708	// after the 2026-08-17 incident could not see the majority of the runs it was
709	// written for, and `dev/verify_thinking.mjs` met the 2026-08-28 one with nothing
710	// between it and a stale mock. Asked at whichever door is used.
711	//
712	// Only for THIS WORLD'S mock. This function is also how a probe points the app at a
713	// real provider (`dev/probe_thinking_live.mjs` hands it an OpenRouter URL), and
714	// openrouter.ai is quite properly not built from dev/mockllm.mjs.
715	if (baseUrl === MOCK) await requireOwnMock();
716	await page.evaluate(async ({ baseUrl, model, apiKey }) => {
717	// Drive the form the user drives, so its own save path is exercised.
718	const open = document.getElementById('settings-btn')
719	\|\| document.querySelector('[data-admin="settings"]')
720	\|\| document.querySelector('#admin-settings-btn');
721	if (open) open.click();
722	await new Promise(r => setTimeout(r, 200));
723	const prov = document.getElementById('cfg-provider');
724	if (prov) {
725	prov.value = 'custom';
726	prov.dispatchEvent(new Event('change', { bubbles: true }));
727	}
728	await new Promise(r => setTimeout(r, 200));
729	const url = document.getElementById('cfg-base-url');
730	if (url) {
731	url.value = baseUrl;
732	url.dispatchEvent(new Event('input', { bubbles: true }));
733	url.dispatchEvent(new Event('change', { bubbles: true }));
734	}
735	const key = document.getElementById('cfg-api-key');
736	if (key) {
737	key.value = apiKey;
738	key.dispatchEvent(new Event('input', { bubbles: true }));
739	key.dispatchEvent(new Event('change', { bubbles: true }));
740	}
741	await new Promise(r => setTimeout(r, 600)); // the model list is fetched
742	const sel = document.getElementById('cfg-model');
743	const cus = document.getElementById('cfg-model-custom');
744	if (sel && [...sel.options].some(o => o.value === model)) {
745	sel.value = model;
746	sel.dispatchEvent(new Event('change', { bubbles: true }));
747	} else if (cus) {
748	cus.style.display = '';
749	cus.value = model;
750	cus.dispatchEvent(new Event('input', { bubbles: true }));
751	cus.dispatchEvent(new Event('change', { bubbles: true }));
752	}
753	const save = document.getElementById('byok-save');
754	if (save) save.click();
755	}, { baseUrl, model, apiKey });
756	await s.page.waitForTimeout(1200);
757
758	// Whatever the form did, the app is only connected if it says it is.
759	//
760	// READ FROM `daimond-models-v2`, WHICH IS WHERE THE APP KEEPS IT. This asked
761	// `daimond-byok` -- the single-provider config that key replaced -- so from the
762	// day the provider list landed it answered `null` for every connection that had
763	// in fact worked perfectly. Nothing caught it because `open()` throws the value
764	// away, and it was found by the first caller that read it: `dev/reflux.mjs`
765	// refused to spend against a relay the app had plainly taken. The old key is
766	// still read, for a profile written before the migration.
767	const ready = await s.page.evaluate(() => {
768	try {
769	const raw = localStorage.getItem('daimond-models-v2');
770	if (raw) {
771	const j = JSON.parse(raw);
772	const id = (j.def \|\| {}).provider;
773	const p = ((j.providers \|\| {})[id]) \|\| {};
774	if (!id) return null;
775	return { baseUrl: p.url \|\| '', model: (j.def \|\| {}).model \|\| '',
776	hasKey: !!(p.key \|\| p.keyEnc) };
777	}
778	const old = localStorage.getItem('daimond-byok');
779	if (!old) return null;
780	const j = JSON.parse(old);
781	return { baseUrl: j.baseUrl, model: j.model, hasKey: !!(j.apiKey \|\| j.apiKeyEnc) };
782	} catch { return null; }
783	});
784	s.cfg = ready;
785	return ready;
786	}
787
788	/// Connect a real provider (from dev/.secrets/testcfg.json) through the real
789	/// Settings form. `tier` selects value\|mid\|power. Returns the saved cfg.
790	export async function connectReal(s, tier = 'value') {
791	const cfg = JSON.parse(fs.readFileSync(path.join(HERE, '.secrets/testcfg.json'), 'utf8'));
792	const model = cfg.models[tier] \|\| cfg.models.value;
793	await s.page.evaluate(async (c) => {
794	document.getElementById('settings-btn')?.click();
795	await new Promise(r => setTimeout(r, 250));
796	const prov = document.getElementById('cfg-provider');
797	prov.value = 'custom'; prov.dispatchEvent(new Event('change', { bubbles: true }));
798	await new Promise(r => setTimeout(r, 200));
799	const url = document.getElementById('cfg-base-url');
800	url.value = c.baseUrl; url.dispatchEvent(new Event('input', { bubbles: true })); url.dispatchEvent(new Event('change', { bubbles: true }));
801	const key = document.getElementById('cfg-api-key');
802	key.value = c.apiKey; key.dispatchEvent(new Event('input', { bubbles: true })); key.dispatchEvent(new Event('change', { bubbles: true }));
803	await new Promise(r => setTimeout(r, 1500));
804	const cus = document.getElementById('cfg-model-custom');
805	if (cus) { cus.style.display = ''; cus.value = c.model; cus.dispatchEvent(new Event('input', { bubbles: true })); }
806	const sel = document.getElementById('cfg-model');
807	if (sel && [...sel.options].some(o => o.value === c.model)) { sel.value = c.model; sel.dispatchEvent(new Event('change', { bubbles: true })); }
808	document.getElementById('byok-save')?.click();
809	}, { baseUrl: cfg.baseUrl, apiKey: cfg.apiKey, model });
810	await s.page.waitForTimeout(1500);
811	s.model = model;
812	return model;
813	}
814
815	/// Cumulative USD spend recorded in the client ledger for this session.
816	export function spend(s) {
817	return s.page.evaluate(() => {
818	try { return JSON.parse(localStorage.getItem('daimond-ledger') \|\| '[]').reduce((a, e) => a + (e.u \|\| 0), 0); }
819	catch { return 0; }
820	});
821	}
822
823	/// Send a message and wait for the turn to finish.
824	///
825	/// "Finished" means the send button is offering Send again, not Stop — the
826	/// only signal the UI itself trusts.
827	export async function chat(s, text, { timeout = 30000 } = {}) {
828	const { page } = s;
829	// `reuse`: a conversation is several messages in ONE chat. Only a caller who
830	// asks for `newChat` itself is asking for a new one.
831	await newChat(s, { reuse: true });
832	await page.fill('#chat-input', text);
833	await page.click('#chat-send', { force: true });
834	await page.waitForTimeout(300);
835	const t0 = Date.now();
836	while (Date.now() - t0 < timeout) {
837	const busy = await page.evaluate(() => {
838	const b = document.getElementById('chat-send');
839	if (!b) return false;
840	const t = (b.getAttribute('title') \|\| '') + (b.className \|\| '');
841	return /stop/i.test(t) \|\| b.disabled;
842	});
843	if (!busy) break;
844	await page.waitForTimeout(250);
845	}
846	await page.waitForTimeout(400);
847	return transcript(s);
848	}
849
850	/// The visible conversation, as text.
851	export async function transcript(s) {
852	return s.page.evaluate(() => {
853	const out = document.getElementById('chat-output');
854	return out ? out.innerText : '';
855	});
856	}
857
858	/// A screenshot, kept in dev/shots.
859	export async function shot(s, label) {
860	fs.mkdirSync(SHOTS, { recursive: true });
861	const p = path.join(SHOTS, `${label}.png`);
862	// Non-fatal and time-boxed: a headless render can hang on a live animation,
863	// and a missing screenshot must never fail a test that otherwise passed.
864	await s.page.screenshot({ path: p, fullPage: false, timeout: 8000 }).catch(() => {});
865	return p;
866	}
867
868	/// Is this URL somewhere outside the world under test?
869	///
870	/// A world is the dev server, the mock provider, the gateway and anything else
871	/// answering on loopback. Everything on any other host is a third party, and a
872	/// third party's refusal is a fact about the internet, not about the product.
873	function foreign(url) {
874	if (!url) return false;
875	let h;
876	try { h = new URL(url).hostname; } catch (e) { return false; }
877	return !(h === 'localhost' \|\| h === '127.0.0.1' \|\| h === '::1' \|\| h === '[::1]');
878	}
879
880	/// Put a console error back together with the URL that caused it.
881	///
882	/// Chrome prints the status and drops the URL, so the pairing has to be made from
883	/// the response log kept in `open()`. Matched by status and CONSUMED: two 429s in
884	/// one run are two different requests, and blaming both on the first would put a
885	/// name to something that was never asked.
886	///
887	/// Anything else -- a `net::ERR_*`, a `pageerror` -- already carries its own URL
888	/// where it has one, so it is only read for the origin.
889	function attribute(msg, pending) {
890	const m = /status of (\d{3})/.exec(msg);
891	if (m) {
892	const i = pending.findIndex(n => n.status === Number(m[1]));
893	if (i < 0) return { text: msg, url: '' };
894	const n = pending.splice(i, 1)[0];
895	return { text: `${msg} ${n.url}`, url: n.url };
896	}
897	const u = /(https?:\/\/[^\s'"]+)/.exec(msg);
898	return { text: msg, url: u ? u[1] : '' };
899	}
900
901	/// Console errors seen so far, minus the noise a dev server always makes.
902	///
903	/// TWO THINGS HAPPEN HERE that did not before the 2026-08-17 gate.
904	///
905	/// Each "Failed to load resource" is given the URL that caused it, so a red is
906	/// actionable on sight. Twenty-three verifiers reported `a status of 429 ()` that
907	/// day and no reader of any of those logs could say which server had answered.
908	///
909	/// And a failure from a host OUTSIDE THIS WORLD is not returned, because every
910	/// caller of this function is asking "did the product throw" and a third party
911	/// declining to serve us is not the product. It is not swallowed: it goes to
912	/// `s.foreign` and is PRINTED, once each, so a run can never be quietly excused by
913	/// a filter. A verifier that means to assert on one reads `s.foreign` itself.
914	export function errors(s) {
915	const skip = [/favicon/i, /net::ERR_ABORTED.*hot/i];
916	const pending = (s.net \|\| []).slice();
917	if (!s.foreign) s.foreign = []; // a session this module did not build
918	const out = [];
919	for (const e of s.errs) {
920	if (skip.some(r => r.test(e))) continue;
921	const a = attribute(e, pending);
922	if (!foreign(a.url)) { out.push(a.text); continue; }
923	if (s.foreign.indexOf(a.text) >= 0) continue;
924	s.foreign.push(a.text);
925	console.log(` note outside this world, so not counted as the app throwing: ${a.text}`);
926	}
927	return out;
928	}