@nanobpm/nano-workforce 0.57.0 → 0.58.1

package/app/agentCompletion.ts

@@ -0,0 +1,219 @@
+// Attributed escalation completion (epic #156, slice U6; ADR 0046) — the SINGLE place an escalation
+// user task is completed on the host side, so an AGENT assignee can answer the exact same `.form` a
+// human would without forking a second lane or a second completion implementation.
+//
+// Every escalation the epic migrated (task, plan-review, trial-merge, PR review-loop) parks on a
+// native `userTask` bearing a linked `.form`. Whoever holds the assignment completes it with the
+// form's typed variables, and the engine resumes the process. This module wraps that one canonical
+// primitive (`engine.completeUserTask`) with two cross-cutting concerns ADR 0046 requires of an
+// agent-answerable escalation:
+//
+//   • Attribution — record WHO completed the task (an agent identity vs a human) and the exact
+//     typed variables they submitted, in the `task_completions` ledger, so the audit trail can tell
+//     an agent answer apart from a human one.
+//   • Reversibility — a completed user task cannot be un-completed in the engine, so an AGENT answer
+//     must not be a silent irreversible commit: it is recorded `reversible`, and a human can mark it
+//     reverted/overridden (recording who + when). Host-side consumers read the ledger to see whether
+//     the latest completion is still authoritative.
+//
+// Derivation over duplication: the human out-of-band answer paths (app/plan.ts) route through the
+// SAME `completeUserTaskAttributed` (as `human`), so there is exactly one implementation of "complete
+// an escalation user task" — the agent path is an extension of it, not a parallel copy.
+
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+
+const now = () => new Date().toISOString();
+
+/** Who completed an escalation user task. `agent` completions are reversible (a human may override);
+ *  `human` completions are already the authority. */
+export type ActorKind = "agent" | "human";
+
+/** The completing identity: an agent (per ADR 0046) or a human operator. `id` is the audit handle
+ *  (agent id / operator name). */
+export interface Actor {
+  kind: ActorKind;
+  id: string;
+}
+
+/** One escalation user-task completion, recorded for attribution + reversibility. */
+export interface TaskCompletion {
+  id: number;
+  user_task_key: string;
+  process_instance_key: string | null;
+  element_id: string | null;
+  actor_kind: ActorKind;
+  actor_id: string;
+  /** The typed form variables submitted, as JSON — the same shape a human submits. */
+  variables_json: string;
+  /** 1 when a human may still override this completion (agent completions). */
+  reversible: number;
+  /** 1 once a human has reverted/overridden it. */
+  reverted: number;
+  reverted_by: string | null;
+  /** The human's corrective guidance that overrides the agent answer (when supplied on revert). */
+  reverted_note: string | null;
+  reverted_at: string | null;
+  created_at: string;
+}
+
+export const taskCompletions = (data: DataLayer) =>
+  data.table<TaskCompletion>("task_completions", "id");
+
+/** The escalation user-task `elementId`s an agent assignee may answer (the four kinds the epic
+ *  migrated to `userTask` + `.form`). The agent completer refuses any other parked task, so the
+ *  agent path is scoped to escalations — it can never complete an arbitrary internal user task. */
+export const ESCALATION_TASK_ELEMENTS: ReadonlySet<string> = new Set([
+  "feature-escalation",
+  "plan-review-decision",
+  "trial-merge-decision",
+  "wait-answer", // PR review-loop escalation (convergence-loop.bpmn, U3)
+]);
+
+/** The canonical attributed completer. Records an attribution row in `task_completions` (reversible
+ *  iff the actor is an agent) and THEN completes the user task with the exact typed `variables` — so
+ *  the ledger row can never be lost by a resume that fires before the write. If the engine
+ *  completion throws (a failed/rejected completion, or a lost race), the just-written row is rolled
+ *  back so the ledger never claims a completion that did not happen, and the error is re-raised so
+ *  the caller can retry. Returns the new completion id. This is the ONE host-side implementation of
+ *  "complete an escalation user task"; both the agent path and the human out-of-band answer paths
+ *  route through it. */
+export async function completeUserTaskAttributed(
+  data: DataLayer,
+  engine: EngineClient,
+  target: {
+    userTaskKey: string;
+    processInstanceKey?: string | null;
+    elementId?: string | null;
+    variables: Record<string, unknown>;
+  },
+  actor: Actor,
+): Promise<{ completionId: number }> {
+  // Normalize + validate the attribution keys upfront so the ledger can never record a row with
+  // blank attribution or whitespace-mismatched keys.
+  const userTaskKey = target.userTaskKey.trim();
+  if (!userTaskKey) throw new Error("userTaskKey is required");
+  const actorId = actor.id.trim();
+  if (!actorId) throw new Error("actor id is required");
+
+  const reversible = actor.kind === "agent";
+  const id = await taskCompletions(data).insert({
+    user_task_key: userTaskKey,
+    process_instance_key: target.processInstanceKey ?? null,
+    element_id: target.elementId ?? null,
+    actor_kind: actor.kind,
+    actor_id: actorId,
+    variables_json: JSON.stringify(target.variables ?? {}),
+    reversible: reversible ? 1 : 0,
+    reverted: 0,
+    reverted_by: null,
+    reverted_note: null,
+    reverted_at: null,
+    created_at: now(),
+  });
+  const completionId = Number(id);
+  try {
+    await engine.completeUserTask(userTaskKey, target.variables);
+  } catch (err) {
+    // The completion did not take — roll the attribution row back so the ledger reflects only
+    // completions that actually happened, and let the caller retry. The rollback is best-effort:
+    // if the delete itself throws, the engine failure remains the primary signal we re-raise.
+    try {
+      await taskCompletions(data).delete(completionId);
+    } catch {
+      // swallow — never let a rollback failure mask the original engine error
+    }
+    throw err;
+  }
+  return { completionId };
+}
+
+/** The newest recorded completion for a user-task key, or undefined. */
+export async function latestCompletion(
+  data: DataLayer,
+  userTaskKey: string,
+): Promise<TaskCompletion | undefined> {
+  const rows = await taskCompletions(data).find({ user_task_key: userTaskKey });
+  let newest: TaskCompletion | undefined;
+  for (const row of rows) {
+    if (!newest || row.id > newest.id) newest = row;
+  }
+  return newest;
+}
+
+export interface AgentCompleteResult {
+  ok: boolean;
+  reason?: string;
+  completionId?: number;
+  userTaskKey?: string;
+  elementId?: string;
+}
+
+/** Complete an escalation user task AS AN AGENT (ADR 0046). Resolves the parked task by its key,
+ *  refuses anything that is not one of the migrated escalation tasks, and routes the typed form
+ *  variables through the shared attributed completer with the agent's identity. Reuses the exact
+ *  form contract + resume path a human uses — no parallel completion. A key with no matching open
+ *  escalation task is a 404-style no-op. */
+export async function completeEscalationAsAgent(
+  data: DataLayer,
+  engine: EngineClient,
+  input: { userTaskKey: string; variables: Record<string, unknown>; agentId: string },
+): Promise<AgentCompleteResult> {
+  const userTaskKey = input.userTaskKey.trim();
+  if (!userTaskKey) return { ok: false, reason: "userTaskKey is required" };
+  const agentId = input.agentId.trim();
+  if (!agentId) return { ok: false, reason: "agentId is required" };
+
+  const open = await engine.searchUserTasks();
+  const match = open.find((t) => t.userTaskKey === userTaskKey);
+  if (!match) return { ok: false, reason: "no open escalation task" };
+  if (!match.elementId || !ESCALATION_TASK_ELEMENTS.has(match.elementId)) {
+    return { ok: false, reason: "not an escalation task" };
+  }
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    {
+      userTaskKey,
+      elementId: match.elementId,
+      variables: input.variables,
+    },
+    { kind: "agent", id: agentId },
+  );
+  return { ok: true, completionId, userTaskKey, elementId: match.elementId };
+}
+
+export interface RevertResult {
+  ok: boolean;
+  reason?: string;
+  completionId?: number;
+}
+
+/** Revert/override an AGENT escalation completion (the reversibility guarantee of ADR 0046). A human
+ *  marks a reversible, not-yet-reverted agent completion reverted, recording who did it, when, and
+ *  optionally the corrective guidance that overrides the agent's answer — so the agent's answer is no
+ *  longer treated as authoritative and the human correction is captured. Human completions are not
+ *  reversible (they are already the authority), and a completion can only be reverted once. */
+export async function revertAgentCompletion(
+  data: DataLayer,
+  completionId: number,
+  reverter: Actor,
+  note?: string,
+): Promise<RevertResult> {
+  const row = await taskCompletions(data).get(completionId);
+  if (!row) return { ok: false, reason: "no such completion" };
+  if (reverter.kind !== "human") return { ok: false, reason: "only a human may revert a completion" };
+  if (!row.reversible) return { ok: false, reason: "completion is not reversible" };
+  if (row.reverted) return { ok: false, reason: "completion already reverted" };
+  const reverterId = reverter.id.trim();
+  if (!reverterId) return { ok: false, reason: "reverter id is required" };
+
+  const correction = typeof note === "string" ? note.trim() : "";
+  await taskCompletions(data).update(completionId, {
+    reverted: 1,
+    reverted_by: reverterId,
+    reverted_note: correction || null,
+    reverted_at: now(),
+  });
+  return { ok: true, completionId };
+}

package/app/answer-escalation.test.ts

@@ -0,0 +1,106 @@
+// Red/green regression for pr.answer-escalation (Copilot review of PR #180).
+//
+// The review-loop escalation migrated from a message catch to a native `wait-answer` userTask.
+// Completing the task resumes the token, but nothing retired the durable `escalations` audit row —
+// so it stayed `status="open"` with a null `answer`/`answered_at` forever, both losing the Q&A
+// trail and (since `activePrs` derives `openEscalation` from that row) surfacing a phantom open
+// escalation on `/status` after it was answered. `pr.answer-escalation` runs on `wait-answer`
+// completion and must transition the latest open row to `answered`, recording the submitted answer.
+//
+// It must ALSO move the `pull_requests` row off `status="escalated"` back to `"converging"`, exactly
+// as the merge-loop's `answerEscalation` message path does. Otherwise the PR stays `escalated` (with
+// a now-null `openEscalation`) until the re-entered round's `persist-round` runs — an inconsistent
+// `/status` window and a divergence from the merge loop the two paths are meant to share.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import handler from "../workers/answer-escalation/worker.ts";
+
+function fakeApp(escalationRows: Record<string, unknown>[]) {
+  const updates: { key: unknown; patch: Record<string, unknown> }[] = [];
+  const prUpdates: { key: unknown; patch: Record<string, unknown> }[] = [];
+  const app = {
+    data: {
+      table(name: string, _key: string) {
+        if (name === "pull_requests") {
+          return {
+            async update(key: unknown, patch: Record<string, unknown>) {
+              prUpdates.push({ key, patch });
+            },
+          };
+        }
+        if (name !== "escalations") throw new Error(`unexpected table ${name}`);
+        return {
+          async find(where: Record<string, unknown>) {
+            return escalationRows.filter((r) =>
+              Object.entries(where).every(([k, v]) => r[k] === v)
+            );
+          },
+          async update(key: unknown, patch: Record<string, unknown>) {
+            updates.push({ key, patch });
+          },
+        };
+      },
+    },
+  };
+  return { app, updates, prUpdates };
+}
+
+test("retires the latest open escalation to answered with the submitted answer", async () => {
+  const rows = [
+    { id: 5, pr_key: "o/r#1", status: "answered", question: "old" },
+    { id: 7, pr_key: "o/r#1", status: "open", question: "Which retry cap?" },
+  ];
+  const { app, updates, prUpdates } = fakeApp(rows);
+  const job = { variables: { prKey: "o/r#1", answer: "  Cap at 5.  " } };
+  await handler(job as any, app as any);
+  assertEquals(updates.length, 1, "exactly the one open row is retired");
+  assertEquals(updates[0].key, 7, "the newest open row (not the already-answered one) is retired");
+  assertEquals(updates[0].patch.status, "answered");
+  assertEquals(updates[0].patch.answer, "Cap at 5.", "the answer is trimmed and recorded");
+  assertEquals(typeof updates[0].patch.answered_at, "string", "answered_at is stamped");
+  assertEquals(prUpdates.length, 1, "the PR row is moved off `escalated`");
+  assertEquals(prUpdates[0].key, "o/r#1", "the PR keyed by prKey is updated");
+  assertEquals(prUpdates[0].patch.status, "converging", "mirrors answerEscalation: back to converging");
+  assertEquals(typeof prUpdates[0].patch.updated_at, "string", "updated_at is stamped");
+});
+
+test("retires ALL open rows: newest answered, any duplicate open rows marked stale", async () => {
+  // `pr.persist-escalation` always INSERTs a new open row, so a retry/duplicate activation can
+  // leave more than one `status="open"` row for the same PR. Answering only the newest would leave
+  // an older open row behind — a phantom that keeps `activePrs` deriving an open escalation while
+  // the PR is still `escalated`. Every open row for the PR must leave `open` in this completion.
+  const rows = [
+    { id: 3, pr_key: "o/r#1", status: "open", question: "stale dup A" },
+    { id: 7, pr_key: "o/r#1", status: "open", question: "Which retry cap?" },
+    { id: 9, pr_key: "o/r#2", status: "open", question: "other PR — untouched" },
+  ];
+  const { app, updates, prUpdates } = fakeApp(rows);
+  const job = { variables: { prKey: "o/r#1", answer: "Cap at 5." } };
+  await handler(job as any, app as any);
+  assertEquals(updates.length, 2, "both open rows for this PR are retired; the other PR is untouched");
+  const answered = updates.find((u) => u.key === 7);
+  const stale = updates.find((u) => u.key === 3);
+  assertEquals(answered?.patch.status, "answered", "the newest open row is answered");
+  assertEquals(answered?.patch.answer, "Cap at 5.", "the answer is recorded on the newest row");
+  assertEquals(stale?.patch.status, "stale", "the older duplicate open row is marked stale");
+  assertEquals(prUpdates.length, 1, "the PR row is moved off `escalated` exactly once");
+  assertEquals(prUpdates[0].patch.status, "converging");
+});
+
+test("no open row is a no-op (idempotent re-completion)", async () => {
+  const rows = [{ id: 7, pr_key: "o/r#1", status: "answered", question: "Which retry cap?" }];
+  const { app, updates, prUpdates } = fakeApp(rows);
+  const job = { variables: { prKey: "o/r#1", answer: "again" } };
+  await handler(job as any, app as any);
+  assertEquals(updates.length, 0, "nothing to retire when no escalation is open");
+  assertEquals(prUpdates.length, 0, "no open row → PR status is left untouched");
+});
+
+test("a blank answer is recorded as NULL, not an empty string", async () => {
+  const rows = [{ id: 7, pr_key: "o/r#1", status: "open", question: "Which retry cap?" }];
+  const { app, updates } = fakeApp(rows);
+  const job = { variables: { prKey: "o/r#1", answer: "   " } };
+  await handler(job as any, app as any);
+  assertEquals(updates[0].patch.answer, null);
+  assertEquals(updates[0].patch.status, "answered");
+});

package/app/answerEscalation.test.ts

@@ -0,0 +1,67 @@
+// Red/green regression for answerEscalation (merge-loop message path) — Copilot review of PR #180.
+//
+// `pr.persist-escalation` always INSERTs a fresh `escalations` row with `status="open"`, so a
+// retry/duplicate activation can leave more than one open row for the same PR. answerEscalation
+// only closed the NEWEST open row, leaving older duplicates `open` — a phantom that keeps
+// `activePrs` deriving an open escalation while the PR is still `escalated`. Every open row for the
+// PR must leave `open` in this completion (newest answered, the rest marked `stale`), exactly as
+// `submitPr`'s resubmit cleanup already does. Mirrors the review loop's `pr.answer-escalation`.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { answerEscalation } from "./service.ts";
+
+function memData(escalations: any[], prs: any[]): DataLayer {
+  const table = (name: string, key: string) => ({
+    async find(where: Record<string, unknown>) {
+      const src = name === "escalations" ? escalations : prs;
+      return src.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+    },
+    async update(k: unknown, patch: Record<string, unknown>) {
+      const src = name === "escalations" ? escalations : prs;
+      const r = src.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return r;
+    },
+  });
+  return { table } as any as DataLayer;
+}
+
+function fakeEngine(published: any[]): EngineClient {
+  return {
+    async publishMessage(m: any) {
+      published.push(m);
+    },
+  } as any as EngineClient;
+}
+
+test("answerEscalation answers the newest open row and marks duplicate open rows stale", async () => {
+  const escalations = [
+    { id: 3, pr_key: "o/r#1", status: "open", answer: null, answered_at: null },
+    { id: 7, pr_key: "o/r#1", status: "open", answer: null, answered_at: null },
+    { id: 9, pr_key: "o/r#2", status: "open", answer: null, answered_at: null },
+  ];
+  const prs = [{ pr_key: "o/r#1", status: "escalated", updated_at: "t0" }];
+  const published: any[] = [];
+  const res = await answerEscalation(memData(escalations, prs), fakeEngine(published), "o/r#1", "Cap at 5.");
+
+  assertEquals(res, { ok: true, escalationId: 7 }, "the newest open row is the one answered");
+  const answered = escalations.find((e) => e.id === 7);
+  const stale = escalations.find((e) => e.id === 3);
+  const other = escalations.find((e) => e.id === 9);
+  assertEquals(answered?.status, "answered");
+  assertEquals(answered?.answer, "Cap at 5.");
+  assertEquals(stale?.status, "stale", "the older duplicate open row is retired to stale");
+  assertEquals(other?.status, "open", "the other PR's open row is untouched");
+  assertEquals(prs[0].status, "converging", "the PR row is moved off escalated");
+  assertEquals(published.length, 1, "the resume message is published once");
+  assertEquals(published[0].variables.escalationId, 7);
+});
+
+test("answerEscalation is a no-op when no row is open", async () => {
+  const escalations = [{ id: 7, pr_key: "o/r#1", status: "answered", answer: "x", answered_at: "t" }];
+  const published: any[] = [];
+  const res = await answerEscalation(memData(escalations, []), fakeEngine(published), "o/r#1", "again");
+  assertEquals(res, { ok: false, reason: "no open escalation" });
+  assertEquals(published.length, 0);
+});

package/app/baseGuard.test.ts

@@ -1,7 +1,7 @@
 // Unit tests for the dead-end-base guard decision (#60).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { type BaseTarget, isDeadEndBase } from "./baseGuard.ts";
+import { type BaseTarget, classifyBaseGuard, isDeadEndBase } from "./baseGuard.ts";
 
 const t = (base: string, defaultBranch: string, landed: BaseTarget["landed"]): BaseTarget => ({
   base,
@@ -34,3 +34,11 @@ test("unknown-safe: blank base or blank default is never a dead-end", () => {
   assertEquals(isDeadEndBase(t("", "main", "landed")), false);
   assertEquals(isDeadEndBase(t("feat/x", "", "landed")), false);
 });
+
+// The dead-end base is classified against the canonical escalation taxonomy: a confirmed dead end
+// is a decision-required escalation (a human must retarget); anything else is not an escalation, so
+// the merge worker never blocks a valid merge on ambiguity.
+test("classifyBaseGuard: a confirmed dead end is decision-required, else none", () => {
+  assertEquals(classifyBaseGuard({ deadEnd: true }), "decision-required");
+  assertEquals(classifyBaseGuard({ deadEnd: false }), "none");
+});

package/app/baseGuard.ts

@@ -9,6 +9,7 @@
 //
 // This module detects that case so the merge worker can escalate (retarget) instead of landing.
 
+import { classifyEscalation, type EscalationDisposition } from "./escalationTaxonomy.ts";
 import { baseBranchLanded, fetchDefaultBranch, fetchPrBase } from "./github.ts";
 
 /** The landing-target facts the dead-end decision is made from. */
@@ -60,3 +61,13 @@ export async function checkBaseTarget(
   const target: BaseTarget = { base, defaultBranch, landed };
   return { deadEnd: isDeadEndBase(target), base, defaultBranch, landed };
 }
+
+/** Classify a base-guard result against the canonical escalation taxonomy. A confirmed
+ * dead-end base is a `decision-required` escalation (a human must retarget the PR); anything
+ * else — a legitimately-stacked open base, an ambiguous signal, or a transport hiccup — is not
+ * an escalation (`none`), so the guard never blocks a valid merge. Delegates to
+ * {@link classifyEscalation} so the merge worker shares one source of truth with every other
+ * raise site. */
+export function classifyBaseGuard(result: Pick<BaseGuardResult, "deadEnd">): EscalationDisposition {
+  return classifyEscalation({ kind: "dead-end-base", deadEnd: result.deadEnd });
+}

package/app/escalationSla.test.ts

@@ -0,0 +1,39 @@
+// Unit coverage for the escalation-of-the-escalation SLA duration policy (U5, #156). The value is
+// baked into every plan-fanout instance's `escalationSlaTimeout` process variable and evaluated by
+// each escalation user task's interrupting timer boundary, so a malformed operator env must never
+// deploy an uninterpretable `<bpmn:timeDuration>` — it falls back to the default instead. Run with
+// `node --test`.
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
+
+test("escalationSlaTimeout: blank / absent / malformed → default", () => {
+  assert.equal(escalationSlaTimeout(undefined), DEFAULT_ESCALATION_SLA_TIMEOUT);
+  assert.equal(escalationSlaTimeout(""), DEFAULT_ESCALATION_SLA_TIMEOUT);
+  assert.equal(escalationSlaTimeout("   "), DEFAULT_ESCALATION_SLA_TIMEOUT);
+  assert.equal(escalationSlaTimeout("2h"), DEFAULT_ESCALATION_SLA_TIMEOUT); // missing leading P/T
+  assert.equal(escalationSlaTimeout("P"), DEFAULT_ESCALATION_SLA_TIMEOUT); // no component
+  assert.equal(escalationSlaTimeout("PT"), DEFAULT_ESCALATION_SLA_TIMEOUT); // T with no time part
+  assert.equal(escalationSlaTimeout("garbage"), DEFAULT_ESCALATION_SLA_TIMEOUT);
+});
+
+test("escalationSlaTimeout: a valid ISO-8601 duration is honoured and upper-cased", () => {
+  assert.equal(escalationSlaTimeout("PT30M"), "PT30M");
+  assert.equal(escalationSlaTimeout("pt2h"), "PT2H");
+  assert.equal(escalationSlaTimeout("P1D"), "P1D");
+  assert.equal(escalationSlaTimeout("  pt15m  "), "PT15M");
+});
+
+test("escalationSlaTimeout: an explicit fallback is honoured for a bad value", () => {
+  assert.equal(escalationSlaTimeout("nope", "PT10M"), "PT10M");
+  assert.equal(escalationSlaTimeout("PT45M", "PT10M"), "PT45M");
+});
+
+test("the default is itself a well-formed ISO-8601 duration (never an uninterpretable timer)", () => {
+  // Validate the default against the grammar with a *distinct* fallback: if the default were
+  // malformed it would fall through to the sentinel, so equality to itself proves it parses.
+  const sentinel = "PT1S";
+  assert.notEqual(DEFAULT_ESCALATION_SLA_TIMEOUT, sentinel);
+  assert.equal(escalationSlaTimeout(DEFAULT_ESCALATION_SLA_TIMEOUT, sentinel), DEFAULT_ESCALATION_SLA_TIMEOUT);
+});

package/app/escalationSla.ts

@@ -0,0 +1,28 @@
+// Escalation-of-the-escalation SLA policy (epic #156, slice U5), kept as a pure module (no env, no
+// I/O) so it is trivially testable — mirrors app/reviewWait.ts. `app/plan.ts` seeds the validated
+// `escalationSlaTimeout` process variable at submit; the escalation user tasks in
+// plan-fanout.bpmn carry an interrupting timer boundary whose `<bpmn:timeDuration>=escalationSlaTimeout`
+// evaluates it at timer creation (FEEL-expression timer durations, engine-native).
+//
+// This models liveness IN the process: an escalation user task a human never answers can no longer
+// hang forever — when the SLA elapses the boundary fires and the token auto-proceeds down each
+// gateway's existing safe-default arm. It is the durable, in-process replacement for a poller-side
+// watchdog: no external actor is required and forward progress is always possible.
+
+import { isoDuration } from "./reviewWait.ts";
+
+/** Default escalation SLA (ISO-8601 duration): how long an escalation user task may sit unanswered
+ * before its timer boundary fires and the process auto-proceeds down the safe-default arm. A day is
+ * generous for a human decision while still bounding the wait. */
+export const DEFAULT_ESCALATION_SLA_TIMEOUT = "PT24H";
+
+/** Validate the operator-supplied escalation SLA (env `NANO_ESCALATION_SLA_TIMEOUT`, ISO-8601
+ * duration), falling back to {@link DEFAULT_ESCALATION_SLA_TIMEOUT} when absent, blank, or
+ * malformed — a bad env value must never deploy an uninterpretable timer expression. Derives its
+ * validation from the single canonical {@link isoDuration}. */
+export function escalationSlaTimeout(
+  raw: string | undefined,
+  def: string = DEFAULT_ESCALATION_SLA_TIMEOUT,
+): string {
+  return isoDuration(raw, def);
+}

package/app/escalationTaxonomy.test.ts

@@ -0,0 +1,115 @@
+// Unit coverage for the canonical escalation taxonomy (app/escalationTaxonomy.ts) — the single
+// source of truth every raise site and escalation-conversion slice routes through (ADR 0002 §1).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import {
+  classifyEscalation,
+  type EscalationSignal,
+  hasAnswerableQuestion,
+  shouldRaiseTask,
+} from "./escalationTaxonomy.ts";
+
+test("hasAnswerableQuestion: only a non-blank string is answerable", () => {
+  assertEquals(hasAnswerableQuestion("decide this"), true);
+  assertEquals(hasAnswerableQuestion("  trimmed  "), true);
+  for (const blank of [undefined, null, "", "   ", "\n\t"]) {
+    assertEquals(hasAnswerableQuestion(blank), false, `blank ${JSON.stringify(blank)} is not answerable`);
+  }
+});
+
+// --- review-round (roundResultDefault / gw-status) ---
+
+test("review-round: an unknown/empty/converged status is transient (the empty-status backstop)", () => {
+  for (const status of [undefined, "", "unknown", "converged", "addressed", "waiting"]) {
+    assertEquals(
+      classifyEscalation({ kind: "review-round", status, question: "ignored" }),
+      "transient",
+      `status ${JSON.stringify(status)} re-enters the loop`,
+    );
+  }
+});
+
+test("review-round: a human-blocking status WITH an answerable question is decision-required", () => {
+  for (const status of ["needs_input", "blocked"]) {
+    assertEquals(classifyEscalation({ kind: "review-round", status, question: "please decide" }), "decision-required");
+  }
+});
+
+test("review-round: status is matched exactly (untrimmed), mirroring the gw-status conditions", () => {
+  // The gw-status gateway does not trim `status`, so a whitespace-padded token is NOT the enum
+  // value and stays transient. Pins the no-drift contract between this taxonomy and the model.
+  for (const status of ["needs_input ", " needs_input", "blocked ", "converged "]) {
+    assertEquals(
+      classifyEscalation({ kind: "review-round", status, question: "please decide" }),
+      "transient",
+      `whitespace-padded status ${JSON.stringify(status)} is not the enum → transient`,
+    );
+  }
+});
+
+test("review-round: a human-blocking status with a BLANK question is a non-escalation", () => {
+  for (const status of ["needs_input", "blocked"]) {
+    for (const question of [undefined, "", "   "]) {
+      assertEquals(
+        classifyEscalation({ kind: "review-round", status, question }),
+        "none",
+        `blank-question ${status} cannot fabricate an escalation`,
+      );
+    }
+  }
+});
+
+// --- dead-end-base (baseGuard) ---
+
+test("dead-end-base: a confirmed dead end is decision-required; ambiguity is none", () => {
+  assertEquals(classifyEscalation({ kind: "dead-end-base", deadEnd: true }), "decision-required");
+  assertEquals(classifyEscalation({ kind: "dead-end-base", deadEnd: false }), "none");
+  assertEquals(classifyEscalation({ kind: "dead-end-base" }), "none");
+});
+
+// --- merge-protocol (mergeProtocol) ---
+
+test("merge-protocol: only a `ui` land method is decision-required; the rest are transient", () => {
+  assertEquals(classifyEscalation({ kind: "merge-protocol", landMethod: "ui" }), "decision-required");
+  for (const landMethod of ["gh-merge", "admin", "mergify-queue", undefined]) {
+    assertEquals(
+      classifyEscalation({ kind: "merge-protocol", landMethod }),
+      "transient",
+      `land method ${JSON.stringify(landMethod)} lands in-process`,
+    );
+  }
+});
+
+// --- task (plan-fanout w_gw "escalated?") ---
+
+test("task: status=escalated with an answerable question is decision-required; blank is none", () => {
+  assertEquals(classifyEscalation({ kind: "task", question: "which approach?" }), "decision-required");
+  for (const question of [undefined, "", "   "]) {
+    assertEquals(
+      classifyEscalation({ kind: "task", question }),
+      "none",
+      "a blank-question escalated task is a non-escalation",
+    );
+  }
+});
+
+// --- the shared guard ---
+
+test("shouldRaiseTask: true only for the decision-required tier", () => {
+  const raised: EscalationSignal[] = [
+    { kind: "review-round", status: "needs_input", question: "q" },
+    { kind: "dead-end-base", deadEnd: true },
+    { kind: "merge-protocol", landMethod: "ui" },
+    { kind: "task", question: "q" },
+  ];
+  for (const s of raised) assert(shouldRaiseTask(s), `${s.kind} should raise a task`);
+
+  const notRaised: EscalationSignal[] = [
+    { kind: "review-round", status: "needs_input", question: "" }, // blank question
+    { kind: "review-round", status: "waiting", question: "q" }, // transient
+    { kind: "dead-end-base", deadEnd: false }, // ambiguous
+    { kind: "merge-protocol", landMethod: "gh-merge" }, // transient
+    { kind: "task", question: "   " }, // blank question
+  ];
+  for (const s of notRaised) assertEquals(shouldRaiseTask(s), false, `${s.kind} should NOT raise a task`);
+});