@nanobpm/nano-workforce 0.210.1 → 0.211.0

package/app/service.ts

@@ -1464,7 +1464,10 @@ export function isOrphanedPr(p: {
     // Provenance only explains the CURRENT owner's termination: a reason bound to a different
     // (predecessor) instance never masks an orphaned successor.
     !hasOwnTerminationReason(p) &&
-    p.merged_at == null
+    p.merged_at == null &&
+    // #959: a landing recorded only in the merge audit derives `merged` (base still `merging`,
+    // `merged_at` NULL) — that PR landed, it is not orphaned.
+    p.derived_status !== "merged"
   );
 }
 
@@ -2053,7 +2056,7 @@ async function classifyWaveTarget(
   token: string,
 ): Promise<"cleared" | "closed" | "pending"> {
   const tracked = await prsTracking(data).get(prKey);
-  if (tracked && tracked.status === "merged") return "cleared"; // worker-owned terminal, passes through the derive edge unchanged
+  if (tracked && (tracked.status === "merged" || tracked.derived_status === "merged")) return "cleared"; // worker-owned terminal, passes through the derive edge unchanged
   if (tracked && tracked.derived_status === ABANDONED_STATUS) return "cleared"; // ADR-0065 derive-only terminal → non-blocking, no re-reconcile needed
   const parsed = parsePr(prKey);
   if (!parsed) return "cleared"; // unparseable ref can't be checked → never wedge the barrier
@@ -2139,7 +2142,12 @@ export async function mergeLaneDecisionForPr(data: DataLayer, prKey: string): Pr
     // cancelled/terminated (derive-only terminal → `derived_status === "abandoned"`; the base row is
     // still frozen at its transient). Reading only base `status` here missed a cancelled member and
     // stalled/misrouted the lane.
-    if (lanePr && (lanePr.status === "merged" || lanePr.derived_status === "abandoned")) {
+    // #959: an audit-only landing (merge recorded, `pr.mark-merged` never ran) derives `merged` while
+    // the base row is still `merging` — it is just as complete as a base `merged` row.
+    if (
+      lanePr &&
+      (lanePr.status === "merged" || lanePr.derived_status === "merged" || lanePr.derived_status === "abandoned")
+    ) {
       completedPrKeys.add(lanePr.pr_key);
     }
   }

package/app/terminalReaderBehaviour.test.ts

@@ -319,3 +319,47 @@ test("startPlan re-admits a derive-only-abandoned epic (base 'dispatched', deriv
     assertEquals(stores.plan_tasks.rows.length, 0);
   });
 });
+
+// #959: an audit-only landing (merge recorded in `merges`, `pr.mark-merged` never ran) derives
+// `merged` while the base row is still `merging`. It must count as lane-complete and never surface as
+// `orphaned` in /status.
+test("#959 mergeLaneDecisionForPr treats an audit-only landed (derived merged) predecessor as complete", async () => {
+  const PLAN_KEY = "o/r#100";
+  const stores: Stores = {
+    plan_tasks: {
+      rows: [
+        { id: 1, plan_key: PLAN_KEY, task_id: "a", pr_key: "o/r#1" },
+        { id: 2, plan_key: PLAN_KEY, task_id: "b", pr_key: "o/r#2" },
+      ],
+      key: "id",
+    },
+    plan_merge_exclusions: {
+      rows: [{ id: 1, plan_key: PLAN_KEY, task_a: "a", task_b: "b", files: JSON.stringify(["shared.ts"]), source: "file-overlap" }],
+      key: "id",
+    },
+    plan_task_deps: { rows: [], key: "plan_key" },
+    pull_requests: {
+      rows: [
+        { pr_key: "o/r#1", repo: "o/r", number: 1, status: "merging", derived_status: "merged", merged_at: null },
+        { pr_key: "o/r#2", repo: "o/r", number: 2, status: "converging", derived_status: "converging" },
+      ],
+      key: "pr_key",
+    },
+  };
+  const decision = await mergeLaneDecisionForPr(memData(stores), "o/r#2");
+  assertEquals(decision?.isHeld, false);
+});
+
+test("#959 activePrs does not surface an audit-only landed (derived merged) PR as orphaned", async () => {
+  const stores: Stores = {
+    pull_requests: {
+      rows: [
+        { pr_key: "o/r#1", repo: "o/r", number: 1, url: "u1", status: "merging", derived_status: "merged", merged_at: null, current_round: 1, updated_at: "2024-01-01" },
+      ],
+      key: "pr_key",
+    },
+    escalations: { rows: [], key: "id" },
+  };
+  const active = await activePrs(memData(stores));
+  assertEquals(active.some((p) => p.status === "orphaned"), false);
+});

package/build-info.json

@@ -1,6 +1,6 @@
 {
-  "version": "0.210.1",
-  "gitSha": "e2c4e966b566ce8b4bdc19e84bceb130909a981c",
-  "gitTag": "v0.210.1",
-  "builtAt": "2026-11-12T12:00:58.232Z"
+  "version": "0.211.0",
+  "gitSha": "4ba5c8c61e6d5bfceaff3883c1719795797eb9a4",
+  "gitTag": "v0.211.0",
+  "builtAt": "2026-11-14T19:46:33.652Z"
 }

package/db/migrations/139_pull_requests_backfill_merged_not_abandoned.sql

@@ -0,0 +1,40 @@
+-- Backfill for issue #959: merged PRs whose run was terminated afterwards showed as "abandoned".
+--
+-- ROOT CAUSE. `pull_requests__tracking.derived_status` mapped ANY terminated run to `abandoned`
+-- without consulting the PR's merge state. Of the 24 top-level runs terminated in November, 23
+-- belong to PRs that MERGED on GitHub — an operator cancelled a redundant post-merge loop, an
+-- out-of-band merge (Mergify / a manual click) was reconciled, or a restart/upgrade cleaned up. Every
+-- one read "abandoned", which made the status untrustworthy and skewed retro/conformance stats
+-- (`LANDED_PR_STATUSES` excludes `abandoned`, so merged PRs didn't count as landed).
+--
+-- THE FIX is the merge-aware derivation (app/prTrackingReadModel.ts): a landed PR now reads `merged`
+-- regardless of how its instance ended, keyed off the base row's `merged_at`. That derivation is
+-- merge-aware ONLY when `merged_at` is set — but several out-of-band/reconciled merges terminated the
+-- loop BEFORE `pr.mark-merged` (or the review-wait retire) could stamp `merged_at`, leaving the base
+-- row frozen at its in-flight transient (`converging`/`waiting_merge`/…) with `merged_at` NULL. For
+-- those rows the derivation still has no merge signal, so they would keep reading `abandoned`.
+--
+-- This migration re-derives the existing rows so the 23 show as `merged`: any `pull_requests` row
+-- that has a `merged` outcome in its `merges` audit trail but whose base `status` is not already
+-- `merged` (and that has no `merged_at` yet) is stamped `status='merged'` + `merged_at`. The audit
+-- trail (`merges.outcome='merged'`) is the canonical record that the PR landed — written by
+-- `pr.mark-merged`, the merge worker's already-merged short-circuit, and the out-of-band retire path.
+-- With the base row settled to `merged`, the derivation reads `merged` whether or not the instance
+-- was later terminated (the terminated edge is gated on `merged_at IS NULL`).
+--
+-- Idempotent and additive-only: it touches only rows with a recorded `merged` audit outcome that are
+-- not already settled `merged`, and never overwrites an existing `merged_at`. `merged_at` is stamped
+-- from the earliest `merged` audit row (`MIN(m.at)`), falling back to the current timestamp when that
+-- is somehow NULL. Safe to re-run.
+UPDATE pull_requests
+SET status = 'merged',
+    merged_at = COALESCE(
+      merged_at,
+      (SELECT MIN(m.at) FROM merges m WHERE m.pr_key = pull_requests.pr_key AND m.outcome = 'merged'),
+      datetime('now')
+    ),
+    updated_at = datetime('now')
+WHERE status <> 'merged'
+  AND EXISTS (
+    SELECT 1 FROM merges m WHERE m.pr_key = pull_requests.pr_key AND m.outcome = 'merged'
+  );

package/main.ts

@@ -23,10 +23,16 @@ import { type AgenticChannelHandle, mountAgenticChannel } from "./app/agentic/ch
 import { makeElementInstanceResolver } from "./app/agentic/element-instance.ts";
 import { mountConsoleRedirect, resolveConsoleOrigin } from "./app/consoleRedirect.ts";
 import { announceEngine, resolveEngineAddress } from "./app/enginePreflight.ts";
+import { registerPullRequestTrackingReadModel } from "./app/prTrackingReadModel.ts";
 import { runEngineReconcile } from "./app/reconcile.ts";
 import { MAX_ROUNDS, pollOnce } from "./app/service.ts";
 import { envVar } from "./app/version.ts";
 
+// Issue #959: register the app-owned, merge-aware `pull_requests__tracking` read model BEFORE the
+// runtime mounts workers/instance-tracking, so the framework provisions THIS derivation (a landed PR
+// reads `merged`, never `abandoned`, however its loop ended) instead of the merge-blind default.
+registerPullRequestTrackingReadModel();
+
 const PORT = Number(process.env.PR_REVIEW_PORT ?? 3000);
 const POLL_MS = Number(process.env.NANO_PR_POLL_MS ?? 60_000);
 const GITHUB_TOKEN = process.env.GITHUB_TOKEN ?? "";

package/openapi.yaml

@@ -4312,6 +4312,8 @@ paths:
   /status:
     get:
       operationId: listActivePrs
+      x-cli:
+        command: [status]
       summary: List every tracked PR currently in flight (not converged/abandoned), newest-updated first.
       security:
         - hookSecret: []
@@ -4332,6 +4334,8 @@ paths:
   /actions/cancel:
     post:
       operationId: cancelInstance
+      x-cli:
+        command: [cancel]
       summary: "Cancel a wedged run the app-owned, record-consistent way: terminate the engine instance AND flip its PR/plan record to `abandoned` (issue #667). The correct unstick — go through the app so its record state stays consistent, rather than engine-level `urban_debug_cancel_instance`, which cancels out from under the app and leaves the PR row inconsistent."
       security:
         - hookSecret: []
@@ -4391,6 +4395,9 @@ paths:
   /actions/cancel-pr:
     post:
       operationId: cancelPrRun
+      x-cli:
+        command: [cancel-pr]
+        audience: operator
       # x-mcp exclusion: the page-only twin of `cancelInstance` (the per-row Cancel button). Agents use
       # the guarded `/actions/cancel` door.
       x-mcp:
@@ -4436,6 +4443,9 @@ paths:
   /actions/incident/retry:
     post:
       operationId: retryIncident
+      x-cli:
+        command: [incidents, retry]
+        audience: operator
       # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only remediation door. Retrying an
       # incident-parked run is the human unstick action on the Convergence/Home grids (the incident
       # row's "Retry incident" button); agents diagnose through the read surface and escalate, they
@@ -4491,6 +4501,8 @@ paths:
   /auto-resolutions:
     get:
       operationId: listAutoResolutions
+      x-cli:
+        command: [auto-resolutions, list]
       summary: List the escalation steward's auto-resolution records (reviewable), newest first.
       description: >-
         The durable, reviewable record of every escalation the opt-in steward (issue #889) resolved
@@ -4537,6 +4549,8 @@ paths:
   /auto-resolutions/review:
     post:
       operationId: reviewAutoResolution
+      x-cli:
+        command: [auto-resolutions, review]
       summary: Mark an auto-resolution record dismissed (reviewed, no action) or intervened (operator stepped in).
       description: >-
         The Auto-resolutions view's review affordance (issue #889). `dismiss` marks the record
@@ -4594,6 +4608,8 @@ paths:
   /incidents:
     get:
       operationId: listIncidents
+      x-cli:
+        command: [incidents, list]
       summary: List every tracked run parked on an ACTIVE engine incident, oldest first.
       description: >-
         Sibling of `/escalations` for technical liveness faults (issue #931). Read-only projection
@@ -4619,6 +4635,8 @@ paths:
   /escalations:
     get:
       operationId: listEscalations
+      x-cli:
+        command: [escalations, list]
       summary: List every OPEN escalation awaiting a human/agent decision, with the completable userTaskKey.
       description: >-
         Discovery for the escalation-answer path (epic #664, issue #666): across every surfaced
@@ -4649,6 +4667,8 @@ paths:
   /lineage:
     get:
       operationId: getLineage
+      x-cli:
+        command: [lineage]
       summary: "Intent to progress lineage projection (issue #245): every request stitched into one arc (request, implementation, PRs, convergence, merge, outcome), active frontier first. Pass root to fetch a single origin's thread."
       security:
         - hookSecret: []
@@ -4676,6 +4696,8 @@ paths:
   /prs/history:
     get:
       operationId: getPrHistory
+      x-cli:
+        command: [prs, history]
       summary: "A PR's escalation + round history (issue #668): per-round status transitions and outcome, plus each escalation's kind, question/answer, and timestamps — the read that retires the DB-over-ssh fallback. Identify the PR by prKey, or by processKey. Reads the same rounds/escalations tables the Convergence page surfaces."
       security:
         - hookSecret: []
@@ -4715,6 +4737,8 @@ paths:
   /agentic/supply:
     get:
       operationId: getAgenticSupply
+      x-cli:
+        command: [agentic, supply]
       summary: The SUPPLY-ONLY agentic visibility report — the live worker list (family, host, current jobs,
         liveness) grouped by leaf, sourced from the H1 presence registry. Feeds the H5 cockpit page.
       security:
@@ -4736,6 +4760,8 @@ paths:
   /agentic/vocab:
     get:
       operationId: getAgenticVocab
+      x-cli:
+        command: [agentic, vocab]
       summary: The crew vocabulary artifact (enrolment epic 152 slice N1) — the ONE capability→token map a
         worker resolves its SERVE set against. Returns the networks/roles tree plus the flattened
         per-token enrolment requirements and the artifact version. Read-only; advisory.
@@ -4758,6 +4784,8 @@ paths:
   /agentic/enrol:
     post:
       operationId: enrolAgenticWorker
+      x-cli:
+        command: [agentic, enrol]
       summary: Resolve a worker's declared enrolment capability to its SERVE token set (ADR 0059 revised
         REGISTER→SERVE, per-worker). Returns the SERVE leaf tokens, the vocab version resolved against,
         and the liveness lease TTL. Pure/deterministic — idempotent per (app, worker).
@@ -4827,6 +4855,8 @@ paths:
   /agentic/registry:
     get:
       operationId: getAgenticRegistry
+      x-cli:
+        command: [agentic, registry]
       summary: The demand×supply report (enrolment epic 152 slice N1) — deployed demand (the models'
         taskDefinition leaves) diffed against live supply (the presence registry resolved through the
         crew vocab), per network, with missing-agent-type reds and the diversity SLO. Read-only; advisory.
@@ -4849,6 +4879,8 @@ paths:
   /agentic/transcripts:
     get:
       operationId: listAgenticTranscripts
+      x-cli:
+        command: [agentic, transcripts, list]
       summary: List captured agent sessions (H3/#146) — the durable transcripts an ephemeral agent flushed
         on job completion, readable AFTER it exited. Optional filters by jobKey / process instance / plan /
         time. Also serves the proxy-safe single-stream READ form `?stream=` (#744). Advisory read-only;
@@ -4954,6 +4986,12 @@ paths:
   /agentic/transcripts/{stream}:
     get:
       operationId: getAgenticTranscript
+      # x-cli exclusion (#744): the legacy PATH form 404s behind a proxy that decodes %2F in a path
+      # segment for slash-bearing worker-instance ids (`34:<instance>/<jobKey>` — covered by
+      # app/agentic/transcript-url.test.ts). The proxy-safe single-stream read is the query form,
+      # `agentic transcripts list --stream <stream>`; do not project this route into the CLI.
+      x-cli:
+        exclude: true
       summary: Fetch a stored transcript's bytes (H3/#146), range/offset-based so the cockpit terminal
         replays it through the same resume-from-offset renderer it uses for a live stream. PATH form
         of the single-stream read (back-compat; a slash-bearing id 404s behind a decoding proxy —
@@ -5004,6 +5042,8 @@ paths:
   /agentic/agent-instances:
     get:
       operationId: listAgentInstances
+      x-cli:
+        command: [agentic, instances, list]
       summary: >-
         List engine-native AgentInstances (issue #745/#747, umbrella #746) — the durable agent-task
         runs the worker harness minted against the `<zeebe:agentDefinition agentType="external"/>` marker,
@@ -5061,6 +5101,9 @@ paths:
   /agentic/agent-instances/{agentInstanceKey}/history:
     get:
       operationId: getAgentInstanceHistory
+      x-cli:
+        command: [agentic, instances, history]
+        positional: [agentInstanceKey]
       summary: >-
         Fetch one AgentInstance's durable conversation history (turns + per-turn metrics) from
         engine `searchAgentInstanceHistory` (issue #745/#747), in conversational order, with the owning
@@ -5120,6 +5163,9 @@ paths:
   /reconcile:
     post:
       operationId: reconcileEngineState
+      x-cli:
+        command: [admin, reconcile]
+        audience: operator
       summary: Reconcile engine-backed inflight projections after an engine reset/rewind (issue #622).
       description: >-
         The explicit operator command for the app-side reconciliation surface. Probes the engine's
@@ -5154,6 +5200,8 @@ paths:
   /version:
     get:
       operationId: getVersion
+      x-cli:
+        command: [version]
       summary: The running app's identity (app/urban versions, git sha/branch, runtime, pid, uptime).
       security:
         - hookSecret: []
@@ -5174,6 +5222,8 @@ paths:
   /agent:
     get:
       operationId: getAgentInstructions
+      x-cli:
+        command: [guide]
       summary: The agent operator guide (markdown) — how to submit PRs/epics, answer escalations, and
         debug this instance. Point a coding agent at this URL to drive and debug the workforce.
       security:
@@ -5195,6 +5245,8 @@ paths:
   /agent/skill:
     get:
       operationId: getAgentSkill
+      x-cli:
+        command: [guide, skill]
       summary: The portable operator skill (markdown SKILL.md) an agent runtime loads on demand — a
         thin bootstrap that resolves which instance to drive, then fetches the live operator guide
         (GET /agent). Surfaced from the Overview tab's "Agent Instructions" prompt.
@@ -5217,6 +5269,8 @@ paths:
   /agent/guide:
     get:
       operationId: getAgentGuide
+      x-cli:
+        command: [guide, full]
       summary: The operator guide, ADDRESSABLE — fetch one section instead of the whole ~43KB blob.
         Read-only, pure, idempotent. Call with NO `section` to get a compact table of contents (every
         stable section id + a one-line summary); call with `section` set to a TOC id (e.g.
@@ -5289,6 +5343,9 @@ paths:
   /actions/start/convergence-loop:
     post:
       operationId: startConvergenceLoop
+      x-cli:
+        command: [converge]
+        positional: [pr]
       summary: Register/refresh a PR aggregate (idempotent on prKey) and start its convergence loop.
       requestBody:
         required: true
@@ -5376,6 +5433,9 @@ paths:
   /actions/start/plan-fanout:
     post:
       operationId: startPlanFanout
+      x-cli:
+        command: [start, epic]
+        positional: [issue]
       summary: Register/refresh a plan aggregate (idempotent on planKey) and start the planning fan-out.
       requestBody:
         required: true
@@ -5451,6 +5511,8 @@ paths:
   /actions/start/epic-set:
     post:
       operationId: startEpicSet
+      x-cli:
+        command: [start, epic-set]
       summary: Admit a SET of epics plus their inter-epic dependency edges in one all-or-nothing call (issue #292).
       description: >-
         The set/batch admission door (slice S2). Validates the WHOLE submission before persisting
@@ -5581,6 +5643,9 @@ paths:
   /actions/start/sequence-issues:
     post:
       operationId: sequenceIssues
+      x-cli:
+        command: [sequence]
+        positional: [issues]
       summary: Generate + STAGE the canonical "implement issue → converge → merge" delivery graph from a high-level intent (never dispatches). (epic #605 / S4)
       description: >-
         An INTENT-SHAPED door (epic nano-workforce#605, S4). ADR 0005's delivery graph is a closed
@@ -5716,6 +5781,8 @@ paths:
   /actions/compile-delivery-graph:
     post:
       operationId: compileDeliveryGraph
+      x-cli:
+        command: [graph, compile]
       summary: Validate + compile a delivery graph and STAGE it for operator review (never dispatches). (ADR 0005 Decision 7 / #460)
       description: >-
         The agent-facing delivery-graph door — the END of the agent's surface (ADR 0005 Decision 7,
@@ -6192,6 +6259,8 @@ paths:
   /actions/delivery-graph/preview:
     post:
       operationId: previewDeliveryGraph
+      x-cli:
+        command: [graph, preview]
       summary: UI JSON-paste PURE PREVIEW — parse a pasted delivery-graph JSON string and compile it, without staging. (ADR 0005 Decision 7 / #460 / #516)
       description: >-
         The human-facing UI JSON-paste PURE PREVIEW ingress. The Delivery Graphs page's "Preview"
@@ -6246,6 +6315,9 @@ paths:
   /actions/delivery-graph/stage:
     post:
       operationId: stageDeliveryGraph
+      x-cli:
+        command: [graph, stage]
+        audience: operator
       # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door, kept OFF the
       # runtime-projected MCP tool surface. The staged-proposal lifecycle (stage -> dispatch ->
       # dismiss) is the human approval path (ADR 0005 Decision 7 — the operator's click IS the
@@ -6285,6 +6357,9 @@ paths:
   /actions/delivery-graph/dispatch:
     post:
       operationId: dispatchDeliveryGraph
+      x-cli:
+        command: [graph, dispatch]
+        audience: operator
       # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): the canonical operator-only door. Dispatch
       # approval IS a human clicking Dispatch in the cockpit (ADR 0005 Decision 7) — there is no
       # replayable token and no agent-facing dispatch handle, so it is never a projected MCP tool.
@@ -6335,6 +6410,9 @@ paths:
   /actions/delivery-graph/dismiss:
     post:
       operationId: dismissProposal
+      x-cli:
+        command: [graph, dismiss]
+        audience: operator
       # x-mcp exclusion (ADR 0067 §2 / nano-ide#488): operator-only cockpit door — discarding a
       # staged proposal as noise is a human decision in the same approval class as dispatch, so it
       # stays off the projected MCP tool surface.
@@ -6373,6 +6451,8 @@ paths:
   /actions/delivery-graph/proposal-bpmn:
     post:
       operationId: previewProposalBpmn
+      x-cli:
+        command: [graph, proposal-bpmn]
       summary: Recompile a staged delivery-graph proposal's BPMN (with DI) for read-only preview — no deploy, no dispatch.
       description: >-
         Return the compiled BPMN 2.0 XML (including diagram interchange) of a staged delivery-graph
@@ -6413,6 +6493,8 @@ paths:
   /delivery-graph/staged:
     get:
       operationId: listStagedProposals
+      x-cli:
+        command: [graph, staged]
       summary: List the LIVE staged delivery-graph proposals awaiting dispatch (issue #511), newest first.
       description: >-
         The read behind the staged-proposals App-View AND the MCP `listStagedProposals` tool: every
@@ -6453,6 +6535,8 @@ paths:
   /delivery-graph/vocabulary:
     get:
       operationId: getDeliveryGraphVocabulary
+      x-cli:
+        command: [graph, vocabulary]
       summary: The closed delivery-graph vocabulary + wait-probe semantics as structured JSON (ADR 0005).
       description: >-
         Read tool (projected onto the MCP surface like `getAgentInstructions`). Returns the CLOSED
@@ -6709,6 +6793,8 @@ paths:
   /actions/delivery-graph/library/save:
     post:
       operationId: saveToLibrary
+      x-cli:
+        command: [graph, library, save]
       summary: Save a delivery graph to the reusable library — from a raw graph JSON or an existing proposal digest (issue #522, #519 S3).
       description: >-
         Persist a delivery graph to the reusable LIBRARY (issue #522, epic #519 S3) — the durable base
@@ -6764,6 +6850,8 @@ paths:
   /actions/delivery-graph/library/import:
     post:
       operationId: importToLibrary
+      x-cli:
+        command: [graph, library, import]
       summary: Import a delivery graph FROM A FILE into the reusable library (issue #524, #519 S5).
       description: >-
         Import a delivery graph into the LIBRARY from a filesystem file (issue #524, epic #519 S5). The
@@ -6823,6 +6911,8 @@ paths:
   /delivery-graph/library:
     get:
       operationId: listLibrary
+      x-cli:
+        command: [graph, library, list]
       summary: List the saved reusable delivery-graph library entries (issue #522, #519 S3), newest first.
       description: >-
         The read behind the Library App-View (S4/#523): every saved library entry, newest first, with
@@ -6849,6 +6939,9 @@ paths:
   /delivery-graph/library/{id}:
     get:
       operationId: getLibraryEntry
+      x-cli:
+        command: [graph, library, get]
+        positional: [id]
       summary: Fetch one saved library entry by id (issue #522, #519 S3).
       description: >-
         Return one saved library entry (issue #522) by its `id`, including its full `graph` JSON. An
@@ -6884,6 +6977,9 @@ paths:
                 $ref: "#/components/schemas/ErrorBody"
     delete:
       operationId: deleteLibraryEntry
+      x-cli:
+        command: [graph, library, delete]
+        positional: [id]
       summary: Delete one saved library entry by id (issue #522, #519 S3).
       description: >-
         Delete one saved library entry (issue #522) by its `id`. Idempotent — deleting an id that names
@@ -6915,6 +7011,9 @@ paths:
   /actions/start/feature:
     post:
       operationId: startFeature
+      x-cli:
+        command: [start, feature]
+        positional: [issue]
       summary: Register/refresh a feature-run aggregate (idempotent on featureKey) and start the single-issue run.
       requestBody:
         required: true
@@ -7259,6 +7358,9 @@ paths:
   /actions/message:
     post:
       operationId: postMessage
+      x-cli:
+        command: [admin, message]
+        audience: operator
       summary: "Publish a BPMN message (optionally correlated) into the engine. Every escalation kind
         (task, plan-review, trial-merge, PR review-loop, PR merge-loop) is a native user task answered
         via the Tasks inbox / POST /actions/complete-user-task, not this route."
@@ -7307,6 +7409,9 @@ paths:
   /actions/complete-user-task:
     post:
       operationId: completeUserTask
+      x-cli:
+        command: [escalations, answer]
+        positional: [userTaskKey]
       summary: "Complete an open native user-task escalation from the nwf Tasks inbox (issue #236).
         Submits the parked task's typed `.form` variables (e.g. a plan-review `{ directive, notes }`, a
         trial-merge `{ action, notes }`, a PR `{ answer }`, a feature escalation `{ resolution, answer }`,
@@ -7360,6 +7465,8 @@ paths:
   /actions/acknowledge-done:
     post:
       operationId: acknowledgeDone
+      x-cli:
+        command: [ack, done]
       summary: "Tick off a TERMINAL feature run (issue #254 §5). Stamps `acknowledged_at` on the run so
         the gateway recomputes its `list_bucket` to 'history', dropping the finished run out of the
         primary Active list into History. The Done twin of the blocked acknowledgement, but a terminal run is
@@ -7407,6 +7514,8 @@ paths:
   /actions/acknowledge-epic:
     post:
       operationId: acknowledgeEpic
+      x-cli:
+        command: [ack, epic]
       summary: "Dismiss a RESOLVED epic (issue #298). Stamps `acknowledged_at` on the `plans` row so
         the gateway recomputes its `list_bucket` to 'history' (and `ack_open` to 0), dropping the
         resolved epic out of the Active epic list into History. The epic twin of acknowledge-done, but
@@ -7458,6 +7567,8 @@ paths:
   /actions/acknowledge-pr:
     post:
       operationId: acknowledgePr
+      x-cli:
+        command: [ack, pr]
       summary: "Dismiss a TERMINAL pull request (issue #641). Stamps `acknowledged_at` on the
         `pull_requests` row so the `pull_requests_read_model` VIEW recomputes its `list_bucket` to
         'history' (and `ack_open` to 0), dropping the finished PR out of the Active convergence list
@@ -7507,6 +7618,8 @@ paths:
   /actions/acknowledge-delivery-graph:
     post:
       operationId: acknowledgeDeliveryGraph
+      x-cli:
+        command: [ack, graph]
       summary: "Dismiss a TERMINAL delivery-graph run (issue #641). Stamps `acknowledged_at` on the
         `delivery_graph_runs` row so the `delivery_graph_read_model` VIEW recomputes its `list_bucket`
         to 'history' (and `ack_open` to 0), dropping the finished run out of the Active delivery-graph
@@ -7556,6 +7669,8 @@ paths:
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation
+      x-cli:
+        exclude: true
       summary: "Complete an escalation user task as an agent assignee (ADR 0046). Reuses the same
         `.form` contract + engine resume path a human uses; records the agent identity for
         attribution. Optional shared-secret guard (x-hook-secret), enforced only when
@@ -7618,6 +7733,8 @@ paths:
   /hooks/revert-completion:
     post:
       operationId: revertEscalationCompletion
+      x-cli:
+        exclude: true
       summary: "Revert/override an agent escalation completion (ADR 0046 reversibility). A human marks
         a reversible agent completion reverted so the agent's answer is no longer authoritative.
         Optional shared-secret guard (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is
@@ -7677,6 +7794,8 @@ paths:
   /hooks/blackboard:
     get:
       operationId: readBlackboard
+      x-cli:
+        exclude: true
       summary: Read a plan's blackboard, scoped by the capability token (Tier 1). Optional ?since=<id>
         returns only newer entries.
       parameters:
@@ -7717,6 +7836,8 @@ paths:
                 $ref: "#/components/schemas/ErrorBody"
     post:
       operationId: appendBlackboard
+      x-cli:
+        exclude: true
       summary: Append one entry to a plan's blackboard, scoped by the capability token (Tier 1).
         Idempotent on (plan, dedupe_key).
       parameters:
@@ -7791,6 +7912,8 @@ paths:
   /hooks/abandon:
     get:
       operationId: checkAbandon
+      x-cli:
+        exclude: true
       summary: "Cooperative abandon check (issue #76): tell a running agent whether its run was cancelled.
         Scoped by the per-PR capability token."
       parameters:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.210.1",
+  "version": "0.211.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -66,7 +66,7 @@
   },
   "dependencies": {
     "@nanobpm/agentic": "^0.16.0",
-    "@nanobpm/urban": "^0.98.0",
+    "@nanobpm/urban": "^0.99.0",
     "bpmn-auto-layout": "^2.0.0-alpha.2"
   },
   "devDependencies": {