@intentius/behold 0.11.0 → 0.13.0

package/web/carve-steps.js

@@ -280,6 +280,30 @@ 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 —
@@ -372,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"));
@@ -450,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(
@@ -669,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);
@@ -693,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,8 @@ import {
   edgeLine,
   initialCarveState,
   lintVerdict,
+  manifestStageLine,
+  manifestStateFor,
   observeSummary,
   pickFacts,
   runbookCommands,
@@ -277,3 +279,68 @@ describe("observeSummary", () => {
     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/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;
+}

package/web/operator.test.js

@@ -0,0 +1,158 @@
+// #234 joins 3 + 1: the pure half of web/operator.js, tested the way
+// web/run-playhead.js (#284) is — no DOM, no jsdom, no browser. Everything the
+// strip DECIDES (which loops get a row, how a lease reads, what the approve
+// button says it does) is a function from data to data; the DOM half is
+// smoke/ui-smoke.mjs's job.
+import { describe, it, expect } from "vitest";
+import {
+  hasOperator,
+  operatorRefusal,
+  operatorRows,
+  leaseText,
+  operatorHeadline,
+  convergeGates,
+  APPROVE_SEMANTICS,
+  APPROVED_SEMANTICS,
+  CONVERGE_LOOP_LINE,
+  ONE_TICK_CAVEAT,
+  LEASE_LABEL,
+} from "./operator.js";
+
+/** src/operator.ts's OperatorState, as the server broadcasts it. Values trace to
+ * chant's own operator tests — see src/operator.test.ts's provenance note. */
+const declared = [{ name: "staging-converge", env: "staging", dial: "apply" }];
+const stripRow = {
+  op: "staging-converge",
+  env: "staging",
+  log: "converge(staging): drifted=1 remediated=0 reported=0 skipped-budget=0 skipped-flap=0 gated=1 unobserved=0 adopted=0",
+  at: "2026-01-01T00:00:00.000Z",
+  lease: "held",
+  leaseHolder: "op-a",
+  leaseExpiresAt: "2026-01-01T00:05:00.000Z",
+  pendingGates: 1,
+};
+const gate = {
+  loop: "converge",
+  rule: "drift-apply",
+  op: "fountain-apply",
+  gate: "rollout-gate",
+  convergeOp: "staging-converge",
+  env: "staging",
+  since: "2026-01-01T00:00:00.000Z",
+  semantics: APPROVE_SEMANTICS,
+  approve: {
+    method: "POST",
+    path: "/api/operator/approve/fountain-apply/rollout-gate",
+    command: "chant approve fountain-apply rollout-gate",
+  },
+};
+const state = {
+  declared,
+  strip: { rows: [stripRow], pendingGates: 1 },
+  gates: [gate],
+  note: null,
+  code: null,
+  readAt: "2026-01-01T00:02:00.000Z",
+};
+const NOW = Date.parse("2026-01-01T00:02:00.000Z");
+
+describe("hasOperator", () => {
+  it("gates the strip on a DECLARED loop, never on a status read having answered", () => {
+    expect(hasOperator(null)).toBe(false);
+    expect(hasOperator({ declared: [] })).toBe(false);
+    // Declared, never read: the strip still appears and says so.
+    expect(hasOperator({ declared, strip: null })).toBe(true);
+  });
+});
+
+describe("operatorRefusal", () => {
+  it("is null on a clean read", () => {
+    expect(operatorRefusal(state)).toBeNull();
+  });
+
+  it("states a refusal plainly for each of the three ways a read can fail", () => {
+    for (const code of ["no-operator", "no-operator-cli", "operator-status"]) {
+      const r = operatorRefusal({ ...state, strip: null, gates: [], note: `something about ${code}`, code });
+      expect(r).toEqual({ code, text: `something about ${code}` });
+    }
+  });
+});
+
+describe("operatorRows", () => {
+  it("prints chant's own tick line verbatim, with the instant and a coarse age", () => {
+    const [row] = operatorRows(state, NOW);
+    expect(row.log).toBe(stripRow.log);
+    expect(row.at).toBe("2026-01-01T00:00:00.000Z");
+    expect(row.ago).toBe("2m");
+  });
+
+  it("keeps a declared loop the last read didn't mention, rather than undercounting", () => {
+    const rows = operatorRows({ ...state, declared: [...declared, { name: "prod-observe", env: "prod" }] }, NOW);
+    expect(rows.map((r) => r.op)).toEqual(["staging-converge", "prod-observe"]);
+    expect(rows[1]).toMatchObject({ log: null, at: null, leaseText: "not in the last status read" });
+  });
+
+  it("says a declared loop has not been read yet before the first ask", () => {
+    const [row] = operatorRows({ ...state, strip: null, gates: [] }, NOW);
+    expect(row.leaseText).toBe("not read yet");
+  });
+});
+
+describe("leaseText", () => {
+  it("always names the holder — 'held' with nobody named is unactionable", () => {
+    expect(leaseText(stripRow)).toBe("lease held by op-a until 2026-01-01T00:05:00.000Z");
+  });
+
+  it("says an expired lease will be reclaimed, not that it is free", () => {
+    expect(leaseText({ ...stripRow, lease: "expired" })).toMatch(/expired \(op-a until .+\) — the next round reclaims it/);
+  });
+
+  it("reads a lease-less row as free", () => {
+    expect(leaseText({ ...stripRow, lease: "free", leaseHolder: null })).toBe(LEASE_LABEL.free);
+  });
+});
+
+describe("operatorHeadline", () => {
+  it("counts the loops, and the gates when a human is owed one", () => {
+    expect(operatorHeadline(state)).toBe("⟳ operating loop — 1 ConvergeOp · 1 gate pending");
+    expect(operatorHeadline({ ...state, gates: [] })).toBe("⟳ operating loop — 1 ConvergeOp");
+  });
+});
+
+describe("the one-tick caveat", () => {
+  it("says the strip is not a timeline, and why", () => {
+    expect(ONE_TICK_CAVEAT).toMatch(/only the last one/);
+    expect(ONE_TICK_CAVEAT).toMatch(/chant#2029/);
+    expect(ONE_TICK_CAVEAT).toMatch(/strip, not a timeline/);
+  });
+});
+
+describe("the converge gate card's words", () => {
+  it("says approving records a fact and does not unblock the dispatch", () => {
+    expect(APPROVE_SEMANTICS).toMatch(/records a fact/);
+    expect(APPROVE_SEMANTICS).toMatch(/does not unblock the dispatch/);
+    expect(APPROVE_SEMANTICS).toMatch(/next tick reads it/);
+    expect(APPROVED_SEMANTICS).toBe("recorded; the next tick acts on it");
+  });
+
+  it("names its loop, so it can't be read as the Temporal run gate", () => {
+    expect(CONVERGE_LOOP_LINE).toMatch(/converge loop/);
+    expect(CONVERGE_LOOP_LINE).toMatch(/chant approve/);
+    expect(CONVERGE_LOOP_LINE).toMatch(/not the Temporal run gate/);
+  });
+
+  it("carries the delegated write it performs, and no URL (chant#2028)", () => {
+    const [g] = convergeGates(state);
+    expect(g.approve).toEqual({
+      method: "POST",
+      path: "/api/operator/approve/fountain-apply/rollout-gate",
+      command: "chant approve fountain-apply rollout-gate",
+    });
+    expect(JSON.stringify(g)).not.toMatch(/https?:/);
+  });
+
+  it("has no cards when nothing is pending", () => {
+    expect(convergeGates({ ...state, gates: [] })).toEqual([]);
+    expect(convergeGates(null)).toEqual([]);
+  });
+});