@nanobpm/nano-workforce 0.123.1 → 0.124.0

package/app/deliveryGraphRun.ts

@@ -1,23 +1,27 @@
-// app/deliveryGraphRun.ts — the `startDeliveryGraph` run AGGREGATE (ADR 0005 Decision 7, slice S5).
+// app/deliveryGraphRun.ts — the delivery-graph run AGGREGATE (ADR 0005 Decision 7).
 //
-// The dispatch door (`operations/startDeliveryGraph.ts`) turns an agent-authored `DeliveryGraph` into
-// a RUNNING engine-native process (via the S4 runner) — but because these graphs merge PRs and publish
-// packages, dispatch is GATED on an approval of the rendered preview and must be idempotent. This
-// module is the durable aggregate that makes both properties true and gives the cockpit a row to show
-// WHERE a run is parked:
+// The cockpit dispatch action (`app/deliveryGraphDispatch.ts`, invoked from `dispatchDeliveryGraph`)
+// turns a staged, agent-authored `DeliveryGraph` into a RUNNING engine-native process (via the S4
+// runner). Because these graphs merge PRs and publish packages, dispatch must be idempotent and
+// at-most-once. This module is the durable aggregate that makes that true and gives the cockpit a row
+// to show WHERE a run is:
 //
 //   • the idempotency fence — a run is keyed by `run_key` (a caller `idempotencyKey`, else the graph's
-//     content digest). A re-POST collapses onto the same row, so an in-flight run short-circuits
+//     content digest). A re-dispatch collapses onto the same row, so an in-flight run short-circuits
 //     instead of double-launching (mirrors `plans`' `alreadyRunning`).
-//   • the approval token — `digest` is the content-address a side-effecting graph must present as its
-//     `approvalToken` to dispatch. Persisted so a second POST re-derives + re-checks it.
+//   • the content digest — `digest` is the content-address of the compiled definition, persisted so
+//     the cockpit and reconcilers can relate a run to the proposal it came from.
 //   • the derived parked-node phase — `phase`/`phase_node_id` is the display-only "where is it parked"
 //     projection `pollDeliveryGraphPhase` recomputes from engine truth (the running instance's open
 //     user tasks), generalising the `epic_phase` derived-phase machinery to a DYNAMIC compiled process.
 //
-// The pure helpers here (`computeRunKey`, `isDeliveryGraphApproved`, `buildHumanLabels`,
-// `deriveDeliveryPhase`) are engine/DB-free so they unit-test in isolation; the door and the poller
-// supply the I/O.
+// The pure helpers here (`computeRunKey`, `buildHumanLabels`, `deriveDeliveryPhase`) are engine/DB-free
+// so they unit-test in isolation; the dispatch action and the poller supply the I/O.
+//
+// NOTE (issue #460): the `awaiting-approval` status remains a RESERVED member of the lifecycle union
+// (like `abandoned`) but is no longer produced — dispatch is now an operator action in the cockpit, so
+// there is no agent-facing approval gate to park a run at. The old replayable `approvalToken` and the
+// approval-park write were removed with the agent `start` door.
 
 import type { DataLayer, ProcessInstanceState } from "@nanobpm/urban";
 import type { CompileDeliveryGraphResult } from "../nano-generated/api-io.d.ts";
@@ -26,7 +30,7 @@ import { DELIVERY_HUMAN_ELEMENT, isDeliveryHumanElement } from "./deliveryHuman.
 
 const now = () => new Date().toISOString();
 
-/** One `startDeliveryGraph` run — the durable row. `side_effecting` is a SQLite boolean (0/1). */
+/** One delivery-graph run — the durable row. `side_effecting` is a SQLite boolean (0/1). */
 export interface DeliveryGraphRun {
   run_key: string;
   process_key: string | null;
@@ -45,8 +49,9 @@ export interface DeliveryGraphRun {
   updated_at: string;
 }
 
-/** The run lifecycle. `awaiting-approval` = a side-effecting graph parked at the approval gate (no
- * instance started); `running` = dispatched to the engine; `done`/`failed`/`abandoned` = terminal. */
+/** The run lifecycle. `awaiting-approval` is RESERVED but no longer produced (issue #460 moved dispatch
+ * to an operator action, so runs are only ever created at launch) — kept in the union to preserve the
+ * durable enum. `running` = dispatched to the engine; `done`/`failed`/`abandoned` = terminal. */
 export const DELIVERY_GRAPH_RUN_STATUSES = [
   "awaiting-approval",
   "running",
@@ -142,74 +147,14 @@ export async function claimRunForLaunch(
   return res.changed === 1;
 }
 
-/** Persist a PARKED (non-launch) run row — the approval-gate write for an unapproved side-effecting
- * graph — WITHOUT ever clobbering a concurrently-launched `running` claim. Two concurrent submits of
- * one graph (same `run_key`) can race an APPROVED launch (which inserts/flips a `running` claim via
- * `claimRunForLaunch`) against an UNAPPROVED park: a blind insert-or-update would let the park
- * overwrite that `running` claim back to `awaiting-approval` and null its `process_key`, breaking the
- * at-most-once dispatch fence and letting a later re-submit double-launch the graph's side effects.
- * So mirror the launch fence exactly — a first write is the `run_key` PK insert; on a unique
- * collision (a concurrent submit already wrote the row) OR when a row already exists, re-apply via a
- * single atomic guarded UPDATE `… WHERE status <> 'running'`. One statement, so the check-and-write
- * is atomic even across the delegate's `await` points: a racing `running` claim matches zero rows and
- * survives untouched, while a still-parked or terminal row is idempotently (re-)parked. */
-export async function parkRunFencedAgainstLaunch(
-  data: DataLayer,
-  existing: boolean,
-  row: DeliveryGraphRun,
-): Promise<void> {
-  if (!existing) {
-    try {
-      await deliveryGraphRuns(data).insert(row);
-      return;
-    } catch (err) {
-      if (!isUniqueConstraintFence(err)) throw err;
-    }
-  }
-  await data
-    .open()
-    .exec(
-      `UPDATE "delivery_graph_runs" SET "process_key" = ?, "process_definition_id" = ?, "digest" = ?, "status" = ?, "side_effecting" = ?, "node_count" = ?, "human_node_count" = ?, "side_effect_count" = ?, "title" = ?, "phase" = ?, "phase_node_id" = ?, "human_labels" = ?, "updated_at" = ? WHERE "run_key" = ? AND "status" <> 'running'`,
-      [
-        row.process_key,
-        row.process_definition_id,
-        row.digest,
-        row.status,
-        row.side_effecting,
-        row.node_count,
-        row.human_node_count,
-        row.side_effect_count,
-        row.title,
-        row.phase,
-        row.phase_node_id,
-        row.human_labels,
-        row.updated_at,
-        row.run_key,
-      ],
-    );
-}
-
 /** The idempotency key for a submitted graph: a caller-supplied `idempotencyKey` (trimmed) when
- * present and non-blank, else the graph's content `digest`. So two POSTs of the SAME graph (no
+ * present and non-blank, else the graph's content `digest`. So two dispatches of the SAME graph (no
  * explicit key) collapse onto one run, and a caller can force a fresh run with an explicit key. */
 export function computeRunKey(idempotencyKey: string | undefined | null, digest: string): string {
   const trimmed = typeof idempotencyKey === "string" ? idempotencyKey.trim() : "";
   return trimmed || digest;
 }
 
-/** The approval decision (Decision 7). A graph with NO side-effecting nodes (only `wait`/`human`)
- * needs no approval and dispatches straight away. A SIDE-EFFECTING graph dispatches only when the
- * caller presents `approvalToken == digest` — an approval OF the rendered preview, content-addressed
- * so it cannot be replayed against a different graph. */
-export function isDeliveryGraphApproved(
-  sideEffecting: boolean,
-  approvalToken: string | undefined | null,
-  digest: string,
-): boolean {
-  if (!sideEffecting) return true;
-  return typeof approvalToken === "string" && approvalToken.trim() === digest;
-}
-
 /** The compiled human-task element id for a node's compiled BPMN element (`delivery-human-task__n3`) —
  * the exact id the S4 compiler inlines and the engine reports as a user task's `elementId`. */
 export function humanTaskElementId(element: string): string {

package/app/deliveryGraphText.ts

@@ -1,9 +1,9 @@
 // app/deliveryGraphText.ts — the shared PARSE step for the human-facing UI JSON-paste ingress
 // (issue #386, ADR 0005). The Delivery Graphs page (`pages/delivery-graphs.page.json`) submits the
 // operator's pasted delivery-graph as a raw JSON STRING (`graphJson`) — the page's text field cannot
-// submit a structured object — so the preview/dispatch ingress operations parse it here before handing
-// the resulting object to the SAME pure `compileDeliveryGraph` compiler / gated `startDeliveryGraph`
-// door the agent-facing paths use. This is a UI text adapter, NOT a parallel compile/dispatch path.
+// submit a structured object — so the preview+stage ingress operation parses it here before handing
+// the resulting object to the SAME pure `compileDeliveryGraph` compiler the agent-facing compile door
+// uses. This is a UI text adapter, NOT a parallel compile path.
 //
 // PURE and I/O-free so it unit-tests in isolation. A blank field, non-JSON text, or a non-object JSON
 // value maps to a clean `{ ok:false, error }` the ingress surfaces as a 400 with a human banner —

package/app/deliveryRunner.ts

@@ -20,9 +20,10 @@ import { assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID } from "./
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery } from "./readiness.ts";
 
 /** The content digest of a compiled graph — `sha256(bpmn)[:12]` — the single source of truth for the
- * content-addressed deploy id (`delivery-graph-<digest>`) AND the S5 dispatch door's approval token /
- * default idempotency key. Both the runner (deploy id) and `operations/startDeliveryGraph` (approval +
- * dedupe key) derive from THIS one function so the two can never drift on how a graph is addressed. */
+ * content-addressed deploy id (`delivery-graph-<digest>`) AND the dispatch fence's default idempotency
+ * key + the staged-proposal primary key. The runner (deploy id), `app/deliveryGraphDispatch` (dedupe
+ * key), and `app/deliveryGraphProposals` (proposal digest) all derive from THIS one function so they
+ * can never drift on how a graph is addressed. */
 export function deliveryGraphDigest(bpmn: string): string {
   return createHash("sha256").update(bpmn).digest("hex").slice(0, 12);
 }

package/app/featureReadModel.test.ts

@@ -10,13 +10,16 @@
 // datasource on a terminated instance — bypassing the gateway and freezing the display columns.
 // 073_feature_read_model.sql retires the write-time projection: the derived columns are now a VIEW
 // over each row's own `status`/`pr_key`/`converge`/`auto_merge`/`acknowledged_at`, so there is no
-// stored column and no write-path for any writer to leave stale.
+// stored column and no write-path for any writer to leave stale. 075_feature_read_model_attention_
+// from_user_tasks.sql then moves `attention` off the drift-prone `status` variable onto ENGINE TRUTH
+// — an OPEN `feature-blocked`/`feature-escalation` row in the `user_tasks` inbox (issue #422).
 //
-// This exercises the REAL SQLite view (073 applied to an in-memory DB, mirroring
+// This exercises the REAL SQLite view (073+075 applied to an in-memory DB, mirroring
 // app/plansReadModel.test.ts / app/mergesPerDayView.test.ts) and pins that its CASE expressions
-// reproduce `deriveStage` / `deriveListBucket` EXACTLY over the full status matrix — the SAME pure
-// helpers the acknowledge operations guard on — plus a RED/GREEN guard reproducing the reconciler
-// bypass: a RAW-datasource `status` write must leave the projection correct.
+// reproduce `deriveStage` / `deriveListBucket` EXACTLY over the full status × open-task matrix — the
+// SAME pure helpers the acknowledge operations guard on — plus RED/GREEN guards reproducing the
+// reconciler bypass (a RAW-datasource `status` write must leave the projection correct) and the #422
+// answered-escalation drift (a sticky `status='escalated'` with no open task must show no ⚠).
 import { readFileSync } from "node:fs";
 import { DatabaseSync } from "node:sqlite";
 import { test } from "node:test";
@@ -40,10 +43,27 @@ function viewDb(): DatabaseSync {
        outcome TEXT, delivery_label TEXT, acknowledged_at TEXT, created_at TEXT, updated_at TEXT,
        stage TEXT, stage_state TEXT, stage_skipped TEXT, attention TEXT, list_bucket TEXT);`,
   );
+  // The `user_tasks` inbox (034_user_tasks_inbox.sql) — the engine-truth source the 075 VIEW derives
+  // `attention` from (a row IFF an escalation user task is OPEN). Minimal shape: the three columns the
+  // correlated EXISTS lookups read, plus its PK.
+  db.exec(
+    `CREATE TABLE user_tasks (
+       user_task_key TEXT PRIMARY KEY, element_id TEXT NOT NULL, subject_type TEXT NOT NULL,
+       subject_key TEXT NOT NULL);`,
+  );
   db.exec(MIG("073_feature_read_model.sql"));
+  db.exec(MIG("075_feature_read_model_attention_from_user_tasks.sql"));
   return db;
 }
 
+// Simulate `pollUserTasks` opening one native user task for a feature run: the presence of this row is
+// the engine truth the VIEW's `attention` derives from (its deletion = the task answered/closed).
+function openUserTask(db: DatabaseSync, feature_key: string, element_id: "feature-escalation" | "feature-blocked"): void {
+  db.prepare(
+    "INSERT INTO user_tasks (user_task_key, element_id, subject_type, subject_key) VALUES (?, ?, 'feature', ?)",
+  ).run(`${feature_key}:${element_id}`, element_id, feature_key);
+}
+
 interface SampleRun {
   status: string;
   pr_key?: string | null;
@@ -94,34 +114,51 @@ function projection(db: DatabaseSync, feature_key: string): Record<string, unkno
   return { ...r };
 }
 
-test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key combination", () => {
+test("feature_read_model derives stage/stage_state/stage_skipped/attention EXACTLY like deriveStage, over every status × converge/auto_merge/pr_key × open-task combination", () => {
   const db = viewDb();
-  const cases: Array<{ key: string; run: SampleRun }> = [];
+  const cases: Array<{ key: string; run: SampleRun; hasOpenBlockedTask: boolean; hasOpenEscalationTask: boolean }> = [];
   let i = 0;
   for (const status of FEATURE_RUN_STATUSES) {
     for (const converge of [0, 1]) {
       for (const auto_merge of [0, 1]) {
         for (const pr_key of [null, `o/r#pr${i}`]) {
-          const key = `o/r#${i++}`;
-          cases.push({ key, run: { status, converge, auto_merge, pr_key } });
-          addRun(db, key, { status, converge, auto_merge, pr_key });
+          // The open-task dimension only matters for the two human-wait statuses (escalated/
+          // awaiting_operator), whose derivation reads open tasks — for them exercise BOTH
+          // task-present and task-absent (the #422 drift case = the task already gone). Every other
+          // status ignores open tasks (`el` is null, so no task is ever created), so iterating the
+          // dimension there would only duplicate identical cases; iterate [false] alone.
+          const el = status === "escalated" ? "feature-escalation" : status === "awaiting_operator" ? "feature-blocked" : null;
+          for (const openTask of el !== null ? [false, true] : [false]) {
+            const key = `o/r#${i++}`;
+            const hasTask = openTask && el !== null;
+            cases.push({
+              key,
+              run: { status, converge, auto_merge, pr_key },
+              hasOpenBlockedTask: hasTask && el === "feature-blocked",
+              hasOpenEscalationTask: hasTask && el === "feature-escalation",
+            });
+            addRun(db, key, { status, converge, auto_merge, pr_key });
+            if (hasTask && el !== null) openUserTask(db, key, el);
+          }
         }
       }
     }
   }
 
-  for (const { key, run } of cases) {
+  for (const { key, run, hasOpenBlockedTask, hasOpenEscalationTask } of cases) {
     const oracle = deriveStage({
       status: run.status,
       pr_key: run.pr_key ?? null,
       converge: run.converge ?? 0,
       auto_merge: run.auto_merge ?? 0,
+      hasOpenBlockedTask,
+      hasOpenEscalationTask,
     });
     const row = projection(db, key);
     assertEquals(row.stage, oracle.stage, `${key} (status=${run.status}): stage`);
     assertEquals(row.stage_state, oracle.state, `${key} (status=${run.status}): stage_state`);
     assertEquals(row.stage_skipped, oracle.skipped, `${key} (status=${run.status}): stage_skipped`);
-    assertEquals(row.attention, oracle.attention, `${key} (status=${run.status}): attention`);
+    assertEquals(row.attention, oracle.attention, `${key} (status=${run.status}, openBlocked=${hasOpenBlockedTask}, openEsc=${hasOpenEscalationTask}): attention`);
   }
 });
 
@@ -162,6 +199,37 @@ test("feature_read_model IGNORES any stale STORED projection columns — it read
   });
 });
 
+test("RED/GREEN GUARD #422: an ANSWERED escalation (status sticky 'escalated', no open user task) shows NO ⚠; the badge tracks the OPEN task, not status", () => {
+  // The `feature` process answer-loop returns the token to `implement-task` without resetting the
+  // `status` variable, so a run whose escalation was already answered still reads `status="escalated"`
+  // until its next agent job completes (observed live on merlin: feature instance 31779). The OLD VIEW
+  // derived `attention` from that value and rendered a stale ⚠ on Overview. The badge now derives from
+  // engine truth — the presence of an OPEN `feature-escalation` user task (`pollUserTasks` deletes the
+  // row the moment it is answered) — so it clears immediately regardless of the stale status.
+  const db = viewDb();
+
+  // Answered escalation: status STILL 'escalated' (stale) + a stored ⚠ that lied, but NO open task.
+  addRun(db, "o/r#answered", { status: "escalated", stored: { attention: "⚠", stage: "Implementing" } });
+  const answered = projection(db, "o/r#answered");
+  assertEquals(answered.attention, null, "the stale ⚠ is gone once the escalation task is closed");
+  assertEquals(answered.stage, "Implementing", "the run is back implementing (stage unchanged, correct either way)");
+
+  // Genuinely-parked escalation: the SAME status, but its `feature-escalation` user task is OPEN → ⚠.
+  addRun(db, "o/r#parked", { status: "escalated" });
+  openUserTask(db, "o/r#parked", "feature-escalation");
+  assertEquals(projection(db, "o/r#parked").attention, "⚠", "an OPEN escalation task shows ⚠");
+
+  // Answering it (deleting the row — what `pollUserTasks` does) clears the badge with status untouched.
+  db.prepare("DELETE FROM user_tasks WHERE subject_key = ?").run("o/r#parked");
+  assertEquals(projection(db, "o/r#parked").attention, null, "closing the task clears ⚠ though status is still 'escalated'");
+
+  // Symmetric operator/blocked wait: 'blocked' glyph IFF an open `feature-blocked` task exists.
+  addRun(db, "o/r#stuck", { status: "awaiting_operator", stored: { attention: "blocked" } });
+  assertEquals(projection(db, "o/r#stuck").attention, null, "no open feature-blocked task → no glyph despite awaiting_operator");
+  openUserTask(db, "o/r#stuck", "feature-blocked");
+  assertEquals(projection(db, "o/r#stuck").attention, "blocked", "an OPEN feature-blocked task shows the blocked glyph");
+});
+
 test("RED/GREEN GUARD: a RAW-datasource feature_runs.status write (the instanceTracking reconciler bypass) leaves the projection CORRECT (stage=Done, terminal stage_state, attention=null, Dismiss renderable, still Active)", () => {
   // Reproduce the framework `instanceTracking` reconciler class of bug: on a terminated (cancelled)
   // process instance it writes `{status:"abandoned"}` to `feature_runs` through the RAW datasource,

package/app/github.test.ts

@@ -663,6 +663,40 @@ for (const c of TOKEN_MODE) {
   });
 }
 
+// ── Draft PRs are never landable (issue #454) ────────────────────────────────────────────────────
+//
+// A draft PR with green checks reports `mergeStateStatus: CLEAN`, so the old `mergeStateStatus`
+// switch classified it `"ready"` → the poller attempted the merge → GitHub refused it (draft) → a
+// misleading "the merge attempt did not land (result: blocked), investigate why GitHub refused"
+// escalation. A draft is *categorically* not landable regardless of checks, and the remedy is
+// always the same (mark it ready), so `isDraft` outranks every other signal and yields a
+// first-class `"draft"` verdict the model can escalate with an actionable message.
+test("classifyMergeability: a draft PR is never ready — even with green checks (issue #454)", () => {
+  // CLEAN + green rollup would be `"ready"` if `isDraft` were ignored.
+  assertEquals(classifyMergeability(mergePrState({ mergeStateStatus: "CLEAN", isDraft: true })), "draft");
+  assertEquals(
+    classifyMergeability(
+      mergePrState({ mergeStateStatus: "CLEAN", isDraft: true, rollup: [{ name: "build", conclusion: "SUCCESS" }] }),
+      protocolWith({ requiredChecks: reqChecks("build") }),
+    ),
+    "draft",
+  );
+});
+
+test("classifyMergeability: draft outranks every mergeStateStatus (issue #454)", () => {
+  for (const status of ["CLEAN", "HAS_HOOKS", "UNSTABLE", "BEHIND", "DIRTY", "BLOCKED", "UNKNOWN", ""]) {
+    assertEquals(
+      classifyMergeability(prState({ mergeStateStatus: status, isDraft: true })),
+      "draft",
+      `draft should outrank ${status || "''"}`,
+    );
+  }
+});
+
+test("classifyMergeability: a non-draft PR is unaffected (regression guard, issue #454)", () => {
+  assertEquals(classifyMergeability(prState({ mergeStateStatus: "CLEAN", isDraft: false })), "ready");
+});
+
 // `checkConclusions` must report a terminal conclusion per check but normalise a STILL-IN-FLIGHT run
 // to "" for BOTH rollup shapes — a CheckRun whose `status` is not COMPLETED, and a legacy
 // StatusContext whose `state` is PENDING/EXPECTED — so a caller never mistakes a pending

package/app/github.ts

@@ -954,9 +954,11 @@ export async function baseBranchLanded(
 }
 
 /** A settled landability verdict, or `waiting` when GitHub hasn't determined it yet (or is
- * still running checks / awaiting review). The poller only advances the process on a settled
- * verdict; `waiting` means re-poll later. */
-export type Mergeability = "ready" | "waiting" | "conflict" | "blocked";
+ * still running checks / awaiting review). `draft` is a settled *not-landable* verdict: a draft PR
+ * can never be merged (GitHub refuses it outright), regardless of its checks — so it outranks every
+ * other signal and carries its own actionable remedy (mark it ready). The poller only advances the
+ * process on a settled verdict; `waiting` means re-poll later. */
+export type Mergeability = "ready" | "waiting" | "conflict" | "blocked" | "draft";
 
 /** Intersect a repo's declared `requiredChecks` against the head's actual per-check conclusions —
  * an INDEPENDENT backstop that runs BEFORE the `mergeStateStatus` switch, so nwf never merges a red
@@ -1009,6 +1011,13 @@ function requiredChecksVerdict(s: PrState, protocol?: MergeProtocol): "blocked"
 }
 
 export function classifyMergeability(s: PrState, protocol?: MergeProtocol): Mergeability {
+  // A draft PR is NEVER landable — GitHub refuses the merge outright, whatever its checks say — so
+  // draft outranks every other signal (issue #454). Surface it as a first-class verdict rather than
+  // letting a green draft read as `CLEAN` → `"ready"` → an attempted merge that GitHub blocks with an
+  // opaque "the merge did not land (blocked)" escalation. The remedy is always the same: mark it
+  // ready. The poller self-heals this (mark-ready) when the repo's protocol wants a fresh head run,
+  // else escalates with an actionable message.
+  if (s.isDraft) return "draft";
   // Protocol-aware backstop FIRST (issue #392): honour the repo's declared `requiredChecks`
   // against the actual head rollup, so an `UNSTABLE` PR with a red DECLARED-required
   // check is no longer blindly `ready`. This never weakens GitHub branch protection (the switch

package/app/maybeEnsureFreshHeadRun.test.ts

@@ -0,0 +1,150 @@
+// Regression guard for the frugal-CI self-heal escalation fall-through (PR #455 review).
+//
+// `maybeEnsureFreshHeadRun` gates the `"draft"` merge branch: the poller `continue`s (re-polls)
+// when it returns `true`, and falls through to the actionable "mark it ready" escalation when it
+// returns `false`. The bug: it returned `true` whenever an action was *selected*, even if
+// `ensureFreshHeadRun` FAILED (`ok === false`, e.g. missing permission / repo policy). A draft PR
+// whose self-heal can never succeed would then `continue` forever, re-attempting `gh pr ready`/
+// reopen every pass and never escalating to a human. The fix returns `ok`, so a persistently
+// failing self-heal falls through to escalation. These tests pin: return value tracks `ok`;
+// persistence (`fresh_head_run_head`) happens only on success; and no action → no attempt.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import type { PrState } from "./github.ts";
+import { parseMergeProtocol } from "./mergeProtocol.ts";
+import { maybeEnsureFreshHeadRun, type PullRequest } from "./service.ts";
+
+const READY = parseMergeProtocol({ freshHeadRun: "ready", land: { method: "gh-merge" } });
+
+function memData(seed: PullRequest): { data: DataLayer; row: () => PullRequest } {
+  const rows: PullRequest[] = [{ ...seed }];
+  const table = {
+    async update(id: string, patch: Partial<PullRequest>) {
+      const r = rows.find((x) => x.pr_key === id);
+      if (r) Object.assign(r, patch);
+    },
+  };
+  const data = { table: () => table } as unknown as DataLayer;
+  return { data, row: () => rows[0] };
+}
+
+function draftState(overrides: Partial<PrState> = {}): PrState {
+  return {
+    merged: false,
+    state: "open",
+    mergeStateStatus: "DRAFT",
+    failingChecks: 0,
+    failingCheckNames: [],
+    totalChecks: 0, // no head run yet → frugal-CI stuck state
+    presentCheckNames: [],
+    pendingCheckNames: [],
+    checkConclusions: {},
+    isDraft: true,
+    headRefOid: "h1",
+    ...overrides,
+  };
+}
+
+function prRow(overrides: Partial<PullRequest> = {}): PullRequest {
+  return {
+    pr_key: "o/r#1",
+    repo: "o/r",
+    number: 1,
+    url: "https://github.com/o/r/pull/1",
+    title: "t",
+    status: "waiting_merge",
+    current_round: 0,
+    process_key: null,
+    waiting_since: null,
+    last_review_id: null,
+    outcome: null,
+    created_at: "t",
+    updated_at: "t",
+    converged_at: null,
+    merged_at: null,
+    active_worker: null,
+    lease_until: null,
+    last_nudge_at: null,
+    fresh_head_run_head: null,
+    abandon_token: null,
+    incident_key: null,
+    incident_message: null,
+    root_request_key: null,
+    ...overrides,
+  };
+}
+
+test("maybeEnsureFreshHeadRun: successful self-heal returns true and records the head", async () => {
+  const { data, row } = memData(prRow());
+  const ret = await maybeEnsureFreshHeadRun(
+    data,
+    "o/r",
+    1,
+    "o/r#1",
+    READY,
+    "draft",
+    draftState(),
+    prRow(),
+    async () => true,
+  );
+  assertEquals(ret, true); // caller re-polls
+  assertEquals(row().fresh_head_run_head, "h1"); // one-shot de-dupe recorded
+});
+
+test("maybeEnsureFreshHeadRun: FAILED self-heal returns false so the draft branch escalates", async () => {
+  const { data, row } = memData(prRow());
+  const ret = await maybeEnsureFreshHeadRun(
+    data,
+    "o/r",
+    1,
+    "o/r#1",
+    READY,
+    "draft",
+    draftState(),
+    prRow(),
+    async () => false, // ensureFreshHeadRun could not perform the action (e.g. permission)
+  );
+  assertEquals(ret, false); // caller falls through to the actionable escalation
+  assertEquals(row().fresh_head_run_head, null); // not recorded → not a wasted one-shot
+});
+
+test("maybeEnsureFreshHeadRun: a throwing self-heal is caught and returns false", async () => {
+  const { data, row } = memData(prRow());
+  const ret = await maybeEnsureFreshHeadRun(
+    data,
+    "o/r",
+    1,
+    "o/r#1",
+    READY,
+    "draft",
+    draftState(),
+    prRow(),
+    async () => {
+      throw new Error("boom");
+    },
+  );
+  assertEquals(ret, false);
+  assertEquals(row().fresh_head_run_head, null);
+});
+
+test("maybeEnsureFreshHeadRun: no applicable action never attempts the self-heal and returns false", async () => {
+  const { data } = memData(prRow());
+  let attempted = false;
+  const ret = await maybeEnsureFreshHeadRun(
+    data,
+    "o/r",
+    1,
+    "o/r#1",
+    READY,
+    "draft",
+    draftState({ totalChecks: 1 }), // required run already present → no action selected
+    prRow(),
+    async () => {
+      attempted = true;
+      return true;
+    },
+  );
+  assertEquals(ret, false);
+  assert(!attempted, "must not attempt a self-heal when no action applies");
+});

package/app/mergeEscalationQuestion.test.ts

@@ -155,3 +155,36 @@ test("regression: a question-less escalation can no longer park a dead wait-merg
     "merge-esc-attempt must NOT flow directly into wait-merge-answer (the #329 dead-wait defect)",
   );
 });
+
+// ── Draft PR escalation (issue #454) ─────────────────────────────────────────────────────────────
+//
+// A draft PR is never landable — `classifyMergeability` now yields a first-class `"draft"` verdict
+// (app/github.ts) that the poller (app/service.ts) publishes as `mergeState = "draft"`. It routes
+// through `gw-mergeable`'s default (`f_m_mBlocked → merge-esc-conflict`), so `merge-esc-conflict`'s
+// question must recognise `draft` and give the ACTIONABLE remedy (mark it ready) instead of the
+// generic "resolve the conflict or failing required check" text (which is the wrong remedy for a
+// draft), and — before this fix — instead of `merge-esc-attempt`'s misleading "the merge attempt did
+// not land (blocked), investigate why GitHub refused the merge".
+const escConflictRaw = flat.match(/<bpmn:serviceTask\b[^>]*\bid="merge-esc-conflict"[\s\S]*?<\/bpmn:serviceTask>/);
+const escConflict = escConflictRaw ? escConflictRaw[0].replace(/&#34;/g, '"').replace(/&#39;/g, "'").replace(/&amp;/g, "&") : null;
+
+test("merge-esc-conflict gives a draft PR an actionable 'mark it ready' question (issue #454)", () => {
+  assert(escConflict, "merge-esc-conflict service task must exist");
+  const el = escConflict!;
+  // Branches on the draft verdict…
+  assertStringIncludes(el, 'mergeState = "draft"', "merge-esc-conflict must branch on the draft verdict");
+  // …with the actionable remedy (mark it ready), not the conflict/failing-check remedy.
+  assertStringIncludes(el, "draft and can't be merged", "the draft question must state the PR is in draft");
+  assertStringIncludes(el, "gh pr ready", "the draft question must tell the human to mark it ready");
+});
+
+test("merge-esc-conflict keeps the non-draft not-mergeable branch intact (regression guard, issue #454)", () => {
+  assert(escConflict, "merge-esc-conflict service task must exist");
+  const el = escConflict!;
+  // The original conflict/failing-check message must still be reachable for non-draft states.
+  assertStringIncludes(el, "This PR is not mergeable (state:", "the non-draft not-mergeable message must remain");
+  // The draft branch must precede the generic message so it isn't shadowed.
+  const draftIdx = el.indexOf('mergeState = "draft"');
+  const genericIdx = el.indexOf("This PR is not mergeable (state:");
+  assert(draftIdx !== -1 && genericIdx !== -1 && draftIdx < genericIdx, "the draft branch must be evaluated before the generic not-mergeable message");
+});

package/app/mergeProtocol.test.ts

@@ -114,6 +114,31 @@ test("freshHeadRunAction: fires in the frugal-CI stuck state (no run + waiting)"
   assertEquals(freshHeadRunAction(NANO, "waiting", 0, true), "ready");
 });
 
+test("freshHeadRunAction: a 'draft' verdict self-heals like waiting (issue #454)", () => {
+  // The merge poller now classifies a draft PR as the distinct "draft" verdict (not "waiting"),
+  // so guard that the fresh-head-run self-heal accepts it directly. A draft is always isDraft=true.
+  assertEquals(freshHeadRunAction(NANO, "draft", 0, true), "ready"); // no run yet → mark ready (un-drafts + runs)
+  assertEquals(freshHeadRunAction(NANO, "draft", 1, true), null); // required run already present → wait
+  assertEquals(freshHeadRunAction(NANO, "draft", -1, true), null); // token mode (unknown) → conservative
+  // fires once per landing-attempt head, then not again until the head changes (post-rebase)
+  assertEquals(
+    freshHeadRunAction(NANO, "draft", 0, true, { headRefOid: "h1", lastActionHeadRefOid: null }),
+    "ready",
+  );
+  assertEquals(
+    freshHeadRunAction(NANO, "draft", 0, true, { headRefOid: "h1", lastActionHeadRefOid: "h1" }),
+    null,
+  );
+  // reopen-only protocol: a draft yields NULL, not "reopen". Reopening (close+reopen) does NOT
+  // un-draft a PR, so a "reopen" self-heal can never resolve the draft-merge failure — it only
+  // emits noisy close/reopen events and delays the actionable escalation by a round (issue #454).
+  // With no mark-ready capability there is no valid draft self-heal, so escalate immediately.
+  const reopenOnly = parseMergeProtocol({ freshHeadRun: "reopen", land: { method: "gh-merge" } });
+  assertEquals(freshHeadRunAction(reopenOnly, "draft", 0, true), null);
+  // none protocol → no self-heal for a draft either
+  assertEquals(freshHeadRunAction(DEFAULT_MERGE_PROTOCOL, "draft", 0, true), null);
+});
+
 test("freshHeadRunAction: fires once per landing-attempt head, then re-fires after rebase", () => {
   assertEquals(
     freshHeadRunAction(NANO, "waiting", 0, false, { headRefOid: "h1", lastActionHeadRefOid: null }),

package/app/mergeProtocol.ts

@@ -241,23 +241,29 @@ export function headRunPresenceCount(
  * same head already got its nudge, this returns `null`, so the poller never re-triggers inside one
  * landing attempt. A rebase changes `headRefOid`, so the decision is re-derived and can fire again
  * for the fresh post-rebase head. A genuinely-failing check (`blocked`) is left to the fix-ci arm,
- * a conflict (`conflict`) to the rebase arm (#42). */
+ * a conflict (`conflict`) to the rebase arm (#42). A `draft` verdict (issue #454) is treated like
+ * `waiting` here so the `freshHeadRun: "ready"`/`"ready-or-reopen"` self-heal still marks a draft
+ * ready (which both un-drafts it and produces the required run). But a `"reopen"` action is
+ * **never** returned for a draft: reopening (close+reopen) does not un-draft a PR, so it can never
+ * resolve the draft-merge failure — it only emits noisy close/reopen events and delays the poller's
+ * actionable escalation. When no mark-ready self-heal applies to a draft, this returns `null` and the
+ * poller escalates immediately. */
 export function freshHeadRunAction(
   protocol: MergeProtocol,
-  verdict: "ready" | "waiting" | "conflict" | "blocked",
+  verdict: "ready" | "waiting" | "conflict" | "blocked" | "draft",
   headRunCount: number,
   isDraft: boolean,
   attempt: FreshHeadRunAttempt = {},
 ): "ready" | "reopen" | null {
   if (protocol.freshHeadRun === "none") return null;
-  if (verdict !== "waiting") return null; // ready = go land; blocked/conflict = other arms
+  if (verdict !== "waiting" && verdict !== "draft") return null; // ready = go land; blocked/conflict = other arms
   if (headRunCount !== 0) return null; // required run already present (or unknown in token mode) → wait
   if (attempt.headRefOid && attempt.headRefOid === attempt.lastActionHeadRefOid) return null;
   switch (protocol.freshHeadRun) {
     case "ready":
       return isDraft ? "ready" : null;
     case "reopen":
-      return "reopen";
+      return isDraft ? null : "reopen";
     case "ready-or-reopen":
       return isDraft ? "ready" : "reopen";
     default: