@nanobpm/nano-workforce 0.93.0 → 0.95.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.95.0](https://github.com/nanobpm/nano-workforce/compare/v0.94.0...v0.95.0) (2026-08-19)
+
+
+### Features
+
+* **pages:** render "Updated" columns in the viewer's local time ([#302](https://github.com/nanobpm/nano-workforce/issues/302)) ([a73504d](https://github.com/nanobpm/nano-workforce/commit/a73504d6d6ebc968f21fa0f49eebf72774aa4b51)), closes [nano-ide#327](https://github.com/nano-ide/issues/327) [nano-ide#329](https://github.com/nano-ide/issues/329) [#301](https://github.com/nanobpm/nano-workforce/issues/301) [nano-ide#329](https://github.com/nano-ide/issues/329)
+
+# [0.94.0](https://github.com/nanobpm/nano-workforce/compare/v0.93.0...v0.94.0) (2026-08-19)
+
+
+### Features
+
+* **pages:** feature-runs current stage links to the process instance ([#316](https://github.com/nanobpm/nano-workforce/issues/316)) ([4984f13](https://github.com/nanobpm/nano-workforce/commit/4984f13c1a3bd101499763731843ee4807bec49e)), closes [#315](https://github.com/nanobpm/nano-workforce/issues/315) [nano-ide#347](https://github.com/nano-ide/issues/347) [nanobpm/nano-ide#348](https://github.com/nanobpm/nano-ide/issues/348) [#311](https://github.com/nanobpm/nano-workforce/issues/311) [#307](https://github.com/nanobpm/nano-workforce/issues/307)
+
 # [0.93.0](https://github.com/nanobpm/nano-workforce/compare/v0.92.0...v0.93.0) (2026-08-19)
 
 

package/app/plan.test.ts

@@ -306,6 +306,60 @@ test("startPlan grandfathers a pre-existing null base_branch row: re-plan reads
   assertEquals(seen.baseBranch, "epic/gate-branch");
 });
 
+test("startPlan fails fast when readiness probes are seeded without a probeTimeout (unusable gate)", async () => {
+  // A gated dependent's preflight escalation timers read `=probeTimeout` and `pr.readiness-probe`
+  // rejects a blank bound, so a non-empty probe set with a null/blank `probeTimeout` would incident
+  // at runtime. Guard the whole class at the start door: reject it before any side effect, and never
+  // create the process instance. The lowering always derives the pair together, so this only fires
+  // for a mis-seeded direct caller.
+  const PLAN_KEY = "owner/repo#292";
+  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 created = false;
+  const engine = {
+    createInstance: () => {
+      created = true;
+      return Promise.resolve({ processInstanceKey: "PI-292" });
+    },
+  } as any;
+
+  const probe = { kind: "command", target: "true", resolvedArtifact: "@scope/pkg@1.0.0" };
+  await assertRejects(
+    () =>
+      startPlan(
+        data,
+        engine,
+        { repo: "owner/repo", number: 292, url: "https://github.com/owner/repo/issues/292", planKey: PLAN_KEY },
+        "epic/gate-branch",
+        { readinessProbes: [probe] as any },
+      ),
+    Error,
+    "probeTimeout",
+  );
+  // A blank/whitespace bound is rejected the same way.
+  await assertRejects(
+    () =>
+      startPlan(
+        data,
+        engine,
+        { repo: "owner/repo", number: 292, url: "https://github.com/owner/repo/issues/292", planKey: PLAN_KEY },
+        "epic/gate-branch",
+        { readinessProbes: [probe] as any, probeTimeout: "   " },
+      ),
+    Error,
+    "probeTimeout",
+  );
+  // No side effect leaked: no plan row written, no process instance created.
+  assertEquals(stores.plans.rows.length, 0);
+  assertEquals(created, false);
+});
+
 // ── admitPlan decision matrix (ADR 0003 §Decision, rules 1-4) ────────────────
 // The fail-fast admission gate composes four ORDERED rules before any fan-out. These drive it
 // through a faked github transport (token mode + stubbed `globalThis.fetch`) and an in-memory

package/app/plan.ts

@@ -22,6 +22,7 @@ import {
   fetchIssueTitle,
 } from "./github.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
+import type { ReadinessProbe } from "./readiness.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
@@ -873,6 +874,20 @@ function assertAcyclic(adjacency: Map<string, Set<string>>): void {
   }
 }
 
+/** Optional scheduling inputs a planner (slice S3) threads into a plan-fanout instance at start.
+ *
+ * `readinessProbes` is the set of `capability` {@link ReadinessProbe} descriptors a DEPENDENT epic
+ * must satisfy before it fans out any wave — one per inbound inter-epic edge (its producers). The
+ * plan-fanout process runs them as a LEADING readiness-gate preflight (resources/processes/plan-fanout.bpmn):
+ * a root epic (no inbound edge) is started with `undefined`/empty here and skips the gate entirely,
+ * fanning out immediately exactly as a single epic does today. `probeTimeout` is the ISO-8601 bound
+ * the preflight's timers fire off (derived once, via {@link readinessTimeout}, from the same probes)
+ * so a never-publishing producer escalates in bounded time instead of wedging the dependent. */
+export interface StartPlanOptions {
+  readinessProbes?: ReadinessProbe[];
+  probeTimeout?: string;
+}
+
 /** 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(
@@ -880,7 +895,21 @@ export async function startPlan(
   engine: EngineClient,
   parsed: ParsedIssue,
   baseBranch: string,
+  opts: StartPlanOptions = {},
 ) {
+  // A gated dependent must carry BOTH its probes and the bound its preflight timers fire off:
+  // `pr.readiness-probe` rejects a blank `probeTimeout` (worker.ts) and the preflight escalation
+  // timers read `=probeTimeout`, so a non-empty probe set with a null/blank bound would incident at
+  // runtime. Fail fast at the start door instead — the lowering (planLowering.ts) always derives the
+  // two together via `readinessTimeout`, so this only fires for a mis-seeded direct caller.
+  const probes = opts.readinessProbes && opts.readinessProbes.length > 0 ? opts.readinessProbes : null;
+  if (probes && (opts.probeTimeout ?? "").trim() === "") {
+    throw new Error(
+      `startPlan(${parsed.planKey}): ${probes.length} readiness probe(s) seeded without a probeTimeout — ` +
+        "the preflight escalation timers (=probeTimeout) and pr.readiness-probe both require a non-blank " +
+        "bound. Derive it via readinessTimeout (see planLowering) before starting a gated dependent.",
+    );
+  }
   const table = plans(data);
   const existing = await table.get(parsed.planKey);
   if (existing && !PLAN_TERMINAL_STATUSES.includes(existing.status)) {
@@ -982,6 +1011,25 @@ export async function startPlan(
       // (normalizeBaseBranch rejects blank), so the brief is always rendered.
       baseBranch: base,
       baseBranchBrief: renderBaseBranchBrief(base),
+      // Inter-epic scheduling (issue #292, slice S3): the leading capability readiness-gate the
+      // plan-fanout runs as a PREFLIGHT before wave 0. `readinessProbes` is a DEPENDENT epic's set
+      // of `capability` probes (one per inbound `plan_deps` edge / producer); it is `null` for a
+      // ROOT (no inbound edge), whose preflight gateway then routes straight past the gate so it
+      // fans out immediately. `probeTimeout` bounds the preflight's escalation timers (derived once
+      // from the same probes) so a never-publishing producer escalates without wedging the set.
+      // `resolvedArtifacts` is filled by the preflight on green — the exact `pkg@version`s carrying
+      // each awaited capability (one per probe, `null` for any that escalated). It rides the
+      // implement task's `appendPrompt` (like `baseBranchBrief`) so slices build against exactly the
+      // bound version. Seeded `null` here so a ROOT (which never runs the preflight) still resolves
+      // the variable in that FEEL expression instead of raising an incident.
+      readinessProbes: probes,
+      probeTimeout: opts.probeTimeout ?? null,
+      // The preflight probe worker (`pr.readiness-probe`) requires a non-blank `gateKey` correlation
+      // key (it publishes `readiness-ready` on it). The typed `ReadinessProbeIn` envelope projects it
+      // from THIS process scope (not task-local ioMapping), so it is seeded here — one per dependent
+      // instance. A ROOT never runs the preflight, so its `gateKey` stays `null`, unused.
+      gateKey: probes ? `preflight:${parsed.planKey}` : null,
+      resolvedArtifacts: null,
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);

package/app/planFanoutPreflight.test.ts

@@ -0,0 +1,73 @@
+// Structural guard for the inter-epic capability PREFLIGHT wired into plan-fanout (issue #292, slice
+// S3). Before S3, `plan-fanout.bpmn` fanned out every epic immediately and `readiness-gate.bpmn` was a
+// standalone process it never invoked. S3 seeds a LEADING capability readiness-gate before wave 0 for
+// dependent epics: an exclusive gateway after Start routes a ROOT (readinessProbes == null) straight to
+// ensure-base-branch, and a DEPENDENT into a multi-instance preflight subprocess (over =readinessProbes)
+// that polls each producer's capability via the reused `pr.readiness-probe` worker and escalates
+// (bounded) via the reused `readiness-escalation` form — never fanning a wave until the gate is green.
+// The bound `pkg@version`s (resolvedArtifacts) ride the implement task's appendPrompt.
+//
+// Pure text assertions over the committed BPMN (no engine), matching the repo's model-guard style
+// (see mergeEscalationUserTask.test.ts / mergeRebaseArm.test.ts).
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { assert, assertStringIncludes } from "#test-assert";
+
+const bpmn = readFileSync("resources/processes/plan-fanout.bpmn", "utf8");
+const flat = bpmn.replace(/\s+/g, " ");
+
+function hasFlow(source: string, target: string): boolean {
+  const re = new RegExp(
+    `<bpmn:sequenceFlow\\b[^>]*\\bsourceRef="${source}"[^>]*\\btargetRef="${target}"|` +
+      `<bpmn:sequenceFlow\\b[^>]*\\btargetRef="${target}"[^>]*\\bsourceRef="${source}"`,
+  );
+  return re.test(flat);
+}
+
+test("Start routes through a readiness gateway that a ROOT skips and a DEPENDENT enters", () => {
+  assert(hasFlow("Start", "gw-readiness"), "Start must reach the readiness gateway");
+  const gw = flat.match(/<bpmn:exclusiveGateway\b[^>]*\bid="gw-readiness"[\s\S]*?<\/bpmn:exclusiveGateway>/);
+  assert(gw, "gw-readiness must be an exclusiveGateway");
+  // Default (root) skips straight to ensure-base-branch; the gated flow enters the preflight only when
+  // readinessProbes is present (a dependent).
+  assertStringIncludes(gw![0], 'default="f_readiness_skip"', "root (no probes) is the default skip flow");
+  assert(hasFlow("gw-readiness", "ensure-base-branch"), "root skips straight to ensure-base-branch");
+  assert(hasFlow("gw-readiness", "readiness-preflight"), "dependent enters the preflight subprocess");
+  const gate = flat.match(/<bpmn:sequenceFlow\b[^>]*\bid="f_readiness_gate"[\s\S]*?<\/bpmn:sequenceFlow>/);
+  assert(gate, "the gated flow must be conditional");
+  assertStringIncludes(gate![0], "readinessProbes != null", "only a dependent (has probes) is gated");
+});
+
+test("the preflight is a multi-instance subprocess over =readinessProbes collecting resolvedArtifacts", () => {
+  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/);
+  assert(sub, "readiness-preflight must be a subProcess");
+  assertStringIncludes(sub![0], "<bpmn:multiInstanceLoopCharacteristics", "it waits for ALL producers in parallel");
+  assertStringIncludes(sub![0], 'inputCollection="=readinessProbes"', "one instance per seeded capability probe");
+  assertStringIncludes(sub![0], 'outputCollection="resolvedArtifacts"', "binds each resolved pkg@version");
+  assert(hasFlow("readiness-preflight", "ensure-base-branch"), "the gate leads into the fan-out, before wave 0");
+});
+
+test("the preflight reuses the pr.readiness-probe worker and the readiness-escalation form (no reinvention)", () => {
+  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
+  assertStringIncludes(sub, 'type="pr.readiness-probe"', "reuses the existing capability probe worker");
+  assertStringIncludes(sub, 'value="ReadinessProbeIn"', "feeds the shared probe input envelope");
+  assertStringIncludes(sub, 'value="ReadinessProbeOut"', "reads the shared probe output envelope");
+  assertStringIncludes(sub, 'formId="readiness-escalation"', "reuses the existing readiness escalation form");
+});
+
+test("a never-green producer escalates (bounded) without wedging: probe timeout + SLA both settle the gate", () => {
+  const sub = flat.match(/<bpmn:subProcess\b[^>]*\bid="readiness-preflight"[\s\S]*?<\/bpmn:subProcess>/)![0];
+  // The probe carries an interrupting timeout bound (reuses the gate's =probeTimeout), and the human
+  // escalation carries the shared SLA bound — so a stuck producer can never wedge the dependent.
+  assertStringIncludes(sub, "=probeTimeout", "the probe is bounded by the reused =probeTimeout");
+  assertStringIncludes(sub, "=escalationSlaTimeout", "the escalation is bounded by the shared SLA");
+  assert(hasFlow("be_pf_probe_timeout", "readiness-escalation-pf"), "a timed-out probe routes to escalation");
+  assert(hasFlow("pf_gw", "readiness-escalation-pf"), "a not-ready probe routes to escalation");
+  assert(hasFlow("be_pf_sla", "pf_end"), "an elapsed escalation SLA settles the preflight instead of wedging");
+});
+
+test("the bound resolvedArtifacts version rides the implement task's appendPrompt", () => {
+  const task = flat.match(/<bpmn:serviceTask\b[^>]*\bid="implement-task"[\s\S]*?<\/bpmn:serviceTask>/);
+  assert(task, "implement-task must exist");
+  assertStringIncludes(task![0], "resolvedArtifacts", "the bound pkg@version is threaded into the slice prompt");
+});

package/app/planLowering.test.ts

@@ -0,0 +1,184 @@
+// Unit coverage for the inter-epic planner LOWERING (issue #292, slice S3) — the pure schedule
+// derivation (`deriveEpicSchedule` / `capabilityProbeForEdge`) plus the `lowerAdmittedSet` executor
+// that reads S2's staging, starts roots immediately, seeds a capability preflight for dependents, and
+// materializes the durable `plan_deps` edges. Runs against an in-memory data/engine double (no engine,
+// no network) exactly like the admission integration harness.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import type { PlanDep } from "./plan.ts";
+import { capabilityProbeForEdge, deriveEpicSchedule, lowerAdmittedSet } from "./planLowering.ts";
+
+const edge = (consumer: string, producer: string, pkg = "@scope/pkg", capRef = producer): PlanDep => ({
+  plan_key: consumer,
+  depends_on_plan_key: producer,
+  package: pkg,
+  capability_ref: capRef,
+  created_at: "t0",
+});
+
+// ── in-memory data + engine double ───────────────────────────────────────────────────────────────
+function makeData() {
+  const tables = new Map<string, Record<string, unknown>[]>();
+  const rowsFor = (name: string) => {
+    const r = tables.get(name) ?? [];
+    tables.set(name, r);
+    return r;
+  };
+  const table = (name: string, key: string) => {
+    const rows = rowsFor(name);
+    return {
+      get: (k: unknown) => Promise.resolve(rows.find((r) => r[key] === k) ?? null),
+      find: (q: Record<string, unknown>) =>
+        Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+      insert: (r: Record<string, unknown>) => {
+        rows.push(r);
+        return Promise.resolve(r);
+      },
+      update: (k: unknown, patch: Record<string, unknown>) => {
+        const row = rows.find((r) => r[key] === k);
+        if (row) Object.assign(row, patch);
+        return Promise.resolve(row);
+      },
+      delete: (k: unknown) => {
+        const i = rows.findIndex((r) => r[key] === k);
+        if (i >= 0) rows.splice(i, 1);
+        return Promise.resolve();
+      },
+    };
+  };
+  const started: { processDefinitionId: string; variables?: Record<string, unknown> }[] = [];
+  const engine = {
+    createInstance: (req: { processDefinitionId: string; variables?: Record<string, unknown> }) => {
+      started.push(req);
+      return Promise.resolve({ processInstanceKey: `PI-${started.length}` });
+    },
+  } as unknown as EngineClient;
+  const data = { table } as unknown as DataLayer;
+  return { data, engine, tables, started };
+}
+
+function stageEpic(tables: Map<string, Record<string, unknown>[]>, planKey: string, base: string) {
+  const rows = tables.get("admitted_epics") ?? [];
+  tables.set("admitted_epics", rows);
+  const [repo, num] = planKey.split("#");
+  rows.push({
+    plan_key: planKey,
+    repo,
+    issue_number: Number(num),
+    issue_url: `https://github.com/${repo}/issues/${num}`,
+    base_branch: base,
+    created_at: "t0",
+  });
+}
+
+function stageEdge(tables: Map<string, Record<string, unknown>[]>, e: PlanDep) {
+  const rows = tables.get("admitted_plan_deps") ?? [];
+  tables.set("admitted_plan_deps", rows);
+  rows.push({ ...e });
+}
+
+// Force token-transport with NO token so startPlan's best-effort issue-title lookup short-circuits to
+// null (no `gh` shell-out, no network) — the epic falls back to its plan key for identity.
+const noFetch = async <T>(fn: () => Promise<T>): Promise<T> => {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevTok = process.env["GITHUB_TOKEN"];
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  delete process.env["GITHUB_TOKEN"];
+  try {
+    return await fn();
+  } finally {
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+    if (prevTok === undefined) delete process.env["GITHUB_TOKEN"];
+    else process.env["GITHUB_TOKEN"] = prevTok;
+  }
+};
+
+// ── capabilityProbeForEdge ──────────────────────────────────────────────────────────────────────
+test("capabilityProbeForEdge derives a capability probe pinned to the producer repo's releases", () => {
+  const probe = capabilityProbeForEdge(edge("owner/repo#2", "owner/repo#1", "@scope/pkg", "owner/repo#1"));
+  assertEquals(probe.kind, "capability");
+  assertEquals(probe.target, "github-releases:owner/repo");
+  assertEquals(probe.match?.package, "@scope/pkg");
+  assertEquals(probe.match?.capabilityRef, "owner/repo#1");
+  assertEquals(probe.onTimeout, "escalate");
+});
+
+test("capabilityProbeForEdge splits the producer repo even across different owner/repo producers", () => {
+  const probe = capabilityProbeForEdge(edge("a/consumer#5", "b/producer#9", "@b/lib", "b/producer#9"));
+  assertEquals(probe.target, "github-releases:b/producer");
+  assertEquals(probe.match?.capabilityRef, "b/producer#9");
+});
+
+// ── deriveEpicSchedule ──────────────────────────────────────────────────────────────────────────
+test("deriveEpicSchedule: an epic with no inbound edge is a ROOT (started immediately)", () => {
+  const sched = deriveEpicSchedule(["o/r#1", "o/r#2"], [edge("o/r#2", "o/r#1")]);
+  assertEquals(sched.roots, ["o/r#1"]);
+  assertEquals(sched.dependents.length, 1);
+  assertEquals(sched.dependents[0].planKey, "o/r#2");
+  assertEquals(sched.dependents[0].producers, ["o/r#1"]);
+  assertEquals(sched.dependents[0].probes.length, 1);
+});
+
+test("deriveEpicSchedule: a set with no edges makes every epic a root, no dependents", () => {
+  const sched = deriveEpicSchedule(["o/r#1", "o/r#2"], []);
+  assertEquals(sched.roots.sort(), ["o/r#1", "o/r#2"]);
+  assertEquals(sched.dependents.length, 0);
+});
+
+test("deriveEpicSchedule: a dependent with MULTIPLE inbound edges waits for ALL its producers", () => {
+  const sched = deriveEpicSchedule(
+    ["o/r#1", "o/r#2", "o/r#3"],
+    [edge("o/r#3", "o/r#1", "@a/x", "o/r#1"), edge("o/r#3", "o/r#2", "@b/y", "o/r#2")],
+  );
+  assertEquals(sched.roots.sort(), ["o/r#1", "o/r#2"]);
+  assertEquals(sched.dependents.length, 1);
+  const dep = sched.dependents[0];
+  assertEquals(dep.planKey, "o/r#3");
+  assertEquals(dep.producers.sort(), ["o/r#1", "o/r#2"]);
+  assertEquals(dep.probes.length, 2); // one probe per producer — must satisfy both to fan out
+  assert(dep.probeTimeout.startsWith("PT") || dep.probeTimeout.startsWith("P"), "an ISO-8601 bound");
+});
+
+// ── lowerAdmittedSet ────────────────────────────────────────────────────────────────────────────
+test("lowerAdmittedSet starts roots with no probe and dependents with their seeded capability gate", async () => {
+  const { data, engine, tables, started } = makeData();
+  stageEpic(tables, "o/r#1", "epic/producer");
+  stageEpic(tables, "o/r#2", "epic/consumer");
+  stageEdge(tables, edge("o/r#2", "o/r#1"));
+
+  const res = await noFetch(() => lowerAdmittedSet(data, engine, ["o/r#1", "o/r#2"]));
+
+  assertEquals(res.roots, ["o/r#1"]);
+  assertEquals(res.dependents, [{ planKey: "o/r#2", producers: ["o/r#1"] }]);
+  assertEquals(res.edgesMaterialized, 1);
+  assertEquals(started.length, 2);
+
+  const byKey = new Map(started.map((s) => [s.variables?.["planKey"], s.variables ?? {}]));
+  assertEquals(byKey.get("o/r#1")?.["readinessProbes"], null); // root fans out immediately
+  const depProbes = byKey.get("o/r#2")?.["readinessProbes"] as unknown[] | null;
+  assert(Array.isArray(depProbes) && depProbes.length === 1, "dependent seeded with one capability probe");
+  assert(byKey.get("o/r#2")?.["probeTimeout"] != null, "dependent seeded with a bounded timeout");
+
+  // Durable edge materialized (after the plans rows exist), and a plans row per epic.
+  assertEquals((tables.get("plan_deps") ?? []).length, 1);
+  assertEquals((tables.get("plans") ?? []).length, 2);
+});
+
+test("lowerAdmittedSet is idempotent: re-running neither double-starts an epic nor duplicates an edge", async () => {
+  const { data, engine, tables, started } = makeData();
+  stageEpic(tables, "o/r#1", "epic/producer");
+  stageEpic(tables, "o/r#2", "epic/consumer");
+  stageEdge(tables, edge("o/r#2", "o/r#1"));
+
+  await noFetch(() => lowerAdmittedSet(data, engine, ["o/r#1", "o/r#2"]));
+  assertEquals(started.length, 2);
+  assertEquals((tables.get("plan_deps") ?? []).length, 1);
+
+  // Second admission of the same set: startPlan short-circuits the already-running plans, recordPlanDep
+  // collapses the duplicate edge — no new instance, no duplicate row.
+  await noFetch(() => lowerAdmittedSet(data, engine, ["o/r#1", "o/r#2"]));
+  assertEquals(started.length, 2, "no epic re-started on a re-run");
+  assertEquals((tables.get("plan_deps") ?? []).length, 1, "no duplicate durable edge on a re-run");
+});

package/app/planLowering.ts

@@ -0,0 +1,201 @@
+// nano-workforce — inter-epic planner lowering (issue #292, slice S3).
+//
+// S1 landed the durable inter-epic edge (`plan_deps` + the `PlanDep` read API); S2 added the
+// set/batch admission DOOR, which validates a whole set all-or-nothing and STAGES the admitted epics
+// + validated edges FK-free into `admitted_epics` / `admitted_plan_deps` — deliberately materializing
+// NEITHER a `plans` row NOR a `plan_deps` edge, and starting nothing.
+//
+// This module is the LOWERING half: it reads that staging and turns the validated DAG into a running
+// schedule. It is the seam `startEpicSet` calls once the whole set has admitted:
+//   1. ROOTS (no inbound edge) start IMMEDIATELY — each fans out right away, exactly as a single epic
+//      does today (`startPlan` with no readiness probe).
+//   2. DEPENDENTS (≥1 inbound edge) start with a LEADING capability readiness-gate: `startPlan`
+//      seeds the epic's `capability` {@link ReadinessProbe} set (one probe per inbound edge / producer)
+//      + the ISO timeout bound, and the plan-fanout process runs them as a preflight before wave 0
+//      (resources/processes/plan-fanout.bpmn). The dependent fans out NO wave until every probe is
+//      green; a never-publishing producer escalates (bounded) via the reused readiness-escalation
+//      user task without wedging the dependent or the rest of the set. A dependent with MULTIPLE
+//      inbound edges waits for ALL its producers (the preflight is multi-instance over the probe set).
+//   3. Once each epic's `plans` row exists (created by `startPlan`), the validated edges are
+//      MATERIALIZED durably via `recordPlanDep` — the `plan_deps.plan_key REFERENCES plans(plan_key)`
+//      FK is satisfied by construction because the consumer's `plans` row was just created.
+//
+// Everything here is idempotent so RE-RUNNING admission for an already-lowered set neither
+// double-starts an epic nor re-seeds a gate nor duplicates an edge: `startPlan` short-circuits an
+// already-running plan (returning `alreadyRunning`), and `recordPlanDep` collapses a duplicate edge.
+// Because the probes are seeded once at instance creation, a re-run that finds the plan already
+// running never creates a second instance — so the gate is seeded exactly once.
+import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import {
+  type AdmittedEpic,
+  admittedEpics,
+  admittedPlanDeps,
+  type PlanDep,
+  parseIssue,
+  recordPlanDep,
+  startPlan,
+} from "./plan.ts";
+import { type ReadinessProbe, readinessTimeout } from "./readiness.ts";
+
+/** Derive the `capability` readiness probe for ONE inbound inter-epic edge: it goes green when the
+ * producer epic (`depends_on_plan_key`) has published a release of `package` whose provenance carries
+ * the `capability_ref` issue handle, resolving the LOWEST such version (`matchCapability`) and binding
+ * it as `resolvedArtifact` (`pkg@version`) — the exact version that FIRST carries the capability, not
+ * merely the newest. The provenance source repo is the producer's repo, split from its plan key. */
+export function capabilityProbeForEdge(edge: PlanDep): ReadinessProbe {
+  const producer = parseIssue(edge.depends_on_plan_key);
+  // The producer plan key is always a parseable `owner/repo#N` (S1/S2 admitted it), but fall back to
+  // the pre-`#` segment defensively so a probe is always well-formed rather than throwing here.
+  const repo = producer ? producer.repo : edge.depends_on_plan_key.split("#")[0];
+  return {
+    kind: "capability",
+    target: `github-releases:${repo}`,
+    match: { package: edge.package, capabilityRef: edge.capability_ref },
+    // A stuck/never-publishing producer must ESCALATE (bounded) — never fail the dependent silently
+    // nor let it proceed unbound. This is the readiness gate's default, made explicit here.
+    onTimeout: "escalate",
+  };
+}
+
+/** One dependent epic's leading gate: the `capability` probes it must ALL satisfy (one per inbound
+ * edge / producer) and the ISO-8601 timeout bound its preflight escalation timers fire off. */
+export interface DependentGate {
+  planKey: string;
+  probes: ReadinessProbe[];
+  producers: string[];
+  probeTimeout: string;
+}
+
+/** The pure schedule derived from a validated set: the ROOTS to start immediately and the
+ * DEPENDENTS whose fan-out is gated behind their producers' capabilities. */
+export interface EpicSchedule {
+  roots: string[];
+  dependents: DependentGate[];
+}
+
+/** Pure, side-effect-free lowering of a validated DAG into a schedule (no data/engine access) — the
+ * unit-testable core of {@link lowerAdmittedSet}. Given the set's plan keys and its inter-epic edges,
+ * it partitions the epics into roots (no inbound edge → start immediately) and dependents (≥1 inbound
+ * edge → wait behind a capability gate), deriving each dependent's probe set from its inbound edges.
+ * A dependent with multiple inbound edges carries multiple probes — it must wait for ALL of them. */
+export function deriveEpicSchedule(
+  planKeys: readonly string[],
+  edges: readonly PlanDep[],
+  env: Record<string, string | undefined> = process.env,
+): EpicSchedule {
+  const inbound = new Map<string, PlanDep[]>();
+  for (const edge of edges) {
+    const list = inbound.get(edge.plan_key);
+    if (list) list.push(edge);
+    else inbound.set(edge.plan_key, [edge]);
+  }
+  const roots: string[] = [];
+  const dependents: DependentGate[] = [];
+  for (const planKey of planKeys) {
+    const edgesForKey = inbound.get(planKey);
+    if (!edgesForKey || edgesForKey.length === 0) {
+      roots.push(planKey);
+      continue;
+    }
+    const probes = edgesForKey.map(capabilityProbeForEdge);
+    // One bound governs the whole dependent's preflight timers — the LONGEST of its probes' derived
+    // timeouts, so no producer is cut short. In practice every derived probe shares the default, so
+    // this is that default; the max keeps it correct if a probe ever carries a bespoke poll budget.
+    const probeTimeout = probes
+      .map((p) => readinessTimeout(p, env))
+      .reduce((a, b) => (isoLonger(a, b) ? a : b));
+    dependents.push({ planKey, probes, producers: edgesForKey.map((e) => e.depends_on_plan_key), probeTimeout });
+  }
+  return { roots, dependents };
+}
+
+/** The result of lowering a set: which epics were started as roots vs gated dependents, and how many
+ * durable edges were materialized. Returned so the admission door can report the schedule. */
+export interface LoweringResult {
+  roots: string[];
+  dependents: { planKey: string; producers: string[] }[];
+  edgesMaterialized: number;
+}
+
+/** Lower a WHOLE admitted set (read from the S2 staging tables) into a running schedule. Reads the
+ * staged epics + edges, derives the schedule, starts roots immediately and dependents behind their
+ * capability gate, then materializes the durable `plan_deps` edges (after the consumer's `plans` row
+ * exists, so the FK holds). Idempotent end-to-end: re-running it neither double-starts an epic, nor
+ * re-seeds a gate, nor duplicates an edge. The set's membership is `planKeys` (every admitted epic,
+ * roots included) — the same list the door staged. */
+export async function lowerAdmittedSet(
+  data: DataLayer,
+  engine: EngineClient,
+  planKeys: readonly string[],
+  env: Record<string, string | undefined> = process.env,
+): Promise<LoweringResult> {
+  // Read the staged epics (for repo/base/issue) and the staged edges (the DAG) for the set.
+  const epicByKey = new Map<string, AdmittedEpic>();
+  for (const planKey of planKeys) {
+    const staged = await admittedEpics(data).get(planKey);
+    if (staged) epicByKey.set(planKey, staged);
+  }
+  const edges: PlanDep[] = [];
+  const seenEdges = new Set<string>();
+  for (const planKey of new Set(planKeys)) {
+    for (const edge of await admittedPlanDeps(data).find({ plan_key: planKey })) {
+      const id = `${edge.plan_key}\u0000${edge.depends_on_plan_key}`;
+      if (seenEdges.has(id)) continue;
+      seenEdges.add(id);
+      edges.push(edge);
+    }
+  }
+
+  const schedule = deriveEpicSchedule([...epicByKey.keys()], edges, env);
+  const gateByKey = new Map(schedule.dependents.map((d) => [d.planKey, d]));
+
+  // Start every admitted epic — roots with no probe (immediate fan-out), dependents with their
+  // seeded capability gate. `startPlan` creates the `plans` row (idempotent on an already-running
+  // plan), which the durable edge FK below then references.
+  for (const planKey of epicByKey.keys()) {
+    const staged = epicByKey.get(planKey);
+    if (!staged) continue;
+    const parsed = parseIssue(staged.issue_url) ?? parseIssue(planKey);
+    if (!parsed) continue;
+    const gate = gateByKey.get(planKey);
+    await startPlan(data, engine, parsed, staged.base_branch, {
+      readinessProbes: gate?.probes,
+      probeTimeout: gate?.probeTimeout,
+    });
+  }
+
+  // Materialize the durable edges now that every consumer's `plans` row exists. Idempotent: a
+  // re-run collapses the duplicate. Done AFTER the starts so the `plan_deps.plan_key` FK is satisfied.
+  let edgesMaterialized = 0;
+  for (const edge of edges) {
+    await recordPlanDep(data, {
+      plan_key: edge.plan_key,
+      depends_on_plan_key: edge.depends_on_plan_key,
+      package: edge.package,
+      capability_ref: edge.capability_ref,
+    });
+    edgesMaterialized += 1;
+  }
+
+  return {
+    roots: schedule.roots,
+    dependents: schedule.dependents.map((d) => ({ planKey: d.planKey, producers: d.producers })),
+    edgesMaterialized,
+  };
+}
+
+/** Compare two ISO-8601 durations of the shape `readinessTimeout` emits (`PT…`), returning true when
+ * `a` is the LONGER. Kept deliberately small: the derived probes all share one default, so this only
+ * ever breaks a tie; it parses the `PnDTnHnMnS` fields the emitter can produce and never throws. */
+function isoLonger(a: string, b: string): boolean {
+  return isoDurationSeconds(a) >= isoDurationSeconds(b);
+}
+
+/** Coarse ISO-8601 duration → seconds for the `PnDTnHnMnS` subset `msToIsoDuration` emits. Only used
+ * to pick the longer of two derived bounds; a malformed value parses as 0 rather than throwing. */
+function isoDurationSeconds(iso: string): number {
+  const m = iso.match(/^P(?:(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+(?:\.\d+)?)S)?)?$/);
+  if (!m) return 0;
+  const [, d, h, min, s] = m;
+  return Number(d ?? 0) * 86400 + Number(h ?? 0) * 3600 + Number(min ?? 0) * 60 + Number(s ?? 0);
+}

package/db/migrations/{043_user_tasks_subject_title.sql → 046_user_tasks_subject_title.sql}

@@ -18,7 +18,8 @@
 -- The backfill coalesces existing rows to `subject_key` (matching the write-time coalesce
 -- in `pollUserTasks`, which re-derives the real title in place on the next poll — a
 -- completed task's row is deleted, not migrated). Idempotent: re-running is a no-op once
--- set. Numbered after the current highest prefix on origin/main (042); the runner wraps
+-- set. Renumbered from 043 to 046 to resolve an apply-order prefix collision with
+-- 043_pr_epic_phase.sql (both landed ~concurrently on main); the runner wraps
 -- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
 ALTER TABLE user_tasks ADD COLUMN subject_title TEXT;
 UPDATE user_tasks SET subject_title = subject_key WHERE subject_title IS NULL OR trim(subject_title) = '';