@nanobpm/nano-workforce 0.176.0 → 0.177.0

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

@@ -0,0 +1,148 @@
+// nano-workforce — the agentic-channel `claim` / `release` job-ownership family (#713).
+//
+// H0 (#143) seam plug-in: ONE new file under `app/agentic/families/`, discovered by the loader's
+// `*.family.ts` convention and mounted by the seam — it never edits `main.ts`, `drainAndExit`, or any
+// shared boot line. It owns the `claim` (wire code 8) and `release` (wire code 9) message families —
+// the explicit job-ownership frames nano-ide#542 appended to `@nanobpm/agentic` — attaching each
+// handler through the hub's `registerFamilyHandler` seam (one family, one owning module), never a
+// shared dispatch switch.
+//
+// What it gives the fleet: a first-class {@link ClaimRegistry} (`instance → set<jobKey>`) that becomes
+// the AUTHORITATIVE source the supply snapshot reads for `jobKeys` — replacing the fragile
+// relay-derived visibility. Each frame carries its OWNING `instance` EXPLICITLY, so attribution reads
+// the frame, NOT the connection id (`conn.id`); that is what lets one per-host supervisor multiplex N
+// distinct workers' ownership over a single connection. On a reconnect the supervisor re-`register`s
+// every worker and re-`claim`s every active jobKey, and the (idempotent) claim handler rebuilds the
+// registry from that resync.
+//
+// Liveness: a worker holding a claim reads "working" even with ZERO transcript — visibility no longer
+// depends on terminal bytes landing/correlating. A bounded-memory maintenance tick reconciles the
+// claim registry against the live presence set so a departed supervisor's claims are reclaimed (the
+// `release` frame is the primary clear; this is the safety net for an unclean drop).
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched; ADVISORY — the registry is a read-only visibility source and NEVER gates a BPMN
+// sequence flow.
+import type { HubConnection } from "@nanobpm/agentic/channel";
+import { type Frame, validatePayload } from "@nanobpm/agentic/protocol";
+import { ClaimRegistry, setCurrentClaimRegistry } from "../claim-registry.ts";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+import { currentPresenceRegistry } from "./presence.family.ts";
+
+/** The message-family names this module owns (the two ownership frames). */
+export const CLAIM_FAMILY = "claim";
+export const RELEASE_FAMILY = "release";
+
+/** The reconcile tick runs at a third of the presence TTL — matching the presence-maintenance cadence. */
+const SWEEP_DIVISOR = 3;
+/** Fallback reconcile cadence when no presence registry is mounted to source a TTL. */
+const DEFAULT_RECONCILE_MS = 10_000;
+
+/** Read a string property from an unknown frame payload, or undefined when absent / non-string. */
+function readString(value: unknown, key: string): string | undefined {
+  if (!value || typeof value !== "object") return undefined;
+  if (!Object.hasOwn(value, key)) return undefined;
+  const field = Object.getOwnPropertyDescriptor(value, key)?.value;
+  return typeof field === "string" ? field : undefined;
+}
+
+interface MountState {
+  readonly registry: ClaimRegistry;
+  timer: ReturnType<typeof setTimeout> | undefined;
+  stopped: boolean;
+}
+
+let state: MountState | undefined;
+
+/**
+ * The `claim` / `release` family module. `mount` installs a fresh {@link ClaimRegistry} as the
+ * process-wide singleton, attaches the two frame handlers via the S1 seam, and starts ONE bounded
+ * reconcile tick. `teardown` stops the tick, detaches nothing (the hub owns handler lifetime for the
+ * remount-guarded test path) and clears the singleton.
+ */
+export const family: AgenticFamily = {
+  name: CLAIM_FAMILY,
+
+  mount(ctx: AgenticContext): void {
+    const registry = new ClaimRegistry();
+    setCurrentClaimRegistry(registry);
+
+    // `claim` opens the ownership window; `release` closes it. Attribution reads the frame's EXPLICIT
+    // `instance` — never `conn.id` — so one connection can carry many instances' ownership frames. A
+    // malformed payload is rejected before it touches the registry (advisory: logged, connection
+    // kept). Both mutations are idempotent, matching the wire contract.
+    ctx.hub.registerFamilyHandler(CLAIM_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(CLAIM_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic claim: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.claim(instance, jobKey);
+    });
+
+    ctx.hub.registerFamilyHandler(RELEASE_FAMILY, (frame: Frame, _conn: HubConnection) => {
+      const result = validatePayload(RELEASE_FAMILY, frame.payload);
+      if (!result.ok) {
+        ctx.log.warn("agentic release: malformed payload", { errors: result.errors.map((e) => e.code) });
+        return;
+      }
+      const instance = readString(frame.payload, "instance");
+      const jobKey = readString(frame.payload, "jobKey");
+      if (!instance || !jobKey) return;
+      registry.release(instance, jobKey);
+    });
+
+    // Bounded-memory reconcile: drop claims whose owning instance no longer has a presence row (a
+    // dropped supervisor / aged-out worker). BOTH the drop-set AND the cadence are recomputed per
+    // tick from the live presence registry via a self-rescheduling timer, so the reconcile is truly
+    // independent of family mount order: whether presence mounts before or after this family, once it
+    // is present each tick reclaims absent instances' claims AND adjusts its cadence to the real TTL
+    // (a fixed-at-mount interval would stay pinned to the fallback cadence when claim mounts first).
+    // Advisory — a fault is logged, never thrown, and the tick never keeps the process alive on its
+    // own.
+    const reconcileMs = (): number => {
+      const presenceTtl = currentPresenceRegistry()?.ttlMs;
+      return Math.max(1, Math.floor((presenceTtl ?? DEFAULT_RECONCILE_MS) / SWEEP_DIVISOR));
+    };
+    const schedule = (): void => {
+      if (!state || state.stopped) return;
+      const timer = setTimeout(tick, reconcileMs());
+      timer.unref?.();
+      state.timer = timer;
+    };
+    const tick = () => {
+      try {
+        const presence = currentPresenceRegistry();
+        if (presence) {
+          const present = new Set(presence.registeredWorkers().map((w) => w.instance));
+          const released = registry.reconcile(present);
+          if (released.length > 0) {
+            ctx.log.info("agentic claim reconcile released absent instances", { released: released.length });
+          }
+        }
+        // else: no presence source → keep claims until one mounts (resync repopulates)
+      } catch (err) {
+        ctx.log.warn("agentic claim reconcile failed", { err: String(err) });
+      }
+      schedule();
+    };
+
+    state = { registry, timer: undefined, stopped: false };
+    schedule();
+    ctx.log.info("agentic claim family mounted", { families: [CLAIM_FAMILY, RELEASE_FAMILY] });
+  },
+
+  teardown(): void {
+    if (state) {
+      state.stopped = true;
+      if (state.timer !== undefined) clearTimeout(state.timer);
+    }
+    state = undefined;
+    setCurrentClaimRegistry(undefined);
+  },
+};
+
+export default family;

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/operations/getAgenticSupply.test.ts

@@ -12,7 +12,9 @@ import { encodeFrame, type Frame } from "@nanobpm/agentic/protocol";
 import type { SqliteDb } from "@nanobpm/agentic/presence";
 import type { AppApi, DataLayer } from "@nanobpm/urban";
 import { assert, assertEquals } from "#test-assert";
+import { currentClaimRegistry } from "../app/agentic/claim-registry.ts";
 import { currentCorrelation } from "../app/agentic/correlation.ts";
+import { family as claimFamily } from "../app/agentic/families/claim.family.ts";
 import { family as correlationFamily } from "../app/agentic/families/correlation.family.ts";
 import { family } from "../app/agentic/families/presence.family.ts";
 import type { AgenticContext } from "../app/agentic/registry.ts";
@@ -154,7 +156,32 @@ test("shared-secret guard rejects a missing secret when configured", async () =>
   }
 });
 
-test("H6: with the correlation family mounted, jobKeys populate, stream repoints, and correlations are reported", async () => {
+test("#713: a claim populates jobKeys and repoints the drill stream with ZERO transcript (claim is the visibility source)", async () => {
+  const hub = await mountPresence(memSqlite());
+  const ctx: AgenticContext = { hub, registry: hub.registry, transport: undefined as never, data: undefined, log: noopLog() };
+  claimFamily.mount(ctx);
+  const claims = currentClaimRegistry();
+  assert(claims !== undefined, "the claim family installs the singleton");
+  // An explicit claim — no relay produce frame, no correlation link, zero transcript.
+  claims.claim("wk-a", "8420");
+  try {
+    const res = (await handler(input(), app)) as {
+      status: number;
+      body: { workers: Array<Record<string, unknown>>; correlations: unknown[] };
+    };
+    assertEquals(res.status, 200);
+    const w = res.body.workers[0];
+    assertEquals(w.jobKeys, ["8420"], "the claim registry feeds the jobKeys seam");
+    assertEquals(w.stream, "job:8420", "the drill stream repoints at the claimed job, keyed by the claim");
+    assertEquals(res.body.correlations.length, 0, "no correlation context until a terminal lands (drill-in only)");
+  } finally {
+    claimFamily.teardown?.();
+    family.teardown?.();
+    await hub.close();
+  }
+});
+
+test("#713: the correlation registry is demoted to drill-in context — a link alone no longer feeds jobKeys", async () => {
   const hub = await mountPresence(memSqlite());
   correlationFamily.mount({
     hub,
@@ -165,6 +192,7 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
   });
   const correlation = currentCorrelation();
   assert(correlation !== undefined, "the correlation family installs the singleton");
+  // A correlation link (drill-in context) WITHOUT a claim: visibility must NOT light up from it.
   correlation.link("wk-a", "6494", { processInstanceKey: "4612", bpmnProcessId: "plan-fanout", elementId: "implement-task", planKey: "o/r#142" });
   try {
     const res = (await handler(input(), app)) as {
@@ -176,8 +204,9 @@ test("H6: with the correlation family mounted, jobKeys populate, stream repoints
     };
     assertEquals(res.status, 200);
     const w = res.body.workers[0];
-    assertEquals(w.jobKeys, ["6494"], "the correlation registry feeds the jobKeys seam");
-    assertEquals(w.stream, "job:6494", "the drill stream repoints at the live job's stream");
+    assertEquals(w.jobKeys, [], "correlation alone no longer feeds jobKeys (relay demoted)");
+    assertEquals(w.stream, "wk-a", "the drill stream stays instance-keyed without a claim");
+    // The correlation context is still reported for drill-in.
     assertEquals(res.body.correlations.length, 1);
     const c = res.body.correlations[0];
     assertEquals(c.jobKey, "6494");