@nanobpm/nano-workforce 0.57.0 → 0.58.0

package/app/plan.test.ts

@@ -127,94 +127,6 @@ test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
   assertEquals(stores.plan_tasks.rows.length, 0);
 });
 
-// Red/green regression for re-plan clearing stale open escalations (issue #25).
-//
-// `plan_escalations` is written by the implementation-phase escalation loop and denormalised onto
-// the plan row (`open_task_*`). When `startPlan` re-plans a finished issue it deletes the prior
-// `plan_tasks`, so any still-"open" escalation from that run points at a task that no longer
-// exists. If those rows (and the plan's denormalised pointer) survive the re-plan,
-// `refreshOpenTaskEscalation` re-surfaces a dead question in the answer form — the same
-// stale-row class as `plan_reviews` above. This drives `startPlan` against the in-memory data
-// layer and asserts both the escalation rows and the denormalised pointer are cleared.
-test("re-plan of a finished issue clears stale open escalations and the denormalised open_task_* pointer", async () => {
-  const PLAN_KEY = "owner/repo#8";
-  const stores: Record<string, { rows: unknown[]; key: string }> = {
-    plans: {
-      rows: [{
-        plan_key: PLAN_KEY,
-        status: "done",
-        task_count: 1,
-        open_task_escalation_id: 5,
-        open_task_question: "stale question from prior run?",
-        open_task_corr_key: `${PLAN_KEY}:task-1`,
-        open_task_id: "task-1",
-      }],
-      key: "plan_key",
-    },
-    plan_tasks: { rows: [{ id: 1, plan_key: PLAN_KEY, task_id: "task-1" }], key: "id" },
-    plan_reviews: { rows: [], key: "plan_key" },
-    plan_escalations: {
-      rows: [{
-        id: 5,
-        plan_key: PLAN_KEY,
-        task_id: "task-1",
-        corr_key: `${PLAN_KEY}:task-1`,
-        question: "stale question from prior run?",
-        status: "open",
-      }],
-      key: "id",
-    },
-    plan_task_deps: { rows: [], key: "plan_key" },
-  };
-  const data = {
-    table: (name: string, key: string) =>
-      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
-  } as any;
-  const engine = {
-    createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }),
-  } as any;
-
-  await startPlan(data, engine, {
-    repo: "owner/repo",
-    number: 8,
-    url: "https://github.com/owner/repo/issues/8",
-    planKey: PLAN_KEY,
-  }, "epic/agent-protocol");
-
-  // Stale escalation rows from the prior run must not survive a re-plan …
-  assertEquals(stores.plan_escalations.rows.length, 0);
-  // … and the plan's denormalised "surfaced escalation" pointer must be reset,
-  // so `refreshOpenTaskEscalation` can't re-surface a question for a deleted task.
-  const plan = stores.plans.rows[0] as Record<string, unknown>;
-  assertEquals(plan.open_task_escalation_id, null);
-  assertEquals(plan.open_task_question, null);
-  assertEquals(plan.open_task_corr_key, null);
-  assertEquals(plan.open_task_id, null);
-});
-
-// Red/green coverage for the implementation-phase escalation lifecycle (issue #25).
-//
-// `refreshOpenTaskEscalation` and `answerTaskEscalation` (issue #25) drive new stateful
-// behaviour — denormalising the plan's "surfaced" escalation, mirroring the answer onto the
-// task row, and publishing the correlated resume message — that had no unit coverage. These
-// drive both against the in-memory data layer above and assert the oldest-first surfacing,
-// the answer mirroring, and the published message.
-import {
-  answerPlanEscalation,
-  answerTaskEscalation,
-  currentPlanReviewEpoch,
-  PLAN_ESCALATION_MESSAGE,
-  refreshOpenTaskEscalation,
-} from "./plan.ts";
-
-function escalationStores(rows: unknown[]): Record<string, { rows: unknown[]; key: string }> {
-  return {
-    plans: { rows: [{ plan_key: "owner/repo#9" }], key: "plan_key" },
-    plan_escalations: { rows, key: "id" },
-    plan_tasks: { rows: [], key: "id" },
-  };
-}
-
 function memData(stores: Record<string, { rows: any[]; key: string }>) {
   return {
     table: (name: string, key: string) =>
@@ -222,212 +134,6 @@ function memData(stores: Record<string, { rows: any[]; key: string }>) {
   } as any;
 }
 
-test("refreshOpenTaskEscalation surfaces the OLDEST open escalation, then clears when none remain", async () => {
-  const stores = escalationStores([
-    { id: 2, plan_key: "owner/repo#9", task_id: "b", corr_key: "owner/repo#9:b", question: "Q-b", status: "open" },
-    { id: 1, plan_key: "owner/repo#9", task_id: "a", corr_key: "owner/repo#9:a", question: "Q-a", status: "open" },
-  ]);
-  const data = memData(stores);
-
-  await refreshOpenTaskEscalation(data, "owner/repo#9");
-  let plan = stores.plans.rows[0] as any;
-  assertEquals(plan.open_task_escalation_id, 1);
-  assertEquals(plan.open_task_question, "Q-a");
-  assertEquals(plan.open_task_corr_key, "owner/repo#9:a");
-  assertEquals(plan.open_task_id, "a");
-
-  // Once the oldest is answered, the next-oldest is surfaced.
-  (stores.plan_escalations.rows.find((r: any) => r.id === 1) as any).status = "answered";
-  await refreshOpenTaskEscalation(data, "owner/repo#9");
-  plan = stores.plans.rows[0] as any;
-  assertEquals(plan.open_task_escalation_id, 2);
-  assertEquals(plan.open_task_id, "b");
-
-  // With nothing open the denormalised fields clear.
-  (stores.plan_escalations.rows.find((r: any) => r.id === 2) as any).status = "answered";
-  await refreshOpenTaskEscalation(data, "owner/repo#9");
-  plan = stores.plans.rows[0] as any;
-  assertEquals(plan.open_task_escalation_id, null);
-  assertEquals(plan.open_task_question, null);
-  assertEquals(plan.open_task_corr_key, null);
-  assertEquals(plan.open_task_id, null);
-});
-
-test("answerTaskEscalation records the answer, mirrors it onto the task, publishes the resume message, and re-surfaces the next escalation", async () => {
-  const stores = escalationStores([
-    { id: 1, plan_key: "owner/repo#9", task_id: "a", corr_key: "owner/repo#9:a", question: "Q-a", status: "open", answer: null },
-    { id: 2, plan_key: "owner/repo#9", task_id: "b", corr_key: "owner/repo#9:b", question: "Q-b", status: "open", answer: null },
-  ]);
-  stores.plan_tasks.rows.push({ id: 10, plan_key: "owner/repo#9", task_id: "a", answer: null });
-  const data = memData(stores);
-
-  const published: any[] = [];
-  const engine = {
-    publishMessage: (m: any) => {
-      published.push(m);
-      return Promise.resolve();
-    },
-  } as any;
-
-  const r = await answerTaskEscalation(data, engine, "owner/repo#9:a", "do it");
-  assertEquals(r.ok, true);
-  assertEquals(r.escalationId, 1);
-  assertEquals(r.planKey, "owner/repo#9");
-  assertEquals(r.taskId, "a");
-
-  // Escalation row marked answered with the recorded answer.
-  const esc = stores.plan_escalations.rows.find((x: any) => x.id === 1) as any;
-  assertEquals(esc.status, "answered");
-  assertEquals(esc.answer, "do it");
-
-  // Answer mirrored onto the task row.
-  assertEquals((stores.plan_tasks.rows[0] as any).answer, "do it");
-
-  // Correlated resume message published on the shared constant channel.
-  assertEquals(published.length, 1);
-  assertEquals(published[0].name, "feature-escalation-answered");
-  assertEquals(published[0].correlationKey, "owner/repo#9:a");
-  assertEquals(published[0].variables.answer, "do it");
-
-  // Next-oldest open escalation re-surfaced on the plan row.
-  assertEquals((stores.plans.rows[0] as any).open_task_escalation_id, 2);
-});
-
-test("answerTaskEscalation is a no-op when no open escalation matches the correlation key", async () => {
-  const stores = escalationStores([]);
-  const data = memData(stores);
-  const engine = {
-    publishMessage: () => Promise.reject(new Error("should not publish")),
-  } as any;
-  const r = await answerTaskEscalation(data, engine, "owner/repo#9:missing", "x");
-  assertEquals(r.ok, false);
-});
-
-// Red/green regression (PR #131 suppressed advisory, app/plan.ts:455).
-//
-// Clearing a trial-merge wave's "Needs attention" row (`resolveTrialMergeAttention`)
-// is a best-effort cosmetic cleanup, but it must be RETRIABLE: if it ran only AFTER
-// the escalation was committed as `answered` and the resume message was published,
-// a transient DB error there would 500 the whole answer flow while the escalation is
-// already answered/resumed — a retry then 404s (no open escalation) and the red row
-// is pinned forever (the very failure the insert-first ordering elsewhere avoids).
-// The fix runs the idempotent resolution BEFORE the commit/publish, so a failure
-// leaves the escalation OPEN and nothing is orphaned — the caller can safely retry.
-test("answerTaskEscalation stays retriable (escalation open, no orphaned resume) when clearing 'Needs attention' fails", async () => {
-  const stores = escalationStores([
-    {
-      id: 1,
-      plan_key: "owner/repo#9",
-      task_id: "trial-merge-wave-0",
-      corr_key: "owner/repo#9:trial-merge-wave-0",
-      question: "Q",
-      status: "open",
-      answer: null,
-    },
-  ]);
-  stores.plan_trial_merges = {
-    rows: [{ id: 100, plan_key: "owner/repo#9", wave: 0, resolved: 0 }],
-    key: "id",
-  };
-  const base = memData(stores);
-  // Inject a transient failure in the trial-merge audit table's `update` only.
-  const data = {
-    table: (name: string, key: string) => {
-      const t = base.table(name, key);
-      if (name === "plan_trial_merges") {
-        return { ...t, update: () => Promise.reject(new Error("transient DB error")) };
-      }
-      return t;
-    },
-  } as any;
-
-  const published: any[] = [];
-  const engine = {
-    publishMessage: (m: any) => {
-      published.push(m);
-      return Promise.resolve();
-    },
-  } as any;
-
-  await assertRejects(() =>
-    answerTaskEscalation(data, engine, "owner/repo#9:trial-merge-wave-0", "proceed")
-  );
-
-  // Escalation must remain OPEN so a retry can recover (never committed as answered).
-  const esc = stores.plan_escalations.rows.find((x: any) => x.id === 1) as any;
-  assertEquals(esc.status, "open");
-  assertEquals(esc.answer, null);
-  // No orphaned resume message was published.
-  assertEquals(published.length, 0);
-});
-
-test("currentPlanReviewEpoch counts answered plan-review escalations only", async () => {
-  const stores = {
-    plan_review_escalations: {
-      rows: [
-        { id: 1, plan_key: "owner/repo#10", status: "answered" },
-        { id: 2, plan_key: "owner/repo#10", status: "open" },
-        { id: 3, plan_key: "owner/repo#other", status: "answered" },
-      ],
-      key: "id",
-    },
-  };
-  assertEquals(await currentPlanReviewEpoch(memData(stores), "owner/repo#10"), 1);
-});
-
-test("answerPlanEscalation records directive, clears the plan pointer, and publishes the resume message", async () => {
-  const stores = {
-    plans: {
-      rows: [{
-        plan_key: "owner/repo#11",
-        open_plan_escalation_id: 7,
-        open_plan_findings: "reviewer findings",
-        open_plan_round: 2,
-      }],
-      key: "plan_key",
-    },
-    plan_review_escalations: {
-      rows: [{
-        id: 7,
-        plan_key: "owner/repo#11",
-        epoch: 0,
-        round: 2,
-        findings: "reviewer findings",
-        status: "open",
-        directive: null,
-        note: null,
-      }],
-      key: "id",
-    },
-  };
-  const published: any[] = [];
-  const engine = {
-    publishMessage: (m: any) => {
-      published.push(m);
-      return Promise.resolve();
-    },
-  } as any;
-
-  const r = await answerPlanEscalation(memData(stores), engine, "owner/repo#11", "revise", "Use issue-1 as seam.");
-  assertEquals(r.ok, true);
-  assertEquals(r.directive, "revise");
-  const esc = stores.plan_review_escalations.rows[0] as any;
-  assertEquals(esc.status, "answered");
-  assertEquals(esc.directive, "revise");
-  assertEquals(esc.note, "Use issue-1 as seam.");
-  const plan = stores.plans.rows[0] as any;
-  assertEquals(plan.open_plan_escalation_id, null);
-  assertEquals(plan.open_plan_findings, null);
-  assertEquals(plan.open_plan_round, null);
-  assertEquals(published[0].name, PLAN_ESCALATION_MESSAGE);
-  assertEquals(published[0].correlationKey, "owner/repo#11");
-  assertEquals(published[0].variables.planEscalationDirective, "revise");
-  assertEquals(
-    String(published[0].variables.planFindings).includes("Use issue-1 as seam."),
-    true,
-  );
-});
-
 // Coverage for the epic base-branch control (issue nano-ide #124 / 019_plan_base_branch.sql; ADR 0003).
 //
 // Every plan must pin a base branch so the fleet branches off — and opens every PR against — a

package/app/plan.ts

@@ -11,14 +11,23 @@
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { DEFAULT_ESCALATION_SLA_TIMEOUT, escalationSlaTimeout } from "./escalationSla.ts";
 import { ensureBaseBranch, fetchDefaultBranch } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
-import { resolveTrialMergeAttention, trialMergeWaveFromTaskId } from "./trialMerge.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
 export const PLAN_PROCESS_ID = "plan-fanout";
 
+/** The fleet-wide escalation SLA (ISO-8601 duration) seeded onto every plan-fanout instance as the
+ * `escalationSlaTimeout` process variable and evaluated by each escalation user task's interrupting
+ * timer boundary. An operator sets `NANO_ESCALATION_SLA_TIMEOUT`; a malformed value falls back to
+ * {@link DEFAULT_ESCALATION_SLA_TIMEOUT} so a bad env can never deploy an uninterpretable timer. */
+export const ESCALATION_SLA_TIMEOUT = escalationSlaTimeout(
+  process.env.NANO_ESCALATION_SLA_TIMEOUT,
+  DEFAULT_ESCALATION_SLA_TIMEOUT,
+);
+
 const now = () => new Date().toISOString();
 
 // Agent prompts are no longer read by the host. The `senior:plan`, `senior:plan-review`, and
@@ -38,21 +47,6 @@ export interface Plan {
   task_count: number;
   process_key: string | null;
   outcome: string | null;
-  // Denormalised "oldest open task escalation" pointer (issue #25): the plans page
-  // detail has a single answer form per row, so the oldest still-open per-task
-  // escalation is surfaced here; answering re-points these at the next one (or
-  // clears them). See refreshOpenTaskEscalation.
-  open_task_escalation_id: number | null;
-  open_task_question: string | null;
-  open_task_corr_key: string | null;
-  open_task_id: string | null;
-  // Denormalised "open plan-review escalation" pointer (# plan-review escalation): when the
-  // adversarial plan-review cap is reached without approval, the process parks for a human
-  // proceed/revise directive. These fields surface the newest open plan-level escalation on the
-  // plans page without overloading the implementation-phase `plan_escalations` table.
-  open_plan_escalation_id: number | null;
-  open_plan_findings: string | null;
-  open_plan_round: number | null;
   // Wave-merge barrier (007_wave_gate.sql): the wave index whose PRs the plan is currently
   // waiting to see MERGED before dispatching the next wave, or null when not parked at the barrier.
   gate_wave: number | null;
@@ -114,36 +108,8 @@ export const PLAN_TASK_STATUSES = [
 ] as const;
 export type PlanTaskStatus = typeof PLAN_TASK_STATUSES[number];
 
-/** One implementation-phase escalation (issue #25) — the per-task analogue of the
- * review loop's `escalations` row. `status` is open | answered. */
-export interface PlanEscalation {
-  id: number;
-  plan_key: string;
-  task_id: string;
-  corr_key: string;
-  question: string;
-  answer: string | null;
-  draft_pr_key: string | null;
-  status: string;
-  asked_at: string;
-  answered_at: string | null;
-}
-
 export const plans = (data: DataLayer) => data.table<Plan>("plans", "plan_key");
 export const planTasks = (data: DataLayer) => data.table<PlanTask>("plan_tasks", "id");
-export const planEscalations = (data: DataLayer) =>
-  data.table<PlanEscalation>("plan_escalations", "id");
-
-/** The message the plan-fanout process catches to resume an escalated task; its
- * subscription correlates on `<plan_key>:<task_id>` (see plan-fanout.bpmn). */
-export const FEATURE_ESCALATION_MESSAGE = "feature-escalation-answered";
-
-/** The message the plan-fanout process catches to resume a plan-review escalation; its
- * subscription correlates on `<plan_key>` (see plan-fanout.bpmn). */
-export const PLAN_ESCALATION_MESSAGE = "plan-escalation-answered";
-
-/** Build the per-task message correlation key the process parks on. */
-export const featureCorrKey = (planKey: string, taskId: string) => `${planKey}:${taskId}`;
 
 /** One dependency edge in the plan DAG (issue #20): `task_id` waits for `depends_on_task_id`.
  * Keyed on `plan_key` so a single delete clears a plan's whole edge set (as pr_dependencies). */
@@ -172,31 +138,6 @@ export interface PlanReview {
 }
 export const planReviews = (data: DataLayer) => data.table<PlanReview>("plan_reviews", "plan_key");
 
-export type PlanEscalationDirective = "proceed" | "revise";
-
-export function parsePlanEscalationDirective(input: unknown): PlanEscalationDirective | null {
-  const s = typeof input === "string" ? input.trim().toLowerCase() : "";
-  return s === "proceed" || s === "revise" ? s : null;
-}
-
-/** One plan-review cap escalation. Kept in a dedicated table rather than overloading
- * `plan_escalations`: the latter is task-scoped (`task_id`/`corr_key` are NOT NULL and mirrored
- * onto `plan_tasks`), while this row is plan-scoped and drives the review epoch reset. */
-export interface PlanReviewEscalation {
-  id: number;
-  plan_key: string;
-  epoch: number;
-  round: number;
-  findings: string | null;
-  status: string;
-  directive: PlanEscalationDirective | null;
-  note: string | null;
-  asked_at: string;
-  answered_at: string | null;
-}
-export const planReviewEscalations = (data: DataLayer) =>
-  data.table<PlanReviewEscalation>("plan_review_escalations", "id");
-
 /** Read a positive-integer env override, falling back when unset/blank/invalid. A bad value
  * (e.g. "", "abc", "0", "2.5") must NOT silently become `NaN`/`0` — that would make the round
  * cap `round + 1 >= cap` always false and allow an unbounded revise loop. */
@@ -212,11 +153,9 @@ export function positiveIntEnv(name: string, fallback: number): number {
  * #86). A human `revise` answer starts a fresh epoch, so the next plan gets a full new budget. */
 export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS", 3);
 
-/** The current review epoch is derived from the append-only escalation log: every answered
- * plan-review escalation represents a human decision to leave the prior budget behind. */
-export async function currentPlanReviewEpoch(data: DataLayer, planKey: string): Promise<number> {
-  return await planReviewEscalations(data).count({ plan_key: planKey, status: "answered" });
-}
+/** The current review epoch is a durable process variable (`planReviewEpoch`) bumped by the
+ * `plan-review-decision` user task each time a human answers a plan-review escalation. It is read
+ * back by `record-plan-review` to reset the round budget — there is no derived counter here. */
 
 /** A plan is "done" in exactly these states; everything else (planning, dispatched)
  * is in flight. The cancel guard and the active view key off this. */
@@ -467,18 +406,6 @@ export async function startPlan(
     // Clear them here — the table is keyed on `plan_key`, so one delete drops the
     // whole set (mirrors how record-plan clears `plan_task_deps`).
     await planReviews(data).delete(parsed.planKey);
-    // Same class of stale-row bug for escalation state: task escalations are keyed on `id` (not
-    // `plan_key`), so drop the prior run's rows one-by-one. Otherwise a still-"open" escalation
-    // from the previous run survives the re-plan and `refreshOpenTaskEscalation` re-surfaces a
-    // question for a `task_id` we just deleted from `plan_tasks`.
-    for (const e of await planEscalations(data).find({ plan_key: parsed.planKey })) {
-      await planEscalations(data).delete(e.id);
-    }
-    // Plan-review escalations are also keyed on `id` because they are an audit trail; clear them
-    // on a fresh submission so the epoch derived from answered escalations resets to 0.
-    for (const e of await planReviewEscalations(data).find({ plan_key: parsed.planKey })) {
-      await planReviewEscalations(data).delete(e.id);
-    }
     // Same for the structured impl-change deltas (D5, #55): keyed on `id`, so drop the prior run's
     // rows one-by-one, otherwise a stale delta lingers in the epic report for a task we just deleted.
     await clearTaskDeltas(data, parsed.planKey);
@@ -489,15 +416,6 @@ export async function startPlan(
       task_count: 0,
       issue_url: parsed.url,
       outcome: null,
-      // Reset the denormalised "surfaced escalation" pointer so nothing from the
-      // prior run lingers on the plan row (would otherwise show a dead answer form).
-      open_task_escalation_id: null,
-      open_task_question: null,
-      open_task_corr_key: null,
-      open_task_id: null,
-      open_plan_escalation_id: null,
-      open_plan_findings: null,
-      open_plan_round: null,
       blackboard_token: token,
       base_branch: base,
       updated_at: ts,
@@ -525,6 +443,19 @@ export async function startPlan(
       issueNumber: parsed.number,
       issueUrl: parsed.url,
       planFindings: null,
+      // The plan-review epoch is a durable process variable, bumped by the `plan-review-decision`
+      // user task each time a human answers a plan-review escalation. `record-plan-review` reads it
+      // to reset the per-epoch round budget; it starts at 0 for the first review round.
+      planReviewEpoch: 0,
+      // Escalation-of-the-escalation SLA (U5, #156): the validated ISO-8601 duration seeded onto the
+      // instance and read by each escalation user task's interrupting timer boundary
+      // (`<bpmn:timeDuration>=escalationSlaTimeout`). If a human never answers, the boundary fires and
+      // the process auto-proceeds down the gateway's safe-default arm — durable in-process liveness,
+      // not a poller-side watchdog. `escalationAssignee` is the optional named assignee the escalation
+      // user tasks' `zeebe:assignmentDefinition` resolves (null = unassigned, routed via the
+      // `operators` candidate group); an operator/agent can claim/reassign via the task inbox.
+      escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
+      escalationAssignee: null,
       // Coordination blackboard (#51): the capability URL + the protocol brief that each
       // implementer agent gets appended to its prompt (composed into `appendPrompt` in
       // plan-fanout.bpmn's implement-task). Advisory shared state, delivered in-band, used
@@ -546,124 +477,3 @@ export async function startPlan(
   return { planKey: parsed.planKey, processKey };
 }
 
-/** Re-point a plan's denormalised "open task escalation" fields at its OLDEST
- * still-open `plan_escalations` row (or clear them when none remain). The page
- * runtime binds a single answer form per plan row, so parallel escalations are
- * surfaced one at a time, oldest-first; this is called after opening an
- * escalation and after answering one. */
-export async function refreshOpenTaskEscalation(data: DataLayer, planKey: string) {
-  const open = (await planEscalations(data).find({ plan_key: planKey, status: "open" }))
-    .sort((a, b) => a.id - b.id)[0];
-  await plans(data).update(planKey, {
-    open_task_escalation_id: open ? open.id : null,
-    open_task_question: open ? open.question : null,
-    open_task_corr_key: open ? open.corr_key : null,
-    open_task_id: open ? open.task_id : null,
-    updated_at: now(),
-  });
-}
-
-/** Answer an open implementation-phase escalation → record it, resume the parked
- * task via the correlated `feature-escalation-answered` message, and re-surface
- * the next-oldest open escalation (if any). Keyed by the correlation key
- * (`<plan_key>:<task_id>`) so an external webhook and the page share one path.
- * Idempotent-ish: a corr_key with no open escalation is a 404-style no-op. */
-export async function answerTaskEscalation(
-  data: DataLayer,
-  engine: EngineClient,
-  corrKey: string,
-  answer: string,
-) {
-  const open = (await planEscalations(data).find({ corr_key: corrKey, status: "open" }))
-    .sort((a, b) => b.id - a.id)[0];
-  if (!open) return { ok: false, reason: "no open escalation" };
-  const ts = now();
-  // A trial-merge escalation (task_id `trial-merge-wave-<wave>`) leaves an
-  // append-only red audit row in `plan_trial_merges`. Answering it clears that
-  // row from the page's "Needs attention" tab — including a "proceed" override
-  // that records no re-run row (a re-run would supersede it, but a proceed would
-  // not, pinning the red row forever).
-  //
-  // Resolve it FIRST, before the escalation is committed as answered and the
-  // resume message is published. `resolveTrialMergeAttention` is idempotent, so
-  // if this throws (e.g. a transient DB error) the escalation is still open and
-  // the whole operation retries cleanly. Running it AFTER the commit/publish
-  // would make a failure here unrecoverable: the escalation is already answered,
-  // a retry 404s (no open escalation), and the red row is pinned forever.
-  const trialWave = trialMergeWaveFromTaskId(open.task_id);
-  if (trialWave != null) await resolveTrialMergeAttention(data, open.plan_key, trialWave);
-  await planEscalations(data).update(open.id, { answer, status: "answered", answered_at: ts });
-  // Mirror onto the task row so a re-dispatched agent (and the UI) sees the answer.
-  for (const t of await planTasks(data).find({ plan_key: open.plan_key, task_id: open.task_id })) {
-    await planTasks(data).update(t.id, { answer, updated_at: ts });
-  }
-  // Resume the parked child: the process merges `answer` into the child scope and
-  // loops back to re-dispatch the SAME task on its existing branch.
-  await engine.publishMessage({
-    name: FEATURE_ESCALATION_MESSAGE,
-    correlationKey: corrKey,
-    variables: { answer },
-  });
-  await refreshOpenTaskEscalation(data, open.plan_key);
-  return { ok: true, escalationId: open.id, planKey: open.plan_key, taskId: open.task_id };
-}
-
-export function normalizePlanEscalationDirective(input: unknown): PlanEscalationDirective {
-  return parsePlanEscalationDirective(input) ?? "revise";
-}
-
-function renderPlanEscalationFindings(open: PlanReviewEscalation, note: string): string {
-  const parts = [
-    `Plan review reached its round budget at epoch ${open.epoch}, round ${open.round}.`,
-    "",
-    "Reviewer findings:",
-    (open.findings ?? "").trim() || "(no reviewer findings were provided.)",
-  ];
-  if (note) {
-    parts.push("", "Human guidance:", note);
-  } else {
-    parts.push("", "Human directive: revise the plan within the allowed task boundaries.");
-  }
-  return parts.join("\n");
-}
-
-/** Answer the newest open plan-review escalation. `proceed` is an explicit human override that lets
-  * the current (unapproved) plan continue to wave dispatch; `revise` (the default) folds the human
-  * note into `planFindings` and starts a fresh review epoch on the next planner pass. */
-export async function answerPlanEscalation(
-  data: DataLayer,
-  engine: EngineClient,
-  planKey: string,
-  directiveInput: unknown,
-  noteInput: unknown,
-) {
-  const open = (await planReviewEscalations(data).find({ plan_key: planKey, status: "open" }))
-    .sort((a, b) => b.id - a.id)[0];
-  if (!open) return { ok: false, reason: "no open plan escalation" };
-
-  const directive = normalizePlanEscalationDirective(directiveInput);
-  const note = typeof noteInput === "string" ? noteInput.trim() : "";
-  const ts = now();
-  await planReviewEscalations(data).update(open.id, {
-    directive,
-    note: note || null,
-    status: "answered",
-    answered_at: ts,
-  });
-  await plans(data).update(planKey, {
-    open_plan_escalation_id: null,
-    open_plan_findings: null,
-    open_plan_round: null,
-    updated_at: ts,
-  });
-
-  await engine.publishMessage({
-    name: PLAN_ESCALATION_MESSAGE,
-    correlationKey: planKey,
-    variables: {
-      planEscalationDirective: directive,
-      planFindings: directive === "revise" ? renderPlanEscalationFindings(open, note) : "",
-    },
-  });
-  return { ok: true, escalationId: open.id, planKey, directive };
-}

package/app/reviewWait.ts

@@ -20,15 +20,23 @@ export const DEFAULT_REVIEW_WAIT_TIMEOUT = "PT20M";
 // would fail to interpret; not a full grammar (we don't need fractional seconds here).
 const ISO_DURATION = /^P(?!$)(\d+Y)?(\d+M)?(\d+W)?(\d+D)?(T(?=\d)(\d+H)?(\d+M)?(\d+S)?)?$/;
 
+/** Validate an ISO-8601 duration string for a BPMN timer's `<bpmn:timeDuration>`, falling back to
+ * `def` when the value is absent, blank, or malformed — a bad env value must never deploy an
+ * uninterpretable timer expression into a process. Normalises to upper case (`pt20m` → `PT20M`).
+ * This is the single canonical duration validator; per-timer policies (review-wait, escalation
+ * SLA) derive their env-driven value from it rather than re-implementing the grammar. */
+export function isoDuration(raw: string | undefined, def: string): string {
+  const s = (raw ?? "").trim().toUpperCase();
+  return s !== "" && ISO_DURATION.test(s) ? s : def;
+}
+
 /** Validate an ISO-8601 duration for the review-wait timer, falling back to `def` when the value
- * is absent, blank, or malformed — a bad env value must never deploy an uninterpretable timer
- * expression into the process. Normalises to upper case (`pt20m` → `PT20M`). */
+ * is absent, blank, or malformed. Thin wrapper over {@link isoDuration}. */
 export function reviewWaitTimeout(
   raw: string | undefined,
   def: string = DEFAULT_REVIEW_WAIT_TIMEOUT,
 ): string {
-  const s = (raw ?? "").trim().toUpperCase();
-  return s !== "" && ISO_DURATION.test(s) ? s : def;
+  return isoDuration(raw, def);
 }
 
 /** Default cooldown (minutes) between automatic Copilot re-request nudges for one waiting PR.