@nanobpm/nano-workforce 0.56.0 → 0.58.0

package/app/roundResultDefault.test.ts

@@ -15,8 +15,9 @@
 // repo's lightweight model-guard style (see mergeRebaseArm.test.ts).
 
 import { test } from "node:test";
-import { assert, assertStringIncludes } from "#test-assert";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { readFileSync } from "node:fs";
+import { routeRoundResult } from "./roundResultDefault.ts";
 
 const bpmn = readFileSync("resources/processes/convergence-loop.bpmn", "utf8");
 
@@ -59,12 +60,18 @@ test("gw-status defaults to the addressed arm, not escalation", () => {
   );
 });
 
-test("escalation is an explicit needs_input/blocked arm", () => {
+test("escalation is an explicit needs_input/blocked arm gated on a non-blank question", () => {
   const esc = flowElement("f_escalate");
   assert(esc, "f_escalate flow missing");
   assertStringIncludes(esc, 'targetRef="persist-escalation"');
   // Escalation now only fires on an explicit human-blocking status.
   assertStringIncludes(esc, 'status = "needs_input" or status = "blocked"');
+  // ...AND only when the round carries an answerable question. A blank/absent/whitespace-only
+  // question can no longer route to escalation (retires the blank-question fabrication failure
+  // mode); it falls through to the addressed default and re-enters the review wait. The guard
+  // trims so a whitespace-only question ("   ") is treated as blank too.
+  assertStringIncludes(esc, 'question != null');
+  assertStringIncludes(esc, 'trim(question) != ""');
 });
 
 test("the default (addressed) arm carries no condition and re-enters the guard", () => {
@@ -92,3 +99,105 @@ test("regression: an empty/unknown status no longer routes to persist-escalation
   const addressed = flowElement("f_addressed");
   assert(addressed && /targetRef="gw-guard"/.test(addressed), "default arm must re-enter gw-guard");
 });
+
+// The canonical router (app/roundResultDefault.ts) mirrors the gw-status routing above, with the
+// escalation decision delegated to the single taxonomy. These unit tests pin its behaviour — the
+// same rules the structural BPMN assertions above enforce on the committed model.
+
+test("routeRoundResult: a converged round converges", () => {
+  assertEquals(routeRoundResult("converged", null), "converged");
+  assertEquals(routeRoundResult("converged", "ignored"), "converged");
+});
+
+test("routeRoundResult: a human-blocking status with a question escalates", () => {
+  assertEquals(routeRoundResult("needs_input", "please decide"), "escalate");
+  assertEquals(routeRoundResult("blocked", "please decide"), "escalate");
+});
+
+test("routeRoundResult: a blank-question human-blocking status re-enters the loop (no fabrication)", () => {
+  for (const status of ["needs_input", "blocked"]) {
+    for (const question of [undefined, null, "", "   "]) {
+      assertEquals(
+        routeRoundResult(status, question),
+        "reenter",
+        `blank-question ${status} must re-enter the review wait, not escalate`,
+      );
+    }
+  }
+});
+
+test("routeRoundResult: an addressed/unknown/empty status re-enters the loop", () => {
+  for (const status of [undefined, "", "addressed", "waiting", "in_progress"]) {
+    assertEquals(routeRoundResult(status, "q"), "reenter", `status ${JSON.stringify(status)} re-enters`);
+  }
+});
+
+test("routeRoundResult: status is matched exactly, mirroring the untrimmed gw-status conditions", () => {
+  // The gw-status gateway conditions do NOT trim `status` (unlike `question`, which trims for
+  // blank-detection). `status` is a machine enum, so a whitespace-padded token is NOT the enum
+  // value: it must route exactly as the deployed model does — never converge/escalate in code
+  // while the model re-enters. This pins the no-drift contract.
+  assertEquals(routeRoundResult("converged ", null), "reenter", "'converged ' is not the enum → re-enter");
+  assertEquals(routeRoundResult(" converged", null), "reenter", "' converged' is not the enum → re-enter");
+  assertEquals(routeRoundResult("needs_input ", "q"), "reenter", "'needs_input ' is not the enum → re-enter");
+  assertEquals(routeRoundResult("blocked ", "q"), "reenter", "'blocked ' is not the enum → re-enter");
+});
+
+// --- Liveness guard: a non-escalation early return must not wedge on the durable answer-wait. ---
+// `persist-escalation` may complete WITHOUT opening an escalation (worker returns
+// `escalated:false` for a blank-question / non-decision-required job — defence-in-depth). The
+// model must branch on that output so such a token re-enters the loop instead of flowing into
+// `wait-answer`, which would block forever with no escalation for a human to answer.
+
+test("persist-escalation routes through the gw-escalated liveness gateway, not straight to wait-answer", () => {
+  // The only flow out of persist-escalation goes to the gateway.
+  const escOut = allFlows().filter((f) => /sourceRef="persist-escalation"/.test(f));
+  assertEquals(escOut.length, 1, "persist-escalation must have exactly one outgoing flow");
+  assertStringIncludes(escOut[0], 'targetRef="gw-escalated"');
+  // No flow leaves persist-escalation directly for wait-answer.
+  assert(
+    !escOut.some((f) => /targetRef="wait-answer"/.test(f)),
+    "persist-escalation must not flow directly into wait-answer",
+  );
+});
+
+test("gw-escalated waits only when an escalation was opened, else re-enters the guard", () => {
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-escalated"[^>]*>/);
+  assert(gw, "gw-escalated gateway missing");
+  // Its default arm must be the re-enter (no-escalation) arm, never the answer-wait.
+  assertStringIncludes(gw[0], 'default="f_escReenter"');
+
+  // The wait arm is guarded on the worker's `escalated` output — a token only reaches the
+  // durable answer-wait when an escalation actually exists.
+  const wait = flowElement("f_escWait");
+  assert(wait, "f_escWait flow missing");
+  assertStringIncludes(wait, 'sourceRef="gw-escalated"');
+  assertStringIncludes(wait, 'targetRef="wait-answer"');
+  assertStringIncludes(wait, "escalated = true");
+
+  // The default (no-escalation) arm carries no condition and re-enters gw-guard (forward
+  // progress), so a non-escalation early return can never wedge on wait-answer.
+  const reenter = flowElement("f_escReenter");
+  assert(reenter, "f_escReenter flow missing");
+  assertStringIncludes(reenter, 'sourceRef="gw-escalated"');
+  assertStringIncludes(reenter, 'targetRef="gw-guard"');
+  assert(
+    !/conditionExpression/.test(reenter),
+    "f_escReenter is the default arm and must not carry a conditionExpression",
+  );
+});
+
+test("regression: every flow into wait-answer is either escalated-gated or a fixed-question escalation", () => {
+  // wait-answer must never be reachable by an unconditional edge from the agent-raised
+  // persist-escalation (whose escalation is conditional). The agent path reaches it only via
+  // gw-escalated's `escalated = true` arm; the max-rounds / review-stalled paths set a fixed
+  // non-blank question and so always escalate.
+  const intoWait = allFlows().filter((f) => /targetRef="wait-answer"/.test(f));
+  assert(intoWait.length > 0, "no flow targets wait-answer");
+  for (const f of intoWait) {
+    assert(
+      !/sourceRef="persist-escalation"/.test(f),
+      "wait-answer must not be entered directly from persist-escalation",
+    );
+  }
+});

package/app/roundResultDefault.ts

@@ -0,0 +1,35 @@
+// Review-round "safe default" routing — the canonical, testable mirror of the convergence-loop
+// `gw-status` exclusive gateway (see resources/processes/convergence-loop.bpmn and the structural
+// guard in roundResultDefault.test.ts).
+//
+// A review round that exits without a machine-readable result (empty/unknown status) must NOT
+// escalate: the round-cap gate and the review-wait timeout already provide the human-escalation
+// safety nets, and `persist-round` defaults an absent status to `addressed`. Escalation is an
+// EXPLICIT decision, delegated here to the single canonical taxonomy so this routing can never
+// drift from the tier logic every other raise site uses.
+//
+// Crucially, a human-blocking status (`needs_input` / `blocked`) with a BLANK question is a
+// NON-escalation — it re-enters the durable review wait rather than fabricating an answerable
+// escalation. The gateway enforces the same rule via its `f_escalate` condition.
+
+import { classifyEscalation } from "./escalationTaxonomy.ts";
+
+/** Where a review-round result routes:
+ *  • `converged` — the PR is done (success path).
+ *  • `escalate`  — a decision-required escalation (human-blocking status + answerable question).
+ *  • `reenter`   — everything else re-enters the durable review wait / round-cap guard: an
+ *                  addressed/waiting/unknown/empty status, OR a human-blocking status whose
+ *                  question is blank (the retired blank-question fabrication path). */
+export type RoundRouting = "converged" | "escalate" | "reenter";
+
+/** Route a review-round result exactly as `gw-status` does, delegating the escalation decision
+ * to {@link classifyEscalation}. A round only escalates when the taxonomy classifies it as
+ * `decision-required`; otherwise it converges or re-enters the loop. */
+export function routeRoundResult(
+  status: string | null | undefined,
+  question?: string | null,
+): RoundRouting {
+  if ((status ?? "") === "converged") return "converged";
+  const disposition = classifyEscalation({ kind: "review-round", status, question });
+  return disposition === "decision-required" ? "escalate" : "reenter";
+}

package/app/service.test.ts

@@ -43,7 +43,7 @@ function withGithubOff(run: () => Promise<void>): Promise<void> {
   });
 }
 
-test("re-submit of a cancelled PR clears stale open escalations + the denormalised pointer", async () => {
+test("re-submit of a cancelled PR marks stale open escalations", async () => {
   await withGithubOff(async () => {
     const PR_KEY = "owner/repo#42";
     const stores: Record<string, { rows: unknown[]; key: string }> = {
@@ -56,8 +56,6 @@ test("re-submit of a cancelled PR clears stale open escalations + the denormalis
           title: "old title",
           status: "abandoned", // terminal -> re-open path
           current_round: 3,
-          open_escalation_id: 5,
-          open_escalation_question: "(no question provided)",
         }],
         key: "pr_key",
       },
@@ -81,15 +79,16 @@ test("re-submit of a cancelled PR clears stale open escalations + the denormalis
       prKey: PR_KEY,
     });
 
-    // The prior run's open escalation is retired (not left "open" to resurface a dead form) …
+    // The prior run's open escalation is retired (not left "open" to resurface a dead form on the
+    // re-opened PR). The review-loop escalation is now a native userTask (open state derived from
+    // the canonical `escalations` row status), so there is no denormalised PR-row pointer to clear.
     const esc = stores.escalations.rows[0] as Record<string, unknown>;
     assertEquals(esc.status, "stale");
-    // … and the PR row is re-opened with the denormalised escalation pointer cleared.
     const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
     assertEquals(pr.status, "converging");
     assertEquals(pr.current_round, 1);
-    assertEquals(pr.open_escalation_id, null);
-    assertEquals(pr.open_escalation_question, null);
+    assertEquals(pr.open_escalation_id, undefined);
+    assertEquals(pr.open_escalation_question, undefined);
     assertEquals(pr.process_key, "PI-9");
   });
 });

package/app/service.ts

@@ -115,8 +115,6 @@ interface PullRequest {
   updated_at: string;
   converged_at: string | null;
   merged_at: string | null;
-  open_escalation_id: number | null;
-  open_escalation_question: string | null;
   // Job-activation visibility (005_job_activation.sql), written by the poller's
   // `pollJobActivation` pass. `active_worker` is the leasing worker's name while an
   // agent is actively working the `senior:pr-review` round; NULL means the job is
@@ -353,10 +351,11 @@ export async function submitPr(
   const abandonToken = existing?.abandon_token ?? mintAbandonToken();
   if (existing) {
     // A prior run (cancelled, converged, or otherwise superseded) may have left an OPEN
-    // escalation row plus the denormalised pointer on the PR. A fresh convergence run must not
-    // inherit that stale answer form — the "(no question provided)" bleed-through on resubmit
-    // (Magikcraft/nano-bpm #597/#599). Mark any still-open escalations `stale` and clear the
-    // pointer below, mirroring the plan re-plan cleanup (issue #25 in plan.ts).
+    // escalation row. A fresh convergence run must not inherit that stale answer — the
+    // "(no question provided)" bleed-through on resubmit (Magikcraft/nano-bpm #597/#599).
+    // Mark any still-open escalations `stale`, mirroring the plan re-plan cleanup (issue #25
+    // in plan.ts). The review-loop escalation is now a native userTask; its open state is derived
+    // from the canonical `escalations` row status, so there is no denormalised PR-row pointer to clear.
     for (const e of await escs(data).find({ pr_key: parsed.prKey, status: "open" })) {
       await escs(data).update(e.id, { status: "stale" });
     }
@@ -372,10 +371,6 @@ export async function submitPr(
       outcome: null,
       converged_at: null,
       merged_at: null,
-      // Drop any denormalised open-escalation pointer from the prior run so the answer form
-      // does not resurface a dead/stale question on the re-opened PR.
-      open_escalation_id: null,
-      open_escalation_question: null,
       abandon_token: abandonToken,
       updated_at: ts,
     });
@@ -486,22 +481,26 @@ export async function answerEscalation(
   prKey: string,
   answer: string,
 ) {
-  const open = (await escs(data).find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id)[0];
-  if (!open) return { ok: false, reason: "no open escalation" };
+  const open = (await escs(data).find({ pr_key: prKey, status: "open" })).sort((a, b) => b.id - a.id);
+  if (open.length === 0) return { ok: false, reason: "no open escalation" };
   const ts = now();
-  await escs(data).update(open.id, { answer, status: "answered", answered_at: ts });
+  await escs(data).update(open[0].id, { answer, status: "answered", answered_at: ts });
+  // `pr.persist-escalation` always INSERTs a new open row, so a retry can leave duplicate open rows
+  // for this PR. Retire any older ones to `stale` so none is left `open` to phantom-surface on
+  // /status (mirrors `submitPr`'s resubmit cleanup and the review loop's `pr.answer-escalation`).
+  for (const dup of open.slice(1)) {
+    await escs(data).update(dup.id, { status: "stale" });
+  }
   await prs(data).update(prKey, {
     status: "converging",
     updated_at: ts,
-    open_escalation_id: null,
-    open_escalation_question: null,
   });
   await engine.publishMessage({
     name: "escalation-answered",
     correlationKey: prKey,
-    variables: { answer, escalationId: open.id },
+    variables: { answer, escalationId: open[0].id },
   });
-  return { ok: true, escalationId: open.id };
+  return { ok: true, escalationId: open[0].id };
 }
 
 /** A PR currently in flight, as reported by the status endpoint. */
@@ -526,27 +525,45 @@ export interface ActivePr {
 
 /** Every tracked PR not in a terminal state (converged/abandoned), newest-updated first. Backs
  * the GET status endpoint so an operator or an external harness can see what is in flight
- * without reading the datasource directly. */
+ * without reading the datasource directly. The open-escalation question is derived from the
+ * canonical `escalations` audit row — the single source of truth (no denormalised PR-row
+ * pointer). A PR reads `status="escalated"` only while a token is parked awaiting a human answer,
+ * and the row it raised carries `status="open"` until that answer is recorded — by the review
+ * loop's `pr.answer-escalation` step on `wait-answer` completion, or the merge loop's
+ * `answerEscalation` message path. Deriving from the row (not a per-loop wait mechanism) surfaces
+ * BOTH loops' escalations: the merge loop parks on a message catch with no user task, so a
+ * user-task probe would silently hide it. Once answered the row leaves `open`, so `openEscalation`
+ * derives back to null. */
 export async function activePrs(data: DataLayer): Promise<ActivePr[]> {
   const all = await prs(data).all();
-  return all
+  const active = all
     .filter((p) => !TERMINAL_STATUSES.includes(p.status))
-    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0))
-    .map((p) => ({
-      prKey: p.pr_key,
-      repo: p.repo,
-      number: p.number,
-      url: p.url,
-      title: p.title ?? null,
-      status: p.status,
-      round: p.current_round,
-      processKey: p.process_key ?? null,
-      waitingSince: p.waiting_since ?? null,
-      openEscalation: p.open_escalation_question ?? null,
-      updatedAt: p.updated_at,
-      activeWorker: p.active_worker ?? null,
-      leaseUntil: p.lease_until ?? null,
-    }));
+    .sort((a, b) => (a.updated_at < b.updated_at ? 1 : a.updated_at > b.updated_at ? -1 : 0));
+  // Only an `escalated` PR is parked awaiting a human answer (either loop). Surface the question
+  // from its latest still-open `escalations` row; a resubmit retires stale rows and finalize/merge
+  // move the PR off `escalated`, so an open row on an escalated PR is a genuinely live escalation.
+  // Fetch every open row in one query (avoids an N+1 over escalated PRs), then keep the newest per PR.
+  const openEscByPr = new Map<string, string>();
+  const escalatedPrs = new Set(active.filter((p) => p.status === "escalated").map((p) => p.pr_key));
+  for (const e of (await escs(data).find({ status: "open" })).sort((a, b) => b.id - a.id)) {
+    if (!escalatedPrs.has(e.pr_key) || openEscByPr.has(e.pr_key)) continue;
+    if (e.question) openEscByPr.set(e.pr_key, e.question);
+  }
+  return active.map((p) => ({
+    prKey: p.pr_key,
+    repo: p.repo,
+    number: p.number,
+    url: p.url,
+    title: p.title ?? null,
+    status: p.status,
+    round: p.current_round,
+    processKey: p.process_key ?? null,
+    waitingSince: p.waiting_since ?? null,
+    openEscalation: openEscByPr.get(p.pr_key) ?? null,
+    updatedAt: p.updated_at,
+    activeWorker: p.active_worker ?? null,
+    leaseUntil: p.lease_until ?? null,
+  }));
 }
 
 /** One review-ready poll pass (SPEC §10): for every PR waiting on a review, fetch its GitHub

package/db/migrations/026_agent_completion.sql

@@ -0,0 +1,36 @@
+-- Agent-answerable escalations (epic #156, slice U6; ADR 0046). The escalation user tasks landed by
+-- U0–U3 are completed by whoever holds the assignment — a human via the task inbox, or an AGENT
+-- assignee via the host-side completer. Both drive the SAME `.form` contract and the SAME engine
+-- `completeUserTask` resume path (no parallel lane); this ledger is the attribution + reversibility
+-- surface layered over that one completion.
+--
+-- One row per escalation user-task completion routed through the canonical attributed completer
+-- (app/agentCompletion.ts). It records WHO completed the task (agent vs human, and their id), the
+-- exact typed form variables submitted, and — for an AGENT completion — whether a human has since
+-- reverted/overridden it. A completed user task cannot be un-completed in the engine, so
+-- reversibility is modelled here: an agent answer is never a silent irreversible commit — a human
+-- can mark it reverted (recording who + when), and any host-side consumer reads this ledger to see
+-- whether the latest completion is still authoritative.
+--
+-- Expand-only / additive (AGENTS.md forward-only migrations): a new table, no existing shape
+-- touched. `actor_kind` is agent | human; `reversible` is 1 for agent completions (a human may
+-- override) and 0 for human completions (already the authority).
+CREATE TABLE task_completions (
+  id                    INTEGER PRIMARY KEY AUTOINCREMENT,
+  user_task_key         TEXT NOT NULL,             -- the engine user-task key that was completed
+  process_instance_key  TEXT,                      -- owning process instance, when known
+  element_id            TEXT,                      -- the escalation task's BPMN elementId
+  actor_kind            TEXT NOT NULL CHECK (actor_kind IN ('agent', 'human')), -- agent | human
+  actor_id              TEXT NOT NULL,             -- the completing identity (agent id / operator)
+  variables_json        TEXT NOT NULL,             -- the typed form variables submitted (JSON)
+  reversible            INTEGER NOT NULL DEFAULT 0, -- 1 = a human may override (agent completions)
+  reverted              INTEGER NOT NULL DEFAULT 0, -- 1 once a human has reverted/overridden it
+  reverted_by           TEXT,                      -- the human identity that reverted it
+  reverted_note         TEXT,                      -- the human's corrective guidance overriding the agent answer
+  reverted_at           TEXT,
+  created_at            TEXT NOT NULL
+);
+
+-- The completer and the revert path look a completion up by its user-task key (newest first);
+-- index it to avoid a scan.
+CREATE INDEX idx_task_completions_key ON task_completions(user_task_key);

package/db/migrations/027_retire_escalation_subsystem.sql

@@ -0,0 +1,43 @@
+-- Retire the bespoke escalation subsystem — the destructive CONTRACT phase of the
+-- expand-and-contract migration to native BPMN `userTask` + `.form` (ADR 0002, epic
+-- #156). The escalation-conversion slices already stopped WRITING/reading these
+-- surfaces (U2 vacated the plan/task/plan-review mirrors; U3 vacated the PR
+-- review-loop `open_escalation_*` mirror), deriving open-escalation state from parked
+-- user tasks (`searchUserTasks`) instead. Nothing reads these tables/columns any more,
+-- so drop them.
+--
+-- Forward-only and numbered after the current highest prefix (026); migrations apply
+-- in order and are auto-applied on boot. The migration runner wraps each file in its
+-- own transaction — this file must NOT contain BEGIN/COMMIT.
+--
+-- NB: the merge-loop escalation (out of scope for #156) still uses the shared
+-- `escalations` audit table + the `escalation-answered` message path — those are
+-- deliberately KEPT here.
+
+-- 1. The per-task implementation-phase escalation audit table (006_task_escalation.sql).
+--    Superseded by the `feature-escalation` user task; its answer now resumes the
+--    process directly. DROP TABLE also drops its indexes.
+DROP TABLE IF EXISTS plan_escalations;
+
+-- 2. The plan-review cap escalation audit table (020_plan_review_escalation.sql).
+--    Superseded by the `plan-review-decision` user task; the review epoch is now the
+--    durable process variable `planReviewEpoch`, not the count of answered rows.
+DROP TABLE IF EXISTS plan_review_escalations;
+
+-- 3. The denormalised "currently-open escalation" pointers on `pull_requests`
+--    (003_open_escalation.sql). The open-escalation question is derived from the
+--    canonical `escalations` audit row + parked user tasks — no denormalised pointer.
+ALTER TABLE pull_requests DROP COLUMN open_escalation_id;
+ALTER TABLE pull_requests DROP COLUMN open_escalation_question;
+
+-- 4. The denormalised per-plan "oldest open task escalation" pointer
+--    (006_task_escalation.sql) and the "open plan-review escalation" pointer
+--    (020_plan_review_escalation.sql) on `plans`. Both are surfaced from the task
+--    inbox (`searchUserTasks`) now, with no denormalised mirror on the plan row.
+ALTER TABLE plans DROP COLUMN open_task_escalation_id;
+ALTER TABLE plans DROP COLUMN open_task_question;
+ALTER TABLE plans DROP COLUMN open_task_corr_key;
+ALTER TABLE plans DROP COLUMN open_task_id;
+ALTER TABLE plans DROP COLUMN open_plan_escalation_id;
+ALTER TABLE plans DROP COLUMN open_plan_findings;
+ALTER TABLE plans DROP COLUMN open_plan_round;

package/db/migrations/028_feature_runs.sql

@@ -0,0 +1,28 @@
+-- Single-issue feature run (issue #172): the "missing middle" between Epics
+-- (plan-fanout: one issue → many PRs) and PR convergence (an already-open PR →
+-- review → merge). One row per issue handed to a single implementation agent
+-- that raises exactly ONE PR, then OPTIONALLY hands that PR to the convergence
+-- loop (and, with auto-merge, the merge-loop).
+--
+-- The downstream PR lifecycle (review rounds, escalations, merge) is NOT
+-- duplicated here: once `converge` hands the opened PR to `submitPr`, its live
+-- state lives on the `pull_requests` row keyed by `pr_key`. `feature_runs` only
+-- tracks the feature run's own lifecycle up to the hand-off.
+
+CREATE TABLE feature_runs (
+  feature_key   TEXT PRIMARY KEY,          -- "<owner>/<repo>#<issue-number>"
+  repo          TEXT NOT NULL,             -- "<owner>/<repo>"
+  issue_number  INTEGER NOT NULL,
+  issue_url     TEXT NOT NULL,
+  base_branch   TEXT NOT NULL,             -- the branch the agent branches off / opens its PR against
+  status        TEXT NOT NULL,             -- running | opened | converging | blocked | skipped | failed | abandoned
+  process_key   TEXT,                       -- engine process-instance key (feature.bpmn)
+  pr_key        TEXT,                       -- the PR this run produced ("<owner>/<repo>#<n>") → pull_requests
+  converge      INTEGER NOT NULL DEFAULT 0, -- 0|1 — hand the opened PR to the convergence loop
+  auto_merge    INTEGER NOT NULL DEFAULT 0, -- 0|1 — drive the merge-loop after convergence (converge=0 ⇒ moot)
+  outcome       TEXT,                       -- final summary / note from the agent
+  created_at    TEXT NOT NULL,
+  updated_at    TEXT NOT NULL
+);
+
+CREATE INDEX idx_feature_runs_status ON feature_runs(status);

package/e2e/agent-answerable.e2e.ts

@@ -0,0 +1,185 @@
+// End-to-end proof for agent-answerable escalations (epic #156, slice U6; ADR 0046). Boots the whole
+// app against the WASM engine and drives the REAL plan-fanout.bpmn to the implementation-phase task
+// escalation — the native `feature-escalation` userTask + form the human path (U2) completes — then
+// completes it through the HOST-SIDE AGENT COMPLETER (`completeEscalationAsAgent`) instead of a raw
+// human completion. It proves the three things U6 promises:
+//
+//   1. an AGENT assignee completing the SAME `.form` resumes the process with typed vars IDENTICAL to
+//      a human completion — asserted on the cumulative taken sequence flows: `{resolution:"answer"}`
+//      routes `w_gw_answer -> implement-task`, exactly as the U2 human test asserts (an empty/wrong
+//      completion would take the abandon default);
+//   2. attribution is recorded — the `task_completions` ledger row is actor_kind=agent + the agent id
+//      + the submitted variables;
+//   3. the completion is reversible — a human reverts it, and the ledger records who + when.
+//
+// No `.bpmn` is touched by this slice: the agent uses the same process + form the human does, only
+// the completion CALLER differs. Network isolation mirrors the sibling e2e suites (github forced to
+// offline `token` mode). 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";
+import {
+  completeEscalationAsAgent,
+  latestCompletion,
+  revertAgentCompletion,
+  type TaskCompletion,
+} from "../app/agentCompletion.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;
+  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("agent-answerable escalations (U6 — same form, agent completer, attribution + reversibility)", () => {
+  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-u6-"));
+    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!;
+  }
+
+  const singleTaskPlan: Stub = () => ({ tasks: [{ id: "t1", title: "T1", prompt: "do t1" }] });
+  const approveReview: Stub = () => ({ approved: true, findings: "" });
+
+  test("an agent completes the SAME feature-escalation form a human would → process resumes with the identical typed vars, attributed, and reversible", async () => {
+    let featureCalls = 0;
+    await withApp(
+      {
+        "senior:plan": singleTaskPlan,
+        "senior:plan-review": approveReview,
+        "senior:feature": () => {
+          featureCalls += 1;
+          return featureCalls === 1
+            ? { status: "escalated", question: "Which API should I use?", summary: "parked for a human" }
+            : { status: "blocked", summary: "resumed after answer" };
+        },
+      },
+      async ({ app, processKey }) => {
+        const task = await openTask(app, processKey, "feature-escalation");
+        assert.ok(task.userTaskKey, "the feature escalation carries a completable userTaskKey");
+
+        // Complete AS AN AGENT through the host-side completer — the same typed `{resolution, answer}`
+        // a human submits through the inbox, only the caller differs.
+        const r = await completeEscalationAsAgent(app.db, app.engine, {
+          userTaskKey: task.userTaskKey,
+          agentId: "senior:answer-bot",
+          variables: { resolution: "answer", answer: "use v2" },
+        });
+        assert.equal(r.ok, true, "the agent completer accepted the escalation completion");
+        assert.equal(r.elementId, "feature-escalation");
+        await app.settle();
+
+        // IDENTICAL resume to the human path (mirrors U2's human test): the typed resolution loops
+        // the child back to re-dispatch the SAME task — NOT the abandon default.
+        const flows = takenFlows(app);
+        assert.ok(
+          flows.includes("w_gw_answer->implement-task"),
+          `agent answer routed back to implement-task (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(
+          !flows.includes("w_gw_answer->w_end"),
+          "the abandon (default) flow was NOT taken",
+        );
+
+        // Attribution: the ledger records an AGENT completion with the agent id + the exact vars.
+        const completions = await app.db
+          .table<TaskCompletion>("task_completions", "id")
+          .find({ user_task_key: task.userTaskKey });
+        assert.equal(completions.length, 1, "exactly one attribution row for the completion");
+        const row = completions[0];
+        assert.equal(row.actor_kind, "agent");
+        assert.equal(row.actor_id, "senior:answer-bot");
+        assert.equal(row.element_id, "feature-escalation");
+        assert.deepEqual(JSON.parse(row.variables_json), { resolution: "answer", answer: "use v2" });
+        assert.equal(row.reversible, 1, "an agent completion is reversible");
+        assert.equal(row.reverted, 0);
+
+        // Reversibility: a human overrides the agent's answer; the ledger records who + when.
+        const rev = await revertAgentCompletion(app.db, row.id, { kind: "human", id: "alice" });
+        assert.equal(rev.ok, true, "a human can revert the agent completion");
+        const after = (await latestCompletion(app.db, task.userTaskKey))!;
+        assert.equal(after.reverted, 1);
+        assert.equal(after.reverted_by, "alice");
+        assert.ok(after.reverted_at, "reverted_at is stamped");
+      },
+    );
+  });
+});