@nanobpm/nano-workforce 0.87.0 → 0.88.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [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)
+
+
+### Features
+
+* **service:** branch-scoped treeless clone for review-job repo envelope ([#287](https://github.com/nanobpm/nano-workforce/issues/287)) ([#288](https://github.com/nanobpm/nano-workforce/issues/288)) ([c90dc23](https://github.com/nanobpm/nano-workforce/commit/c90dc23274fbb5e19835e25eef755f88337ab86f)), closes [jwulf/c8ctl-plugin-nano#91](https://github.com/jwulf/c8ctl-plugin-nano/issues/91)
+
 # [0.87.0](https://github.com/nanobpm/nano-workforce/compare/v0.86.0...v0.87.0) (2026-08-18)
 
 

package/SPEC.md

@@ -193,9 +193,17 @@ Consequences the prompt (`resources/prompts/review-round.md`) encodes:
   `io.nanobpm.agentTask.repository.url`; the **app** supplies it — plus the head
   branch as `…repository.ref` — as a process variable at `createInstance`
   (`repoEnvelopeVars` in `app/service.ts`, resolving the head via `fetchPrMeta`/
-  `fetchPrHead`). The harness is PR-agnostic: it does **not** derive the head branch
-  from `prNumber`/`prUrl`. When the head can't be resolved the envelope is omitted and
-  the agent falls back to the worker's launch directory (the legacy behavior).
+  `fetchPrHead`). The envelope also carries clone-shaping fields so large monorepos
+  provision within the c8ctl clone timeout (issue #287): `singleBranch: true` and
+  `filter: "blob:none"` request a **branch-scoped, blobless partial clone** (trees are
+  still fetched up-front — a *treeless* clone would be `--filter=tree:0`; the full
+  commit graph is kept — no `--depth 1` — so `git merge-base` / the review 3-dot diff
+  stays correct while blobs fetch lazily), and, when the PR base branch is resolvable,
+  an optional `…repository.baseRef` so the harness fetches the base tip alongside the
+  head and keeps `origin/<base>` reachable for the diff. The harness is PR-agnostic: it
+  does **not** derive the head branch from `prNumber`/`prUrl`. When the head can't be
+  resolved the envelope is omitted and the agent falls back to the worker's launch
+  directory (the legacy behavior).
 
 ## 6. Signals
 
@@ -625,8 +633,11 @@ but encode incompatible decisions about a shared contract** — a genuine design
   integration provisions the repo and checks out the PR's head branch (it must
   already give the worker repo access to work at all). The **app** resolves the head
   branch and passes it in the `io.nanobpm.agentTask.repository.{url,ref}` envelope
-  (a `createInstance` process variable — see `repoEnvelopeVars`); the harness is
-  PR-agnostic and provisions from that envelope. The worker stays a pure provisioner.
+  (a `createInstance` process variable — see `repoEnvelopeVars`), along with the
+  branch-scoped, blobless clone-shaping fields (`singleBranch`, `filter`, optional
+  `baseRef`) that let large monorepos provision within the clone timeout (#287); the
+  harness is PR-agnostic and provisions from that envelope. The worker stays a pure
+  provisioner.
 - **review-ready via GitHub webhook** — same message, swappable faster trigger,
   when the app is publicly reachable. Deferred (poller-only for v1).
 - **Supervised vs external worker** — the agent runs as an external

package/app/contracts.ts

@@ -334,6 +334,15 @@ export const WIRE_CONTRACTS = {
       "Op-tagged relay control frame a worker terminal chunk producer emits and the hub consumes. The op-tagged shape superseded the legacy positional `{stream, offset, chunk}` frame (nano-ide #234/#236); a producer must emit the op-tagged shape or the hub rejects it as `malformed relay message payload`.",
     shape: '{ op: "produce", incarnation: number, stream: string, offset: number, chunk: string }',
   },
+  "io.nanobpm.agentTask.repository": {
+    category: "wire",
+    name: "io.nanobpm.agentTask.repository",
+    owner: "app/service.ts",
+    semantics:
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`) and the c8ctl worker harness consumes to provision an isolated clone on the PR head branch. Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable). Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).",
+    shape:
+      '{ provider: "github", url: string, ref: string, singleBranch: true, filter: "blob:none", baseRef?: string }',
+  },
 } as const satisfies Record<string, WireContract>;
 
 export const TYPE_CONTRACTS = {
@@ -345,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/github.ts

@@ -406,6 +406,10 @@ export interface PrMeta {
    * workspace checkout (`io.nanobpm.agentTask.repository.ref`) so the review agent lands on the
    * PR branch instead of the worker's launch directory. `null` when GitHub doesn't return it. */
   headRef: string | null;
+  /** The PR's base branch name (e.g. `main`). Emitted in the repository envelope so the c8ctl
+   * harness fetches the base tip alongside the single-branch head clone, keeping `git diff
+   * origin/<base>...HEAD` (the review 3-dot diff) computable. `null` when GitHub doesn't return it. */
+  baseRef: string | null;
 }
 
 export async function fetchPrMeta(
@@ -414,10 +418,10 @@ export async function fetchPrMeta(
   token: string,
 ): Promise<PrMeta | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body,headRefName"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body,headRefName,baseRefName"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { title?: string; body?: string; headRefName?: string | null };
-    return { title: j.title ?? null, body: j.body ?? "", headRef: j.headRefName ?? null };
+    const j = JSON.parse(out) as { title?: string; body?: string; headRefName?: string | null; baseRefName?: string | null };
+    return { title: j.title ?? null, body: j.body ?? "", headRef: j.headRefName ?? null, baseRef: j.baseRefName ?? null };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -425,8 +429,8 @@ export async function fetchPrMeta(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { title?: string; body?: string; head?: { ref?: string | null } };
-  return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null };
+  const j = (await r.json()) as { title?: string; body?: string; head?: { ref?: string | null }; base?: { ref?: string | null } };
+  return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null, baseRef: j.base?.ref ?? null };
 }
 
 /** Fetch an issue's title via the configured transport, mirroring `fetchPrMeta` (both `gh` and
@@ -666,12 +670,12 @@ export async function fetchPrHead(
   repo: string,
   number: number | string,
   token: string,
-): Promise<{ headRef: string | null; headSha: string | null } | null> {
+): Promise<{ headRef: string | null; headSha: string | null; baseRef: string | null } | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "headRefName,headRefOid,baseRefName"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null };
-    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null };
+    const j = JSON.parse(out) as { headRefName?: string | null; headRefOid?: string | null; baseRefName?: string | null };
+    return { headRef: j.headRefName ?? null, headSha: j.headRefOid ?? null, baseRef: j.baseRefName ?? null };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -679,8 +683,8 @@ export async function fetchPrHead(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null } };
-  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null };
+  const j = (await r.json()) as { head?: { ref?: string | null; sha?: string | null }; base?: { ref?: string | null } };
+  return { headRef: j.head?.ref ?? null, headSha: j.head?.sha ?? null, baseRef: j.base?.ref ?? null };
 }
 
 /** The PR's current base branch ref — the branch this PR would land *into*. `null` when no

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.test.ts

@@ -439,11 +439,26 @@ test("startMerge reads root_request_key off the PR row onto the merge instance",
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness
 // falls back to the legacy launch-dir behavior instead of cloning the wrong default branch).
 test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch", () => {
-  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12");
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12", "main");
   const env = (vars as any)["io.nanobpm.agentTask"];
   assertEquals(env.repository.url, "https://github.com/owner/repo.git");
   assertEquals(env.repository.ref, "feat/issue-12");
   assertEquals(env.repository.provider, "github");
+  // Branch-scoped, blobless partial clone (issue #287): large monorepos provision within the clone
+  // timeout while the full commit graph is kept so `git diff origin/<base>...HEAD` has a merge-base.
+  assertEquals(env.repository.singleBranch, true);
+  assertEquals(env.repository.filter, "blob:none");
+  // The base branch is emitted so the harness fetches its tip, keeping `origin/<base>` reachable.
+  assertEquals(env.repository.baseRef, "main");
+});
+
+test("repoEnvelopeVars omits baseRef when the base branch is unresolved", () => {
+  const env = (repoEnvelopeVars("owner/repo", "feat/issue-12") as any)["io.nanobpm.agentTask"];
+  // The single-branch/blobless partial-clone request still stands without a base ref…
+  assertEquals(env.repository.singleBranch, true);
+  assertEquals(env.repository.filter, "blob:none");
+  // …but `baseRef` is omitted entirely rather than emitted as null (no key at all).
+  assertEquals("baseRef" in env.repository, false);
 });
 
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {

package/app/service.ts

@@ -323,8 +323,18 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * a usable checkout for repos already present locally). `ref` MUST be the PR head branch; when it
  * is unresolved we emit nothing (no `repository.url`) so the harness falls back to the legacy
  * launch-dir behavior rather than silently cloning the repo's default branch. The static
- * `task.prompt` header on the service task deep-merges with this over the same namespace. */
-export function repoEnvelopeVars(repo: string, ref: string | null): Record<string, unknown> {
+ * `task.prompt` header on the service task deep-merges with this over the same namespace.
+ *
+ * The clone is requested **branch-scoped and blobless** (`singleBranch: true` + `filter:
+ * "blob:none"`) so large monorepos (e.g. `camunda/camunda`, ~1.16 GB) provision within the c8ctl
+ * clone timeout instead of full-cloning the whole history (issue #287). `blob:none` is a *blobless*
+ * partial clone (trees are still fetched up-front — a *treeless* clone would be `--filter=tree:0`); it
+ * keeps the full *commit graph* (so `git merge-base` / the review 3-dot diff stays correct) while
+ * fetching file blobs lazily — small upfront, correct diffs. `--depth 1` is deliberately NOT used:
+ * it would drop the merge-base and break `git diff origin/<base>...HEAD`. When the PR base branch
+ * is known we also emit `baseRef` so the harness fetches the base tip alongside the head, keeping
+ * that base reachable for the diff. */
+export function repoEnvelopeVars(repo: string, ref: string | null, baseRef: string | null = null): Record<string, unknown> {
   if (!ref) return {};
   // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
   // `owner/repo`), but this is an exported helper the fan-out epic gives many new callers. A repo
@@ -336,7 +346,20 @@ export function repoEnvelopeVars(repo: string, ref: string | null): Record<strin
   if (!/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(repo) || /\.git$/i.test(repo)) return {};
   return {
     [AGENT_TASK_NS]: {
-      repository: { provider: "github", url: `https://github.com/${repo}.git`, ref },
+      repository: {
+        provider: "github",
+        url: `https://github.com/${repo}.git`,
+        ref,
+        // Branch-scoped, blobless partial clone (issue #287): fetch only the head branch with lazy
+        // blobs so large monorepos provision within the clone timeout. Single-branch + blob:none
+        // (not --depth 1) preserves the commit graph so the review's `git diff origin/<base>...HEAD`
+        // has a valid merge-base. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91).
+        singleBranch: true,
+        filter: "blob:none",
+        // The base branch this PR targets — emitted so the harness fetches its tip alongside the
+        // single-branch head, keeping `origin/<base>` reachable for the diff. Omitted when unknown.
+        ...(baseRef ? { baseRef } : {}),
+      },
     },
   };
 }
@@ -364,12 +387,14 @@ export async function submitPr(
   const token = process.env.GITHUB_TOKEN ?? "";
   let title: string | null = null;
   let headRef: string | null = null;
+  let baseRef: string | null = null;
   const depKeys = new Set(dependsOn.map((d) => parsePr(d)?.prKey).filter((k): k is string => !!k));
   try {
     const meta = await fetchPrMeta(parsed.repo, parsed.number, token);
     if (meta) {
       title = meta.title;
       headRef = meta.headRef;
+      baseRef = meta.baseRef;
       for (const k of parseDependsOn(meta.body)) depKeys.add(k);
     }
   } catch (err) {
@@ -468,7 +493,7 @@ export async function submitPr(
       // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
       // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
       // unresolved head (`{}`) leaves the other vars untouched.
-      ...repoEnvelopeVars(parsed.repo, headRef),
+      ...repoEnvelopeVars(parsed.repo, headRef, baseRef),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -504,8 +529,11 @@ export async function startMerge(
   // means the envelope is omitted and the agent falls back to the worker's launch dir.
   const token = process.env.GITHUB_TOKEN ?? "";
   let headRef: string | null = null;
+  let baseRef: string | null = null;
   try {
-    headRef = (await fetchPrHead(pr.repo, pr.number, token))?.headRef ?? null;
+    const head = await fetchPrHead(pr.repo, pr.number, token);
+    headRef = head?.headRef ?? null;
+    baseRef = head?.baseRef ?? null;
   } catch (err) {
     console.warn(`[startMerge] ${pr.prKey} head branch fetch: ${err}`);
   }
@@ -531,7 +559,7 @@ export async function startMerge(
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
       // fix-ci/rebase agents operate on an isolated checkout of the PR head branch.
-      ...repoEnvelopeVars(pr.repo, headRef),
+      ...repoEnvelopeVars(pr.repo, headRef, baseRef),
     },
   });
   if (processInstanceKey != null) {
@@ -1382,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);
@@ -1416,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);
@@ -1549,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;
@@ -1604,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.87.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",

package/pages/overview.page.json

@@ -67,6 +67,7 @@
         "columns": [
           { "field": "title", "template": "{{title}}", "header": "Item", "subtitleField": "pr_key", "truncate": true, "width": "36%", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
+          { "field": "incident_message", "header": "Incident", "truncate": true, "badge": { "tone": "danger", "label": "1" } },
           { "field": "current_round", "template": "{{current_round}} · {{active_worker}}", "header": "Round · Agent" },
           { "field": "updated_at", "header": "Updated", "width": "9rem" }
         ]