@intentius/behold 0.13.0 → 0.14.0

package/example-writes/package-lock.json

@@ -6,9 +6,9 @@
     "": {
       "name": "behold-example-writes",
       "dependencies": {
-        "@intentius/chant": "^0.52.1",
-        "@intentius/chant-lexicon-aws": "^0.52.1",
-        "@intentius/chant-lexicon-temporal": "^0.52.1"
+        "@intentius/chant": "^0.53.1",
+        "@intentius/chant-lexicon-aws": "^0.53.1",
+        "@intentius/chant-lexicon-temporal": "^0.53.1"
       }
     },
     "node_modules/@dagrejs/dagre": {
@@ -443,9 +443,9 @@
       }
     },
     "node_modules/@intentius/chant": {
-      "version": "0.52.1",
-      "resolved": "https://registry.npmjs.org/@intentius/chant/-/chant-0.52.1.tgz",
-      "integrity": "sha512-JvlJ8JrmcDWF6IhmO1aJPgBCMIoTT9xUu/4sOs+3O2NSILZFJBJ3gN23FMW3goN+HP0HbniPtR/MH5cklpam0Q==",
+      "version": "0.53.1",
+      "resolved": "https://registry.npmjs.org/@intentius/chant/-/chant-0.53.1.tgz",
+      "integrity": "sha512-AIVy6/NQxnplHPip+oYhbgr1qe8QCzUc7heqiXoV9OZynn6x+/4sflrFha98dOotJ7Fraj2/QjfGQ+q1DpXK8w==",
       "license": "Apache-2.0",
       "dependencies": {
         "@dagrejs/dagre": "^3.0.0",
@@ -461,30 +461,30 @@
       }
     },
     "node_modules/@intentius/chant-lexicon-aws": {
-      "version": "0.52.1",
-      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-aws/-/chant-lexicon-aws-0.52.1.tgz",
-      "integrity": "sha512-TuTt3AMfAZmtuyfYGijtO5HjtHab9XSE1f2a51PjfzbgBspwQT1dfMa1SGnGsDbtgtaE1sUoe48bbTfU12dQmw==",
+      "version": "0.53.1",
+      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-aws/-/chant-lexicon-aws-0.53.1.tgz",
+      "integrity": "sha512-LyI7IMib1m69k+oNovrBw/RNJqIM17vSj9ew+h5kviGf3KHfyU0VxPX5n6mxqZCNK5LAoMtRlW/cdzN2caJAWQ==",
       "license": "Apache-2.0",
       "dependencies": {
         "fflate": "^0.8.2",
         "js-yaml": "^4.3.1"
       },
       "peerDependencies": {
-        "@intentius/chant": "^0.52.1",
+        "@intentius/chant": "^0.53.1",
         "typescript": "^5.9.3"
       }
     },
     "node_modules/@intentius/chant-lexicon-temporal": {
-      "version": "0.52.1",
-      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-temporal/-/chant-lexicon-temporal-0.52.1.tgz",
-      "integrity": "sha512-tVBZTPF3FZSeyLgHSid8+6jrxii/pRQEW4na8M4FnA5kGbUKTL8+Ckwsobp9nIE7HFWfBKdLcoCNt6Guw/tEfA==",
+      "version": "0.53.1",
+      "resolved": "https://registry.npmjs.org/@intentius/chant-lexicon-temporal/-/chant-lexicon-temporal-0.53.1.tgz",
+      "integrity": "sha512-zcj1OzDgOXUG/c50Bd3FWW7arodD72Wm50CItar0XBcXEV/w+gZaB/ksXx/D5vrRJvccZP2oIMSAsdLaVRso4w==",
       "license": "Apache-2.0",
       "dependencies": {
         "@temporalio/common": "^1.17.2",
         "js-yaml": "^4.3.1"
       },
       "peerDependencies": {
-        "@intentius/chant": "^0.52.1",
+        "@intentius/chant": "^0.53.1",
         "typescript": "^5.9.3",
         "zod": "^4.3.6"
       }

package/example-writes/package.json

@@ -7,8 +7,8 @@
     "build": "./node_modules/.bin/chant build src --lexicon aws -o template.json"
   },
   "dependencies": {
-    "@intentius/chant": "^0.52.1",
-    "@intentius/chant-lexicon-aws": "^0.52.1",
-    "@intentius/chant-lexicon-temporal": "^0.52.1"
+    "@intentius/chant": "^0.53.1",
+    "@intentius/chant-lexicon-aws": "^0.53.1",
+    "@intentius/chant-lexicon-temporal": "^0.53.1"
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@intentius/behold",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "type": "module",
   "description": "behold — a live control plane on chant. See your whole estate (every substrate in one graph), coloured by drift; act through delegated, gated Ops.",
   "bin": {
@@ -35,9 +35,9 @@
   },
   "dependencies": {
     "@hono/node-server": "^2.0.5",
-    "@intentius/chant": "^0.52.1",
-    "@intentius/chant-k8s-client": "^0.52.1",
-    "@intentius/pinhole": "^0.3.5",
+    "@intentius/chant": "^0.53.1",
+    "@intentius/chant-k8s-client": "^0.53.1",
+    "@intentius/pinhole": "^0.3.7",
     "hono": "^4.12.34"
   },
   "devDependencies": {

package/web/app.js

@@ -46,7 +46,7 @@ import { fetchDemos, demoLabel, demoTitle, demoProgress } from "./demos.js";
 // #284 item 2: the run playhead's panel — the verdict wording, the pending gate
 // card and the settled-step rows. Everything it DECIDES is pure in there; the
 // fetches, the SSE subscription and the graph re-pull stay here.
-import { hasPlayhead, renderPlayhead } from "./run-playhead.js";
+import { hasPlayhead, renderPlayhead, waitingFor } from "./run-playhead.js";
 // #234 joins 3 + 1: the operator strip (one honestly-dated tick per ConvergeOp,
 // the lease, the pending gate count) and the converge gate card, whose Approve
 // records a fact for the next tick rather than releasing anything. Same split as
@@ -382,6 +382,11 @@ function inspect(node) {
   // joinComponentStatus, so its presence picks the component-status label set
   // over the entity overlay's managed/foreign/pending.
   const liveStatus = node.attrs && node.attrs._liveStatus;
+  // chant#2027: what the operating loop's last tick said about this component
+  // (src/component-status.ts's joinTickVerdicts). Same component-status
+  // vocabulary as `_liveStatus`, one tier lower and dated — so it picks the same
+  // label set, and it may sit alongside a live verdict rather than replacing it.
+  const tickStatus = node.attrs && node.attrs._tickStatus;
   // behold#146: a Helm chart's status is artifact presence, not management —
   // the join sets `_artifact` on a match, and every Helm::Chart in an overlay
   // went through it, so the kind alone is the reliable picker.
@@ -396,7 +401,7 @@ function inspect(node) {
       "status",
       driftLabel ||
         (node.lexicon === "op" ? opStatusLabel(node) : undefined) ||
-        (isArtifact ? ARTIFACT_STATUS_LABEL[st] : liveStatus ? COMPONENT_STATUS_LABEL[st] : STATUS_LABEL[st]) ||
+        (isArtifact ? ARTIFACT_STATUS_LABEL[st] : liveStatus || tickStatus ? COMPONENT_STATUS_LABEL[st] : STATUS_LABEL[st]) ||
         st,
     );
   if (node.attrs && node.attrs._artifact) {
@@ -514,6 +519,29 @@ function inspect(node) {
     live("", `runtime child — owned by ${node.runtimeOwner || "its declared parent"}, not itself declared`);
   }
 
+  // What the operating loop's last tick said about this component (chant#2027).
+  // Its own section, never folded into "live status": a tick is dated, and the
+  // date is the point. Shown alongside a live verdict when there is one — the
+  // two can disagree, and which is newer is the reader's to see, not behold's to
+  // resolve. The heading itself carries the age, and a tick too old to have
+  // painted says so in words rather than leaving its verdict to be read as now.
+  if (tickStatus) {
+    const ago = tickStatus.at ? waitingFor(tickStatus.at) : null;
+    const tick = section(`converge tick${ago ? ` · ${ago} ago` : ""}${tickStatus.stale ? " · not painted" : ""}`);
+    tick("reconciliation", tickStatus.reconciliation);
+    if (tickStatus.detail) tick("detail", tickStatus.detail);
+    if (tickStatus.live !== undefined) tick("observed live", String(tickStatus.live));
+    if (tickStatus.unobserved) {
+      tick("unobserved", tickStatus.unobserved.detail ? `${tickStatus.unobserved.reason} — ${tickStatus.unobserved.detail}` : tickStatus.unobserved.reason);
+    }
+    tick("recorded by", tickStatus.env ? `${tickStatus.op} (${tickStatus.env})` : tickStatus.op);
+    tick("at", tickStatus.at);
+    if (tickStatus.tickId) tick("tick", tickStatus.tickId);
+    if (tickStatus.stale) {
+      tick("", "older than the operator's own cadence allows for — this verdict is history, so no colour was taken from it");
+    }
+  }
+
   // Declared attributes — the source-of-truth values / cross-resource refs.
   const attrKeys = Object.keys(node.attrs || {}).filter((k) => !k.startsWith("_"));
   if (attrKeys.length) {
@@ -589,7 +617,7 @@ function inspect(node) {
   // `observed` map already carries a runtime child (chant's describeResources
   // reports it the same as any other resource it found), and its own
   // `fieldDrift` may apply too on a substrate with per-field ownership.
-  const observed = st === "good" || st === "warn" || st === "runtime" || (st === "neutral" && !liveStatus);
+  const observed = st === "good" || st === "warn" || st === "runtime" || (st === "neutral" && !liveStatus && !tickStatus);
   if (view.env && observed) {
     const forId = node.id;
     const loading = document.createElement("p");
@@ -1867,6 +1895,11 @@ let runStatusInFlight = false;
 // playhead's reason: a loop belongs to its project, not to a picked env/tier.
 let operatorState = null;
 let operatorInFlight = false;
+// #234, chant#2029 — the converge timeline behind the strip. Closed until a
+// human opens it, read once when they do, and never on a timer: the strip is the
+// at-a-glance line that ages by itself, the history is a ledger's past and does
+// not change while you read it. `data` is src/operator.ts's OperatorHistory.
+let operatorHistory = { open: false, loading: false, error: null, data: null };
 let componentChoices = []; // component names for the apply picker — loaded lazily (independent of whether the graph pane is currently in components mode)
 let componentStatusById = {}; // id -> _status ("good"|"accent"|"warn"|"neutral"), populated alongside componentChoices — lets the picker show which stacks are already applied
 
@@ -2067,7 +2100,17 @@ function mountOperator(host) {
   if (!view.ops || !hasOperator(operatorState)) return;
   const box = document.createElement("div");
   box.className = "operator-strip";
-  renderOperator(box, operatorState, { approve: (op, gate) => approveConvergeGate(op, gate) });
+  renderOperator(
+    box,
+    operatorState,
+    {
+      approve: (op, gate) => approveConvergeGate(op, gate),
+      // A static export has no server to ask, so it gets no history affordance
+      // at all rather than a button that can only fail.
+      ...(staticMode ? {} : { history: () => toggleOperatorHistory() }),
+    },
+    operatorHistory,
+  );
   host.appendChild(box);
 }
 
@@ -3816,6 +3859,48 @@ function pollOperatorStatus() {
     });
 }
 
+/**
+ * Open or close the converge history (#234, chant#2029), reading it the first
+ * time it is opened.
+ *
+ * This is the whole poll discipline for the timeline: a click. `chant operator
+ * log` walks the project's `chant/lifecycle` ledger, and an interval against it
+ * would spend a process per tick of the clock to be handed a past that hasn't
+ * moved. Re-opening re-reads, so a human who wants the newest ticks closes and
+ * opens — an explicit ask, which is what this surface is.
+ */
+function toggleOperatorHistory() {
+  operatorHistory = { ...operatorHistory, open: !operatorHistory.open };
+  if (operatorHistory.open) loadOperatorHistory();
+  renderDial();
+}
+
+/**
+ * Read one bounded window of the converge timeline.
+ *
+ * The server clamps and reports the window it used (src/operator.ts's
+ * OPERATOR_LOG_MAX_LIMIT), so the panel states the bound rather than implying it
+ * is showing everything. A refusal — a chant older than the `operator log`
+ * subcommand, an unreadable answer — lands on the panel as its own sentence: an
+ * empty timeline must never stand in for "behold couldn't ask".
+ */
+function loadOperatorHistory() {
+  if (staticMode || operatorHistory.loading) return;
+  operatorHistory = { ...operatorHistory, loading: true, error: null };
+  apiFetch("/api/operator/log")
+    .then((r) => r.json())
+    .then((j) => {
+      operatorHistory = j && j.history
+        ? { open: true, loading: false, error: null, data: j.history }
+        : { open: true, loading: false, error: (j && j.error) || "the server answered with no timeline", data: null };
+      renderDial();
+    })
+    .catch((e) => {
+      operatorHistory = { open: true, loading: false, error: String(e), data: null };
+      renderDial();
+    });
+}
+
 /**
  * Record a converge gate's resolution — `chant approve <op> <gate>`, delegated
  * exactly as the run gate's signal is.
@@ -3837,6 +3922,9 @@ function approveConvergeGate(op, gate) {
         showToast(`✓ ${gate} — ${APPROVED_SEMANTICS}`, true);
       }
       pollOperatorStatus();
+      // A resolution just became a ledger record. Re-read the timeline only if
+      // it is already open — still a human's ask, not a background refresh.
+      if (operatorHistory.open) loadOperatorHistory();
     });
 }
 

package/web/index.html

@@ -390,9 +390,31 @@
       .operator-meta { font: var(--t-caption)/1.5 var(--font-mono); color: var(--muted);
         overflow-wrap: anywhere; }
       .operator-gates { font: var(--t-caption)/1.6 var(--font-mono); color: var(--pending); flex: none; }
-      /* Why one line is all there is (chant#2029). A statement, not an alarm —
-         the same voice .run-lost uses for what behold does not know. */
+      /* Why one line is all the strip has, and where the rest is (chant#2029).
+         A statement, not an alarm — the same voice .run-lost uses for what
+         behold does not know. */
       .operator-caveat { font-size: var(--t-caption); color: var(--muted); }
+      /* The converge history (chant#2029) — the timeline the strip is NOT,
+         reached from it. Closed by default and read on the click that opens it,
+         so this whole block is inert until a human asks for it. */
+      .operator-history { display: flex; flex-direction: column; gap: 4px; }
+      .operator-history-toggle { align-self: flex-start; background: none; color: var(--pending);
+        border: none; padding: 0; font-size: var(--t-caption); cursor: pointer; }
+      .operator-history-head { font: var(--t-caption)/1.5 var(--font-mono); color: var(--muted); }
+      /* Ticks and gate resolutions, oldest first — chant's own order. The rule
+         down the left is the lane: one column of time, read forward. */
+      .operator-timeline { display: flex; flex-direction: column; gap: 6px;
+        border-left: 1px solid var(--rule); padding-left: 8px; max-height: 320px; overflow-y: auto; }
+      .operator-entry { display: flex; flex-direction: column; gap: 1px; }
+      /* A resolution is the human's half of the loop, so it wears the gate's own
+         colour rather than the tick's. */
+      .operator-entry-gate-resolution .operator-meta { color: var(--managed); }
+      .operator-gated { font: var(--t-caption)/1.5 var(--font-mono); color: var(--foreign);
+        overflow-wrap: anywhere; }
+      /* chant#2028's address. A link only ever appears where a fact carried one
+         — there is no placeholder state for this rule to style. */
+      .operator-url { display: block; font: var(--t-caption)/1.5 var(--font-mono); color: var(--pending);
+        overflow-wrap: anywhere; }
       /* The converge gate's own two lines, inside the shared .run-gate card:
          which loop this is, and what approving actually does. */
       .operator-loop { font: var(--t-caption)/1.5 var(--font-mono); color: var(--foreign); }

package/web/operator.js

@@ -9,13 +9,20 @@
  *
  * What it renders, from the `operator` state the server broadcasts:
  *  - one line per ConvergeOp: the last tick's own log line, verbatim, honestly
- *    dated; the lease; the pending-gate count. ONE line, because chant's status
- *    surface exposes one tick and no history (chant#2029) — this is a strip, and
- *    there is deliberately no code path here that can render a second tick.
+ *    dated; the lease; the pending-gate count. ONE line, because that is what
+ *    `chant operator status` answers with — there is deliberately no code path
+ *    here that can render a second tick onto the strip.
  *  - each pending converge gate as a card whose Approve button says what
  *    approving actually does: it records a fact, and the next tick acts on it.
  *    It does not release anything. That is the run gate, painted by the playhead
  *    panel next door, and the card names its loop so the two can't be confused.
+ *    When the gate fact names where approval happens (chant#2028) the card links
+ *    it, under chant's own words — `approve at:`. When it doesn't, the card is
+ *    exactly the card it was before that field existed.
+ *  - the history, when a human opens it: the converge timeline chant#2029's
+ *    `operator log` reads, ticks and gate resolutions interleaved. It grows from
+ *    the strip and is fetched on the click, never on a timer — the strip is the
+ *    at-a-glance line, the timeline is the thing you go and look at.
  */
 import { waitingFor } from "./run-playhead.js";
 
@@ -46,6 +53,35 @@ export const APPROVE_SEMANTICS =
 /** The past-tense half, for the toast right after the click. */
 export const APPROVED_SEMANTICS = "recorded; the next tick acts on it";
 
+/** The words a gate's address is offered under — chant's own. `chant operator
+ * status`'s human render prints `approve at: <url>` beneath the pending gate, so
+ * the card labels the same fact the same way. */
+export const APPROVE_AT = "approve at:";
+
+/** The resolved half's label. Same field, chant#2028's other end
+ * (`GateResolutionRecord.url`): where the approval DID happen, so the tense
+ * changes — a resolution's link is a record, not an invitation. */
+export const RESOLVED_AT = "resolved at:";
+
+/**
+ * The address behold will put behind an `href`, or null.
+ *
+ * Re-checked here rather than only trusted from the server, exactly as
+ * APPROVE_SEMANTICS is re-stated above: an absolute http/https URL becomes a
+ * link, anything else reads as no address at all and the card renders without
+ * one. A `javascript:` string that reached a ledger must not become a link
+ * because a server was older than this file.
+ */
+export function approvalLink(url) {
+  if (!url || typeof url !== "string") return null;
+  try {
+    const parsed = new URL(url);
+    return parsed.protocol === "http:" || parsed.protocol === "https:" ? url : null;
+  } catch {
+    return null;
+  }
+}
+
 /** Which loop a card belongs to, spelled out. behold draws two gate cards and
  * they resolve through different commands with different effects. */
 export const CONVERGE_LOOP_LINE =
@@ -86,6 +122,8 @@ export function operatorRows(state, now = Date.now()) {
         log: null,
         at: null,
         ago: null,
+        tickId: null,
+        tick: null,
         lease: "free",
         leaseText: state.strip ? "not in the last status read" : "not read yet",
         pendingGates: 0,
@@ -98,6 +136,12 @@ export function operatorRows(state, now = Date.now()) {
       log: r.log,
       at: r.at,
       ago: r.at ? waitingFor(r.at, now) : null,
+      // chant#2027's tick id: whole (so the hover can quote it in full) and
+      // truncated (so the line stays a line). Both null on a chant that
+      // recorded none, and the row then reads exactly as it did before the
+      // field existed.
+      tickId: r.tickId || null,
+      tick: shortTickId(r.tickId),
       lease: r.lease,
       leaseText: leaseText(r),
       pendingGates: r.pendingGates,
@@ -105,6 +149,25 @@ export function operatorRows(state, now = Date.now()) {
   });
 }
 
+/**
+ * How much of a tick id to show.
+ *
+ * chant mints one with `randomUUID()` (chant#2027), so the first block of a
+ * canonical UUID is already the part a human reads out and the part that
+ * distinguishes two ticks in the same ISO second — which is the whole reason
+ * the field exists. Anything shorter than the cut is shown whole rather than
+ * padded: behold never invents characters chant didn't write.
+ */
+export const TICK_ID_CHARS = 8;
+
+/** A tick id, short enough to sit on a strip line. Null in, null out — a chant
+ * older than 0.53.1 recorded no id, and the strip says nothing rather than
+ * showing a placeholder for an identity that doesn't exist. */
+export function shortTickId(id) {
+  if (typeof id !== "string" || !id) return null;
+  return id.length > TICK_ID_CHARS ? id.slice(0, TICK_ID_CHARS) : id;
+}
+
 /** The lease, in words. The holder is always named when there is one — "held"
  * without a holder is a fact nobody can act on. */
 export function leaseText(row) {
@@ -127,12 +190,18 @@ export function operatorHeadline(state) {
 /**
  * The one-tick caveat, said every time there is a tick to say it about.
  *
- * A reader must never take this strip for a shortened timeline: chant's
- * `operator status` keeps only the last ledger record and no CLI exposes the
- * rest (chant#2029), so one line is all there is, not one line behold chose.
+ * A reader must never take this strip for a shortened timeline: `chant operator
+ * status` keeps only the last ledger record per loop, so one line is all this
+ * read has, not one line behold chose. The rest of the history is a different
+ * command (chant#2029) and a different click — which the caveat now points at,
+ * because "this is not a timeline" without saying where the timeline IS would be
+ * the strip keeping a secret.
  */
 export const ONE_TICK_CAVEAT =
-  "One tick per loop — chant's status surface exposes only the last one (chant#2029), so this is a strip, not a timeline.";
+  "One tick per loop — `chant operator status` answers with only the last one. The rest is its own read (chant#2029): open the history below.";
+
+/** What the history disclosure is called, closed and open. */
+export const HISTORY_LABEL = "converge history";
 
 /** The converge gate cards, from the same state. Each already carries the
  * delegated write it performs; nothing here is derived from a graph. */
@@ -140,6 +209,76 @@ export function convergeGates(state) {
   return (state && state.gates) || [];
 }
 
+// ── the timeline (chant#2029) ────────────────────────────────────────────────
+
+/** The rows of a loaded history, or [] for one that hasn't been read. */
+export function timelineRows(history) {
+  return (history && history.data && history.data.entries) || [];
+}
+
+/**
+ * The history's own headline: how much of the ledger this is, and whether there
+ * is more behind it.
+ *
+ * The window is stated on screen rather than implied. behold asks for the newest
+ * n (never the whole ledger — it grows one line per tick forever), so a full
+ * window means "and older ticks before these", and a reader who isn't told that
+ * would read the oldest row as the beginning of history.
+ */
+export function historyHeadline(history) {
+  const data = history && history.data;
+  if (!data) return null;
+  const n = data.entries.length;
+  const head = `${n} ${n === 1 ? "entry" : "entries"}`;
+  const window = data.window || {};
+  const bits = [`newest ${window.limit}`];
+  if (window.since) bits.push(`since ${window.since}`);
+  if (data.more) bits.push("older ticks before these");
+  return `${head} · ${bits.join(" · ")}`;
+}
+
+/**
+ * The unreadable-line count, in words, or null when every line read.
+ *
+ * chant counts the ledger lines it could not parse rather than throwing, so a
+ * corrupted ledger renders a SHORTER timeline. Surfacing the count is the
+ * difference between "3 lines of this ledger are unreadable" and a quiet gap the
+ * reader takes for a quiet loop.
+ */
+export function historyMalformedNote(history) {
+  const m = (history && history.data && history.data.malformed) || null;
+  if (!m) return null;
+  const total = (m.converge || 0) + (m.gates || 0);
+  if (!total) return null;
+  return (
+    `${total} ledger line${total === 1 ? "" : "s"} were unreadable and are missing from this timeline ` +
+    `(converge: ${m.converge || 0}, gates: ${m.gates || 0}).`
+  );
+}
+
+/**
+ * One timeline row, in words — chant's own `operator log` render is the model.
+ *
+ * A tick reads as its op, its id and the log line chant wrote, verbatim; a
+ * resolution reads as who resolved which gate. Nothing here rewords a fact:
+ * behold's job on this surface is ordering and legibility, not narration.
+ */
+export function timelineText(row) {
+  if (!row) return "";
+  if (row.kind === "gate-resolution") {
+    return `gate resolved · ${row.op}/${row.gate} by ${row.resolvedBy}`;
+  }
+  // Bracketed, the way chant's own `operator log` render prints it, and cut by
+  // the strip's own {@link shortTickId} so one tick reads the same in both.
+  const id = shortTickId(row.id) ? ` [${shortTickId(row.id)}]` : "";
+  return `${row.op}${row.env ? `@${row.env}` : ""}${id}`;
+}
+
+/** One gated outcome within a tick, in chant's own `operator log` words. */
+export function gatedText(gate) {
+  return `gated ${gate.rule} → ${gate.op || "?"} gate "${gate.gate}"`;
+}
+
 // ── the DOM half ─────────────────────────────────────────────────────────────
 
 function el(tag, cls, text) {
@@ -149,13 +288,33 @@ function el(tag, cls, text) {
   return n;
 }
 
+/** An `approve at: <url>` link, or null for a fact carrying no address behold
+ * will link. Never a placeholder: the absent case renders nothing at all. */
+function approveAtLink(url, label = APPROVE_AT) {
+  const href = approvalLink(url);
+  if (!href) return null;
+  const a = el("a", "operator-url", `${label} ${href}`);
+  a.href = href;
+  a.target = "_blank";
+  a.rel = "noreferrer noopener";
+  a.title = `${href} — the address the gate fact itself records (chant#2028). behold never invents this link.`;
+  return a;
+}
+
 /**
  * Render the operator strip into `host` (cleared first — the whole subtree is
  * rebuilt per event, exactly as renderPlayhead does).
  *
- * `actions.approve(op, gate)` performs the delegated `chant approve`.
+ * `actions.approve(op, gate)` performs the delegated `chant approve`;
+ * `actions.history()` toggles the timeline below the strip and is what triggers
+ * its one read. Omit it (a static export has no server to ask) and no history
+ * affordance is drawn at all.
+ *
+ * `history` is the caller's own `{open, loading, error, data}` — this module
+ * decides what the panel SAYS, app.js owns the fetch and the open/closed bit,
+ * the same split every other panel here keeps.
  */
-export function renderOperator(host, state, actions = {}) {
+export function renderOperator(host, state, actions = {}, history = null) {
   host.textContent = "";
   if (!hasOperator(state)) return host;
 
@@ -178,8 +337,12 @@ export function renderOperator(host, state, actions = {}) {
     body.appendChild(head);
     // chant's own log line, verbatim — behold re-words nothing about a tick.
     body.appendChild(el("div", "operator-log", r.log || "no tick recorded yet"));
-    const when = r.at ? `last tick ${r.at}${r.ago ? ` (${r.ago} ago)` : ""}` : "never ticked";
-    body.appendChild(el("div", "operator-meta", `${when} · ${r.leaseText}`));
+    // `· tick <id>` only when chant wrote one (chant#2027) — a tick becomes a
+    // thing you can point at, and an older chant's line is unchanged.
+    const when = r.at ? `last tick ${r.at}${r.ago ? ` (${r.ago} ago)` : ""}${r.tick ? ` · tick ${r.tick}` : ""}` : "never ticked";
+    const meta = el("div", "operator-meta", `${when} · ${r.leaseText}`);
+    if (r.tick) meta.title = `tick id ${r.tickId || r.tick}`;
+    body.appendChild(meta);
     row.appendChild(body);
 
     if (r.pendingGates) {
@@ -190,11 +353,76 @@ export function renderOperator(host, state, actions = {}) {
   host.appendChild(list);
 
   if (rows.some((r) => r.at)) host.appendChild(el("div", "operator-caveat", ONE_TICK_CAVEAT));
+  if (actions.history) host.appendChild(renderHistory(history, actions));
 
   for (const gate of convergeGates(state)) host.appendChild(renderConvergeGateCard(gate, actions));
   return host;
 }
 
+/**
+ * The history disclosure and, when it is open, the timeline.
+ *
+ * Closed is the default and costs nothing: the read happens on the click that
+ * opens it, and there is no interval anywhere on this path. The strip above ages
+ * on its own — a tick lands whether or not anyone is looking — but a ledger's
+ * past does not change while you read it, so re-fetching it on a timer would be
+ * spending a chant process per interval to be told the same thing.
+ */
+function renderHistory(history, actions) {
+  const box = el("div", "operator-history");
+  const open = !!(history && history.open);
+  const toggle = el("button", "operator-history-toggle", `${open ? "▾" : "▸"} ${HISTORY_LABEL}`);
+  toggle.title =
+    "The converge timeline: ticks and gate resolutions from the chant/lifecycle ledger " +
+    "(chant operator log, chant#2029). Read when you open it — behold never polls the history.";
+  toggle.addEventListener("click", () => actions.history());
+  box.appendChild(toggle);
+  if (!open) return box;
+
+  if (history.error) {
+    box.appendChild(el("div", "run-lost", `Converge history unavailable — ${history.error}`));
+    return box;
+  }
+  if (history.loading || !history.data) {
+    box.appendChild(el("div", "operator-meta", "reading the converge ledger…"));
+    return box;
+  }
+
+  box.appendChild(el("div", "operator-history-head", historyHeadline(history)));
+  const malformed = historyMalformedNote(history);
+  if (malformed) box.appendChild(el("div", "run-lost", malformed));
+
+  const rows = timelineRows(history);
+  if (!rows.length) {
+    box.appendChild(el("div", "operator-meta", "No converge ticks recorded in this window."));
+    return box;
+  }
+
+  const list = el("div", "operator-timeline");
+  for (const row of rows) {
+    // Oldest first, exactly as chant merged them — a timeline reads forward.
+    const entry = el("div", `operator-entry operator-entry-${row.kind}`);
+    entry.appendChild(el("div", "operator-meta", `${row.at} · ${timelineText(row)}`));
+    if (row.kind === "tick") {
+      // chant's own log line, verbatim — the strip's rule, on every row.
+      entry.appendChild(el("div", "operator-log", row.log));
+      for (const gate of row.gated) {
+        const line = el("div", "operator-gated", gatedText(gate));
+        const link = approveAtLink(gate.url);
+        if (link) line.appendChild(link);
+        entry.appendChild(line);
+      }
+    } else {
+      if (row.note) entry.appendChild(el("div", "operator-log", row.note));
+      const link = approveAtLink(row.url, RESOLVED_AT);
+      if (link) entry.appendChild(link);
+    }
+    list.appendChild(entry);
+  }
+  box.appendChild(list);
+  return box;
+}
+
 /**
  * A pending converge gate.
  *
@@ -205,9 +433,12 @@ export function renderOperator(host, state, actions = {}) {
  *    own gate-ledger doc, and what `chant approve` itself prints;
  *  - the exact command the button delegates to.
  *
- * And one thing it deliberately does not render: a link. A pending gate fact
- * carries no URL (chant#2028), and a placeholder link would invent a review
- * surface that does not exist.
+ * And the fourth, since chant#2028: where approval happens, when the gate fact
+ * says so. `approve at: <url>` — chant's own words from `operator status`'s
+ * human render — linking the PR/MR the gated tick knew about. A fact with no
+ * address renders no link and no placeholder for one: the url is optional by
+ * design (a local tick with no PR behind it genuinely has none), and inventing a
+ * review surface would be worse than the shell command it replaces.
  */
 export function renderConvergeGateCard(gate, actions = {}) {
   const box = el("div", "run-gate operator-gate");
@@ -224,6 +455,8 @@ export function renderConvergeGateCard(gate, actions = {}) {
     ),
   );
   box.appendChild(el("div", "operator-semantics", gate.semantics || APPROVE_SEMANTICS));
+  const at = approveAtLink(gate.url);
+  if (at) box.appendChild(at);
 
   const command = (gate.approve && gate.approve.command) || `chant approve ${gate.op} ${gate.gate}`;
   const approve = el("button", "approve", "Record approval");