@intentius/behold 0.10.1 → 0.12.0

package/web/carve-steps.js

@@ -66,7 +66,11 @@ export function initialCarveState() {
     /** POST /api/carve/plan's answer (live tier only). Estate-wide, so a new
      * pick keeps it — the plan is about the armed Terraform, not the pick. */
     plan: null,
-    /** Which step is mid-run ("emit" | "bridge" | "plan" | null). */
+    /** POST /api/carve/observe's answer (live tier only) — chant reading the
+     * carved resource live while Terraform still owns it (chant#1647). About
+     * THIS pick's carveout, so a new pick drops it with emit/bridge. */
+    observe: null,
+    /** Which step is mid-run ("emit" | "bridge" | "plan" | "observe" | null). */
     busy: null,
     /** The last structured refusal, keyed by step id. */
     error: null,
@@ -276,6 +280,56 @@ export function lintVerdict(lint) {
   return { tone: "bad", text: `chant lint exited ${lint.code} — the emitted source doesn't pass yet` };
 }
 
+/**
+ * The carve state manifest for one address, off `/api/project`'s
+ * `carve.state` (#230 M3). Null when nothing has been carved for it — which is
+ * the honest reading before Emit runs, and the reading a fresh clone gives.
+ */
+export function manifestStateFor(carveState, address) {
+  const states = (carveState && carveState.states) || [];
+  return states.find((s) => s.target === address) || null;
+}
+
+/**
+ * A carve's recorded stage as one line + a tone.
+ *
+ * `applied` is the only green: it is the only stage at which ownership has
+ * actually moved. `emitted` and `bridged` are real progress and read as such
+ * (the pending blue, the same tone the card carries), but they are work in
+ * flight, not a graduation — and the line says which, in words, because tone
+ * alone was never allowed to carry a state here.
+ */
+export function manifestStageLine(state) {
+  if (!state) return null;
+  return { tone: state.graduated ? "good" : "pending", text: `${state.target}: ${state.note}` };
+}
+
+/**
+ * The observe verdict as one line + a tone (chant#1647). `observed` with
+ * EXTERNAL/foreign IS the beat: live, outside every stack, still Terraform's —
+ * and chant read it clean anyway. `unobserved` repeats chant's own hole
+ * ("not a verdict about the resource" is #1089's rule said small). `missing`
+ * names the one honest local cause: a demo-copy chant that predates the
+ * identity read path.
+ */
+export function observeSummary(o) {
+  if (!o) return null;
+  if (o.verdict === "observed") {
+    const how = [o.status, o.ownership ? `ownership ${o.ownership}` : null].filter(Boolean).join(", ");
+    return {
+      tone: "good",
+      text: `${o.entity}: observed${how ? ` (${how})` : ""} — Terraform still owns it, and chant read it clean. Nothing blinked.`,
+    };
+  }
+  if (o.verdict === "unobserved") {
+    return { tone: "warn", text: `${o.entity}: the read itself had a hole — ${o.detail || "unobserved"}. Not a verdict about the resource.` };
+  }
+  return {
+    tone: "warn",
+    text: `${o.entity}: read MISSING. The demo copy's chant predates the identity read path (chant#1647, fixed in chant ≥ 0.44.12) — npm install in the copy's app/ and re-run.`,
+  };
+}
+
 // ---------------------------------------------------------------------------
 // The DOM half. Plain browser JS, no build step, themed entirely by the shared
 // CSS vars — same rules as app.js. `actions` is the host's wiring:
@@ -342,6 +396,18 @@ function artifactBlock(a, actions) {
   return wrap;
 }
 
+/** A dot + a line, tone reinforcing the words (never replacing them). `good` is
+ * the managed green, `pending` the in-flight blue pinhole paints `accent` cards
+ * with, anything else the degraded red. */
+function toneRow(tone, text, tag) {
+  const row = el("div", "count-row");
+  const dot = el("span", "dot");
+  dot.style.background = tone === "good" ? "var(--managed)" : tone === "pending" ? "var(--pending)" : "var(--degraded)";
+  row.append(dot, el("span", "grow", text));
+  if (tag) row.appendChild(el("span", "tag", tag));
+  return row;
+}
+
 function refusalBlock(err) {
   const wrap = el("div", "carve-refusal");
   wrap.appendChild(el("div", "carve-refusal-title", err.error || "that step didn't run"));
@@ -420,6 +486,16 @@ function renderAdvise(body, ctx) {
     row.append(dot, el("span", "grow", meaning), el("span", "tag", String(bands[band] ?? 0)));
     body.appendChild(row);
   }
+  // #230 M3: what the estate has ALREADY carved, off chant's own state
+  // manifests rather than off this session. Reload the page mid-walkthrough and
+  // this is unchanged, because the manifests on disk are unchanged.
+  const carveState = ctx.carve && ctx.carve.state;
+  if (carveState && carveState.manifests) {
+    body.appendChild(el("h3", null, "carved so far"));
+    body.appendChild(toneRow("good", carveState.progress.label, `${carveState.manifests} manifest(s)`));
+    for (const s of carveState.states) body.appendChild(toneRow(s.graduated ? "good" : "pending", s.target, s.stage));
+    if (carveState.progress.detail) body.appendChild(el("p", "panel-muted", carveState.progress.detail));
+  }
   if (ctx.carve && ctx.carve.advisory) body.appendChild(el("p", "panel-muted", ctx.carve.advisory));
   if (ctx.demo) {
     body.appendChild(
@@ -436,7 +512,7 @@ function renderAdvise(body, ctx) {
           "panel-muted carve-live-note",
           `Live tier: the starred resources are REALLY applied into a scratch Floci (${ctx.demo.live.endpoint}, ` +
             "deleted when this server exits) and the tfstate the advisor read was written by terraform, not shipped. " +
-            "The observe beat — chant reading the bucket live while Terraform still owns it — waits on chant#1647.",
+            "After Emit, the observe beat reads the carved resource live while Terraform still owns it (chant#1647).",
         ),
       );
     }
@@ -519,6 +595,27 @@ function renderEmit(body, state, ctx, actions) {
   caveat.appendChild(el("p", "panel-muted", e.buildCaveat || (ctx.demo && ctx.demo.buildCaveat) || ""));
   body.appendChild(caveat);
 
+  // The observe beat (#254, chant#1647): chant reads the carved resource live
+  // FROM THE CARVEOUT, against the scratch Floci, while Terraform still owns
+  // it. Live tier only — offline has no live to read.
+  if (ctx.demo && ctx.demo.live) {
+    const obsBtn = el("button", "act carve-observe", state.busy === "observe" ? "observing…" : "▶ watch chant read it live");
+    obsBtn.disabled = !!state.busy;
+    obsBtn.title = "Runs chant lifecycle diff --live in the carveout against the scratch Floci. Reads everything, changes nothing.";
+    obsBtn.addEventListener("click", actions.runObserve);
+    body.appendChild(obsBtn);
+    const summary = observeSummary(state.observe);
+    if (summary) {
+      const row = el("div", "count-row");
+      const dot = el("span", "dot");
+      dot.style.background = summary.tone === "good" ? "var(--managed)" : "var(--degraded)";
+      row.append(dot, el("span", "grow", summary.text));
+      body.appendChild(row);
+      if (state.observe.queried) body.appendChild(pre(state.observe.command + "\n→ queried " + state.observe.queried, "carve-cmd"));
+      else body.appendChild(pre(state.observe.command, "carve-cmd"));
+    }
+  }
+
   body.appendChild(el("h3", null, "emitted"));
   for (const a of e.artifacts || []) body.appendChild(artifactBlock(a, actions));
 
@@ -618,6 +715,32 @@ function renderHandoff(body, state, ctx, actions) {
     if (c.note) body.appendChild(el("p", "panel-muted carve-cmd-note", c.note));
   }
 
+  // The graduation step (#230 M3). `chant carve apply` resolves the ownership
+  // marker that makes chant the owner of a live resource, and it composes off
+  // the carve manifest — no --select needed, the emit left the target there.
+  //
+  // It is echoed here for the same reason `terraform state rm` is: this is
+  // where the temptation to add a button lives. There is no apply endpoint on
+  // the server and no apply button here, and neither is a gap waiting to be
+  // filled — behold triggers delegated work, it does not decide when an estate
+  // changes hands. What the manifest RECORDS about an apply is rendered (the
+  // Done step, and the Advise step's "carved so far"); the trigger is a person.
+  const applyState = manifestStateFor(ctx.carve && ctx.carve.state, state.pick && state.pick.node.id);
+  if (applyState) {
+    body.appendChild(el("h3", null, "graduation"));
+    const line = manifestStageLine(applyState);
+    body.appendChild(toneRow(line.tone, line.text));
+    if (!applyState.graduated) {
+      // Its own class, not the runbook's: this row is chant's command, not one
+      // of the runbook's terraform lines, and the two are counted separately.
+      const row = el("div", "prow carve-cmd-row carve-apply-row");
+      row.appendChild(el("code", "grow carve-cmd-text", applyState.applyCommand));
+      row.appendChild(copyButton("copy", applyState.applyCommand, actions));
+      body.appendChild(row);
+      body.appendChild(el("p", "panel-muted carve-cmd-note", (ctx.carve.state.apply && ctx.carve.state.apply.note) || ""));
+    }
+  }
+
   const ran = el("button", "act carve-ran", state.handoff ? "✓ marked as run" : "I ran these →");
   ran.title = "Marks the handoff done in this walkthrough. behold has not checked — it can't, and won't pretend to.";
   ran.addEventListener("click", actions.markHandoff);
@@ -642,6 +765,13 @@ function renderDone(body, state, ctx, actions) {
   );
   body.appendChild(card);
 
+  // #230 M3: the durable half of the ending. The card above is the shape of the
+  // walkthrough; this is what chant's manifest actually records — and it is
+  // still here after a restart, when everything in `state` is gone.
+  const recorded = manifestStateFor(ctx.carve && ctx.carve.state, state.pick && state.pick.node.id);
+  const line = manifestStageLine(recorded);
+  if (line) body.appendChild(toneRow(line.tone, line.text, recorded.stage));
+
   if (!state.handoff) {
     body.appendChild(el("p", "panel-muted", "The handoff commands haven't been marked as run — this is the shape of the ending, not a claim about your estate."));
   }

package/web/carve-steps.test.js

@@ -15,6 +15,9 @@ import {
   edgeLine,
   initialCarveState,
   lintVerdict,
+  manifestStageLine,
+  manifestStateFor,
+  observeSummary,
   pickFacts,
   runbookCommands,
   stepStatus,
@@ -241,8 +244,103 @@ describe("lintVerdict", () => {
     expect(bad.tone).toBe("bad");
     expect(bad.text).toContain("exited 1");
   });
+});
+
+// The observe beat's one-line verdicts (#254, chant#1647). `observed` is the
+// claim the whole tier films; the other two must stay distinguishable — a hole
+// in the read is not a verdict about the resource (#1089), and MISSING has
+// exactly one honest local cause worth naming.
+describe("observeSummary", () => {
+  it("is null before any observe ran", () => {
+    expect(observeSummary(null)).toBeNull();
+  });
+
+  it("observed: names the how and claims the beat", () => {
+    const s = observeSummary({ entity: "assets", verdict: "observed", status: "EXTERNAL", ownership: "foreign" });
+    expect(s.tone).toBe("good");
+    expect(s.text).toContain("assets: observed (EXTERNAL, ownership foreign)");
+    expect(s.text).toContain("Nothing blinked");
+  });
+
+  it("unobserved: repeats chant's own hole and refuses to call it a verdict", () => {
+    const s = observeSummary({ entity: "assets", verdict: "unobserved", detail: "read-failed: connection refused" });
+    expect(s.tone).toBe("warn");
+    expect(s.text).toContain("read-failed: connection refused");
+    expect(s.text).toContain("Not a verdict about the resource");
+  });
+
+  it("missing: names the one honest local cause", () => {
+    const s = observeSummary({ entity: "assets", verdict: "missing" });
+    expect(s.tone).toBe("warn");
+    expect(s.text).toContain("chant#1647");
+  });
 
   it("is null with no lint at all — nothing to claim", () => {
     expect(lintVerdict(null)).toBeNull();
   });
 });
+
+// ---------------------------------------------------------------------------
+// #230 M3 — the manifest-backed state the panel reads off /api/project.
+// ---------------------------------------------------------------------------
+
+const CARVE_STATE = {
+  manifests: 2,
+  progress: {
+    applied: 1,
+    bridged: 0,
+    emitted: 1,
+    inFlight: 1,
+    total: 12,
+    label: "1 of 12 carved",
+    detail: "1 emitted — apply is yours",
+  },
+  states: [
+    {
+      target: "aws_iam_role.api",
+      stage: "emitted",
+      graduated: false,
+      note: "emitted — typed chant source exists, and the surviving Terraform still reads the resource directly. `carve bridge` is next.",
+      applyCommand: "chant carve apply --from legacy-tf --output app/carveout --env <env> --stack <stack> --write-source",
+    },
+    {
+      target: "aws_s3_bucket.assets",
+      stage: "applied",
+      graduated: true,
+      note: "graduated — `carve apply` recorded the ownership marker (stack assets, env prod). chant owns it.",
+      applyCommand: "chant carve apply --from legacy-tf --output app/carveout --env prod --stack assets --write-source",
+    },
+  ],
+  apply: { human: true, note: "behold has no apply endpoint and no apply button, by design." },
+};
+
+describe("manifestStateFor", () => {
+  it("finds the carve recorded for an address", () => {
+    expect(manifestStateFor(CARVE_STATE, "aws_s3_bucket.assets").stage).toBe("applied");
+  });
+
+  it("is null for an address nothing has been carved for — the honest read before Emit", () => {
+    expect(manifestStateFor(CARVE_STATE, "aws_vpc.main")).toBeNull();
+    expect(manifestStateFor(null, "aws_s3_bucket.assets")).toBeNull();
+    expect(manifestStateFor(CARVE_STATE, null)).toBeNull();
+  });
+});
+
+describe("manifestStageLine", () => {
+  it("greens only the graduated one — the only stage at which ownership moved", () => {
+    const line = manifestStageLine(manifestStateFor(CARVE_STATE, "aws_s3_bucket.assets"));
+    expect(line.tone).toBe("good");
+    expect(line.text).toContain("chant owns it");
+  });
+
+  it("paints a partial carve as in flight, and says which stage in words", () => {
+    const line = manifestStageLine(manifestStateFor(CARVE_STATE, "aws_iam_role.api"));
+    expect(line.tone).toBe("pending");
+    expect(line.text).toContain("aws_iam_role.api");
+    expect(line.text).toContain("still reads the resource directly");
+  });
+
+  it("is null with nothing recorded — no manifest, no claim", () => {
+    expect(manifestStageLine(null)).toBeNull();
+  });
+});

package/web/index.html

@@ -347,6 +347,67 @@
       .dial-detail { display: flex; flex-wrap: wrap; gap: 4px 12px; color: var(--muted);
         font: var(--t-caption)/1.6 var(--font-mono); }
 
+      /* The run playhead (#284 item 2) — the Op run's verdict, the pending gate
+         card (#234), and the steps that have actually settled. Sits under the
+         dial's apply progress, in the same tokens, so "green means it worked"
+         reads the same in both. */
+      .run-playhead { display: flex; flex-direction: column; gap: 6px; width: 100%; margin-top: 6px; }
+      .run-verdict { font-size: var(--t-caption); }
+      /* What behold does NOT know — a lost stream, an unreachable gate query.
+         Same voice as the carve refusal: a statement, not an alarm. */
+      .run-lost { border-left: 3px solid var(--foreign); background: var(--well);
+        border-radius: var(--r-ctl); padding: 4px 8px; color: var(--muted);
+        font: var(--t-caption)/1.5 var(--font-mono); }
+      .run-steps { display: flex; flex-direction: column; gap: 2px; }
+      .run-step { display: flex; align-items: center; gap: 6px;
+        font: var(--t-caption)/1.6 var(--font-mono); color: var(--fg); }
+      .run-dot { width: 6px; height: 6px; border-radius: 50%; flex: none; }
+      .run-took { color: var(--muted); }
+      /* A human decision is owed: the same --pending edge the carve
+         walkthrough's human refusal wears. */
+      .run-gate { border: 1px solid var(--pending); border-left: 3px solid var(--pending);
+        border-radius: var(--r-ctl); padding: 6px 8px; background: var(--well);
+        display: flex; flex-direction: column; gap: 3px; align-items: flex-start; }
+      .run-gate-title { font-size: var(--t-body); color: var(--pending); }
+      .run-gate-desc { font-size: var(--t-caption); }
+      .run-gate-meta { font: var(--t-caption)/1.5 var(--font-mono); color: var(--muted);
+        overflow-wrap: anywhere; }
+      .run-gate button.approve { margin-top: 3px; background: var(--well); color: var(--managed);
+        border: 1px solid var(--managed); border-radius: var(--r-ctl); padding: 3px 12px;
+        font-size: var(--t-body); cursor: pointer; }
+      /* The operator strip (#234 join 3) — one honestly-dated tick per
+         ConvergeOp, its lease, its pending gates. Sits above the run playhead in
+         the same tokens: both are "what is happening to this project's Ops", and
+         the loop is the one that never stopped. */
+      .operator-strip { display: flex; flex-direction: column; gap: 6px; width: 100%; margin-top: 6px; }
+      .operator-title { font-size: var(--t-caption); color: var(--pending); }
+      .operator-rows { display: flex; flex-direction: column; gap: 4px; }
+      .operator-row { display: flex; align-items: flex-start; gap: 6px; }
+      .operator-op { font-size: var(--t-body); color: var(--fg); }
+      /* chant's own tick line, verbatim — mono, because it is a log line. */
+      .operator-log { font: var(--t-caption)/1.5 var(--font-mono); color: var(--fg);
+        overflow-wrap: anywhere; }
+      .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. */
+      .operator-caveat { font-size: var(--t-caption); color: var(--muted); }
+      /* 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); }
+      .operator-semantics { font-size: var(--t-caption); color: var(--fg); }
+      /* #234 free rider: the operating loop's home on the graph — the same
+         --pending edge the run gate wears, because both say "a loop is running
+         here", not "something is wrong". */
+      #graph [data-node-id].operator-home rect:first-of-type { stroke: var(--pending); stroke-width: 2; }
+
+      /* The step the playhead sits on, on the graph itself — the ops lens marks
+         it `_playhead` and the card wears a dashed edge, so "here" reads
+         differently from "this one is done". */
+      #graph [data-node-id].playhead rect:first-of-type { stroke: var(--pending); stroke-width: 2;
+        stroke-dasharray: 4 3; }
+
       /* The carve walkthrough (#254) — the panel's Carve tab. Six steps on the
          same track the deploy dial uses, so "where am I in this" reads the same
          way in both places; below it, the step's own panel. Every colour here is

package/web/layout-store.js

@@ -157,10 +157,10 @@ export function straightEdge(anchors, from, to) {
 // "I need more room" means grow the box first (#245 already resizes them).
 //
 // No twin in src/layout.ts, unlike the three functions above: the server-side
-// bake does not reconstruct containment boxes (only pinhole's architecture
-// layout stamps them with a `data-group-id`, and not every lens uses it — see
-// wrapContainmentBoxes in web/app.js), so it has nothing to clamp against and
-// deliberately does not try.
+// bake does not reconstruct containment boxes (pinhole stamps every layout's
+// boxes with `data-group-id` since 0.3.5, but the bake still parses no box
+// geometry — see wrapContainmentBoxes in web/app.js), so it has nothing to
+// clamp against and deliberately does not try.
 
 /** How far a card keeps off its container's edge, in viewBox units. */
 export const CLAMP_PAD = 8;

package/web/operator.js

@@ -0,0 +1,236 @@
+/**
+ * The operator strip and the converge gate card (#234 joins 3 + 1) — the SPA
+ * half of src/operator.ts.
+ *
+ * Same discipline as web/run-playhead.js next door: everything this panel
+ * DECIDES is a pure function that takes data and returns data, unit-tested in
+ * operator.test.js; the DOM half at the bottom is smoke/ui-smoke.mjs's job. The
+ * fetches, the poll and the SSE subscription all stay in app.js.
+ *
+ * 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.
+ *  - 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.
+ */
+import { waitingFor } from "./run-playhead.js";
+
+/** How a lease reads. `expired` is its own tone, not a shade of `free`: a lapsed
+ * lease means the holder stopped renewing and the next round reclaims it, which
+ * is a different statement from "nobody has ever held it". */
+export const LEASE_COLOR = {
+  held: "var(--managed)",
+  expired: "var(--foreign)",
+  free: "var(--muted)",
+};
+
+export const LEASE_LABEL = {
+  held: "lease held",
+  expired: "lease expired",
+  free: "lease free",
+};
+
+/**
+ * The one sentence the card must never soften — kept in step with
+ * src/operator.ts's `APPROVE_SEMANTICS`, and re-stated here rather than only
+ * trusted from the server so the card still tells the truth if an older server
+ * omits the field.
+ */
+export const APPROVE_SEMANTICS =
+  "Approving records a fact in the gate ledger; it does not unblock the dispatch. The next tick reads it.";
+
+/** The past-tense half, for the toast right after the click. */
+export const APPROVED_SEMANTICS = "recorded; the next tick acts on it";
+
+/** 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 =
+  "converge loop · chant approve — not the Temporal run gate, which is signalled and does release its run";
+
+/** Does the served project declare an operating loop at all? The strip is gated
+ * on the DECLARATION (read from the emitted op.json), never on whether a status
+ * read happened to answer — so a declared loop behold couldn't read still shows,
+ * saying why, instead of vanishing as if no loop existed. */
+export function hasOperator(state) {
+  return Boolean(state && Array.isArray(state.declared) && state.declared.length);
+}
+
+/** The refusal to state plainly, or null when the last read succeeded. */
+export function operatorRefusal(state) {
+  if (!state || !state.note) return null;
+  return { code: state.code || "operator-status", text: state.note };
+}
+
+/**
+ * One row per ConvergeOp, ready to paint.
+ *
+ * A loop that is declared but absent from the last status read still gets a row
+ * — from its declaration alone, saying it has not been read. Dropping it would
+ * make the strip undercount the loops the project runs, which is the one thing a
+ * strip about "how many loops and what did they last do" must not do.
+ */
+export function operatorRows(state, now = Date.now()) {
+  if (!hasOperator(state)) return [];
+  const read = new Map(((state.strip && state.strip.rows) || []).map((r) => [r.op, r]));
+  return (state.declared || []).map((d) => {
+    const r = read.get(d.name);
+    if (!r) {
+      return {
+        op: d.name,
+        env: d.env || null,
+        dial: d.dial || null,
+        log: null,
+        at: null,
+        ago: null,
+        lease: "free",
+        leaseText: state.strip ? "not in the last status read" : "not read yet",
+        pendingGates: 0,
+      };
+    }
+    return {
+      op: r.op,
+      env: r.env || d.env || null,
+      dial: d.dial || null,
+      log: r.log,
+      at: r.at,
+      ago: r.at ? waitingFor(r.at, now) : null,
+      lease: r.lease,
+      leaseText: leaseText(r),
+      pendingGates: r.pendingGates,
+    };
+  });
+}
+
+/** 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) {
+  if (row.lease === "free" || !row.leaseHolder) return LEASE_LABEL.free;
+  const until = row.leaseExpiresAt ? ` until ${row.leaseExpiresAt}` : "";
+  return row.lease === "expired"
+    ? `lease expired (${row.leaseHolder}${until}) — the next round reclaims it`
+    : `lease held by ${row.leaseHolder}${until}`;
+}
+
+/** The strip's own headline: how many loops, how many gates are owed a human. */
+export function operatorHeadline(state) {
+  if (!hasOperator(state)) return null;
+  const n = state.declared.length;
+  const gates = (state.gates || []).length;
+  const head = `⟳ operating loop — ${n} ConvergeOp${n === 1 ? "" : "s"}`;
+  return gates ? `${head} · ${gates} gate${gates === 1 ? "" : "s"} pending` : head;
+}
+
+/**
+ * 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.
+ */
+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.";
+
+/** The converge gate cards, from the same state. Each already carries the
+ * delegated write it performs; nothing here is derived from a graph. */
+export function convergeGates(state) {
+  return (state && state.gates) || [];
+}
+
+// ── the DOM half ─────────────────────────────────────────────────────────────
+
+function el(tag, cls, text) {
+  const n = document.createElement(tag);
+  if (cls) n.className = cls;
+  if (text !== undefined) n.textContent = text;
+  return n;
+}
+
+/**
+ * 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`.
+ */
+export function renderOperator(host, state, actions = {}) {
+  host.textContent = "";
+  if (!hasOperator(state)) return host;
+
+  host.appendChild(el("div", "operator-title", operatorHeadline(state)));
+
+  const refusal = operatorRefusal(state);
+  if (refusal) host.appendChild(el("div", "run-lost", `Operator status unavailable — ${refusal.text}`));
+
+  const rows = operatorRows(state);
+  const list = el("div", "operator-rows");
+  for (const r of rows) {
+    const row = el("div", "operator-row");
+    const dot = el("span", "run-dot");
+    dot.style.background = LEASE_COLOR[r.lease] || "var(--muted)";
+    dot.title = r.leaseText;
+    row.appendChild(dot);
+
+    const body = el("div", "grow");
+    const head = el("div", "operator-op", r.env ? `${r.op} (${r.env})${r.dial ? ` · dial ${r.dial}` : ""}` : r.op);
+    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}`));
+    row.appendChild(body);
+
+    if (r.pendingGates) {
+      row.appendChild(el("span", "operator-gates", `${r.pendingGates} gate${r.pendingGates === 1 ? "" : "s"}`));
+    }
+    list.appendChild(row);
+  }
+  host.appendChild(list);
+
+  if (rows.some((r) => r.at)) host.appendChild(el("div", "operator-caveat", ONE_TICK_CAVEAT));
+
+  for (const gate of convergeGates(state)) host.appendChild(renderConvergeGateCard(gate, actions));
+  return host;
+}
+
+/**
+ * A pending converge gate.
+ *
+ * Three things this card says out loud, because getting any of them wrong would
+ * make the button lie:
+ *  - which loop it belongs to (converge, not the Temporal run gate next door);
+ *  - that approving RECORDS A FACT and does not unblock the dispatch — chant's
+ *    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.
+ */
+export function renderConvergeGateCard(gate, actions = {}) {
+  const box = el("div", "run-gate operator-gate");
+  box.appendChild(el("div", "run-gate-title", `⏸ converge gate — ${gate.gate}`));
+  box.appendChild(el("div", "operator-loop", CONVERGE_LOOP_LINE));
+  const waited = gate.since ? waitingFor(gate.since) : null;
+  box.appendChild(
+    el(
+      "div",
+      "run-gate-meta",
+      `rule ${gate.rule} → ${gate.op}` +
+        `${gate.convergeOp ? ` · recorded by ${gate.convergeOp}${gate.env ? ` (${gate.env})` : ""}` : ""}` +
+        `${gate.since ? ` · gated ${waited ? `${waited} ago, ` : ""}${gate.since}` : ""}`,
+    ),
+  );
+  box.appendChild(el("div", "operator-semantics", gate.semantics || APPROVE_SEMANTICS));
+
+  const command = (gate.approve && gate.approve.command) || `chant approve ${gate.op} ${gate.gate}`;
+  const approve = el("button", "approve", "Record approval");
+  approve.title =
+    `${(gate.approve && gate.approve.method) || "POST"} ${(gate.approve && gate.approve.path) || ""} — ` +
+    `${command}. ${gate.semantics || APPROVE_SEMANTICS} behold never approves on its own.`;
+  approve.addEventListener("click", () => actions.approve?.(gate.op, gate.gate));
+  box.appendChild(approve);
+  return box;
+}