@nanobpm/nano-workforce 0.206.3 → 0.207.0

package/docs/mcp-runbook.md

@@ -214,8 +214,8 @@ acceptable. When it **is set**, the guard is not mutation-only: it also covers
 reads, so read endpoints like `GET /app/api/agent` and `GET /app/api/version`
 return `401` without the `x-hook-secret` header, just as guarded mutations do. It
 is not blanket, though — a few doors stay intentionally unguarded even when the
-secret is set (e.g. the declarative Save-to-library page action, which
-structurally cannot attach the header). Put it in the server entry's
+secret is set (e.g. the declarative Save-to-library and Retry-incident page actions,
+which structurally cannot attach the header). Put it in the server entry's
 `headers`, never in chat. For a remote fleet,
 `NANO_WORKFORCE_BASE_URL` reachability rules apply unchanged. The rest of the app's
 HTTP surface follows the `network.bind` manifest setting, but the runtime-served

package/e2e/delivery-graph.e2e.ts

@@ -373,6 +373,66 @@ describe("delivery-graph runner — engine-native execution (S4)", () => {
     assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the satisfied producer's result reaches End");
   });
 
+  test("#932 producer contract: an agent reporting status=completed with all required emits routes onward and NEVER reaches a human escalation", async () => {
+    const app = track(await boot(freshDir()));
+
+    // Issue #932's observed failure (nano-bpm#1337 → PR #1464 escalation 584376; nano-bpm#1463 →
+    // PR #1476 escalation 599960): the agent FULLY delivered — required `pr` emit present, work done,
+    // PR later merged — but self-reported the affirmative-completion alias `status: "completed"`,
+    // which the #731 gate (accepting only `done`/`opened`/`skipped`) treated as a contract violation
+    // and parked on a human "Continue" escalation. With the synonym allowlisted in the ONE canonical
+    // vocabulary, the same result must sail through the gate: no __contract task, the downstream
+    // connector fires, the graph reaches End.
+    let agentFired = 0;
+    await app.engine.registerWorker("senior:demo", async () => {
+      agentFired++;
+      return { status: "completed", pr: "owner/repo#100", summary: "Fully delivered; PR opened and green." };
+    });
+    let connectorFired = 0;
+    await app.engine.registerWorker(
+      "pr.delivery-connector",
+      async (job) => {
+        connectorFired++;
+        const vars = job.variables as Record<string, unknown>;
+        const { target, payload, boundFacts } = readConnectorInput(vars as Parameters<typeof readConnectorInput>[0]);
+        const dedupeKey = connectorDedupeKey({
+          dedupeKey: (vars.dedupeKey as string | null | undefined) ?? null,
+          processInstanceKey: job.processInstanceKey ?? null,
+          elementId: job.elementId ?? null,
+        });
+        if (!dedupeKey) throw new Error("connector stub: no dedupe key (author-supplied or graph-derived) available");
+        return await dispatchConnector(app.db, { dedupeKey, target, payload, boundFacts }, new Date().toISOString());
+      },
+      { fetchVariables: ["boundFacts", "target", "dedupeKey", "payload"] },
+    );
+
+    const graph: DeliveryGraph = {
+      name: "e2e producer gate completed synonym",
+      nodes: [
+        { id: "open", kind: "agent", agent: { jobType: "senior:demo" }, emits: [{ name: "pr", type: "pr" }] },
+        { id: "land", kind: "connector", connector: { target: "slack", payload: { pr: "open.pr" }, dedupeKey: "land-932" } },
+      ],
+      edges: [{ from: "open.pr", to: "land" }],
+    };
+
+    const run = await runDeliveryGraph(app.engine, graph, { escalationSlaTimeout: "PT1H", repoless: true });
+    assert.ok(run.ok, `graph should deploy + run, got ${JSON.stringify(run)}`);
+    await app.settle();
+
+    // The `completed` report + all required emits is a terminal success: it routes ONWARD — no
+    // producer-contract escalation (and no escalation of any kind), the connector fired once on the
+    // real PR, and the graph reached End. A human is never in the loop.
+    assert.equal(agentFired, 1, "the agent node's job fired and completed");
+    const createdTasks = await app.engine.searchUserTasks({ state: "CREATED" });
+    assert.deepEqual(
+      createdTasks.map((t) => t.elementId),
+      [],
+      `a fully-delivered "completed" result must NEVER park a human task, got ${JSON.stringify(createdTasks.map((t) => t.elementId))}`,
+    );
+    assert.equal(connectorFired, 1, "the satisfied producer threads its result to the downstream connector");
+    assert.ok(takenFlows(app).some((f) => f.endsWith("->End")), "the completed producer's result reaches End");
+  });
+
   test("resume never double-fires: an at-least-once redelivery of the connector dedupes", async () => {
     const app = track(await boot(freshDir()));
     // The connector fired once above's-style; here prove the idempotency directly against the ledger a

package/openapi.yaml

@@ -93,6 +93,7 @@ components:
         - leaseUntil
         - autoResolveEscalations
         - merge
+        - incident
       properties:
         prKey:
           type: string
@@ -107,6 +108,13 @@ components:
           nullable: true
         status:
           type: string
+          description: >-
+            The run's workflow status — `converging`, `waiting_review`, `escalated`, `waiting_deps`,
+            `waiting_merge`, `queued`, `merging` — OVERLAID with `incident` (issue #931) while the
+            run's instance is parked on an ACTIVE engine incident, so a dead-in-the-water loop can
+            never again read as a healthy `converging`. The overlay is derived at read time from the
+            mirrored `incident` block; the base workflow status resumes the moment the incident
+            clears.
         round:
           type: integer
         processKey:
@@ -189,6 +197,37 @@ components:
               nullable: true
               enum: ["env", "human-approval", null]
               description: Why a requested merge will not proceed; null when effective or converge-only.
+        incident:
+          type: object
+          nullable: true
+          additionalProperties: false
+          description: >-
+            The ACTIVE engine incident parking this PR's instance (issue #931), mirrored by the
+            poller's incident pass, else null. While set, `status` reads `incident`. `key` is the
+            engine incidentKey; `type` the errorType (e.g. `JOB_NO_RETRIES`); `message` the
+            errorMessage; `since` the incident's creationTime. The operator remedy is the
+            `retryIncident` action (the Convergence/Home grids' "Retry incident" row action).
+          required:
+            - key
+            - type
+            - message
+            - since
+          properties:
+            key:
+              type: string
+              description: The engine incidentKey of the ACTIVE incident.
+            type:
+              type: string
+              nullable: true
+              description: The incident's errorType (e.g. JOB_NO_RETRIES).
+            message:
+              type: string
+              nullable: true
+              description: The incident's errorMessage.
+            since:
+              type: string
+              nullable: true
+              description: The incident's creationTime (ISO).
     ActivePrList:
       type: object
       required:
@@ -243,6 +282,7 @@ components:
         - openEscalation
         - updatedAt
         - autoResolveEscalations
+        - incident
       properties:
         runKey:
           type: string
@@ -251,6 +291,10 @@ components:
           nullable: true
         status:
           type: string
+          description: >-
+            The run's workflow status (`running`, …) OVERLAID with `incident` (issue #931) while the
+            run's instance is parked on an ACTIVE engine incident — the same read-time overlay the
+            PR rows carry.
         phase:
           type: string
           nullable: true
@@ -285,6 +329,35 @@ components:
             Whether this delivery run opted into automatic escalation resolution by the escalation
             steward (issue #889). Derived from the durable `auto_resolve_escalations` flag, never a
             clobbered process variable.
+        incident:
+          type: object
+          nullable: true
+          additionalProperties: false
+          description: >-
+            The ACTIVE engine incident parking this run's instance (issue #931), mirrored by the
+            poller's incident pass, else null. While set, `status` reads `incident`. Same shape as
+            the PR rows' `incident` block.
+          required:
+            - key
+            - type
+            - message
+            - since
+          properties:
+            key:
+              type: string
+              description: The engine incidentKey of the ACTIVE incident.
+            type:
+              type: string
+              nullable: true
+              description: The incident's errorType (e.g. JOB_NO_RETRIES).
+            message:
+              type: string
+              nullable: true
+              description: The incident's errorMessage.
+            since:
+              type: string
+              nullable: true
+              description: The incident's creationTime (ISO).
     Escalation:
       type: object
       description: >-
@@ -351,6 +424,59 @@ components:
             The denormalised decision/form context the Tasks inbox renders for this task (the same
             question + subject the deployed form is seeded with). The typed answer fields an agent
             submits depend on `kind` (e.g. a PR `{ answer }`, a plan-review `{ directive, notes }`).
+    IncidentList:
+      type: object
+      additionalProperties: false
+      required: [count, incidents]
+      properties:
+        count:
+          type: integer
+        incidents:
+          type: array
+          items:
+            $ref: "#/components/schemas/IncidentEntry"
+    IncidentEntry:
+      type: object
+      additionalProperties: false
+      required: [kind, subjectKey, processInstanceKey, incidentKey, type, message, since, retry]
+      properties:
+        kind:
+          type: string
+          enum: [pr, delivery]
+        subjectKey:
+          type: string
+          description: The PR key (owner/repo#N) or delivery-graph run key.
+        processInstanceKey:
+          type: string
+          nullable: true
+        incidentKey:
+          type: string
+        type:
+          type: string
+          nullable: true
+          description: The engine errorType (e.g. JOB_NO_RETRIES).
+        message:
+          type: string
+          nullable: true
+        since:
+          type: string
+          nullable: true
+          description: The incident's creationTime.
+        retry:
+          type: object
+          additionalProperties: false
+          required: [path, body]
+          properties:
+            path:
+              type: string
+            body:
+              type: object
+              additionalProperties: false
+              required: [processInstanceKey]
+              properties:
+                processInstanceKey:
+                  type: string
+                  nullable: true
     EscalationList:
       type: object
       additionalProperties: false
@@ -4099,6 +4225,38 @@ components:
         error:
           type: string
           description: Present on a non-terminal failure — the reason the cancel did not take, the tracked record was not reconciled, or no tracked record owns the key.
+    RetryIncidentIntent:
+      type: object
+      additionalProperties: false
+      required:
+        - processInstanceKey
+      properties:
+        processInstanceKey:
+          type: string
+          description: The engine process-instance key of the incident-parked run to retry (the `process_key` column surfaced by `listActivePrs`/the Convergence page). Must be a string — engine keys are 64-bit and a numeric value risks silent JS precision loss.
+    RetryIncidentResult:
+      type: object
+      additionalProperties: false
+      required:
+        - ok
+        - processInstanceKey
+      properties:
+        ok:
+          type: boolean
+          description: True when the engine confirmed the incident resolution (the failed job was given a retry first, so a JOB_NO_RETRIES incident does not re-incident instantly) and the record row's mirrored incident columns were cleared. False ⇒ a 4xx/5xx body carrying the reason in `error`.
+        processInstanceKey:
+          type: string
+          description: The instance key, echoed back.
+        incidentKey:
+          type: string
+          description: The engine incidentKey that was resolved (the oldest ACTIVE incident on the instance — the same one the poller mirrors onto the record row).
+        jobKey:
+          type: string
+          nullable: true
+          description: The failed job whose retries were bumped to 1 before the resolution; null when the incident carried no job handle (a non-job fault — resolution alone unsticks it).
+        error:
+          type: string
+          description: Present on a failure — the reason the retry did not take (no tracked record owns the key, no active incident on the instance, or the engine refused the retries bump / resolution).
 # ─────────────────────────────────────────────────────────────────────────────────────────────
 # MCP tool-schema convention (epic nano-workforce#605, S0 — the shared invariant every later slice
 # inherits). The Urban runtime projects THIS document into MCP tools (ADR 0067 — zero MCP server
@@ -4199,6 +4357,61 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/incident/retry:
+    post:
+      operationId: retryIncident
+      # 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
+      # do not force engine retries.
+      x-mcp:
+        exclude: true
+      summary: "Retry an incident-parked run the app-owned way (issue #931): bump the failed job's retries AND resolve the ACTIVE engine incident on the run's instance, then clear the incident mirror off the record row. This is the operator remedy for a loop that shows `status: \"incident\"` — previously a hand-run engine-REST sequence (`PATCH /v2/jobs/<k> {changeset:{retries:1}}` + `POST /v2/incidents/<k>/resolution`)."
+      # Intentionally NO hookSecret security: the declarative "Retry incident" page action cannot
+      # attach x-hook-secret (see operations/retryIncident.ts).
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/RetryIncidentIntent"
+      responses:
+        "200":
+          description: The incident was resolved (the failed job was given a retry first) and the record row's incident mirror cleared — the `/status` row leaves `incident` immediately.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "400":
+          description: Missing/invalid `processInstanceKey`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "404":
+          description: No tracked record owns the key (a clean no-op — the engine is never touched).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "409":
+          description: The instance carries no ACTIVE incident — nothing to retry (it may already be resolved).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "502":
+          description: "The remedy did not fully take: the engine's incident search was unavailable, the job retries bump failed (the incident is left ACTIVE — never a half-applied remedy), or the resolution itself failed."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/RetryIncidentResult"
+        "503":
+          description: The app has no data source configured, so the record cannot be resolved.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /auto-resolutions:
     get:
       operationId: listAutoResolutions
@@ -4302,6 +4515,31 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /incidents:
+    get:
+      operationId: listIncidents
+      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
+        over the incident mirror the poller writes onto PR and delivery-graph rows (the same source
+        as the `/status` `incident` overlay). Each entry carries the operator remedy: POST
+        `retry.path` (the `retryIncident` action) with `retry.body`.
+      security:
+        - hookSecret: []
+        - {}
+      responses:
+        "200":
+          description: The active incidents.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/IncidentList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /escalations:
     get:
       operationId: listEscalations

package/operations/listIncidents.test.ts

@@ -0,0 +1,70 @@
+// Tests for GET /app/api/incidents operation `listIncidents` (issue #931): the incident projection
+// lists every mirrored ACTIVE incident (PR + delivery-graph rows) with its retry remedy, oldest first.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./listIncidents.ts";
+
+function memApp(stores: Record<string, Record<string, unknown>[]>): AppApi {
+  const app = {
+    data: { table: (n: string) => ({ all: async () => [...(stores[n] ?? [])] }) },
+    log: noopLog(),
+    // biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+  } as any as AppApi;
+  return app;
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test harness cast, mirrors sibling op tests
+async function call(app: AppApi): Promise<any> {
+  // biome-ignore lint/suspicious/noExplicitAny: see above
+  return (await handler({ req: { headers: new Headers() } as any, params: {}, query: {}, body: undefined } as any, app)) as any;
+}
+
+test("listIncidents: lists PR + delivery incidents oldest-first with the retry remedy; skips healthy rows", async () => {
+  const app = memApp({
+    pull_requests: [
+      { pr_key: "o/r#1", process_key: "11", incident_key: null },
+      {
+        pr_key: "o/r#2",
+        process_key: "22",
+        incident_key: "i2",
+        incident_type: "JOB_NO_RETRIES",
+        incident_message: "idle",
+        incident_since: "2026-11-09T10:00:00Z",
+      },
+    ],
+    delivery_graph_runs: [
+      {
+        run_key: "run-a",
+        process_key: "33",
+        incident_key: "i3",
+        incident_type: "IO_MAPPING_ERROR",
+        incident_message: "boom",
+        incident_since: "2026-11-09T09:00:00Z",
+      },
+    ],
+  });
+  const res = await call(app);
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 2);
+  assertEquals(
+    res.body.incidents.map((i: { kind: string; subjectKey: string }) => `${i.kind}:${i.subjectKey}`),
+    ["delivery:run-a", "pr:o/r#2"],
+  );
+  assertEquals(res.body.incidents[1], {
+    kind: "pr",
+    subjectKey: "o/r#2",
+    processInstanceKey: "22",
+    incidentKey: "i2",
+    type: "JOB_NO_RETRIES",
+    message: "idle",
+    since: "2026-11-09T10:00:00Z",
+    retry: { path: "/app/api/actions/incident/retry", body: { processInstanceKey: "22" } },
+  });
+});
+
+test("listIncidents: empty when nothing is parked", async () => {
+  const res = await call(memApp({ pull_requests: [{ pr_key: "x", incident_key: null }] }));
+  assertEquals(res.body, { count: 0, incidents: [] });
+});

package/operations/listIncidents.ts

@@ -0,0 +1,78 @@
+// GET /app/api/incidents → operationId `listIncidents` (issue #931). The sibling of `/escalations`
+// for TECHNICAL liveness faults: every tracked run (PR convergence/merge loop, delivery-graph run)
+// whose engine instance is parked on an ACTIVE incident, with the `processInstanceKey` the operator
+// remedy `retryIncident` (POST /actions/incident/retry) takes.
+//
+// Read-only projection over the ONE incident mirror the poller's `pollIncidents` pass writes onto
+// the record rows (`incident_key/type/message/since`) — NOT a second engine query, so it can never
+// disagree with the `/status` rows' `incident` overlay. Oldest incident first (longest-dead first).
+//
+// The optional shared-secret guard stays HERE (mirrors `listEscalations`).
+import type { DataLayer } from "@nanobpm/urban";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export interface IncidentView {
+  kind: "pr" | "delivery";
+  subjectKey: string;
+  processInstanceKey: string | null;
+  incidentKey: string;
+  type: string | null;
+  message: string | null;
+  since: string | null;
+  retry: { path: string; body: { processInstanceKey: string | null } };
+}
+
+interface MirrorRow {
+  process_key?: string | null;
+  incident_key?: string | null;
+  incident_type?: string | null;
+  incident_message?: string | null;
+  incident_since?: string | null;
+}
+
+const RETRY_PATH = "/app/api/actions/incident/retry";
+
+function toView(kind: IncidentView["kind"], subjectKey: string, r: MirrorRow): IncidentView | null {
+  if (!r.incident_key) return null;
+  const processInstanceKey = r.process_key ?? null;
+  return {
+    kind,
+    subjectKey,
+    processInstanceKey,
+    incidentKey: r.incident_key,
+    type: r.incident_type ?? null,
+    message: r.incident_message ?? null,
+    since: r.incident_since ?? null,
+    retry: { path: RETRY_PATH, body: { processInstanceKey } },
+  };
+}
+
+/** Every mirrored ACTIVE incident across the incident-watched aggregates, oldest first (a missing
+ * `since` sorts last). */
+export async function activeIncidents(data: DataLayer): Promise<IncidentView[]> {
+  const out: IncidentView[] = [];
+  const prRows = await data.table<MirrorRow & { pr_key: string }>("pull_requests", "pr_key").all();
+  for (const r of prRows) {
+    const v = toView("pr", r.pr_key, r);
+    if (v) out.push(v);
+  }
+  const runRows = await data.table<MirrorRow & { run_key: string }>("delivery_graph_runs", "run_key").all();
+  for (const r of runRows) {
+    const v = toView("delivery", r.run_key, r);
+    if (v) out.push(v);
+  }
+  return out.sort((a, b) => (a.since ?? "\uffff").localeCompare(b.since ?? "\uffff"));
+}
+
+export default defineOperation("listIncidents", async ({ req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("listIncidents rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  if (!app.data) return { status: 200, body: { count: 0, incidents: [] } };
+  const incidents = await activeIncidents(app.data);
+  return { status: 200, body: { count: incidents.length, incidents } };
+});