@nanobpm/nano-workforce 0.44.1 → 0.46.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [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)
+
+
+### Features
+
+* **plan:** pin an epic's base branch so the fleet lands on an integration branch ([#125](https://github.com/nanobpm/nano-workforce/issues/125)) ([1c3bfa1](https://github.com/nanobpm/nano-workforce/commit/1c3bfa1a1dbc212e31e510931766f46904dae1a3)), closes [#124](https://github.com/nanobpm/nano-workforce/issues/124) [nanobpm/nano-workforce#124](https://github.com/nanobpm/nano-workforce/issues/124)
+
 ## [0.44.1](https://github.com/nanobpm/nano-workforce/compare/v0.44.0...v0.44.1) (2026-08-11)
 
 

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

@@ -5,7 +5,7 @@
 // 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 { test } from "node:test";
-import { assertEquals } from "#test-assert";
+import { assertEquals, assertThrows } from "#test-assert";
 import { positiveIntEnv } from "./plan.ts";
 
 const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
@@ -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 {
@@ -292,3 +302,188 @@ test("answerTaskEscalation is a no-op when no open escalation matches the correl
   const r = await answerTaskEscalation(data, engine, "owner/repo#9:missing", "x");
   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
+// integration branch instead of the repo default, keeping an epic off the default branch (and off any
+// merge-to-default side effect such as auto-publishing) until the integration branch is deliberately
+// merged. `normalizeBaseBranch` decides "unset" (fall back to default), `renderBaseBranchBrief` is the
+// authoritative prompt override, and `startPlan` must persist the branch and seed BOTH the `baseBranch`
+// variable and the `baseBranchBrief` (which rides `appendPrompt`) — or leave them null when unpinned.
+import { InvalidBaseBranchError, normalizeBaseBranch, renderBaseBranchBrief } from "./plan.ts";
+
+test("normalizeBaseBranch: blank/whitespace/undefined → null; a real branch is trimmed", () => {
+  assertEquals(normalizeBaseBranch(undefined), null);
+  assertEquals(normalizeBaseBranch(null), null);
+  assertEquals(normalizeBaseBranch(""), null);
+  assertEquals(normalizeBaseBranch("   "), null);
+  assertEquals(normalizeBaseBranch("  epic/agent-protocol  "), "epic/agent-protocol");
+});
+
+test("normalizeBaseBranch: accepts conservative git-branch shapes", () => {
+  assertEquals(normalizeBaseBranch("main"), "main");
+  assertEquals(normalizeBaseBranch("release-1.2"), "release-1.2");
+  assertEquals(normalizeBaseBranch("feature/x_y.z"), "feature/x_y.z");
+});
+
+test("normalizeBaseBranch: rejects injection-prone / implausible branch names", () => {
+  // `baseBranch` is interpolated into an authoritative agent prompt that carries shell
+  // commands, so anything that isn't a plausible git ref must be rejected at the edge —
+  // not silently rendered into `git`/`gh` snippets or the prompt Markdown.
+  const bad = [
+    "foo bar", // whitespace
+    "-rf", // leading dash → looks like a CLI flag
+    "foo; rm -rf /", // shell metacharacters
+    "foo`whoami`", // command substitution
+    "foo$(id)", // command substitution
+    "foo\nbar", // newline → breaks rendered instructions
+    "foo..bar", // git-illegal double dot
+    "/foo", // leading slash
+    "foo/", // trailing slash
+    "foo.", // trailing dot
+    "foo//bar", // empty path component
+    "foo.lock", // git-reserved .lock suffix
+    "épée", // outside the conservative allowlist
+  ];
+  for (const value of bad) {
+    assertThrows(() => normalizeBaseBranch(value), InvalidBaseBranchError);
+  }
+});
+
+test("renderBaseBranchBrief names the branch in every instruction (branch-off, read, PR base)", () => {
+  const brief = renderBaseBranchBrief("epic/agent-protocol");
+  // Authoritative marker so it overrides the static "default branch" wording.
+  assertEquals(brief.includes("authoritative"), true);
+  assertEquals(brief.includes("git checkout -b feat/<task.id> origin/epic/agent-protocol"), true);
+  assertEquals(brief.includes("gh pr create --base epic/agent-protocol"), true);
+});
+
+test("startPlan pins the base branch: persisted on the row + seeded as baseBranch/baseBranchBrief variables", async () => {
+  const PLAN_KEY = "owner/repo#124";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_escalations: { rows: [], key: "id" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const data = memData(stores);
+  let seen: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      seen = req.variables;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+
+  await startPlan(
+    data,
+    engine,
+    { repo: "owner/repo", number: 124, url: "https://github.com/owner/repo/issues/124", planKey: PLAN_KEY },
+    "  epic/agent-protocol  ",
+  );
+
+  // Persisted (trimmed) on the plan row for the epic UI + resume.
+  assertEquals((stores.plans.rows[0] as any).base_branch, "epic/agent-protocol");
+  // Process variables the implement-task consumes.
+  assertEquals(seen.baseBranch, "epic/agent-protocol");
+  assertEquals(seen.baseBranchBrief.includes("gh pr create --base epic/agent-protocol"), true);
+});
+
+test("startPlan without a base branch keeps default-branch behaviour (null row + null variables)", async () => {
+  const PLAN_KEY = "owner/repo#200";
+  const stores: Record<string, { rows: any[]; key: string }> = {
+    plans: { rows: [], key: "plan_key" },
+    plan_tasks: { rows: [], key: "id" },
+    plan_reviews: { rows: [], key: "plan_key" },
+    plan_escalations: { rows: [], key: "id" },
+    plan_task_deps: { rows: [], key: "plan_key" },
+  };
+  const data = memData(stores);
+  let seen: any = null;
+  const engine = {
+    createInstance: (req: any) => {
+      seen = req.variables;
+      return Promise.resolve({ processInstanceKey: "PI-2" });
+    },
+  } as any;
+
+  await startPlan(data, engine, {
+    repo: "owner/repo",
+    number: 200,
+    url: "https://github.com/owner/repo/issues/200",
+    planKey: PLAN_KEY,
+  });
+
+  assertEquals((stores.plans.rows[0] as any).base_branch, null);
+  assertEquals(seen.baseBranch, null);
+  assertEquals(seen.baseBranchBrief, null);
+});

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;
@@ -51,6 +58,10 @@ export interface Plan {
   // 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;
+  // Optional target base branch (019_plan_base_branch.sql): when set, the fleet branches off this
+  // branch and opens every task PR against it instead of the repository's default branch, landing
+  // the whole epic on a long-lived integration branch. NULL keeps the default-branch behaviour.
+  base_branch: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -111,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}`;
 
@@ -132,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;
@@ -140,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. */
@@ -150,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"];
@@ -185,14 +232,79 @@ export function parseIssue(input: string): ParsedIssue | null {
   return null;
 }
 
+/** Raised when a caller supplies a `baseBranch` that isn't a plausible git branch name. The
+ * value is interpolated into the authoritative implementer prompt (which carries `git`/`gh`
+ * shell snippets and inline-code Markdown), so a non-ref value could break the rendered
+ * instructions or smuggle in a command/prompt fragment — reject it at the edge instead. */
+export class InvalidBaseBranchError extends Error {
+  readonly value: string;
+  constructor(value: string) {
+    super(`invalid base branch name: ${JSON.stringify(value)}`);
+    this.name = "InvalidBaseBranchError";
+    this.value = value;
+  }
+}
+
+/** Conservative allowlist gate for a base-branch name. Stricter than `git check-ref-format` on
+ * purpose: only `[A-Za-z0-9._/-]`, no leading `/`/`.`/`-` (a leading dash reads as a CLI flag),
+ * no trailing `/`/`.`, no `..`/`//`, no empty or `.lock`-suffixed path component, bounded length.
+ * This rejects whitespace, shell metacharacters, command substitution, and newlines outright. */
+function isPlausibleBranchName(s: string): boolean {
+  if (s.length === 0 || s.length > 255) return false;
+  if (!/^[A-Za-z0-9._/-]+$/.test(s)) return false;
+  if (/^[/.-]/.test(s) || /[/.]$/.test(s)) return false;
+  if (s.includes("..") || s.includes("//")) return false;
+  return s.split("/").every((seg) => seg.length > 0 && !seg.startsWith(".") && !seg.endsWith(".lock"));
+}
+
+/** Normalise a caller-supplied base branch: trim, and treat blank as "unset" (null) so the fleet
+ * falls back to the repository's default branch — the legacy behaviour. A non-blank value that is
+ * not a plausible git branch name is rejected (`InvalidBaseBranchError`) rather than persisted or
+ * rendered into the agent prompt; the operation edge maps that to a 400. */
+export function normalizeBaseBranch(input: string | null | undefined): string | null {
+  const s = (input ?? "").trim();
+  if (s.length === 0) return null;
+  if (!isPlausibleBranchName(s)) throw new InvalidBaseBranchError(s);
+  return s;
+}
+
+/** The per-instance brief appended to an implementer agent's prompt when the plan pins a base
+ * branch. It is authoritative over the static "branch off the default branch" wording in
+ * prompts/feature.md, so the agent branches off — and opens its PR against — the integration
+ * branch, and reads the epic's latest landed state there rather than the repo default branch. */
+export function renderBaseBranchBrief(baseBranch: string): string {
+  return [
+    "",
+    "",
+    "---",
+    "",
+    `**Base branch (authoritative — overrides any "default branch" instruction above): \`${baseBranch}\`.**`,
+    "",
+    `This epic lands on \`${baseBranch}\`, NOT the repository default branch. Everywhere the`,
+    "instructions say \"default branch\", use this branch instead:",
+    "",
+    `- Branch off it: \`git fetch origin ${baseBranch} && git checkout -b feat/<task.id> origin/${baseBranch}\`.`,
+    `- Read the epic's latest landed state from \`${baseBranch}\` (your prerequisites merged there, not into the default branch).`,
+    `- Open your PR against it: \`gh pr create --base ${baseBranch} ...\`.`,
+    "",
+    "Do not target the repository default branch — a PR opened against it will not be merged into the epic.",
+  ].join("\n");
+}
+
 /** 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) {
+export async function startPlan(
+  data: DataLayer,
+  engine: EngineClient,
+  parsed: ParsedIssue,
+  baseBranch: string | null = null,
+) {
   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 base = normalizeBaseBranch(baseBranch);
   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
@@ -210,14 +322,18 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
     // 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);
@@ -234,7 +350,11 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       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,
     });
   } else {
@@ -246,6 +366,7 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       status: "planning",
       task_count: 0,
       blackboard_token: token,
+      base_branch: base,
       created_at: ts,
       updated_at: ts,
     });
@@ -265,6 +386,12 @@ export async function startPlan(data: DataLayer, engine: EngineClient, parsed: P
       // out-of-band.
       blackboardUrl: bbUrl,
       blackboardBrief: renderCoordinationBrief(bbUrl),
+      // Optional epic base branch (019_plan_base_branch.sql): the branch the fleet branches off and
+      // opens every PR against instead of the repo default. `baseBranchBrief` rides `appendPrompt`
+      // in the implement-task (like `blackboardBrief`); both are null when no base branch is pinned,
+      // so the agent keeps the default-branch behaviour from prompts/feature.md.
+      baseBranch: base,
+      baseBranchBrief: base == null ? null : renderBaseBranchBrief(base),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -321,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/app/service.test.ts

@@ -347,3 +347,39 @@ test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch
 test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {
   assertEquals(Object.keys(repoEnvelopeVars("owner/repo", null)).length, 0);
 });
+
+test("repoEnvelopeVars emits nothing for a malformed repo (not owner/repo)", () => {
+  // Defence in depth: a repo that isn't exactly `owner/repo` would build a bogus clone URL, so the
+  // helper emits no envelope (harness falls back to the launch dir) rather than a malformed URL.
+  for (const bad of [
+    "",
+    "noslash",
+    "a/b/c",
+    "owner /repo",
+    "owner/re po",
+    "/repo",
+    "owner/",
+    // A trailing `.git` would build a double-suffixed clone URL (…/owner/repo.git.git).
+    "owner/repo.git",
+    "owner/repo.GIT",
+    // Query/fragment/host-injection characters must never reach the clone URL.
+    "owner/repo?x",
+    "owner/repo#frag",
+    "owner/repo:x",
+    "owner/re~po",
+    // Owner is a GitHub login: no dots or underscores allowed there.
+    "own.er/repo",
+    "own_er/repo",
+  ]) {
+    assertEquals(Object.keys(repoEnvelopeVars(bad, "feat/x")).length, 0, `expected no envelope for "${bad}"`);
+  }
+  // Well-formed repos still emit (guard is not over-eager): hyphens, dots and underscores
+  // are legal in the repo-name segment, mixed case is preserved.
+  for (const good of ["owner/repo", "my-org/my.repo", "Owner123/Repo_2", "a-b/c-d"]) {
+    assertEquals(
+      ((repoEnvelopeVars(good, "feat/x") as any)["io.nanobpm.agentTask"].repository.url),
+      `https://github.com/${good}.git`,
+      `expected envelope for "${good}"`,
+    );
+  }
+});

package/app/service.ts

@@ -292,6 +292,14 @@ const AGENT_TASK_NS = "io.nanobpm.agentTask";
  * `task.prompt` header on the service task deep-merges with this over the same namespace. */
 export function repoEnvelopeVars(repo: string, ref: string | null): Record<string, unknown> {
   if (!ref) return {};
+  // Defence in depth: every current caller derives `repo` from parsePr/parseIssue (regex-bounded to
+  // `owner/repo`), but this is an exported helper the fan-out epic gives many new callers. A repo
+  // that is not exactly `owner/repo` would build a bogus clone URL, so emit nothing (the harness
+  // then falls back to the launch-dir behaviour) rather than handing the harness a malformed URL.
+  // The owner is a GitHub login (alphanumeric + hyphen); the repo-name segment additionally allows
+  // `.` and `_`. A trailing `.git` is rejected outright so we never emit a double-suffixed
+  // `…/owner/repo.git.git`, and the anchored allowlist bars query/fragment/host-injection chars.
+  if (!/^[A-Za-z0-9-]+\/[A-Za-z0-9._-]+$/.test(repo) || /\.git$/i.test(repo)) return {};
   return {
     [AGENT_TASK_NS]: {
       repository: { provider: "github", url: `https://github.com/${repo}.git`, ref },

package/db/migrations/019_plan_base_branch.sql

@@ -0,0 +1,8 @@
+-- Per-plan target base branch (epic base-branch control). When set, the fleet branches off this
+-- branch and opens every task PR against it instead of the repository's default branch, so an
+-- entire epic can land on a long-lived integration branch (e.g. `epic/agent-protocol`) and reach
+-- the default branch — and any merge-to-default side effect such as auto-publishing a package —
+-- only when the integration branch is deliberately merged. NULL keeps the legacy behaviour (the
+-- repo default branch), so pre-migration plans are unaffected.
+
+ALTER TABLE plans ADD COLUMN base_branch TEXT;