@wenathlan/forge 2.0.94 → 2.0.117

package/package.json

@@ -1,9 +1,12 @@
 {
   "name": "@wenathlan/forge",
-  "version": "2.0.94",
+  "version": "2.0.117",
   "description": "forge is the sandbox runner surface of the wenathlan family: it runs the sandbox runners on the saddle engine boundary and ships the documentation set and the tests directory as one package",
   "type": "module",
-  "private": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wenathlan/devthink"
+  },
   "license": "GPL-3.0-only",
   "author": "Wenathlan",
   "sideEffects": false,
@@ -12,7 +15,12 @@
     "build": "vite build",
     "start": "vite preview --host",
     "preview": "vite preview --host",
-    "check": "tsc --noEmit"
+    "check": "tsc --noEmit",
+    "typecheck": "tsc --noEmit",
+    "test": "node --test \"tests/*.test.ts\"",
+    "test:watch": "node --test --watch \"tests/*.test.ts\"",
+    "lint": "biome check .",
+    "restore:entry": "node -e \"const{readFileSync}=require('node:fs');const{execSync}=require('node:child_process');const script=/script[^>]*App\\.tsx/;const triad=/family=Bricolage\\+Grotesque[\\s\\S]*Outfit[\\s\\S]*JetBrains\\+Mono/;const face=(h)=>script.test(h)&&triad.test(h);if(face(readFileSync('index.html','utf8'))){console.log('index.html already rides the source face');process.exit(0)}if(!face(execSync('git show HEAD:./index.html',{encoding:'utf8'}))){console.error('refusing: HEAD index.html is not the canonical source face yet (script App.tsx + the font triad) - land the source-face fix first; nothing was touched');process.exit(1)}execSync('git checkout -- index.html',{stdio:'inherit'});console.log('index.html restored from HEAD (the source face)')\""
   },
   "dependencies": {
     "@hono/node-server": "^2.1.3",
@@ -35,7 +43,22 @@
     "LICENSE"
   ],
   "engines": {
-    "node": ">=26.8.1 <27"
+    "bare": "^1.18.0",
+    "bun": "^1.4.2",
+    "chrome": "^16.0.912",
+    "cnpm": "^9.4.0",
+    "corepack": "^0.35.0",
+    "deno": "^2.9.5",
+    "ecmascript": "^5.0.0",
+    "firefox": ">=0.8.0",
+    "iojs": "^1.0.0",
+    "node": "^26.8.2",
+    "npm": "^12.1.0",
+    "pnpm": "^12.6.0",
+    "teleport": ">=0.2.0",
+    "typescript": "^5.8.0",
+    "vscode": "^1.118.0",
+    "yarn": "^4.17.1"
   },
   "publishConfig": {
     "access": "public"
@@ -46,6 +69,7 @@
     "@capacitor/cli": "^8.5.2",
     "@capacitor/core": "^8.5.2",
     "@capacitor/ios": "^8.5.2",
+    "@fluentui/react-icons": "^2.0.344",
     "@hookform/resolvers": "^5.9.1",
     "@libsql/client": "^0.18.0",
     "@opencode-ai/sdk": "^1.18.34",
@@ -144,6 +168,9 @@
       "mysql2": "^3.23.1",
       "uuid": "^11.1.1",
       "postcss-selector-parser": "^7.1.6"
-    }
+    },
+    "neverBuiltDependencies": [
+      "ssh2"
+    ]
   }
 }

package/tests/design.test.ts

@@ -0,0 +1,182 @@
+// # design.test — the design contract of the forge surface, runnable with
+// the node built-in runner (no dependencies, no install):
+//   node --test tests/design.test.ts
+// The file reads the shipped sources (css, entry face, brand mark, app
+// identity, route anchor, flow sources) and pins the family laws of the
+// reform wave: the trylle foundation (canvas, surfaces, Inter + Geist Mono),
+// the windows hands (accent, close red, no pill, no all-properties
+// transition, no zero-scale entry outside the dtPopIntro bounce), the
+// source-face entry, the reduced-motion stop, tabular numerals, the honest
+// page set and the first-run flow contract (the entry gate, the shared
+// onboarding state, the db mirror).
+import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { describe, it } from "node:test";
+
+function read(path: string): string {
+  return readFileSync(new URL(path, import.meta.url), "utf8");
+}
+
+const CSS = read("../Sol/sol.css");
+const ENTRY = read("../index.html");
+const MARK = read("../Sol/shell/BrandMark.tsx");
+const TOML = read("../devthink.toml");
+const SOL = read("../Sol/Sol.tsx");
+const GATE = read("../Sol/home/entrygate.tsx");
+const STATE = read("../onboardingstate.ts");
+const ONBOARDING = read("../Sol/onboarding/onboarding.tsx");
+const INTRO = read("../Sol/intro/intro.tsx");
+const SHELL = read("../Sol/shell/Shell.tsx");
+const PRISMA = read("../schema.prisma");
+const DB = read("../db.ts");
+
+const BANNED = [/3b82f6/i, /2563eb/i, /f97316/i, /f59e0b/i];
+
+describe("design contract", () => {
+  it("ships no banned hue in the stylesheet, the entry or the mark", () => {
+    for (const source of [CSS, ENTRY, MARK]) {
+      for (const banned of BANNED) {
+        assert.ok(!banned.test(source), `banned hue ${banned} found`);
+      }
+    }
+  });
+
+  it("builds on the trylle foundation (canvas, deep floor, ink)", () => {
+    assert.match(CSS, /--sol-canvas: #0a0a0b/);
+    assert.match(CSS, /--sol-canvas-deep: #060607/);
+    assert.match(CSS, /--sol-ink: #fafafa/);
+    assert.match(CSS, /--sol-surface-1: #171717/);
+    assert.match(CSS, /--sol-surface-8: #484848/);
+  });
+
+  it("carries the forge lime #a2cb3a as the one identity signal (brand, CTAs, active ladder)", () => {
+    assert.match(CSS, /--fg-lime: #a2cb3a/);
+    assert.match(CSS, /--sol-primary: #a2cb3a/);
+    assert.match(MARK, /#a2cb3a/);
+  });
+
+  it("rides the windows accent #4cc2ff for focus (the win10 #0067c0 in the light face)", () => {
+    assert.match(CSS, /--win-accent: #4cc2ff/);
+    assert.match(CSS, /--win-accent: #0067c0/);
+    assert.match(CSS, /--sol-focus: var\(--win-accent\)/);
+    const dark = CSS.indexOf("--win-accent: #4cc2ff");
+    const light = CSS.indexOf("--win-accent: #0067c0");
+    assert.ok(light > dark, "the light accent must be restated after the dark one");
+  });
+
+  it("keeps the pill out of the stylesheet (no 999px, no stadium radius)", () => {
+    assert.ok(!CSS.includes("999px"), "the pill radius is retired");
+    assert.ok(!CSS.includes("--r-pill"), "no pill token survives");
+  });
+
+  it("never ships transition: all", () => {
+    assert.ok(!/transition:\s*all/.test(CSS), "transition: all is a reprovação");
+  });
+
+  it("never enters an element from zero scale (the windows dtPopIntro bounce excepted)", () => {
+    const sansPopIntro = CSS.replace(/@keyframes dtPopIntro \{[\s\S]*?\n\}/g, "");
+    assert.ok(
+      !/scale\(0\)/.test(sansPopIntro),
+      "scale(0) entries are a reprovação (the dtPopIntro bounce of the windows recipe excepted)",
+    );
+  });
+
+  it("declares the trylle font stacks (Inter reading, Geist Mono detail)", () => {
+    assert.match(CSS, /--font-sans: "Inter Variable"/);
+    assert.match(CSS, /--font-mono: "Geist Mono Variable"/);
+    assert.match(ENTRY, /family=Inter/);
+    assert.match(ENTRY, /Geist\+Mono/);
+  });
+
+  it("keeps the entry on the source face (./App.tsx, canonical assets, no hashed ghosts)", () => {
+    assert.match(ENTRY, /script[^>]*\.\/App\.tsx/);
+    assert.ok(!/-[0-9a-f]{8}\.(js|css)/.test(ENTRY), "no hashed bundle rides the entry");
+    assert.match(ENTRY, /href="\.\/favicon\.svg"/);
+  });
+
+  it("guards the reduced-motion stop on every layer, the hard stop last", () => {
+    const blocks = CSS.match(/@media \(prefers-reduced-motion: reduce\)/g) ?? [];
+    assert.ok(blocks.length >= 4, `expected the hard stop on every layer, found ${blocks.length}`);
+    const hardStop = CSS.indexOf("animation-duration: 0.01ms !important");
+    assert.ok(hardStop > 0, "the .01ms hard stop must exist");
+    assert.ok(/@media \(prefers-reduced-motion: reduce\)[\s\S]*$/.test(CSS), "the guards close the file");
+    const lastGuard = CSS.lastIndexOf("@media (prefers-reduced-motion: reduce)");
+    assert.ok(CSS.indexOf("animation-duration: 0.01ms", lastGuard) > lastGuard, "the hard stop is the last word");
+  });
+
+  it("floors the acrylics on reduced transparency (the window values)", () => {
+    assert.match(CSS, /@media \(prefers-reduced-transparency: reduce\)/);
+    assert.match(CSS, /background-color: #202020/);
+    assert.match(CSS, /background-color: #2b2b2b/);
+    assert.match(CSS, /background-color: #2c2c2c/);
+  });
+
+  it("keeps tabular numerals on the platform numbers", () => {
+    assert.match(CSS, /font-variant-numeric:\s*tabular-nums/);
+  });
+
+  it("rests the title-bar mark on the landing (logo discipline)", () => {
+    assert.match(CSS, /data-landing/);
+  });
+
+  it("wears the windows hands (press scale .7, dtPopIntro, the state ladder, the red close)", () => {
+    assert.match(CSS, /@keyframes dtPopIntro/);
+    assert.match(CSS, /transform: scale\(0\.7\)/);
+    assert.match(CSS, /--win-close: rgb\(232, 17, 35\)/);
+    assert.match(CSS, /--win-close-hot: rgb\(139, 10, 20\)/);
+    assert.match(CSS, /grayscale\(80%\)/);
+  });
+
+  it("declares the honest page set (home, runs, queue, logs, notfound)", () => {
+    assert.match(TOML, /pages = \["home", "runs", "queue", "logs", "notfound"\]/);
+    for (const route of ['"/runs"', '"/queue"', '"/logs"', '"/404"']) {
+      assert.ok(SOL.includes(`path=${route}`), `route ${route} must mount`);
+    }
+  });
+
+  it("keeps the entry flow mounted (intro, onboarding) before the gated fundamentals", () => {
+    assert.match(SOL, /path="\/intro"/);
+    assert.match(SOL, /path="\/onboarding"/);
+    assert.ok(SOL.indexOf('"/intro"') < SOL.indexOf('"/"'), "the intro route precedes the home route");
+    assert.match(SOL, /EntryGate/);
+  });
+
+  it("carries the flow contract sources (the gate beside the home anchor, the shared state module)", () => {
+    assert.match(GATE, /navigate\("\/intro", \{ replace: true \}\)/);
+    assert.match(GATE, /navigate\("\/onboarding", \{ replace: true \}\)/);
+    assert.match(GATE, /loadOnboardingState/);
+    assert.match(STATE, /forge\.onboarding\.seen/);
+    assert.match(STATE, /\/api\/v1\/onboarding/);
+    assert.match(STATE, /VITE_ONBOARDING_URL/);
+    assert.match(INTRO, /markIntroSeen/);
+    assert.match(ONBOARDING, /markOnboardingSeen/);
+    assert.ok(!INTRO.includes("sessionStorage"), "the sessionStorage-only flag is retired");
+  });
+
+  it("hands the intro directly to the onboarding (the auto-advance)", () => {
+    assert.match(INTRO, /navigate\("\/onboarding"\)/);
+  });
+
+  it("marks the onboarding stage on finish and skip alike", () => {
+    const finishes = ONBOARDING.match(/markOnboardingSeen/g) ?? [];
+    assert.ok(finishes.length >= 2, "finish and skip both write the stage");
+    assert.match(ONBOARDING, /navigate\("\/"\)/);
+  });
+
+  it("catalogues the first-run state in the db layer (prisma model + sqlite mirror)", () => {
+    assert.match(PRISMA, /model OnboardingState \{/);
+    assert.match(PRISMA, /introseen\s+Boolean\s+@default\(false\)/);
+    assert.match(PRISMA, /onboardingseen\s+Boolean\s+@default\(false\)/);
+    assert.match(DB, /CREATE TABLE IF NOT EXISTS onboarding_state/);
+    assert.match(DB, /getonboardingstate/);
+    assert.match(DB, /setonboardingstage/);
+    assert.match(DB, /MAX\(introseen, excluded\.introseen\)/, "the upsert is seen-wins");
+  });
+
+  it("reforms the navigation to the 48px pin rail with the windows hands", () => {
+    assert.match(CSS, /--win-rail-w: 48px/);
+    assert.match(SHELL, /data-tip=\{app\.label\}/);
+    assert.match(SHELL, /data-dir="se"/, "the eight resize handles ride the frame");
+    assert.match(SHELL, /setPointerCapture/);
+  });
+});

package/tests/family.test.ts

@@ -0,0 +1,105 @@
+// # family.test — the family table the chrome rides, runnable with the node
+// built-in runner (no dependencies, no install):
+//   node --test tests/family.test.ts
+// Every test watches the promise the row makes: the nine siblings beside
+// forge are listed once, every slug resolves through the familyurl contract
+// into a climb-one-level url, every member carries the spec §12 accent with
+// its own dot ink, and no accent ever collides with the banned palette.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { FAMILY_ACCENTS, FAMILY_SLUGS, familyAccentOf, familyrow } from "../family.ts";
+import { familyurl } from "../familyurl.ts";
+
+const BANNED = new Set(["#3b82f6", "#2563eb", "#f97316"]);
+
+describe("family table", () => {
+  it("lists the nine siblings beside forge, never forge itself", () => {
+    assert.deepEqual(FAMILY_SLUGS, [
+      "devthink",
+      "cadria",
+      "stealthhead",
+      "debonair",
+      "argan",
+      "saddle",
+      "foundry",
+      "vault",
+      "getry",
+    ]);
+    assert.ok(!FAMILY_SLUGS.includes("forge"));
+  });
+
+  it("answers an accent for every listed sibling", () => {
+    for (const slug of FAMILY_SLUGS) {
+      const member = FAMILY_ACCENTS[slug];
+      assert.ok(member, `${slug} must carry an accent`);
+      assert.equal(member.slug, slug);
+      assert.match(member.accent, /^#[0-9a-fA-F]{6}$/);
+      assert.match(member.dotInk, /^#[0-9a-fA-F]{6}$/);
+    }
+    // the table holds exactly the ten deploy units — no orphan accents
+    assert.deepEqual(Object.keys(FAMILY_ACCENTS).sort(), [
+      "argan",
+      "cadria",
+      "debonair",
+      "devthink",
+      "forge",
+      "foundry",
+      "getry",
+      "saddle",
+      "stealthhead",
+      "vault",
+    ]);
+  });
+
+  it("keeps the spec §12 accents stable, verbatim", () => {
+    assert.equal(FAMILY_ACCENTS.devthink.accent, "#F59E0B");
+    assert.equal(FAMILY_ACCENTS.argan.accent, "#34d8a8");
+    assert.equal(FAMILY_ACCENTS.cadria.accent, "#f472b6");
+    assert.equal(FAMILY_ACCENTS.debonair.accent, "#d9962e");
+    assert.equal(FAMILY_ACCENTS.forge.accent, "#a2cb3a");
+    assert.equal(FAMILY_ACCENTS.foundry.accent, "#2fb8b5");
+    assert.equal(FAMILY_ACCENTS.getry.accent, "#8b5cf6");
+    assert.equal(FAMILY_ACCENTS.saddle.accent, "#e86f2d");
+    assert.equal(FAMILY_ACCENTS.stealthhead.accent, "#e8563f");
+    assert.equal(FAMILY_ACCENTS.vault.accent, "#a3d7e6");
+  });
+
+  it("keeps the spec accent-ink column stable", () => {
+    assert.equal(FAMILY_ACCENTS.forge.dotInk, "#161d03");
+    assert.equal(FAMILY_ACCENTS.foundry.dotInk, "#03211f");
+    assert.equal(FAMILY_ACCENTS.vault.dotInk, "#072330");
+  });
+
+  it("resolves every member through the familyurl contract", () => {
+    for (const slug of FAMILY_SLUGS) {
+      assert.equal(familyurl(slug), `../${slug}/`);
+    }
+  });
+
+  it("never ships a banned hue in the row or the table", () => {
+    for (const member of [...familyrow(), ...Object.values(FAMILY_ACCENTS)]) {
+      assert.ok(!BANNED.has(member.accent.toLowerCase()), `${member.slug} rides a banned accent`);
+    }
+  });
+
+  it("builds the rail row in slug order without gaps", () => {
+    const row = familyrow();
+    assert.equal(row.length, FAMILY_SLUGS.length);
+    assert.deepEqual(
+      row.map((member) => member.slug),
+      [...FAMILY_SLUGS],
+    );
+  });
+
+  it("answers familyAccentOf for the house and falls back for unknowns", () => {
+    assert.equal(familyAccentOf("forge")?.accent, "#a2cb3a");
+    assert.equal(familyAccentOf("vault")?.accent, "#a3d7e6");
+    assert.equal(familyAccentOf("nope"), undefined);
+  });
+
+  it("keeps the familyurl contract on the climb-one-level shape", () => {
+    assert.equal(familyurl("cadria"), "../cadria/");
+    assert.equal(familyurl("/cadria/"), "../cadria/");
+    assert.equal(familyurl("cadria"), familyurl("  cadria ".trim()));
+  });
+});

package/tests/fleet.test.ts

@@ -0,0 +1,209 @@
+// # fleet.test — the runner fleet engine of the /runs page, runnable with
+// the node built-in runner (no dependencies, no install):
+//   node --test tests/fleet.test.ts
+// The fleet is a seeded rehearsal: the same seed musters the same runners,
+// the health ladder is pure thresholds, the tick advances the floor
+// deterministically and never heals an offline runner by hiding its record.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  fleetSummary,
+  fleetTick,
+  HEALTH_LADDER,
+  healthRungOf,
+  mulberry32,
+  pickRunner,
+  RUNNER_MODES,
+  RUNNER_STATES,
+  type Runner,
+  seedFleet,
+} from "../fleet.ts";
+
+/** one hand-built runner for the threshold tests */
+function runnerOf(patch: Partial<Runner>): Runner {
+  return {
+    id: "fgr-test-01",
+    name: "runner-test-01",
+    mode: "runner",
+    state: "busy",
+    load: 0.4,
+    runs: 100,
+    failures: 0,
+    ...patch,
+  };
+}
+
+describe("seeded fleet", () => {
+  it("musters the same runners from the same seed, every time", () => {
+    const a = seedFleet(20260214, 8);
+    const b = seedFleet(20260214, 8);
+    assert.deepEqual(a, b);
+  });
+
+  it("musters a fleet of the requested size with unique ids and names", () => {
+    const fleet = seedFleet(7, 12);
+    assert.equal(fleet.length, 12);
+    assert.equal(new Set(fleet.map((r) => r.id)).size, 12);
+    assert.equal(new Set(fleet.map((r) => r.name)).size, 12);
+  });
+
+  it("answers only real states, modes and load ranges", () => {
+    for (const runner of seedFleet(99, 40)) {
+      assert.ok(RUNNER_STATES.includes(runner.state), `state ${runner.state} is on the ladder`);
+      assert.ok(RUNNER_MODES.includes(runner.mode), `mode ${runner.mode} is a saddle mode`);
+      assert.ok(runner.load >= 0 && runner.load <= 1, `load ${runner.load} rides 0..1`);
+      assert.ok(runner.runs >= 0 && runner.failures >= 0);
+      assert.ok(runner.failures <= runner.runs, "failures never exceed runs");
+    }
+  });
+
+  it("keeps offline runners honest: no load, no fresh runs", () => {
+    const fleet = seedFleet(1234, 60);
+    for (const runner of fleet.filter((r) => r.state === "offline")) {
+      assert.equal(runner.failures, 0);
+    }
+  });
+});
+
+describe("prng", () => {
+  it("mulberry32 is deterministic across calls", () => {
+    const a = mulberry32(42);
+    const b = mulberry32(42);
+    for (let i = 0; i < 16; i++) assert.equal(a(), b());
+  });
+});
+
+describe("health ladder", () => {
+  it("is the three-rung ladder green → amber → red", () => {
+    assert.deepEqual(HEALTH_LADDER, ["green", "amber", "red"]);
+  });
+
+  it("paints an offline runner red with an honest why", () => {
+    const rung = healthRungOf(runnerOf({ state: "offline" }));
+    assert.equal(rung.rung, 2);
+    assert.equal(rung.label, "red");
+    assert.match(rung.why, /offline/);
+  });
+
+  it("paints a failure rate over 20% red", () => {
+    const rung = healthRungOf(runnerOf({ runs: 10, failures: 3 }));
+    assert.equal(rung.label, "red");
+    assert.match(rung.why, /failure rate/);
+  });
+
+  it("paints a draining runner amber", () => {
+    const rung = healthRungOf(runnerOf({ state: "draining" }));
+    assert.equal(rung.rung, 1);
+    assert.equal(rung.label, "amber");
+    assert.match(rung.why, /draining/);
+  });
+
+  it("paints a saturated runner amber (load over 85%)", () => {
+    const rung = healthRungOf(runnerOf({ load: 0.9 }));
+    assert.equal(rung.label, "amber");
+    assert.match(rung.why, /load/);
+  });
+
+  it("keeps a healthy busy runner green", () => {
+    const rung = healthRungOf(runnerOf({ load: 0.5, runs: 40, failures: 1 }));
+    assert.equal(rung.rung, 0);
+    assert.equal(rung.label, "green");
+  });
+
+  it("computes the failure rate honestly (zero runs → zero)", () => {
+    assert.equal(healthRungOf(runnerOf({ runs: 0, failures: 0 })).label, "green");
+  });
+});
+
+describe("fleet tick", () => {
+  it("advances the fleet deterministically", () => {
+    const fleet = seedFleet(20260214, 8);
+    const t1 = fleetTick(fleet, 20260214, 1);
+    const t1again = fleetTick(fleet, 20260214, 1);
+    assert.deepEqual(t1, t1again);
+  });
+
+  it("never mutates the input fleet", () => {
+    const fleet = seedFleet(5, 6);
+    const frozen = JSON.parse(JSON.stringify(fleet)) as Runner[];
+    fleetTick(fleet, 5, 3);
+    assert.deepEqual(fleet, frozen);
+  });
+
+  it("keeps runs monotonic and loads inside 0..1", () => {
+    let fleet = seedFleet(321, 8);
+    for (let tick = 1; tick <= 12; tick++) {
+      const next = fleetTick(fleet, 321, tick);
+      for (let i = 0; i < next.length; i++) {
+        assert.ok(next[i].runs >= fleet[i].runs, "runs never go backwards");
+        assert.ok(next[i].load >= 0 && next[i].load <= 1);
+      }
+      fleet = next;
+    }
+  });
+
+  it("never heals an offline runner by hiding its record", () => {
+    const fleet = [runnerOf({ id: "fgr-off", name: "runner-off-01", state: "offline", runs: 10, failures: 4 })];
+    const next = fleetTick(fleet, 1, 1)[0];
+    assert.equal(next.state, "offline");
+    assert.equal(next.failures, 4);
+  });
+});
+
+describe("fleet summary", () => {
+  it("counts states and rungs exactly", () => {
+    const fleet = [
+      runnerOf({ id: "a", state: "busy", load: 0.5 }),
+      runnerOf({ id: "b", state: "idle", load: 0.1 }),
+      runnerOf({ id: "c", state: "offline", load: 0 }),
+    ];
+    const summary = fleetSummary(fleet);
+    assert.equal(summary.total, 3);
+    assert.equal(summary.byState.busy, 1);
+    assert.equal(summary.byState.idle, 1);
+    assert.equal(summary.byState.offline, 1);
+    assert.equal(summary.byHealth.red, 1);
+    assert.equal(summary.byHealth.green, 2);
+    assert.equal(summary.healthy, false);
+  });
+
+  it("answers a healthy floor when no runner rides red", () => {
+    const summary = fleetSummary([
+      runnerOf({ id: "a", state: "busy", load: 0.5 }),
+      runnerOf({ id: "b", state: "idle", load: 0.2 }),
+    ]);
+    assert.equal(summary.healthy, true);
+  });
+
+  it("answers a zero busy load on an empty floor", () => {
+    const summary = fleetSummary([]);
+    assert.equal(summary.total, 0);
+    assert.equal(summary.busyLoad, 0);
+  });
+});
+
+describe("pick runner", () => {
+  it("never hands work to an offline or red runner", () => {
+    const fleet = [
+      runnerOf({ id: "a", state: "offline" }),
+      runnerOf({ id: "b", runs: 10, failures: 5 }),
+      runnerOf({ id: "c", state: "idle", load: 0.1 }),
+    ];
+    const picked = pickRunner(fleet, "runner");
+    assert.ok(picked);
+    assert.equal(picked.id, "c");
+  });
+
+  it("prefers the greener, lighter runner of the requested mode", () => {
+    const fleet = [
+      runnerOf({ id: "light", state: "idle", load: 0.1 }),
+      runnerOf({ id: "heavy", state: "busy", load: 0.9 }),
+    ];
+    assert.equal(pickRunner(fleet, "runner")?.id, "light");
+  });
+
+  it("refuses honestly when nobody of the mode can take the work", () => {
+    const fleet = [runnerOf({ id: "a", mode: "docker", state: "offline" })];
+    assert.equal(pickRunner(fleet, "runner"), undefined);
+  });
+});

package/tests/queue.test.ts

@@ -0,0 +1,174 @@
+// # queue.test — the execution queue engine of the /queue page, runnable
+// with the node built-in runner (no dependencies, no install):
+//   node --test tests/queue.test.ts
+// The queue never lies: storage is append-only, the serving order is
+// priority first and FIFO inside the lane, the depth counts exactly and
+// the rehearsal seed replays the same queue every time.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import {
+  cancel,
+  depthByPriority,
+  dequeue,
+  enqueue,
+  nextUp,
+  PRIORITY_RANK,
+  positionOf,
+  QUEUE_PRIORITIES,
+  type QueueItem,
+  queueDepth,
+  queueFromSeed,
+  queueOrder,
+} from "../queue.ts";
+
+/** a draft without the seq (enqueue stamps it) */
+function draft(id: string, priority: QueueItem["priority"], seqLess: true = true): Omit<QueueItem, "seq"> {
+  void seqLess;
+  return { id, label: `run ${id}`, mode: "runner", priority, enqueuedAt: 0 };
+}
+
+describe("queue order", () => {
+  it("serves express before normal before batch", () => {
+    const queue = [draft("b", "batch"), draft("e", "express"), draft("n", "normal")] as QueueItem[];
+    const seeded = queue.reduce((acc, item) => enqueue(acc, item), [] as QueueItem[]);
+    assert.deepEqual(
+      queueOrder(seeded).map((item) => item.id),
+      ["e", "n", "b"],
+    );
+  });
+
+  it("keeps FIFO inside a lane (arrival order breaks the ties)", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("a1", "normal"));
+    queue = enqueue(queue, draft("a2", "normal"));
+    queue = enqueue(queue, draft("a3", "normal"));
+    assert.deepEqual(
+      queueOrder(queue).map((item) => item.id),
+      ["a1", "a2", "a3"],
+    );
+  });
+
+  it("ranks the priorities in serve order", () => {
+    assert.equal(PRIORITY_RANK.express, 0);
+    assert.equal(PRIORITY_RANK.normal, 1);
+    assert.equal(PRIORITY_RANK.batch, 2);
+    assert.deepEqual(QUEUE_PRIORITIES, ["express", "normal", "batch"]);
+  });
+});
+
+describe("enqueue", () => {
+  it("stamps monotonic arrival seqs", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("a", "express"));
+    queue = enqueue(queue, draft("b", "express"));
+    queue = enqueue(queue, draft("c", "express"));
+    assert.deepEqual(
+      queue.map((item) => item.seq),
+      [1, 2, 3],
+    );
+  });
+
+  it("appends without mutating the input queue", () => {
+    const before: QueueItem[] = [{ id: "x", label: "run x", mode: "docker", priority: "batch", seq: 1, enqueuedAt: 0 }];
+    const after = enqueue(before, draft("y", "normal"));
+    assert.equal(before.length, 1);
+    assert.equal(after.length, 2);
+    assert.deepEqual(before[0], { id: "x", label: "run x", mode: "docker", priority: "batch", seq: 1, enqueuedAt: 0 });
+  });
+});
+
+describe("dequeue", () => {
+  it("pops the head of the serving order and removes it", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("batch-1", "batch"));
+    queue = enqueue(queue, draft("express-1", "express"));
+    const answer = dequeue(queue);
+    assert.equal(answer.item?.id, "express-1");
+    assert.equal(answer.queue.length, 1);
+    assert.equal(answer.queue[0].id, "batch-1");
+  });
+
+  it("answers an honest empty when the queue is empty", () => {
+    const answer = dequeue([]);
+    assert.equal(answer.item, undefined);
+    assert.equal(answer.queue.length, 0);
+  });
+
+  it("serves FIFO inside the lane across dequeues", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("n1", "normal"));
+    queue = enqueue(queue, draft("n2", "normal"));
+    const first = dequeue(queue);
+    const second = dequeue(first.queue);
+    assert.equal(first.item?.id, "n1");
+    assert.equal(second.item?.id, "n2");
+  });
+});
+
+describe("cancel", () => {
+  it("removes only the cancelled run", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("a", "normal"));
+    queue = enqueue(queue, draft("b", "normal"));
+    const next = cancel(queue, "a");
+    assert.deepEqual(
+      next.map((item) => item.id),
+      ["b"],
+    );
+  });
+
+  it("keeps the queue untouched when the id is unknown", () => {
+    const queue = enqueue(enqueue([], draft("a", "normal")), draft("b", "normal"));
+    const next = cancel(queue, "ghost");
+    assert.equal(next.length, 2);
+  });
+});
+
+describe("depth and position", () => {
+  it("counts the depth exactly", () => {
+    let queue: QueueItem[] = [];
+    for (let i = 0; i < 5; i++) queue = enqueue(queue, draft(`r${i}`, "batch"));
+    assert.equal(queueDepth(queue), 5);
+    assert.equal(queueDepth([]), 0);
+  });
+
+  it("counts the lanes per priority", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("e1", "express"));
+    queue = enqueue(queue, draft("n1", "normal"));
+    queue = enqueue(queue, draft("n2", "normal"));
+    queue = enqueue(queue, draft("b1", "batch"));
+    const lanes = depthByPriority(queue);
+    assert.equal(lanes.express, 1);
+    assert.equal(lanes.normal, 2);
+    assert.equal(lanes.batch, 1);
+  });
+
+  it("answers the position in the serving order", () => {
+    let queue: QueueItem[] = [];
+    queue = enqueue(queue, draft("express", "express"));
+    queue = enqueue(queue, draft("normal", "normal"));
+    queue = enqueue(queue, draft("batch", "batch"));
+    assert.equal(positionOf(queue, "express"), 0);
+    assert.equal(positionOf(queue, "batch"), 2);
+    assert.equal(positionOf(queue, "ghost"), -1);
+  });
+});
+
+describe("rehearsal queue", () => {
+  it("replays the same queue from the same seed", () => {
+    assert.deepEqual(queueFromSeed(731004, 7), queueFromSeed(731004, 7));
+  });
+
+  it("stamps unique ids and seqs on every item", () => {
+    const queue = queueFromSeed(42, 9);
+    assert.equal(queue.length, 9);
+    assert.equal(new Set(queue.map((item) => item.id)).size, 9);
+    assert.equal(new Set(queue.map((item) => item.seq)).size, 9);
+  });
+
+  it("answers nextUp as the head of the serving order", () => {
+    const queue = queueFromSeed(731004, 7);
+    assert.equal(nextUp(queue)?.id, queueOrder(queue)[0]?.id);
+  });
+});

package/tests/runstream.test.ts

@@ -0,0 +1,126 @@
+// # runstream.test — the deterministic log replay of the /logs page,
+// runnable with the node built-in runner (no dependencies, no install):
+//   node --test tests/runstream.test.ts
+// One seed unrolls the whole line stream: the same seed answers the same
+// lines forever, the outcome derives from the stream itself, the prefix
+// window and the census are pure.
+import assert from "node:assert/strict";
+import { describe, it } from "node:test";
+import { formatLogTime, linesWithin, logCensus, logDuration, logOutcome, logText, runLogLines } from "../runstream.ts";
+
+describe("replay determinism", () => {
+  it("answers the same stream from the same seed", () => {
+    assert.deepEqual(runLogLines(421337), runLogLines(421337));
+  });
+
+  it("answers the same stream for the same seed at any size", () => {
+    const a = runLogLines(7, 9);
+    const b = runLogLines(7, 9);
+    assert.deepEqual(a, b);
+    assert.equal(a.length, 3 + 9 + 2);
+  });
+
+  it("opens every run with the three boot lines in order", () => {
+    const lines = runLogLines(1);
+    assert.match(lines[0].text, /^floor: accepting run on the /);
+    assert.match(lines[1].text, /mount sandbox/);
+    assert.match(lines[2].text, /restore working set/);
+  });
+
+  it("keeps the stream chronological (t never goes backwards)", () => {
+    const lines = runLogLines(90012);
+    for (let i = 1; i < lines.length; i++) {
+      assert.ok(lines[i].t >= lines[i - 1].t, `line ${i} drifted backwards`);
+    }
+  });
+
+  it("answers differing streams for differing seeds (over 20 seeds)", () => {
+    const firsts = new Set<string>();
+    for (let seed = 1; seed <= 20; seed++) {
+      const lines = runLogLines(seed);
+      firsts.add(JSON.stringify(lines));
+    }
+    // at most two identical streams across 20 seeds is well within chance
+    assert.ok(firsts.size >= 18, `expected near-unique streams, got ${firsts.size}`);
+  });
+});
+
+describe("outcome honesty", () => {
+  it("derives success when the stream carries no error", () => {
+    const lines = runLogLines(421337);
+    if (lines.some((line) => line.level === "error")) return;
+    assert.equal(logOutcome(lines), "success");
+  });
+
+  it("derives failed from the error line itself", () => {
+    const lines = runLogLines(1, 1); // small stream; find a failing seed
+    let failing: ReturnType<typeof runLogLines> | undefined;
+    for (let seed = 0; seed < 64 && !failing; seed++) {
+      const candidate = runLogLines(seed);
+      if (candidate.some((line) => line.level === "error")) failing = candidate;
+    }
+    assert.ok(failing, "some seed in 0..63 must fail");
+    void lines;
+    assert.equal(logOutcome(failing), "failed");
+    const last = failing[failing.length - 1];
+    assert.match(last.text, /outcome: failed/);
+  });
+
+  it("closes a successful run with the report line", () => {
+    for (let seed = 0; seed < 64; seed++) {
+      const lines = runLogLines(seed);
+      if (!lines.some((line) => line.level === "error")) {
+        assert.match(lines[lines.length - 1].text, /outcome: success/);
+        return;
+      }
+    }
+    assert.fail("no successful seed found in 0..63");
+  });
+});
+
+describe("window and clock", () => {
+  it("linesWithin answers the chronological prefix", () => {
+    const lines = runLogLines(5124);
+    const mid = logDuration(lines) / 2;
+    const head = linesWithin(lines, mid);
+    assert.ok(head.length > 0);
+    assert.ok(head.length < lines.length);
+    assert.deepEqual(
+      head,
+      lines.filter((line) => line.t <= mid),
+    );
+  });
+
+  it("linesWithin at zero answers only the boot head, at full the whole stream", () => {
+    const lines = runLogLines(5124);
+    assert.ok(linesWithin(lines, 0).length >= 1);
+    assert.deepEqual(linesWithin(lines, logDuration(lines)), lines);
+  });
+
+  it("logDuration answers the last timestamp", () => {
+    const lines = runLogLines(77031);
+    assert.equal(logDuration(lines), Math.max(...lines.map((line) => line.t)));
+  });
+
+  it("formatLogTime renders the tabular mm:ss.mmm clock", () => {
+    assert.equal(formatLogTime(0), "00:00.000");
+    assert.equal(formatLogTime(1000), "00:01.000");
+    assert.equal(formatLogTime(61_234), "01:01.234");
+    assert.equal(formatLogTime(600_000), "10:00.000");
+    assert.equal(formatLogTime(-5), "00:00.000");
+  });
+
+  it("logCensus counts every level and sums to the total", () => {
+    const lines = runLogLines(77031);
+    const census = logCensus(lines);
+    assert.equal(census.info + census.warn + census.error, lines.length);
+  });
+
+  it("logText renders one line per stream line with the clock first", () => {
+    const lines = runLogLines(421337);
+    const text = logText(lines);
+    const rows = text.split("\n");
+    assert.equal(rows.length, lines.length);
+    assert.match(rows[0], /^\d{2}:\d{2}\.\d{3} info /);
+  });
+});