feat(admin): /dispatch graph, the topology as text (issue #54)

The graph's first consumer: renderGraph (pure, render.mjs) formats the
assembled model as folder groups, triggers with run stats and dangling
badges, skills with reachability badges, and edges labelled by their
evidence class, then the counters and the caps line, which renders
ALWAYS: edges without their bounds invite the reader to extrapolate an
unbounded chain fabric out of a depth-1, width-2 reality.

assembleGraph (index.ts, the assembleCosts twin) reads triggers FRESH
every call (OQ-008: a cached topology is a stale topology), the
resident schedulers, one bounded record scan, and the enumerations
through collectGraphInputs. Deliberately NOT an LLM-callable tool: the
enumeration spawns git per folder, and the topology is for the
operator's eyes (DES-CLI-SURFACE ungated tier; tool-count pin stands).

readTriggers now also returns the RAW entries count, because the
attribution range guard must accept an index pointing at an
unusable-but-present row.

New wiring pin: USAGE and KNOWN_SUBCOMMANDS agree member-for-member
(two copies of one list that nothing pinned together until this
amendment widened both).

Specs: NEW REQ-TOPOLOGY-GRAPH (honesty rules as requirements, the
REQ-COST-ANALYTICS discipline applied to topology).
REQ-ADMIN-VIA-PI-EXTENSION and DES-ADMIN-VIA-PI-EXTENSION AMENDED
(command list). REQ-COST-ANALYTICS UNCHANGED, checked. Docs:
docs/graph.md, README and workflows.md cross-links.

Suite in the CI posture: 2120 pass, 0 skipped; admin bundle builds.

Signed-off-by: Rob Boerman <robboerman@live.nl>

Author: edgehero

README.md

@@ -380,7 +380,10 @@ Steer the running worker without stopping it, from any terminal:
 ## The admin panel
 
 The dashboard shown at the top of this README is a **pi extension**: it loads into your own interactive
-pi session. No daemon, no web app, no network port.
+pi session. No daemon, no web app, no network port. Beside the dashboard, `/dispatch graph` renders the
+whole trigger and flow topology as text: what triggers what, what chained to what in the recorded runs,
+what a skill's own text says it might chain to, plus orphan skills and dangling triggers
+([`docs/graph.md`](docs/graph.md)).
 
 ```bash
 pi install npm:@edgehero/pi-dispatch-admin   # then, in pi:  /dispatch

admin/src/index.ts

@@ -75,7 +75,13 @@ import {
   scanRunRecords,
   readSubscriptions,
   KNOWN_KEYS,
+  GRAPH_LIMITS,
+  cronRunStats,
+  joinRunsToTriggers,
+  observedChainEdges,
+  collectGraphInputs,
 } from "./read-model.mjs";
+import { buildGraphModel } from "./graph-model.mjs";
 // The deployment pointer (INT-DEPLOYMENT-POINTER-CONTRACT): the wizard-written file that aims this
 // extension at a deployment built in another directory. Layered into process.env once at factory load
 // (the operator's env always wins), so resolvePaths stays env-only by contract while every one of its
@@ -96,7 +102,7 @@ import { getPricedModel, isZeroRated, listPricedModels, piAiVersion, reprice } f
 import { setGlyphs } from "./panel.mjs";
 import { buildSandboxRunArgs, launchSandbox as spawnSandbox, resolveSandbox, sandboxContainerName } from "@edgehero/pi-dispatch/sandbox";
 import { readManifest } from "@edgehero/pi-dispatch/sandbox-store";
-import { renderStatus, renderRuns, renderBudget, renderTriggers, renderSettingsView, renderCosts, renderWhatIf } from "./render.mjs";
+import { renderStatus, renderRuns, renderBudget, renderTriggers, renderSettingsView, renderCosts, renderWhatIf, renderGraph } from "./render.mjs";
 import { makeDashboard, createDashboardDeps } from "./dashboard.ts";
 // Only the nudge is loaded eagerly (it must register its session_start handler at factory time); the
 // wizard itself stays behind the dispatch handler's lazy import. The setup-wizard module imports
@@ -152,7 +158,7 @@ const REBUILT_NOTICE = (reason: string) =>
   `replaced invalid settings file (${reason}) — other keys were lost`;
 
 const USAGE =
-  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|triggers|settings|set|unset|setup>";
+  "usage: /dispatch <status|pause|resume|run|runs|logs|budget|costs|graph|triggers|settings|set|unset|setup>";
 
 const KNOWN_SUBCOMMANDS = [
   "status",
@@ -163,6 +169,7 @@ const KNOWN_SUBCOMMANDS = [
   "logs",
   "budget",
   "costs",
+  "graph",
   "triggers",
   "settings",
   "set",
@@ -913,6 +920,14 @@ async function dispatch(pi: ExtensionAPI, args: string, ctx: any): Promise<void>
       costsCommand(pi, paths, tokens, notify);
       return;
     }
+    case "graph": {
+      // Operator-typed read, ungated (DES-CLI-SURFACE: typing it is the approval); renders the same
+      // model the GRAPH view draws, as plain text into the admin channel. Deliberately NOT an
+      // LLM-callable tool: the folder enumeration spawns git per folder, and the text is a topology
+      // the operator reads, not a fold a model consumes.
+      send(pi, renderGraph(await assembleGraph(paths)));
+      return;
+    }
     case "run": {
       const folder = tokens[1];
       const flow = tokens[2];
@@ -1019,6 +1034,34 @@ function assembleCosts(paths: any, window: string, flow?: string): any {
   return { fold };
 }
 
+// ---- the graph command surface (issue #54) ----
+
+/**
+ * Assemble the trigger/flow graph model exactly as the dashboard's seam will: a FRESH triggers read
+ * every call (the file live-reloads, OQ-008 -- a cached topology is a stale topology), the resident
+ * schedulers, one bounded record scan for the window, the folder/injected enumerations through
+ * `collectGraphInputs`, and the pure fold. All I/O lives in the read-model; this function only
+ * aggregates its outputs into buildGraphModel's input shape.
+ */
+async function assembleGraph(paths: any): Promise<any> {
+  const nowMs = Date.now();
+  const triggers: any = readTriggers({ triggersPath: paths.triggersPath });
+  const triggerList: any[] = Array.isArray(triggers?.triggers) ? triggers.triggers : [];
+  const schedulers: any = await readSchedulers({ url: paths.valkeyUrl });
+  const records: any = scanRunRecords({ logsDir: paths.logsDir, sinceMs: nowMs - GRAPH_LIMITS.windowDays * 24 * 60 * 60 * 1000, nowMs });
+  const recs: any[] = Array.isArray(records) ? records : [];
+  return buildGraphModel({
+    triggers,
+    schedulers: Array.isArray(schedulers) ? schedulers : [],
+    ...collectGraphInputs({ triggers: triggerList }),
+    cronStats: cronRunStats({ records: recs, schedulerIds: triggerList.filter((t) => t.type === "cron" && typeof t.id === "string").map((t) => t.id) }),
+    runJoin: joinRunsToTriggers({ records: recs, triggerCount: triggers?.count }),
+    chainEdges: observedChainEdges({ records: recs }),
+    caps: { chainDepthMax: paths.chainDepthMax, chainMaxPerJob: paths.chainMaxPerJob, windowDays: GRAPH_LIMITS.windowDays },
+    nowMs,
+  });
+}
+
 /**
  * `/dispatch costs [7d|30d|mtd]` renders the fold; `costs whatif …` estimates one flow at another model's
  * rates. Both send PII-free text into the admin channel -- the same records `runs` already sends,

admin/src/read-model.mjs

@@ -671,7 +671,10 @@ export function readTriggers({ triggersPath, fs = nodeFs }) {
     // above row i would otherwise shift every attribution below it onto the wrong trigger.
     if (display) triggers.push({ ...display, index });
   });
-  return { triggers };
+  // `count` is the RAW entries length, for the same reason `index` is raw: the attribution range
+  // guard must accept an index that points at an unusable-but-present row (triggers.length would
+  // reject it and miscount the run as stale).
+  return { triggers, count: entries.length };
 }
 
 /**

admin/src/render.mjs

@@ -377,3 +377,115 @@ export function renderSettingsView(settings) {
   }
   return out.join("\n");
 }
+
+/**
+ * Render the trigger/flow graph model as plain text -- the `/dispatch graph` command body and the
+ * dashboard's unframed degrade twin. Pure over the model (built by graph-model.mjs buildGraphModel);
+ * every honesty rule lives THERE, so this function only formats: folder groups, their triggers with
+ * run stats and dangling badges, their skills with reachability badges and outgoing edges labelled by
+ * evidence class, then the counters and the caps line -- which renders ALWAYS, because edges without
+ * their bounds invite the reader to extrapolate an unbounded chain fabric (DES-GRAPH-EDGE-DERIVATION).
+ */
+export function renderGraph(model) {
+  const m = model ?? {};
+  if (m.meta?.triggersMissing) return "Graph: no triggers file found";
+  if (typeof m.meta?.triggersInvalid === "string" && m.meta.triggersInvalid !== "") return `Graph: triggers file invalid: ${m.meta.triggersInvalid}`;
+  const nodes = Array.isArray(m.nodes) ? m.nodes : [];
+  const nodeById = new Map(nodes.map((n) => [n.id, n]));
+  const edges = Array.isArray(m.edges) ? m.edges : [];
+  const flagsByNode = new Map();
+  for (const f of Array.isArray(m.flags) ? m.flags : []) {
+    if (!flagsByNode.has(f.nodeId)) flagsByNode.set(f.nodeId, []);
+    flagsByNode.get(f.nodeId).push(f.flag);
+  }
+
+  const out = ["Graph: triggers and flows"];
+  const triggerCount = nodes.filter((n) => n.kind === "trigger").length;
+  if (triggerCount === 0) out.push("", "no triggers configured");
+
+  for (const group of Array.isArray(m.folders) ? m.folders : []) {
+    if ((group.triggerIds?.length ?? 0) === 0 && (group.skillIds?.length ?? 0) === 0) continue;
+    out.push("", groupHeading(group));
+    for (const id of group.triggerIds ?? []) {
+      const t = nodeById.get(id);
+      if (t) out.push(`  ${graphTriggerLine(t, flagsByNode.get(id) ?? [])}`);
+    }
+    for (const id of group.skillIds ?? []) {
+      const s = nodeById.get(id);
+      if (!s || s.kind === "skill-unverified") continue; // an unverified flow is already on its trigger line
+      out.push(`  ${graphSkillLine(s, flagsByNode.get(id) ?? [])}`);
+      for (const e of edges) {
+        if (e.from !== id || e.kind === "cron-rearm") continue;
+        const target = nodeById.get(e.to);
+        out.push(`    ${graphEdgeLine(e, target)}`);
+      }
+    }
+  }
+
+  const injected = nodes.filter((n) => n.kind === "injected");
+  if (injected.length > 0) {
+    out.push("", "injected skills (trigger-reachable, never AI-reachable):");
+    for (const n of injected) {
+      const marks = (flagsByNode.get(n.id) ?? []).includes("injected-ai-trigger") ? "  [ai-trigger: allow is a silent no-op here]" : "";
+      out.push(`  ${n.name} (${n.dir})${marks}`);
+    }
+  }
+
+  out.push("");
+  if ((m.meta?.unattributedRuns ?? 0) > 0) out.push(`${m.meta.unattributedRuns} runs unattributed (triggers file changed since they ran, or they predate attribution)`);
+  const refusals = Object.entries(m.meta?.chainRefusals ?? {});
+  if (refusals.length > 0) out.push(`chain refusals: ${refusals.map(([flow, n]) => `${flow} ${n}`).join(", ")}`);
+  const trunc = m.meta?.truncated ?? {};
+  if (trunc.folders) out.push("folder scan truncated (cap reached): unlisted folders are not empty, they are unscanned");
+  if (trunc.skills) out.push("skill enumeration truncated or partly unread");
+  if (trunc.edges) out.push("observed edges truncated (cap reached)");
+  if ((m.meta?.droppedObservedEdges ?? 0) > 0) out.push(`${m.meta.droppedObservedEdges} observed edges dropped (no unique folder to attach them to)`);
+  out.push("edges: -> configured, observed xN (from records), mention (potential; a mention is not a promise)");
+  out.push(capsLine(m.caps));
+  return out.join("\n");
+}
+
+function groupHeading(group) {
+  if (group.kind === "forge") return `forge ${group.label} (skills unverifiable from the admin host)`;
+  const head = group.head ? `, HEAD ${String(group.head).slice(0, 7)}` : "";
+  const state = group.unreachable ? `, ${group.unreachable}` : "";
+  return `folder ${group.path ?? group.label}${head}${state}`;
+}
+
+function graphTriggerLine(t, flags) {
+  const stats = t.runs > 0 ? `runs ${t.runs}${t.lastOutcome ? `, last ${t.lastOutcome}` : ""}` : "no runs in window";
+  const badges = [];
+  if (flags.includes("no-skill")) badges.push("[no-skill: flow absent at HEAD]");
+  if (flags.includes("charset-invalid")) badges.push("[invalid flow name: can never materialise]");
+  if (flags.includes("pr-spend-loop-risk")) badges.push("[spend-loop risk: fires on opened/synchronize]");
+  const replicas = t.replicas ? ` x${t.replicas}` : "";
+  return `${t.onType} ${t.label} -> ${t.flow ?? "(no flow)"}${replicas}  (${stats})${badges.length ? ` ${badges.join(" ")}` : ""}`;
+}
+
+function graphSkillLine(s, flags) {
+  const badges = [];
+  if (s.kind === "skill-missing") badges.push("[missing at HEAD]");
+  if (s.isSub) badges.push(`[sub-skill of ${s.group}: loadable, never a flow]`);
+  if (s.aiTrigger) badges.push("[chainable]");
+  if (flags.includes("orphan")) badges.push("[orphan: no trigger, no ai-trigger, no mention]");
+  if (flags.includes("ai-reachable-no-trigger")) badges.push("[AI-reachable, no trigger]");
+  if (flags.includes("unread")) badges.push("[SKILL.md unread: facts unknown]");
+  return `skill ${s.name}${badges.length ? `  ${badges.join(" ")}` : ""}`;
+}
+
+function graphEdgeLine(e, target) {
+  const name = target?.name ?? "(unknown)";
+  if (e.kind === "observed") return `-> ${name}  observed x${e.count}`;
+  if (e.kind === "potential") {
+    const fire = e.eligible ? "could fire" : "can never fire: target has no ai-trigger allow";
+    return `-> ${name}  mention (potential${e.strong ? ", strong" : ""}; ${fire})`;
+  }
+  return `-> ${name}  ${e.kind}`;
+}
+
+function capsLine(caps) {
+  const depth = caps?.chainDepthMax ?? "?";
+  const width = caps?.chainMaxPerJob ?? "?";
+  const window = caps?.windowDays ?? "?";
+  return `caps: chain depth <= ${depth}, <= ${width} per job, same folder only, window ${window}d`;
+}

admin/test/read-model.test.mjs

@@ -1212,6 +1212,7 @@ test("readTriggers attaches the RAW array index, unshifted by dropped entries",
     [["label", 0], ["comment", 2]],
     "the dropped row 1 must leave a hole, not renumber row 2",
   );
+  assert.equal(out.count, 3, "count is the RAW length: the range guard must accept an index at an unusable-but-present row");
 });
 
 // A minimal run record for the join tests; every field a real record carries that these folds read.

admin/test/render.test.mjs

@@ -413,3 +413,84 @@ test("renderTriggers marks a replicating trigger, and an unflagged line is byte-
   });
   assert.equal(all.split("[x").length - 1, 3, "label, comment and pull_request each show their count");
 });
+
+// ---- renderGraph (issue #54): the /dispatch graph text body and the dashboard's unframed twin ----
+
+import { renderGraph } from "../src/render.mjs";
+import { buildGraphModel } from "../src/graph-model.mjs";
+
+// Hand-built through the REAL assembler so the render tests cannot drift from the model contract;
+// every number below is hand-computable from these literals.
+const GRAPH_MODEL = () =>
+  buildGraphModel({
+    triggers: {
+      count: 2,
+      triggers: [
+        { type: "cron", index: 0, id: "nightly", pattern: "0 3 * * *", folder: "/srv/site", flow: "build-report", model: null, packages: true, image: null, skillsDir: null, instructions: false, resume: false },
+        { type: "label", index: 1, any: ["ai"], all: [], none: [], flow: "triage", packages: true, image: null, skillsDir: null, instructions: false, resume: false, replicas: null, forge: "github" },
+      ],
+    },
+    schedulers: [],
+    folderSkills: {
+      "/srv/site": {
+        head: "abc1234def",
+        truncated: false,
+        unreachable: null,
+        skills: [
+          { name: "build-report", isSub: false, group: null, aiTrigger: true, meta: null, mentions: [{ name: "notify", strong: true }], unread: false },
+          { name: "notify", isSub: false, group: null, aiTrigger: false, meta: null, mentions: [], unread: false },
+          { name: "old-import", isSub: false, group: null, aiTrigger: false, meta: null, mentions: [], unread: false },
+        ],
+      },
+    },
+    injectedSkills: {},
+    cronStats: { byId: { nightly: { runs: 41, lastOutcome: "completed", lastEndedAt: "2026-08-11T00:00:00.000Z" } } },
+    runJoin: { byIndex: { 1: { runs: 12, lastOutcome: "failed", lastEndedAt: "2026-08-11T01:00:00.000Z" } }, unattributed: 2 },
+    chainEdges: { edges: [{ parentFlow: "build-report", childFlow: "notify", target: "local:site", count: 3, lastEndedAt: null }], refusals: {}, truncated: false },
+    caps: { chainDepthMax: 1, chainMaxPerJob: 2, windowDays: 30 },
+    nowMs: 1770000000000,
+  });
+
+test("renderGraph renders folders, triggers with stats, skills with badges, and evidence-labelled edges", () => {
+  const out = renderGraph(GRAPH_MODEL());
+  assert.match(out, /^Graph: triggers and flows/, "header anchored at the start");
+  assert.match(out, /folder \/srv\/site, HEAD abc1234\b/, "the folder heading carries the short HEAD");
+  assert.match(out, /cron nightly 0 3 \* \* \* -> build-report {2}\(runs 41, last completed\)/);
+  assert.match(out, /forge github \(skills unverifiable from the admin host\)/);
+  assert.match(out, /label any\[ai\] -> triage {2}\(runs 12, last failed\)/, "forge runs join via the persisted index");
+  assert.match(out, /-> notify {2}observed x3/, "an observed edge carries its count");
+  assert.match(out, /-> notify {2}mention \(potential, strong; can never fire: target has no ai-trigger allow\)/, "a mention of a non-eligible target says it can never fire");
+  assert.match(out, /skill old-import {2}\[orphan/, "the orphan badge renders");
+  assert.match(out, /2 runs unattributed/);
+  assert.match(out, /caps: chain depth <= 1, <= 2 per job, same folder only, window 30d/, "the caps line always renders");
+
+  // The negative claims: evidence classes never blur, and record-side text never appears.
+  assert.ok(!out.includes("label:"), "no matched label text exists anywhere in the model or the render");
+  const observedLines = out.split("\n").filter((l) => /observed x\d/.test(l));
+  assert.equal(observedLines.length, 1, "exactly the one observed edge renders with a count (the legend's xN is not a count)");
+  for (const line of out.split("\n").filter((l) => l.includes("mention (potential") && !l.startsWith("edges:"))) {
+    assert.ok(!/observed/.test(line), "a potential EDGE line never borrows observed's vocabulary (the legend names both on purpose)");
+  }
+});
+
+test("renderGraph: empty model and degraded inputs render exact, honest strings", () => {
+  assert.equal(renderGraph({ meta: { triggersMissing: true } }), "Graph: no triggers file found");
+  assert.equal(renderGraph({ meta: { triggersInvalid: "not valid JSON" } }), "Graph: triggers file invalid: not valid JSON");
+  const empty = renderGraph(buildGraphModel({ caps: { chainDepthMax: 1, chainMaxPerJob: 2, windowDays: 30 } }));
+  assert.equal(
+    empty,
+    ["Graph: triggers and flows", "", "no triggers configured", "", "edges: -> configured, observed xN (from records), mention (potential; a mention is not a promise)", "caps: chain depth <= 1, <= 2 per job, same folder only, window 30d"].join("\n"),
+    "the empty render is exact-equality pinned, caps included",
+  );
+});
+
+test("renderGraph surfaces truncation and dropped edges rather than pretending coverage", () => {
+  const model = GRAPH_MODEL();
+  model.meta.truncated.folders = true;
+  model.meta.truncated.edges = true;
+  model.meta.droppedObservedEdges = 2;
+  const out = renderGraph(model);
+  assert.match(out, /folder scan truncated .*unscanned/);
+  assert.match(out, /observed edges truncated/);
+  assert.match(out, /2 observed edges dropped \(no unique folder/);
+});