@intentius/behold 0.11.0 → 0.13.0

package/web/app.js

@@ -43,6 +43,15 @@ import { isContainer, jsonCell, renderJson, scalarText } from "./json-view.js";
 // #268: the demo catalog's presentation — what a catalog row's button says
 // about it (disabled + reason, or the fetch it would do).
 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";
+// #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
+// the playhead — the decisions are pure in there, the fetches stay here.
+import { hasOperator, renderOperator, APPROVED_SEMANTICS } from "./operator.js";
 initTheme();
 initPanel();
 mountThemePicker(document.getElementById("panel-theme"));
@@ -145,11 +154,11 @@ if (staticMode) {
 
 /** Canonical key for a read URL — path + the lens params (whitelisted, sorted)
  * that select a distinct snapshot. MUST match src/export.ts `canonicalKey`. */
-const LENS_PARAMS = ["components", "detail", "env", "logical", "radial", "runtime", "tier"];
+const LENS_PARAMS = ["components", "detail", "env", "logical", "ops", "radial", "runtime", "tier"];
 function canonicalKey(path, params) {
-  // Components + logical views ignore detail/radial — drop them so they match
-  // the single captured snapshot (MUST match src/export.ts).
-  const flat = params.get("components") === "1" || params.get("logical") === "1";
+  // Components + logical + ops views ignore detail/radial — drop them so they
+  // match the single captured snapshot (MUST match src/export.ts).
+  const flat = params.get("components") === "1" || params.get("logical") === "1" || params.get("ops") === "1";
   const q = LENS_PARAMS.filter((k) => params.has(k) && !(flat && (k === "detail" || k === "radial")))
     .map((k) => `${k}=${params.get(k)}`)
     .join("&");
@@ -188,6 +197,41 @@ const COMPONENT_STATUS_LABEL = { good: "healthy", accent: "in progress", warn: "
 // artifacts have no declared axis to classify against. `_artifact`'s presence
 // (or an artifact-flavoured `_unobserved`) picks this label set.
 const ARTIFACT_STATUS_LABEL = { good: "installed", warn: "installed, not healthy", accent: "not installed", neutral: "unobserved" };
+// The ops lens (#284) and its converge rule table (#234) paint the same four
+// colours about a DECLARED Op, where none of the entity vocabulary applies: a
+// gate is not "foreign" and a rule that may dispatch is not "pending". The word
+// carries the meaning here (accessible-ops: never rely on the colour alone), so
+// it is picked from what the card actually is — `_step` — and not from the
+// colour alone, which in this lens says four different things per step kind.
+const OP_STATUS_LABEL = {
+  gate: { warn: "stops here for a human", good: "approved", accent: "waiting", neutral: "declared" },
+  effect: { accent: "conditional — skipped when the receipt already matches", good: "fired", warn: "failed", neutral: "skipped" },
+  rule: { accent: "may dispatch on a matching tick", warn: "dispatch target not in this graph", neutral: "reports only, never mutates" },
+  activity: { good: "ran ok", warn: "failed", accent: "reached, not settled", neutral: "declared, not run" },
+};
+function opStatusLabel(node) {
+  const set = OP_STATUS_LABEL[node.attrs && node.attrs._step];
+  return set && set[node.attrs._status];
+}
+// The render-drift axis (#146's deferred half, chant#1249/#1250 via
+// src/helm-drift.ts). A chart carrying `_renderDrift` has had its PINNED
+// render diffed against the live cluster, so `warn` on it means "drifted",
+// not "installed, not healthy" — same word the field-drift and entity-diff
+// vocabularies already use for the same fact. `in-sync`/`unobserved` never
+// repaint the node, so this only overrides the artifact label on drift.
+const RENDER_VERDICT_LABEL = {
+  drifted: "drifted from its pinned render",
+  "in-sync": "matches its pinned render",
+  unobserved: "not compared to its pinned render",
+};
+// Why nothing was compared. Every one of these is a hole, never a clean bill —
+// see src/helm-drift.ts's header.
+const RENDER_UNOBSERVED_LABEL = {
+  unpinned: "render is unpinned (no capability profile) — no content identity to diff",
+  "no-stored-render": "chant's render store has never seen this digest",
+  "nothing-observed": "the live read returned no documents at all",
+  "partly-observed": "some documents matched, others could not be read",
+};
 
 // A declared attribute value may be a cross-resource reference ({$ref:"x.y"}) —
 // the "static infra refs" — rather than a concrete value. Render those readably;
@@ -256,6 +300,60 @@ function pairCell(aLabel, a, bLabel, b, opts = {}) {
   return wrap;
 }
 
+/** Shorten a `sha256:<64 hex>` to the 12 hex digits chant's own reports print. */
+function shortDigest(d) {
+  return typeof d === "string" && d.startsWith("sha256:") ? d.slice(7, 19) : d;
+}
+
+/**
+ * The `render diff` inspect section (#146's deferred half). `r` is the
+ * `_renderDrift` report src/helm-drift.ts put on the chart node.
+ *
+ * Reports the verdict in words first, then the counts behind it, then — on
+ * drift — every document that moved, path by path, in the same
+ * declared → live form the field-drift section uses for a k8s resource.
+ * Provenance comes last: which bytes were compared, and where they came from.
+ */
+function renderDriftSection(section, r) {
+  const rd = section("render diff");
+  rd("verdict", RENDER_VERDICT_LABEL[r.verdict] || r.verdict);
+  if (r.reason) rd("reason", RENDER_UNOBSERVED_LABEL[r.reason] || r.reason);
+  if (r.counts) {
+    const c = r.counts;
+    rd(
+      "documents",
+      `${c.drifted} drifted (${c.changes} propert${c.changes === 1 ? "y" : "ies"}) · ${c.unchanged} matching` +
+        (c.unobserved ? ` · ${c.unobserved} unread` : "") +
+        (c.undeclared ? ` · ${c.undeclared} not in the render` : ""),
+    );
+  }
+  for (const doc of r.drifted || []) {
+    const d = section(doc.name);
+    for (const ch of doc.changes) {
+      // Same declared → live form the k8s field-drift section uses, so a
+      // release's drift reads exactly like a resource's.
+      d(ch.path, `${JSON.stringify(ch.declared)} → ${JSON.stringify(ch.live)}`);
+    }
+  }
+  const p = r.provenance;
+  if (!p) return;
+  // chant#1228's pinned-render record: what was rendered, from which inputs,
+  // by which helm and chant, against which cluster profile. #234's "is prod
+  // running what staging tested" is answered by comparing these across two
+  // environments — behold renders one at a time, so it shows the facts and
+  // leaves the comparison to a cross-environment surface.
+  const pr = section("render provenance");
+  pr("content digest", shortDigest(p.contentDigest));
+  pr("input digest", shortDigest(p.inputDigest));
+  pr("values digest", shortDigest(p.valuesDigest));
+  pr("chart", p.chartVersion ? `${p.chart} ${p.chartVersion}` : p.chart);
+  if (p.repo) pr("repo", p.repo);
+  pr("release", p.namespace ? `${p.namespace}/${p.releaseName}` : p.releaseName);
+  if (p.profile) pr("pinned against", p.kubeVersion ? `${p.profile} (k8s ${p.kubeVersion})` : p.profile);
+  if (p.sourceRef) pr("source ref", p.sourceRef);
+  pr("rendered", `${p.renderedAt} · helm ${p.helmVersion} · chant ${p.chantVersion}`);
+}
+
 function inspect(node) {
   const panel = document.getElementById("inspect-body");
   panel.innerHTML = "<h2>inspect</h2>";
@@ -288,7 +386,19 @@ function inspect(node) {
   // 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.
   const isArtifact = node.kind === "Helm::Chart";
-  if (st) id("status", (isArtifact ? ARTIFACT_STATUS_LABEL[st] : liveStatus ? COMPONENT_STATUS_LABEL[st] : STATUS_LABEL[st]) || st);
+  // The render-drift axis only ever repaints on drift (src/helm-drift.ts), so
+  // a `warn` chart carrying a drifted verdict is drifted, not unhealthy — the
+  // artifact vocabulary would say the wrong thing about the right colour.
+  const renderDrift = node.attrs && node.attrs._renderDrift;
+  const driftLabel = renderDrift && renderDrift.verdict === "drifted" ? RENDER_VERDICT_LABEL.drifted : undefined;
+  if (st)
+    id(
+      "status",
+      driftLabel ||
+        (node.lexicon === "op" ? opStatusLabel(node) : undefined) ||
+        (isArtifact ? ARTIFACT_STATUS_LABEL[st] : liveStatus ? COMPONENT_STATUS_LABEL[st] : STATUS_LABEL[st]) ||
+        st,
+    );
   if (node.attrs && node.attrs._artifact) {
     const a = node.attrs._artifact;
     if (a.release) id("release", a.release);
@@ -301,6 +411,16 @@ function inspect(node) {
   // `_status: "neutral"` (never the component-status join's own, unrelated
   // `neutral` = "not deployed"), so it's safe to show unconditionally here.
   if (node.attrs && node.attrs._unobserved) id("unobserved reason", node.attrs._unobserved);
+  // #234's free rider: an OperatorStack's Namespace/CronJob, named. The server
+  // reads this off chant's own `app.kubernetes.io/*` labels (src/operator.ts) —
+  // it is a declared fact, not a naming convention behold inferred.
+  if (node.attrs && node.attrs._operator) {
+    const o = node.attrs._operator;
+    id("operating loop", o.role === "home" ? `home · namespace ${o.namespace}` : `converge tick · ${o.op}`);
+    if (o.stack) id("operator stack", o.stack);
+    if (o.schedule) id("tick schedule", o.schedule);
+    if (o.ticks && o.ticks.length) id("hosted ConvergeOps", o.ticks.join(", "));
+  }
   // chant#1180 (#1077): `runtimeOwner` is a first-class IR field (like
   // `ownership`/`physicalId`), not an `attrs` tag — the declared entity this
   // live, undeclared node's owner chain resolves to. Shown immediately from
@@ -349,6 +469,13 @@ function inspect(node) {
     });
   }
 
+  // Render diff (#146's deferred half): what `chant helm diff <digest> <env>
+  // --live --json` said about this chart's PINNED render. Never rely on the
+  // colour alone (#57's accessibility note) — and here that matters twice
+  // over, because `in-sync` and `unobserved` don't move the colour at all, so
+  // this section is the only place they're reported.
+  if (renderDrift) renderDriftSection(section, renderDrift);
+
   // Live state: what chant observed in the cloud. Only managed (provisioned)
   // nodes carry it — pending nodes have none because they aren't deployed yet.
   if (node.physicalId || node.ownership) {
@@ -371,7 +498,12 @@ function inspect(node) {
       if (liveStatus.stack.status) live("stack status", liveStatus.stack.status);
       if (liveStatus.stack.healthy !== undefined) live("healthy", String(liveStatus.stack.healthy));
     }
-  } else if (st === "accent") {
+  } else if (st === "accent" && node.lexicon !== "op") {
+    // The `op` lexicon is excluded because nothing in the ops lens (#284) is an
+    // estate entity: `accent` there means "may not fire at all" — an effect step
+    // whose receipt already matches, a converge rule that dispatches only on a
+    // tick that matches it (#234) — and "not provisioned yet" would be an answer
+    // to a question the card never asked.
     const live = section("live");
     live("", "not provisioned yet (pending) — no live state");
   } else if (st === "runtime") {
@@ -735,7 +867,7 @@ function wire(ir) {
 // null on a project that declares no `stacks[]` at all — the picker (and the
 // status strip's stack tag) then never renders. Every fetch reads this, so
 // the `changed` SSE re-pull and a palette lens change go through the same path.
-const view = { env: null, detail: 2, components: true, logical: false, runtime: false, tier: null, target: null, stack: null, radial: false };
+const view = { env: null, detail: 2, components: true, logical: false, runtime: false, ops: false, tier: null, target: null, stack: null, radial: false };
 
 // #182: `components` is the boot default, but a project that declares no
 // components renders it as ZERO nodes — the first screen was a blank graph
@@ -771,21 +903,38 @@ const ZOOM_OPTS = [
   // detail level, because it is a different axis: every tier above shows what
   // you declared, and this one shows what your declaration produced.
   ["zoom: runtime", "runtime"],
+  // The ops lens (#284): the project's declared Ops — the phase track of each
+  // `dist/ops/<name>/op.json`. Off the granularity axis entirely (an Op is
+  // neither coarser nor finer than a resource; it's a different artifact of the
+  // same chant source), so it sits last, and only appears when the served
+  // estate has actually emitted Ops — `opsAvailable`, from /api/project.
+  ["zoom: ops", "ops"],
 ];
 const ZOOM_DETAIL = { composites: 1, resources: 2, attributes: 3, runtime: 3 };
-/** Current zoom value from (components, logical, detail). */
+/** How many emitted Ops the served estate has (0 = the stop doesn't exist).
+ * Seeded from /api/project in initPickers(). */
+let opsAvailable = 0;
+/** The zoom stops this project can actually offer — `runtime` needs an env,
+ * `ops` needs emitted op.json files. Both the panel and ⌘K read this, so a stop
+ * never appears in one surface and not the other. */
+function availableZooms() {
+  return ZOOM_OPTS.filter(([, z]) => (z === "runtime" ? Boolean(view.env) : z === "ops" ? opsAvailable > 0 : true));
+}
+/** Current zoom value from (components, logical, ops, detail). */
 function zoomValue() {
   if (view.components) return "components";
   if (view.logical) return "logical";
+  if (view.ops) return "ops";
   if (view.runtime) return "runtime";
   return { 1: "composites", 2: "resources", 3: "attributes" }[view.detail] ?? "resources";
 }
-/** Apply a zoom value back onto (components, logical, detail). */
+/** Apply a zoom value back onto (components, logical, ops, detail). */
 function applyZoom(z) {
   view.components = z === "components";
   view.logical = z === "logical";
+  view.ops = z === "ops";
   view.runtime = z === "runtime";
-  if (z !== "components" && z !== "logical") view.detail = ZOOM_DETAIL[z] ?? 2;
+  if (z !== "components" && z !== "logical" && z !== "ops") view.detail = ZOOM_DETAIL[z] ?? 2;
 }
 
 // --- Floating control panel content ---------------------------------------
@@ -830,8 +979,8 @@ function renderPanelView() {
   const current = zoomValue();
   // runtime is only meaningful with an env: it descends below the declaration
   // boundary to owner-referenced children, which exist in a cluster and never
-  // in your source.
-  for (const [label, v] of ZOOM_OPTS.filter(([, z]) => z !== "runtime" || view.env)) {
+  // in your source. ops only exists once the project has emitted op.json.
+  for (const [label, v] of availableZooms()) {
     zoom.appendChild(
       panelOpt(label.replace(/^zoom: /, ""), v === current, () => {
         applyZoom(v);
@@ -841,8 +990,9 @@ function renderPanelView() {
     );
   }
   // Radial toggle — entity zooms only, same gate the ⌘K entry has
-  // (components/logical both lay themselves out: waves / nested arch boxes).
-  if (!view.components && !view.logical) {
+  // (components/logical/ops all lay themselves out: waves / nested arch boxes /
+  // phase boxes).
+  if (!view.components && !view.logical && !view.ops) {
     zoom.appendChild(panelHeading("layout"));
     zoom.appendChild(
       panelOpt("radial", view.radial, () => {
@@ -951,6 +1101,55 @@ function primeDemoCatalog() {
   });
 }
 
+/**
+ * The manifest-backed carve state (#230 M3), as the scope panel shows it: the
+ * progress read, then one row per carved address with its stage.
+ *
+ * Stage is carried by the WORD, with the tone reinforcing it — green for
+ * graduated, the pending blue for a carve still in flight (the same blue
+ * pinhole paints `accent` cards with, so the panel row and the card agree).
+ * A no-op when the served estate carries no manifests: a project that was
+ * never carved grows no dead section.
+ *
+ * `chant carve apply` is echoed per row and never offered as a button — see
+ * src/carve-manifest.ts APPLY_IS_HUMAN, which `state.apply.note` carries here
+ * verbatim.
+ */
+function renderCarveState(host, state) {
+  if (!state || !state.manifests) return;
+  host.appendChild(panelHeading("carved out of terraform"));
+  const head = document.createElement("div");
+  head.className = "count-row";
+  const label = document.createElement("span");
+  label.className = "grow";
+  label.textContent = state.progress.label;
+  const tag = document.createElement("span");
+  tag.className = "tag";
+  tag.textContent = state.manifests + (state.manifests === 1 ? " manifest" : " manifests");
+  tag.title = "chant's own *.carve.json state manifests — behold reads them and never writes one.";
+  head.append(label, tag);
+  host.appendChild(head);
+  if (state.progress.detail) host.appendChild(panelMuted(state.progress.detail));
+  for (const s of state.states) {
+    const row = document.createElement("div");
+    row.className = "count-row";
+    const dot = document.createElement("span");
+    dot.className = "dot";
+    dot.style.background = s.graduated ? "var(--managed)" : "var(--pending)";
+    const name = document.createElement("span");
+    name.className = "grow";
+    name.textContent = s.target;
+    name.title = s.note;
+    const stage = document.createElement("span");
+    stage.className = "tag";
+    stage.textContent = s.stage;
+    row.append(dot, name, stage);
+    host.appendChild(row);
+    if (!s.graduated) host.appendChild(panelMuted(s.applyCommand));
+  }
+  host.appendChild(panelMuted(state.apply.note));
+}
+
 function renderPanelScope() {
   const host = document.getElementById("tab-scope");
   if (!host) return;
@@ -976,6 +1175,12 @@ function renderPanelScope() {
     host.appendChild(panelMuted(dir));
   }
   if (!estateDirs.length) host.appendChild(panelMuted("no project loaded yet"));
+  // #230 M3: the strangler-fig progress, right where the panel already
+  // summarizes this estate's members. It reads off chant's own `*.carve.json`
+  // manifests (chant#998), so it says the same thing after a restart as before
+  // one — and it renders identically in carve mode and on an ordinary project
+  // serve, because /api/project publishes one shape for both.
+  renderCarveState(host, info.carve && info.carve.state);
   // #195: switching — recents first (server-persisted, validated), then a
   // free path input. Locked in preview mode (the demo's contract) and
   // meaningless in a static export.
@@ -1304,6 +1509,27 @@ const carveActions = {
 
 /** Run one of the two safe steps. Both are POSTs with a `{select}` body; both
  * answer either their result or #193's `{error, code, remedy}`. */
+/**
+ * Re-read the manifest-backed carve state (#230 M3) after a step wrote one.
+ *
+ * One `/api/project` plus a graph reload: the panel's "carved so far" and the
+ * repainted card both come off the manifests on disk, so an in-session update
+ * and a post-restart read are the same read. A failed refresh leaves what was
+ * already shown alone — stale is better than a state change nobody made.
+ */
+async function refreshCarveState() {
+  try {
+    const info = await apiFetch("/api/project").then((r) => r.json());
+    projectInfo = info;
+    carveInfo = info.carve || null;
+  } catch {
+    return;
+  }
+  renderPanelScope();
+  renderPanelCarve();
+  await load();
+}
+
 async function runCarveStep(which) {
   if (carveState.busy || !carveState.pick) return;
   carveState.busy = which;
@@ -1326,6 +1552,11 @@ async function runCarveStep(which) {
       // to the next button would hide the thing the run was for. The "next"
       // control unlocks; pressing it stays the viewer's move.
       showToast(`✓ carve ${which} — wrote into ${(carveInfo.demo && carveInfo.demo.outLabel) || "the demo copy"}`, true);
+      // #230 M3: the step just wrote a carve manifest. Re-read it rather than
+      // inferring the new state from the response — the file on disk is what
+      // the panel and the card claim to be showing, and after a reload it is
+      // the only thing left.
+      await refreshCarveState();
     }
   } catch (err) {
     carveState.error = { step: which, error: String((err && err.message) || err), remedy: "Is the behold server still running?" };
@@ -1393,6 +1624,67 @@ function markCarvedCards() {
   }
 }
 
+/**
+ * #284 item 2: mark the step the playhead sits on, on the graph itself.
+ *
+ * The card's tone already moved (the server paints `_status`), but "here" and
+ * "done" must not read the same, so the position also wears a dashed edge —
+ * the same after-the-render SVG stamp markCarvedCards() uses, for the same
+ * reason: the SVG is replaced wholesale on every render.
+ */
+function markPlayhead(ir) {
+  const svg = document.querySelector("#graph svg");
+  if (!svg) return;
+  const here = (ir.nodes || []).find((n) => n.attrs && n.attrs._playhead);
+  if (!here) return;
+  const g = svg.querySelector('[data-node-id="' + CSS.escape(here.id) + '"]');
+  if (g) g.classList.add("playhead");
+}
+
+/**
+ * #234's free rider: name the operating loop's home in the estate graph.
+ *
+ * An `OperatorStack` (chant#1940) renders as an ordinary namespace of CronJobs,
+ * so the loop was already on the picture — anonymously. The server marks the
+ * Namespace and its tick CronJobs from chant's own labels (`_operator`, see
+ * src/operator.ts); this is the paint, in the same after-the-render stamp shape
+ * markCarvedCards() uses, and for the same reason: the SVG is replaced wholesale
+ * on every render.
+ */
+const OPERATOR_MARK_LABEL = { home: "⟳ operating loop", tick: "⟳ converge tick" };
+function markOperatorCards(ir) {
+  const svg = document.querySelector("#graph svg");
+  if (!svg) return;
+  for (const n of ir.nodes || []) {
+    const mark = n.attrs && n.attrs._operator;
+    if (!mark || !OPERATOR_MARK_LABEL[mark.role]) continue;
+    const g = svg.querySelector('[data-node-id="' + CSS.escape(n.id) + '"]');
+    if (!g || g.querySelector('[data-operator="1"]')) continue;
+    g.classList.add("operator-home");
+    // Measured, not read off attributes — markCarvedCards()'s note applies here
+    // verbatim (pinhole sizes a card from its content).
+    const rect = g.querySelector("rect");
+    const box = rect && rect.getBBox ? rect.getBBox() : null;
+    const tag = document.createElementNS("http://www.w3.org/2000/svg", "text");
+    tag.setAttribute("data-operator", "1");
+    tag.setAttribute("x", String((box ? box.x + box.width : 150) - 10));
+    tag.setAttribute("y", String((box ? box.y + box.height : 60) - 9));
+    tag.setAttribute("text-anchor", "end");
+    tag.setAttribute("font-size", "11");
+    tag.setAttribute("font-weight", "600");
+    tag.setAttribute("fill", "var(--pending)");
+    tag.textContent = OPERATOR_MARK_LABEL[mark.role];
+    const title = document.createElementNS("http://www.w3.org/2000/svg", "title");
+    title.textContent =
+      mark.role === "home"
+        ? `The operating loop's home: namespace ${mark.namespace}${mark.stack ? ` (OperatorStack ${mark.stack})` : ""}` +
+          `${mark.ticks && mark.ticks.length ? ` — ticks ${mark.ticks.join(", ")}` : ""}`
+        : `Ticks the ConvergeOp ${mark.op}${mark.schedule ? ` on ${mark.schedule}` : ""}`;
+    g.appendChild(title);
+    g.appendChild(tag);
+  }
+}
+
 function renderPanelCarve() {
   if (!carveMode()) return;
   if (!carveHost) {
@@ -1450,7 +1742,7 @@ function renderStatusbar() {
   const parts = [`zoom: ${zoomValue()}`, view.env ? `env: ${view.env}` : "env: (source)"];
   if (view.stack) parts.push(`stack: ${view.stack}`);
   if (axes.tier) parts.push(`tier: ${axes.tier}`);
-  if (view.radial && !view.components && !view.logical) parts.push("radial");
+  if (view.radial && !view.components && !view.logical && !view.ops) parts.push("radial");
   el.textContent = parts.join(" · ");
   // #131: why this level rendered empty, or as the one below it. The server
   // decides (src/zoom-notes.ts) — the SPA never infers it, so the note always
@@ -1558,6 +1850,23 @@ async function loadResources() {
 let reconcileCache = null; // last ReconcileSummary for the current env/tier/target, or null
 let applyProgress = null; // last ApplyProgressState (src/apply.ts) for the current env, or null — hydrated from /api/ops on load, then kept live by the `apply` SSE event
 let applyPicker = false; // whether the inline "apply <component|all> →" prompt is open
+// #284 item 2 — the run playhead. `runState` is src/run-playhead.ts's RunState:
+// hydrated from /api/ops on load (so a reload mid-run doesn't start blank) and
+// kept live by the `run` SSE event. `gateCard` is the graph's own richer answer
+// (meta.gate — it knows which declared step the gate holds back), used when the
+// ops lens has been loaded; the panel falls back to deriving one from runState.
+// Deliberately NOT reset by resetDialCaches(): a run belongs to an Op, not to
+// whichever env/tier lens happens to be picked.
+let runState = null;
+let gateCard = null;
+let runStatusInFlight = false;
+// #234 joins 3 + 1 — the operating loop. src/operator.ts's OperatorState:
+// `declared` (the ConvergeOps the built project declares, from op.json) arrives
+// with the ops lens, the rest from `/api/operator/status`; kept live by the
+// `operator` SSE event. Deliberately NOT reset by resetDialCaches(), for the
+// playhead's reason: a loop belongs to its project, not to a picked env/tier.
+let operatorState = null;
+let operatorInFlight = false;
 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
 
@@ -1575,6 +1884,53 @@ function applyOptionLabel(name) {
   return tag ? `${name} — ${tag}` : name;
 }
 
+// Disruption severity (chant#1665, #284) → an existing palette token. No new
+// colours: the drift palette's own two "look at this" tones do the work, which
+// keeps a reconcile row reading the same as the overlay a user just came from.
+// --foreign is the mild one (the yellow an adoptable node wears — go look);
+// --degraded is the strong one (the tone the component dial already spends on
+// a failure). `in-place` gets NO tint: a pending row whose update mutates in
+// place must read exactly as every pending row read before this landed.
+//
+// `unknown` takes the mild tone rather than none. chant's contract is that
+// `unknown` is the default and the ONLY fallback — a silent, broken, or absent
+// classifier all land there — so it means "nobody could say", and painting it
+// like `in-place` would turn "unclassified" into "safe", which is the one
+// reading #1665 exists to prevent.
+const DISRUPTION_VAR = {
+  "in-place": "",
+  rolling: "var(--foreign)",
+  replace: "var(--degraded)",
+  destroy: "var(--degraded)",
+  unknown: "var(--foreign)",
+};
+
+// The word is the carrier; the tone only reinforces it (accessible-ops: colour
+// is never the only thing saying this row is expensive — the same reason the
+// drift panel's dot rows always ship a label beside the dot). These lines are
+// the row tooltip's second half.
+const DISRUPTION_WHY = {
+  "in-place": "the provider mutates the existing resource — no new identity, no window where it is absent",
+  rolling: "the resource survives, but its workload is replaced incrementally — disruptive to what is running",
+  replace: "a new resource is built and the old one removed — the physical id changes",
+  destroy: "the old resource is deleted FIRST, then rebuilt — there is a window with nothing in it",
+  unknown: "no lexicon could classify this change. Unknown is not \"in place\" — go read it",
+};
+
+// The levels worth putting on the dial badge, loudest last. `in-place` is
+// omitted on purpose: it is the "nothing new to say" verdict, and listing it
+// would lengthen the badge without changing what anyone does about it. It is
+// still named in full on any row where it IS the worst verdict, because
+// "classified in-place" and "never classified" have to look different.
+const DISRUPTION_BADGE_LEVELS = ["rolling", "unknown", "replace", "destroy"];
+
+/** The dial button's disruption suffix, e.g. " · 1 replace". Empty against a
+ * chant that doesn't classify (every count 0), so the badge is unchanged. */
+function disruptionBadge(d) {
+  if (!d) return "";
+  return DISRUPTION_BADGE_LEVELS.filter((l) => d[l]).map((l) => ` · ${d[l]} ${l}`).join("");
+}
+
 // Reset the dial's per-target caches (reconcile summary, apply picker/progress,
 // component-name list) when the env/tier/target lens changes — all three are
 // scoped to "whatever target is currently picked", so switching targets must
@@ -1637,6 +1993,7 @@ function renderDial() {
     host.appendChild(hint);
     // A pipeline run (#163) is env-less — its progress still belongs here.
     if (applyProgress && applyProgress.waves.length) host.appendChild(renderApplyProgress(applyProgress));
+    mountPlayhead(host);
     return;
   }
   host.style.display = "flex";
@@ -1658,9 +2015,14 @@ function renderDial() {
   // chant, so this is a no-op suffix until #1168 ships.
   // chant#1180 (#1077): `runtime` gets the identical treatment — its own
   // count, 0 against a chant predating it.
+  // chant#1665 (#284): the disruption suffix is NOT a fourth count — it's a
+  // re-cut of the `pending` number by what applying it costs, so "4 pending ·
+  // 1 replace" means one of those four rebuilds the resource. Empty against a
+  // chant that doesn't classify, same no-op suffix discipline as the two above.
   const reconcileBtn = button(
     reconcileCache
       ? `reconcile · ${reconcileCache.total} pending` +
+        disruptionBadge(reconcileCache.disruption) +
         (reconcileCache.unobserved ? ` · ${reconcileCache.unobserved} unobserved` : "") +
         (reconcileCache.runtime ? ` · ${reconcileCache.runtime} runtime` : "")
       : "reconcile",
@@ -1693,6 +2055,32 @@ function renderDial() {
   if (reconcileCache) host.appendChild(renderReconcileDetail(reconcileCache));
   if (applyPicker && !applying && !staticMode) host.appendChild(renderApplyPicker());
   if (applyProgress && applyProgress.waves.length) host.appendChild(renderApplyProgress(applyProgress));
+  mountOperator(host);
+  mountPlayhead(host);
+}
+
+// #234 joins 3 + 1 — the operator strip. Only on the ops lens: the operating
+// loop is a fact about the project's declared Ops, and it belongs beside the
+// track they draw rather than on top of whichever env the dial is pointed at.
+// Gated on a DECLARED ConvergeOp, so an estate that runs no loop grows nothing.
+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) });
+  host.appendChild(box);
+}
+
+// #284 item 2 — the run playhead panel: the run's honest verdict, the pending
+// gate as a first-class card (#234) with its delegated approve, and the steps
+// that have actually settled. Env-less on purpose, like a pipeline run: an Op
+// belongs to its project, not to whichever env the dial is pointed at.
+function mountPlayhead(host) {
+  if (!hasPlayhead(runState)) return;
+  const box = document.createElement("div");
+  box.className = "run-playhead";
+  renderPlayhead(box, runState, gateCard, { approve: (op, gate) => signal(op, gate) });
+  host.appendChild(box);
 }
 
 // Apply picker (M3): "which component(s)?" prompt for the dial's apply step —
@@ -1868,15 +2256,31 @@ function renderReconcileDetail(r) {
     wrap.textContent = "no pending changes";
     return wrap;
   }
+  // chant#1665 (#284): a row carries the loudest verdict among its pending
+  // changes, as a WORD plus a tone — an update that rebuilds the resource is a
+  // materially different pending item from one that flips a tag, and until now
+  // both read as "worker: 1". A component whose entries carry no verdict (an
+  // older chant, or no `update` among them) gets neither, which is the same row
+  // it drew before — absence is not `in-place`.
+  const severity = (span, level) => {
+    if (!level) return;
+    const tint = DISRUPTION_VAR[level];
+    if (tint) span.style.color = tint;
+    span.textContent += ` · ${level}`;
+    const why = `Worst pending change here: ${level} — ${DISRUPTION_WHY[level]}.`;
+    span.title = span.title ? `${span.title}\n${why}` : why;
+  };
   for (const [component, count] of rows) {
     const span = document.createElement("span");
     span.textContent = `${component}: ${count}`;
+    severity(span, r.disruptionByComponent && r.disruptionByComponent[component]);
     wrap.appendChild(span);
   }
   if (r.uncorrelated) {
     const span = document.createElement("span");
     span.textContent = `${r.uncorrelated} uncorrelated`;
     span.title = "Pending changes that couldn't be mapped to a component by source location.";
+    severity(span, r.disruptionUncorrelated);
     wrap.appendChild(span);
   }
   if (hasUnobserved) {
@@ -2005,6 +2409,19 @@ function render(ir, svg, m) {
   // previous one (recolorNodesByCategory also sets lastGraphIr; harmless).
   lastMeta = m;
   lastGraphIr = ir;
+  // #284 item 2: the ops lens answers with the run state it painted with and
+  // the pending gate card it built (which knows the declared step the gate
+  // holds back — the SPA can't derive that from runState alone). Only the ops
+  // lens carries them; every other lens leaves the playhead exactly as it was.
+  // (render() ends with renderDial(), so the panel picks these up there.)
+  if (m.mode === "ops") {
+    if (m.run) runState = m.run;
+    gateCard = m.gate || null;
+    // #234 join 3: the lens's answer carries which ConvergeOps the project
+    // DECLARES (read from the same op.json it just parsed — no subprocess). The
+    // strip's content arrives from the poll below.
+    if (m.operator) operatorState = m.operator;
+  }
   const overlay = m.mode === "overlay";
   // Logical/architecture lens (#63): its own mode, but when an env is picked the
   // projected nodes still carry the drift `_status`, so it reads as a drift view
@@ -2098,8 +2515,10 @@ function render(ir, svg, m) {
   ensureZoomControls(g);
   ensureBackToInfra(g);
   wire(ir);
-  if (view.radial && !view.components && !view.logical) addRadialLabels(ir);
+  if (view.radial && !view.components && !view.logical && !view.ops) addRadialLabels(ir);
   markCarvedCards(); // #254: the SVG is replaced per render — re-stamp the marker
+  markPlayhead(ir); // #284 item 2: same, for the step the run is sitting on
+  markOperatorCards(ir); // #234 free rider: same, for the operating loop's home
   applyLayout(); // #228: last, so the hand-placed deltas ride on top of every other pass
   renderDial();
 }
@@ -2894,7 +3313,7 @@ async function load(opts = {}) {
     showLoading(`loading ${zoomValue()}${view.env ? " · " + view.env : ""}…`);
   }
   try {
-    const q = lensParams(new URLSearchParams({ detail: String(view.detail) }));
+    let q = lensParams(new URLSearchParams({ detail: String(view.detail) }));
     let endpoint = "/api/graph";
     if (view.components) {
       // M1.1 (#57): the component DAG stays on /api/graph even with an env
@@ -2903,6 +3322,23 @@ async function load(opts = {}) {
       // cross-substrate entity overlay, which components never use.
       q.set("components", "1");
       if (view.env) q.set("env", view.env);
+    } else if (view.ops) {
+      // The ops lens (#284): the declared Ops, read from each Op's emitted
+      // op.json. Built fresh rather than layered onto the entity lenses,
+      // because this view reads NONE of them — no env, no detail, no radial,
+      // and no tier (a tier re-evaluates tier-conditioned source, and an Op's
+      // IR was already resolved at build). Sending them anyway would also give
+      // a static export a different key per tier for one identical snapshot.
+      q = new URLSearchParams({ ops: "1" });
+      // #284 item 2: this is the view run state paints over, so this is when
+      // it's worth shelling chant for the one thing the record stream can't
+      // carry — whether a gate is pending. Asked once per lens load; the
+      // in-flight run has its own tick above. The server only broadcasts a
+      // CHANGED answer, so this can't chase its own re-pull.
+      pollRunStatus();
+      // #234 join 3: same pull-not-push discipline for the operating loop — ask
+      // once per lens load, and only from the lens the strip lives on.
+      pollOperatorStatus();
     } else if (view.logical) {
       // Logical/architecture lens (#63): the server re-projects at detail 3
       // regardless of the dial, so detail/radial don't apply. With an env it
@@ -2922,7 +3358,7 @@ async function load(opts = {}) {
       if (view.runtime) q.set("runtime", "1");
     }
     // Radial layout (entity view only) — curl the wide DAG onto concentric rings.
-    if (view.radial && !view.components && !view.logical) q.set("radial", "1");
+    if (view.radial && !view.components && !view.logical && !view.ops) q.set("radial", "1");
     // The CI + resources facets are component-DAG-mode-only details. Load
     // both whenever components mode is on, env picked or not — #59 unifies
     // the CI facet (#58), the live-status join (#57), and resources (#59) so
@@ -3037,6 +3473,11 @@ async function initPickers() {
   // with none leaves `view.stack` (and the picker + status tag) null.
   stacks = info.stacks || [];
   view.stack = stacks[0] || null;
+  // #284: the ops stop exists only for an estate that has emitted op.json —
+  // `info.ops` is the count, absent when there are none (server.ts gates it the
+  // way it gates `tiers`/`stacks`), so an unbuilt project or a chant < 0.50
+  // never grows a stop that would refuse.
+  opsAvailable = info.ops || 0;
   // #254: carve mode declares itself here. The Carve tab is mounted at runtime
   // (panel.js's addPanelTab), so nothing else grows a dead tab.
   carveInfo = info.carve || null;
@@ -3182,6 +3623,23 @@ loadSubstrates();
 // Poll readiness so pills update as things come up on their own (Docker
 // starting, a bring-up provisioning) without needing a `changed` event.
 setInterval(loadSubstrates, 5000);
+// #284 item 2: while a DURABLE run is in flight, a gate can open at any moment
+// — and the record stream falls silent exactly when it does, so a stalled
+// playhead is not evidence of anything. Ask. Only while a run is actually
+// running, so an idle behold shells nothing.
+setInterval(() => {
+  if (runState && runState.status === "running" && runState.mode === "temporal") pollRunStatus();
+}, 5000);
+// #234 join 3: the operating loop ticks on its own schedule (chant's operator
+// defaults to a 60s round, a CronJob to whatever it declares), so the strip goes
+// stale without anyone clicking. Same discipline as the gate tick above rather
+// than a second pattern: an interval only while it is RELEVANT — the ops lens is
+// what the strip lives on, and a project with no declared ConvergeOp shells
+// nothing, ever. The server broadcasts only a CHANGED answer, so a quiet loop
+// costs one read and no repaint.
+setInterval(() => {
+  if (view.ops && hasOperator(operatorState)) pollOperatorStatus();
+}, 15000);
 
 // Delegated writes (#7 Sync / #8 Adopt). behold never mutates — these buttons
 // trigger the project's committed Ops on the executor; the now-line streams phases.
@@ -3266,6 +3724,122 @@ events.addEventListener("apply", (e) => {
   renderDial();
 });
 
+// #284 item 2 — the run playhead. Same channel and same shape as `apply` above:
+// the server broadcasts the whole RunState (src/run-playhead.ts) after every
+// settled StepRecord and every gateState read, so a client that (re)subscribes
+// mid-run renders correctly from the very next event. Repaint the dial always;
+// re-pull the graph only when the ops lens is what's on screen, since that's
+// the view the run state paints over.
+events.addEventListener("run", (e) => {
+  try {
+    runState = JSON.parse(e.data);
+  } catch {
+    return;
+  }
+  renderDial();
+  if (view.ops) load({ quiet: true });
+});
+
+// #234 join 3 — the operator strip. Same channel and shape as `run` above: the
+// server broadcasts the whole OperatorState after every CHANGED status read, so
+// a client that (re)subscribes renders correctly from the next event. Repaint
+// the dial only: the strip paints nothing onto the graph, so there is no re-pull
+// to make here (which is also what stops the poll and the broadcast chasing each
+// other).
+events.addEventListener("operator", (e) => {
+  try {
+    operatorState = JSON.parse(e.data);
+  } catch {
+    return;
+  }
+  renderDial();
+});
+
+/**
+ * Ask the server for the Op's durable run status — the ONLY way to learn
+ * gateState (chant#1676 made it a workflow query, not part of the record
+ * stream). Pull, not push: one shell-out per ask, and only while there is a
+ * durable run to ask about, rather than a background poll against Temporal for
+ * an Op nobody is watching.
+ *
+ * A refusal (no Temporal, no run, an older chant) is not an error to shout
+ * about — the server folds its reason into `runState.gateNote` and the panel
+ * states it. What must never happen is a silent fallback to "no gate pending".
+ */
+function runStatusTarget() {
+  if (runState && runState.op) return runState.op;
+  // Nothing has run this session: the one Op whose gate the Approve button
+  // already targets is the honest thing to ask about.
+  return opsApply && opsApply.gate ? opsApply.name : null;
+}
+function pollRunStatus() {
+  if (staticMode || runStatusInFlight) return;
+  const name = runStatusTarget();
+  if (!name) return;
+  // Only a durable run has gate state at all. A local run's playhead is
+  // complete without it, so don't shell chant to be told so.
+  if (runState && runState.mode === "local") return;
+  runStatusInFlight = true;
+  apiFetch(`/api/ops/${encodeURIComponent(name)}/status`)
+    .then((r) => r.json())
+    .then((j) => {
+      if (j && j.runState) runState = j.runState;
+      renderDial();
+    })
+    .catch(() => {})
+    .finally(() => {
+      runStatusInFlight = false;
+    });
+}
+
+/**
+ * Ask the server for the operating loop's status (#234 join 3).
+ *
+ * Pull, not push, exactly like `pollRunStatus`: one shell-out per ask, and only
+ * for a project that DECLARES a ConvergeOp. A refusal (no loop, a chant older
+ * than 0.52, an answer behold can't read) comes back on the state as `note` +
+ * `code` and the strip states it — what must never happen is a silently empty
+ * strip standing in for "behold couldn't ask".
+ */
+function pollOperatorStatus() {
+  if (staticMode || operatorInFlight) return;
+  operatorInFlight = true;
+  apiFetch("/api/operator/status")
+    .then((r) => r.json())
+    .then((j) => {
+      if (j && j.operator) operatorState = j.operator;
+      renderDial();
+    })
+    .catch(() => {})
+    .finally(() => {
+      operatorInFlight = false;
+    });
+}
+
+/**
+ * Record a converge gate's resolution — `chant approve <op> <gate>`, delegated
+ * exactly as the run gate's signal is.
+ *
+ * It is NOT the same act, and the toast says so: chant's gate ledger writes a
+ * fact, and the local executor still refuses the gated dispatch. The next tick
+ * is what reads the fact. Re-poll once either way — on success the gate should
+ * have left `pendingGates` (a card that lingered would read as if a human were
+ * still owed something), and on failure it should still be there.
+ */
+function approveConvergeGate(op, gate) {
+  fetch(`/api/operator/approve/${encodeURIComponent(op)}/${encodeURIComponent(gate)}`, { method: "POST" })
+    .then((r) => r.json())
+    .then((j) => {
+      if (j.error) {
+        showToast(`✗ approve ${gate}: ${j.error}`, false);
+        nowline("✗ " + j.error);
+      } else {
+        showToast(`✓ ${gate} — ${APPROVED_SEMANTICS}`, true);
+      }
+      pollOperatorStatus();
+    });
+}
+
 function button(label, cls, onClick) {
   const b = document.createElement("button");
   b.textContent = label;
@@ -3295,6 +3869,10 @@ function signal(name, gate) {
       } else {
         showToast(`✓ approved ${gate}`, true);
       }
+      // #284 item 2: re-ask gateState either way. On success the gate should be
+      // gone (the pending card must not linger as if a human were still owed);
+      // on failure it should still be there, and the card is what says so.
+      pollRunStatus();
     });
 }
 // Adopt is a per-node gesture (a *foreign* node → ReconcileOp → PR), so it lives
@@ -3382,7 +3960,7 @@ async function initActions() {
   const project = await apiFetch("/api/project").then((r) => r.json()).catch(() => ({}));
   opsInitialEnv = project.currentEnv || null;
   previewMode = staticMode || !!project.previewMode; // static ⇒ read-only, no writes at all
-  const { ops, adoptLexicons, autoSync, local, applyProgress: apInit } = await apiFetch("/api/ops")
+  const { ops, adoptLexicons, autoSync, local, applyProgress: apInit, runState: runInit, operatorState: opInit } = await apiFetch("/api/ops")
     .then((r) => r.json())
     .catch(() => ({ ops: [], adoptLexicons: [] }));
   // M3 (#54): hydrate the dial's apply progress from the server's last known
@@ -3392,6 +3970,19 @@ async function initActions() {
     applyProgress = apInit;
     renderDial();
   }
+  // #284 item 2: the same hydration for the run playhead — a reload mid-run
+  // picks up the settled steps and any pending gate instead of starting blank.
+  if (runInit && runInit.op) {
+    runState = runInit;
+    renderDial();
+  }
+  // #234 join 3: and the same for the operator strip — a reload with the ops
+  // lens open picks up the last status read rather than showing an empty strip
+  // until the next poll comes back.
+  if (opInit && opInit.declared && opInit.declared.length) {
+    operatorState = opInit;
+    renderDial();
+  }
   // Local-mode banner (#46) — the emulator(s) behold booted with --local, so it's
   // obvious deploys/overlay hit them (no cloud creds), not a real account.
   if (local && local.emulators && local.emulators.length) {
@@ -3608,12 +4199,13 @@ function paletteCommands() {
   }
 
   // Lens/zoom switches (#56, #63) — replaces the old header zoom picker.
-  for (const [label, v] of ZOOM_OPTS) {
+  for (const [label, v] of availableZooms()) {
     c.push([label + (v === zoomValue() ? " ✓" : ""), () => { applyZoom(v); load(); }]);
   }
   // Radial toggle — entity zooms only, same gate the removed checkbox had
-  // (components/logical both lay themselves out: waves / nested arch boxes).
-  if (!view.components && !view.logical) {
+  // (components/logical/ops all lay themselves out: waves / nested arch boxes /
+  // phase boxes).
+  if (!view.components && !view.logical && !view.ops) {
     c.push([(view.radial ? "Disable" : "Enable") + " radial layout", () => { view.radial = !view.radial; load(); }]);
   }