@nanobpm/nano-workforce 0.208.2 → 0.208.4

package/db/migrations/131_pull_requests_read_model_termination_reason.sql

@@ -0,0 +1,48 @@
+-- Re-create the `pull_requests_read_model` VIEW so it re-exports the new base column (the VIEW must pass
+-- through EVERY base `pull_requests` column — app/pullRequestReadModel.test.ts DRIFT GUARD). A mechanical
+-- re-emission of 128 with `termination_reason` added; the derived columns are emitted VERBATIM from
+-- app/pullRequestReadModel.ts and are unchanged. No BEGIN/COMMIT (the runner wraps each file). Numbered after 130.
+
+DROP VIEW IF EXISTS pull_requests_read_model;
+
+CREATE VIEW pull_requests_read_model AS
+SELECT
+  pr.pr_key AS pr_key,
+  pr.repo AS repo,
+  pr.number AS number,
+  pr.url AS url,
+  pr.title AS title,
+  COALESCE(pr.derived_status, pr.status) AS status,
+  pr.current_round AS current_round,
+  pr.process_key AS process_key,
+  pr.waiting_since AS waiting_since,
+  pr.last_review_id AS last_review_id,
+  pr.outcome AS outcome,
+  pr.created_at AS created_at,
+  pr.updated_at AS updated_at,
+  pr.converged_at AS converged_at,
+  pr.merged_at AS merged_at,
+  pr.active_worker AS active_worker,
+  pr.lease_until AS lease_until,
+  pr.last_nudge_at AS last_nudge_at,
+  pr.fresh_head_run_head AS fresh_head_run_head,
+  pr.abandon_token AS abandon_token,
+  pr.incident_key AS incident_key,
+  pr.incident_type AS incident_type,
+  pr.incident_since AS incident_since,
+  pr.incident_message AS incident_message,
+  pr.last_round_head AS last_round_head,
+  pr.last_progress_job_key AS last_progress_job_key,
+  pr.last_progress_result AS last_progress_result,
+  pr.last_progress_agent_watermark AS last_progress_agent_watermark,
+  pr.churn_escalated_round AS churn_escalated_round,
+  pr.root_request_key AS root_request_key,
+  pr.epic_phase_label AS epic_phase_label,
+  pr.acknowledged_at AS acknowledged_at,
+  pr.auto_resolve_escalations AS auto_resolve_escalations,
+  pr.termination_reason AS termination_reason,
+  pr.termination_process_key AS termination_process_key,
+  pr.retire_pending_key AS retire_pending_key,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("pr"."derived_status" = 'merged'), 0) OR COALESCE(("pr"."derived_status" = 'converged'), 0) OR COALESCE(("pr"."derived_status" = 'abandoned'), 0) OR COALESCE(("pr"."derived_status" = 'closed'), 0) OR COALESCE(("pr"."derived_status" = 'failed'), 0)), 0) AND (NOT COALESCE(COALESCE(("pr"."acknowledged_at" = "pr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM pull_requests__tracking pr;

package/e2e/feature-preflight.e2e.ts

@@ -159,7 +159,7 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       assert.ok(
         flows.includes("ensure-base-branch->record-feature-implementing") &&
           flows.includes("record-feature-implementing->implement") &&
-          flows.includes("Start->implement-task"),
+          flows.includes("slice-branch->implement-task"),
         `the run reaches the implement agent (via the implement cell) only after the gate (flows: ${flows.join(", ")})`,
       );
       // A green probe never escalates.
@@ -192,7 +192,7 @@ describe("single-issue feature intake readiness gate (feature.bpmn, issue #295)"
       assert.ok(!flows.includes("gw-readiness->readiness-preflight"), "an ungated feature never enters the preflight");
       assert.ok(
         flows.includes("record-feature-implementing->implement") &&
-          flows.includes("Start->implement-task"),
+          flows.includes("slice-branch->implement-task"),
         "an ungated feature reaches the implement agent (via the implement cell)",
       );
     } finally {

package/e2e/plan-fanout.e2e.ts

@@ -21,6 +21,7 @@ import { after, before, describe, test } from "node:test";
 import { fileURLToPath } from "node:url";
 import type { EngineJob } from "@nanobpm/urban/runtime";
 import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { recoverBranchCreate } from "../app/repoEnvelope.ts";
 import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
 import { advancePastTimer, settleFully } from "./support/time.ts";
 
@@ -127,32 +128,127 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
   const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
   const approveReview: Stub = () => ({ approved: true, findings: "" });
 
-  test("host-git provisioning: each slice's implement-cell agent job carries the repository envelope (#684)", async () => {
+  test("host-git provisioning: each slice's implement-cell agent job carries the repository envelope AND the deterministic branch.create (#684/#945)", async () => {
     // The whole-epic seed emits `io.nanobpm.agentTask.repository` so every slice's `senior:feature`
     // agent gets an ISOLATED clone instead of clobbering the worker's launch dir. The process variable
     // rides down through the wave subprocess + `implement-cell-call` callActivity into each agent job.
     // The epic seed carries the BASE branch as `ref` but NO `branch.create` — each slice's
-    // `feat/<task.id>` differs per MI child, so the agent cuts its own branch inside the clone.
-    let agentTask: any = null;
+    // `feat/<task.id>` differs per MI child, so it can't be named at seed time. Issue #945: the
+    // per-instance `slice-branch` worker (first step of each implement-cell) now stamps the deterministic `branch.create` (`feat/<task.id>`)
+    // onto the envelope as a FLAT dotted process variable (`io.nanobpm.agentTask.branch.create`), which
+    // the c8ctl harness deep-merges with the whole-object seed — so a retry re-derives the SAME branch
+    // and the durable WIP checkpoint restore matches (previously every retry cut a random
+    // `nano/agent-work/*` fallback and discarded the prior session's work).
+    let agentVars: Record<string, unknown> = {};
     await withApp(
       {
         "senior:plan": singleTaskPlan,
         "senior:plan-review": approveReview,
         "senior:feature": (job) => {
-          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
+          agentVars = job.variables as Record<string, unknown>;
           return { status: "blocked", summary: "n/a" };
         },
       },
       async ({ app }) => {
         await app.settle();
+        const agentTask = agentVars["io.nanobpm.agentTask"] as Record<string, any> | undefined;
         assert.ok(agentTask, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
         const agentRepo = agentTask.repository;
         assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
         assert.equal(agentRepo.ref, "epic/e2e", "the epic seed checks out the BASE (integration) branch");
-        // `branch` is a top-level sibling of `repository` (#882); the epic seed omits it entirely.
-        assert.equal("branch" in agentTask, false, "the epic seed omits branch.create — the agent branches per slice");
         assert.equal(agentRepo.singleBranch, true, "the blobless/single-branch monorepo shaping rides along");
         assert.equal(agentRepo.filter, "blob:none");
+        // The whole-object seed still omits `branch` (it can't name a per-child branch)…
+        assert.equal("branch" in agentTask, false, "the whole-object seed carries no per-slice branch");
+        // …but the per-instance slice-branch worker stamps it as a FLAT dotted variable, which the harness
+        // merges onto the SAME envelope. Assert the dotted variable is present and names the
+        // deterministic `feat/<task.id>` branch (the single task here is `t1`).
+        assert.equal(
+          agentVars["io.nanobpm.agentTask.branch.create"],
+          "feat/t1",
+          "slice-branch stamps the deterministic per-slice branch.create as a flat dotted variable (#945)",
+        );
+        // Round-trip through the harness normalizer shape: the merged envelope must recover
+        // `branch.create` from the top level (proving the dotted variable and the whole-object seed
+        // merge into one envelope the harness reads).
+        assert.equal(
+          recoverBranchCreate({}, agentVars),
+          "feat/t1",
+          "the harness merges the dotted branch.create with the whole-object seed envelope (#945)",
+        );
+      },
+    );
+  });
+
+  test("sibling isolation: two parallel slices each see their OWN branch.create, never a sibling's (#945)", async () => {
+    // A per-slice branch emitted into the SHARED plan-fanout MI body lands on the epic root, so a
+    // sibling's emission overwrites it and a slice can inherit `feat/<sibling>` — sending its work and
+    // checkpoint to the wrong branch. The emitter runs inside each implement-cell instance instead, so
+    // every activation's recovered branch must be `feat/<its own task.id>`.
+    const seen: Array<{ id: unknown; branch: string | undefined }> = [];
+    await withApp(
+      {
+        "senior:plan": () => ({
+          tasks: [
+            { id: "t1", title: "T1", prompt: "do t1" },
+            { id: "t2", title: "T2", prompt: "do t2" },
+          ],
+        }),
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          const vars = job.variables as Record<string, any>;
+          seen.push({ id: vars.task?.id, branch: recoverBranchCreate({}, vars) });
+          return { status: "blocked", summary: "n/a" };
+        },
+      },
+      async ({ app }) => {
+        await app.settle();
+        assert.deepEqual(
+          seen.map((s) => s.id).sort(),
+          ["t1", "t2"],
+          "both sibling slices activated their implement-task",
+        );
+        for (const s of seen) {
+          assert.equal(s.branch, `feat/${String(s.id)}`, `slice ${String(s.id)} must see its OWN branch.create`);
+        }
+      },
+    );
+  });
+
+  test("retry determinism: a re-dispatched implement-task names the SAME branch.create, so the WIP checkpoint restore matches (#945)", async () => {
+    // Issue #945's field failure: every c8ctl retry of an implement-cell slice cut a NEW random
+    // `nano/agent-work/*` fallback branch, so the durable WIP checkpoint (keyed on the deterministic
+    // `feat/<task.id>`) was NEVER restored — each retry started from the epic base and discarded the
+    // prior session's work. The fix makes `branch.create` a pure function of `task.id`, so a retry
+    // re-derives the SAME branch and the checkpoint restore matches. Drive the implement-task through
+    // TWO activations of the SAME slice (an escalation parks it; answering re-dispatches it — the same
+    // re-activation an idle-kill retry produces) and assert both carry the identical recovered
+    // `branch.create`.
+    const seenBranches: Array<string | undefined> = [];
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": (job) => {
+          seenBranches.push(recoverBranchCreate({}, job.variables as Record<string, unknown>));
+          // First activation escalates (parks for a human); the resume (second activation) blocks.
+          return seenBranches.length === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "blocked", summary: "resumed after answer" };
+        },
+      },
+      async ({ app, processKey }) => {
+        // First activation parked on the human-escalation task; answer it to re-dispatch the SAME slice.
+        const task = await openTask(app, processKey, "escalation");
+        await app.engine.completeUserTask(task.userTaskKey, { resolution: "answer", answer: "use v2" });
+        await app.settle();
+        assert.equal(seenBranches.length, 2, "the implement-task was activated twice (initial + retry)");
+        assert.equal(seenBranches[0], "feat/t1", "the FIRST activation carries the deterministic branch.create");
+        assert.equal(
+          seenBranches[1],
+          seenBranches[0],
+          "the RETRY activation re-derives the SAME branch.create — the WIP checkpoint restore matches (#945)",
+        );
       },
     );
   });
@@ -532,7 +628,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
 
         const flows = takenFlows(app);
         assert.ok(
-          flows.includes("wait-caps-resolved->implement-cell-call") && flows.includes("Start->implement-task"),
+          flows.includes("wait-caps-resolved->implement-cell-call") && flows.includes("slice-branch->implement-task"),
           `caps-resolved released the barrier into the implement cell (flows: ${flows.join(", ")})`,
         );
         assert.equal(
@@ -614,7 +710,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         assert.ok(
           answered.includes("w_gw_answer->record-task-implementing") &&
             answered.includes("record-task-implementing->implement-cell-call") &&
-            answered.includes("Start->implement-task"),
+            answered.includes("slice-branch->implement-task"),
           `answering the caps escalation reset the stale question and released the barrier into the implement cell (flows: ${answered.join(", ")})`,
         );
         assert.equal(featureRan, true, "the agent was dispatched once the operator answered the caps escalation");
@@ -668,7 +764,7 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
         assert.ok(
           entered.includes("w_gw_answer->record-task-implementing") &&
             entered.includes("record-task-implementing->implement-cell-call") &&
-            entered.includes("Start->implement-task"),
+            entered.includes("slice-branch->implement-task"),
           `answering the caps escalation reset the stale question and released the barrier into the implement cell (flows: ${entered.join(", ")})`,
         );
 

package/nano.app.json

@@ -180,6 +180,10 @@
       "taskType": "pr.select-wave",
       "handler": "workers/select-wave/worker.ts"
     },
+    {
+      "taskType": "pr.slice-branch",
+      "handler": "workers/slice-branch/worker.ts"
+    },
     {
       "taskType": "pr.caps-prepare",
       "handler": "workers/caps-prepare/worker.ts"

package/openapi.yaml

@@ -94,7 +94,15 @@ components:
         - autoResolveEscalations
         - merge
         - incident
+        - terminationReason
       properties:
+        terminationReason:
+          type: string
+          nullable: true
+          description: >-
+            Why the app (or an operator) last cancelled this PR's current loop instance (issue #943),
+            naming the successor/outcome; null when never. An `orphaned` status means the loop ended
+            with no recorded reason, successor, or escalation.
         prKey:
           type: string
         repo:
@@ -4357,6 +4365,51 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/cancel-pr:
+    post:
+      operationId: cancelPrRun
+      # x-mcp exclusion: the page-only twin of `cancelInstance` (the per-row Cancel button). Agents use
+      # the guarded `/actions/cancel` door.
+      x-mcp:
+        exclude: true
+      summary: "Page-facing record-consistent cancel (issue #943): identical to `cancelInstance` (shared implementation, records termination provenance) but unguarded, because the declarative page action cannot attach x-hook-secret (see operations/cancelPrRun.ts)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/CancelInstanceIntent"
+      responses:
+        "200":
+          description: The instance was terminated; its record derives/flips to `abandoned` and drops out of `listActivePrs`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "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). Body is a CancelInstanceResult with `ok:false`, `state:\"gone\"`, `reconciled:0`."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "502":
+          description: "The cancel did not fully take: EITHER the engine did NOT stop the instance (the cancel was not committed; the run may still be live), OR the engine stopped it but the tracked record did not settle to a terminal edge (`ok:false`, `reconciled:0`) — a wedged record the caller must not read as done."
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/CancelInstanceResult"
+        "503":
+          description: The app has no data source configured, so the cancel cannot be reconciled into the record.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/incident/retry:
     post:
       operationId: retryIncident

package/operations/cancelInstance.test.ts

@@ -293,3 +293,12 @@ test("record routing also covers PR/plan aggregates (a resolved pull_requests ke
   assertEquals(res.body.ok, true);
   assertEquals(res.body.reconciled, 1);
 });
+
+test("PR#944: operator-cancel provenance is recorded even when the record fails to reconcile (502)", async () => {
+  const rows: any[] = [{ pr_key: "o/r#4", process_key: "400", status: "converging" }];
+  const { app } = makeRecordApp({ pull_requests: { rows, key: "pr_key" } }, { readBackState: "TERMINATED" });
+  const res = await call(app, { processInstanceKey: "400" });
+  assertEquals(res.status, 502, "the unreconciled record still surfaces as 502");
+  assertEquals(rows[0].termination_process_key, "400", "provenance is stamped once the engine confirms termination");
+  assert(typeof rows[0].termination_reason === "string" && rows[0].termination_reason.length > 0);
+});

package/operations/cancelInstance.ts

@@ -37,9 +37,12 @@
 // door, when NANO_PR_WEBHOOK_SECRET is set callers must present it via the x-hook-secret header —
 // mirroring `reconcileEngineState`/`agentCompleteEscalation`.
 
+import type { AppApi } from "@nanobpm/urban";
 import { cancelInstanceReconciling } from "@nanobpm/urban";
 import { engineBackedBindings, resolveTrackedInstance } from "../app/instanceTracking.ts";
+import { recordOperatorCancelProvenance } from "../app/service.ts";
 import { envVar } from "../app/version.ts";
+import type { CancelInstanceResponse } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
@@ -49,6 +52,17 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
     app.log.warn("cancelInstance rejected: missing/invalid shared secret");
     return { status: 401, body: { error: "unauthorized" } };
   }
+  return cancelTrackedRun(app, body, "/actions/cancel");
+});
+
+/** The ONE record-consistent cancel implementation shared by every cancel door (this guarded API/MCP
+ * door and the unguarded page door `/actions/cancel-pr`, operations/cancelPrRun.ts), so both stamp
+ * termination provenance (issue #943, PR #944 review) and neither can drift. Auth stays per door. */
+export async function cancelTrackedRun(
+  app: AppApi,
+  body: unknown,
+  door: string,
+): Promise<{ status: number; body: CancelInstanceResponse }> {
   if (!app.data) {
     app.log.warn("cancelInstance: no data source configured — cannot reconcile the record");
     return { status: 503, body: { error: "no data source configured" } };
@@ -58,7 +72,7 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
   // so a numeric JSON value would already have lost precision before it reached us — accepting it
   // (and coercing it back to a string) would silently cancel the wrong instance and also contradicts
   // the OpenAPI `string` contract. Reject a non-string with a 400 rather than coerce.
-  const raw = body && typeof body === "object" ? body.processInstanceKey : undefined;
+  const raw = body && typeof body === "object" && "processInstanceKey" in body ? body.processInstanceKey : undefined;
   const processInstanceKey = typeof raw === "string" ? raw.trim() : "";
   if (!processInstanceKey) {
     return { status: 400, body: { error: "processInstanceKey is required and must be a string" } };
@@ -124,6 +138,17 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
   // delta lies. Re-read the resolved record and count it reconciled only when its ADR-0065
   // `derived_status` has LEFT its `activeStatuses` (become terminal → resubmittable). When we cannot
   // read the record (no default source), trust the primitive's own count.
+  // Termination provenance (issue #943): a deliberate operator cancel of a PR loop is NOT an orphan —
+  // stamp the reason (as soon as the ENGINE confirms termination, before
+  // the record re-read — a 502 on an unreconciled record must not lose it; PR #944 review) on the owning PR row so `/status` does not flag it `orphaned`. Best-effort.
+  if (canResolveRecord) {
+    try {
+      await recordOperatorCancelProvenance(app.data, processInstanceKey, door);
+    } catch (err) {
+      app.log.warn("cancelInstance: could not record termination reason", { processInstanceKey, error: String(err) });
+    }
+  }
+
   let reconciled = result.reconciled;
   let recordReconciled = true;
   if (canResolveRecord) {
@@ -163,4 +188,5 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
     reconciled,
   });
   return { status: 200, body: responseBody };
-});
+}
+

package/operations/cancelPrRun.ts

@@ -0,0 +1,16 @@
+// POST /app/api/actions/cancel-pr → operationId `cancelPrRun` (issue #943, PR #944 review).
+//
+// The page-facing twin of `cancelInstance` for the per-row Cancel button. The runtime's built-in
+// `/app/actions/cancel` page action bypassed the app's termination-provenance write, so a deliberate
+// UI cancel left an in-flight base status with no reason and `/status` reported it `orphaned`. Both
+// doors now route through ONE implementation (`cancelTrackedRun`), which stamps provenance.
+//
+// Auth posture is preserved: like the built-in page action it replaces (and `retryIncident`), this
+// door is INTENTIONALLY UNGUARDED by NANO_PR_WEBHOOK_SECRET — the `@nanobpm/urban` page runtime cannot
+// attach x-hook-secret, so a guard would 401 every button press on a secured deployment. The guarded
+// `/actions/cancel` stays the API/MCP door; this one is excluded from MCP (`x-mcp`).
+
+import { defineOperation } from "../nano-generated/operations.ts";
+import { cancelTrackedRun } from "./cancelInstance.ts";
+
+export default defineOperation("cancelPrRun", async ({ body }, app) => cancelTrackedRun(app, body, "/actions/cancel-pr"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.208.2",
+  "version": "0.208.4",
   "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",

package/pages/home.page.json

@@ -247,7 +247,7 @@
             "confirm": "Cancel this PR's review run?",
             "showWhenField": "process_key",
             "action": {
-              "path": "/app/actions/cancel",
+              "path": "/app/api/actions/cancel-pr",
               "body": {
                 "processInstanceKey": "{{row.process_key}}"
               }