@intentius/behold 0.25.0 → 0.27.0

package/web/edge-kind.test.js

@@ -0,0 +1,70 @@
+import { describe, expect, it } from "vitest";
+import { edgeLabel, edgeLegend, edgeTitle } from "./edge-kind.js";
+
+// The edges chant 0.124.20's GitHub lexicon writes (lexicons/github/src/
+// graph-edges.ts) and one from its GitLab lexicon.
+const needs = { from: "Test", to: "Build", kind: "needs", viaAttr: "needs" };
+const calls = { from: "Ci", to: "Release", kind: "calls", viaAttr: "uses", crossPipeline: true };
+const triggers = { from: "Deploy", to: "Ci", kind: "triggers", viaAttr: "workflow_run", crossPipeline: true };
+const stage = { from: "test", to: "build", kind: "needs", viaAttr: "stage" };
+const ref = { from: "api", to: "db", kind: "ref", viaAttr: "data dependency" };
+
+const title = (e) => edgeTitle(e.from, e.to, { kind: e.kind, via: e.viaAttr, cross: e.crossPipeline });
+
+describe("edgeLabel (#553)", () => {
+  it("names a CI edge by its kind, with the attribute only when it adds something", () => {
+    expect(edgeLabel({ kind: "needs", via: "needs" })).toBe("needs");
+    expect(edgeLabel({ kind: "needs", via: "stage" })).toBe("needs (stage)");
+    expect(edgeLabel({ kind: "calls", via: "uses" })).toBe("calls (uses)");
+    expect(edgeLabel({ kind: "triggers", via: "workflow_run" })).toBe("triggers (workflow_run)");
+    expect(edgeLabel({ kind: "includes" })).toBe("includes");
+  });
+
+  it("names a reference by the attribute it flows through", () => {
+    expect(edgeLabel({ kind: "ref", via: "role" })).toBe("role");
+    expect(edgeLabel({ via: "role", toAttr: "arn" })).toBe("role → arn");
+    expect(edgeLabel({ kind: "ref" })).toBe("");
+  });
+});
+
+describe("edgeTitle, the hover tooltip (#553)", () => {
+  it("says a needs edge's kind and what it means", () => {
+    expect(title(needs)).toBe("Test → Build\nneeds: waits for the other job to finish");
+    expect(title(stage)).toBe("test → build\nneeds (stage): waits for the other job to finish");
+  });
+
+  it("says a call to a reusable workflow leaves its pipeline", () => {
+    expect(title(calls)).toBe(
+      "Ci → Release\ncalls (uses): runs the other workflow as a reusable workflow\ncross-pipeline: leaves its own workflow or pipeline",
+    );
+    expect(title(triggers)).toBe(
+      "Deploy → Ci\ntriggers (workflow_run): starts the other workflow or pipeline\ncross-pipeline: leaves its own workflow or pipeline",
+    );
+  });
+
+  it("keeps a reference's reason as it was", () => {
+    expect(title(ref)).toBe("api → db\ndata dependency — reads/uses this store");
+    expect(edgeTitle("a", "b", { kind: "ref", via: "role" })).toBe("a → b\nrole");
+    expect(edgeTitle("a", "b", {})).toBe("a → b");
+  });
+
+  it("names a kind it has no sentence for", () => {
+    expect(edgeTitle("a", "b", { kind: "waits", via: "on" })).toBe("a → b\nwaits (on)");
+  });
+});
+
+describe("edgeLegend (#553)", () => {
+  it("lists the CI kinds the graph holds, then the cross-pipeline edges", () => {
+    const rows = edgeLegend([needs, needs, calls, triggers, ref]);
+    expect(rows.map((r) => [r.label, r.count, r.cross])).toEqual([
+      ["needs", 2, false],
+      ["calls", 1, true],
+      ["triggers", 1, true],
+      ["cross-pipeline (dashed)", 2, true],
+    ]);
+  });
+
+  it("is empty for a graph of references", () => {
+    expect(edgeLegend([ref, { from: "a", to: "b", kind: "ref" }])).toEqual([]);
+  });
+});

package/web/index.html

@@ -132,6 +132,34 @@
          either for the full reason (native SVG <title>). */
       #graph g[data-edge-via="data dependency"] .pin-edge-line { stroke-dasharray: 6 5; }
       #graph g[data-edge-from][data-edge-via] { cursor: help; }
+      /* #553: CI edges by kind (chant's IREdge.kind, stamped by pinhole as
+         data-edge-kind, left off for a plain reference). Each kind has a hue,
+         65% of a status token and 35% --fg so it clears the background on the
+         light palettes too (all but Unikitty, whose pastel slots sit on its
+         pink ground, read at least as well as --edge). On 128 of the 552
+         themes two of those slots come out the same colour, so the line's
+         pattern carries the kind
+         as well: needs is a heavier solid line, triggers a dash-dot, includes
+         and extends dotted. An edge that leaves its workflow or pipeline
+         (data-edge-cross) is dashed, as chant's Mermaid and DOT draw it. The
+         Model tab's edge legend (.edge-swatch) is drawn by the same rules.
+         Hover and .edge-hi above stay the more specific rules, so a traced
+         edge still turns --pending. */
+      .edge-swatch { flex: none; overflow: visible; }
+      .edge-swatch .pin-edge-line { stroke: var(--edge); stroke-width: 1.5; fill: none; }
+      :is(#graph, .edge-swatch) g[data-edge-kind] .pin-edge-line { stroke-width: 1.6; }
+      :is(#graph, .edge-swatch) g[data-edge-kind="needs"] .pin-edge-line { stroke: color-mix(in srgb, var(--runtime) 65%, var(--fg)); stroke-width: 2.1; }
+      :is(#graph, .edge-swatch) g[data-edge-kind="calls"] .pin-edge-line { stroke: color-mix(in srgb, var(--foreign) 65%, var(--fg)); }
+      :is(#graph, .edge-swatch) g[data-edge-kind="triggers"] .pin-edge-line { stroke: color-mix(in srgb, var(--managed) 65%, var(--fg)); }
+      :is(#graph, .edge-swatch) g[data-edge-cross="true"] .pin-edge-line { stroke-dasharray: 7 5; }
+      :is(#graph, .edge-swatch) g[data-edge-kind="triggers"] .pin-edge-line { stroke-dasharray: 9 4 2 4; }
+      :is(#graph, .edge-swatch) g[data-edge-kind="includes"] .pin-edge-line,
+      :is(#graph, .edge-swatch) g[data-edge-kind="extends"] .pin-edge-line { stroke: var(--muted); stroke-dasharray: 1.5 4; stroke-linecap: round; }
+      /* The chip wears its kind's hue on its outline; its text stays pinhole's. */
+      #graph g[data-edge-kind="needs"] rect { stroke: color-mix(in srgb, var(--runtime) 65%, var(--fg)); }
+      #graph g[data-edge-kind="calls"] rect { stroke: color-mix(in srgb, var(--foreign) 65%, var(--fg)); }
+      #graph g[data-edge-kind="triggers"] rect { stroke: color-mix(in srgb, var(--managed) 65%, var(--fg)); }
+      #graph g[data-edge-kind="includes"] rect, #graph g[data-edge-kind="extends"] rect { stroke: var(--muted); }
       /* #477: a declared workspace's waiting gates, over the top of the graph
          pane (same grid cell, so #graph's re-renders never take it with them). */
       #ws-gates { grid-row: 1; grid-column: 1; align-self: start; justify-self: center; z-index: 3; margin-top: 8px;
@@ -142,6 +170,21 @@
       #ws-gates .ws-gate-title { font-weight: 600; }
       #ws-gates .ws-gate-facts, #ws-gates .ws-gate-note { color: var(--muted); font-size: var(--t-caption); }
       #ws-gates .ws-gate button { margin-top: 4px; }
+      /* #526: SQL Yodeler's report and drift, from files, dated. Never a fill. */
+      #panel-body #tab-yodel.active { display: flex; flex-direction: column; gap: 4px; font-size: var(--t-caption); }
+      #tab-yodel h3 { margin: 8px 0 0; font-size: var(--t-caption); }
+      #tab-yodel .tg-legend { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel .tg-inspect { overflow-wrap: anywhere; }
+      #tab-yodel .tg-refusal { color: var(--degraded); font-weight: 600; }
+      /* #524: SQL Yodeler's gates on chant/lifecycle, dated. A Copy button is the only control. */
+      #panel-body #tab-yodel-lane.active { display: flex; flex-direction: column; gap: 6px; font-size: var(--t-caption); }
+      #tab-yodel-lane h3 { margin: 8px 0 0; font-size: var(--t-caption); }
+      #tab-yodel-lane .tg-legend { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel-lane .tg-refusal { color: var(--degraded); font-weight: 600; }
+      #tab-yodel-lane .ws-gate { border: 1px solid var(--rule); border-radius: 6px; padding: 6px 8px; }
+      #tab-yodel-lane .ws-gate-title { font-weight: 600; }
+      #tab-yodel-lane .ws-gate-facts, #tab-yodel-lane .ws-gate-note { color: var(--muted); overflow-wrap: anywhere; }
+      #tab-yodel-lane .tg-command { display: block; font-family: var(--font-mono); overflow-wrap: anywhere; margin: 4px 0; }
       /* #490: terragucci's reports, dated. Never a fill. */
       #panel-body #tab-terragucci.active { display: flex; flex-direction: column; gap: 8px; font-size: var(--t-caption); }
       #tab-terragucci .tg-legend, #tab-terragucci .tg-estate { color: var(--muted); }
@@ -189,6 +232,13 @@
       /* #506: the audit record's lane, in the tab and in a card's inspect pane. */
       #tab-terragucci .tg-timeline-title { font-weight: 600; border-top: 1px solid var(--rule); padding-top: 6px; }
       .tg-timeline { display: flex; flex-direction: column; gap: 3px; font-size: var(--t-caption); }
+      .rel-strip { border-collapse: collapse; margin: 6px 0; font-size: 12px; }
+      .rel-strip th, .rel-strip td { padding: 3px 6px; text-align: left; vertical-align: top; border-bottom: 1px solid var(--neutral); }
+      .rel-strip .rel-component { font-family: var(--font-mono); overflow-wrap: anywhere; }
+      .rel-strip .rel-cell { font-family: var(--font-mono); }
+      .rel-strip .rel-empty { color: var(--muted); }
+      .rel-strip .rel-differs { box-shadow: inset 2px 0 0 var(--degraded); }
+      .rel-strip .rel-mark { color: var(--degraded); font-weight: 600; font-family: inherit; }
       .tg-timeline .tg-legend { color: var(--muted); }
       .tg-timeline .tg-refusal { color: var(--degraded); font-weight: 600; }
       .tg-timeline .tg-entry { overflow-wrap: anywhere; }

package/web/releases.js

@@ -0,0 +1,121 @@
+// #525: the Releases strip. Pure words from /api/lifecycle/releases, and one
+// render. One column per environment (wave order when yodel-waves.json gives
+// one), one row per component or tenant. Every cell says when its release was
+// recorded, by whom, and which commit of chant/lifecycle it was read from. A
+// cell whose digest the environment before it does not hold is marked
+// "differs from <env>" with both digests. Nothing here deploys or promotes.
+
+import { ago, clock } from "./terragucci.js";
+
+const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
+
+/** The strip's line: what was read, how, and when. */
+export function releasesLegend(a, now = new Date()) {
+  if (!a || a.error) return { text: `release ledger not read${a && a.error ? `: ${a.error}` : ""}`, title: "", tone: "refusal" };
+  const when = `read ${ago(a.read.at, now)}`;
+  if (!a.found) {
+    const text = a.via === "none" ? `release ledger unknown: behold could not fetch chant/lifecycle · ${when}` : `no release recorded yet · ${when}`;
+    return { text, title: a.note, tone: a.via === "none" ? "refusal" : "quiet" };
+  }
+  const how = a.via === "fetch" ? "fetched from origin" : "the checkout's origin/chant/lifecycle, as of its last git fetch (behold's fetch failed)";
+  const order = a.order === "waves" ? "columns in yodel-waves.json's wave order" : "columns by name";
+  const bad = Object.entries(a.malformed || {}).map(([env, n]) => `${env}: ${n} malformed line${n === 1 ? "" : "s"} skipped`);
+  return {
+    text: `release ledger on chant/lifecycle · ${when}, ${how} · ${order}`,
+    title: [a.note, a.fetch && a.fetch.error ? `fetch: ${a.fetch.error}` : "", ...bad].filter(Boolean).join("\n"),
+    tone: a.via === "fetch" ? "quiet" : "stale",
+  };
+}
+
+/** One cell's words: digest, age, who, and a difference mark when there is one. */
+export function releaseCellWords(cell, now = new Date()) {
+  if (!cell) return { text: "no release", title: "", differs: null };
+  const who = `${cell.actor}${cell.approver ? `, approved by ${cell.approver}` : ""}`;
+  const src = cell.source && cell.source.commit ? `chant/lifecycle ${short(cell.source.commit)}${cell.source.committed ? `, committed ${clock(cell.source.committed, now)}` : ""}` : "chant/lifecycle";
+  let differs = null;
+  if (cell.differs) {
+    const theirs = cell.differs.digest ? short(cell.differs.digest) : "nothing";
+    differs = {
+      text: `differs from ${cell.differs.from}`,
+      title: `${cell.env} holds ${short(cell.digest)}; ${cell.differs.from} holds ${theirs}.${cell.differs.everHad ? "" : ` ${cell.differs.from}'s ledger never recorded ${short(cell.digest)}.`}`,
+    };
+  }
+  return {
+    text: `${short(cell.digest)} · ${ago(cell.timestamp, now)}`,
+    title: [
+      `${cell.component} in ${cell.env}`,
+      `digest ${cell.digest}`,
+      `recorded ${clock(cell.timestamp, now)}, ${ago(cell.timestamp, now)}, by ${who}`,
+      `commit ${short(cell.gitSha)}, run ${cell.runId}`,
+      `from ${src} (${cell.source ? cell.source.path : ""})`,
+      differs ? differs.title : "",
+    ]
+      .filter(Boolean)
+      .join("\n"),
+    differs,
+  };
+}
+
+/** The grid: header row of environments, then a row per component with a cell per environment. */
+export function releaseGrid(a, now = new Date()) {
+  if (!a || !a.found) return { environments: [], rows: [] };
+  const at = new Map(a.cells.map((c) => [`${c.component}\u0000${c.env}`, c]));
+  return {
+    environments: a.environments,
+    rows: a.components.map((component) => ({
+      component,
+      cells: a.environments.map((env) => {
+        const c = at.get(`${component}\u0000${env}`);
+        return { env, ...releaseCellWords(c, now), runUrl: c && c.runUrl ? c.runUrl : null, empty: !c };
+      }),
+    })),
+  };
+}
+
+/** Render into `host`. `ui.link(text, href)` is app.js's link. */
+export function renderReleases(host, a, now, ui) {
+  host.replaceChildren();
+  const lg = releasesLegend(a, now);
+  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);
+  const g = releaseGrid(a, now);
+  if (!g.rows.length) return;
+  const table = document.createElement("table");
+  table.className = "rel-strip";
+  const tr = document.createElement("tr");
+  tr.appendChild(document.createElement("th"));
+  for (const env of g.environments) {
+    const th = document.createElement("th");
+    th.textContent = env;
+    tr.appendChild(th);
+  }
+  table.appendChild(tr);
+  for (const row of g.rows) {
+    const r = document.createElement("tr");
+    const name = document.createElement("th");
+    name.className = "rel-component";
+    name.textContent = row.component;
+    r.appendChild(name);
+    for (const c of row.cells) {
+      const td = document.createElement("td");
+      td.className = c.empty ? "rel-cell rel-empty" : c.differs ? "rel-cell rel-differs" : "rel-cell";
+      td.title = c.title;
+      const t = document.createElement("div");
+      t.textContent = c.text;
+      td.appendChild(t);
+      if (c.differs) {
+        const d = document.createElement("div");
+        d.className = "rel-mark";
+        d.textContent = c.differs.text;
+        td.appendChild(d);
+      }
+      if (c.runUrl && ui && ui.link) td.appendChild(ui.link("run", c.runUrl));
+      r.appendChild(td);
+    }
+    table.appendChild(r);
+  }
+  host.appendChild(table);
+}

package/web/sql-yodeler-lane.js

@@ -0,0 +1,129 @@
+// #524: a SQL Yodeler repo's lane, from /api/sql-yodeler/lifecycle. One row
+// per environment in the order of applies (yodel-waves.json), each with its
+// wave's gate and its migrations op's gate: the state, the plan digest, who
+// approved and how, and the chant/lifecycle commit it was read from. A
+// waiting gate offers `npx yodel approve <env> --plan <digest>` to copy;
+// nothing here approves.
+
+import { ago, clock } from "./terragucci.js";
+import { holderWords, laneLegend, modeWords, sourceWords } from "./terragucci-lifecycle.js";
+
+const short = (s) => (s ? String(s).replace(/^(jcs1-)?sha256:/, "").slice(0, 12) : "");
+
+const STATE_WORDS = {
+  waiting: "waits for an approval",
+  expired: "asked for an approval that expired",
+  approved: "approved, not applied yet",
+  applied: "applied",
+  failed: "apply failed",
+  refused: "refused: an approval stands for another plan",
+  "refused-by-policy": "refused by policy, no override counts",
+  held: "held on another gate",
+};
+
+/** The line over the lane: what was read, how, when, and where the order came from. */
+export function yodelLegend(answer, now = new Date()) {
+  const lg = laneLegend(answer, now);
+  if (!answer || answer.error) return lg;
+  const order = answer.order && answer.order.source === "yodel-waves.json" ? "environments in yodel-waves.json's order" : answer.order && answer.order.source === "ops" ? "environments from ops/migrate-<env>.op.ts (no yodel-waves.json)" : "no environments declared";
+  const member = answer.member && answer.member.members.length ? ` · workspace member ${answer.member.members.join(" / ")}, read under ${answer.member.prefix}` : "";
+  return { ...lg, text: `${lg.text} · ${order}${member}`, title: [lg.title, answer.order && answer.order.error ? `yodel-waves.json: ${answer.order.error}` : "", answer.member && answer.member.error ? answer.member.error : ""].filter(Boolean).join("\n") };
+}
+
+/** One gate as a card: title, facts, source, and the line to copy when it waits. Pure. */
+export function yodelGateCard(env, g, now = new Date()) {
+  const what = g.kind === "wave" ? `wave ${g.wave} (${g.gate})` : `${g.op} (${g.gate})`;
+  const facts = [];
+  if (g.pending) facts.push(`asked ${clock(g.pending.timestamp, now)}, ${ago(g.pending.timestamp, now)}`);
+  if (g.approval) {
+    const how = [g.approval.signed ? "signed" : "unsigned", g.approval.via ? `via ${g.approval.via}` : "", g.approval.pr !== undefined ? `PR #${g.approval.pr}` : "", g.approval.relayedBy ? `relayed by ${g.approval.relayedBy}` : ""].filter(Boolean).join(", ");
+    facts.push(`approved by ${g.approval.by} (${how}) ${clock(g.approval.at, now)}, ${ago(g.approval.at, now)}`);
+  }
+  if (g.applied) facts.push(`applied ${clock(g.applied.at, now)}, ${ago(g.applied.at, now)}${g.applied.result ? "" : " (outcome not recorded)"}`);
+  if (g.digest) facts.push(`plan ${short(g.digest)}`);
+  for (const u of g.uncounted || []) facts.push(`${u.approval.by}'s approval does not count: ${u.reason}`);
+  if (g.heldOn) facts.push(`held on ${g.heldOn.op}/${g.heldOn.gate}${holderWords(g.heldOn) ? `, ${holderWords(g.heldOn)}` : ""}`);
+  if (modeWords(g)) facts.push(modeWords(g));
+  if ((g.headPlans || []).length) {
+    const h = g.headPlans[0];
+    facts.push(`pull request head ${h.head.slice(0, 12)} recorded this plan ${clock(h.timestamp, now)}, ${ago(h.timestamp, now)} (${h.path}): a writer's approving review of that head, merged, approves it${g.headPlans.length > 1 ? `; ${g.headPlans.length - 1} more head${g.headPlans.length > 2 ? "s" : ""} recorded it too` : ""}`);
+  }
+  return {
+    env,
+    kind: g.kind,
+    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: `${env}: ${what} ${STATE_WORDS[g.state] || g.state}`,
+    facts: facts.join(" · "),
+    source: sourceWords(g.source, now),
+    ...(g.command ? { command: g.command } : {}),
+    ...(g.pending && g.pending.url ? { job: g.pending.url } : {}),
+  };
+}
+
+/** Every environment's rows, in the order of applies. An environment with no gate on the ledger says so. Pure. */
+export function yodelRows(answer, now = new Date()) {
+  if (!answer || answer.error || !answer.found) return [];
+  const rows = [];
+  for (const e of answer.environments || []) {
+    const head = e.wave ? `${e.env}: wave ${e.wave.k}${e.wave.gate ? `, gate ${e.wave.gate}` : ""}${e.wave.approval ? `, approval ${e.wave.approval}` : ""}${e.wave.targets.length > 1 || e.wave.targets[0] !== e.env ? `, ${e.wave.targets.join(", ")}` : ""}` : `${e.env}: in no wave`;
+    rows.push({ env: e.env, head, cards: e.gates.map((g) => yodelGateCard(e.env, g, now)) });
+  }
+  if ((answer.unplaced || []).length) rows.push({ env: "", head: "waves yodel-waves.json does not name", cards: answer.unplaced.map((g) => yodelGateCard(`wave ${g.wave}`, g, now)) });
+  return rows;
+}
+
+const APPROVE_NOTE = "An approval is a git record bound to this plan digest: run the line at your shell. behold does not approve.";
+
+/** The lane as DOM. `ui` lends app.js's `button`, `copy` and `link`; a Copy button is the only control. */
+export function renderYodelLane(host, answer, now, ui) {
+  const lg = yodelLegend(answer, now);
+  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);
+  for (const r of yodelRows(answer, now)) {
+    const h = document.createElement("h3");
+    h.textContent = r.head;
+    host.appendChild(h);
+    if (!r.cards.length) {
+      const none = document.createElement("div");
+      none.className = "tg-legend";
+      none.textContent = "no gate on chant/lifecycle yet";
+      host.appendChild(none);
+    }
+    for (const c of r.cards) {
+      const box = document.createElement("div");
+      box.className = `ws-gate tg-lane-gate tg-${c.tone}`;
+      const title = document.createElement("div");
+      title.className = "ws-gate-title";
+      title.textContent = c.title;
+      const facts = document.createElement("div");
+      facts.className = "ws-gate-facts";
+      facts.textContent = c.facts;
+      const src = document.createElement("div");
+      src.className = "ws-gate-note";
+      src.textContent = `from ${c.source}`;
+      box.append(title, facts, src);
+      if (c.command) {
+        const cmd = document.createElement("code");
+        cmd.className = "tg-command";
+        cmd.textContent = c.command;
+        const copy = ui.button("Copy", "", () => ui.copy(c.command, copy));
+        copy.title = "Copy the line. Run it at your shell: the approval is yours.";
+        const note = document.createElement("div");
+        note.className = "ws-gate-note";
+        note.textContent = APPROVE_NOTE;
+        box.append(cmd, copy, note);
+      }
+      if (c.job) {
+        const links = document.createElement("div");
+        links.className = "ws-gate-note";
+        links.appendChild(ui.link("job", c.job));
+        box.appendChild(links);
+      }
+      host.appendChild(box);
+    }
+  }
+}

package/web/terragucci-lifecycle.js

@@ -28,8 +28,12 @@ export function laneLegend(lane, now = new Date(), polled = null) {
   }
   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"),
+    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",
   };
 }
@@ -38,28 +42,86 @@ 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`,
+  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 = [];
-    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)}`);
+    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" ? "wave" : g.state === "failed" ? "failed" : g.state === "expired" ? "none" : "ok",
+      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: "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 } : {}),
+      ...(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 } : {}),
     };
   });
 }
@@ -108,13 +170,43 @@ export function renderLane(host, lane, polled, now, ui) {
     const src = document.createElement("div");
     src.className = "ws-gate-note";
     src.textContent = `from ${g.source}`;
-    box.append(title, facts, src);
+    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 is yours, signed, in git.";
+      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;

package/web/terragucci-lifecycle.test.js

@@ -1,5 +1,5 @@
 import { describe, it, expect } from "vitest";
-import { laneGateCards, laneLegend, laneLockRows, sourceWords } from "./terragucci-lifecycle.js";
+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" };
@@ -52,6 +52,41 @@ describe("the chant/lifecycle lane, dated (#505)", () => {
     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");