@nanobpm/nano-workforce 0.91.0 → 0.92.0

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

package/operations/acknowledgeEpic.test.ts

@@ -0,0 +1,130 @@
+// Tests for the POST /app/api/actions/acknowledge-epic operation `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic — landed (`delivery=landed`) or
+// resolved-not-landed (`delivery=null`); only still-`converging` epics are rejected. It stamps
+// `acknowledged_at` via the plans gateway, which recomputes `list_bucket` to 'history' (and
+// `ack_open` to 0), dropping the resolved epic from Active into History. Unlike acknowledge-blocked
+// it completes NO user task (a resolved epic is not parked). The epic twin of acknowledge-done.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { plans } from "../app/plan.ts";
+import { noopLog } from "../test/log.ts";
+import handler from "./acknowledgeEpic.ts";
+
+// An in-memory data layer wired through the REAL plans gateway proxy, so the test exercises the
+// gateway's list_bucket/ack_open projection exactly as production does.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  const stores: Record<string, any[]> = { plans: seed };
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+        return r ? 1 : 0;
+      },
+    };
+  }
+  const app = {
+    data: { table: (n: string, pk?: string) => tbl(n, pk) },
+    log: noopLog(),
+  } as any as AppApi;
+  return { app, rows: stores.plans };
+}
+
+async function call(app: AppApi, body: unknown) {
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-epic: stamps acknowledged_at and flips list_bucket to 'history' on a landed epic", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#1", status: "done", delivery: "landed", acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (landed, unacknowledged → active).
+  await plans(app.data).update("o/r#1", { delivery: "landed" });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#1" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a still-converging epic is rejected (409) and stays Active", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2", status: "done", delivery: "converging", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#2", { delivery: "converging" });
+
+  const res = await call(app, { plan_key: "o/r#2" });
+
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  // Untouched: no premature acknowledged_at, still Active.
+  assertEquals(rows[0].acknowledged_at, null);
+  assertEquals(rows[0].list_bucket, "active");
+});
+
+test("acknowledge-epic: a resolved-not-landed epic (delivery=null) is accepted (200) and flips to History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#2b", status: "done", delivery: null, acknowledged_at: null }]);
+  // Seed the projection as the gateway would have on the last write (resolved-not-landed, unacknowledged → active).
+  await plans(app.data).update("o/r#2b", { delivery: null });
+  assertEquals(rows[0].list_bucket, "active");
+  assertEquals(rows[0].ack_open, 1);
+
+  const res = await call(app, { plan_key: "o/r#2b" });
+
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(rows[0].list_bucket, "history");
+  assertEquals(rows[0].ack_open, 0);
+});
+
+test("acknowledge-epic: a live (dispatched) epic is rejected (409)", async () => {
+  const { app } = memApp([{ plan_key: "o/r#3", status: "dispatched", delivery: null, acknowledged_at: null }]);
+  const res = await call(app, { plan_key: "o/r#3" });
+  assertEquals(res.status, 409);
+});
+
+test("acknowledge-epic: a missing plan_key → 400", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, {});
+  assertEquals(res.status, 400);
+});
+
+test("acknowledge-epic: no matching epic → 404", async () => {
+  const { app } = memApp([]);
+  const res = await call(app, { plan_key: "o/r#404" });
+  assertEquals(res.status, 404);
+});
+
+test("acknowledge-epic: idempotent — re-acknowledging a landed epic keeps it in History", async () => {
+  const { app, rows } = memApp([{ plan_key: "o/r#5", status: "done", delivery: "landed", acknowledged_at: null }]);
+  await plans(app.data).update("o/r#5", { delivery: "landed" });
+
+  assertEquals((await call(app, { plan_key: "o/r#5" })).status, 200);
+  const firstStamp = rows[0].acknowledged_at;
+  assertEquals(rows[0].list_bucket, "history");
+
+  const res2 = await call(app, { plan_key: "o/r#5" });
+  assertEquals(res2.status, 200);
+  assertEquals(rows[0].list_bucket, "history");
+  // Re-stamped (a fresh timestamp) but still resolved.
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  void firstStamp;
+});

package/operations/acknowledgeEpic.ts

@@ -0,0 +1,63 @@
+// POST /app/api/actions/acknowledge-epic → operationId `acknowledgeEpic` (issue #298).
+// The nwf UI's "Dismiss" affordance for a RESOLVED epic: an operator dismisses a `done` epic whose
+// fan-out has finished (all slice PRs reached a terminal state — whether all merged/landed or
+// resolved-not-landed) directly from the Epic / Overview pages so it drops out of the Active epic list
+// into History. It is the epic twin of `acknowledgeDone` (the feature-run tick-off) — a resolved epic
+// is NOT parked at a user task, so this op completes no user task and touches no engine/ledger: it
+// simply stamps `acknowledged_at` on the `plans` row via the plans gateway.
+//
+// The gateway (app/plan.ts) recomputes `list_bucket`/`ack_open` on that write — a landed, now-
+// acknowledged epic flips `list_bucket` to 'history' and `ack_open` to 0 — so this op NEVER hand-sets
+// a derived projection. Keyed on the row's `plan_key`. Idempotent-safe: re-acknowledging re-stamps
+// the timestamp and keeps the row in History.
+//
+// It rejects (409) an epic that is NOT yet resolved — i.e. anything the `epicIsAcknowledgeable`
+// guard refuses: a non-`done` status (`planning`/`dispatched`), or `done` but still `converging`. A
+// resolved epic is acknowledgeable whether all slices merged (`delivery=landed`) or it resolved-not-
+// landed (`delivery=null`); only a still-live or still-converging epic is refused, so those stay
+// visible in Active and can never pre-seed the tick-off.
+
+import { epicIsAcknowledgeable } from "../app/delivery.ts";
+import { plans } from "../app/plan.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgeEpic", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-epic rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "plan_key is required" } };
+  }
+
+  const planKey = str(body.plan_key);
+  if (!planKey) return { status: 400, body: { ok: false, error: "plan_key is required" } };
+
+  const table = plans(app.data);
+  const plan = await table.get(planKey);
+  if (!plan) {
+    app.log.warn("acknowledge-epic: no such plan", { planKey });
+    return { status: 404, body: { ok: false, error: "no such epic" } };
+  }
+
+  // Guard: only a RESOLVED epic (`status=done` and no longer `converging`) carries the Dismiss
+  // affordance. Acknowledging a live/converging epic would pre-seed `acknowledged_at`, so the moment
+  // it later resolved `deriveEpicBucket` would drop it straight into History, skipping the operator
+  // tick-off this op exists to require — and a converging epic must stay visible while its slices land.
+  if (!epicIsAcknowledgeable(plan.status, plan.delivery ?? null)) {
+    app.log.warn("acknowledge-epic rejected: epic is not resolved", {
+      planKey,
+      status: plan.status,
+      delivery: plan.delivery ?? null,
+    });
+    return { status: 409, body: { ok: false, error: "epic is not resolved" } };
+  }
+
+  // Stamp the dismissal. The gateway recomputes `list_bucket` (→ 'history') and `ack_open` (→ 0) from
+  // the merged row, so we never hand-set them here. Idempotent: re-acknowledging re-stamps and stays
+  // in History.
+  const now = new Date().toISOString();
+  await table.update(planKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator dismissed resolved epic", { planKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});