@intentius/behold 0.29.7 → 0.29.9

package/web/kiosk-approval.js

@@ -0,0 +1,241 @@
+// behold#571: "How this hold ends", the approval panel. From the step a wave
+// waits on through the waves applied, four rows light one by one, each from a
+// record, never from the narration:
+//
+// - Requested: the wave asked for an approval of its plan (by digest). The
+//   gate ledger's pending fact on chant/lifecycle (/api/lifecycle/history,
+//   chant's gate-audit `approval-requested`), and the wave's log line.
+// - Approved: a reviewer approved exactly that plan. The ledger's approval of
+//   that digest, its seal, and whether the seal checks out against the
+//   repo's allowed signers (/api/terragucci/lifecycle's `sealCheck`).
+// - Resumed: `/terragucci apply` started the waves again and the gate found
+//   the approval of this digest. The resume run and its log lines.
+// - Spent: the wave applied under that approval, which is now used up. The
+//   ledger's applied record, and the wave's log line.
+//
+// Each record is this cycle's: no earlier than the cycle's start, and, in a
+// replay, no later than the replay's clock. The digests repeat from cycle to
+// cycle (the loop plans the same change), so the cycle's start is what keeps
+// an older approval of the same plan from lighting a row.
+
+import { findLine } from "./kiosk-annotations.js";
+
+/** The steps the panel shows on: from the wave waiting to the waves applied. */
+export const PANEL_STEPS = ["waiting", "approved", "resumed", "applied"];
+
+/** The panel's title. */
+export const PANEL_TITLE = "How this hold ends";
+
+/** The rows, in order. */
+export const ROWS = [
+  { id: "requested", label: "Requested" },
+  { id: "approved", label: "Approved" },
+  { id: "resumed", label: "Resumed" },
+  { id: "spent", label: "Spent" },
+];
+
+/** A digest's hex part, for comparing `jcs1-sha256:…` with `sha256:…`. */
+export const digestHex = (d) => (typeof d === "string" ? d.slice(d.lastIndexOf(":") + 1).toLowerCase() : "");
+export const sameDigest = (a, b) => !!digestHex(a) && digestHex(a) === digestHex(b);
+/** A digest as a viewer reads it: its first 12 hex digits. */
+export const shortDigest = (d) => digestHex(d).slice(0, 12);
+
+const ms = (t) => (t ? Date.parse(t) : NaN);
+
+/** The runs of the cycle demo.json is at, oldest first: same cycle (or, without one, the same pull request since the cycle started), merges and resumes. */
+export function cycleRuns(runs, demo) {
+  const start = ms(demo && demo.started_at);
+  return (runs || [])
+    .filter((r) => r && (r.trigger === "merge" || isResume(r) || r.trigger === "push"))
+    .filter((r) => (Number.isInteger(r.cycle) && Number.isInteger(demo.cycle) ? r.cycle === demo.cycle : String(r.pull) === String(demo.pull) && !(ms(r.created_at) < start)))
+    .sort((a, b) => ms(a.created_at) - ms(b.created_at) || a.id - b.id);
+}
+
+/** A run that `/terragucci apply` started: the driver's resume, a comment on the merged pull request. */
+export const isResume = (r) => !!r && (r.trigger === "resume" || r.event === "issue_comment");
+
+const waveLine = (wave) => (text) => new RegExp(`^wave ${wave}\\b`).test(text);
+
+/** The line of a run that `ids` know about wave `wave`, with the run's id: `{ run, a, job, step, n, text }` or null. */
+function lineOf(run, ids, wave, more = () => true) {
+  const f = findLine(run, ids, (text, a) => waveLine(wave)(text) && more(text, a));
+  return f ? { run: run.id, ...f } : null;
+}
+
+/**
+ * The wave this cycle holds and the plan it asks about: the newest "waits for
+ * an approval of digest" line (T11) in the cycle's runs, with where it is.
+ * Null when no run of the cycle printed one.
+ */
+export function heldWave(runs) {
+  let found = null;
+  for (const run of runs) {
+    const f = findLine(run, ["T11"]);
+    if (!f) continue;
+    const m = /^wave (\d+) of \d+ waits for an approval of digest (\S+?)\./.exec(f.text);
+    if (m) found = { wave: Number(m[1]), digest: m[2], line: { run: run.id, ...f } };
+  }
+  return found;
+}
+
+/** When a line says it happened: the time in it (T14's approval time is not when it applied), else the run's step's end, else the run's start. */
+function lineTime(run, f) {
+  const job = run.jobs.find((j) => j.name === f.job);
+  const step = job && job.steps ? job.steps[f.step] : null;
+  return (step && (step.ended_at || step.started_at)) || run.started_at || run.created_at || null;
+}
+
+/**
+ * The panel's model: `{ wave, digest, rows: [{ id, label, state, … }] }`, or
+ * null when the step is not one the panel shows or no wave of the cycle
+ * held. `state` is `lit`, `going` (begun, not done) or `dim`. Inputs:
+ *
+ * - `demo`: demo.json (or the replay's step);
+ * - `runs`: the cycle's runs' documents (any order);
+ * - `history`: /api/lifecycle/history's answer;
+ * - `lifecycle`: /api/terragucci/lifecycle's answer;
+ * - `fallback`: `{ wave, digest }` from the run view, for a wave whose log isn't copied yet;
+ * - `now`: the page's clock (the replay's, in a replay), in ms.
+ */
+export function approvalModel({ demo, runs = [], history = null, lifecycle = null, fallback = null, now = Date.now(), driver = null }) {
+  if (!demo || !PANEL_STEPS.includes(demo.step)) return null;
+  const cycle = cycleRuns(runs, demo);
+  const held = heldWave(cycle) || (fallback && fallback.wave ? { wave: fallback.wave, digest: fallback.digest || null, line: null } : null);
+  if (!held) return null;
+  const { wave, digest } = held;
+  const start = ms(demo.started_at);
+  const inCycle = (t) => !(ms(t) < start) && !(ms(t) > now);
+  const gate = `wave-${wave}`;
+  const entries = (history && Array.isArray(history.entries) ? history.entries : []).filter((e) => e.gate === gate && inCycle(e.at) && (!digest || sameDigest(e.digest, digest)));
+  const oldest = (kind) => entries.filter((e) => e.kind === kind).sort((a, b) => ms(a.at) - ms(b.at))[0] || null;
+  const requested = oldest("approval-requested");
+  const approved = entries.filter((e) => e.kind === "approved" && (!requested || ms(e.at) >= ms(requested.at))).sort((a, b) => ms(a.at) - ms(b.at))[0] || null;
+  const lane = lifecycle && Array.isArray(lifecycle.gates) ? lifecycle.gates.find((g) => g.gate === gate) : null;
+
+  // Requested.
+  const reqLine = held.line;
+  const reqRow = { id: "requested", label: "Requested" };
+  if (requested || reqLine) {
+    Object.assign(reqRow, {
+      state: "lit",
+      text: `Wave ${wave} asked for an approval of this plan.`,
+      at: requested ? requested.at : reqLine ? lineTime(cycle.find((r) => r.id === reqLine.run), reqLine) : null,
+      commit: requested && requested.source ? requested.source.commit || null : null,
+      line: reqLine,
+    });
+  } else Object.assign(reqRow, { state: "dim", text: `Wave ${wave} has not asked for an approval yet.` });
+
+  // Approved.
+  const apRow = { id: "approved", label: "Approved" };
+  // The resume runs: started by /terragucci apply after the run that held the wave.
+  const holdRun = reqLine ? cycle.find((r) => r.id === reqLine.run) : null;
+  const resumeRuns = cycle.filter((r) => isResume(r) && (!holdRun || !(ms(r.created_at) < ms(holdRun.created_at))));
+  const gateRead = resumeRuns.map((r) => lineOf(r, ["T09"], wave, (text) => / approved by /.test(text))).find(Boolean) || null;
+  if (approved) {
+    const check = lane && lane.approval && lane.approval.by === approved.actor && ms(lane.approval.at) === ms(approved.at) ? lane.approval.sealCheck || null : null;
+    Object.assign(apRow, {
+      state: "lit",
+      text: `${approved.actor || "A reviewer"} approved exactly this plan.`,
+      seal: sealWords(approved, check),
+      at: approved.at,
+      commit: approved.source ? approved.source.commit || null : null,
+      line: gateRead,
+    });
+  } else if (driver) {
+    Object.assign(apRow, { state: "dim", text: driver.gloss, command: driver.approve });
+  } else Object.assign(apRow, { state: "dim", text: "Waiting for a reviewer to approve this plan." });
+
+  // Resumed: the resume run, and the gate finding the approval in it.
+  const rsRow = { id: "resumed", label: "Resumed" };
+  const resume = resumeRuns[resumeRuns.length - 1] || null;
+  const found = resume ? lineOf(resume, ["T13"], wave) || gateRead : null;
+  const start2 = resume ? findLine(resume, ["T36"]) : null;
+  if (resume && found) {
+    Object.assign(rsRow, {
+      state: "lit",
+      text: "/terragucci apply ran the waves again, and the gate found this approval.",
+      at: resume.started_at || resume.created_at,
+      runId: resume.id,
+      line: start2 ? { run: resume.id, ...start2 } : found,
+    });
+  } else if (resume) {
+    Object.assign(rsRow, { state: "going", text: `/terragucci apply started the waves again; wave ${wave} has not reached its gate yet.`, at: resume.started_at || resume.created_at, runId: resume.id, line: start2 ? { run: resume.id, ...start2 } : null });
+  } else {
+    Object.assign(rsRow, { state: "dim", text: driver && driver.comment ? `Then a comment of ${driver.comment} on ${driver.on} starts the waves again.` : "A comment of /terragucci apply starts the waves again." });
+  }
+
+  // Spent: the ledger's applied record under this approval, or the wave's line.
+  const spRow = { id: "spent", label: "Spent" };
+  const spentLine = cycle.map((r) => lineOf(r, ["T14"], wave, (text) => !approved || !approved.actor || text.includes(` by ${approved.actor} `))).find(Boolean) || null;
+  const appliedRec = lane && lane.applied && approved && lane.applied.approvedBy === approved.actor && ms(lane.applied.approvedAt) === ms(approved.at) && inCycle(lane.applied.at) ? lane.applied : null;
+  if (appliedRec || spentLine) {
+    Object.assign(spRow, {
+      state: "lit",
+      text: `Wave ${wave} applied under that approval, which is now used up.`,
+      at: appliedRec ? appliedRec.at : spentLine ? lineTime(cycle.find((r) => r.id === spentLine.run), spentLine) : null,
+      runId: spentLine ? spentLine.run : null,
+      line: spentLine,
+    });
+  } else Object.assign(spRow, { state: "dim", text: `Once wave ${wave} applies, this approval is used up for good.` });
+
+  return { wave, digest, rows: inferBack([reqRow, apRow, rsRow, spRow], { wave, gateRead, spentLine, resumeRuns }) };
+}
+
+/** The words a row lit only because a later one is, by row. Each says it was inferred; none invents a time. */
+export const INFERRED = {
+  requested: (wave) => `Wave ${wave} asked for an approval of this plan.`,
+  approved: (actor) => `${actor || "A reviewer"} approved this plan.`,
+  resumed: () => "The waves ran again under this approval.",
+};
+
+/**
+ * behold#571: a hold ends in order, so no row is lit after one that isn't.
+ * A lit row lights the rows before it: Spent means the waves ran again
+ * (Resumed), which means the plan was approved, which means it was asked
+ * for. A row lit this way says so (`inferred`), names what the later rows
+ * show (the approver from the gate's or the spend's line, the run), and
+ * carries no time it does not have.
+ */
+export function inferBack(rows, { wave, gateRead = null, spentLine = null, resumeRuns = [] } = {}) {
+  const out = rows.map((r) => ({ ...r }));
+  for (let i = out.length - 1; i > 0; i--) {
+    if (out[i].state !== "lit" || out[i - 1].state === "lit") continue;
+    const r = out[i - 1];
+    const base = { id: r.id, label: r.label, state: "lit", inferred: true };
+    if (r.id === "requested") out[i - 1] = { ...base, text: INFERRED.requested(wave) };
+    else if (r.id === "approved") {
+      const said = [gateRead, spentLine].filter(Boolean).map((l) => / approv(?:ed|al) by (\S+?)[;,\s]/.exec(`${l.text} `)).find(Boolean);
+      out[i - 1] = { ...base, text: INFERRED.approved(said ? said[1] : null), line: gateRead || null };
+    } else if (r.id === "resumed") {
+      const run = resumeRuns[resumeRuns.length - 1] || null;
+      out[i - 1] = { ...base, text: INFERRED.resumed(), runId: run ? run.id : r.runId || (spentLine ? spentLine.run : null), at: r.at || null, line: r.line || null };
+    }
+  }
+  return out;
+}
+
+/**
+ * The seal in words: signed and checked against the repo's allowed signers,
+ * signed and not matching (with chant's reason), signed with nothing to
+ * check it against here, or not signed.
+ */
+export function sealWords(entry, check) {
+  const signed = entry && (entry.seal === "sealed" || (entry.audit && entry.audit.sealed));
+  if (!signed) return { ok: null, text: entry && entry.seal === "review" ? "approved by a pull request review" : "not signed" };
+  if (check && check.ok) return { ok: true, text: "signed; matches the repo's allowed signers" };
+  if (check && check.ok === false) return { ok: false, text: `signed, but the signature does not check out: ${check.reason}` };
+  return { ok: null, text: "signed; behold has not checked the signature" };
+}
+
+/** "04:09:41", in UTC (the panel's head says so). */
+export function clockWords(at) {
+  const t = ms(at);
+  if (Number.isNaN(t)) return null;
+  return new Date(t).toISOString().slice(11, 19);
+}
+
+/** A row's facts after its sentence, in order: the seal, the time, the ledger's commit on chant/lifecycle, the run. */
+export function rowFacts(row) {
+  return [row.inferred ? "inferred from the rows after it" : null, row.seal ? row.seal.text : null, clockWords(row.at), row.commit ? `ledger ${row.commit.slice(0, 8)}` : null, row.runId ? `run #${row.runId}` : null].filter(Boolean);
+}
+

package/web/kiosk-approval.test.js

@@ -0,0 +1,122 @@
+// behold#571: "How this hold ends" lights its rows from records (the fixture runs approve as terragucci-admin): the ledger's
+// requested and approved entries, the lane's seal check and applied record,
+// and the cycle's runs' log lines. Never from the step the narration is at.
+import { readFileSync } from "node:fs";
+import { join } from "node:path";
+import { describe, expect, it } from "vitest";
+import { PANEL_STEPS, ROWS, approvalModel, inferBack, clockWords, cycleRuns, heldWave, rowFacts, sameDigest, sealWords, shortDigest } from "./kiosk-approval.js";
+
+const FIX = join(import.meta.dirname, "..", "src", "__fixtures__", "terragucci-demo", "runs");
+const run = (id) => JSON.parse(readFileSync(join(FIX, `${id}.json`), "utf8"));
+const D2 = "jcs1-sha256:0accc105ba060b9974468c91def518039d935ad6629f8a15869f6e89ef748b61";
+const demo = (step) => ({ step, cycle: 90, pull: 278, started_at: "2026-10-15T04:08:30Z", commit: "ef959409b8d590f4c3b05f0b7154cd576c9e1abf" });
+const history = (kinds) => ({
+  entries: [
+    { kind: "approved", gate: "wave-2", at: "2026-10-15T04:10:08.707Z", digest: D2, actor: "terragucci-admin", seal: "sealed", audit: { sealed: true }, source: { commit: "4cba487a0000" } },
+    { kind: "approval-requested", gate: "wave-2", at: "2026-10-15T04:09:41Z", digest: D2, source: { commit: "57869649aaaa" } },
+    // An earlier cycle's approval of the same plan: the loop plans the same change every time.
+    { kind: "approved", gate: "wave-2", at: "2026-10-15T03:56:09.124Z", digest: D2, actor: "terragucci-admin", seal: "sealed", source: { commit: "0ld" } },
+  ].filter((e) => kinds.includes(e.kind)),
+});
+const lane = (over = {}) => ({ gates: [{ gate: "wave-2", approval: { by: "terragucci-admin", at: "2026-10-15T04:10:08.707Z", signed: true, sealCheck: { ok: true } }, ...over }] });
+const state = (m) => Object.fromEntries(m.rows.map((r) => [r.id, r.state]));
+
+describe("the approval panel (behold#571)", () => {
+  it("shows from the wave waiting through the waves applied, and has four rows", () => {
+    expect(PANEL_STEPS).toEqual(["waiting", "approved", "resumed", "applied"]);
+    expect(ROWS.map((r) => r.label)).toEqual(["Requested", "Approved", "Resumed", "Spent"]);
+    expect(approvalModel({ demo: demo("applying"), runs: [run(444)] })).toBe(null);
+    expect(approvalModel({ demo: demo("waiting"), runs: [] })).toBe(null);
+  });
+
+  it("finds the held wave and its plan in the cycle's runs", () => {
+    const cycle = cycleRuns([run(445), run(444), run(443), run(447)], demo("waiting"));
+    expect(cycle.map((r) => r.id)).toEqual([444, 445]);
+    const h = heldWave(cycle);
+    expect(h).toMatchObject({ wave: 2, digest: D2, line: { run: 444, job: "apply-wave-2" } });
+  });
+
+  it("lights Requested at the hold, from the log line alone and then the ledger", () => {
+    const m = approvalModel({ demo: demo("waiting"), runs: [run(444)], now: Date.parse("2026-10-15T04:09:50Z") });
+    expect(state(m)).toEqual({ requested: "lit", approved: "dim", resumed: "dim", spent: "dim" });
+    expect(m.rows[0].line.a.id).toBe("T11");
+    const withLedger = approvalModel({ demo: demo("waiting"), runs: [run(444)], history: history(["approval-requested", "approved"]), now: Date.parse("2026-10-15T04:09:50Z") });
+    // The approval at 04:10:08 is after the page's clock, so it is not there yet.
+    expect(state(withLedger).approved).toBe("dim");
+    expect(withLedger.rows[0].commit).toBe("57869649aaaa");
+  });
+
+  it("puts the driver's command in the Approved row until the approval is recorded", () => {
+    const driver = { gloss: "Next the driver signs.", approve: "chant approve tf-apply wave-2", comment: "/terragucci apply", on: "pull request #278" };
+    const m = approvalModel({ demo: demo("waiting"), runs: [run(444)], driver, now: Date.parse("2026-10-15T04:09:50Z") });
+    expect(m.rows[1]).toMatchObject({ state: "dim", command: "chant approve tf-apply wave-2" });
+  });
+
+  it("lights Approved for exactly this plan, this cycle, with its seal checked", () => {
+    const m = approvalModel({ demo: demo("approved"), runs: [run(444)], history: history(["approval-requested", "approved"]), lifecycle: lane(), now: Date.parse("2026-10-15T04:10:09Z") });
+    expect(state(m)).toEqual({ requested: "lit", approved: "lit", resumed: "dim", spent: "dim" });
+    expect(m.rows[1].text).toBe("terragucci-admin approved exactly this plan.");
+    expect(m.rows[1].seal.ok).toBe(true);
+    expect(m.rows[1].at).toBe("2026-10-15T04:10:08.707Z");
+    // Only an earlier cycle's approval of the same digest: nothing lights.
+    const old = approvalModel({ demo: demo("approved"), runs: [run(444)], history: { entries: history(["approved"]).entries.filter((e) => e.source.commit === "0ld") }, now: Date.parse("2026-10-15T04:10:09Z") });
+    expect(state(old).approved).toBe("dim");
+  });
+
+  it("lights Resumed and Spent from the resume run's lines and the ledger's applied record", () => {
+    const m = approvalModel({
+      demo: demo("applied"),
+      runs: [run(444), run(445)],
+      history: history(["approval-requested", "approved"]),
+      lifecycle: lane({ applied: { at: "2026-10-15T04:10:15Z", approvedAt: "2026-10-15T04:10:08.707Z", approvedBy: "terragucci-admin" } }),
+      now: Date.parse("2026-10-15T04:11:00Z"),
+    });
+    expect(state(m)).toEqual({ requested: "lit", approved: "lit", resumed: "lit", spent: "lit" });
+    expect(m.rows[2].line.a.id).toBe("T36");
+    expect(m.rows[3].line).toMatchObject({ run: 445, a: { id: "T14" } });
+    expect(m.rows[3].at).toBe("2026-10-15T04:10:15Z");
+    expect(m.rows[1].line.a.id).toBe("T09");
+  });
+
+  it("says what the seal is", () => {
+    expect(sealWords({ seal: "sealed" }, { ok: true }).ok).toBe(true);
+    expect(sealWords({ seal: "sealed" }, { ok: false, reason: "no key" }).text).toMatch(/does not check out: no key$/);
+    expect(sealWords({ seal: "sealed" }, null).ok).toBe(null);
+    expect(sealWords({ seal: "unsigned" }, null).text).toBe("not signed");
+  });
+
+  it("reads digests and times the way the panel shows them", () => {
+    expect(sameDigest(D2, `sha256:${D2.slice(12)}`)).toBe(true);
+    expect(shortDigest(D2)).toBe("0accc105ba06");
+    expect(clockWords("2026-10-15T04:10:08.707Z")).toBe("04:10:08");
+    expect(rowFacts({ at: "2026-10-15T04:10:08Z", commit: "4cba487a0000", runId: 445 })).toEqual(["04:10:08", "ledger 4cba487a", "run #445"]);
+  });
+
+  it("never lights a row after one that is not lit", () => {
+    const resumeless = { ...run(445), trigger: "merge", event: "push" };
+    const inputs = {
+      runs: [[run(444)], [run(444), run(445)], [run(444), resumeless], [run(445)]],
+      history: [null, history(["approval-requested"]), history(["approval-requested", "approved"]), history(["approved"])],
+      lifecycle: [null, lane(), lane({ applied: { at: "2026-10-15T04:10:15Z", approvedAt: "2026-10-15T04:10:08.707Z", approvedBy: "terragucci-admin" } })],
+    };
+    for (const step of PANEL_STEPS)
+      for (const runs of inputs.runs)
+        for (const h of inputs.history)
+          for (const l of inputs.lifecycle) {
+            const m = approvalModel({ demo: demo(step), runs, history: h, lifecycle: l, fallback: { wave: 2, digest: D2 }, now: Date.parse("2026-10-15T04:11:00Z") });
+            if (!m) continue;
+            const lit = m.rows.map((r) => r.state === "lit");
+            expect(lit.findIndex((x, i) => x && i > 0 && !lit[i - 1]), `${step}: ${m.rows.map((r) => r.state).join(",")}`).toBe(-1);
+          }
+  });
+
+  it("lights Resumed from the spend when no resume run was copied, says so, and invents no time", () => {
+    const resumeless = { ...run(445), trigger: "merge", event: "push" };
+    const m = approvalModel({ demo: demo("applied"), runs: [run(444), resumeless], now: Date.parse("2026-10-15T04:11:00Z") });
+    expect(m.rows.map((r) => r.state)).toEqual(["lit", "lit", "lit", "lit"]);
+    expect(m.rows[2]).toMatchObject({ inferred: true, runId: 445, at: null });
+    expect(rowFacts(m.rows[2])).toEqual(["inferred from the rows after it", "run #445"]);
+    expect(m.rows[1]).toMatchObject({ inferred: true, text: "terragucci-admin approved this plan." });
+    expect(inferBack([{ id: "requested", state: "dim" }, { id: "approved", state: "dim" }], { wave: 2 }).map((r) => r.state)).toEqual(["dim", "dim"]);
+  });
+});

package/web/kiosk-popover.js

@@ -40,6 +40,7 @@ export const WORDS = {
   leftIsApplied: "Left of each arrow is the value applied now.",
   pinHint: "Click to keep this open.",
   pinnedHint: "Click elsewhere or press Escape to close this.",
+  tapPinnedHint: "Tap elsewhere to close this.",
   noResources: "No resources found for this root.",
   noRootChange: "No resource in this root changes.",
   changes: "changes",

package/web/kiosk-repo.js

@@ -0,0 +1,25 @@
+// behold#571: which repo the kiosk's graph reads, on a behold that serves
+// several (`behold serve --repos`, one checkout per demo repo). The kiosk
+// knows the repo it is about (demo.json's `repo`, or a tool's latest cycle's)
+// and asks for that checkout by name with `?repo=`; the server answers from
+// it, or refuses a name it doesn't serve.
+
+/** The reads that depend on the served checkout: the project, the reports' marks, the run view, and (behold#571's approval panel) the gate ledger read from its chant/lifecycle. */
+const REPO_READS = new Set(["/api/project", "/api/terragucci", "/api/terragucci/progress", "/api/terragucci/lifecycle", "/api/lifecycle/history"]);
+
+/** The checkout name for `repo` ("<owner>/<name>") when the server serves it; null otherwise. */
+export function repoParam(repo, served) {
+  if (typeof repo !== "string" || !repo || !Array.isArray(served)) return null;
+  const name = repo.replace(/\.git$/, "").slice(repo.lastIndexOf("/") + 1);
+  return served.includes(name) ? name : null;
+}
+
+/** `url` asking for `repo`, when it is one of the reads that depend on the checkout. */
+export function repoUrl(url, repo) {
+  if (!repo || typeof url !== "string") return url;
+  const [path, query = ""] = url.split("?");
+  if (!REPO_READS.has(path)) return url;
+  const q = new URLSearchParams(query);
+  q.set("repo", repo);
+  return `${path}?${q.toString()}`;
+}

package/web/kiosk-repo.test.js

@@ -0,0 +1,43 @@
+// behold#571: the kiosk asks for its repo's checkout by name, on a behold that serves several.
+import { describe, expect, it } from "vitest";
+import { repoParam, repoUrl } from "./kiosk-repo.js";
+import { frameSrc } from "./kiosk.js";
+import { pageRepo, withRepo } from "./view-repo.js";
+
+describe("repoParam", () => {
+  it("is the checkout name when the server serves it, else null", () => {
+    expect(repoParam("terragucci-admin/demo-terragrunt", ["demo", "demo-terragrunt"])).toBe("demo-terragrunt");
+    expect(repoParam("terragucci-admin/demo-cdk", ["demo", "demo-terragrunt"])).toBeNull();
+    expect(repoParam("terragucci-admin/demo", null)).toBeNull();
+    expect(repoParam(null, ["demo"])).toBeNull();
+  });
+});
+
+describe("repoUrl", () => {
+  it("adds the repo to the reads about the checkout only", () => {
+    expect(repoUrl("/api/project", "demo-terragrunt")).toBe("/api/project?repo=demo-terragrunt");
+    expect(repoUrl("/api/terragucci?fresh=1", "demo-terragrunt")).toBe("/api/terragucci?fresh=1&repo=demo-terragrunt");
+    expect(repoUrl("/api/terragucci/progress?commit=abc", "demo")).toBe("/api/terragucci/progress?commit=abc&repo=demo");
+    expect(repoUrl("/api/terragucci/lifecycle", "demo")).toBe("/api/terragucci/lifecycle?repo=demo");
+    expect(repoUrl("/api/lifecycle/history?limit=200", "demo")).toBe("/api/lifecycle/history?limit=200&repo=demo");
+    expect(repoUrl("/api/terragucci/demo", "demo")).toBe("/api/terragucci/demo");
+    expect(repoUrl("/api/terragucci/runs/4", "demo")).toBe("/api/terragucci/runs/4");
+    expect(repoUrl("/api/project", null)).toBe("/api/project");
+  });
+});
+
+describe("the frame", () => {
+  it("names the repo it draws, and nothing without one", () => {
+    expect(frameSrc("http://h", "resources")).toBe("/?embed=1&bare=1&zoom=resources&host=http%3A%2F%2Fh");
+    expect(frameSrc("http://h", "components", "demo-terragrunt")).toBe("/?embed=1&bare=1&zoom=components&host=http%3A%2F%2Fh&repo=demo-terragrunt");
+  });
+  it("carries the page's repo on each of its own /api/ reads", () => {
+    expect(pageRepo("?embed=1&repo=demo-terragrunt")).toBe("demo-terragrunt");
+    expect(pageRepo("?embed=1")).toBeNull();
+    expect(withRepo("/api/graph?zoom=resources", "demo-terragrunt", "http://h")).toBe("/api/graph?zoom=resources&repo=demo-terragrunt");
+    expect(withRepo("http://h/api/project", "demo-terragrunt", "http://h")).toBe("http://h/api/project?repo=demo-terragrunt");
+    expect(withRepo("/api/project?repo=demo", "demo-terragrunt", "http://h")).toBe("/api/project?repo=demo");
+    expect(withRepo("./manifest.json", "demo-terragrunt", "http://h")).toBe("./manifest.json");
+    expect(withRepo("https://elsewhere/api/x", "demo-terragrunt", "http://h")).toBe("https://elsewhere/api/x");
+  });
+});

package/web/kiosk-roots.js

@@ -7,17 +7,17 @@
 // its name, never as a text or fill colour. The hues below are none of those,
 // and each passes 4.5:1 on its theme's background and panel (checked against
 // #1e1e2e, #2e2f40, #11101f and #0f141d for dark; #ffffff and #f6f8fa for
-// light).
+// light). theme.js pushes each, per theme, to 3:1 on every kiosk surface
+// (--root-0 … --root-4), and the page paints a dot with that, this as its fallback.
 //
 // The colour follows the root's place in the sorted list of declared roots
 // (terragucci.components.json), so it is the same on every cycle and on every
 // screen showing the same repo.
 
-/** The root hues, by theme: violet, orange, orchid, silver, tan. */
-export const ROOT_HUES = {
-  dark: ["#b392f0", "#ff9f5a", "#e66ce8", "#e4e4e4", "#c89b6d"],
-  light: ["#7c3aed", "#c2410c", "#a21caf", "#334155", "#8b5a2b"],
-};
+import { ROOT_HUES } from "./theme.js";
+
+/** The root hues, by theme: violet, orange, orchid, silver, tan. theme.js holds them, and derives each theme's own (--root-0 …). */
+export { ROOT_HUES };
 
 /** The declared roots, sorted and without repeats: the order colours follow. */
 export function rootOrder(roots) {
@@ -33,6 +33,14 @@ export function rootColour(name, roots, { light = false } = {}) {
   return hues[i % hues.length];
 }
 
+/** A root's paint: the theme's own root colour (--root-<i>), with rootColour's as its fallback; null for a name that is not a root. */
+export function rootPaint(name, roots, { light = false } = {}) {
+  const c = rootColour(name, roots, { light });
+  if (!c) return null;
+  const hues = light ? ROOT_HUES.light : ROOT_HUES.dark;
+  return `var(--root-${rootOrder(roots).indexOf(name) % hues.length}, ${c})`;
+}
+
 // A token holding any of these is an address, a path, a hash or a key=value:
 // a root name inside it is not a mention of the root.
 const NOT_PROSE = /:\/\/|\/|=|^[0-9a-f]{7,}$|^jcs\d|sha\d+:/i;
@@ -167,7 +175,7 @@ export function rootText(doc, text, roots, { light = false } = {}) {
     const span = doc.createElement("span");
     span.className = "k-root";
     span.dataset.kRoot = seg.root;
-    span.style.setProperty("--k-root", rootColour(seg.root, roots, { light }));
+    span.style.setProperty("--k-root", rootPaint(seg.root, roots, { light }));
     span.textContent = seg.text;
     frag.appendChild(span);
   }