@openrig/cli 0.4.4 → 0.4.6

package/dist/commands/workflow-render.js

@@ -0,0 +1,223 @@
+/**
+ * OPR.0.4.6.WF3 FR-2 — the glanceable human renderers for
+ * trace/list/show. RENDER-SIDE ONLY (BR-2): these functions format
+ * daemon payloads the CLI already receives; `--json` paths never come
+ * through here and stay byte-identical to the shipped output.
+ *
+ * Shapes ported from in-repo precedent: the `rig ps` table mechanics
+ * (fitCell/truncate) and the argo-get per-step tree bar (STEP / ACTOR
+ * / EXIT / DURATION columns with status glyphs).
+ *
+ * Present-tolerant fields: WF-2's branch/gate additions
+ * (closureEvidence.branch_taken etc.) render when the payload carries
+ * them and leave no residue when absent — this module never requires
+ * them (WF-3 builds against the pre-WF-2 tip; the fields land with
+ * WF-2).
+ */
+const STATUS_GLYPH = {
+    completed: "✔",
+    failed: "✖",
+    active: "●",
+    waiting: "◐",
+};
+export function statusGlyph(status) {
+    return STATUS_GLYPH[status] ?? "●";
+}
+function truncate(s, max) {
+    return s.length > max ? s.slice(0, max - 1) + "…" : s;
+}
+function fitCell(value, width) {
+    return truncate(value, width).padEnd(width);
+}
+/** Compact human duration between two ISO timestamps ("3s", "4m", "2h", "5d"). */
+export function humanDuration(fromIso, toIso) {
+    if (!fromIso || !toIso)
+        return "";
+    const ms = Date.parse(toIso) - Date.parse(fromIso);
+    if (!Number.isFinite(ms) || ms < 0)
+        return "";
+    const s = Math.round(ms / 1000);
+    if (s < 60)
+        return `${s}s`;
+    const m = Math.round(s / 60);
+    // Minutes render up to AND INCLUDING 120 so sub-/at-2h durations keep
+    // their precision ("90m"/"120m" beat a rounded-up "2h" for judging
+    // step latency). Guard prepass catch: `m < 120` excluded exactly 120.
+    if (m <= 120)
+        return `${m}m`;
+    const h = Math.round(m / 60);
+    if (h < 48)
+        return `${h}h`;
+    return `${Math.round(h / 24)}d`;
+}
+/** Instance age relative to a supplied "now" (injectable for tests). */
+export function humanAge(createdAt, nowIso) {
+    return humanDuration(createdAt, nowIso);
+}
+/** Compact render of a plain seconds quantity (same scale rules). */
+export function humanSeconds(seconds) {
+    return humanDuration("1970-01-01T00:00:00.000Z", new Date(seconds * 1000).toISOString());
+}
+/**
+ * The trace tree (mini-req 2's bar: where it is + how it got there,
+ * one screen, no JSON literacy required).
+ */
+export function renderTraceTree(instance, trail, nowIso = new Date().toISOString()) {
+    const lines = [];
+    const name = instance.workflowName ? `${instance.workflowName}${instance.workflowVersion ? ` v${instance.workflowVersion}` : ""}` : "";
+    lines.push(`${statusGlyph(instance.status)} ${instance.instanceId}  ${name}  status=${instance.status}${instance.hopCount !== undefined ? `  hops=${instance.hopCount}` : ""}${instance.boundRig ? `  rig=${instance.boundRig}` : ""}`);
+    if (instance.createdAt) {
+        lines.push(`  created ${instance.createdAt}${instance.createdBySession ? ` by ${instance.createdBySession}` : ""}  age ${humanAge(instance.createdAt, nowIso)}`);
+    }
+    lines.push("");
+    lines.push(`  ${fitCell("STEP", 22)}${fitCell("ACTOR", 28)}${fitCell("EXIT", 10)}DURATION`);
+    let prevClosed = instance.createdAt;
+    for (let i = 0; i < trail.length; i++) {
+        const row = trail[i];
+        if (!row)
+            continue;
+        const glyph = row.closureReason === "failed" ? "✖" : "✔";
+        const bar = i === trail.length - 1 && !instance.currentStepId ? "└─" : "├─";
+        const duration = humanDuration(prevClosed, row.closedAt);
+        lines.push(`  ${bar} ${glyph} ${fitCell(row.stepId, 20)}${fitCell(row.actorSession, 28)}${fitCell(row.closureReason, 10)}${duration}`);
+        const branchTaken = row.closureEvidence?.["branch_taken"];
+        if (typeof branchTaken === "string" && branchTaken.length > 0) {
+            lines.push(`  │    ↳ branch: ${branchTaken}`);
+        }
+        prevClosed = row.closedAt ?? prevClosed;
+    }
+    if (instance.currentStepId) {
+        const owner = ""; // frontier owner is a queue-side fact; the frontier packet ids are what the payload carries
+        lines.push(`  └─ ▸ ${fitCell(instance.currentStepId, 20)}${fitCell(owner || "(current)", 28)}${fitCell("open", 10)}frontier=[${(instance.currentFrontier ?? []).join(", ")}]`);
+    }
+    else if (trail.length === 0) {
+        lines.push(`  (no steps closed yet)`);
+    }
+    return lines;
+}
+/**
+ * OPR.0.4.6.WF3 FR-3 — the attention marker for a list row (the
+ * single marker home). Classes: failed · stuck (consumed VERBATIM
+ * from the API-carried deadline classification — rail 1: the CLI
+ * never recomputes a threshold or class) · waiting. A row shows its
+ * highest-priority class; the `status` verb shows ALL classes per
+ * instance (exactly-once, combined reasons).
+ */
+export function attentionMarker(instance) {
+    if (instance.status === "failed")
+        return "▲ failed";
+    if (isStuck(instance))
+        return "▲ stuck";
+    if (instance.status === "waiting")
+        return "▲ waiting";
+    return "";
+}
+/** Rail 1: stuck-ness is READ from the API field, never derived. */
+function isStuck(instance) {
+    const state = instance.deadline?.state;
+    return typeof state === "string" && state.startsWith("overdue");
+}
+/**
+ * Compose the rollup from list rows. Pure arithmetic over
+ * pre-classified rows (the arch ruling's boundary: counting +
+ * grouping + rendering is render-side; the ONE correctness-rule
+ * composition — the threshold classification — arrives ALREADY DONE
+ * in instance.deadline). Per-instance dedup by instanceId (rail 2):
+ * an instance with multiple attention reasons renders ONCE with all
+ * of them.
+ */
+export function composeAttentionRollup(instances) {
+    const counts = { total: instances.length, active: 0, waiting: 0, completed: 0, failed: 0 };
+    const attention = [];
+    for (const inst of instances) {
+        if (inst.status === "active")
+            counts.active += 1;
+        else if (inst.status === "waiting")
+            counts.waiting += 1;
+        else if (inst.status === "completed")
+            counts.completed += 1;
+        else if (inst.status === "failed")
+            counts.failed += 1;
+        const classes = [];
+        const reasons = [];
+        if (inst.status === "failed") {
+            classes.push("failed");
+            reasons.push("workflow failed");
+        }
+        if (isStuck(inst)) {
+            classes.push("stuck");
+            const ev = inst.deadline?.evidence;
+            reasons.push(`${inst.deadline?.state}${ev?.stepId ? ` at step ${ev.stepId}` : ""}${ev?.ownerSession ? ` (owner ${ev.ownerSession})` : ""}${typeof ev?.overdueBySeconds === "number" ? `, overdue ${humanSeconds(ev.overdueBySeconds)}` : ""}`);
+        }
+        if (inst.status === "waiting") {
+            classes.push("waiting");
+            const blocker = inst.lastContinuationDecision?.blockedOn;
+            reasons.push(`waiting${blocker ? ` on ${blocker}` : " (blocker unrecorded)"}`);
+        }
+        if (classes.length === 0)
+            continue;
+        // Affordance by highest-priority class. `route` ships in this same
+        // slice (commit 6) — the verbs land together at merge (BR-1 holds
+        // at the shipped boundary).
+        const affordance = classes.includes("failed")
+            ? `inspect: rig workflow trace ${inst.instanceId}`
+            : classes.includes("stuck")
+                ? `re-route: rig workflow route ${inst.instanceId} --to <seat>`
+                : `resolve the blocker, then the owner projects (rig workflow trace ${inst.instanceId})`;
+        attention.push({
+            instanceId: inst.instanceId,
+            workflowName: inst.workflowName ?? "",
+            classes,
+            reasons,
+            affordance,
+        });
+    }
+    return { counts, attention };
+}
+/** Human render of the rollup — proven-empty, never blank. */
+export function renderStatus(rollup) {
+    const c = rollup.counts;
+    const lines = [];
+    lines.push(`${c.total} instance${c.total === 1 ? "" : "s"}: ${c.active} active · ${c.waiting} waiting · ${c.completed} completed · ${c.failed} failed`);
+    if (rollup.attention.length === 0) {
+        lines.push("No instances need attention (proven empty — every in-flight instance reads healthy).");
+        return lines;
+    }
+    lines.push("");
+    lines.push(`${fitCell("", 2)}${fitCell("INSTANCE", 30)}${fitCell("WORKFLOW", 20)}${fitCell("CLASS", 16)}REASON`);
+    for (const row of rollup.attention) {
+        lines.push(`${fitCell("▲", 2)}${fitCell(row.instanceId, 30)}${fitCell(row.workflowName, 20)}${fitCell(row.classes.join("+"), 16)}${row.reasons.join("; ")}`);
+        lines.push(`  ${fitCell("", 2)}└ ${row.affordance}`);
+    }
+    return lines;
+}
+/** The list table: INSTANCE · WORKFLOW · STATUS · STEP · AGE · ATTN. */
+export function renderInstanceList(instances, nowIso = new Date().toISOString()) {
+    if (instances.length === 0)
+        return ["No workflow instances."];
+    const lines = [];
+    lines.push(`${fitCell("", 2)}${fitCell("INSTANCE", 30)}${fitCell("WORKFLOW", 22)}${fitCell("STATUS", 11)}${fitCell("STEP", 20)}${fitCell("AGE", 6)}ATTN`);
+    for (const inst of instances) {
+        lines.push(`${fitCell(statusGlyph(inst.status), 2)}${fitCell(inst.instanceId, 30)}${fitCell(inst.workflowName ?? "", 22)}${fitCell(inst.status, 11)}${fitCell(inst.currentStepId ?? "-", 20)}${fitCell(humanAge(inst.createdAt, nowIso), 6)}${attentionMarker(inst)}`);
+    }
+    return lines;
+}
+/** The show summary, headed by the status line. */
+export function renderInstanceShow(instance, nowIso = new Date().toISOString()) {
+    const lines = [];
+    lines.push(`${statusGlyph(instance.status)} ${instance.instanceId}  status=${instance.status}`);
+    if (instance.workflowName)
+        lines.push(`  workflow: ${instance.workflowName}${instance.workflowVersion ? ` v${instance.workflowVersion}` : ""}`);
+    // OPR.0.4.6.FAC1: the bound rig renders when present (unbound rows unchanged).
+    if (instance.boundRig)
+        lines.push(`  rig:      ${instance.boundRig}`);
+    if (instance.createdAt)
+        lines.push(`  created:  ${instance.createdAt}${instance.createdBySession ? ` by ${instance.createdBySession}` : ""}  (age ${humanAge(instance.createdAt, nowIso)})`);
+    if (instance.currentStepId)
+        lines.push(`  at step:  ${instance.currentStepId}  frontier=[${(instance.currentFrontier ?? []).join(", ")}]`);
+    if (instance.hopCount !== undefined)
+        lines.push(`  hops:     ${instance.hopCount}`);
+    lines.push(`  next:     rig workflow trace ${instance.instanceId}`);
+    return lines;
+}
+//# sourceMappingURL=workflow-render.js.map

package/dist/commands/workflow-render.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"workflow-render.js","sourceRoot":"","sources":["../../src/commands/workflow-render.ts"],"names":[],"mappings":"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"}

package/dist/commands/workflow.d.ts

@@ -22,5 +22,6 @@ export declare const PROJECT_EXIT_KINDS: readonly ["handoff", "waiting", "done",
 export type ProjectExitKind = (typeof PROJECT_EXIT_KINDS)[number];
 export declare function isProjectExitKind(value: unknown): value is ProjectExitKind;
 export declare function printOutcomeSummary(json: boolean, status: number, summary: OutcomeSummary | null): void;
+export declare function printWorkflowAdvisories(advisories: string[] | undefined): void;
 export declare function workflowCommand(depsOverride?: WorkflowDeps): Command;
 //# sourceMappingURL=workflow.d.ts.map

package/dist/commands/workflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAa,SAAQ,UAAU;CAAG;AA6BnD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAOD,eAAO,MAAM,kBAAkB,mDAAoD,CAAC;AACpF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAWD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAMvG;AAMD,wBAAgB,eAAe,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CAkTpE"}
+{"version":3,"file":"workflow.d.ts","sourceRoot":"","sources":["../../src/commands/workflow.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAIpC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAW9C;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAa,SAAQ,UAAU;CAAG;AAwCnD,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;CACd;AAOD,eAAO,MAAM,kBAAkB,mDAAoD,CAAC;AACpF,MAAM,MAAM,eAAe,GAAG,CAAC,OAAO,kBAAkB,CAAC,CAAC,MAAM,CAAC,CAAC;AAElE,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,eAAe,CAE1E;AAWD,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI,GAAG,IAAI,CAMvG;AAYD,wBAAgB,uBAAuB,CAAC,UAAU,EAAE,MAAM,EAAE,GAAG,SAAS,GAAG,IAAI,CAK9E;AAED,wBAAgB,eAAe,CAAC,YAAY,CAAC,EAAE,YAAY,GAAG,OAAO,CA8jBpE"}

package/dist/commands/workflow.js

@@ -2,6 +2,9 @@ import { Command } from "commander";
 import { DaemonClient } from "../client.js";
 import { getDaemonStatus, getDaemonUrl, printDaemonNotRunning } from "../daemon-lifecycle.js";
 import { realDeps } from "./daemon.js";
+import { followInstance } from "./workflow-follow.js";
+import { composeAttentionRollup, renderInstanceList, renderInstanceShow, renderStatus, renderTraceTree, } from "./workflow-render.js";
+import { describeDaemonRejection, formatThreePart } from "./workflow-errors.js";
 async function withClient(deps, fn) {
     const status = await getDaemonStatus(deps.lifecycleDeps);
     if (status.state !== "running" || status.healthy === false) {
@@ -15,6 +18,20 @@ function printResult(json, body, status) {
     if (json) {
         console.log(JSON.stringify(body));
     }
+    else if (status >= 400) {
+        // WF3 FR-5: named daemon rejections render the house what/why/fix
+        // 3-part in human mode; unrecognized bodies keep the raw-JSON
+        // fallback. --json (above) stays the RAW body byte-identically;
+        // exit codes below are unchanged.
+        const rejection = describeDaemonRejection(body);
+        if (rejection) {
+            for (const line of formatThreePart(rejection))
+                process.stderr.write(`${line}\n`);
+        }
+        else {
+            console.log(JSON.stringify(body, null, 2));
+        }
+    }
     else {
         console.log(JSON.stringify(body, null, 2));
     }
@@ -50,6 +67,19 @@ export function printOutcomeSummary(json, status, summary) {
 function asString(value) {
     return typeof value === "string" && value.length > 0 ? value : undefined;
 }
+// OPR.0.4.6.FAC1 (arch ruling 2026-07-07): instantiate-time advisories
+// (currently the spec-default-target.rig degrade-to-unbound notice) MUST
+// be LOUD. Always write to STDERR — even in --json mode the structured
+// body already carries `advisories`, but an operator piping stdout to a
+// consumer still needs to see the warning, so it lands on stderr in both
+// modes. Non-fatal: never sets a non-zero exit code.
+export function printWorkflowAdvisories(advisories) {
+    if (!advisories || advisories.length === 0)
+        return;
+    for (const line of advisories) {
+        process.stderr.write(`⚠ workflow advisory: ${line}\n`);
+    }
+}
 export function workflowCommand(depsOverride) {
     const cmd = new Command("workflow").description("Daemon-native Workflow Runtime — declarative spec + transactional-scribe step projection (PL-004 Phase D)");
     const getDeps = () => depsOverride ?? {
@@ -78,6 +108,7 @@ Examples:
         .requiredOption("--root-objective <text>", "Root objective for the run")
         .requiredOption("--created-by <session>", "Session creating the instance (canonical <member>@<rig>)")
         .option("--entry-owner <session>", "Override default entry-step owner")
+        .option("--rig <name>", "Bind the instance to this rig (overrides the spec's target.rig default; roles resolve to seats on this rig)")
         .option("--json", "JSON output for agents")
         .addHelpText("after", `
 Examples:
@@ -98,15 +129,18 @@ Examples:
                 rootObjective: opts.rootObjective,
                 createdBySession: opts.createdBy,
                 entryOwnerSession: opts.entryOwner,
+                targetRig: opts.rig,
             });
             printResult(opts.json ?? false, res.data, res.status);
+            printWorkflowAdvisories(res.data?.advisories);
             const body = res.data ?? {};
             const instanceId = asString(body.instanceId) ?? "(no instance id)";
             const entryStepId = asString(body.entryStepId);
             const owner = asString(body.entryOwnerSession) ?? opts.entryOwner ?? "(default from spec)";
+            const boundRig = asString(body.instance?.boundRig ?? undefined);
             printOutcomeSummary(opts.json ?? false, res.status, {
                 what: `Instantiated workflow from ${specPath} (instance ${instanceId})`,
-                state: `${body.status ?? "active"}; entry packet ${entryStepId ?? "pending"} owned by ${owner}`,
+                state: `${body.status ?? "active"}${boundRig ? `; bound to rig ${boundRig}` : ""}; entry packet ${entryStepId ?? "pending"} owned by ${owner}`,
                 next: entryStepId
                     ? `Inspect: rig workflow show ${instanceId} | Open packet: rig queue show ${entryStepId}`
                     : `Inspect: rig workflow show ${instanceId}`,
@@ -202,7 +236,15 @@ Examples:
         const qs = params.toString();
         await withClient(deps, async (client) => {
             const res = await client.get(`/api/workflow/list${qs ? `?${qs}` : ""}`);
-            printResult(opts.json ?? false, res.data, res.status);
+            // WF3 FR-2: human mode renders the table; --json byte-identical (BR-2).
+            if (opts.json || res.status >= 400) {
+                printResult(opts.json ?? false, res.data, res.status);
+                return;
+            }
+            const body = res.data;
+            const rows = (Array.isArray(body) ? body : body?.instances ?? []);
+            for (const line of renderInstanceList(rows))
+                console.log(line);
         });
     });
     // List cached workflow_specs (NOT instances). The existing
@@ -260,7 +302,13 @@ Examples:
         const deps = getDeps();
         await withClient(deps, async (client) => {
             const res = await client.get(`/api/workflow/${encodeURIComponent(instanceId)}`);
-            printResult(opts.json ?? false, res.data, res.status);
+            // WF3 FR-2: human summary headed by the status line; --json byte-identical (BR-2).
+            if (opts.json || res.status >= 400) {
+                printResult(opts.json ?? false, res.data, res.status);
+                return;
+            }
+            for (const line of renderInstanceShow(res.data))
+                console.log(line);
         });
     });
     cmd
@@ -276,14 +324,36 @@ Examples:
         const deps = getDeps();
         await withClient(deps, async (client) => {
             const res = await client.get(`/api/workflow/${encodeURIComponent(instanceId)}/trace`);
-            printResult(opts.json ?? false, res.data, res.status);
+            // WF3 FR-2: human mode renders the per-step tree (mini-req 2's
+            // one-screen bar); --json byte-identical (BR-2).
+            if (opts.json || res.status >= 400 || !res.data?.instance) {
+                printResult(opts.json ?? false, res.data, res.status);
+                return;
+            }
+            const instance = res.data.instance;
+            const trail = (res.data.trail ?? []);
+            for (const line of renderTraceTree(instance, trail))
+                console.log(line);
         });
     });
+    // OPR.0.4.6.WF1 FR-8 (G6): `continue` RELABELED to its real
+    // inspector semantics. The wire has been a read-only frontier+trail
+    // inspector since Phase D v1, but the label said "Mechanically
+    // advance" and the summary printed "Advanced instance ..." — the
+    // label-vs-wire lie dies here. A true mechanical advance would mint
+    // a closure without the owner's truthful exit, violating
+    // owner-as-author + BR-2 (project is the sole advance write path) —
+    // arch-endorsed as architecture, not just wording.
     cmd
         .command("continue <instanceId>")
-        .description("Mechanically advance an instance after truthful closure (idempotent inspector in v1)")
+        .description("Inspect an instance's current frontier + step trail (read-only; advancing happens via 'rig workflow project')")
         .option("--json", "JSON output for agents")
         .addHelpText("after", `
+Read-only: reports where the instance is and how it got there so the
+frontier owner can continue truthfully. To actually advance, the packet
+OWNER closes it via:
+  $ rig workflow project --instance <id> --current-packet <qitem> --exit <exit> --actor-session <you>
+
 Examples:
   $ rig workflow continue WF01ABC
   $ rig workflow continue WF01ABC --json
@@ -294,19 +364,213 @@ Examples:
             const res = await client.post(`/api/workflow/${encodeURIComponent(instanceId)}/continue`, {});
             printResult(opts.json ?? false, res.data, res.status);
             const body = res.data ?? {};
-            const advanced = body.advanced !== false;
-            const nextId = asString(body.nextPacketId);
-            const nextOwner = asString(body.nextOwnerSession) ?? "(unknown)";
-            const status = body.instanceStatus ?? "(unknown)";
+            const status = body.instance?.status ?? "(unknown)";
+            const frontier = body.instance?.currentFrontier ?? [];
+            const stepId = body.instance?.currentStepId ?? null;
+            const trailLen = body.trail?.length ?? 0;
+            printOutcomeSummary(opts.json ?? false, res.status, {
+                what: `Inspected instance ${instanceId} (read-only; no state changed)`,
+                state: `status = ${status}; step = ${stepId ?? "(terminal)"}; frontier = [${frontier.join(", ")}]; trail rows = ${trailLen}`,
+                next: frontier.length > 0
+                    ? `The frontier owner advances via: rig workflow project --instance ${instanceId} --current-packet ${frontier[0]} --exit <handoff|waiting|done|failed> --actor-session <owner>`
+                    : `Terminal or empty frontier - see: rig workflow trace ${instanceId}`,
+            });
+        });
+    });
+    // OPR.0.4.6.WF3 FR-1 — the follow verbs. Two verbs, ONE renderer
+    // (workflow-follow.ts). BR-1 verb honesty: `run` instantiates AND
+    // follows; `watch` ONLY watches — neither advances a step (project
+    // remains the sole advance path). Outcome-as-exit-code by default
+    // (the kubectl choice): completed=0, workflow-failed=3 (distinct
+    // from the shipped 1=4xx / 2=5xx transport codes), so
+    // `rig workflow run … && next-thing` is honest in scripts.
+    cmd
+        .command("run <specPath>")
+        .description("Instantiate a workflow AND follow it live to a terminal state (exit 0 completed / 3 failed)")
+        .requiredOption("--root-objective <text>", "Root objective for the run")
+        .requiredOption("--created-by <session>", "Session creating the instance (canonical <member>@<rig>)")
+        .option("--entry-owner <session>", "Override default entry-step owner")
+        .option("--rig <name>", "Bind the instance to this rig (overrides the spec's target.rig default; roles resolve to seats on this rig)")
+        .option("--json", "Stream events as JSON lines for agents")
+        .addHelpText("after", `
+Streams each step event as it happens; exits when the workflow reaches
+a terminal state. Exit codes: 0 = completed, 3 = workflow failed,
+1/2 = transport errors (4xx/5xx). If the event stream drops, the
+command reconnects, then degrades to polling — announced, never a
+silent freeze.
+
+Examples:
+  $ rig workflow run workflows/conveyor.workflow.md \\
+      --root-objective "Ship it" --created-by orch-lead@my-rig
+  $ rig workflow run ./spec.yaml --root-objective x --created-by a@b --json
+`)
+        .action(async (specPath, opts) => {
+        const deps = getDeps();
+        await withClient(deps, async (client) => {
+            const res = await client.post("/api/workflow/instantiate", {
+                specPath,
+                rootObjective: opts.rootObjective,
+                createdBySession: opts.createdBy,
+                entryOwnerSession: opts.entryOwner,
+                targetRig: opts.rig,
+            });
+            printWorkflowAdvisories(res.data?.advisories);
+            // The daemon returns the nested InstantiateResult shape
+            // ({instance:{instanceId}}); tolerate a flattened {instanceId}
+            // too (walk-caught: reading only the flat field made `run`
+            // print-and-exit-0 without ever following — the same
+            // flattening confusion as the pre-existing instantiate
+            // summary polish note from WF-1 rev1-r2).
+            const instanceId = asString(res.data?.instance?.instanceId) ?? asString(res.data?.instanceId);
+            if (res.status >= 400 || !instanceId) {
+                printResult(opts.json ?? false, res.data, res.status);
+                return;
+            }
+            if (!opts.json)
+                console.log(`● instance ${instanceId} created — following`);
+            const code = await followInstance(client, instanceId, { json: opts.json ?? false });
+            if (code !== 0)
+                process.exitCode = code;
+        });
+    });
+    cmd
+        .command("watch <instanceId>")
+        .description("Attach to an in-flight instance and follow it live (read-only; exit mirrors the outcome)")
+        .option("--json", "Stream events as JSON lines for agents")
+        .addHelpText("after", `
+Read-only: renders the instance's current state (snapshot), then
+streams live events until a terminal state. Attaching to an already
+fast-moving instance is safe — steps that closed before attach render
+from the snapshot exactly once. Exit codes: 0 = completed, 3 =
+workflow failed, 1/2 = transport errors.
+
+Examples:
+  $ rig workflow watch WF01ABC
+  $ rig workflow watch WF01ABC --json
+`)
+        .action(async (instanceId, opts) => {
+        const deps = getDeps();
+        await withClient(deps, async (client) => {
+            const code = await followInstance(client, instanceId, { json: opts.json ?? false });
+            if (code !== 0)
+                process.exitCode = code;
+        });
+    });
+    // OPR.0.4.6.WF3 FR-4 — the ONE WF-3 mutation. BR-1: `route` routes;
+    // it NEVER advances a step (hop count untouched; project remains the
+    // sole advance path). Exception-lane by usage, not by gate.
+    cmd
+        .command("route <instanceId>")
+        .description("Re-route the current frontier step to a new owner (same step, honest handoff closure; never advances)")
+        .requiredOption("--to <session>", "New owner session (canonical <member>@<rig>)")
+        .requiredOption("--actor-session <session>", "Session performing the re-route (recorded as provenance)")
+        .option("--reason <text>", "Why the step is being re-routed (recorded in the audit trail)")
+        .option("--json", "JSON output for agents")
+        .addHelpText("after", `
+Use when a step's owner is unresponsive (dead seat, compaction) and the
+work should continue from the SAME step under a new owner. The old
+owner's stale close attempts are structurally rejected afterwards
+(packet_not_on_frontier).
+
+Examples:
+  $ rig workflow route WF01ABC --to dev2-driver@my-rig \\
+      --actor-session orch-lead@my-rig --reason "owner seat dead"
+`)
+        .action(async (instanceId, opts) => {
+        const deps = getDeps();
+        await withClient(deps, async (client) => {
+            const res = await client.post(`/api/workflow/${encodeURIComponent(instanceId)}/route`, {
+                toSession: opts.to,
+                actorSession: opts.actorSession,
+                reason: opts.reason,
+            });
+            printResult(opts.json ?? false, res.data, res.status);
+            const body = res.data ?? {};
             printOutcomeSummary(opts.json ?? false, res.status, {
-                what: advanced
-                    ? `Advanced instance ${instanceId}${nextId ? ` to packet ${nextId}` : ""}`
-                    : `No advance for instance ${instanceId} (already at frontier or terminal)`,
-                state: `instance status = ${status}${nextId ? `; next owner = ${nextOwner}` : ""}`,
-                next: nextId ? `Inspect: rig queue show ${nextId}` : `Inspect: rig workflow trace ${instanceId}`,
+                what: `Re-routed step ${body.stepId ?? "?"} from ${body.fromSession ?? "?"} to ${body.toSession ?? opts.to} (packet ${body.closedPacketId ?? "?"} → ${body.newPacketId ?? "?"})`,
+                state: `instance ${instanceId} = ${body.instanceStatus ?? "active"}; same step, new owner; no step advanced`,
+                next: `The new owner advances via: rig workflow project --instance ${instanceId} --current-packet ${body.newPacketId ?? "<packet>"} --exit <exit> --actor-session ${opts.to}`,
             });
         });
     });
+    // OPR.0.4.6.WF5 FR-4 — resume: redrive a FAILED instance from the
+    // failed step (BR-1 verb honesty: resume re-drives, it never advances
+    // a step itself and never re-runs completed steps; waiting instances
+    // resume via the shipped project path, not this verb).
+    cmd
+        .command("resume <instanceId>")
+        .description("Redrive a FAILED instance from its failed step (completed steps never re-run; one fresh max_hops window)")
+        .requiredOption("--actor-session <session>", "Session performing the resume (recorded as provenance)")
+        .option("--decision <text>", "Durable instruction for the step owner (lands in the redrive packet)")
+        .option("--json", "JSON output for agents")
+        .addHelpText("after", `
+Use after diagnosing an exception item: the instance returns to active,
+REBOUND to the step that failed, with a fresh packet routed to that
+step's re-resolved owner. The trail is preserved and extended; the
+resolved exception occurrence closes; a NEW failure of the same step
+raises a NEW occurrence honestly.
+
+Examples:
+  $ rig workflow resume WF01ABC --actor-session orch-lead@my-rig \\
+      --decision "flaky fixture fixed in commit abc123 — retry"
+`)
+        .action(async (instanceId, opts) => {
+        const deps = getDeps();
+        await withClient(deps, async (client) => {
+            const res = await client.post(`/api/workflow/${encodeURIComponent(instanceId)}/resume`, {
+                actorSession: opts.actorSession,
+                decision: opts.decision,
+            });
+            printResult(opts.json ?? false, res.data, res.status);
+            const body = res.data ?? {};
+            printOutcomeSummary(opts.json ?? false, res.status, {
+                what: `Redrove instance ${instanceId} from step ${body.stepId ?? "?"} (redrive #${body.resumeCount ?? "?"}; packet ${body.newPacketId ?? "?"} → ${body.ownerSession ?? "?"}; ${body.exceptionItemsClosed ?? 0} exception item(s) resolved)`,
+                state: `instance ${instanceId} = active, rebound to ${body.stepId ?? "?"}; completed steps untouched; fresh max_hops window`,
+                next: `The owner advances via: rig workflow project --instance ${instanceId} --current-packet ${body.newPacketId ?? "<packet>"} --exit <exit> --actor-session ${body.ownerSession ?? "<owner>"}`,
+            });
+        });
+    });
+    // OPR.0.4.6.WF3 FR-3 part B — the needs-attention rollup. CLI-SIDE
+    // composition per the arch ruling (Rev-4 rails): consumes the
+    // API-carried instance.deadline classification + instance.status
+    // from the SHIPPED read surface; counting/grouping/rendering only —
+    // NO threshold or class is ever computed here, NO daemon route was
+    // added (the WF-4-era web UI adds a daemon rollup endpoint under its
+    // own authorization when it needs one; this verb is not the
+    // permanent home of that composition).
+    cmd
+        .command("status")
+        .description("Which instances need attention: counts + one row per failed/stuck/waiting instance with reason + next action (read-only)")
+        .option("--json", "Rollup as JSON for agents")
+        .addHelpText("after", `
+Answers "what needs me" (list answers "what exists"). Every
+attention-worthy instance appears exactly once with ALL its classes
+(failed / stuck / waiting) and the actionable next step. A clean fleet
+renders the proven-empty statement with counts — never a blank.
+
+Examples:
+  $ rig workflow status
+  $ rig workflow status --json | jq '.attention[] | {instanceId, classes}'
+`)
+        .action(async (opts) => {
+        const deps = getDeps();
+        await withClient(deps, async (client) => {
+            const res = await client.get("/api/workflow/list");
+            if (res.status >= 400) {
+                printResult(opts.json ?? false, res.data, res.status);
+                return;
+            }
+            const body = res.data;
+            const rows = (Array.isArray(body) ? body : body?.instances ?? []);
+            const rollup = composeAttentionRollup(rows);
+            if (opts.json) {
+                console.log(JSON.stringify(rollup));
+                return;
+            }
+            for (const line of renderStatus(rollup))
+                console.log(line);
+        });
+    });
     return cmd;
 }
 //# sourceMappingURL=workflow.js.map