@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/e2e/convergence-escalation.e2e.ts

@@ -0,0 +1,180 @@
+// End-to-end proof for the PR review-loop escalation → native userTask + form (epic #156, slice
+// U4, issues #597/#599). Boots this whole Urban app in-process against the WASM engine via
+// `bootTestApp` and proves the migrated escalation round-trip:
+//
+//   start convergence-loop → the review agent returns `needs_input` with a question → the loop
+//   parks on the native `wait-answer` userTask (linked to `pr-escalation.form`), NOT the retired
+//   `escalation-answered` message catch → the open escalation is derived from the durable
+//   `escalations` audit row (surfaced on GET /app/api/status as `openEscalation`, with NO
+//   denormalised PR-row pointer) → an operator completes the task through the taskInbox surface
+//   with the typed `{ answer }` → the `record-answer` step retires the escalations row to
+//   `answered` and the loop resumes and the answer reaches the next review round.
+//
+// The falsifiable core (mirroring the U0 spine e2e): the WASM engine folds a completed instance's
+// variables away, so "resumes WITH the typed answer" is proven by capturing `job.variables.answer`
+// on the review agent's SECOND activation — an empty/wrong completion would surface a different
+// value. The `senior:pr-review` task is an `externalTaskType` (no app worker), so the test
+// registers a stateful stub for it: needs_input first, converged (capturing the answer) second.
+//
+// Network isolation mirrors the sibling convergence e2e: the app's GitHub transport is forced to
+// `token` mode with no token, so any best-effort GitHub read short-circuits instead of reaching out.
+//
+// Run with `npm run e2e` (a dedicated node:test invocation, kept out of the fast unit `npm test`).
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-u4-"));
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+const HARNESS_ENV = {
+  NANO_APP_DB_URL: `file:${join(DB_DIR, "app.db")}`,
+} as const;
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+}
+
+interface StatusBody {
+  prs: Array<{ prKey: string; status: string; openEscalation: string | null }>;
+}
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+describe("nano-workforce PR review-loop escalation (U4 userTask)", () => {
+  let app: TestApp;
+  // The review agent stub's captured state across activations.
+  let reviewCalls = 0;
+  let capturedAnswer: unknown;
+
+  before(async () => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV });
+    // `senior:pr-review` is an externalTaskType (no app worker), so register a stateful stub:
+    // round 1 escalates (needs_input + question); round 2 captures the resume `answer` and converges.
+    await app.engine.registerWorker("senior:pr-review", (job) => {
+      reviewCalls += 1;
+      if (reviewCalls === 1) {
+        return { status: "needs_input", summary: "need a human decision", question: "Which retry cap?" };
+      }
+      capturedAnswer = (job.variables as Record<string, unknown>).answer;
+      return { status: "converged", summary: "resolved after the human answer" };
+    });
+  });
+
+  after(async () => {
+    await app?.stop();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(DB_DIR, { recursive: true, force: true });
+  });
+
+  test("a review-loop escalation parks on a userTask; completing it with {answer} resumes the loop", async () => {
+    const api = app.api;
+    assert.ok(api, "the OpenAPI driver is available");
+
+    const prKey = "acme/widgets#77";
+    const started = await api.call<{ prKey: string }>("startConvergenceLoop", {
+      body: { pr: prKey, convergeOnly: true },
+    });
+    assert.equal(started.status, 202, "start returns 202 Accepted");
+
+    const prs = app.db.table<{ pr_key: string; status: string; process_key: string | null }>(
+      "pull_requests",
+      "pr_key",
+    );
+    const row = await prs.findOne({ pr_key: prKey });
+    assert.ok(row?.process_key, "the PR row carries the engine process-instance key");
+    const processInstanceKey = row!.process_key!;
+
+    // Drain the first review round: needs_input routes through persist-escalation (which sets the
+    // PR `escalated` and returns the `question`) and parks on the native `wait-answer` userTask.
+    await app.settle();
+    assert.equal(reviewCalls, 1, "the review agent ran exactly once before parking");
+
+    // The escalation is a native userTask — visible through the taskInbox surface, NOT a message wait.
+    const listed = await app.callRoute<InboxTask[]>({
+      method: "GET",
+      path: "/tasks/api/tasks",
+      query: { processInstanceKey },
+    });
+    assert.equal(listed.status, 200, "the taskInbox surface serves the task list");
+    assert.equal(listed.body.length, 1, "exactly one escalation userTask is open");
+    const task = listed.body[0];
+    assert.equal(task.elementId, "wait-answer", "the open task is the review-loop escalation userTask");
+    assert.ok(task.userTaskKey, "the task carries a completable userTaskKey");
+
+    // The open escalation is DERIVED from the durable `escalations` audit row on the status
+    // endpoint — no denormalised `open_escalation_*` pointer is written or read.
+    const status = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
+    assert.equal(status.status, 200, "the status endpoint responds");
+    const statusRow = status.body.prs.find((p) => p.prKey === prKey);
+    assert.ok(statusRow, "the escalated PR is listed as active");
+    assert.equal(statusRow?.status, "escalated", "the PR reads as escalated");
+    assert.equal(
+      statusRow?.openEscalation,
+      "Which retry cap?",
+      "the open escalation question is derived from the open escalations row",
+    );
+
+    // Complete the escalation through the taskInbox completion route with the typed `answer`.
+    const answer = "Cap the retries at 5 and proceed.";
+    const completed = await app.callRoute<{ ok: boolean }>({
+      method: "POST",
+      path: "/tasks/api/complete",
+      body: JSON.stringify({ userTaskKey: task.userTaskKey, variables: { answer } }),
+    });
+    assert.equal(completed.status, 200, "the completion route accepts the typed submission");
+    assert.equal(completed.body.ok, true, "the userTask was completed");
+
+    // The typed answer resumed the loop back into the review round: the token took
+    // wait-answer → record-answer (which retires the escalations row) → review-round, and the
+    // review agent saw exactly the submitted answer. An empty or wrong completion would surface a
+    // different `capturedAnswer` — this is the falsifiable core.
+    await app.settle();
+    const flows = takenFlows(app);
+    assert.ok(
+      flows.includes("wait-answer->record-answer") && flows.includes("record-answer->review-round"),
+      `the answer resumed the loop through record-answer back to the review round (flows: ${flows.join(", ")})`,
+    );
+    assert.equal(reviewCalls, 2, "the review agent ran a second round after the answer");
+    assert.equal(capturedAnswer, answer, "the typed answer reached the resumed review round");
+
+    // The escalations row was retired to `answered` (the single source of truth the status endpoint
+    // derives from), so no open escalation lingers on the status endpoint once answered + resumed.
+    const afterStatus = await app.callRoute<StatusBody>({ method: "GET", path: "/app/api/status" });
+    const afterRow = afterStatus.body.prs.find((p) => p.prKey === prKey);
+    if (afterRow) {
+      assert.equal(afterRow.openEscalation, null, "no open escalation lingers after the answer");
+    }
+  });
+});

package/e2e/convergence-loop.e2e.ts

@@ -183,7 +183,7 @@ describe("nano-workforce e2e (urban-testkit pilot)", () => {
 
     // Advance past the instanceTracking pollMs (derived from nano.app.json above, plus a margin):
     // the reconciler observes TERMINATED and applies the manifest `onTerminated.set` → status
-    // `abandoned`, escalation pointers cleared.
+    // `abandoned`.
     await app.advanceTime(PR_POLL_MS + 1000);
     const reconciled = await prs.findOne({ pr_key: prKey });
     assert.equal(reconciled?.status, "abandoned", "reconciler abandoned the terminated PR's row");

package/e2e/feature-run.e2e.ts

@@ -0,0 +1,231 @@
+// End-to-end proof for the single-issue feature run (issue #172). Boots the whole app against the
+// WASM engine and drives the REAL feature.bpmn through its three outcomes:
+//   • raise-only — the agent opens a PR, `converge` is off → the run ends at `opened`, no hand-off;
+//   • raise + converge — with `converge` on, the opened PR is enrolled into the convergence loop
+//     (a `pull_requests` row appears) and the feature_run lands `converging`;
+//   • escalate + resume — the agent escalates, a native `feature-escalation` user task parks the
+//     run, and answering re-dispatches the SAME implement task (mirrors the epic slice).
+//
+// The gateway assertions are the falsifiable core: the WASM engine folds a completed instance's
+// variables away, so we assert on the cumulative taken sequence flows (an empty/wrong result takes a
+// different, default branch). Each scenario boots its own app so `takenSequenceFlows`
+// (engine-global, cumulative) reflects exactly one instance's routing.
+//
+// Run with `npm run e2e`.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import type { EngineJob } from "@nanobpm/urban/runtime";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+}
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+type Stub = (job: EngineJob) => Record<string, unknown> | void;
+
+interface FeatureRow {
+  feature_key: string;
+  process_key: string | null;
+  status: string;
+  pr_key: string | null;
+}
+interface PrRow {
+  pr_key: string;
+}
+
+describe("single-issue feature run (#172 — feature.bpmn)", () => {
+  const savedEnv = new Map<string, string | undefined>();
+  let restoreGithub: (() => void) | undefined;
+
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    // ADR 0003: `startFeature` + the `pr.ensure-base-branch` head task pass through base admission,
+    // which reads/creates the base ref. Pin the hermetic `token` transport + fetch stub.
+    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+  });
+
+  after(() => {
+    restoreGithub?.();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  /** Boot a fresh app (isolated engine + DB), register the given `senior:*` stubs, run `body`, and
+   *  tear down. Each scenario gets its own engine so `takenSequenceFlows` is that run's alone. */
+  async function withApp(
+    stubs: Record<string, Stub>,
+    startBody: Record<string, unknown>,
+    body: (ctx: { app: TestApp; featureKey: string; processKey: string }) => Promise<void>,
+  ): Promise<void> {
+    const dbDir = mkdtempSync(join(tmpdir(), "nwf-f172-"));
+    const app = await bootTestApp(APP_ROOT, {
+      env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` },
+    });
+    try {
+      for (const [jobType, stub] of Object.entries(stubs)) {
+        await app.engine.registerWorker(jobType, async (job) => stub(job) ?? undefined);
+      }
+      const featureKey = "owner/repo#7";
+      const started = await app.api?.call("startFeature", { body: { issue: featureKey, ...startBody } });
+      assert.equal(started?.status, 202, "startFeature accepted the issue");
+      await app.settle();
+      const run = await app.db
+        .table<FeatureRow>("feature_runs", "feature_key")
+        .findOne({ feature_key: featureKey });
+      assert.ok(run?.process_key, "the feature_runs row carries the engine process-instance key");
+      await body({ app, featureKey, processKey: run!.process_key! });
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  }
+
+  async function featureRow(app: TestApp, featureKey: string): Promise<FeatureRow> {
+    const run = await app.db.table<FeatureRow>("feature_runs", "feature_key").findOne({ feature_key: featureKey });
+    assert.ok(run, `feature_runs row for ${featureKey} exists`);
+    return run!;
+  }
+
+  test("raise-only: an opened PR ends the run at `opened`, taking the raise-only branch", async () => {
+    await withApp(
+      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#101", summary: "built it" }) },
+      { baseBranch: "epic/e2e" },
+      async ({ app, featureKey }) => {
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-converge->End"),
+          `converge=false took the raise-only branch (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(!flows.includes("gw-converge->converge"), "the converge hand-off branch was NOT taken");
+
+        const run = await featureRow(app, featureKey);
+        assert.equal(run.status, "opened", "the run settled at opened");
+        assert.equal(run.pr_key, "owner/repo#101", "the raised PR key was recorded");
+
+        const prs = await app.db.table<PrRow>("pull_requests", "pr_key").find({});
+        assert.equal(prs.length, 0, "raise-only did NOT enroll the PR into the convergence loop");
+      },
+    );
+  });
+
+  test("raise + converge: the opened PR is enrolled into the convergence loop", async () => {
+    await withApp(
+      { "senior:feature": () => ({ status: "opened", pr: "owner/repo#102", summary: "built it" }) },
+      { baseBranch: "epic/e2e", converge: true },
+      async ({ app, featureKey }) => {
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("gw-converge->converge"),
+          `converge=true took the hand-off branch (flows: ${flows.join(", ")})`,
+        );
+
+        const run = await featureRow(app, featureKey);
+        assert.equal(run.status, "converging", "the run settled at converging");
+
+        const pr = await app.db.table<PrRow>("pull_requests", "pr_key").findOne({ pr_key: "owner/repo#102" });
+        assert.ok(pr, "converge enrolled the raised PR into pull_requests (submitPr hand-off)");
+      },
+    );
+  });
+
+  test("blocked: a non-opened result never enrolls a PR and settles blocked", async () => {
+    await withApp(
+      { "senior:feature": () => ({ status: "blocked", summary: "could not proceed" }) },
+      { baseBranch: "epic/e2e", converge: true },
+      async ({ app, featureKey }) => {
+        const flows = takenFlows(app);
+        assert.ok(flows.includes("gw-converge->End"), "a blocked run takes the raise-only branch even with converge=true");
+        const run = await featureRow(app, featureKey);
+        assert.equal(run.status, "blocked");
+        assert.equal(run.pr_key, null);
+      },
+    );
+  });
+
+  test("escalate + resume: a native userTask parks the run; answering re-dispatches implement-task", async () => {
+    let calls = 0;
+    await withApp(
+      {
+        "senior:feature": () => {
+          calls += 1;
+          return calls === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "opened", pr: "owner/repo#103", summary: "resumed and opened" };
+        },
+      },
+      { baseBranch: "epic/e2e" },
+      async ({ app, processKey }) => {
+        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+
+        await app.engine.completeUserTask(task!.userTaskKey, { resolution: "answer", answer: "use v2" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->implement-task"),
+          `answer re-dispatched the same implement task (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(!flows.includes("w_gw_answer->record-feature"), "the abandon (default) flow was NOT taken");
+        assert.equal(calls, 2, "the implementation agent was re-dispatched exactly once after the answer");
+      },
+    );
+  });
+
+  test("escalate + abandon: abandoning routes to record-feature (default flow)", async () => {
+    await withApp(
+      {
+        "senior:feature": () => ({ status: "escalated", question: "Blocked — abandon?", summary: "parked" }),
+      },
+      { baseBranch: "epic/e2e" },
+      async ({ app, processKey }) => {
+        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "feature-escalation") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the feature escalation parked a completable native user task");
+
+        await app.engine.completeUserTask(task!.userTaskKey, { resolution: "abandon" });
+        await app.settle();
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->record-feature"),
+          `abandon routed to record-feature (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(!flows.includes("w_gw_answer->implement-task"), "the answer loop was NOT taken");
+      },
+    );
+  });
+});

package/e2e/plan-fanout-sla.e2e.ts

@@ -0,0 +1,238 @@
+// End-to-end proof for the escalation-of-the-escalation SLA timer boundaries and operator
+// assignment on the plan-fanout escalation user tasks (epic #156, slice U5). Boots the whole app
+// against the WASM engine + virtual clock and drives the REAL plan-fanout.bpmn to each of its three
+// human-decision user tasks — the implementation-phase task escalation, the plan-review cap
+// escalation, and the trial-merge escalation — then, WITHOUT answering, advances the virtual clock
+// past the seeded `escalationSlaTimeout` so each task's interrupting timer boundary fires. It
+// asserts the token took the boundary's safe-default auto-proceed arm (never the human-answer arm),
+// and that each escalation task is discoverable by its `operators` candidate group (and not by a
+// bogus group) — i.e. the inbox is assignment-filterable.
+//
+// The boundary path is the falsifiable core (mirroring U0/U2): the WASM engine folds a completed
+// instance's variables away, so we assert on the cumulative taken sequence flows. An unanswered task
+// with no SLA boundary would simply hang — never taking a boundary flow — so a green here proves the
+// durable in-process liveness the slice lands. Each scenario boots its own app so `takenSequenceFlows`
+// (engine-global, cumulative) reflects exactly one instance's routing.
+//
+// Run with `npm run e2e`.
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join, resolve } from "node:path";
+import { after, before, describe, test } from "node:test";
+import { fileURLToPath } from "node:url";
+import type { EngineJob } from "@nanobpm/urban/runtime";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+import { admitGithubState, installAdmitGithub } from "./support/github-admit.ts";
+
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+
+// Advance well past the default escalation SLA (PT24H) so every armed boundary timer is due.
+const PAST_SLA_MS = 25 * 60 * 60 * 1000;
+
+interface InboxTask {
+  userTaskKey: string;
+  elementId?: string;
+  variables?: Record<string, unknown>;
+}
+
+interface TakenFlow {
+  from: string;
+  to: string;
+}
+
+function takenFlows(app: TestApp): string[] {
+  const snapshot = app.snapshot();
+  const flows = Array.isArray(snapshot.takenSequenceFlows) ? snapshot.takenSequenceFlows : [];
+  return flows
+    .filter((f): f is TakenFlow => typeof f === "object" && f !== null && "from" in f && "to" in f)
+    .map((f) => `${f.from}->${f.to}`);
+}
+
+type Stub = (job: EngineJob) => Record<string, unknown> | void;
+
+describe("plan-fanout escalation SLA + assignment (U5)", () => {
+  const savedEnv = new Map<string, string | undefined>();
+  let restoreGithub: (() => void) | undefined;
+
+  before(() => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    // ADR 0003: `startPlanFanout` + the `pr.ensure-base-branch` head task now pass through base
+    // admission, which reads/creates the base ref. Pin the hermetic `token` transport + fetch stub.
+    restoreGithub = installAdmitGithub(admitGithubState("owner/repo", "main"));
+  });
+
+  after(() => {
+    restoreGithub?.();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+  });
+
+  async function withApp(
+    stubs: Record<string, Stub>,
+    body: (ctx: { app: TestApp; planKey: string; processKey: string }) => Promise<void>,
+  ): Promise<void> {
+    const dbDir = mkdtempSync(join(tmpdir(), "nwf-u5-"));
+    const app = await bootTestApp(APP_ROOT, {
+      env: { NANO_APP_DB_URL: `file:${join(dbDir, "app.db")}` },
+    });
+    try {
+      for (const [jobType, stub] of Object.entries(stubs)) {
+        await app.engine.registerWorker(jobType, async (job) => stub(job) ?? undefined);
+      }
+      const planKey = "owner/repo#1";
+      const started = await app.api?.call("startPlanFanout", { body: { issue: planKey, baseBranch: "epic/e2e" } });
+      assert.equal(started?.status, 202, "startPlanFanout accepted the issue");
+      await app.settle();
+      const plan = await app.db
+        .table<{ plan_key: string; process_key: string | null }>("plans", "plan_key")
+        .findOne({ plan_key: planKey });
+      assert.ok(plan?.process_key, "the plan row carries the engine process-instance key");
+      await body({ app, planKey, processKey: plan!.process_key! });
+    } finally {
+      await app.stop();
+      rmSync(dbDir, { recursive: true, force: true });
+    }
+  }
+
+  async function openTask(app: TestApp, processKey: string, elementId: string): Promise<InboxTask> {
+    const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+    const match = tasks.find((t) => t.elementId === elementId);
+    assert.ok(match, `expected an open ${elementId} user task (open: ${tasks.map((t) => t.elementId).join(", ")})`);
+    return match!;
+  }
+
+  /** Assert the escalation task is discoverable by the `operators` candidate group (the inbox
+   *  filter) and NOT by a bogus group — proving `zeebe:assignmentDefinition candidateGroups` took. */
+  async function assertAssignmentFilterable(app: TestApp, processKey: string, elementId: string) {
+    const byOperators = await app.engine.searchUserTasks({
+      processInstanceKey: processKey,
+      candidateGroup: "operators",
+    });
+    assert.ok(
+      byOperators.some((t) => t.elementId === elementId),
+      `${elementId} is filterable by the operators candidate group`,
+    );
+    const byBogus = await app.engine.searchUserTasks({
+      processInstanceKey: processKey,
+      candidateGroup: "nobody-here",
+    });
+    assert.ok(
+      !byBogus.some((t) => t.elementId === elementId),
+      `${elementId} is NOT surfaced under a group it does not belong to`,
+    );
+  }
+
+  const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
+  const approveReview: Stub = () => ({ approved: true, findings: "" });
+
+  test("task escalation: an unanswered task hits its SLA boundary and auto-abandons the slice", async () => {
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => ({
+          status: "escalated",
+          question: "Which API should I use?",
+          summary: "parked for a human",
+        }),
+      },
+      async ({ app, processKey }) => {
+        await openTask(app, processKey, "feature-escalation");
+        await assertAssignmentFilterable(app, processKey, "feature-escalation");
+
+        // Never answer — let the SLA elapse. The interrupting boundary cancels the parked task and
+        // routes to the task-done end (the safe auto-abandon default).
+        await app.advanceTime(PAST_SLA_MS);
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("be_feature_sla->w_end"),
+          `the SLA boundary auto-abandoned to the task-done end (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("w_gw_answer->implement-task"),
+          "the human answer loop was NOT taken",
+        );
+      },
+    );
+  });
+
+  test("plan-review escalation: an unanswered task hits its SLA boundary and auto-revises", async () => {
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": () => ({ approved: false, findings: "not good enough" }),
+        "senior:feature": () => ({ status: "blocked", summary: "n/a" }),
+      },
+      async ({ app, processKey }) => {
+        await openTask(app, processKey, "plan-review-decision");
+        await assertAssignmentFilterable(app, processKey, "plan-review-decision");
+
+        await app.advanceTime(PAST_SLA_MS);
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("be_plan_sla->plan"),
+          `the SLA boundary auto-revised back to plan (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-plan-answer->select-wave"),
+          "the human proceed-override arm was NOT taken",
+        );
+      },
+    );
+  });
+
+  const twoTaskPlan: Stub = () => ({
+    tasks: [
+      { id: "t1", title: "T1", prompt: "do t1" },
+      { id: "t2", title: "T2", prompt: "do t2" },
+    ],
+  });
+  const openBothPrs: Stub = (job) => {
+    const taskId = (job.variables as { task?: { id?: string } }).task?.id;
+    return taskId === "t2"
+      ? { status: "opened", pr: "owner/repo#102", summary: "opened t2" }
+      : { status: "opened", pr: "owner/repo#101", summary: "opened t1" };
+  };
+  const trialSuiteFailed: Stub = () => ({ result: "suite-failed", failing: "combined suite red" });
+
+  test("trial-merge escalation: an unanswered task hits its SLA boundary and auto-reruns", async () => {
+    await withApp(
+      {
+        "senior:plan": twoTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": openBothPrs,
+        "senior:trial-merge": trialSuiteFailed,
+      },
+      async ({ app, processKey }) => {
+        await openTask(app, processKey, "trial-merge-decision");
+        await assertAssignmentFilterable(app, processKey, "trial-merge-decision");
+
+        await app.advanceTime(PAST_SLA_MS);
+
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("be_trial_sla->trial-merge"),
+          `the SLA boundary auto-reran the trial merge (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("gw-trial-answer->gw-more"),
+          "the human proceed arm was NOT taken",
+        );
+      },
+    );
+  });
+});