@nanobpm/nano-workforce 0.175.2 → 0.176.1

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [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
+
+* **agentic:** flush durable transcript on a worker phase:close event (fixes truncated tails) ([#711](https://github.com/nanobpm/nano-workforce/issues/711)) ([e02ff9b](https://github.com/nanobpm/nano-workforce/commit/e02ff9b4f8c2b7452dc40b0b8532736c5d418cc0)), closes [#710](https://github.com/nanobpm/nano-workforce/issues/710)
+
 ## [0.175.2](https://github.com/nanobpm/nano-workforce/compare/v0.175.1...v0.175.2) (2026-09-02)
 
 ### Bug Fixes

package/app/agentic/families/relay.family.test.ts

@@ -16,7 +16,13 @@ import { fileURLToPath } from "node:url";
 import { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY } from "@nanobpm/agentic/relay";
-import { encodeTranscriptEvent, type SqliteDb, TRANSCRIPT_SCHEMA_SQL } from "@nanobpm/agentic/transcript";
+import {
+  encodeTranscriptEvent,
+  type SqliteDb,
+  TRANSCRIPT_EVENT_MARKER,
+  TRANSCRIPT_EVENT_VERSION,
+  TRANSCRIPT_SCHEMA_SQL,
+} from "@nanobpm/agentic/transcript";
 import { assert, assertEquals, assertThrows } from "#test-assert";
 import { noopLog } from "../../../test/log.ts";
 import { CorrelationRegistry, jobStream } from "../correlation.ts";
@@ -551,6 +557,21 @@ test("#544 element-instance enrichment: an unresolved job (never parked) leaves
 const lifecycle = (stream: string, incarnation: number, phase: "open" | "completed" | "exited"): Frame =>
   produce(stream, incarnation, encodeTranscriptEvent({ kind: "lifecycle", phase, offset: 0 }));
 
+/**
+ * A `produce` frame carrying the harness's job-end `phase:"close"` transcript lifecycle marker
+ * (#710 / jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:"open"` RELAY_OPEN_CHUNK the
+ * harness emits at relay-session open. The typed `encodeTranscriptEvent` cannot express the `close`
+ * phase (the agentic `LifecycleEvent` union is `open|completed|exited`), so the on-wire envelope is
+ * built through the SAME marker/version constants the encoder stamps — mirroring exactly what the
+ * harness's untyped `encodeTranscriptEvent({ kind: "lifecycle", phase: "close" })` puts on the wire,
+ * without a forked wire shape. */
+const closeMarker = JSON.stringify({
+  [TRANSCRIPT_EVENT_MARKER]: TRANSCRIPT_EVENT_VERSION,
+  kind: "lifecycle",
+  phase: "close",
+});
+const close = (stream: string, incarnation: number): Frame => produce(stream, incarnation, closeMarker);
+
 test("#661 primary release: a terminal lifecycle event clears an idle-but-connected worker's finished job", () => {
   const registry = new ConnectionRegistry();
   const correlation = new CorrelationRegistry();
@@ -607,6 +628,79 @@ test("#661 primary release: an `exited` lifecycle also releases; a non-terminal
   service.teardown();
 });
 
+test("#710 close release: a job-end `phase:close` marker flushes the durable transcript with ALL bytes (no truncated tail)", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  // The worker relays N job frames on a live connection → linked as active. It then goes idle after the
+  // job WITHOUT a supersede (no next job) and WITHOUT a disconnect (the channel persists across jobs),
+  // so the ONLY job-end signal is the harness's drained `phase:close` marker.
+  const N = 4;
+  for (let i = 0; i < N; i++) hub.handler?.(produce(jobStream("k1"), 1, `job-1 line ${i}`), p.conn);
+  assertEquals(correlation.jobKeysFor("worker-A"), ["k1"], "the job is active while it runs");
+  assertEquals(service.transcriptOf(jobStream("k1")), undefined, "not flushed while the job runs");
+
+  // The job completes: the harness drains its outbound relay buffer and emits `phase:close` on the SAME
+  // live connection, then goes idle. Before #710 this was NOT a flush trigger — the durable transcript
+  // was snapshotted late (or not at all) by a later supersede/disconnect, truncating the tail. Now the
+  // close event flushes it deterministically at job-completion time.
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+
+  assertEquals(correlation.jobKeysFor("worker-A"), [], "the finished job is released on the close marker");
+  assertEquals(correlation.count(), 0, "no phantom active job after close");
+
+  const meta = service.transcriptOf(jobStream("k1"));
+  assertEquals(meta?.status, "completed", "the job becomes a completed past session at close time");
+  // ALL N produced frames PLUS the close marker itself are in the durable transcript — no truncated
+  // tail (the close event rides the ring append before the release, like the #661 terminal path).
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    N + 1,
+    "every relayed byte (and the close marker) is flushed — the tail is not truncated",
+  );
+  service.teardown();
+});
+
+test("#710 idempotent: a close then a duplicate close then a producer disconnect neither double-flushes nor throws", () => {
+  const registry = new ConnectionRegistry();
+  const correlation = new CorrelationRegistry();
+  const byConnection = new Map([["prod", "worker-A"]]);
+  const { service, hub } = mkCorrelatedService(registry, memoryDb(), correlation, byConnection);
+  const p = connect("prod", registry);
+
+  hub.handler?.(produce(jobStream("k1"), 1, "job-1 line"), p.conn);
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+  const afterClose = service.reattach(jobStream("k1"), 0)?.entries.length;
+  assertEquals(service.transcriptOf(jobStream("k1"))?.status, "completed", "flushed on the first close");
+  assertEquals(correlation.count(), 0, "correlation released on the first close");
+
+  // A late DUPLICATE close (a harness retry, or a redelivered frame) is a no-op — the completed stream
+  // is terminal, so it neither re-flushes nor throws.
+  hub.handler?.(close(jobStream("k1"), 1), p.conn);
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    afterClose,
+    "a duplicate close does not append or re-flush",
+  );
+
+  // The producer later disconnects (the belt-and-suspenders fallback). #reconcile runs on the next
+  // inbound frame; the already-completed stream is skipped, so the fallback neither double-flushes nor
+  // throws — the additive close trigger composes cleanly with the disconnect fallback.
+  registry.remove("prod");
+  const q = connect("other", registry);
+  hub.handler?.(produce(jobStream("k2"), 1, "unrelated"), q.conn);
+  assertEquals(
+    service.reattach(jobStream("k1"), 0)?.entries.length,
+    afterClose,
+    "the disconnect fallback does not re-flush the already-closed stream",
+  );
+  assertEquals(service.transcriptOf(jobStream("k1"))?.status, "completed", "still exactly one completed past session");
+  service.teardown();
+});
+
 test("#661 no-regression: an ordinary (non-lifecycle) chunk never clears a genuinely active job", () => {
   const registry = new ConnectionRegistry();
   const correlation = new CorrelationRegistry();

package/app/agentic/families/relay.family.ts

@@ -24,6 +24,8 @@ import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
 import type { Frame } from "@nanobpm/agentic/protocol";
 import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
 import {
+  CORE_TRANSCRIPT_VOCAB,
+  mergeTranscriptVocab,
   parseTranscriptEvent,
   type SqliteDb,
   type TranscriptLifecycle,
@@ -32,6 +34,7 @@ import {
   TranscriptStore,
   type TranscriptStoreOptions,
   type TranscriptStream,
+  type TranscriptVocab,
 } from "@nanobpm/agentic/transcript";
 import type { Logger } from "@nanobpm/urban";
 import { currentCorrelation, type JobContext, type JobCorrelation, jobKeyOfStream } from "../correlation.ts";
@@ -128,17 +131,50 @@ function readProp(value: unknown, key: string): unknown {
   return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
 }
 
+/**
+ * The harness's job-end lifecycle phase (#710 / jwulf/c8ctl-plugin-nano#150): the closing twin of the
+ * `phase:"open"` `RELAY_OPEN_CHUNK` the harness emits at relay-session open. The harness emits it —
+ * through agentic's own `encodeTranscriptEvent`, never hand-rolled — right before `job.complete`/
+ * `job.fail`, once it has DRAINED its outbound relay buffer, so it is the deterministic "this job's
+ * bytes are all here, it is done" signal that supersede/disconnect only ever approximated.
+ */
+const HARNESS_CLOSE_PHASE = "close";
+
+/**
+ * The relay family's terminal-detection vocabulary: the ONE canonical transcript vocab, additively
+ * EXTENDED (via the sanctioned {@link mergeTranscriptVocab} extension point, never a forked parser) to
+ * ALSO classify the harness's job-end `phase:"close"` marker (#710). The agentic `LifecycleEvent`
+ * contract's phases are `open|completed|exited` — `close` is a fourth, job-scoped termination marker
+ * agentic 0.10.0 does not yet know, so the core `lifecycle` decoder drops it to a raw `stream-chunk`.
+ * This override recognizes it and maps it onto the contract's terminal `completed` phase, so
+ * {@link parseTranscriptEvent} classifies a close envelope as a terminal lifecycle WITHOUT a second
+ * wire shape. It is scoped to {@link isTerminalLifecycleChunk} (the correlation-release detector); the
+ * cockpit derive/read fold keeps using the CORE vocab, so the close chunk stays byte-faithful in the
+ * durable transcript and this remap never leaks into the derived view.
+ */
+const RELAY_TERMINAL_VOCAB: TranscriptVocab = mergeTranscriptVocab(CORE_TRANSCRIPT_VOCAB, {
+  lifecycle: (body, offset) => {
+    const phase = typeof body.phase === "string" ? body.phase : undefined;
+    if (phase === "open" || phase === "completed" || phase === "exited") return { kind: "lifecycle", offset, phase };
+    if (phase === HARNESS_CLOSE_PHASE) return { kind: "lifecycle", offset, phase: "completed" };
+    return undefined;
+  },
+});
+
 /**
  * Decode a single relay chunk through the ONE canonical transcript parser and report whether it is a
- * TERMINAL `lifecycle` event (`phase` `completed`/`exited`) — the authoritative "job end" signal a
- * clean agent run emits on its transcript stream (#661). Anything else — raw terminal bytes, a
- * non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is not terminal.
- * Reusing {@link parseTranscriptEvent} keeps transcript-vocab knowledge out of the content-agnostic
- * relay ring and off any forked decoder (Derivation Over Duplication): the ring still sees opaque
- * bytes; only this narrow seam classifies them.
+ * TERMINAL `lifecycle` event — the authoritative "job end" signal that flushes the durable transcript
+ * and releases correlation. Two shapes are terminal: the agent run's own `phase` `completed`/`exited`
+ * (#661), and the harness's drained job-end `phase:"close"` marker (#710), which
+ * {@link RELAY_TERMINAL_VOCAB} decodes onto the contract's `completed` phase. Anything else — raw
+ * terminal bytes, a non-envelope JSON value, a `phase: "open"` lifecycle, any other event kind — is
+ * not terminal. Reusing {@link parseTranscriptEvent} (with the additively-extended vocab) keeps
+ * transcript-vocab knowledge out of the content-agnostic relay ring and off any forked decoder
+ * (Derivation Over Duplication): the ring still sees opaque bytes; only this narrow seam classifies
+ * them.
  */
 function isTerminalLifecycleChunk(chunk: string): boolean {
-  const event = parseTranscriptEvent({ offset: 0, chunk });
+  const event = parseTranscriptEvent({ offset: 0, chunk }, RELAY_TERMINAL_VOCAB);
   return event.kind === "lifecycle" && (event.phase === "completed" || event.phase === "exited");
 }
 
@@ -516,8 +552,8 @@ export class RelayTranscriptService {
   }
 
   /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, delegate, then
-   * release on a terminal `lifecycle` event (#661 — AFTER the hub appended the chunk, so the terminal
-   * event itself is captured in the flushed transcript). */
+   * release on a terminal `lifecycle` event (#661/#710 — AFTER the hub appended the chunk, so the
+   * terminal event itself is captured in the flushed transcript). */
   #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
     this.#reconcile();
     this.#observe(frame, conn);
@@ -526,17 +562,23 @@ export class RelayTranscriptService {
   }
 
   /**
-   * Primary job-end release (#661): when a `produce` frame carries the terminal `lifecycle` event
-   * (`phase` `completed`/`exited`), complete its stream so the worker's job⇄instance correlation is
-   * released the moment the job ends — even though the worker's relay connection stays open across jobs
-   * (the disconnect/supersede release paths miss that idle-after-last-job tail, so an idle worker's
-   * finished job would otherwise linger as a phantom active job on its supply row). Runs AFTER the hub
-   * appends the chunk to the ring, so the terminal event is part of the flushed transcript. A narrow,
-   * self-contained decode at the correlation seam that reuses the ONE canonical
-   * {@link parseTranscriptEvent} — the content-agnostic relay ring keeps treating chunks as opaque
-   * bytes, and no transcript-vocab knowledge is forked into it. Non-terminal chunks (raw bytes, a
-   * `phase: "open"` lifecycle, any other event kind) never complete a live stream, so a genuinely
-   * active job is never cleared. Advisory — never throws into the frame handler.
+   * Primary job-end release (#661, #710): when a `produce` frame carries a terminal `lifecycle` event —
+   * the agent run's own `phase` `completed`/`exited` (#661), OR the harness's drained job-end
+   * `phase:"close"` marker (#710) — complete its stream so the worker's job⇄instance correlation is
+   * released, and the durable "past session" transcript is flushed, the moment the job ends. This runs
+   * even though the worker's relay connection stays open across jobs (the disconnect/supersede release
+   * paths miss that idle-after-last-job tail, so an idle worker's finished job would otherwise linger as
+   * a phantom active job on its supply row, and its transcript would be snapshotted late → truncated
+   * tail). The `close` trigger is ADDITIVE — supersede + disconnect remain as belt-and-suspenders
+   * fallbacks for a harness that predates the close event or a crash that never sends one — and the
+   * `state.completed` guard below makes a close-then-later-disconnect (or a duplicate close) an
+   * idempotent no-op. Runs AFTER the hub appends the chunk to the ring, so the terminal event is part
+   * of the flushed transcript. A narrow, self-contained decode at the correlation seam that reuses the
+   * ONE canonical {@link parseTranscriptEvent} ({@link isTerminalLifecycleChunk}) — the content-agnostic
+   * relay ring keeps treating chunks as opaque bytes, and no transcript-vocab knowledge is forked into
+   * it. Non-terminal chunks (raw bytes, a `phase: "open"` lifecycle, any other event kind) never
+   * complete a live stream, so a genuinely active job is never cleared. Advisory — never throws into
+   * the frame handler.
    */
   #observeTerminalLifecycle(frame: Frame): void {
     if (readProp(frame.payload, "op") !== "produce") return;

package/app/contracts.ts

@@ -463,6 +463,14 @@ export const WIRE_CONTRACTS = {
     shape:
       '{ nwfTranscriptEvent: 1, kind: "permission", phase: "request", callId: string, policy: "escalate"|"yolo", options: [{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }, ...Array<{ optionId: string, name: string, kind: "allow-once"|"allow-always"|"reject-once"|"reject-always" }>], toolName?: string, title?: string, reason?: string } | { nwfTranscriptEvent: 1, kind: "permission", phase: "resolution", callId: string, optionId: string, allowed: boolean, by?: "operator"|"auto" }',
   },
+  "transcript.lifecycleClose": {
+    category: "wire",
+    name: "transcript.lifecycleClose",
+    owner: "app/agentic/families/relay.family.ts",
+    semantics:
+      "The harness's job-end `phase:\"close\"` transcript `lifecycle` event (issue #710, harness half jwulf/c8ctl-plugin-nano#150) — the closing twin of the `phase:\"open\"` RELAY_OPEN_CHUNK the harness emits at relay-session open. The harness emits it on the `job:<jobKey>` relay stream through agentic's own `encodeTranscriptEvent` (never hand-rolled), right before `job.complete`/`job.fail` and AFTER draining its outbound relay buffer, so it is the deterministic \"all this job's bytes are here, it is done\" signal. The app recognizes it in `isTerminalLifecycleChunk` (relay.family.ts) to `completeStream()` — flush the durable past-session transcript and release job⇄instance correlation — at job-completion time, fixing the truncated-tail defect where the flush waited for a supersede/disconnect. `close` is NOT a core agentic `LifecycleEvent` phase (the contract's phases are open|completed|exited); the app decodes it via an ADDITIVE `mergeTranscriptVocab` extension (`RELAY_TERMINAL_VOCAB`) that maps it onto the terminal `completed` phase — never a forked wire shape, and scoped to the relay job-end detector so the cockpit derive (CORE vocab) keeps the close chunk byte-faithful. The `close` trigger is ADDITIVE: supersede + disconnect remain as fallbacks and the `state.completed` guard keeps a close-then-disconnect (or duplicate close) idempotent. Consume this ONE marker — do not re-declare a synonym or a second job-end signal.",
+    shape: '{ nwfTranscriptEvent: 1, kind: "lifecycle", phase: "close" }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {

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.175.2",
+  "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",