@nanobpm/nano-workforce 0.88.0 → 0.88.1

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+## [0.88.1](https://github.com/nanobpm/nano-workforce/compare/v0.88.0...v0.88.1) (2026-08-18)
+
+
+### Bug Fixes
+
+* scope user-task pollers to open tasks so they can't latch a COMPLETED task ([#297](https://github.com/nanobpm/nano-workforce/issues/297)) ([131a796](https://github.com/nanobpm/nano-workforce/commit/131a796dfaed8f9b2eb25526f6583b86b8d7b0df)), closes [#294](https://github.com/nanobpm/nano-workforce/issues/294)
+
 # [0.88.0](https://github.com/nanobpm/nano-workforce/compare/v0.87.0...v0.88.0) (2026-08-18)
 
 

package/app/contracts.ts

@@ -354,6 +354,14 @@ export const TYPE_CONTRACTS = {
       "The snake_case, agent-facing view of a blackboard entry — the HTTP-hook boundary shape every caller and agent consumes. Both the read and write halves import this ONE definition.",
     module: "app/blackboard.ts",
   },
+  PlanDep: {
+    category: "type",
+    name: "PlanDep",
+    owner: "app/plan.ts",
+    semantics:
+      "One INTER-epic dependency edge (issue #292): dependent epic `plan_key` waits for producer epic `depends_on_plan_key`, gated by the producer's `{ package, capability_ref }` capability descriptor. Set admission (S2), planner lowering (S3), and operator visibility (S4) all import this ONE row shape from app/plan.ts — no re-declared synonym.",
+    module: "app/plan.ts",
+  },
 } as const satisfies Record<string, TypeContract>;
 
 export const CAPABILITY_URL_CONTRACTS = {

package/app/feature.ts

@@ -181,10 +181,12 @@ export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryR
 export const FEATURE_ESCALATION_ELEMENT = "feature-escalation";
 
 /** The parked `feature-escalation` user task, as `pollFeatureEscalations` observes it via
- * `searchUserTasks`: the completable user-task key the pages drive an attributed answer against.
+ *  `openUserTasks` (the open-task-scoped query — issue #294): the completable user-task key the pages
+ *  drive an attributed answer against. Scoping to `state:"CREATED"` is what keeps a looping run — which
+ *  holds COMPLETED prior-round tasks for the same element — from latching the pointer onto a dead task.
  *
  * The agent's `question` is NOT read from here — the WASM testkit engine does not surface a user
- * task's `zeebe:ioMapping`-mapped local variables through `searchUserTasks`, so relying on it would
+ * task's `zeebe:ioMapping`-mapped local variables through the user-task query, so relying on it would
  * make the question untestable. Instead the `record-feature-escalation` service task (feature.bpmn)
  * persists `question` onto the row at escalation entry — see `workers/record-feature-escalation`. */
 export interface FeatureEscalationParked {
@@ -240,8 +242,10 @@ export function deriveFeatureEscalationPatch(
  * `pollFeatureBlocked` reconciles it onto the read model. */
 export const FEATURE_BLOCKED_ELEMENT = "feature-blocked";
 
-/** The parked `feature-blocked` user task, as `pollFeatureBlocked` observes it via `searchUserTasks`:
- * the completable user-task key the pages drive an attributed acknowledgement against. */
+/** The parked `feature-blocked` user task, as `pollFeatureBlocked` observes it via `openUserTasks`
+ *  (the open-task-scoped query — issue #294): the completable user-task key the pages drive an
+ *  attributed acknowledgement against. Scoping to `state:"CREATED"` keeps a re-blocked run — which
+ *  holds COMPLETED prior-round tasks for the same element — from latching the pointer onto a dead task. */
 export interface FeatureBlockedParked {
   userTaskKey: string;
 }

package/app/featureBlocked.test.ts

@@ -49,12 +49,22 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field
- *  pollFeatureBlocked queries on). */
-function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+/** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
+ *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
+ *  A looping run holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
+type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED" };
+
+/** A fake engine whose user tasks are keyed by processInstanceKey (the only field
+ *  pollFeatureBlocked queries on). It models the real engine's two accessors from ONE fixture so a test
+ *  genuinely exercises the lifecycle-state filtering: `searchUserTasks` returns tasks in ANY state
+ *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`. */
+function fakeEngine(byInstance: Record<string, FakeTask[]>): EngineClient {
+  const all = (filter?: { processInstanceKey?: string }) =>
+    filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : [];
   return {
-    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
-      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+    searchUserTasks: (filter?: { processInstanceKey?: string }) => Promise.resolve(all(filter)),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(all(filter).filter((t) => (t.state ?? "CREATED") === "CREATED")),
   } as unknown as EngineClient;
 }
 
@@ -133,3 +143,40 @@ test("pollFeatureBlocked: a parked non-blocked task (feature-escalation) does no
 
   assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
 });
+
+// ── Defect-class guard (issue #294): a looping run holds MULTIPLE feature-blocked tasks ────────────
+// The blocked wait sits on a blocked→ack loop, so a re-blocked run holds a COMPLETED feature-blocked
+// task from a prior round alongside the live CREATED one; the engine returns the COMPLETED task first.
+// Scoping the query to open (CREATED) tasks records the live key, never the terminal one.
+test("pollFeatureBlocked: a looping run records the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#6", status: "awaiting_operator", process_key: "600", blocked_user_task_key: null },
+  ];
+  const engine = fakeEngine({
+    "600": [
+      { userTaskKey: "ut-completed", elementId: "feature-blocked", state: "COMPLETED" },
+      { userTaskKey: "ut-live", elementId: "feature-blocked", state: "CREATED" },
+    ],
+  });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, "ut-live");
+});
+
+// Self-heal reached: a run past the blocked wait whose only feature-blocked task is COMPLETED must
+// clear the stale pointer (open-task query returns [] → `parked=null`), not latch it on the dead key.
+test("pollFeatureBlocked: a run whose only feature-blocked task is COMPLETED clears the stale pointer", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#7", status: "awaiting_operator", process_key: "700", blocked_user_task_key: "ut-7" },
+  ];
+  const engine = fakeEngine({
+    "700": [{ userTaskKey: "ut-7", elementId: "feature-blocked", state: "COMPLETED" }],
+  });
+
+  await pollFeatureBlocked(data, engine);
+
+  assertEquals(stores.feature_runs[0].blocked_user_task_key, null);
+});

package/app/featureEscalation.test.ts

@@ -50,12 +50,22 @@ function memData(): { data: DataLayer; stores: Record<string, any[]> } {
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field
- *  pollFeatureEscalations queries on). */
-function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+/** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
+ *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
+ *  A looping run holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
+type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED" };
+
+/** A fake engine whose user tasks are keyed by processInstanceKey (the only field
+ *  pollFeatureEscalations queries on). It models the real engine's two accessors from ONE fixture so a
+ *  test genuinely exercises the lifecycle-state filtering: `searchUserTasks` returns tasks in ANY state
+ *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`. */
+function fakeEngine(byInstance: Record<string, FakeTask[]>): EngineClient {
+  const all = (filter?: { processInstanceKey?: string }) =>
+    filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : [];
   return {
-    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
-      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+    searchUserTasks: (filter?: { processInstanceKey?: string }) => Promise.resolve(all(filter)),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(all(filter).filter((t) => (t.state ?? "CREATED") === "CREATED")),
   } as unknown as EngineClient;
 }
 
@@ -178,3 +188,48 @@ test("pollFeatureEscalations: a parked non-escalation task (feature-blocked) doe
   assertEquals(stores.feature_runs[0].status, "running");
   assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
 });
+
+// ── Defect-class guard (issue #294): a looping run holds MULTIPLE feature-escalation tasks ─────────
+// A run in an escalate→answer→implement→re-escalate loop holds a COMPLETED feature-escalation task
+// from a prior round alongside the live CREATED one. The engine returns the COMPLETED task first, so a
+// poller that reads UNFILTERED tasks and `.find`s by element latches onto the terminal key — pinning
+// the pointer at a dead task. Scoping the query to open (CREATED) tasks resolves the live one.
+test("pollFeatureEscalations: a looping run resolves the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#7", status: "running", process_key: "700", escalation_question: null, escalation_user_task_key: null },
+  ];
+  // Engine returns the COMPLETED (prior-round) task FIRST, then the live CREATED one (issue #294).
+  const engine = fakeEngine({
+    "700": [
+      { userTaskKey: "ut-completed", elementId: "feature-escalation", state: "COMPLETED" },
+      { userTaskKey: "ut-live", elementId: "feature-escalation", state: "CREATED" },
+    ],
+  });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "escalated");
+  // Must be the live CREATED task, not the COMPLETED prior-round one.
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, "ut-live");
+});
+
+// Self-heal reached: once a run finally exits escalation for good, only a lingering COMPLETED
+// feature-escalation task remains. The open-task query returns [], so `parked=null` and the run
+// resets escalated→running — instead of a false-positive pointer built from the terminal task pinning
+// `status='escalated'` forever.
+test("pollFeatureEscalations: a run whose only feature-escalation task is COMPLETED self-heals to running", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#8", status: "escalated", process_key: "800", escalation_question: "Q", escalation_user_task_key: "ut-8" },
+  ];
+  const engine = fakeEngine({
+    "800": [{ userTaskKey: "ut-8", elementId: "feature-escalation", state: "COMPLETED" }],
+  });
+
+  await pollFeatureEscalations(data, engine);
+
+  assertEquals(stores.feature_runs[0].status, "running");
+  assertEquals(stores.feature_runs[0].escalation_user_task_key, null);
+  assertEquals(stores.feature_runs[0].escalation_question, null);
+});

package/app/migration041.test.ts

@@ -0,0 +1,79 @@
+// Regression guard for migration 041 (issue #292 slice S1): the durable constraints on the INTER-epic
+// `plan_deps` table. The app-layer accessors (app/planDeps.test.ts) enforce self-edge / duplicate
+// rejection for the in-memory data layer; this test proves the SCHEMA itself is the backstop — the
+// migration applies cleanly, a self-edge trips the CHECK, a duplicate consumer→producer pair trips
+// the PRIMARY KEY, and the consumer `plan_key` foreign-keys to an admitted plan.
+import { readFileSync } from "node:fs";
+import { DatabaseSync } from "node:sqlite";
+import test from "node:test";
+import { fileURLToPath } from "node:url";
+import { assertEquals } from "#test-assert";
+
+function migratedDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  // Minimal `plans` shape the migration's FK references.
+  db.exec("CREATE TABLE plans (plan_key TEXT PRIMARY KEY);");
+  for (const k of ["o/r#1", "o/r#2", "o/r#3"]) {
+    db.prepare("INSERT INTO plans (plan_key) VALUES (?)").run(k);
+  }
+  const sql = readFileSync(
+    fileURLToPath(new URL("../db/migrations/041_inter_epic_plan_deps.sql", import.meta.url)),
+    "utf8",
+  );
+  db.exec(sql);
+  return db;
+}
+
+const insert = (db: DatabaseSync, planKey: string, dependsOn: string) =>
+  db
+    .prepare(
+      `INSERT INTO plan_deps (plan_key, depends_on_plan_key, package, capability_ref, created_at)
+       VALUES (?, ?, '@nanobpm/p', ?, 't')`,
+    )
+    .run(planKey, dependsOn, dependsOn);
+
+test("migration 041 applies cleanly and records a valid inter-epic edge", () => {
+  const db = migratedDb();
+  insert(db, "o/r#2", "o/r#1");
+  const row = db
+    .prepare("SELECT plan_key, depends_on_plan_key, package FROM plan_deps WHERE plan_key = ?")
+    .get("o/r#2") as { plan_key: string; depends_on_plan_key: string; package: string };
+  assertEquals(row.plan_key, "o/r#2");
+  assertEquals(row.depends_on_plan_key, "o/r#1");
+  assertEquals(row.package, "@nanobpm/p");
+});
+
+test("migration 041 CHECK rejects a self-edge", () => {
+  const db = migratedDb();
+  let threw = false;
+  try {
+    insert(db, "o/r#1", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 041 PRIMARY KEY rejects a duplicate consumer→producer edge", () => {
+  const db = migratedDb();
+  insert(db, "o/r#2", "o/r#1");
+  let threw = false;
+  try {
+    insert(db, "o/r#2", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});
+
+test("migration 041 FK ties the consumer plan_key to an admitted plan", () => {
+  const db = migratedDb();
+  let threw = false;
+  try {
+    insert(db, "o/r#404", "o/r#1");
+  } catch {
+    threw = true;
+  }
+  assertEquals(threw, true);
+});

package/app/plan.ts

@@ -138,6 +138,87 @@ export interface PlanTaskDep {
 export const planTaskDeps = (data: DataLayer) =>
   data.table<PlanTaskDep>("plan_task_deps", "plan_key");
 
+/** One INTER-epic dependency edge in the plan-set DAG (issue #292, slice S1): the epic `plan_key`
+ * waits for the producer epic `depends_on_plan_key` to publish a capability before it may fan out.
+ *
+ * This is the coarser sibling of {@link PlanTaskDep} (which orders TASKS *within* one epic into
+ * waves). A `PlanDep` orders whole EPICS relative to each other. The edge additionally carries the
+ * gating contract descriptor the capability probe (slice S3) resolves against:
+ *   • `package` — the producer epic's published package name, and
+ *   • `capability_ref` — the producer epic's issue handle, used to resolve which published
+ *     `pkg@version` FIRST carries the awaited capability (late-bound into the dependent's build).
+ * Keyed on `plan_key` (the dependent) so a single delete clears a dependent's whole inbound edge set
+ * — mirroring how `plan_task_deps` is keyed on `plan_key`. See db/migrations/041_inter_epic_plan_deps.sql
+ * for the durable constraints (one edge per consumer→producer pair; no self-edge). */
+export interface PlanDep {
+  plan_key: string;
+  depends_on_plan_key: string;
+  package: string;
+  capability_ref: string;
+  created_at: string;
+}
+export const planDeps = (data: DataLayer) => data.table<PlanDep>("plan_deps", "plan_key");
+
+/** The fields an admission caller supplies for one inter-epic edge; `created_at` is stamped here. */
+export type PlanDepInput = Omit<PlanDep, "created_at">;
+
+/** Record one inter-epic dependency edge, enforcing the schema's two invariants at the app layer too
+ * (the durable table backstops both, but the in-memory test data layer does not): an epic may not
+ * depend on itself, and a consumer→producer edge is recorded at most once. A duplicate re-submission
+ * is a no-op that returns the existing row rather than throwing, so batch admission (S2) stays
+ * idempotent; a self-edge is a programming/validation error and throws. */
+export async function recordPlanDep(data: DataLayer, edge: PlanDepInput): Promise<PlanDep> {
+  if (edge.plan_key === edge.depends_on_plan_key) {
+    throw new Error(
+      `plan_deps: self-edge rejected — epic ${edge.plan_key} cannot depend on itself`,
+    );
+  }
+  const table = planDeps(data);
+  const match = { plan_key: edge.plan_key, depends_on_plan_key: edge.depends_on_plan_key };
+  const existing = (await table.find(match))[0];
+  if (existing) return existing;
+  const row: PlanDep = { ...edge, created_at: now() };
+  try {
+    await table.insert(row);
+    return row;
+  } catch (err) {
+    // A concurrent caller may have inserted the same consumer→producer pair between our find and
+    // our insert (classic check-then-insert race); the composite PRIMARY KEY is the durable
+    // backstop that rejects the loser. Honour the "duplicate re-submission is a no-op" contract by
+    // re-reading and returning the winning row rather than surfacing the constraint error. Only a
+    // genuine non-collision failure (the pair still absent after the re-read) is re-raised.
+    const raced = (await table.find(match))[0];
+    if (raced) return raced;
+    throw err;
+  }
+}
+
+/** All INBOUND edges for `planKey` — i.e. every producer epic this dependent waits on. Empty for a
+ * root epic (no inter-epic dependencies). */
+export function inboundPlanDeps(data: DataLayer, planKey: string): Promise<PlanDep[]> {
+  return planDeps(data).find({ plan_key: planKey });
+}
+
+/** Every inter-epic edge whose dependent is in `planKeys` — the whole DAG for a submitted plan set.
+ * Reads per-key (not a table scan) so it composes with the same equality-filtered data layer the
+ * unit tests exercise. Producers outside the set are still returned as edge fields; the set
+ * validator (S3) is what rejects an edge naming an unsubmitted epic. */
+export async function planDepsForSet(data: DataLayer, planKeys: string[]): Promise<PlanDep[]> {
+  const seen = new Set<string>();
+  const out: PlanDep[] = [];
+  // De-duplicate the keys first so a repeated key (retries / accidental repeats) does not trigger a
+  // redundant per-key inbound read; the edge de-dup below still guards against any overlap.
+  for (const key of new Set(planKeys)) {
+    for (const edge of await inboundPlanDeps(data, key)) {
+      const id = `${edge.plan_key}\u0000${edge.depends_on_plan_key}`;
+      if (seen.has(id)) continue;
+      seen.add(id);
+      out.push(edge);
+    }
+  }
+  return out;
+}
+
 /** One adversarial plan-review round (006_plan_review.sql): the `senior:plan-review` agent's
  * verdict on the plan before fan-out. Append-only within a plan run; the current round is
  * `count(plan_reviews)`. Re-planning a finished issue clears the prior rows (see startPlan) so

package/app/planDeps.test.ts

@@ -0,0 +1,192 @@
+// Red/green regression for the INTER-epic dependency edge (PlanDep) data layer — issue #292 slice S1.
+//
+// This slice adds `plan_deps` (db/migrations/041_inter_epic_plan_deps.sql) and its typed read/write
+// surface in app/plan.ts, mirroring the intra-epic `plan_task_deps` accessors. The durable table
+// enforces "one edge per consumer→producer pair" (PRIMARY KEY) and "no self-edge" (CHECK); these
+// tests pin the app-layer accessors that admission (S2) and the planner (S3) build on, driven against
+// the same in-memory data layer the rest of app/plan's tests use.
+import { test } from "node:test";
+import { assertEquals, assertRejects } from "#test-assert";
+import {
+  inboundPlanDeps,
+  type PlanDep,
+  planDepsForSet,
+  recordPlanDep,
+} from "./plan.ts";
+
+// Minimal in-memory data layer, matching the helper style in app/plan.test.ts: equality-filtered
+// `find`, append `insert`, and a `delete(planKey)` that clears every row keyed on `plan_key` (so a
+// re-seed of a plan's inbound edge set is one delete, exactly as `plan_task_deps` is cleared).
+function memData() {
+  const rows: any[] = [];
+  const key = "plan_key";
+  const table = {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    count: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+  return {
+    rows,
+    data: { table: () => table } as any,
+  };
+}
+
+const EDGE = {
+  plan_key: "owner/repo#2",
+  depends_on_plan_key: "owner/repo#1",
+  package: "@nanobpm/producer",
+  capability_ref: "owner/repo#1",
+};
+
+test("recordPlanDep persists an edge with a stamped created_at", async () => {
+  const { data, rows } = memData();
+  const row = await recordPlanDep(data, EDGE);
+  assertEquals(rows.length, 1);
+  assertEquals(row.plan_key, "owner/repo#2");
+  assertEquals(row.depends_on_plan_key, "owner/repo#1");
+  assertEquals(row.package, "@nanobpm/producer");
+  assertEquals(row.capability_ref, "owner/repo#1");
+  assertEquals(typeof row.created_at, "string");
+  assertEquals(row.created_at.length > 0, true);
+});
+
+test("recordPlanDep rejects a self-edge (an epic cannot depend on itself)", async () => {
+  const { data, rows } = memData();
+  await assertRejects(() =>
+    recordPlanDep(data, { ...EDGE, plan_key: "owner/repo#1", depends_on_plan_key: "owner/repo#1" }),
+  );
+  assertEquals(rows.length, 0);
+});
+
+test("recordPlanDep is idempotent on a duplicate edge (no second row)", async () => {
+  const { data, rows } = memData();
+  const first = await recordPlanDep(data, EDGE);
+  const again = await recordPlanDep(data, { ...EDGE, package: "@nanobpm/ignored-on-dupe" });
+  assertEquals(rows.length, 1);
+  // The existing row wins — a re-submission does not overwrite nor append.
+  assertEquals(again.created_at, first.created_at);
+  assertEquals(again.package, "@nanobpm/producer");
+});
+
+test("recordPlanDep treats a concurrent PK collision as idempotent (no throw)", async () => {
+  // Simulate the check-then-insert race the durable composite PRIMARY KEY backstops: a sibling
+  // caller wins between our find and our insert, so `find` sees nothing but `insert` collides.
+  const rows: any[] = [];
+  const key = "plan_key";
+  let raceArmed = true;
+  const table = {
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    find: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    insert: (r: any) => {
+      // On the first insert, a concurrent writer has already landed the same pair: append the
+      // rival row and reject this one with a UNIQUE/PK constraint error, as SQLite would.
+      if (raceArmed) {
+        raceArmed = false;
+        rows.push({ ...r, package: "@nanobpm/winner", created_at: "1999-01-01T00:00:00.000Z" });
+        return Promise.reject(new Error("UNIQUE constraint failed: plan_deps.plan_key"));
+      }
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    count: (q: any) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) if (rows[i][key] === k) rows.splice(i, 1);
+      return Promise.resolve();
+    },
+  };
+  const data = { table: () => table } as any;
+
+  const row = await recordPlanDep(data, EDGE);
+  // The rival row is returned rather than the constraint error surfacing, and no duplicate lands.
+  assertEquals(rows.length, 1);
+  assertEquals(row.package, "@nanobpm/winner");
+  assertEquals(row.created_at, "1999-01-01T00:00:00.000Z");
+});
+
+test("recordPlanDep re-raises a non-collision insert failure", async () => {
+  // A genuine failure (the pair is still absent after the re-read) must not be swallowed.
+  const table = {
+    get: () => Promise.resolve(null),
+    find: () => Promise.resolve([] as any[]),
+    insert: () => Promise.reject(new Error("disk I/O error")),
+    count: () => Promise.resolve(0),
+    delete: () => Promise.resolve(),
+  };
+  const data = { table: () => table } as any;
+  await assertRejects(() => recordPlanDep(data, EDGE), Error, "disk I/O error");
+});
+
+test("inboundPlanDeps returns every producer a dependent waits on; empty for a root", async () => {
+  const { data } = memData();
+  await recordPlanDep(data, EDGE);
+  await recordPlanDep(data, { ...EDGE, depends_on_plan_key: "owner/repo#3", capability_ref: "owner/repo#3" });
+
+  const inbound = await inboundPlanDeps(data, "owner/repo#2");
+  assertEquals(inbound.length, 2);
+  assertEquals(
+    inbound.map((e: PlanDep) => e.depends_on_plan_key).sort(),
+    ["owner/repo#1", "owner/repo#3"],
+  );
+
+  const root = await inboundPlanDeps(data, "owner/repo#1");
+  assertEquals(root.length, 0);
+});
+
+test("planDepsForSet returns the whole DAG for a submitted set, de-duplicated", async () => {
+  const { data } = memData();
+  // #3 -> #1, #3 -> #2, #2 -> #1 : a small DAG across three epics.
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#3",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/a",
+    capability_ref: "owner/repo#1",
+  });
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#3",
+    depends_on_plan_key: "owner/repo#2",
+    package: "@nanobpm/b",
+    capability_ref: "owner/repo#2",
+  });
+  await recordPlanDep(data, {
+    plan_key: "owner/repo#2",
+    depends_on_plan_key: "owner/repo#1",
+    package: "@nanobpm/a",
+    capability_ref: "owner/repo#1",
+  });
+
+  const edges = await planDepsForSet(data, ["owner/repo#1", "owner/repo#2", "owner/repo#3"]);
+  assertEquals(edges.length, 3);
+  // A root (#1) contributes no inbound edges; passing overlapping keys never double-counts an edge.
+  const overlapped = await planDepsForSet(data, ["owner/repo#3", "owner/repo#3"]);
+  assertEquals(overlapped.length, 2);
+});
+
+test("planDepsForSet reads each key once even when planKeys repeats", async () => {
+  // Prove the key de-dup: a repeated key must not drive a redundant inbound read.
+  const findKeys: string[] = [];
+  const table = {
+    get: () => Promise.resolve(null),
+    find: (q: any) => {
+      findKeys.push(q.plan_key);
+      return Promise.resolve([] as any[]);
+    },
+    insert: (r: any) => Promise.resolve(r),
+    count: () => Promise.resolve(0),
+    delete: () => Promise.resolve(),
+  };
+  const data = { table: () => table } as any;
+  await planDepsForSet(data, ["owner/repo#3", "owner/repo#3", "owner/repo#4", "owner/repo#3"]);
+  assertEquals(findKeys.sort(), ["owner/repo#3", "owner/repo#4"]);
+});

package/app/pollUserTasks.test.ts

@@ -51,12 +51,22 @@ function memData(seed: Record<string, any[]> = {}): { data: DataLayer; stores: R
   return { data, stores };
 }
 
-/** A fake engine whose open user tasks are keyed by processInstanceKey (the only field the poller
- *  queries on for plan / PR instances). */
-function fakeEngine(byInstance: Record<string, { userTaskKey: string; elementId?: string }[]>): EngineClient {
+/** A single engine-reported user task in the fixture. `state` mirrors the engine lifecycle; it
+ *  defaults to `"CREATED"` (the only open/answerable state) so existing fixtures read as live tasks.
+ *  A looping instance holds multiple tasks for one element (COMPLETED from prior rounds + the live one). */
+type FakeTask = { userTaskKey: string; elementId?: string; state?: "CREATED" | "COMPLETED" | "CANCELED" };
+
+/** A fake engine whose user tasks are keyed by processInstanceKey (the only field the poller queries on
+ *  for plan / PR instances). It models the real engine's two accessors from ONE fixture so a test
+ *  genuinely exercises the lifecycle-state filtering: `searchUserTasks` returns tasks in ANY state
+ *  (COMPLETED first, as the live API does — issue #294), while `openUserTasks` pins `state:"CREATED"`. */
+function fakeEngine(byInstance: Record<string, FakeTask[]>): EngineClient {
+  const all = (filter?: { processInstanceKey?: string }) =>
+    filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : [];
   return {
-    searchUserTasks: (filter?: { processInstanceKey?: string }) =>
-      Promise.resolve(filter?.processInstanceKey ? (byInstance[filter.processInstanceKey] ?? []) : []),
+    searchUserTasks: (filter?: { processInstanceKey?: string }) => Promise.resolve(all(filter)),
+    openUserTasks: (filter?: { processInstanceKey?: string }) =>
+      Promise.resolve(all(filter).filter((t) => (t.state ?? "CREATED") === "CREATED")),
   } as unknown as EngineClient;
 }
 
@@ -172,3 +182,50 @@ test("pollUserTasks: skips terminal plans and PRs without a process key", async
 
   assertEquals(stores.user_tasks ?? [], []);
 });
+
+// ── Defect-class guard (issue #294): a looping instance holds MULTIPLE tasks for one element ───────
+// The plan-review (review→revise→review) and PR-wait (escalate→answer→re-escalate) elements sit on a
+// loop, so a looping instance holds a COMPLETED task from a prior round alongside the live CREATED one,
+// and the engine returns the COMPLETED one first. Scoping the query to open (CREATED) tasks projects
+// only the live completable key onto `user_tasks`, never a terminal one the page could not complete.
+test("pollUserTasks: a looping plan/PR projects only the CREATED task, never the COMPLETED one", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#50", status: "dispatched", process_key: "pp-50", issue_url: "https://github.com/o/r/issues/50" }],
+    plan_reviews: [{ plan_key: "o/r#50", epoch: 0, round: 0, approved: 0, findings: "scope too broad", created_at: "2025-01-01T00:00:00.000Z" }],
+    pull_requests: [{ pr_key: "o/r#51", status: "escalated", process_key: "rp-51", url: "https://github.com/o/r/pull/51" }],
+    escalations: [{ id: 1, pr_key: "o/r#51", status: "open", question: "conflicting reviews" }],
+  });
+  // Each looping instance returns its COMPLETED prior-round task FIRST, then the live CREATED one.
+  const engine = fakeEngine({
+    "pp-50": [
+      { userTaskKey: "ut-plan-completed", elementId: "plan-review-decision", state: "COMPLETED" },
+      { userTaskKey: "ut-plan-live", elementId: "plan-review-decision", state: "CREATED" },
+    ],
+    "rp-51": [
+      { userTaskKey: "ut-pr-completed", elementId: "wait-answer", state: "COMPLETED" },
+      { userTaskKey: "ut-pr-live", elementId: "wait-answer", state: "CREATED" },
+    ],
+  });
+
+  await pollUserTasks(data, engine);
+
+  const keys = (stores.user_tasks ?? []).map((r) => r.user_task_key).sort();
+  // Only the live CREATED keys — the COMPLETED prior-round tasks must never surface a dead affordance.
+  assertEquals(keys, ["ut-plan-live", "ut-pr-live"]);
+});
+
+// Self-heal reached: an instance whose only task for an element is COMPLETED yields no open task, so
+// its row is removed (open-task query returns []), rather than pinning a dead completable pointer.
+test("pollUserTasks: an instance whose only task is COMPLETED surfaces no row", async () => {
+  const { data, stores } = memData({
+    plans: [{ plan_key: "o/r#52", status: "dispatched", process_key: "pp-52", issue_url: "https://github.com/o/r/issues/52" }],
+    plan_reviews: [{ plan_key: "o/r#52", epoch: 0, round: 0, approved: 0, findings: "scope too broad", created_at: "2025-01-01T00:00:00.000Z" }],
+  });
+  const engine = fakeEngine({
+    "pp-52": [{ userTaskKey: "ut-plan-completed", elementId: "plan-review-decision", state: "COMPLETED" }],
+  });
+
+  await pollUserTasks(data, engine);
+
+  assertEquals(stores.user_tasks ?? [], []);
+});

package/app/service.ts

@@ -1410,7 +1410,7 @@ export async function pollFeatureEscalations(data: DataLayer, engine: EngineClie
   for (const run of candidates) {
     if (!run.process_key) continue;
     try {
-      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const tasks = await engine.openUserTasks({ processInstanceKey: run.process_key });
       const task = tasks.find((t) => t.elementId === FEATURE_ESCALATION_ELEMENT);
       const parked = task ? { userTaskKey: task.userTaskKey } : null;
       const patch = deriveFeatureEscalationPatch(run, parked);
@@ -1444,7 +1444,7 @@ export async function pollFeatureBlocked(data: DataLayer, engine: EngineClient)
   for (const run of await featureRuns(data).find({ status: "awaiting_operator" })) {
     if (!run.process_key) continue;
     try {
-      const tasks = await engine.searchUserTasks({ processInstanceKey: run.process_key });
+      const tasks = await engine.openUserTasks({ processInstanceKey: run.process_key });
       const task = tasks.find((t) => t.elementId === FEATURE_BLOCKED_ELEMENT);
       const parked = task ? { userTaskKey: task.userTaskKey } : null;
       const patch = deriveFeatureBlockedPatch(run, parked);
@@ -1577,7 +1577,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
       planSeen.add(plan.plan_key);
       let tasks: { userTaskKey: string; elementId?: string }[];
       try {
-        tasks = await engine.searchUserTasks({ processInstanceKey: plan.process_key });
+        tasks = await engine.openUserTasks({ processInstanceKey: plan.process_key });
       } catch (err) {
         console.error(`[poller] user tasks (plan ${plan.plan_key}): ${err}`);
         continue;
@@ -1632,7 +1632,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
       prSeen.add(pr.pr_key);
       let tasks: { userTaskKey: string; elementId?: string }[];
       try {
-        tasks = await engine.searchUserTasks({ processInstanceKey: pr.process_key });
+        tasks = await engine.openUserTasks({ processInstanceKey: pr.process_key });
       } catch (err) {
         console.error(`[poller] user tasks (pr ${pr.pr_key}): ${err}`);
         continue;

package/db/migrations/041_inter_epic_plan_deps.sql

@@ -0,0 +1,38 @@
+-- 041_inter_epic_plan_deps.sql — issue #292 slice S1: first-class INTER-epic dependency edge.
+--
+-- `plan_task_deps` (005_plan_deps.sql) records the INTRA-epic task DAG — edges that order tasks
+-- *within a single plan* into waves. There is no way today to say "epic B depends-on epic A": that
+-- the whole of epic B must wait until epic A has published a capability before B may fan out.
+--
+-- This table adds that second, coarser grain: one row per INTER-epic edge. `plan_key` is the
+-- dependent/consumer epic that waits; `depends_on_plan_key` is the producer epic it waits for. The
+-- edge also carries the GATING CONTRACT DESCRIPTOR the later capability probe (slice S3) needs to
+-- resolve which published `pkg@version` first carries the awaited capability: `package` is the
+-- producer's published package name, and `capability_ref` is the producer epic's issue handle used
+-- to resolve that version. This slice (S1) only lands the durable schema + typed read/write surface;
+-- admission (S2), lowering into a readiness gate (S3), and visibility (S4) build on it later.
+--
+-- Constraints mirror how `plan_task_deps` is constrained:
+--   • PRIMARY KEY (plan_key, depends_on_plan_key) — one edge per consumer→producer pair, so a
+--     re-submitted set cannot duplicate an edge.
+--   • CHECK (plan_key <> depends_on_plan_key) — an epic cannot depend on itself.
+--   • plan_key REFERENCES plans(plan_key) — the consumer is an admitted plan (as plan_task_deps FKs
+--     its plan_key). `depends_on_plan_key` is intentionally NOT FK-constrained: a batch admission
+--     (S2) may insert edges before every producer row exists, and the set validator enforces that
+--     every edge names a submitted epic. An index on plan_key backs the inbound read.
+--
+-- Numbered after the current highest prefix on origin/main (040); the runner wraps each file in its
+-- own transaction, so this file must NOT contain BEGIN/COMMIT.
+
+CREATE TABLE plan_deps (
+  plan_key            TEXT NOT NULL REFERENCES plans(plan_key),  -- dependent/consumer epic that waits
+  depends_on_plan_key TEXT NOT NULL,                             -- producer epic it waits for
+  package             TEXT NOT NULL,                             -- producer's published package name
+  capability_ref      TEXT NOT NULL,                             -- producer epic issue handle → pkg@version
+  created_at          TEXT NOT NULL,
+  PRIMARY KEY (plan_key, depends_on_plan_key),
+  CHECK (plan_key <> depends_on_plan_key)
+);
+
+CREATE INDEX idx_plan_deps_plan ON plan_deps(plan_key);
+CREATE INDEX idx_plan_deps_producer ON plan_deps(depends_on_plan_key);

package/package.json

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