@nanobpm/nano-workforce 0.105.0 → 0.106.1

package/scripts/check-migrations.ts

@@ -13,11 +13,23 @@
 // The rule: no two migration files may share a numeric prefix. The pre-existing historical
 // duplicates are forward-only and already applied, so they cannot be renamed — they are
 // grandfathered in GRANDFATHERED_DUPES. Any NEW duplicate prefix fails the build.
+//
+// A second, independent invariant lives here too (issue #357): once a migration has merged to
+// `main` it is IMMUTABLE — never renamed, deleted, or edited. The runtime keys the migration ledger
+// by FILENAME, so renaming a merged migration makes the runner re-apply it against an already-
+// migrated DB and abort boot ("duplicate column"); editing one silently no-ops on every existing
+// install (the ledger already has that name) while diverging fresh installs. `checkImmutability`
+// diffs `db/migrations/` against the merge-base with `origin/main` and fails on any rename, delete,
+// or content change to a file that existed there. It compares against the merge-base (the branch's
+// fork point), NOT `origin/main`'s tip, so a branch that is merely behind main isn't wrongly flagged
+// for migrations added to main after it forked.
+import { execFileSync } from "node:child_process";
 import { readdirSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 
-const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db", "migrations");
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
 
 // Historical collisions that predate this gate. Forward-only + already applied ⇒ cannot be
 // renumbered. New duplicates are NOT allowed here — fix them before merge.
@@ -32,10 +44,112 @@ const MIGRATIONS_DIR = join(dirname(fileURLToPath(import.meta.url)), "..", "db",
 // cannot be renumbered (a rename re-runs `CREATE TABLE`/`ALTER TABLE DROP COLUMN` on migrated DBs and
 // fails). They create three disjoint schema objects, so their relative apply order is irrelevant.
 // Grandfather 049; any NEW duplicate prefix still fails the build.
-const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007", "049"]);
+//
+// 052 is the same story across two PRs: #351 landed `052_worker_durable_resume` and #355 landed
+// `052_plan_conformance`, each the branch-local "next" prefix, colliding silently only once both were
+// on main. Both are already applied forward-only, and — reinforced now by the immutability check
+// below — renumbering a merged migration is itself forbidden (the rename would re-run it and abort
+// boot, issue #357). The two create disjoint tables (`worker_durable_resume`, `plan_conformance`), so
+// apply order is irrelevant. Grandfather 052; any NEW duplicate prefix still fails the build.
+const GRANDFATHERED_DUPES: ReadonlySet<string> = new Set(["004", "005", "006", "007", "049", "052"]);
 
 const PREFIX = /^(\d{3})_[^/]*\.sql$/;
 
+function git(args: string[]): string {
+  return execFileSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+}
+
+/** The commit to treat as "already merged" — the branch's fork point from `origin/main` (fall back to
+ *  local `main`). `null` when no baseline is resolvable (e.g. a shallow clone with no `main`), in
+ *  which case the immutability check is skipped with a warning; CI checks out full history. Override
+ *  with `MIGRATION_BASELINE_REF` (used by the gate's own tests). */
+function resolveBaseline(): string | null {
+  const override = process.env.MIGRATION_BASELINE_REF;
+  const upstreams = override ? [override] : ["origin/main", "main"];
+  for (const ref of upstreams) {
+    try {
+      // An explicit override is used as-is; a branch name is resolved to its merge-base with HEAD so a
+      // branch that is merely behind main isn't blamed for migrations main gained after it forked.
+      if (override) {
+        git(["rev-parse", "--verify", "--quiet", `${ref}^{commit}`]);
+        return ref;
+      }
+      return git(["merge-base", ref, "HEAD"]).trim();
+    } catch {
+      // try the next candidate
+    }
+  }
+  return null;
+}
+
+/** Classify a `git diff --find-renames --name-status <baseline> -- db/migrations` listing into
+ *  immutability violations. Renames (`R`), deletes (`D`), and content edits (`M`) of a merged
+ *  migration are violations; additions (`A`) are allowed. Exported for unit coverage. */
+export function immutabilityErrorsFromDiff(statusOutput: string): string[] {
+  const errors: string[] = [];
+  const name = (p: string): string => p.slice(p.lastIndexOf("/") + 1);
+  for (const line of statusOutput.split("\n")) {
+    if (line.trim() === "") continue;
+    const [status, ...paths] = line.split("\t");
+    if (status.startsWith("R")) {
+      errors.push(
+        `  ${name(paths[0])} -> ${name(paths[1])}: a merged migration was RENAMED. The ledger keys ` +
+          `by filename, so the renamed file re-runs on every existing install and aborts boot. Keep ` +
+          `the original filename; add a NEW migration for further change.`,
+      );
+    } else if (status.startsWith("D")) {
+      errors.push(
+        `  ${name(paths[0])}: a merged migration was DELETED. Forward-only migrations are immutable — ` +
+          `removing one desyncs the ledger from the schema. Leave it in place.`,
+      );
+    } else if (status.startsWith("M")) {
+      errors.push(
+        `  ${name(paths[0])}: a merged migration was EDITED. The ledger already records it, so the ` +
+          `edit silently no-ops on every migrated install while diverging fresh ones. Add a NEW ` +
+          `migration instead of changing a merged one.`,
+      );
+    }
+  }
+  return errors;
+}
+
+/** Fail on any rename, delete, or content change to a migration already present at the baseline — a
+ *  merged migration is immutable (issue #357). Additions are fine. Returns whether the immutability
+ *  gate actually ran (false when it was skipped because no baseline/diff was available), so the
+ *  caller's success message doesn't claim a guarantee the gate never checked. */
+function checkImmutability(errors: string[]): boolean {
+  const baseline = resolveBaseline();
+  if (baseline === null) {
+    console.warn(
+      "check-migrations: WARN — no origin/main baseline resolvable; skipping the immutability check " +
+        "(CI runs it with full history via fetch-depth: 0).",
+    );
+    return false;
+  }
+
+  let statusOutput: string;
+  try {
+    // Diff the baseline tree against the WORKING TREE (staged + unstaged), detecting renames, scoped
+    // to db/migrations. `--find-renames` surfaces a rename as one `R` row instead of a delete+add.
+    statusOutput = git([
+      "diff",
+      "--find-renames",
+      "--name-status",
+      baseline,
+      "--",
+      "db/migrations",
+    ]);
+  } catch {
+    console.warn(
+      `check-migrations: WARN — could not diff migrations against ${baseline}; skipping the immutability check.`,
+    );
+    return false;
+  }
+
+  errors.push(...immutabilityErrorsFromDiff(statusOutput));
+  return true;
+}
+
 function main(): void {
   const files = readdirSync(MIGRATIONS_DIR)
     .filter((f) => f.endsWith(".sql"))
@@ -68,12 +182,20 @@ function main(): void {
     }
   }
 
+  const immutabilityChecked = checkImmutability(errors);
+
   if (errors.length > 0) {
-    console.error(`check-migrations: db/migrations has colliding prefixes:\n${errors.join("\n")}`);
+    console.error(`check-migrations: db/migrations failed its merge-safety checks:\n${errors.join("\n")}`);
     process.exit(1);
   }
 
-  console.log(`check-migrations: OK (${files.length} migrations, no colliding prefixes).`);
+  const immutabilityClause = immutabilityChecked
+    ? "none renamed/deleted/edited"
+    : "immutability check skipped (no baseline)";
+  console.log(
+    `check-migrations: OK (${files.length} migrations, no colliding prefixes, ${immutabilityClause}).`,
+  );
 }
 
-main();
+if (import.meta.main) main();
+

package/scripts/heal-migration-ledger.ts

@@ -0,0 +1,49 @@
+// heal-migration-ledger — one-shot recovery for an install wedged by issue #357 (a migration that
+// was renamed after it merged, so the runtime re-runs it and boot aborts on "duplicate column").
+//
+// Usage:
+//   node --experimental-strip-types scripts/heal-migration-ledger.ts <path-to-sqlite.db>
+//
+// It reconciles the `_urban_migrations` ledger for every known historical rename
+// (`RENAMED_MIGRATIONS`): where the OLD filename is recorded as applied but the NEW one is not, it
+// records the new filename as applied. This is a pure ledger-alias — it makes NO schema change — and
+// is safe to run repeatedly and on a healthy DB (it only acts on the broken state). After running it,
+// restart the node; the renamed migration is skipped and boot completes.
+import { existsSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import { healMigrationLedger } from "../app/migrationHeal.ts";
+
+function main(): void {
+  const dbPath = process.argv[2];
+  if (!dbPath) {
+    console.error(
+      "usage: node --experimental-strip-types scripts/heal-migration-ledger.ts <path-to-sqlite.db>",
+    );
+    process.exit(2);
+  }
+
+  // `DatabaseSync` silently CREATES an empty DB when the path doesn't exist, so a typo'd path would
+  // "heal" a brand-new empty file and misleadingly report "nothing to heal". Fail loudly instead.
+  if (!existsSync(dbPath)) {
+    console.error(
+      `heal-migration-ledger: ${dbPath} — no such file. Pass the path to the existing install's SQLite DB.`,
+    );
+    process.exit(2);
+  }
+
+  const db = new DatabaseSync(dbPath);
+  try {
+    const healed = healMigrationLedger(db);
+    if (healed.length === 0) {
+      console.log(`heal-migration-ledger: ${dbPath} — nothing to heal (ledger already consistent).`);
+    } else {
+      console.log(
+        `heal-migration-ledger: ${dbPath} — aliased ${healed.length} migration(s) as applied: ${healed.join(", ")}. Restart the node to complete boot.`,
+      );
+    }
+  } finally {
+    db.close();
+  }
+}
+
+if (import.meta.main) main();

package/test/migrations.ts

@@ -0,0 +1,121 @@
+// Test helpers for exercising the forward-only SQLite migration set the way the runtime does.
+//
+// `applyMigrationSet` mirrors `@nanobpm/urban`'s `applyMigrations` (ledger keyed by FILENAME, each
+// migration wrapped in its own transaction, skip-applied / apply-new) against a `node:sqlite`
+// `DatabaseSync`, so upgrade tests reproduce the exact boot-time behaviour — including the
+// "duplicate column" abort a renamed migration causes — without booting the whole app.
+import { execFileSync } from "node:child_process";
+import { readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import type { DatabaseSync } from "node:sqlite";
+import { fileURLToPath } from "node:url";
+
+const REPO_ROOT = join(dirname(fileURLToPath(import.meta.url)), "..");
+const MIGRATIONS_DIR = join(REPO_ROOT, "db", "migrations");
+const MIGRATIONS_TABLE = "_urban_migrations";
+
+export interface MigrationFile {
+  name: string;
+  sql: string;
+}
+
+function byName(files: MigrationFile[]): MigrationFile[] {
+  // Match the runtime's plain lexical `.sort()` on filename (apply order).
+  return [...files].sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0));
+}
+
+/**
+ * Apply `files` to `db` exactly as the runtime does: create the ledger, skip any filename already
+ * recorded, and for each remaining file run its SQL + record the filename atomically in one
+ * transaction. Throws the same rolled-back error the runtime raises when a migration's SQL fails.
+ * @returns the filenames newly applied.
+ */
+export function applyMigrationSet(
+  db: DatabaseSync,
+  files: MigrationFile[],
+  now: () => Date = () => new Date(),
+): string[] {
+  db.exec(
+    `CREATE TABLE IF NOT EXISTS ${MIGRATIONS_TABLE} (name TEXT PRIMARY KEY, applied_at TEXT NOT NULL)`,
+  );
+  const applied = new Set(
+    (db.prepare(`SELECT name FROM ${MIGRATIONS_TABLE}`).all() as { name: string }[]).map(
+      (r) => r.name,
+    ),
+  );
+  const newlyApplied: string[] = [];
+  for (const file of byName(files)) {
+    if (applied.has(file.name)) continue;
+    db.exec("BEGIN");
+    try {
+      db.exec(file.sql);
+      db.prepare(`INSERT INTO ${MIGRATIONS_TABLE} (name, applied_at) VALUES (?, ?)`).run(
+        file.name,
+        now().toISOString(),
+      );
+      db.exec("COMMIT");
+    } catch (err) {
+      db.exec("ROLLBACK");
+      throw new Error(
+        `migration "${file.name}" failed and was rolled back (no partial schema change, not recorded as applied): ${err instanceof Error ? err.message : String(err)}`,
+        { cause: err },
+      );
+    }
+    newlyApplied.push(file.name);
+  }
+  return newlyApplied;
+}
+
+/** The current worktree's migration set, read from `db/migrations/`. */
+export function readMigrationSetFromDisk(): MigrationFile[] {
+  return readdirSync(MIGRATIONS_DIR)
+    .filter((f) => f.endsWith(".sql"))
+    .map((name) => ({ name, sql: readFileSync(join(MIGRATIONS_DIR, name), "utf8") }));
+}
+
+function git(args: string[]): string {
+  return execFileSync("git", args, { cwd: REPO_ROOT, encoding: "utf8" });
+}
+
+/**
+ * The migration set as it existed at a git ref (tag/branch/sha), read straight from the object
+ * store so it works from any worktree. Returns `null` if the ref (or git) is unavailable — e.g. a
+ * shallow clone without tags — so callers can skip rather than fail spuriously (CI fetches full
+ * history + tags, so it exercises the real path).
+ */
+export function readMigrationSetFromGit(ref: string): MigrationFile[] | null {
+  let listing: string;
+  try {
+    listing = git(["ls-tree", "-r", "--name-only", ref, "--", "db/migrations"]);
+  } catch {
+    return null;
+  }
+  const paths = listing
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.endsWith(".sql"));
+  if (paths.length === 0) return null;
+  const files: MigrationFile[] = [];
+  for (const path of paths) {
+    const name = path.slice(path.lastIndexOf("/") + 1);
+    files.push({ name, sql: git(["show", `${ref}:${path}`]) });
+  }
+  return files;
+}
+
+/**
+ * The most recent release tag (`vN.N.N`) reachable from HEAD's parent — i.e. the release we would be
+ * upgrading a live install FROM. Falls back to the tag on HEAD itself, then `null` if none is
+ * reachable (shallow clone without tags).
+ */
+export function previousReleaseTag(): string | null {
+  for (const from of ["HEAD^", "HEAD"]) {
+    try {
+      const ref = git(["describe", "--tags", "--abbrev=0", "--match", "v*", from]).trim();
+      if (ref) return ref;
+    } catch {
+      // try the next base
+    }
+  }
+  return null;
+}

package/workers/conformance-ack/worker.test.ts

@@ -0,0 +1,50 @@
+// Unit coverage for pr.conformance-ack — the operator acknowledged a conformance-review escalation
+// (issue #216). It must settle the parked `plan_conformance` row at `review_status = 'reviewed'` so
+// the inbox scan drops it (the retro instance COMPLETES normally, so `instanceTracking.onTerminated`
+// never fires) and fold the operator's disposition note into the audit `summary`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp(rows: Record<string, unknown>[]) {
+  const stores: Record<string, Record<string, unknown>[]> = { plan_conformance: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  } as any;
+}
+
+test("conformance-ack: settles the review at reviewed and appends the operator note to the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#7", review_status: "reviewing", summary: "slice 2 reduced" }];
+  const app = fakeApp(rows);
+  const out = await handler({ variables: { planKey: "owner/repo#7", note: "filed follow-up #9" } } as any, app);
+  assertEquals(out, {});
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "slice 2 reduced\n\nOperator ack: filed follow-up #9");
+});
+
+test("conformance-ack: a blank note settles the review without touching the summary", async () => {
+  const rows = [{ plan_key: "owner/repo#8", review_status: "reviewing", summary: "auth cache unverified" }];
+  const app = fakeApp(rows);
+  await handler({ variables: { planKey: "owner/repo#8", note: "   " } } as any, app);
+  assertEquals(rows[0].review_status, "reviewed");
+  assertEquals(rows[0].summary, "auth cache unverified");
+});

package/workers/conformance-ack/worker.ts

@@ -0,0 +1,31 @@
+// pr.conformance-ack — an operator acknowledged a conformance-review escalation (issue #216).
+//
+// When the spec-conformance audit finds the epic did NOT cleanly meet its spec, the `retro` process
+// routes to the `conformance-escalation` operator user task (retro.bpmn), which parks the instance
+// on the operators' inbox with `plan_conformance.review_status = 'reviewing'`. This worker fires once
+// the operator completes that ack task: it settles the row at `reviewed` (so the inbox scan drops it)
+// and folds the operator's optional disposition note into the audit `summary`. The instance then
+// continues to the lessons (retro) synthesis, so the ack is NON-blocking — delivery already landed.
+// Persistence goes through the record gateway (`app.data`), never hand-written SQL.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { acknowledgeConformance } from "../../app/conformance.ts";
+
+interface In extends Record<string, unknown> {
+  planKey: string;
+  note?: unknown;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const planKey = job.variables.planKey;
+  const note = str(job.variables.note);
+
+  await acknowledgeConformance(app.data, planKey, note);
+  app.log.info("conformance-ack", { planKey, note: note ?? null });
+
+  return {};
+};
+
+export default handler;

package/workers/conformance-record/worker.test.ts

@@ -1,5 +1,5 @@
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertRejects } from "#test-assert";
 import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
@@ -36,8 +36,9 @@ function fakeApp() {
 
 test("conformance-record: persists a filed conformance from hoisted result vars", async () => {
   const { app, stores } = fakeApp();
-  await handler(
+  const out = await handler(
     {
+      processInstanceKey: "retro-inst-5",
       variables: {
         planKey: "o/r#5",
         status: "filed",
@@ -66,12 +67,17 @@ test("conformance-record: persists a filed conformance from hoisted result vars"
   assertEquals(row.deviations_unraised, 1);
   assertEquals(row.has_deviations, 1);
   assertEquals(row.report, "the full conformance report");
+  // Tracks the retro instance and enters the inbox scan (issue #216) — a deviation escalates.
+  assertEquals(row.process_key, "retro-inst-5");
+  assertEquals(row.review_status, "reviewing");
+  // The gateway routes off the returned ground-truth flag, not the agent's hoisted var.
+  assertEquals(out, { hasDeviations: true });
 });
 
 test("conformance-record: derives has_deviations from ground truth even when the agent flag is absent", async () => {
   const { app, stores } = fakeApp();
   await handler(
-    { variables: { planKey: "o/r#6", status: "filed", commentUrl: "https://x/6#c", slicesNotVerified: 1 } } as any,
+    { processInstanceKey: "retro-inst-6", variables: { planKey: "o/r#6", status: "filed", commentUrl: "https://x/6#c", slicesNotVerified: 1 } } as any,
     app as any,
   );
   // The agent didn't set hasDeviations, but a not-verified item means the epic didn't cleanly meet spec.
@@ -80,12 +86,15 @@ test("conformance-record: derives has_deviations from ground truth even when the
 
 test("conformance-record: a clean epic records has_deviations = 0", async () => {
   const { app, stores } = fakeApp();
-  await handler(
-    { variables: { planKey: "o/r#7", status: "filed", commentUrl: "https://x/7#c", slicesMet: 3, hasDeviations: false } } as any,
+  const out = await handler(
+    { processInstanceKey: "retro-inst-7", variables: { planKey: "o/r#7", status: "filed", commentUrl: "https://x/7#c", slicesMet: 3, hasDeviations: false } } as any,
     app as any,
   );
   assertEquals(stores.plan_conformance[0].has_deviations, 0);
   assertEquals(stores.plan_conformance[0].slices_met, 3);
+  // No deviation → settles straight to `reviewed`, never entering the inbox scan.
+  assertEquals(stores.plan_conformance[0].review_status, "reviewed");
+  assertEquals(out, { hasDeviations: false });
 });
 
 test("conformance-record: coerces filed without a comment URL to skipped", async () => {
@@ -139,6 +148,7 @@ test("conformance-record: coerces string-encoded numeric counts hoisted by the a
   // These must be parsed, not silently coerced to 0 (which would wrongly clear the verdict).
   await handler(
     {
+      processInstanceKey: "retro-inst-12",
       variables: {
         planKey: "o/r#12",
         status: "filed",
@@ -167,6 +177,7 @@ test("conformance-record: honours a string-encoded hasDeviations flag", async ()
   // string "true" must still record a deviation — a stringified boolean can't silently be dropped.
   await handler(
     {
+      processInstanceKey: "retro-inst-13",
       variables: {
         planKey: "o/r#13",
         status: "filed",
@@ -197,3 +208,34 @@ test("conformance-record: defaults to skipped when the agent reported nothing",
   );
   assertEquals(stores.plan_conformance[0].status, "skipped");
 });
+
+test("conformance-record: coerces a numeric processInstanceKey to a string (TEXT process_key never drifts)", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    { processInstanceKey: 220592130 as any, variables: { planKey: "o/r#11", status: "filed", commentUrl: "https://x/11#c", slicesNotVerified: 1 } } as any,
+    app as any,
+  );
+  const row = stores.plan_conformance[0];
+  assertEquals(row.process_key, "220592130");
+  assertEquals(typeof row.process_key, "string");
+  assertEquals(row.review_status, "reviewing");
+});
+
+test("conformance-record: fails (not a silent, untrackable escalation) when there is no processKey but there are deviations", async () => {
+  const { app, stores } = fakeApp();
+  // No `processInstanceKey` + deviations: the handler would otherwise return `hasDeviations:true`
+  // (routing retro to `conformance-escalation`) while the row is `reviewed`/`process_key=null`, an
+  // ack `pollUserTasks` can never surface nor `onTerminated` clear — an invisible, wedged escalation.
+  // Fail loudly instead so the run retries/alerts rather than encoding that silent state.
+  await assertRejects(
+    () =>
+      handler(
+        { variables: { planKey: "o/r#12", status: "filed", commentUrl: "https://x/12#c", slicesNotVerified: 1, hasDeviations: true } } as any,
+        app as any,
+      ),
+    Error,
+    "no processInstanceKey",
+  );
+  // Nothing was persisted: the throw precedes the write, so no untrackable row is left behind.
+  assertEquals(stores.plan_conformance.length, 0);
+});

package/workers/conformance-record/worker.ts

@@ -73,6 +73,28 @@ const handler: AppJobHandler<In> = async (job, app) => {
     (asBool(job.variables.hasDeviations) ||
       slicesReduced > 0 || slicesNotVerified > 0 || deviationsUnraised > 0);
 
+  // Track this retro instance on the conformance row so `pollUserTasks` can find the escalation ack
+  // task, but only mark it `reviewing` when there IS something to escalate — a clean run settles
+  // straight to `reviewed` and never enters the inbox scan (migration 054). Coerce the instance key
+  // to a string (the engine can hand back a numeric key) so `plan_conformance.process_key` (TEXT)
+  // never drifts to a number and break the string-filter reads in `pollUserTasks`/`openUserTasks` —
+  // the same `String(...)` coercion app/service.ts applies when it stamps `process_key`.
+  const processKey = job.processInstanceKey != null ? String(job.processInstanceKey) : null;
+
+  // Invariant: an escalation must be trackable. If we found deviations to escalate but have no
+  // process key to key the `reviewing` row off, the `hasDeviations` return below would still route
+  // retro to the `conformance-escalation` user task — yet `pollUserTasks` can never surface that ack
+  // (it skips rows without `process_key`) nor can the `onTerminated` binding ever clear it, so the
+  // escalation wedges forever, invisible to any human. Rather than record that silent, unreachable
+  // state, fail loudly so the run retries/alerts. `job.processInstanceKey` is always present for an
+  // activated job, so this only fires on a genuine engine-contract violation.
+  if (hasDeviations && processKey == null) {
+    throw new Error(
+      `conformance-record: ${planKey} has deviations to escalate but no processInstanceKey to track ` +
+        "the escalation — refusing to route to an untrackable conformance-escalation ack task",
+    );
+  }
+
   await recordConformance(app.data, planKey, {
     status,
     commentUrl: filed ? commentUrl : null,
@@ -84,12 +106,22 @@ const handler: AppJobHandler<In> = async (job, app) => {
     hasDeviations,
     summary,
     report,
+    processKey,
+    // Only enter the `reviewing` inbox scan when we actually have a `processKey` to key off — a
+    // null key can never be found by `pollUserTasks` (it skips rows without `process_key`) nor
+    // cleared by the `instanceTracking` `onTerminated` binding, so a `reviewing` row with no key
+    // would wedge forever. The invariant guard above already rejected `hasDeviations` with a null
+    // key, so `reviewing` here always carries a non-null `processKey`.
+    reviewStatus: hasDeviations ? "reviewing" : "reviewed",
   });
 
   app.log.info(
     `conformance-record: ${planKey} — status=${status} deviations=${hasDeviations ? "yes" : "no"}`,
   );
-  return {};
+  // Return the ground-truth `hasDeviations` as a process variable so the `gw-deviations` gateway
+  // routes to the human ack task (retro.bpmn) — overriding the agent's hoisted flag with the value
+  // reconciled against the recorded counts above.
+  return { hasDeviations };
 };
 
 export default handler;