@nanobpm/nano-workforce 0.45.0 → 0.46.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [0.46.0](https://github.com/nanobpm/nano-workforce/compare/v0.45.0...v0.46.0) (2026-08-12)
+
+
+### Features
+
+* add plan review escalation ([#128](https://github.com/nanobpm/nano-workforce/issues/128)) ([b67cc9e](https://github.com/nanobpm/nano-workforce/commit/b67cc9ebd84ef251e38e1e0fc332f712f82438c2)), closes [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 # [0.45.0](https://github.com/nanobpm/nano-workforce/compare/v0.44.1...v0.45.0) (2026-08-12)
 
 

package/SPEC.md

@@ -511,6 +511,44 @@ the loop runs one parallel `implement` MI fan-out per wave:
   directive in a sub-issue body, mapping each prerequisite `#M` to `issue-M` in the
   adopted task's `dependsOn` — so a human-declared blocking order survives adoption.
 
+### 13.2 Trial-merge integration gate (D3) — issue #69
+
+Before a wave's still-open heads land, the fan-out runs a **D3 trial merge** to catch
+**emergent** conflicts: heads that merge cleanly but whose *combination* breaks the
+target repo's suite. `app/trialMerge.ts` classifies the result `clean | merge-conflict
+| suite-failed`; only `suite-failed` escalates (`trialMergeDecision`). Textual
+merge-conflicts are pass-through — D2/D6 own merge-exclusion and merge-train ordering.
+It runs only for `headCount >= 2` on non-mergify repos (`shouldRunTrialMerge`).
+
+Flow (`resources/processes/plan-fanout.bpmn`): `gw-trial-needed` → `trial-merge`
+(`senior:trial-merge`) → `record-trial-merge` (audit row in `plan_trial_merges`) →
+`gw-trial` (`trial red?`). On red it persists a plan-level escalation
+(`pr.persist-task-escalation`, task id `trial-merge-wave-<N>`, corrKey
+`<plan_key>:trial-merge-wave-<N>`) and parks at `wait-trial-answer`
+(`feature-escalation-answered`). The operator answers exactly `proceed` to override and
+continue, or anything else to **rerun** the trial after pushing a fix.
+
+**Known gap — inherited vs emergent failures (issue #129, PLANNED).** As shipped, D3
+escalates on *any* red combined suite, including a failure that was **already red on
+each head individually** (e.g. a per-PR build defect, or a repo-wide workspace
+build-ordering bug). That parks a human on something that is not an integration
+decision. The target behaviour is an **autonomy ladder**:
+
+1. **Shift-left** — a head whose *required* checks are red never enters the trial merge;
+  the convergence loop's `senior:fix-ci` path owns per-PR failures. D3 only sees
+  individually-green heads.
+2. **Baseline-diff** — the `senior:trial-merge` agent reports, per failing check,
+  whether it was green on each head alone; D3 escalates **only** on checks that
+  *regress under combination* (green-per-head → red-combined) and attributes inherited
+  failures back to the owning head's loop.
+3. **Auto-remediation** — for deterministic, agent-diagnosable classes (build ordering,
+  lockfile drift, renamed scripts) a `senior:integration-fix` agent pushes the fix and
+  reruns the trial before any human is parked (reusing the escalate→wait→rerun/proceed
+  branch from the plan-review escalation, PR #128).
+
+A human escalation is then reserved for its one true case: **two slices that each pass
+but encode incompatible decisions about a shared contract** — a genuine design call.
+
 ## 14. Open questions / future
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git
@@ -524,6 +562,8 @@ the loop runs one parallel `implement` MI fan-out per wave:
 - **Supervised vs external worker** — the agent runs as an external
   `c8ctl nano work` daemon by default; a supervised in-server mode is possible
   later (ADR 0041 decision).
+- **Autonomous D3** — shift-left + baseline-diff + auto-remediation so the trial-merge
+  gate only escalates genuine cross-slice design conflicts (§13.2, issue #129).
 - **Prompt versioning/hash** per PR for auditability.
 - **Auth on the web UI** — the manifest `security` block (ADR 0028) if this is
   exposed beyond localhost.

package/app/plan.test.ts

@@ -70,6 +70,10 @@ function memTable(rows: any[], key: string) {
       rows.push(r);
       return Promise.resolve(r);
     },
+    count: (q: any) =>
+      Promise.resolve(
+        rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length,
+      ),
     update: (k: any, patch: any) => {
       const r = rows.find((x) => x[key] === k);
       if (r) Object.assign(r, patch);
@@ -97,8 +101,8 @@ test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
     },
     plan_reviews: {
       rows: [
-        { plan_key: PLAN_KEY, round: 0 },
-        { plan_key: PLAN_KEY, round: 1 },
+        { plan_key: PLAN_KEY, epoch: 0, round: 0 },
+        { plan_key: PLAN_KEY, epoch: 0, round: 1 },
       ],
       key: "plan_key",
     },
@@ -195,7 +199,13 @@ test("re-plan of a finished issue clears stale open escalations and the denormal
 // 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 { answerTaskEscalation, refreshOpenTaskEscalation } from "./plan.ts";
+import {
+  answerPlanEscalation,
+  answerTaskEscalation,
+  currentPlanReviewEpoch,
+  PLAN_ESCALATION_MESSAGE,
+  refreshOpenTaskEscalation,
+} from "./plan.ts";
 
 function escalationStores(rows: unknown[]): Record<string, { rows: unknown[]; key: string }> {
   return {
@@ -293,6 +303,73 @@ test("answerTaskEscalation is a no-op when no open escalation matches the correl
   assertEquals(r.ok, false);
 });
 
+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).
 //
 // A plan may pin a base branch so the fleet branches off — and opens every PR against — a long-lived

package/app/plan.ts

@@ -44,6 +44,13 @@ export interface Plan {
   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;
@@ -115,6 +122,10 @@ export const planEscalations = (data: DataLayer) =>
  * 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}`;
 
@@ -136,6 +147,7 @@ export const planTaskDeps = (data: DataLayer) =>
  * (crash/timeout after the insert) reuses its row instead of appending a duplicate round. */
 export interface PlanReview {
   plan_key: string;
+  epoch: number;
   round: number;
   approved: number;
   findings: string | null;
@@ -144,6 +156,31 @@ 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. */
@@ -154,11 +191,17 @@ export function positiveIntEnv(name: string, fallback: number): number {
   return Number.isInteger(n) && n > 0 ? n : fallback;
 }
 
-/** Max adversarial plan-review rounds. Reaching the cap WITHOUT approval is a hard failure: the
- * fan-out raises a `PLAN_REJECTED` incident rather than dispatching an un-approved plan (issue
- * #86). The last round's findings are still recorded. */
+/** Max adversarial plan-review rounds per epoch. Reaching the cap WITHOUT approval parks the
+ * fan-out on a human plan-review escalation rather than dispatching an un-approved plan (issue
+ * #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" });
+}
+
 /** 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. */
 export const PLAN_TERMINAL_STATUSES: readonly string[] = ["done", "failed", "abandoned"];
@@ -279,14 +322,18 @@ 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 the implementation-phase escalation state
-    // (issue #25): `plan_escalations` is 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`.
+    // 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);
@@ -303,6 +350,9 @@ export async function startPlan(
       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,
@@ -398,3 +448,63 @@ export async function answerTaskEscalation(
   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/db/migrations/020_plan_review_escalation.sql

@@ -0,0 +1,51 @@
+-- Plan-review cap escalation. When the adversarial review loop exhausts its per-epoch budget
+-- without approval, the plan-fanout process parks for a human directive instead of raising an
+-- unhandled PLAN_REJECTED incident. A `revise` answer starts a new review epoch; a `proceed`
+-- answer explicitly dispatches the current plan as-is.
+--
+-- `plan_reviews.round` remains derived from the append-only review log, but now within the current
+-- epoch. SQLite cannot alter the existing PRIMARY KEY (plan_key, round), so recreate the table with
+-- (plan_key, epoch, round) and backfill existing rows into epoch 0.
+
+ALTER TABLE plan_reviews ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0;
+
+CREATE TABLE plan_reviews_new (
+  plan_key    TEXT NOT NULL REFERENCES plans(plan_key),
+  epoch       INTEGER NOT NULL DEFAULT 0,
+  round       INTEGER NOT NULL,
+  approved    INTEGER NOT NULL,
+  findings    TEXT,
+  created_at  TEXT NOT NULL,
+  job_key     TEXT,
+  PRIMARY KEY (plan_key, epoch, round)
+);
+
+INSERT INTO plan_reviews_new (plan_key, epoch, round, approved, findings, created_at, job_key)
+SELECT plan_key, epoch, round, approved, findings, created_at, job_key
+FROM plan_reviews;
+
+DROP TABLE plan_reviews;
+ALTER TABLE plan_reviews_new RENAME TO plan_reviews;
+
+CREATE INDEX idx_plan_reviews_plan ON plan_reviews(plan_key);
+CREATE UNIQUE INDEX idx_plan_reviews_job ON plan_reviews(plan_key, job_key);
+
+CREATE TABLE plan_review_escalations (
+  id           INTEGER PRIMARY KEY AUTOINCREMENT,
+  plan_key     TEXT NOT NULL REFERENCES plans(plan_key),
+  epoch        INTEGER NOT NULL,
+  round        INTEGER NOT NULL,
+  findings     TEXT,
+  status       TEXT NOT NULL,              -- open | answered
+  directive    TEXT,                       -- proceed | revise (answered rows only)
+  note         TEXT,
+  asked_at     TEXT NOT NULL,
+  answered_at  TEXT
+);
+
+CREATE INDEX idx_plan_review_escalations_plan ON plan_review_escalations(plan_key);
+CREATE INDEX idx_plan_review_escalations_open ON plan_review_escalations(plan_key, status);
+
+ALTER TABLE plans ADD COLUMN open_plan_escalation_id INTEGER;
+ALTER TABLE plans ADD COLUMN open_plan_findings TEXT;
+ALTER TABLE plans ADD COLUMN open_plan_round INTEGER;

package/nano.app.json

@@ -119,6 +119,10 @@
       "taskType": "pr.persist-task-escalation",
       "handler": "workers/persist-task-escalation/worker.ts"
     },
+    {
+      "taskType": "pr.persist-plan-escalation",
+      "handler": "workers/persist-plan-escalation/worker.ts"
+    },
     {
       "taskType": "pr.retro-gather",
       "handler": "workers/retro-gather/worker.ts"

package/openapi.yaml

@@ -345,6 +345,27 @@ components:
           type: string
           minLength: 1
           description: The operator's answer that resumes the parked implementation agent.
+    PlanAnswerRequest:
+      type: object
+      additionalProperties: false
+      required:
+        - plan
+        - directive
+      properties:
+        plan:
+          type: string
+          description: Plan reference (owner/repo#N), also the message correlation key.
+        directive:
+          type: string
+          description: >-
+            One of `proceed` or `revise` (case-insensitive; normalized to lowercase and trimmed
+            server-side, see `parsePlanEscalationDirective`).
+            `proceed` dispatches the current unapproved plan as an explicit human override;
+            `revise` loops back to the planner with the note folded into planFindings and a fresh
+            review budget.
+        note:
+          type: string
+          description: Human guidance for the planner (used for `revise`; optional for `proceed`).
     BlackboardEntry:
       type: object
       additionalProperties: false
@@ -578,9 +599,9 @@ paths:
   /actions/message:
     post:
       operationId: postMessage
-      summary: Publish a message / answer an escalation. For escalation-answered and
-        feature-escalation-answered names, runs the corresponding answer flow; otherwise a plain
-        publishMessage.
+      summary: Publish a message / answer an escalation. For escalation-answered,
+        feature-escalation-answered, and plan-escalation-answered names, runs the corresponding
+        answer flow; otherwise a plain publishMessage.
       requestBody:
         required: true
         content:
@@ -603,6 +624,13 @@ paths:
                   properties:
                     answer:
                       type: string
+                    directive:
+                      type: string
+                      description: >-
+                        One of `proceed` or `revise` (case-insensitive; normalized to lowercase and
+                        trimmed server-side, see `parsePlanEscalationDirective`).
+                    note:
+                      type: string
       responses:
         "200":
           description: The message was published (or the escalation answered).
@@ -661,6 +689,45 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /hooks/plan-answer:
+    post:
+      operationId: answerPlanEscalation
+      summary: "Answer a plan-review cap escalation out of band. Optional shared-secret guard
+        (x-hook-secret), enforced only when NANO_PR_WEBHOOK_SECRET is set."
+      security:
+        - hookSecret: []
+        - {}
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/PlanAnswerRequest"
+      responses:
+        "200":
+          description: The escalation was answered and the parked plan resumed.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field was missing (plan or directive).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No matching open plan escalation for the plan key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/blackboard:
     get:
       operationId: readBlackboard

package/operations/answerPlanEscalation.test.ts

@@ -0,0 +1,115 @@
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+
+const hadSecret = Object.prototype.hasOwnProperty.call(process.env, "NANO_PR_WEBHOOK_SECRET");
+const previousSecret = process.env.NANO_PR_WEBHOOK_SECRET;
+let answerPlanEscalation: typeof import("./answerPlanEscalation.ts").default;
+try {
+  process.env.NANO_PR_WEBHOOK_SECRET = " test-secret ";
+  answerPlanEscalation = (await import("./answerPlanEscalation.ts")).default;
+} finally {
+  if (hadSecret && previousSecret !== undefined) process.env.NANO_PR_WEBHOOK_SECRET = previousSecret;
+  else delete process.env.NANO_PR_WEBHOOK_SECRET;
+}
+
+function memTable(rows: any[], key: string) {
+  return {
+    find: (where: Record<string, unknown>) =>
+      Promise.resolve(rows.filter((row) => Object.entries(where).every(([field, value]) => row[field] === value))),
+    update: (value: unknown, patch: Record<string, unknown>) => {
+      const row = rows.find((candidate) => candidate[key] === value);
+      if (row) Object.assign(row, patch);
+      return Promise.resolve(row);
+    },
+  };
+}
+
+function memApp(escalations: any[] = []) {
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [{ plan_key: "owner/repo#9", open_plan_escalation_id: 1 }], key: "plan_key" },
+    plan_review_escalations: { rows: escalations, key: "id" },
+  };
+  const published: Record<string, unknown>[] = [];
+  const app = {
+    data: {
+      table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    },
+    engine: {
+      publishMessage: (message: Record<string, unknown>) => {
+        published.push(message);
+        return Promise.resolve();
+      },
+    },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, published, stores };
+}
+
+function input(body: Record<string, unknown>, secret?: string) {
+  const headers = new Headers();
+  if (secret !== undefined) headers.set("x-hook-secret", secret);
+  return {
+    req: {
+      method: "POST",
+      path: "/app/api/hooks/plan-answer",
+      query: new URLSearchParams(),
+      headers,
+      text: async () => "",
+    } as any,
+    params: {},
+    query: {},
+    body,
+  };
+}
+
+test("rejects a request without the configured hook secret", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(input({ plan: "owner/repo#9", directive: "revise" }), app) as any;
+  assertEquals(result.status, 401);
+  assertEquals(result.body, { ok: false, error: "unauthorized" });
+});
+
+test("answers an open plan escalation and publishes the plan correlation message", async () => {
+  const { app, published, stores } = memApp([{
+    id: 1,
+    plan_key: "owner/repo#9",
+    epoch: 0,
+    round: 2,
+    findings: "needs wave 0",
+    status: "open",
+  }]);
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#9", directive: "revise", note: " use issue-1 first " }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 200);
+  assertEquals(result.body.ok, true);
+  assertEquals(stores.plan_review_escalations.rows[0].status, "answered");
+  assertEquals(stores.plan_review_escalations.rows[0].directive, "revise");
+  assertEquals(stores.plan_review_escalations.rows[0].note, "use issue-1 first");
+  assertEquals(published[0]?.name, "plan-escalation-answered");
+  assertEquals(published[0]?.correlationKey, "owner/repo#9");
+  assertEquals((published[0]?.variables as Record<string, unknown>).planEscalationDirective, "revise");
+});
+
+test("maps an unmatched plan to 404", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#missing", directive: "revise" }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 404);
+  assertEquals(result.body.ok, false);
+});
+
+test("rejects an invalid directive with 400", async () => {
+  const { app } = memApp();
+  const result = await answerPlanEscalation(
+    input({ plan: "owner/repo#9", directive: "ship-it" }, "test-secret"),
+    app,
+  ) as any;
+  assertEquals(result.status, 400);
+  assertEquals(result.body.ok, false);
+});