@intentius/behold 0.24.0 → 0.26.0

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,235 @@
+// #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}${lane.approval && lane.approval.inferred ? ` · approval mode ${lane.approval.mode} at base, for the waves whose requests record none` : ""}`,
+    title: [
+      lane.note,
+      lane.approval ? `approvals counted: ${lane.approval.mode} (${lane.approval.source}${lane.approval.base ? `, base ${short(lane.approval.base)}` : ""})${lane.approval.inferred ? `; ${lane.approval.inferred}` : ""}${lane.approval.note ? `; ${lane.approval.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) => (g.applied && !g.applied.result ? `wave ${g.wave} applied (outcome not recorded)` : `wave ${g.wave} applied`),
+  failed: (g) => `wave ${g.wave}'s apply failed`,
+  refused: (g) => `wave ${g.wave} refused: an approval stands for other plans`,
+  "refused-by-policy": (g) => `wave ${g.wave} refused by policy: ${(g.denials || []).length} run${(g.denials || []).length === 1 ? "" : "s"} denied, no override counts`,
+  held: (g) => `wave ${g.wave} held on ${g.heldOn.op}/${g.heldOn.gate}${g.heldOn.heldBy ? ` by hook ${g.heldOn.heldBy.hook}` : ""}`,
+};
+
+/**
+ * Who holds a wave on another gate: the hook the fact names (`heldBy`,
+ * chant#3886), with the moment it ran at and its run; for a fact written
+ * before chant named it, the fact's description, which the hook wrote.
+ */
+export function holderWords(heldOn) {
+  if (!heldOn) return "";
+  const h = heldOn.heldBy;
+  if (h) return `held by hook ${h.hook} at ${h.moment}${h.target ? ` for ${h.target}` : ""}`;
+  return heldOn.description || "";
+}
+
+const NOTE = {
+  approve: "An approval is a signed git record bound to this plan digest: run the line at your shell. behold does not approve.",
+  answer: "This gate asks a decision point: answer it at your shell. behold does not answer.",
+  override: "An override is a person's git record with a reason, bound to this plan and these rules: run the line at your shell. behold does not override.",
+};
+
+/** The mode a wave is decided under: the one its request recorded (chant#3861), else the one read at base. */
+export function modeWords(g) {
+  if (!g.approvalMode) return "";
+  return g.approvalMode.from === "pending" ? `asked under ${g.approvalMode.mode}` : `approval mode ${g.approvalMode.mode}, read at base: its request records none`;
+}
+
+/** Who approved, and how: signed, relayed, from a pull request's review. */
+function approvalWords(a, now) {
+  const how = [
+    a.signed ? "signed" : "",
+    a.via ? `via ${a.via}` : "",
+    a.pr !== undefined ? `PR #${a.pr}${a.head ? ` at ${short(a.head)}` : ""}` : "",
+    a.reviewers && a.reviewers.length ? `reviewed by ${a.reviewers.join(", ")}` : "",
+    a.relayedBy ? `relayed by ${a.relayedBy}` : "",
+  ].filter(Boolean);
+  return `${a.by}${how.length ? ` (${how.join(", ")})` : ""} ${clock(a.at, now)}, ${ago(a.at, now)}`;
+}
+
+/** 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 = [];
+    const own = g.state !== "refused-by-policy" && g.state !== "held";
+    if (g.pending && own) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
+    if (g.pending && g.pending.description && own) facts.push(g.pending.description);
+    if (g.pending && g.pending.answer && g.state === "waiting") facts.push(`asks decision point ${g.pending.answer.point}`);
+    if (g.heldOn) facts.push(`held ${clock(g.heldOn.since, now)}, ${ago(g.heldOn.since, now)}; ${g.heldOn.op}/${g.heldOn.gate} waits${g.heldOn.digest ? ` for plan ${short(g.heldOn.digest)}` : ""}${g.heldOn.answer ? ` on decision point ${g.heldOn.answer.point}` : ""}`);
+    if (holderWords(g.heldOn)) facts.push(holderWords(g.heldOn));
+    if (g.approval) facts.push(`${g.state === "refused" ? `approved for plan ${short(g.refused && g.refused.digest) || "(none)"} by` : "approved by"} ${approvalWords(g.approval, 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)}${g.applied.review && g.applied.review.pr !== undefined ? ` under the review of PR #${g.applied.review.pr}` : ""}`);
+    if (g.digest) facts.push(`plan ${short(g.digest)}`);
+    if (g.pending && g.pending.members && g.pending.members.length) facts.push(`${g.pending.members.length} root${g.pending.members.length === 1 ? "" : "s"}: ${g.pending.members.map((m) => m.member).join(", ")}`);
+    if (g.pending && g.pending.neverOverMcp) facts.push("never approved over MCP");
+    if (modeWords(g)) facts.push(modeWords(g));
+    if (g.identity) facts.push(`identity.gates at base: only a signed approval counts${g.identity.class ? `, from class ${g.identity.class}` : ""}`);
+    if (g.spent) facts.push(`the approval of plan ${short(g.spent.planDigest)} by ${g.spent.by} was spent by its apply`);
+    const uncounted = (g.uncounted || []).map((u) => `${u.approval.by}'s approval of this plan does not count: ${u.reason}`);
+    const overrides = (g.denials || []).map((d) => ({
+      text: `${d.member}: plan ${short(d.plan)} denied by ${d.rules.join(", ")} ${clock(d.at, now)}, ${ago(d.at, now)}${d.moved ? `; ${d.moved.by} overrode an earlier plan or other rules` : ""}${d.refusals.length ? `; ${d.refusals.join("; ")}` : ""}`,
+      command: d.command,
+      ...(d.url ? { job: d.url } : {}),
+    }));
+    const commandNote = (g.state === "held" ? g.heldOn && g.heldOn.answer : g.pending && g.pending.answer) ? NOTE.answer : NOTE.approve;
+    return {
+      wave: g.wave,
+      state: g.state,
+      tone: g.state === "waiting" || g.state === "held" ? "wave" : g.state === "failed" || g.state === "refused" || g.state === "refused-by-policy" ? "failed" : g.state === "expired" ? "none" : "ok",
+      title: TITLE[g.state] ? TITLE[g.state](g) : `wave ${g.wave}: ${g.state}`,
+      facts: facts.join(" · "),
+      ...(uncounted.length ? { uncounted } : {}),
+      ...(overrides.length ? { overrides, overrideNote: NOTE.override } : {}),
+      source: sourceWords(g.source, now),
+      ...(g.command ? { command: g.command, note: commandNote } : {}),
+      ...(g.heldOn && g.heldOn.url ? { job: g.heldOn.url } : 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);
+    for (const u of g.uncounted || []) {
+      const why = document.createElement("div");
+      why.className = "ws-gate-note";
+      why.textContent = u;
+      box.appendChild(why);
+    }
+    box.appendChild(src);
+    for (const o of g.overrides || []) {
+      const what = document.createElement("div");
+      what.className = "ws-gate-note";
+      what.textContent = o.text;
+      const cmd = document.createElement("code");
+      cmd.className = "tg-command";
+      cmd.textContent = o.command;
+      const copy = ui.button("Copy", "", () => ui.copy(o.command, copy));
+      copy.title = "Copy the line. Run it at your shell, with your reason: the override is yours.";
+      box.append(what, cmd, copy);
+      if (o.job) {
+        const links = document.createElement("div");
+        links.className = "ws-gate-note";
+        links.appendChild(ui.link("job", o.job));
+        box.appendChild(links);
+      }
+    }
+    if (g.overrideNote) {
+      const n = document.createElement("div");
+      n.className = "ws-gate-note";
+      n.textContent = g.overrideNote;
+      box.appendChild(n);
+    }
+    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 or answer is yours.";
+      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,95 @@
+import { describe, it, expect } from "vitest";
+import { holderWords, 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("shows the mode a wave asked under, and says when it was read at base instead (chant#3861)", () => {
+    const [one, two] = lane().gates;
+    const g = lane({
+      approval: { mode: "ledger", source: "the default", inferred: "a wave whose pending fact records no approval mode ..." },
+      gates: [{ ...one, approvalMode: { mode: "sealed", from: "pending" } }, { ...two, approvalMode: { mode: "ledger", from: "base" } }],
+    });
+    const [a, b] = laneGateCards(g, NOW);
+    expect(a.facts).toContain("asked under sealed");
+    expect(b.facts).toContain("approval mode ledger, read at base: its request records none");
+    expect(laneLegend(g, NOW).text).toContain("approval mode ledger at base, for the waves whose requests record none");
+    expect(laneLegend(lane({ approval: { mode: "ledger", source: "the default" } }), NOW).text).not.toContain("approval mode");
+  });
+
+  it("names an identity.gates gate's class without a caveat, and a hold by its fact (chant#3862, chant#3839)", () => {
+    const [one] = lane().gates;
+    const held = { ...one, state: "held", approval: undefined, heldOn: { op: "tf-migrate", gate: "move-db", since: "2026-10-09T10:00:00Z", description: "migrate the orders table first" }, identity: { class: "human" } };
+    const [c] = laneGateCards(lane({ gates: [held] }), NOW);
+    expect(c.facts).toContain("only a signed approval counts, from class human");
+    expect(c.facts).not.toContain("chant#3862");
+    expect(c.facts).toContain("held 10:00 UTC, 2h ago; tf-migrate/move-db waits");
+    expect(c.facts).toContain("migrate the orders table first");
+    expect(c.title).toBe("wave 1 held on tf-migrate/move-db");
+  });
+
+  it("names the hook that holds a wave from the fact's heldBy, before its description (chant#3886)", () => {
+    const [one] = lane().gates;
+    const heldOn = { op: "tf-migrate", gate: "move-db", since: "2026-10-09T10:00:00Z", heldBy: { hook: "migrate", moment: "after-plan", target: "vpc" }, description: "migrate the orders table first" };
+    const [c] = laneGateCards(lane({ gates: [{ ...one, state: "held", approval: undefined, heldOn }] }), NOW);
+    expect(c.title).toBe("wave 1 held on tf-migrate/move-db by hook migrate");
+    expect(c.facts).toContain("held by hook migrate at after-plan for vpc");
+    expect(c.facts).not.toContain("migrate the orders table first");
+    expect(holderWords({ ...heldOn, heldBy: { hook: "migrate", moment: "after-plan" } })).toBe("held by hook migrate at after-plan");
+    expect(holderWords({ ...heldOn, heldBy: undefined })).toBe("migrate the orders table first");
+  });
+
+  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");
+  });
+});

package/web/terragucci-progress.js

@@ -0,0 +1,127 @@
+// #511: a choudoufu wave's progress per resource, from terragucci's run view.
+// app.js fetches /api/terragucci/progress (and hears the `progress` event on
+// /api/terragucci/events), then stamps cards and fills the panel from what
+// these functions return.
+//
+// A progress mark is dated by the records read it came from ("in flight,
+// records read 09:43 UTC, 2m ago"). It is a corner tag, never a fill: the
+// fill is the live-status channel, and this is what the wave job's last read
+// of the estates' records found, which may already be behind.
+
+import { ago, clock, hrefOf } from "./terragucci.js";
+
+export const PROGRESS_WORDS = { done: "done", "in-flight": "in flight", waiting: "waiting", "not-applied": "not applied" };
+const GLYPH = { done: "✓", "in-flight": "▶", waiting: "…", "not-applied": "✕" };
+
+/** "records read 09:43 UTC, 2m ago". */
+export function readWords(read, now = new Date()) {
+  return `records read ${clock(read, now)}, ${ago(read, now)}`;
+}
+
+/** The newest wave's mark on a card: a wave applying now outranks an earlier one. */
+export function cardProgress(marks) {
+  if (!marks || !marks.length) return null;
+  return [...marks].sort((a, b) => b.wave - a.wave)[0];
+}
+
+/** The corner tag of a card: "▶ wave 2 in flight · 2m". */
+export function progressTag(mark, now = new Date()) {
+  const s = Math.max(0, (now.getTime() - Date.parse(mark.read)) / 1000);
+  const age = s < 3600 ? `${Math.max(1, Math.round(s / 60))}m` : s < 172800 ? `${Math.round(s / 3600)}h` : `${Math.round(s / 86400)}d`;
+  return { text: `${GLYPH[mark.status]} wave ${mark.wave} ${PROGRESS_WORDS[mark.status]} · ${age}`, tone: mark.status };
+}
+
+/** One instance as a line: "module.x.aws_y.z[1] (replace): in flight", with when a read first found it done. */
+export function resourceLine(r, now = new Date()) {
+  const done = r.status === "done" && r.done_at ? ` ${clock(r.done_at, now)}` : "";
+  return `${r.address} (${r.action}): ${PROGRESS_WORDS[r.status]}${done}`;
+}
+
+/** A card's mark as sentences, for its tooltip and the inspect pane. */
+export function progressLines(mark, now = new Date()) {
+  return [`wave ${mark.wave} ${PROGRESS_WORDS[mark.status]}, ${readWords(mark.read, now)}`, ...mark.resources.map((r) => resourceLine(r, now))];
+}
+
+/** "2 of 5 done, 1 in flight, 2 waiting", plus "1 not applied" when there is one. */
+export function countsLine(counts) {
+  const total = counts.done + counts["in-flight"] + counts.waiting + counts["not-applied"];
+  return `${counts.done} of ${total} done, ${counts["in-flight"]} in flight, ${counts.waiting} waiting${counts["not-applied"] ? `, ${counts["not-applied"]} not applied` : ""}`;
+}
+
+/** The panel's rows: the run's line, then one per wave with progress. Never "live". */
+export function progressRows(answer, now = new Date()) {
+  if (!answer || answer.error) return { head: answer && answer.error ? `apply progress not read: ${answer.error}` : "", title: (answer && answer.remedy) || "", waves: [] };
+  if (!answer.run || !answer.run.present) return { head: answer.absent || "", title: "", waves: [] };
+  const head = `apply progress of ${answer.run.commit.slice(0, 12)}, from terragucci's run view${answer.watching ? " · asked again while a wave moves" : " · settled"}`;
+  const title = [`${answer.run.key}, read ${ago(answer.read, now)}`, answer.unmatched.length ? `no card: ${answer.unmatched.map((u) => `${u.root}: ${u.address}`).join(", ")}` : ""].filter(Boolean).join("\n");
+  return {
+    head,
+    title,
+    html: answer.run.html,
+    waves: answer.waves.map((w) => ({
+      number: w.number,
+      text: `wave ${w.number} ${w.state}: ${countsLine(w.counts)}`,
+      read: readWords(w.read, now),
+      tone: w.counts["not-applied"] ? "not-applied" : w.counts["in-flight"] ? "in-flight" : w.counts.waiting ? "waiting" : "done",
+      lines: w.resources.map((r) => `${r.root}: ${resourceLine(r, now)}`),
+    })),
+  };
+}
+
+const FILL = { done: "var(--muted)", "in-flight": "var(--pending)", waiting: "var(--muted)", "not-applied": "var(--degraded)" };
+
+/** Stamp each card's progress tag at its top-right corner. Replaces the previous stamps. */
+export function stampProgress(svg, answer, now = new Date()) {
+  if (!svg) return;
+  for (const old of svg.querySelectorAll("[data-tg-progress]")) old.remove();
+  if (!answer || !answer.cards) return;
+  for (const [id, marks] of Object.entries(answer.cards)) {
+    const g = svg.querySelector('[data-node-id="' + CSS.escape(id) + '"]');
+    const mark = cardProgress(marks);
+    if (!g || !mark) continue;
+    const rect = g.querySelector("rect");
+    const box = rect && rect.getBBox ? rect.getBBox() : null;
+    const t = progressTag(mark, now);
+    const tag = document.createElementNS("http://www.w3.org/2000/svg", "text");
+    tag.setAttribute("data-tg-progress", t.tone);
+    tag.setAttribute("x", String((box ? box.x + box.width : 150) - 10));
+    tag.setAttribute("y", String((box ? box.y : 0) + 14));
+    tag.setAttribute("text-anchor", "end");
+    tag.setAttribute("font-size", "10");
+    tag.setAttribute("fill", FILL[t.tone]);
+    tag.textContent = t.text;
+    const title = document.createElementNS("http://www.w3.org/2000/svg", "title");
+    title.textContent = progressLines(mark, now).join("\n") + "\n(from terragucci's run view, as of that read: not live)";
+    tag.appendChild(title);
+    g.appendChild(tag);
+  }
+}
+
+/** The panel section: the run's line, then each wave's counts and read time, its resources folded. */
+export function progressSection(answer, now, link) {
+  const rows = progressRows(answer, now);
+  const box = document.createElement("div");
+  box.className = "tg-progress";
+  if (!rows.head) return box;
+  const head = document.createElement("div");
+  head.className = "tg-legend";
+  head.textContent = rows.head + " ";
+  if (rows.title) head.title = rows.title;
+  if (rows.html && link) head.appendChild(link("run", hrefOf(answer, rows.html)));
+  box.appendChild(head);
+  for (const w of rows.waves) {
+    const d = document.createElement("details");
+    d.className = `tg-progress-wave tg-progress-${w.tone}`;
+    const s = document.createElement("summary");
+    s.textContent = `${w.text} · ${w.read}`;
+    d.appendChild(s);
+    for (const line of w.lines) {
+      const row = document.createElement("div");
+      row.className = "ws-gate-note";
+      row.textContent = line;
+      d.appendChild(row);
+    }
+    box.appendChild(d);
+  }
+  return box;
+}

package/web/terragucci-progress.test.js

@@ -0,0 +1,59 @@
+import { describe, it, expect } from "vitest";
+import { cardProgress, countsLine, progressLines, progressRows, progressTag, resourceLine } from "./terragucci-progress.js";
+
+// #511: the progress words. Every mark is dated by the records read it came
+// from; none says "live".
+const NOW = new Date("2026-10-08T09:45:00Z");
+const mark = (over = {}) => ({
+  wave: 2,
+  state: "applying",
+  read: "2026-10-08T09:43:00.000Z",
+  status: "in-flight",
+  counts: { done: 1, "in-flight": 1, waiting: 0, "not-applied": 0 },
+  resources: [
+    { root: "envs/prod/orders", address: "module.service.aws_dynamodb_table.records[0]", action: "replace", status: "done", done_at: "2026-10-08T09:42:20.000Z" },
+    { root: "envs/prod/orders", address: "module.service.aws_dynamodb_table.records[1]", action: "replace", status: "in-flight" },
+  ],
+  ...over,
+});
+
+describe("progress marks (#511)", () => {
+  it("tags a card with its newest wave's status and the read's age", () => {
+    const m = cardProgress([mark({ wave: 1, status: "done" }), mark()]);
+    expect(m.wave).toBe(2);
+    expect(progressTag(m, NOW)).toEqual({ text: "▶ wave 2 in flight · 2m", tone: "in-flight" });
+    expect(cardProgress([])).toBeNull();
+  });
+
+  it("dates every line by the records read, and a done instance by when a read found it", () => {
+    expect(progressLines(mark(), NOW)).toEqual([
+      "wave 2 in flight, records read 09:43 UTC, 2m ago",
+      "module.service.aws_dynamodb_table.records[0] (replace): done 09:42 UTC",
+      "module.service.aws_dynamodb_table.records[1] (replace): in flight",
+    ]);
+    expect(resourceLine({ address: "a.b", action: "create", status: "not-applied" }, NOW)).toBe("a.b (create): not applied");
+  });
+
+  it("counts a wave the way terragucci's log line does", () => {
+    expect(countsLine({ done: 2, "in-flight": 1, waiting: 2, "not-applied": 0 })).toBe("2 of 5 done, 1 in flight, 2 waiting");
+    expect(countsLine({ done: 2, "in-flight": 0, waiting: 0, "not-applied": 3 })).toBe("2 of 5 done, 0 in flight, 0 waiting, 3 not applied");
+  });
+
+  it("says when there is no run view, and never paints one as live", () => {
+    expect(progressRows({ run: { commit: "c", key: "k", present: false }, absent: "has no k" }, NOW)).toEqual({ head: "has no k", title: "", waves: [] });
+    const rows = progressRows(
+      {
+        read: "2026-10-08T09:44:00Z",
+        run: { commit: "d3e4f5a6b7c8d9e0", key: "p/runs/d3e4/run.json", present: true, html: "p/runs/d3e4/run.html" },
+        watching: true,
+        unmatched: [{ root: "envs/prod/payments", address: "module.service.aws_iam_role.worker" }],
+        waves: [{ number: 2, state: "applying", read: "2026-10-08T09:43:00.000Z", counts: { done: 2, "in-flight": 1, waiting: 2, "not-applied": 0 }, resources: [] }],
+      },
+      NOW,
+    );
+    expect(rows.head).toBe("apply progress of d3e4f5a6b7c8, from terragucci's run view · asked again while a wave moves");
+    expect(rows.head).not.toMatch(/\blive\b/);
+    expect(rows.title).toContain("no card: envs/prod/payments: module.service.aws_iam_role.worker");
+    expect(rows.waves[0]).toMatchObject({ text: "wave 2 applying: 2 of 5 done, 1 in flight, 2 waiting", read: "records read 09:43 UTC, 2m ago", tone: "in-flight" });
+  });
+});