@nanobpm/nano-workforce 0.90.0 → 0.92.0

package/app/service.ts

@@ -33,7 +33,7 @@ import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
-import { planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
+import { backfillPlanBuckets, planReviews, plans, planTaskDeps, planTasks } from "./plan.ts";
 import { derivePromotionState, isPromotable, promotionPrBody, promotionPrTitle } from "./promotion.ts";
 import { clampNudgeMinutes, reviewWaitTimeout } from "./reviewWait.ts";
 import { trialMergeAudits } from "./trialMerge.ts";
@@ -1626,6 +1626,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: FEATURE_ESCALATION_ELEMENT,
               subjectType: "feature",
               subjectKey: run.feature_key,
+              subjectTitle: run.title,
               subjectUrl: run.issue_url,
               question: run.escalation_question,
               processKey: run.process_key,
@@ -1642,6 +1643,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: FEATURE_BLOCKED_ELEMENT,
               subjectType: "feature",
               subjectKey: run.feature_key,
+              subjectTitle: run.title,
               subjectUrl: run.issue_url,
               question: run.delivery_label,
               processKey: run.process_key,
@@ -1680,6 +1682,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
                 elementId: PLAN_REVIEW_ELEMENT,
                 subjectType: "plan",
                 subjectKey: plan.plan_key,
+                subjectTitle: plan.title,
                 subjectUrl: plan.issue_url,
                 question,
                 processKey: plan.process_key,
@@ -1696,6 +1699,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
                 elementId: TRIAL_MERGE_ELEMENT,
                 subjectType: "plan",
                 subjectKey: plan.plan_key,
+                subjectTitle: plan.title,
                 subjectUrl: plan.issue_url,
                 question,
                 processKey: plan.process_key,
@@ -1735,6 +1739,7 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
               elementId: t.elementId,
               subjectType: "pr",
               subjectKey: pr.pr_key,
+              subjectTitle: pr.title,
               subjectUrl: pr.url,
               question,
               processKey: pr.process_key,
@@ -1768,6 +1773,11 @@ export async function pollUserTasks(data: DataLayer, engine: EngineClient) {
  * on every poll. */
 let featureStagesBackfilled = false;
 
+/** One-shot guard so the epic-bucket backfill (`backfillPlanBuckets`, #298) runs at most once per
+ * process, on the first `pollOnce` — re-projecting pre-migration-042 `plans` rows whose
+ * `list_bucket` is still NULL. The gateway keeps every future write fresh; idempotent regardless. */
+let planBucketsBackfilled = false;
+
 export async function pollOnce(
   data: DataLayer,
   engine: EngineClient,
@@ -1784,6 +1794,13 @@ export async function pollOnce(
     await backfillFeatureStages(data);
     featureStagesBackfilled = true;
   }
+  // One-shot: re-project any pre-#298 `plans` rows whose `list_bucket` is still NULL, so a legacy
+  // epic buckets correctly into Active/History from the first pass. Guard armed only after success so
+  // a transient failure retries next pass (mirrors the feature-stage backfill above).
+  if (!planBucketsBackfilled) {
+    await backfillPlanBuckets(data);
+    planBucketsBackfilled = true;
+  }
   await pollReviews(data, engine, token);
   await pollMerges(data, engine, token);
   await pollDelivery(data);

package/app/userTasks.test.ts

@@ -41,6 +41,7 @@ test("buildUserTaskRow: a plan-review task becomes a labelled row with its findi
     kind_label: "Plan review",
     subject_type: "plan",
     subject_key: "o/r#1",
+    subject_title: "o/r#1",
     subject_url: "https://github.com/o/r/issues/1",
     question: "cap reached: revise scope",
     process_key: "pk-1",
@@ -80,6 +81,28 @@ test("buildUserTaskRow: a blank userTaskKey or subjectKey yields null", () => {
   );
 });
 
+test("buildUserTaskRow: subject_title carries the subject title, trimmed, and coalesces to subject_key when absent/blank (issue #308)", () => {
+  const titled = buildUserTaskRow(
+    {
+      userTaskKey: "ut-t1",
+      elementId: PLAN_REVIEW_ELEMENT,
+      subjectType: "plan",
+      subjectKey: "o/r#1",
+      subjectTitle: "  Add the widget  ",
+    },
+    AT,
+  );
+  assertEquals(titled?.subject_title, "Add the widget");
+
+  for (const subjectTitle of [undefined, null, "   "]) {
+    const row = buildUserTaskRow(
+      { userTaskKey: "ut-t2", elementId: PLAN_REVIEW_ELEMENT, subjectType: "plan", subjectKey: "o/r#2", subjectTitle },
+      AT,
+    );
+    assertEquals(row?.subject_title, "o/r#2");
+  }
+});
+
 function row(key: string, extra: Partial<UserTaskRow> = {}): UserTaskRow {
   return {
     user_task_key: key,
@@ -87,6 +110,7 @@ function row(key: string, extra: Partial<UserTaskRow> = {}): UserTaskRow {
     kind_label: "Plan review",
     subject_type: "plan",
     subject_key: "o/r#1",
+    subject_title: "o/r#1",
     subject_url: null,
     question: null,
     process_key: null,

package/app/userTasks.ts

@@ -51,6 +51,10 @@ export interface UserTaskRow {
   kind_label: string;
   subject_type: string;
   subject_key: string;
+  /** The subject's human-readable title (`feature_runs`/`plans`/`pull_requests`.`title`), derived by
+   *  `pollUserTasks` from the subject row keyed on `subject_key` and coalesced to `subject_key` at
+   *  build time so the title-led grids never render a blank primary line (issue #308). */
+  subject_title: string;
   subject_url: string | null;
   question: string | null;
   process_key: string | null;
@@ -78,6 +82,10 @@ export interface UserTaskContext {
   elementId: string;
   subjectType: "feature" | "plan" | "pr";
   subjectKey: string;
+  /** The subject's human-readable title from its own row (`feature_runs`/`plans`/`pull_requests`.
+   *  `title`). Optional/blank tolerated — `buildUserTaskRow` coalesces it to `subjectKey` so the
+   *  projected `subject_title` is never blank. */
+  subjectTitle?: string | null;
   subjectUrl?: string | null;
   question?: string | null;
   processKey?: string | null;
@@ -93,12 +101,14 @@ export function buildUserTaskRow(ctx: UserTaskContext, at: string = now()): User
   const kindLabel = USER_TASK_KIND_LABELS[ctx.elementId];
   if (!userTaskKey || !subjectKey || !kindLabel) return null;
   const question = typeof ctx.question === "string" && ctx.question.trim() ? ctx.question.trim() : null;
+  const subjectTitle = typeof ctx.subjectTitle === "string" && ctx.subjectTitle.trim() ? ctx.subjectTitle.trim() : subjectKey;
   return {
     user_task_key: userTaskKey,
     element_id: ctx.elementId,
     kind_label: kindLabel,
     subject_type: ctx.subjectType,
     subject_key: subjectKey,
+    subject_title: subjectTitle,
     subject_url: ctx.subjectUrl ?? null,
     question,
     process_key: ctx.processKey ?? null,
@@ -124,6 +134,7 @@ function sameRow(a: UserTaskRow, b: UserTaskRow): boolean {
     a.kind_label === b.kind_label &&
     a.subject_type === b.subject_type &&
     a.subject_key === b.subject_key &&
+    a.subject_title === b.subject_title &&
     a.subject_url === b.subject_url &&
     a.question === b.question &&
     a.process_key === b.process_key

package/db/migrations/043_user_tasks_subject_title.sql

@@ -0,0 +1,24 @@
+-- Surface the subject's human-readable title as the primary identity on the Tasks
+-- grids (issue #308), mirroring the Features list. Every `user_tasks` row was keyed
+-- only by `subject_key` (`owner/repo#N`) — meaningful while you remember the number,
+-- opaque hours later. The Features list already leads with `{{title}}` and shows the
+-- key as a subtitle; the Tasks grids could only show the bare key.
+--
+-- The title is DERIVED (no new fetch): each escalation's subject already persists a
+-- title in a surviving table keyed by `subject_key` — `feature_runs.title`,
+-- `plans.title`, `pull_requests.title`. `pollUserTasks` reads it from the subject row
+-- already in scope this pass and coalesces to `subject_key` at write time so the
+-- column is ALWAYS non-blank — the grid's `{{subject_title}}` template then needs no
+-- fallback and a missing subject title still shows a usable identity.
+--
+-- Forward-only, additive (expand): nullable with no default, then backfilled in the
+-- same migration so the column is non-blank immediately — pre-#308 rows would otherwise
+-- grandfather in as NULL and the grid's `{{subject_title}}` primary line would render a
+-- blank/"null" identity for the window between deploy and the first `pollUserTasks` pass.
+-- 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
+-- 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) = '';

package/db/migrations/044_plan_list_bucket.sql

@@ -0,0 +1,32 @@
+-- 044_plan_list_bucket.sql — issue #298: bucket EPICS on the derived `delivery` rollup, not raw
+-- `plan.status`, so a `done` epic whose slice PRs are still CONVERGING — or one that has fully LANDED
+-- but still needs its integration→main promotion PR — does NOT silently vanish from the Active epic
+-- lists the instant `status = done`. Mirrors the feature-run Active/History tick-off partition
+-- (038/039 `feature_runs`): reify the partition as a derived, write-time-projected column so the
+-- declarative epic/overview page tabs can filter with only stored `{"field":…}` `in` clauses (the
+-- dataGrid page DSL has no OR / IS NULL), and give epics the same operator "Dismiss" affordance
+-- feature runs already have.
+--
+-- Columns (all maintained by the `plans` gateway — app/plan.ts — from the pure `deriveEpicBucket` /
+-- `epicIsAcknowledgeable` helpers in app/delivery.ts on every write, never hand-derived in SQL, the
+-- page, or a poller):
+--   • acknowledged_at — NULL until an operator dismisses a RESOLVED epic (acknowledge-epic) — landed
+--                       or resolved-not-landed (`delivery=null`); only still-`converging` epics are
+--                       rejected. The twin of feature_runs.acknowledged_at (039).
+--   • list_bucket     — 'active' | 'history': deriveEpicBucket(status, delivery, acknowledged_at).
+--                       Active = live epics (planning/dispatched) + `done` epics not yet acknowledged
+--                       (still converging, landed-but-unpromoted, or resolved-not-landed); History =
+--                       acknowledged `done` epics and terminal failed/abandoned epics.
+--   • ack_open        — 1 | 0: 1 iff the epic is a RESOLVED (`done`, not `converging`) but
+--                       unacknowledged epic — the Active states that carry the Dismiss affordance — so
+--                       the page's `showWhenField` gates the button precisely. Mirrors
+--                       feature_runs.escalation_open (040).
+--
+-- Forward-only, additive (expand): all nullable with no default, so pre-#298 rows grandfather in as
+-- NULL and never gate control flow. `backfillPlanBuckets` (app/plan.ts) stamps legacy rows once at
+-- boot, and the gateway keeps every future write fresh. Numbered after the current highest prefix on
+-- origin/main (041); the runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+ALTER TABLE plans ADD COLUMN acknowledged_at TEXT;
+ALTER TABLE plans ADD COLUMN list_bucket TEXT;
+ALTER TABLE plans ADD COLUMN ack_open INTEGER;

package/db/migrations/045_epic_set_admission_staging.sql

@@ -0,0 +1,56 @@
+-- 045_epic_set_admission_staging.sql — issue #292 slice S2: durable ADMISSION STAGING for the
+-- set/batch door (`startEpicSet`).
+--
+-- S2 is the admission DOOR + DAG validator only; it deliberately does NOT start any epic and does
+-- NOT materialize the durable plan graph. Slice S3 (planner lowering: schedule roots, seed the
+-- capability gate, bind the resolved version) is the slice that actually CREATES `plans` rows and
+-- their `plan_deps` edges — so S3, not S2, is the correct owner of both.
+--
+-- That split leaves S2 needing to persist WHAT it admitted so a crash between admission and lowering
+-- does not lose the set. It cannot write `plan_deps` for that: `plan_deps.plan_key REFERENCES
+-- plans(plan_key)` (041), but S2 has not created any `plans` row, so a first-time set submission
+-- would FK-fail (500). Nor should it pre-create a `plans` row — a non-terminal `plans` row reads as
+-- `alreadyRunning` to the canonical `startPlan`, which would wedge S3 from ever starting it.
+--
+-- So S2 stages into its OWN, FK-FREE structure here, and S3 reads it during lowering to materialize
+-- `plans` + `plan_deps` when it schedules roots (where the FK is satisfied by construction). Neither
+-- staging table references `plans` — that is the whole point: the staging is writable BEFORE any
+-- plan graph exists.
+--
+--   • admitted_epics — one row per admitted epic in the set (INCLUDING roots, which carry no edge).
+--     `plan_key` is the epic's canonical key; the rest is what S3 needs to materialize the `plans`
+--     row (repo, issue number/url, the normalized integration base branch). PRIMARY KEY (plan_key)
+--     makes a re-submitted set idempotent (one staged row per epic).
+--   • admitted_plan_deps — the FK-FREE staging twin of `plan_deps`: one row per validated inter-epic
+--     edge (`plan_key` waits for `depends_on_plan_key`, gated by { package, capability_ref }).
+--     Constraints MIRROR plan_deps EXCEPT the FK: PRIMARY KEY (plan_key, depends_on_plan_key) so a
+--     re-submitted set cannot duplicate an edge, CHECK (plan_key <> depends_on_plan_key) so no
+--     self-edge — but NO `REFERENCES plans(...)`, since neither endpoint's plan row exists yet. The
+--     set validator (S2) is what guarantees every endpoint names a submitted epic.
+--
+-- Numbered after the current highest prefix on origin/main (042_plan_promotion.sql) — the branch
+-- forks at 041 while main advanced to 042, so this MUST be 043 to avoid a merge-time prefix
+-- collision. The runner wraps each file in its own transaction, so this file must NOT contain
+-- BEGIN/COMMIT.
+
+CREATE TABLE admitted_epics (
+  plan_key     TEXT NOT NULL PRIMARY KEY,  -- the admitted epic's canonical key (owner/repo#123)
+  repo         TEXT NOT NULL,              -- owner/repo the epic issue lives in
+  issue_number INTEGER NOT NULL,           -- the epic issue number
+  issue_url    TEXT NOT NULL,              -- canonical issue URL (for S3 to materialize the plans row)
+  base_branch  TEXT NOT NULL,              -- normalized integration base branch admitPlan resolved
+  created_at   TEXT NOT NULL
+);
+
+CREATE TABLE admitted_plan_deps (
+  plan_key            TEXT NOT NULL,  -- dependent/consumer epic that waits (FK-free: plans may not exist yet)
+  depends_on_plan_key TEXT NOT NULL,  -- producer epic it waits for
+  package             TEXT NOT NULL,  -- producer's published package name
+  capability_ref      TEXT NOT NULL,  -- producer epic issue handle → pkg@version
+  created_at          TEXT NOT NULL,
+  PRIMARY KEY (plan_key, depends_on_plan_key),
+  CHECK (plan_key <> depends_on_plan_key)
+);
+
+CREATE INDEX idx_admitted_plan_deps_plan ON admitted_plan_deps(plan_key);
+CREATE INDEX idx_admitted_plan_deps_producer ON admitted_plan_deps(depends_on_plan_key);

package/e2e/support/engine-client.ts

@@ -1,17 +1,33 @@
 import type { EngineClient } from "@nanobpm/urban";
 import type { TestApp } from "@nanobpm/urban-testkit";
 
-// urban 0.49.0 (ADR 0062) added `EngineClient.getForm`, but the published
-// @nanobpm/urban-testkit (0.4.0) predates it, so its `WasmEngineClient` neither
-// declares nor implements the method. These hermetic e2e flows drive user-task
-// completion directly (`completeUserTask`) and never resolve a form schema, so we
-// complete the contract with a null-returning `getForm` — the documented "no
-// matching form" path — until a testkit release catches up with urban's engine
-// seam. Scoped to the test harness; production adapters implement `getForm` for real.
+// `@nanobpm/urban-testkit`'s `WasmEngineClient` has historically lagged urban's `EngineClient`
+// interface: a method lands on the real seam a release or two before the testkit fake grows it. Both
+// guards below defensively COMPLETE the contract for any method the *installed* testkit hasn't
+// implemented yet — each is an idempotent `if (typeof … !== "function")`, so it no-ops the moment a
+// testkit release ships the real method (no version pins to drift). Scoped to the test harness;
+// production adapters (`SdkEngineClient`) implement both for real.
+//
+//  - `getForm` (urban 0.49.0, ADR 0062): the original instance of this lag. Now implemented by the
+//    currently pinned testkit, so this guard is a no-op there; kept as defence against version skew.
+//    These hermetic flows drive completion directly and never resolve a form schema, so the fallback
+//    returns `null` — the documented "no matching form" path.
+//  - `openUserTasks` (issue #294 moved the pollers onto it): the CURRENT gap — the pinned testkit has
+//    `searchUserTasks` but not the open-task-scoped `openUserTasks`, so a poller call throws
+//    `not a function` (swallowed by the poller's try/catch) and the read-model denormalisation
+//    silently no-ops. Polyfill it as `searchUserTasks({ state: "CREATED" })` — byte-for-byte what
+//    urban's real `SdkEngineClient.openUserTasks` does, so the two cannot drift. Fix: nano-workforce
+//    #309; categorical (testkit) fix upstream in nanobpm/nano-ide#341.
 export function asEngineClient(engine: TestApp["engine"]): EngineClient {
-  const e = engine as unknown as EngineClient & { getForm?: EngineClient["getForm"] };
+  const e = engine as unknown as EngineClient & {
+    getForm?: EngineClient["getForm"];
+    openUserTasks?: EngineClient["openUserTasks"];
+  };
   if (typeof e.getForm !== "function") {
     e.getForm = async () => null;
   }
+  if (typeof e.openUserTasks !== "function") {
+    e.openUserTasks = (filter) => e.searchUserTasks({ ...filter, state: "CREATED" });
+  }
   return e;
 }

package/openapi.yaml

@@ -845,6 +845,159 @@ components:
         alreadyRunning:
           type: boolean
           description: True when a non-terminal feature run for this issue already exists; no new instance was started.
+    EpicSetStart:
+      description: >-
+        The set/batch admission request body (issue #292, slice S2). Submits a SET of epics plus the
+        inter-epic dependency edges between them. `epics` is admitted all-or-nothing through the same
+        `admitPlan` gate as the single-issue door; `deps` declares that a `consumer` epic waits for a
+        `producer` epic's published `{ package, capabilityRef }` capability. Every edge must connect
+        two epics named in `epics`, and the edge set must be an acyclic DAG — otherwise the whole set
+        is rejected with a 4xx and nothing is persisted.
+      type: object
+      additionalProperties: false
+      required:
+        - epics
+      properties:
+        epics:
+          type: array
+          minItems: 1
+          description: The epics to admit as one set. Each is admitted through the `admitPlan` gate.
+          items:
+            $ref: "#/components/schemas/EpicSetMember"
+        deps:
+          type: array
+          description: >-
+            The inter-epic dependency edges. Each declares `consumer` waits for `producer` to publish
+            the `{ package, capabilityRef }` capability. Both endpoints must name epics in `epics`.
+            Omit or pass `[]` for a set of independent (root) epics.
+          items:
+            $ref: "#/components/schemas/EpicSetDep"
+    EpicSetMember:
+      description: >-
+        One epic in a submitted set. Names the target issue by EXACTLY ONE of `issue`
+        (`owner/repo#123`) or `url` (a bare issue URL), plus a REQUIRED `baseBranch` and the optional
+        admission acknowledgements — the same per-epic admission inputs as `PlanStart`.
+      oneOf:
+        - $ref: "#/components/schemas/EpicSetMemberByIssue"
+        - $ref: "#/components/schemas/EpicSetMemberByUrl"
+    EpicSetMemberByIssue:
+      type: object
+      additionalProperties: false
+      required:
+        - issue
+        - baseBranch
+      properties:
+        issue:
+          type: string
+          description: "Issue reference: owner/repo#123."
+        baseBranch:
+          type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: >-
+            REQUIRED integration branch this epic branches off and opens its PRs against, admitted
+            through the same ADR 0003 policy as the single-issue door. See `PlanStartByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: Opt in to sharing a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
+          description: Acknowledge that `baseBranch` names the repository default branch. See `PlanStartByIssue.confirmDefaultBase`.
+    EpicSetMemberByUrl:
+      type: object
+      additionalProperties: false
+      required:
+        - url
+        - baseBranch
+      properties:
+        url:
+          type: string
+          description: A bare issue URL, when no `owner/repo#123` reference is supplied.
+        baseBranch:
+          type: string
+          minLength: 1
+          maxLength: 255
+          pattern: '\S'
+          description: REQUIRED integration branch this epic branches off. See `EpicSetMemberByIssue.baseBranch`.
+        allowSharedBase:
+          type: boolean
+          description: Share a custom integration base with another active epic. See `PlanStartByIssue.allowSharedBase`.
+        confirmDefaultBase:
+          type: boolean
+          description: Acknowledge landing on the default branch. See `PlanStartByIssue.confirmDefaultBase`.
+    EpicSetDep:
+      description: >-
+        One inter-epic dependency edge: the `consumer` epic waits for the `producer` epic to publish
+        the `{ package, capabilityRef }` capability. `consumer`/`producer` are epic references
+        (`owner/repo#123` or an issue URL) that MUST both appear in the set's `epics`.
+      type: object
+      additionalProperties: false
+      required:
+        - consumer
+        - producer
+        - package
+        - capabilityRef
+      properties:
+        consumer:
+          type: string
+          description: The dependent epic (waits). An `owner/repo#123` reference or issue URL in the set.
+        producer:
+          type: string
+          description: The producer epic it waits for. An `owner/repo#123` reference or issue URL in the set.
+        package:
+          type: string
+          minLength: 1
+          description: The producer epic's published package name — the capability probe's target (S3).
+        capabilityRef:
+          type: string
+          minLength: 1
+          description: The producer epic's issue handle, used to resolve which published pkg@version first carries the capability (S3).
+    StartEpicSetResult:
+      description: The result of a successful set admission — the epics admitted and the edges staged (FK-free in `admitted_plan_deps`) for S3 to materialize.
+      type: object
+      required:
+        - epics
+        - roots
+        - edges
+      properties:
+        epics:
+          type: array
+          description: Every epic admitted, with its normalized base branch.
+          items:
+            type: object
+            required:
+              - planKey
+              - baseBranch
+            properties:
+              planKey:
+                type: string
+              baseBranch:
+                type: string
+        roots:
+          type: array
+          description: The plan keys of epics with NO inbound edge — the roots S3 starts immediately.
+          items:
+            type: string
+        edges:
+          type: array
+          description: The inter-epic edges staged FK-free into `admitted_plan_deps` for S3 to materialize into `plan_deps` (endpoints resolved to plan keys).
+          items:
+            type: object
+            required:
+              - consumer
+              - producer
+              - package
+              - capabilityRef
+            properties:
+              consumer:
+                type: string
+              producer:
+                type: string
+              package:
+                type: string
+              capabilityRef:
+                type: string
     ConvergenceStart:
       description: The start-convergence request body. Names the target PR by EXACTLY ONE of `pr`
         (an `owner/repo#123` reference) or `url` (a bare PR URL) — never both, never neither — with
@@ -1620,6 +1773,47 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /actions/start/epic-set:
+    post:
+      operationId: startEpicSet
+      summary: Admit a SET of epics plus their inter-epic dependency edges in one all-or-nothing call (issue #292).
+      description: >-
+        The set/batch admission door (slice S2). Validates the WHOLE submission before persisting
+        anything: each epic passes the same `admitPlan` gate as the single-issue door, every edge must
+        connect two epics in the submitted set, and the edge set must be an acyclic DAG. A malformed
+        set fails as one clean 4xx at the offending epic/edge with nothing half-started — no edge is
+        persisted. On success the admitted epics and validated edges are staged FK-free into
+        `admitted_epics` / `admitted_plan_deps`; materializing them into `plans` / `plan_deps` and
+        scheduling/lowering (starting roots, seeding the capability readiness-gate, version binding)
+        is a later slice (S3).
+        Idempotent on the set: re-submitting the identical set records no duplicate edge.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/EpicSetStart"
+      responses:
+        "202":
+          description: The whole set validated; every epic was admitted and every edge staged FK-free (in `admitted_plan_deps`) for S3 to materialize.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/StartEpicSetResult"
+        "400":
+          description: >-
+            The set is malformed — an unparseable epic/edge reference, a rejected base branch, an edge
+            naming an epic outside the set, or a dependency cycle.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
+        "409":
+          description: An epic's base branch is already in use by another active epic (shared-base guard).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /actions/start/feature:
     post:
       operationId: startFeature
@@ -1898,6 +2092,57 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-epic:
+    post:
+      operationId: acknowledgeEpic
+      summary: "Dismiss a RESOLVED epic (issue #298). Stamps `acknowledged_at` on the `plans` row so
+        the gateway recomputes its `list_bucket` to 'history' (and `ack_open` to 0), dropping the
+        resolved epic out of the Active epic list into History. The epic twin of acknowledge-done, but
+        a resolved epic is not parked at a user task, so this completes no user task and only writes the
+        row. Keyed on the epic's `plan_key`. Rejects (409) an epic that is not yet resolved (still
+        `planning`/`dispatched`, or `done` but still `converging`), so a converging epic stays visible
+        in Active. Idempotent-safe (re-acknowledging keeps it in History)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - plan_key
+              properties:
+                plan_key:
+                  type: string
+                  minLength: 1
+                  description: The epic's key (plans.plan_key, `<owner>/<repo>#<n>`).
+      responses:
+        "200":
+          description: The resolved epic was acknowledged and moved to History. Applies to any
+            resolved epic — whether all slices merged (`delivery=landed`) or it resolved-not-landed
+            (`delivery=null`), not only landed epics.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field (plan_key) was missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No epic matches the plan_key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "409":
+          description: The epic is not yet resolved (still planning/dispatched, or converging), so it cannot be dismissed yet.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation