@nanobpm/nano-workforce 0.26.0

package/app/plan.test.ts

@@ -0,0 +1,317 @@
+// Red/green regression for the plan-review round-cap parsing (PR #26 review).
+//
+// `MAX_PLAN_REVIEW_ROUNDS` bounds the adversarial revise loop. If the env override parsed to
+// `NaN`/`0` (e.g. unset, "", "abc"), the cap check `round + 1 >= cap` would never fire and the
+// planner could revise forever. `positiveIntEnv` must fall back to the default on any value that
+// is not a positive integer, so the loop is always bounded.
+import { assertEquals } from "jsr:@std/assert@1";
+import { positiveIntEnv } from "./plan.ts";
+
+const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
+
+function withEnv(value: string | undefined, run: () => void) {
+  const had = Object.prototype.hasOwnProperty.call(Deno.env.toObject(), KEY);
+  const prev = Deno.env.get(KEY);
+  try {
+    if (value === undefined) Deno.env.delete(KEY);
+    else Deno.env.set(KEY, value);
+    run();
+  } finally {
+    if (had && prev !== undefined) Deno.env.set(KEY, prev);
+    else Deno.env.delete(KEY);
+  }
+}
+
+Deno.test("unset → fallback (bounded loop, never NaN)", () => {
+  withEnv(undefined, () => assertEquals(positiveIntEnv(KEY, 3), 3));
+});
+
+Deno.test("blank/whitespace → fallback, not 0", () => {
+  withEnv("", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+  withEnv("   ", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+});
+
+Deno.test("non-numeric → fallback, not NaN", () => {
+  withEnv("abc", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+});
+
+Deno.test("zero and negatives → fallback (cap must be >= 1)", () => {
+  withEnv("0", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+  withEnv("-2", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+});
+
+Deno.test("non-integer → fallback", () => {
+  withEnv("2.5", () => assertEquals(positiveIntEnv(KEY, 3), 3));
+});
+
+Deno.test("valid positive integer → honoured", () => {
+  withEnv("5", () => assertEquals(positiveIntEnv(KEY, 3), 5));
+  withEnv("1", () => assertEquals(positiveIntEnv(KEY, 3), 1));
+});
+
+// Red/green regression for re-plan clearing `plan_reviews` (PR #26 review).
+//
+// `plan_reviews` is append-only and the review round is derived from `count(plan_reviews)`.
+// When `startPlan` re-plans a previously finished issue it must clear the prior review rows,
+// otherwise the stale count inflates the next round index and can trip `reviewExhausted` early,
+// bypassing the adversarial gate. This drives `startPlan` against an in-memory data layer and
+// asserts the `plan_reviews` rows for the plan key are gone after a re-plan.
+import { startPlan } from "./plan.ts";
+
+// deno-lint-ignore no-explicit-any
+function memTable(rows: any[], key: string) {
+  return {
+    // deno-lint-ignore no-explicit-any
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+    // deno-lint-ignore no-explicit-any
+    find: (q: any) =>
+      Promise.resolve(
+        rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)),
+      ),
+    // deno-lint-ignore no-explicit-any
+    insert: (r: any) => {
+      rows.push(r);
+      return Promise.resolve(r);
+    },
+    // deno-lint-ignore no-explicit-any
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r);
+    },
+    // deno-lint-ignore no-explicit-any
+    delete: (k: any) => {
+      for (let i = rows.length - 1; i >= 0; i--) {
+        if (rows[i][key] === k) rows.splice(i, 1);
+      }
+      return Promise.resolve();
+    },
+  };
+}
+
+Deno.test("re-plan of a finished issue clears stale plan_reviews rows", async () => {
+  const PLAN_KEY = "owner/repo#7";
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    plans: {
+      rows: [{ plan_key: PLAN_KEY, status: "done", task_count: 2 }],
+      key: "plan_key",
+    },
+    plan_tasks: {
+      rows: [{ id: 1, plan_key: PLAN_KEY }, { id: 2, plan_key: PLAN_KEY }],
+      key: "id",
+    },
+    plan_reviews: {
+      rows: [
+        { plan_key: PLAN_KEY, round: 0 },
+        { plan_key: PLAN_KEY, round: 1 },
+      ],
+      key: "plan_key",
+    },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const data = {
+    table: (name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const engine = {
+    createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+
+  await startPlan(data, engine, {
+    repo: "owner/repo",
+    number: 7,
+    url: "https://github.com/owner/repo/issues/7",
+    planKey: PLAN_KEY,
+  });
+
+  assertEquals(stores.plan_reviews.rows.length, 0);
+  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.
+Deno.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),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const engine = {
+    createInstance: () => Promise.resolve({ processInstanceKey: "PI-1" }),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+
+  await startPlan(data, engine, {
+    repo: "owner/repo",
+    number: 8,
+    url: "https://github.com/owner/repo/issues/8",
+    planKey: PLAN_KEY,
+  });
+
+  // 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 { answerTaskEscalation, 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" },
+  };
+}
+
+// deno-lint-ignore no-explicit-any
+function memData(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+}
+
+Deno.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");
+  // deno-lint-ignore no-explicit-any
+  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.
+  // deno-lint-ignore no-explicit-any
+  (stores.plan_escalations.rows.find((r: any) => r.id === 1) as any).status = "answered";
+  await refreshOpenTaskEscalation(data, "owner/repo#9");
+  // deno-lint-ignore no-explicit-any
+  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.
+  // deno-lint-ignore no-explicit-any
+  (stores.plan_escalations.rows.find((r: any) => r.id === 2) as any).status = "answered";
+  await refreshOpenTaskEscalation(data, "owner/repo#9");
+  // deno-lint-ignore no-explicit-any
+  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);
+});
+
+Deno.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);
+
+  // deno-lint-ignore no-explicit-any
+  const published: any[] = [];
+  const engine = {
+    // deno-lint-ignore no-explicit-any
+    publishMessage: (m: any) => {
+      published.push(m);
+      return Promise.resolve();
+    },
+    // deno-lint-ignore no-explicit-any
+  } 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.
+  // deno-lint-ignore no-explicit-any
+  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.
+  // deno-lint-ignore no-explicit-any
+  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.
+  // deno-lint-ignore no-explicit-any
+  assertEquals((stores.plans.rows[0] as any).open_task_escalation_id, 2);
+});
+
+Deno.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")),
+    // deno-lint-ignore no-explicit-any
+  } as any;
+  const r = await answerTaskEscalation(data, engine, "owner/repo#9:missing", "x");
+  assertEquals(r.ok, false);
+});

package/app/plan.ts

@@ -0,0 +1,321 @@
+// nano-workforce — planning fan-out logic (issue #14).
+//
+// A planning agent (`senior:plan`) decomposes an issue into a list of tasks; the
+// `plan-fanout` process then fans those tasks out over a parallel multi-instance
+// service task (`senior:feature`), one implementation agent per task. Each agent
+// opens a PR, which `record-results` enrolls into the existing convergence loop.
+//
+// This module is the seam the start actions and the record workers call: it owns
+// issue parsing, the plan/plan_tasks row shapes, the prompt assets, and starting
+// the process. Data access goes through the record gateway (`data.table`), never
+// hand-written SQL — matching app/service.ts.
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
+import { clearTaskDeltas } from "./taskDelta.ts";
+import { clearExclusions } from "./mergeExclusion.ts";
+
+/** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
+export const PLAN_PROCESS_ID = "plan-fanout";
+
+const now = () => new Date().toISOString();
+
+// Agent prompts are no longer read by the host. The `senior:plan`, `senior:plan-review`, and
+// `senior:feature` prompts are authored in the model as `{{plan}}` / `{{plan-review}}` /
+// `{{feature}}` deploy-time templates (see `models.templates` in nano.app.json) substituted into
+// each task's `io.nanobpm.agentTask.task.prompt` header. Per-instance dynamic context (a plan's
+// rejection findings, a task's brief) rides `appendPrompt`, which the harness concatenates onto
+// the header base. The host only carries runtime identity + `planFindings`.
+
+export interface Plan {
+  plan_key: string;
+  repo: string;
+  issue_number: number;
+  issue_url: string;
+  title: string | null;
+  status: string;
+  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;
+  // 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;
+  // Per-plan capability token for the coordination blackboard (009_plan_blackboard.sql, #51).
+  // Minted at plan start; baked into the blackboard URL handed to implementer agents. NULL for
+  // plans created before the blackboard shipped.
+  blackboard_token: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export interface PlanTask {
+  id: number;
+  plan_key: string;
+  task_index: number;
+  task_id: string;
+  title: string | null;
+  prompt: string | null;
+  status: PlanTaskStatus;
+  pr_key: string | null;
+  summary: string | null;
+  wave: number | null;
+  // Implementation-phase escalation (issue #25): the agent's open question, the
+  // human's answer, the work-preserving draft PR, and the message correlation key
+  // (`<plan_key>:<task_id>`) the process parks on. NULL unless the task escalated.
+  open_question: string | null;
+  answer: string | null;
+  draft_pr_key: string | null;
+  corr_key: string | null;
+  created_at: string;
+  updated_at: string;
+}
+
+export const PLAN_TASK_STATUSES = [
+  "pending",
+  "opened",
+  "blocked",
+  "skipped",
+  "escalated",
+  "waiting-for-lane",
+] 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";
+
+/** 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). */
+export interface PlanTaskDep {
+  plan_key: string;
+  task_id: string;
+  depends_on_task_id: string;
+}
+export const planTaskDeps = (data: DataLayer) =>
+  data.table<PlanTaskDep>("plan_task_deps", "plan_key");
+
+/** One adversarial plan-review round (006_plan_review.sql): the `senior:plan-review` agent's
+ * verdict on the plan before fan-out. Append-only within a plan run; the current round is
+ * `count(plan_reviews)`. Re-planning a finished issue clears the prior rows (see startPlan) so
+ * the round index restarts at 0.
+ * `job_key` is the engine job key that wrote the row — an idempotency guard so a retried job
+ * (crash/timeout after the insert) reuses its row instead of appending a duplicate round. */
+export interface PlanReview {
+  plan_key: string;
+  round: number;
+  approved: number;
+  findings: string | null;
+  created_at: string;
+  job_key: string | null;
+}
+export const planReviews = (data: DataLayer) => data.table<PlanReview>("plan_reviews", "plan_key");
+
+/** 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. */
+export function positiveIntEnv(name: string, fallback: number): number {
+  const raw = process.env[name];
+  if (raw == null || raw.trim() === "") return fallback;
+  const n = Number(raw);
+  return Number.isInteger(n) && n > 0 ? n : fallback;
+}
+
+/** Max adversarial plan-review rounds before the fan-out proceeds regardless (so a reviewer that
+ * never approves can't dead-lock the plan). The last round's findings are still recorded. */
+export const MAX_PLAN_REVIEW_ROUNDS = positiveIntEnv("NANO_PLAN_REVIEW_ROUNDS", 3);
+
+/** 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"];
+
+export interface ParsedIssue {
+  repo: string;
+  number: number;
+  url: string;
+  planKey: string;
+}
+
+/** Parse "owner/repo#123" or a canonical issue URL into its parts. Mirrors parsePr
+ * (app/service.ts) but for the /issues/ path. */
+export function parseIssue(input: string): ParsedIssue | null {
+  const s = input.trim();
+  let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/i);
+  if (m) {
+    const repo = `${m[1]}/${m[2]}`;
+    const number = Number(m[3]);
+    return { repo, number, url: `https://github.com/${repo}/issues/${number}`, planKey: `${repo}#${number}` };
+  }
+  m = s.match(/^([^/]+\/[^#]+)#(\d+)$/);
+  if (m) {
+    const repo = m[1];
+    const number = Number(m[2]);
+    return { repo, number, url: `https://github.com/${repo}/issues/${number}`, planKey: `${repo}#${number}` };
+  }
+  return null;
+}
+
+/** Register a plan row (if new) and start the plan-fanout process. Idempotent on
+ * planKey: a plan already in flight is not restarted. */
+export async function startPlan(data: DataLayer, engine: EngineClient, parsed: ParsedIssue) {
+  const table = plans(data);
+  const existing = await table.get(parsed.planKey);
+  if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
+    return { planKey: parsed.planKey, alreadyRunning: true };
+  }
+  const ts = now();
+  // Mint (or reuse, on a re-plan) this plan's blackboard capability token, and render the
+  // coordination brief that carries its concrete URL. The token is the credential; agents reach
+  // the blackboard directly with the URL we seed into `appendPrompt` below (#51).
+  const token = existing?.blackboard_token ?? mintBlackboardToken();
+  const bbUrl = blackboardUrl(token);
+  if (existing) {
+    // Re-plan a previously finished issue: clear the old tasks and start fresh.
+    for (const t of await planTasks(data).find({ plan_key: parsed.planKey })) {
+      await planTasks(data).delete(t.id);
+    }
+    // `plan_reviews` is append-only and the review round is derived from
+    // `count(plan_reviews)`, so stale rows from the prior run would inflate the
+    // next round index and trip `reviewExhausted` early (bypassing the gate).
+    // 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`.
+    for (const e of await planEscalations(data).find({ plan_key: parsed.planKey })) {
+      await planEscalations(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);
+    // And the merge-exclusion graph (D1, #57): stale edges would mislead the merge-train.
+    await clearExclusions(data, parsed.planKey);
+    await table.update(parsed.planKey, {
+      status: "planning",
+      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,
+      blackboard_token: token,
+      updated_at: ts,
+    });
+  } else {
+    await table.insert({
+      plan_key: parsed.planKey,
+      repo: parsed.repo,
+      issue_number: parsed.number,
+      issue_url: parsed.url,
+      status: "planning",
+      task_count: 0,
+      blackboard_token: token,
+      created_at: ts,
+      updated_at: ts,
+    });
+  }
+  const { processInstanceKey } = await engine.createInstance({
+    processDefinitionId: PLAN_PROCESS_ID,
+    variables: {
+      planKey: parsed.planKey,
+      repo: parsed.repo,
+      issue: parsed.planKey,
+      issueNumber: parsed.number,
+      issueUrl: parsed.url,
+      planFindings: 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
+      // out-of-band.
+      blackboardUrl: bbUrl,
+      blackboardBrief: renderCoordinationBrief(bbUrl),
+    },
+  });
+  if (processInstanceKey != null) {
+    await table.update(parsed.planKey, { process_key: String(processInstanceKey), updated_at: now() });
+  }
+  return { planKey: parsed.planKey, processKey: processInstanceKey };
+}
+
+/** 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();
+  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 };
+}

package/app/record-plan-review.test.ts

@@ -0,0 +1,38 @@
+// Red/green regression for record-plan-review's defensive stringify (PR #26 review).
+//
+// `str()` normalizes an agent-emitted `findings` variable to a string before it is recorded and
+// re-emitted as `planFindings`. `JSON.stringify` can THROW (BigInt, circular refs) or return
+// `undefined` (functions/symbols); either would fail the whole job and wedge the process in a
+// retry loop. `str()` must never throw and must always yield a string.
+import { assertEquals } from "jsr:@std/assert@1";
+import { str } from "../workers/record-plan-review/worker.ts";
+
+Deno.test("strings pass through unchanged", () => {
+  assertEquals(str("hello"), "hello");
+  assertEquals(str(""), "");
+});
+
+Deno.test("null/undefined → empty string", () => {
+  assertEquals(str(null), "");
+  assertEquals(str(undefined), "");
+});
+
+Deno.test("plain objects/arrays → JSON", () => {
+  assertEquals(str({ a: 1 }), '{"a":1}');
+  assertEquals(str([1, 2]), "[1,2]");
+});
+
+Deno.test("BigInt does not throw (JSON.stringify would) → String fallback", () => {
+  assertEquals(str(10n), "10");
+});
+
+Deno.test("circular structure does not throw → String fallback", () => {
+  const circular: Record<string, unknown> = {};
+  circular.self = circular;
+  const out = str(circular);
+  assertEquals(typeof out, "string");
+});
+
+Deno.test("value JSON.stringify renders as undefined → String fallback", () => {
+  assertEquals(str(() => 1), String(() => 1));
+});