@nanobpm/nano-workforce 0.176.0 → 0.176.1

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [0.176.1](https://github.com/nanobpm/nano-workforce/compare/v0.176.0...v0.176.1) (2026-09-02)
+
+### Bug Fixes
+
+* **cancel:** reconcile feature_runs in the app cancel door with a truthful result ([#712](https://github.com/nanobpm/nano-workforce/issues/712)) ([810979b](https://github.com/nanobpm/nano-workforce/commit/810979b3708a247b2ab4ee068c211abd5478363a)), closes [#667](https://github.com/nanobpm/nano-workforce/issues/667) [#705](https://github.com/nanobpm/nano-workforce/issues/705)
+
 ## [0.176.0](https://github.com/nanobpm/nano-workforce/compare/v0.175.2...v0.176.0) (2026-09-02)
 
 ### Features

package/app/instanceTracking.ts

@@ -112,3 +112,46 @@ export function derivedTrackingTable<T extends object>(
 ): Table<T> {
   return data.table<T>(trackingTargetFor(table).view, pk);
 }
+
+/** A tracked record resolved from an engine process-instance key: which binding's base table owns it,
+ *  its ADR-0065 `derived_status` (the terminal edge folded over the base transient), and whether that
+ *  derived status is still ACTIVE (in the binding's `activeStatuses`). `active === false` means the
+ *  record has LEFT Active — it is at a terminal edge (`abandoned`/`failed`/`reviewed`/…) and
+ *  resubmittable. */
+export interface ResolvedTrackedInstance {
+  table: string;
+  keyField: string;
+  derivedStatus: string;
+  active: boolean;
+}
+
+/** Resolve which tracked record (if any) an engine process-instance key belongs to, scanning every
+ *  engine-backed binding and matching the key against each binding's `keyField` on its DERIVED
+ *  tracking VIEW — so the answer reflects the ADR-0065 terminal edge, not the frozen base transient.
+ *  This is the cancel door's record-type resolver (issue #705): it lets the door route a key to the
+ *  correct aggregate (PR vs plan vs feature run vs …) and report a TRUTHFUL reconciled result, and
+ *  distinguishes a key that maps to a tracked record (reconcile it) from one that maps to NONE (a
+ *  clean no-op, never a silent success). Returns `undefined` when no binding has a row for the key.
+ *  Reads only — the terminal transition itself is DERIVED (recorded through the shared
+ *  `reconcileTerminatedKey` seam), never hand-written here. */
+export async function resolveTrackedInstance(
+  data: DataLayer,
+  processInstanceKey: string,
+): Promise<ResolvedTrackedInstance | undefined> {
+  for (const binding of engineBackedBindings()) {
+    const table = binding.table;
+    const keyField = keyFieldFor(table);
+    const row = await derivedTrackingTable<Record<string, unknown>>(data, table, keyField).findOne({
+      [keyField]: processInstanceKey,
+    });
+    if (!row) continue;
+    const statusColumn = trackingTargetFor(table).statusColumn;
+    const derivedStatus = String(row[statusColumn] ?? "");
+    // Classify against the manifest-enforced active set (throws on a binding whose `activeStatuses`
+    // is missing/empty) rather than a silent `?? []` — an empty fallback would misclassify EVERY
+    // resolved record as terminal (`active:false`) and let the cancel door report a false success.
+    const active = activeStatusesFor(table).some((s) => s === derivedStatus);
+    return { table, keyField, derivedStatus, active };
+  }
+  return undefined;
+}

package/openapi.yaml

@@ -3188,20 +3188,20 @@ components:
       properties:
         ok:
           type: boolean
-          description: True when the engine confirmed the instance is terminated (the record is now — or derives as — `abandoned`). False ⇒ the engine did NOT stop the instance (surfaced as a 502).
+          description: True when the engine confirmed the instance is terminated AND its tracked record reconciled to a terminal edge (the record is now — or derives as — `abandoned`). False ⇒ either the engine did NOT stop the instance, or it stopped it but the tracked record did not settle to a terminal edge (both surfaced as a 502), or no tracked record owns the key (404). NOTE — record reconciliation is only verified when the deployment has a readable default source; in a no-default-source deployment (e.g. `mount.data:false`) there is no derived view to reconcile against, so `ok:true` reflects ENGINE TERMINATION ONLY (the primitive-only path) and does not by itself guarantee a tracked record reconciled.
         processInstanceKey:
           type: string
           description: The cancelled instance key, echoed back.
         state:
           type: string
           enum: [ACTIVE, COMPLETED, TERMINATED, gone]
-          description: The instance state read back from the engine after the cancel attempt. `gone` ⇒ the engine has no record of the key (already cleaned up / never existed).
+          description: The instance state after the cancel attempt. For a tracked key, this is read back from the engine — `ACTIVE`/`COMPLETED`/`TERMINATED` reflect that post-cancel engine read. NOTE — this readback can LAG — a committed cancel is acknowledged asynchronously, so the engine may still report `ACTIVE` for a short window even though the cancel has been accepted. Therefore `ok:true` can coincide with `state:ACTIVE` (see the "accepted cancel whose read model lags at ACTIVE is still trusted → 200 ok" case); do NOT treat `ok:true` + `state:ACTIVE` as contradictory — `ok`/`reconciled` are the authoritative signal that the cancel took, not `state`. `gone` ⇒ EITHER the engine has no record of the key (already cleaned up / never existed) OR no tracked record owns the key (the 404 no-op, in which case the engine is never contacted, so `gone` is not an engine read).
         reconciled:
           type: integer
-          description: 1 when the immediate reconcile recorded the terminal source into the canonical instance-state projection (so the PR's derived tracking status flips to `abandoned` at once), else 0.
+          description: 1 when the tracked record's derived status has left its active set (become terminal → the tracked PR/plan/feature-run row derives as `abandoned`; for a PR that additionally means it drops out of `listActivePrs`, which lists PRs only — plans and feature runs are not surfaced there), else 0. NOTE — with no readable default source there is no derived record to re-read, so this carries the primitive's own reconciliation count rather than a record-derived terminal edge.
         error:
           type: string
-          description: Present only on a non-terminal failure — the reason the cancel did not take.
+          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.
 # ─────────────────────────────────────────────────────────────────────────────────────────────
 # 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
@@ -3284,8 +3284,14 @@ paths:
             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 engine did NOT stop the instance (the cancel was not committed); the run may still be live.
+          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:

package/operations/cancelInstance.test.ts

@@ -10,7 +10,9 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { AppApi } from "@nanobpm/urban";
+import { memBlackboardSource } from "../test/blackboardDb.ts";
 import { noopLog } from "../test/log.ts";
+import { withTrackingViews } from "../test/trackingViews.ts";
 import handler from "./cancelInstance.ts";
 
 interface FakeEngineOpts {
@@ -136,3 +138,158 @@ test("shared-secret guard: when NANO_PR_WEBHOOK_SECRET is set, a missing/wrong s
     else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
   }
 });
+
+// --- Record-type routing + a truthful reconciled result (issue #705) ----------------------------
+//
+// #667 shipped this door reconciling the pull_requests / plans aggregates, but a `processInstanceKey`
+// belonging to a FEATURE RUN reported `reconciled:0` and left the `feature_runs` row inconsistent.
+// These tests drive the delegate against a data layer whose derived tracking VIEWs are served off
+// in-memory base stores (`withTrackingViews`, exactly as the feature/PR domain tests) plus a REAL
+// SQLite `source()` so the shared primitive's absent-safe projection feed has a handle to write. They
+// pin the delegate's OWN additions: it resolves the record type across every engine-backed binding,
+// 404s a key that maps to none, and reports `reconciled` off the record's derived terminal edge.
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only in-memory table over dynamic row shapes.
+function memTable(rows: any[], key: string) {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only predicate over dynamic row shapes.
+  const matches = (r: any, q: any) => Object.entries(q).every(([f, v]) => r[f] === v);
+  return {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    find: (q: any = {}) => Promise.resolve(rows.filter((r) => matches(r, q))),
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    findOne: (q: any = {}) => Promise.resolve(rows.find((r) => matches(r, q)) ?? null),
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+  };
+}
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only store map over dynamic row shapes.
+function makeRecordApp(
+  stores: Record<string, { rows: any[]; key: string }>,
+  opts: FakeEngineOpts = {},
+): { app: AppApi; cancelCalls: string[] } {
+  const cancelCalls: string[] = [];
+  const engine = {
+    async cancelInstance({ processInstanceKey }: { processInstanceKey: string }) {
+      cancelCalls.push(processInstanceKey);
+      if (opts.cancelThrows) throw new Error("engine refused");
+    },
+    async searchProcessInstances() {
+      return opts.readBackState ? [{ state: opts.readBackState }] : [];
+    },
+  };
+  const bb = memBlackboardSource();
+  const data = {
+    hasDefaultSource: () => true,
+    source: bb.source,
+    table: withTrackingViews((name: string, key = "id") =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    ),
+  };
+  const app = { engine, data, log: noopLog() } as unknown as AppApi;
+  return { app, cancelCalls };
+}
+
+test("a key that maps to NO tracked record → 404 no-op and never touches the engine", async () => {
+  // The record-type resolver finds no binding row for this key: a clean 404, NOT a silent
+  // reconciled:0 success — and we never terminate an instance we don't track.
+  const { app, cancelCalls } = makeRecordApp({ feature_runs: { rows: [], key: "feature_key" } });
+  const res = await call(app, { processInstanceKey: "does-not-exist" });
+  assertEquals(res.status, 404);
+  assertEquals(res.body.ok, false);
+  assertEquals(res.body.state, "gone");
+  assertEquals(res.body.reconciled, 0);
+  assert(typeof res.body.error === "string" && res.body.error.length > 0, "carries a reason");
+  assertEquals(cancelCalls.length, 0, "an untracked key never reaches the engine");
+});
+
+test("a feature-run key whose derived record is terminal → 200 ok reconciled:1 (resubmittable)", async () => {
+  // The live repro: the engine instance is already TERMINATED, so its `feature_runs` row derives to
+  // `abandoned` (base `status` frozen at its last transient — the ADR-0065 divergence, seeded here).
+  // The shared primitive writes nothing new (already terminal), yet the delegate must report the
+  // record's REAL terminal state, not the projection-write delta of 0.
+  const { app, cancelCalls } = makeRecordApp(
+    {
+      feature_runs: {
+        rows: [
+          {
+            feature_key: "Magikcraft/nano-bpm#1099",
+            process_key: "5654",
+            status: "running",
+            derived_status: "abandoned",
+          },
+        ],
+        key: "feature_key",
+      },
+    },
+    { cancelThrows: true, readBackState: "TERMINATED" },
+  );
+  const res = await call(app, { processInstanceKey: "5654" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.reconciled, 1, "the lagging feature_runs record is reported reconciled");
+  assertEquals(cancelCalls, ["5654"], "the door still issued the idempotent engine cancel");
+});
+
+test("a feature-run key committed-cancelled whose record went terminal → 200 ok reconciled:1", async () => {
+  const { app } = makeRecordApp(
+    {
+      feature_runs: {
+        rows: [{ feature_key: "o/r#7", process_key: "900", status: "running", derived_status: "abandoned" }],
+        key: "feature_key",
+      },
+    },
+    { readBackState: "TERMINATED" },
+  );
+  const res = await call(app, { processInstanceKey: "900" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.reconciled, 1);
+});
+
+test("engine terminates but the record stays ACTIVE → 502 ok:false (not an unqualified success)", async () => {
+  // A resolved record whose derived edge did NOT leave `activeStatuses` (e.g. a projection write that
+  // failed) must not be reported as a clean cancel: reconciled:0 and a non-ok 502.
+  const { app } = makeRecordApp(
+    {
+      feature_runs: {
+        // No seeded derived_status ⇒ the VIEW folds `derived_status := status` = "running" (still active).
+        rows: [{ feature_key: "o/r#8", process_key: "901", status: "running" }],
+        key: "feature_key",
+      },
+    },
+    { readBackState: "TERMINATED" },
+  );
+  const res = await call(app, { processInstanceKey: "901" });
+  assertEquals(res.status, 502, "a terminated instance whose record didn't reconcile is not ok:true");
+  assertEquals(res.body.ok, false);
+  assertEquals(res.body.reconciled, 0);
+  assert(typeof res.body.error === "string" && res.body.error.length > 0, "explains the un-reconciled record");
+});
+
+test("record routing also covers PR/plan aggregates (a resolved pull_requests key reconciles)", async () => {
+  const { app } = makeRecordApp(
+    {
+      pull_requests: {
+        rows: [{ pr_key: "o/r#3", process_key: "300", status: "converging", derived_status: "abandoned" }],
+        key: "pr_key",
+      },
+    },
+    { readBackState: "TERMINATED" },
+  );
+  const res = await call(app, { processInstanceKey: "300" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(res.body.reconciled, 1);
+});

package/operations/cancelInstance.ts

@@ -16,13 +16,29 @@
 // bindings come from the app's single accessor (`engineBackedBindings`), so the set can never drift
 // from the reconciler's registry.
 //
+// Record-type routing + a TRUTHFUL result (issue #705). #667 shipped this door reconciling the
+// pull_requests / plans aggregates, but a `processInstanceKey` belonging to a FEATURE RUN reported
+// `reconciled:0` and left the `feature_runs` row inconsistent — the run stayed wedged and resubmit
+// returned a green "Done". The reconcile itself is binding-agnostic (the shared primitive records the
+// terminal fact into `urban_instance_state`, and EVERY binding's derived view — feature_runs included
+// — folds it), so the gap was in what the door RESOLVED and REPORTED:
+//   - It resolves the record type from the key across ALL engine-backed bindings
+//     (`resolveTrackedInstance`) and requires a hit: a key that maps to NO tracked record is a clean
+//     404 no-op, not a silent `reconciled:0` success (and we never terminate an instance we don't
+//     track).
+//   - `reconciled` reflects the REAL record transition — whether the resolved record's ADR-0065
+//     `derived_status` has left its `activeStatuses` (become terminal) — NOT the primitive's
+//     projection-write delta, which reports 0 for an ALREADY-terminated instance whose record is in
+//     fact (now) terminal. So the `reconciled:0`-on-already-TERMINATED case returns a flipped record.
+//   - Terminating a run whose record could NOT be reconciled is not an unqualified `ok:true`.
+//
 // The runtime validates the body against openapi.yaml (`processInstanceKey` required); the optional
 // shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`): as a MUTATING
 // door, when NANO_PR_WEBHOOK_SECRET is set callers must present it via the x-hook-secret header —
 // mirroring `reconcileEngineState`/`agentCompleteEscalation`.
 
 import { cancelInstanceReconciling } from "@nanobpm/urban";
-import { engineBackedBindings } from "../app/instanceTracking.ts";
+import { engineBackedBindings, resolveTrackedInstance } from "../app/instanceTracking.ts";
 import { envVar } from "../app/version.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
@@ -48,33 +64,103 @@ export default defineOperation("cancelInstance", async ({ req, body }, app) => {
     return { status: 400, body: { error: "processInstanceKey is required and must be a string" } };
   }
 
+  // Resolve which tracked aggregate (PR / plan / feature run / …) this key belongs to BEFORE we touch
+  // the engine (issue #705). A key that maps to NO tracked record is a clean 404 no-op — we neither
+  // cancel an instance we don't track nor report a silent `reconciled:0` success. Only meaningful with
+  // a readable default source; without one (e.g. a `mount.data:false` deployment) there is no derived
+  // view to resolve against, so fall through to the primitive-only path below (behaviour unchanged).
+  const canResolveRecord = app.data.hasDefaultSource();
+  if (canResolveRecord) {
+    const record = await resolveTrackedInstance(app.data, processInstanceKey);
+    if (!record) {
+      app.log.warn("cancelInstance: no tracked record for processInstanceKey — no-op", {
+        processInstanceKey,
+      });
+      return {
+        status: 404,
+        body: {
+          ok: false,
+          processInstanceKey,
+          // No tracked record owns this key, so from the door's aggregates the run is `gone`. Carry a
+          // `state` so the body is a full CancelInstanceResult (uniform shape for clients/projection).
+          state: "gone",
+          reconciled: 0,
+          error: "no tracked record for processInstanceKey",
+        },
+      };
+    }
+  }
+
   const result = await cancelInstanceReconciling(
     app,
     [...engineBackedBindings()],
     processInstanceKey,
   );
+
+  // A !ok result means the engine did NOT stop the instance (the cancel was not committed); the run
+  // may still be live, so surface 502 — the same non-committed-cancel signal the built-in page
+  // action returns. Report it before we assert anything about the record (nothing was reconciled).
+  if (!result.ok) {
+    app.log.warn("cancelInstance: engine did not confirm termination", {
+      processInstanceKey,
+      state: result.state,
+      error: result.error,
+    });
+    return {
+      status: 502,
+      body: {
+        ok: false,
+        processInstanceKey: result.processInstanceKey,
+        state: result.state,
+        reconciled: 0,
+        ...(result.error !== undefined ? { error: result.error } : {}),
+      },
+    };
+  }
+
+  // The engine confirmed termination. Report a TRUTHFUL `reconciled` off the RECORD's derived terminal
+  // edge, not the primitive's projection-write delta: an already-TERMINATED instance re-fed on this
+  // pass writes nothing new (`result.reconciled === 0`) yet its record IS (now) terminal, so the
+  // 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.
+  let reconciled = result.reconciled;
+  let recordReconciled = true;
+  if (canResolveRecord) {
+    const after = await resolveTrackedInstance(app.data, processInstanceKey);
+    recordReconciled = !!after && !after.active;
+    reconciled = recordReconciled ? 1 : 0;
+  }
+
   const responseBody = {
-    ok: result.ok,
+    ok: result.ok && recordReconciled,
     processInstanceKey: result.processInstanceKey,
     state: result.state,
-    reconciled: result.reconciled,
+    reconciled,
     ...(result.error !== undefined ? { error: result.error } : {}),
   };
-  if (result.ok) {
-    app.log.info("cancelInstance: instance terminated", {
+
+  // The engine stopped the instance but the record did not settle to a terminal edge — terminating a
+  // run whose record could not be reconciled is not an unqualified `ok:true` (issue #705). Surface it
+  // as a 502 so the caller does not read a wedged record as "done".
+  if (!recordReconciled) {
+    app.log.warn("cancelInstance: instance terminated but record not reconciled", {
       processInstanceKey,
       state: result.state,
-      reconciled: result.reconciled,
     });
-    return { status: 200, body: responseBody };
+    return {
+      status: 502,
+      body: {
+        ...responseBody,
+        error: responseBody.error ?? "instance terminated but tracked record was not reconciled",
+      },
+    };
   }
-  // A !ok result means the engine did NOT stop the instance (the cancel was not committed); the run
-  // may still be live, so surface 502 — the same non-committed-cancel signal the built-in page
-  // action returns.
-  app.log.warn("cancelInstance: engine did not confirm termination", {
+
+  app.log.info("cancelInstance: instance terminated", {
     processInstanceKey,
     state: result.state,
-    error: result.error,
+    reconciled,
   });
-  return { status: 502, body: responseBody };
+  return { status: 200, body: responseBody };
 });

package/package.json

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