@intentius/behold 0.24.0 → 0.25.0

package/web/terragucci-estate.js

@@ -0,0 +1,328 @@
+// #509: a terragucci control repo, across its projects. app.js calls
+// initTerragucciEstate once; when /api/project names a control repo, this reads
+// /api/terragucci/estate and draws it over the (empty) graph area:
+//
+// - one box per project, its roots grouped by wave inside it, a solid arrow
+//   for each read within a project and a dashed one for each read between
+//   projects (an arrow points from a root to the root that reads its state,
+//   as on terragucci's estate page);
+// - on each box, terragucci's counts and the run view it was drawn from,
+//   each with its age and source;
+// - below, per project, its waiting waves with the approve line to copy (no
+//   button approves), its links, and how to serve its own checkout.
+//
+// A project with no run view is drawn as a box that says so, never dropped.
+// Nothing here is live: every figure is dated by estate.json's `generated` or
+// a run view's `updated`. The layout functions are pure and tested.
+
+import { ago, clock } from "./terragucci.js";
+
+export const COL_W = 176;
+export const ROW_H = 26;
+export const PAD = 12;
+export const HEAD_H = 64;
+export const WAVE_H = 22;
+export const GAP = 72;
+export const NO_RUN_W = 300;
+
+/** The address a key opens at: this server's file route. */
+export function keyHref(answer, key) {
+  return `${answer.files || ""}${answer.files && answer.files.includes("?") ? encodeURIComponent(key) : key}`;
+}
+
+/**
+ * Projects in drawing order: a project whose roots another reads comes before
+ * the reader, so a dashed edge runs left to right where it can. Ties keep
+ * estate.json's order.
+ */
+export function projectOrder(answer) {
+  const names = answer.projects.map((p) => p.project);
+  const before = new Map(names.map((n) => [n, new Set()]));
+  for (const e of answer.edges || []) if (e.cross && before.has(e.to.project) && before.has(e.from.project)) before.get(e.to.project).add(e.from.project);
+  const out = [];
+  const seen = new Set();
+  const visit = (n, stack) => {
+    if (seen.has(n) || stack.has(n)) return;
+    stack.add(n);
+    for (const m of names) if (before.get(n).has(m)) visit(m, stack);
+    stack.delete(n);
+    seen.add(n);
+    out.push(n);
+  };
+  for (const n of names) visit(n, new Set());
+  return out.map((n) => answer.projects.find((p) => p.project === n));
+}
+
+/** The waves a project's box has columns for: its run view's waves and any wave a root names, ascending. */
+export function wavesOf(run) {
+  const n = new Set([...(run.waves || []).map((w) => w.number), ...(run.roots || []).map((r) => r.wave)]);
+  return [...n].sort((a, b) => a - b);
+}
+
+/**
+ * Where everything goes: each project's box, each wave column in it, each
+ * root's rect, and each edge's path. Coordinates are SVG user units.
+ */
+export function estateLayout(answer) {
+  const boxes = [];
+  const at = new Map(); // "project\u0000root" -> rect
+  let x = PAD;
+  let height = 0;
+  for (const p of projectOrder(answer)) {
+    const run = p.run;
+    const waves = run ? wavesOf(run) : [];
+    const rows = run ? Math.max(1, ...waves.map((n) => run.roots.filter((r) => r.wave === n).length)) : 0;
+    const w = run && waves.length ? waves.length * COL_W + PAD * 2 : NO_RUN_W;
+    const h = run ? HEAD_H + WAVE_H + rows * ROW_H + PAD : HEAD_H + PAD;
+    const box = { project: p.project, x, y: PAD, w, h, waves: [] };
+    if (run) {
+      waves.forEach((n, i) => {
+        const wx = x + PAD + i * COL_W;
+        const meta = run.waves.find((v) => v.number === n);
+        const roots = run.roots
+          .filter((r) => r.wave === n)
+          .sort((a, b) => (a.root < b.root ? -1 : 1))
+          .map((r, j) => {
+            const rect = { root: r.root, x: wx, y: PAD + HEAD_H + WAVE_H + j * ROW_H, w: COL_W - 16, h: ROW_H - 6 };
+            at.set(`${p.project}\u0000${r.root}`, rect);
+            return rect;
+          });
+        box.waves.push({ number: n, x: wx, y: PAD + HEAD_H, state: meta ? meta.state : "not-started", roots });
+      });
+    }
+    boxes.push(box);
+    x += w + GAP;
+    height = Math.max(height, box.y + h);
+  }
+  const edges = [];
+  for (const e of answer.edges || []) {
+    const a = at.get(`${e.from.project}\u0000${e.from.root}`);
+    const b = at.get(`${e.to.project}\u0000${e.to.root}`);
+    if (!a || !b) continue;
+    const x1 = a.x + a.w;
+    const y1 = a.y + a.h / 2;
+    const x2 = b.x;
+    const y2 = b.y + b.h / 2;
+    const bend = Math.max(36, Math.abs(x2 - x1) / 3);
+    edges.push({ from: e.from, to: e.to, cross: !!e.cross, d: `M${x1},${y1} C${x1 + bend},${y1} ${x2 - bend},${y2} ${x2},${y2}` });
+  }
+  return { width: Math.max(x - GAP + PAD, NO_RUN_W + PAD * 2), height: height + PAD, boxes, edges };
+}
+
+const plural = (n, one, many = `${one}s`) => `${n} ${n === 1 ? one : many}`;
+
+/** terragucci's counts for a project, with their age and source. */
+export function countsLine(p, now = new Date()) {
+  if (!p.counts) return { text: p.status === "not-in-estate" ? "not in estate.json" : "no counts", title: p.missing || "" };
+  const c = p.counts;
+  return {
+    text: `${plural(c.drifted, "root")} drifted · ${c.failed} failed · ${plural(c.waiting, "wave")} waiting · ${ago(c.dated.at, now)}`,
+    title: `from ${c.dated.key}, generated ${clock(c.dated.at, now)} (${ago(c.dated.at, now)}); not live`,
+  };
+}
+
+/** Which run view the box was drawn from, or why it has none. */
+export function runLine(p, now = new Date()) {
+  if (p.run) {
+    return {
+      text: `run view ${p.run.commit.slice(0, 12)} · updated ${ago(p.run.updated, now)}`,
+      title: `${p.run.key}, the run view of ${p.run.commit}, named by estate.json's ${p.run.from === "run_view" ? "run_view" : "newest apply"}; a wave last wrote it ${clock(p.run.updated, now)}`,
+      tone: "ok",
+    };
+  }
+  if (p.refused) return { text: "run view refused", title: `${p.refused.error}\n${p.refused.remedy}`, tone: "bad" };
+  return { text: "no run view", title: p.missing || "no run view", tone: "none" };
+}
+
+/** A waiting wave as a line and its approve command. */
+export function waitingRows(p, now = new Date()) {
+  return (p.waiting || []).map((w) => ({
+    text: `wave ${w.wave} waiting since ${clock(w.since, now)}, ${ago(w.since, now)} · commit ${w.commit.slice(0, 12)}${w.digest ? ` · plan ${String(w.digest).replace(/^jcs1-sha256:/, "").slice(0, 12)}` : ""}`,
+    title: `from ${w.dated.key}, generated ${clock(w.dated.at, now)}`,
+    command: w.command,
+    digestKnown: !!w.digest,
+    report: w.report,
+  }));
+}
+
+/** The line over the picture: whose estate, how old, how checked. */
+export function estateLegend(answer, now = new Date()) {
+  const cross = (answer.edges || []).filter((e) => e.cross).length;
+  const drawn = answer.projects.filter((p) => p.run).length;
+  const checked = (v) => (v.by === "schema" ? `terragucci ${v.terragucci}'s schema` : "a structural check");
+  return {
+    text: `terragucci estate of ${plural(answer.projects.length, "project")}, not live · estate.json generated ${ago(answer.estate.generated, now)} · ${drawn} drawn from a run view · ${plural(cross, "read")} between projects`,
+    title: [`read from ${answer.source} (${answer.gets} GETs)`, `estate.json checked with ${checked(answer.validation.estate)}`, `run views checked with ${checked(answer.validation.run)}`, `config: ${answer.config}`].join("\n"),
+  };
+}
+
+// ---------------------------------------------------------------------------
+// The DOM. Text only, never innerHTML: every string here came from a bucket.
+// ---------------------------------------------------------------------------
+
+const SVG = "http://www.w3.org/2000/svg";
+
+function el(doc, tag, cls, text) {
+  const e = doc.createElement(tag);
+  if (cls) e.className = cls;
+  if (text !== undefined) e.textContent = text;
+  return e;
+}
+function svgEl(doc, tag, attrs = {}, text) {
+  const e = doc.createElementNS(SVG, tag);
+  for (const [k, v] of Object.entries(attrs)) e.setAttribute(k, String(v));
+  if (text !== undefined) e.textContent = text;
+  return e;
+}
+function link(doc, text, href) {
+  const a = el(doc, "a", "", text);
+  a.href = href;
+  a.target = "_blank";
+  a.rel = "noopener";
+  return a;
+}
+function titled(doc, node, title) {
+  if (title) node.appendChild(svgEl(doc, "title", {}, title));
+  return node;
+}
+
+/** The picture: boxes, wave columns, roots and edges. */
+export function renderEstateSvg(answer, now = new Date(), doc = document) {
+  const L = estateLayout(answer);
+  const svg = svgEl(doc, "svg", { width: L.width, height: L.height, viewBox: `0 0 ${L.width} ${L.height}`, class: "tg-estate-svg", role: "img", "aria-label": "terragucci estate: projects, their roots by wave, and the reads between them" });
+  const defs = svgEl(doc, "defs");
+  const marker = svgEl(doc, "marker", { id: "tg-estate-arrow", viewBox: "0 0 10 10", refX: 9, refY: 5, markerWidth: 7, markerHeight: 7, orient: "auto-start-reverse" });
+  marker.appendChild(svgEl(doc, "path", { d: "M0,0 L10,5 L0,10 z", fill: "var(--edge)" }));
+  defs.appendChild(marker);
+  svg.appendChild(defs);
+  const byName = new Map(answer.projects.map((p) => [p.project, p]));
+  for (const b of L.boxes) {
+    const p = byName.get(b.project);
+    const g = svgEl(doc, "g", { class: "tg-project", "data-project": b.project });
+    g.appendChild(svgEl(doc, "rect", { x: b.x, y: b.y, width: b.w, height: b.h, rx: 6, class: `tg-project-box${p.run ? "" : " tg-no-run"}` }));
+    const name = svgEl(doc, "text", { x: b.x + PAD, y: b.y + 20, class: "tg-project-name" }, b.project);
+    if (p.index) {
+      const a = svgEl(doc, "a", { href: keyHref(answer, p.index), target: "_blank" });
+      a.appendChild(name);
+      g.appendChild(a);
+    } else g.appendChild(name);
+    const counts = countsLine(p, now);
+    g.appendChild(titled(doc, svgEl(doc, "text", { x: b.x + PAD, y: b.y + 38, class: "tg-project-counts" }, counts.text), counts.title));
+    const run = runLine(p, now);
+    g.appendChild(titled(doc, svgEl(doc, "text", { x: b.x + PAD, y: b.y + 55, class: `tg-project-run tg-${run.tone}` }, run.text), run.title));
+    for (const w of b.waves) {
+      g.appendChild(svgEl(doc, "text", { x: w.x, y: w.y + 14, class: `tg-wave-label tg-wave-${w.state}`, "data-wave": w.number }, `wave ${w.number} · ${w.state === "not-started" ? "not started" : w.state}`));
+      for (const r of w.roots) {
+        const node = svgEl(doc, "g", { class: "tg-root-node", "data-root": r.root });
+        node.appendChild(svgEl(doc, "rect", { x: r.x, y: r.y, width: r.w, height: r.h, rx: 4 }));
+        node.appendChild(titled(doc, svgEl(doc, "text", { x: r.x + 6, y: r.y + r.h / 2 + 4 }, r.root.length > 24 ? `…${r.root.slice(-23)}` : r.root), `${b.project}: ${r.root}, wave ${w.number}`));
+        g.appendChild(node);
+      }
+    }
+    svg.appendChild(g);
+  }
+  for (const e of L.edges) {
+    const path = svgEl(doc, "path", { d: e.d, class: `tg-edge${e.cross ? " tg-edge-cross" : ""}`, "marker-end": "url(#tg-estate-arrow)", "data-from": `${e.from.project} ${e.from.root}`, "data-to": `${e.to.project} ${e.to.root}` });
+    svg.appendChild(titled(doc, path, `${e.to.project}: ${e.to.root} reads ${e.from.project}: ${e.from.root}`));
+  }
+  return svg;
+}
+
+/** Draw the whole view into `host`. `copy(text, buttonEl)` puts a line on the clipboard. */
+export function renderEstate(host, answer, { copy = () => {}, refresh, now = new Date(), doc = document } = {}) {
+  host.replaceChildren();
+  if (!answer || answer.error) {
+    host.append(el(doc, "div", "tg-refusal", answer ? answer.error : "the estate was not read"), el(doc, "div", "tg-legend", (answer && answer.remedy) || ""));
+    return;
+  }
+  const lg = estateLegend(answer, now);
+  const head = el(doc, "div", "tg-legend", lg.text);
+  head.title = lg.title;
+  const top = el(doc, "div", "tg-estate-head");
+  top.append(head, link(doc, "terragucci's estate page", keyHref(answer, answer.estate.html)));
+  if (refresh) {
+    const again = el(doc, "button", "", "Read again");
+    again.addEventListener("click", refresh);
+    top.appendChild(again);
+  }
+  host.appendChild(top);
+  const wrap = el(doc, "div", "tg-estate-graph");
+  wrap.appendChild(renderEstateSvg(answer, now, doc));
+  host.appendChild(wrap);
+  const list = el(doc, "div", "tg-estate-projects");
+  const copyRow = (text) => {
+    const row = el(doc, "div", "tg-estate-cmd");
+    const code = el(doc, "code", "tg-command", text);
+    const b = el(doc, "button", "", "Copy");
+    b.title = "Copy the line and run it at your shell. behold runs nothing here.";
+    b.addEventListener("click", () => copy(text, b));
+    row.append(code, b);
+    return row;
+  };
+  for (const p of projectOrder(answer)) {
+    const card = el(doc, "section", "tg-estate-project");
+    card.dataset.project = p.project;
+    const title = el(doc, "div", "tg-estate-title", p.project);
+    card.appendChild(title);
+    const links = el(doc, "div", "tg-legend");
+    const parts = [];
+    if (p.index) parts.push(link(doc, "its index", keyHref(answer, p.index)));
+    parts.push(link(doc, "estate.html", keyHref(answer, answer.estate.html)));
+    if (p.run) parts.push(link(doc, "run view", keyHref(answer, p.run.page)));
+    parts.forEach((a, i) => links.append(...(i ? [" · ", a] : [a])));
+    card.appendChild(links);
+    const counts = countsLine(p, now);
+    const c = el(doc, "div", "tg-estate-counts", counts.text);
+    c.title = counts.title;
+    card.appendChild(c);
+    const run = runLine(p, now);
+    const r = el(doc, "div", `tg-estate-run tg-${run.tone}`, run.tone === "ok" ? run.text : `${run.text}: ${p.refused ? p.refused.error : p.missing || ""}`);
+    r.title = run.title;
+    card.appendChild(r);
+    for (const w of waitingRows(p, now)) {
+      const box = el(doc, "div", "ws-gate tg-wave");
+      const t = el(doc, "div", "ws-gate-facts", w.text);
+      t.title = w.title;
+      box.append(t, copyRow(w.command));
+      const note = el(doc, "div", "ws-gate-note", w.digestKnown ? "Run it in the project's own checkout: the approval is a signed git record bound to this plan digest. behold does not approve." : "Run it in the project's own checkout, with the plan digest from the wave's report. behold does not approve.");
+      box.appendChild(note);
+      if (w.report) {
+        const l = el(doc, "div", "ws-gate-note");
+        l.appendChild(link(doc, "report", keyHref(answer, w.report)));
+        box.appendChild(l);
+      }
+      card.appendChild(box);
+    }
+    if (p.checkout) {
+      card.appendChild(el(doc, "div", "tg-legend", `checked out at ${p.checkout.path}; serve it to see its roots:`));
+      card.appendChild(copyRow(p.checkout.command));
+    }
+    list.appendChild(card);
+  }
+  host.appendChild(list);
+}
+
+/**
+ * Once, at boot: when /api/project names a terragucci control repo, read the
+ * estate and draw it in a layer over the graph area. `fetchUrl(url)` is
+ * app.js's apiFetch, `copy` its copyToClipboard.
+ */
+export async function initTerragucciEstate({ fetchUrl, copy, doc = document } = {}) {
+  const project = await fetchUrl("/api/project").then((r) => r.json()).catch(() => ({}));
+  if (!project.terragucciControl || !project.terragucciReports) return;
+  const graph = doc.getElementById("graph");
+  if (!graph || !graph.parentElement) return;
+  let host = doc.getElementById("tg-estate");
+  if (!host) {
+    host = el(doc, "div");
+    host.id = "tg-estate";
+    graph.parentElement.insertBefore(host, graph.nextSibling);
+  }
+  const load = async (fresh) => {
+    const answer = await fetchUrl(`/api/terragucci/estate${fresh ? "?fresh=1" : ""}`)
+      .then((r) => r.json())
+      .catch((e) => ({ error: String(e), code: "terragucci-report", remedy: "" }));
+    renderEstate(host, answer, { copy, refresh: () => load(true), doc });
+  };
+  await load(false);
+}

package/web/terragucci-estate.test.js

@@ -0,0 +1,114 @@
+import { describe, it, expect } from "vitest";
+import { COL_W, countsLine, estateLayout, estateLegend, keyHref, NO_RUN_W, PAD, projectOrder, runLine, waitingRows, wavesOf } from "./terragucci-estate.js";
+
+// #509: the control repo view's layout and words, over an answer shaped like
+// /api/terragucci/estate's.
+const NOW = new Date("2026-10-08T12:00:00.000Z");
+const dated = (at, key = "estate.json") => ({ key, at });
+const answer = {
+  source: "/b",
+  kind: "dir",
+  config: "/c/terragucci.yml",
+  validation: { estate: { by: "structural" }, run: { by: "schema", terragucci: "0.4.7" } },
+  read: NOW.toISOString(),
+  estate: { key: "estate.json", html: "estate.html", generated: "2026-10-08T10:00:00.000Z" },
+  gets: 4,
+  files: "/api/terragucci/file?key=",
+  projects: [
+    {
+      project: "github.com/acme/shop",
+      status: "ok",
+      index: "github.com/acme/shop/index.html",
+      counts: { drifted: 2, failed: 0, waiting: 1, dated: dated("2026-10-08T10:00:00.000Z") },
+      waiting: [{ wave: 2, commit: "d3e4f5a6b7c8d9e0", since: "2026-10-08T09:31:00.000Z", age_seconds: 1740, digest: "jcs1-sha256:7777777777777777", command: "npx terragucci approve wave-2 --plan jcs1-sha256:7777777777777777", dated: dated("2026-10-08T10:00:00.000Z") }],
+      run: {
+        commit: "d3e4f5a6b7c8d9e0",
+        updated: "2026-10-08T09:31:00.000Z",
+        from: "run_view",
+        key: "github.com/acme/shop/runs/d3/run.json",
+        page: "github.com/acme/shop/runs/d3/run.html",
+        roots: [
+          { root: "app", wave: 1, reads: [] },
+          { root: "worker", wave: 2, reads: ["app"] },
+          { root: "cron", wave: 2, reads: ["app"] },
+        ],
+        waves: [
+          { number: 1, roots: ["app"], reads: [], state: "applied", gate: "wave-1" },
+          { number: 2, roots: ["cron", "worker"], reads: [1], state: "waiting", gate: "wave-2" },
+        ],
+        dated: dated("2026-10-08T09:31:00.000Z", "github.com/acme/shop/runs/d3/run.json"),
+      },
+      configured: true,
+    },
+    {
+      project: "github.com/acme/network",
+      status: "ok",
+      counts: { drifted: 0, failed: 0, waiting: 0, dated: dated("2026-10-08T10:00:00.000Z") },
+      waiting: [],
+      run: { commit: "a1b2", updated: "2026-10-07T12:10:00.000Z", from: "apply", key: "k", page: "p", roots: [{ root: "vpc", wave: 1, reads: [] }], waves: [{ number: 1, roots: ["vpc"], reads: [], state: "applied", gate: "wave-1" }], dated: dated("2026-10-07T12:10:00.000Z", "k") },
+      configured: true,
+    },
+    { project: "github.com/acme/billing", status: "ok", counts: { drifted: 0, failed: 0, waiting: 0, dated: dated("2026-10-08T10:00:00.000Z") }, waiting: [], missing: "no run view at github.com/acme/billing/runs/f0/run.json", configured: true },
+    { project: "github.com/acme/legacy", status: "ok", counts: { drifted: 0, failed: 1, waiting: 0, dated: dated("2026-10-08T10:00:00.000Z") }, waiting: [], refused: { error: "k is not a terragucci terragucci.run/v1 document", code: "terragucci-report", remedy: "r" }, configured: false },
+  ],
+  edges: [
+    { from: { project: "github.com/acme/shop", root: "app" }, to: { project: "github.com/acme/shop", root: "worker" }, cross: false },
+    { from: { project: "github.com/acme/shop", root: "app" }, to: { project: "github.com/acme/shop", root: "cron" }, cross: false },
+    { from: { project: "github.com/acme/network", root: "vpc" }, to: { project: "github.com/acme/shop", root: "app" }, cross: true },
+  ],
+};
+
+describe("the control repo view (#509)", () => {
+  it("puts a project before the projects that read its roots", () => {
+    expect(projectOrder(answer).map((p) => p.project)).toEqual(["github.com/acme/network", "github.com/acme/shop", "github.com/acme/billing", "github.com/acme/legacy"]);
+  });
+
+  it("lays out one box per project, roots by wave, and keeps a project with no run view as a box", () => {
+    const L = estateLayout(answer);
+    expect(L.boxes.map((b) => b.project)).toEqual(["github.com/acme/network", "github.com/acme/shop", "github.com/acme/billing", "github.com/acme/legacy"]);
+    const shop = L.boxes[1];
+    expect(shop.w).toBe(2 * COL_W + 2 * PAD);
+    expect(shop.waves.map((w) => [w.number, w.state, w.roots.map((r) => r.root)])).toEqual([
+      [1, "applied", ["app"]],
+      [2, "waiting", ["cron", "worker"]],
+    ]);
+    expect(L.boxes[2].waves).toEqual([]);
+    expect(L.boxes[2].w).toBe(NO_RUN_W);
+    // Boxes do not overlap, and the cross edge runs left to right.
+    for (let i = 1; i < L.boxes.length; i++) expect(L.boxes[i].x).toBeGreaterThan(L.boxes[i - 1].x + L.boxes[i - 1].w);
+    expect(L.edges).toHaveLength(3);
+    const cross = L.edges.find((e) => e.cross);
+    const n = cross.d.match(/-?[\d.]+/g).map(Number);
+    expect(n[6]).toBeGreaterThan(n[0]); // the end's x is right of the start's
+    expect(L.width).toBeGreaterThan(L.boxes[3].x + L.boxes[3].w);
+  });
+
+  it("skips an edge to a root no box draws", () => {
+    const L = estateLayout({ ...answer, edges: [{ from: { project: "github.com/acme/billing", root: "x" }, to: { project: "github.com/acme/shop", root: "app" }, cross: true }] });
+    expect(L.edges).toEqual([]);
+  });
+
+  it("dates every count and run view, and says when a project has none", () => {
+    const shop = answer.projects[0];
+    expect(countsLine(shop, NOW)).toEqual({ text: "2 roots drifted · 0 failed · 1 wave waiting · 2h ago", title: "from estate.json, generated 10:00 UTC (2h ago); not live" });
+    expect(runLine(shop, NOW).text).toBe("run view d3e4f5a6b7c8 · updated 2h ago");
+    expect(runLine(answer.projects[2], NOW)).toMatchObject({ text: "no run view", tone: "none" });
+    expect(runLine(answer.projects[3], NOW)).toMatchObject({ text: "run view refused", tone: "bad" });
+    expect(countsLine({ status: "not-in-estate", missing: "m" }, NOW).text).toBe("not in estate.json");
+  });
+
+  it("offers a waiting wave's approve line to copy, with its age", () => {
+    expect(waitingRows(answer.projects[0], NOW)).toEqual([
+      { text: "wave 2 waiting since 09:31 UTC, 2h ago · commit d3e4f5a6b7c8 · plan 777777777777", title: "from estate.json, generated 10:00 UTC", command: "npx terragucci approve wave-2 --plan jcs1-sha256:7777777777777777", digestKnown: true, report: undefined },
+    ]);
+  });
+
+  it("says whose estate, how old and how checked, and opens keys through the file route", () => {
+    const lg = estateLegend(answer, NOW);
+    expect(lg.text).toBe("terragucci estate of 4 projects, not live · estate.json generated 2h ago · 2 drawn from a run view · 1 read between projects");
+    expect(lg.title).toContain("4 GETs");
+    expect(lg.title).toContain("terragucci 0.4.7's schema");
+    expect(keyHref(answer, "github.com/acme/shop/index.html")).toBe("/api/terragucci/file?key=github.com%2Facme%2Fshop%2Findex.html");
+    expect(wavesOf({ waves: [{ number: 3 }], roots: [{ wave: 1 }] })).toEqual([1, 3]);
+  });
+});

package/web/terragucci-lifecycle.js

@@ -0,0 +1,143 @@
+// #505: the chant/lifecycle lane of a terragucci repo, in words. Pure: app.js
+// fetches /api/terragucci/lifecycle (and hears /api/terragucci/events), then
+// renders what these functions return.
+//
+// Every gate and lock says which commit of chant/lifecycle it came from and
+// how old that commit is, and the lane's line says when behold last read the
+// branch and how (fetched from origin, or the checkout's own copy when the
+// fetch failed). Nothing here is painted as live, and nothing approves,
+// locks or unlocks: a waiting wave offers the line a person runs.
+
+import { ago, clock } from "./terragucci.js";
+
+const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
+
+/** Where an entry came from: "chant/lifecycle 1a2b3c4d5e6f, committed 09:00 UTC, 2h ago". */
+export function sourceWords(source, now = new Date()) {
+  return `chant/lifecycle ${short(source.commit)}, committed ${clock(source.committed, now)}, ${ago(source.committed, now)}`;
+}
+
+/** The lane's line under the tab title: what was read, how, and when. `title` carries the note. */
+export function laneLegend(lane, now = new Date(), polled = null) {
+  if (!lane || lane.error) return { text: `chant/lifecycle not read${lane && lane.error ? `: ${lane.error}` : ""}`, title: "", tone: "refusal" };
+  const looked = polled && polled.at && polled.at > lane.read.at ? polled.at : lane.read.at;
+  const when = `read ${ago(looked, now)}`;
+  if (!lane.found) {
+    const text = lane.via === "none" ? `chant/lifecycle unknown: behold could not fetch it · ${when}` : `no chant/lifecycle branch yet: no gate asked, no root locked · ${when}`;
+    return { text, title: lane.note, tone: lane.via === "none" ? "refusal" : "quiet" };
+  }
+  const how = lane.via === "fetch" ? "fetched from origin" : "the checkout's origin/chant/lifecycle, as of its last git fetch (behold's fetch failed)";
+  return {
+    text: `chant/lifecycle at ${short(lane.commit.sha)}, committed ${ago(lane.commit.committed, now)} · ${when}, ${how}`,
+    title: [lane.note, lane.fetch && lane.fetch.error ? `fetch: ${lane.fetch.error}` : ""].filter(Boolean).join("\n"),
+    tone: lane.via === "fetch" ? "quiet" : "stale",
+  };
+}
+
+const TITLE = {
+  waiting: (g) => `wave ${g.wave} waits for an approval`,
+  expired: (g) => `wave ${g.wave}'s request for an approval expired`,
+  approved: (g) => `wave ${g.wave} approved by ${g.approval.by}, not applied yet`,
+  applied: (g) => `wave ${g.wave} applied`,
+  failed: (g) => `wave ${g.wave}'s apply failed`,
+};
+
+/** Each wave's gate as a card: its state, who and when, the digest, the commit it was read from, and for a waiting wave the line to run. No button. */
+export function laneGateCards(lane, now = new Date()) {
+  if (!lane || !lane.found) return [];
+  return lane.gates.map((g) => {
+    const facts = [];
+    if (g.pending) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
+    if (g.approval) facts.push(`approved by ${g.approval.by}${g.approval.signed ? " (signed)" : ""}${g.approval.via ? ` via ${g.approval.via}` : ""} ${clock(g.approval.at, now)}, ${ago(g.approval.at, now)}`);
+    if (g.applied) facts.push(`${g.applied.result === "failed" ? "apply failed" : "applied"} ${clock(g.applied.finished || g.applied.at, now)}, ${ago(g.applied.finished || g.applied.at, now)}`);
+    if (g.digest) facts.push(`plan ${short(g.digest)}`);
+    return {
+      wave: g.wave,
+      state: g.state,
+      tone: g.state === "waiting" ? "wave" : g.state === "failed" ? "failed" : g.state === "expired" ? "none" : "ok",
+      title: TITLE[g.state] ? TITLE[g.state](g) : `wave ${g.wave}: ${g.state}`,
+      facts: facts.join(" · "),
+      source: sourceWords(g.source, now),
+      ...(g.command ? { command: g.command, note: "An approval is a signed git record bound to this plan digest: run the line at your shell. behold does not approve." } : {}),
+      ...(g.pending && g.pending.url ? { job: g.pending.url } : {}),
+    };
+  });
+}
+
+/** Each locked root: who holds it and since when, and the commit it was read from. */
+export function laneLockRows(lane, now = new Date()) {
+  if (!lane || !lane.found) return [];
+  return lane.locks.map((l) => {
+    const how = l.stage === "plan" ? "its plan" : l.via === "lock" ? "/terragucci lock" : "an apply";
+    return {
+      root: l.root,
+      text: `locked by PR #${l.pr} (${l.by}, by ${how}) ${clock(l.at, now)}, ${ago(l.at, now)}`,
+      title: `head ${short(l.head)}\nfrom ${sourceWords(l.source, now)}\nUnlocking is a pull request comment (/terragucci unlock), never behold's.`,
+    };
+  });
+}
+
+/**
+ * The lane in the Terragucci tab: the line, a card per gate, a row per lock.
+ * `ui` lends app.js's own `button`, `copy` and `link`, so the cards look like
+ * the reports' wave cards. A Copy button is the only control: no approve,
+ * lock or unlock.
+ */
+export function renderLane(host, lane, polled, now, ui) {
+  const lg = laneLegend(lane, now, polled);
+  const head = document.createElement("div");
+  head.className = lg.tone === "refusal" ? "tg-refusal" : "tg-legend";
+  head.textContent = lg.text;
+  head.title = lg.title;
+  host.appendChild(head);
+  if (polled && polled.reports && polled.reports.error) {
+    const e = document.createElement("div");
+    e.className = "tg-legend";
+    e.textContent = `the reports' index could not be checked: ${polled.reports.error}`;
+    host.appendChild(e);
+  }
+  for (const g of laneGateCards(lane, now)) {
+    const box = document.createElement("div");
+    box.className = `ws-gate tg-lane-gate tg-${g.tone}`;
+    const title = document.createElement("div");
+    title.className = "ws-gate-title";
+    title.textContent = g.title;
+    const facts = document.createElement("div");
+    facts.className = "ws-gate-facts";
+    facts.textContent = g.facts;
+    const src = document.createElement("div");
+    src.className = "ws-gate-note";
+    src.textContent = `from ${g.source}`;
+    box.append(title, facts, src);
+    if (g.command) {
+      const cmd = document.createElement("code");
+      cmd.className = "tg-command";
+      cmd.textContent = g.command;
+      const copy = ui.button("Copy", "", () => ui.copy(g.command, copy));
+      copy.title = "Copy the line. Run it at your shell: the approval is yours, signed, in git.";
+      const note = document.createElement("div");
+      note.className = "ws-gate-note";
+      note.textContent = g.note;
+      box.append(cmd, copy, note);
+    }
+    if (g.job) {
+      const links = document.createElement("div");
+      links.className = "ws-gate-note";
+      links.appendChild(ui.link("job", g.job));
+      box.appendChild(links);
+    }
+    host.appendChild(box);
+  }
+  for (const l of laneLockRows(lane, now)) {
+    const row = document.createElement("div");
+    row.className = "tg-root tg-lock";
+    const path = document.createElement("div");
+    path.className = "tg-path";
+    path.textContent = l.root;
+    const what = document.createElement("div");
+    what.textContent = l.text;
+    what.title = l.title;
+    row.append(path, what);
+    host.appendChild(row);
+  }
+}

package/web/terragucci-lifecycle.test.js

@@ -0,0 +1,60 @@
+import { describe, it, expect } from "vitest";
+import { laneGateCards, laneLegend, laneLockRows, sourceWords } from "./terragucci-lifecycle.js";
+
+const NOW = new Date("2026-10-09T12:00:00Z");
+const source = { branch: "chant/lifecycle", commit: "1a2b3c4d5e6f7a8b", committed: "2026-10-09T10:00:00Z", path: "_gates/tf-apply.jsonl" };
+const D = `jcs1-sha256:${"2".repeat(64)}`;
+const lane = (over = {}) => ({
+  branch: "chant/lifecycle",
+  found: true,
+  via: "fetch",
+  fetch: { ok: true },
+  commit: { sha: "1a2b3c4d5e6f7a8b", committed: "2026-10-09T10:00:00Z" },
+  read: { at: "2026-10-09T11:59:00Z" },
+  gates: [
+    { gate: "wave-1", wave: 1, state: "approved", digest: D, approval: { by: "alice", at: "2026-10-09T09:00:00Z", signed: true }, records: [], source },
+    { gate: "wave-2", wave: 2, state: "waiting", digest: D, pending: { timestamp: "2026-10-09T10:00:00Z", expiresAt: "2099-01-01T00:00:00Z" }, records: [], command: `npx terragucci approve wave-2 --plan ${D}`, source },
+  ],
+  locks: [{ root: "envs/prod/orders", pr: 12, by: "carol", at: "2026-10-09T07:00:00Z", head: "abc123", source: { ...source, path: "_locks/tf-apply.json" } }],
+  note: "chant/lifecycle as fetched",
+  ...over,
+});
+
+describe("the chant/lifecycle lane, dated (#505)", () => {
+  it("names the commit an entry came from and its age", () => {
+    expect(sourceWords(source, NOW)).toBe("chant/lifecycle 1a2b3c4d5e6f, committed 10:00 UTC, 2h ago");
+  });
+
+  it("says when behold last read the branch, and how", () => {
+    expect(laneLegend(lane(), NOW).text).toBe("chant/lifecycle at 1a2b3c4d5e6f, committed 2h ago · read 1m ago, fetched from origin");
+    const stale = laneLegend(lane({ via: "checkout-ref", fetch: { ok: false, error: "Could not resolve host" } }), NOW);
+    expect(stale.text).toContain("the checkout's origin/chant/lifecycle");
+    expect(stale.title).toContain("Could not resolve host");
+    expect(stale.tone).toBe("stale");
+    // A later poll moves "read" forward without a new lane read.
+    expect(laneLegend(lane({ read: { at: "2026-10-09T10:00:00Z" } }), NOW, { at: "2026-10-09T11:59:30Z" }).text).toContain("read just now");
+  });
+
+  it("says no branch is no branch, and an unreadable one is unknown", () => {
+    expect(laneLegend(lane({ found: false, gates: [], locks: [] }), NOW).text).toMatch(/^no chant\/lifecycle branch yet/);
+    expect(laneLegend(lane({ found: false, via: "none" }), NOW).text).toMatch(/^chant\/lifecycle unknown/);
+    expect(laneGateCards(lane({ found: false }), NOW)).toEqual([]);
+  });
+
+  it("words each gate with its state, its source and, when it waits, the line to run", () => {
+    const [one, two] = laneGateCards(lane(), NOW);
+    expect(one.title).toBe("wave 1 approved by alice, not applied yet");
+    expect(one.facts).toContain("approved by alice (signed) 09:00 UTC, 3h ago");
+    expect(one.command).toBeUndefined();
+    expect(two.title).toBe("wave 2 waits for an approval");
+    expect(two.command).toBe(`npx terragucci approve wave-2 --plan ${D}`);
+    expect(two.source).toBe("chant/lifecycle 1a2b3c4d5e6f, committed 10:00 UTC, 2h ago");
+    expect(two.tone).toBe("wave");
+  });
+
+  it("words a lock with its holder, its age and its source", () => {
+    const [l] = laneLockRows(lane(), NOW);
+    expect(l.text).toBe("locked by PR #12 (carol, by an apply) 07:00 UTC, 5h ago");
+    expect(l.title).toContain("chant/lifecycle 1a2b3c4d5e6f");
+  });
+});