@nanobpm/nano-workforce 0.166.0 → 0.167.0

package/db/migrations/098_delivery_graph_units_acknowledged_at.sql

@@ -0,0 +1,63 @@
+-- Delivery Graphs: carry the new `acknowledged_at` dismissal stamp (095) through the `delivery_units`
+-- aggregate (issue #641). Migration 095 added `acknowledged_at` to the base `delivery_graph_runs`
+-- table, but its projection onto the ADR "declare-once" `delivery_units` aggregate (088-091) predates
+-- the column: the delivery-graph sync triggers (089) never copied it and the `delivery_graph_runs__units`
+-- compat VIEW (091) never re-exported it. That broke the aggregate's compat-view parity invariant
+-- (`delivery_graph_runs__units` must be byte-identical to `delivery_graph_runs`), and — since the
+-- aggregate is the S9 unified store the feature/epic surfaces already read `acknowledged_at`/`list_bucket`
+-- from — left the delivery-graph unit rows without the dismissal stamp the other kinds carry.
+--
+-- This migration supersedes the two delivery-graph WRITE triggers (INSERT/UPDATE) to also project
+-- `NEW.acknowledged_at`, re-creates the `delivery_graph_runs__units` compat VIEW to re-export it, and
+-- backfills the stamp onto the existing aggregate rows (095's backfill fired the OLD trigger, which
+-- dropped `acknowledged_at`, so the aggregate must be re-synced from the base once here). The feature
+-- and epic triggers/views already project `acknowledged_at` (089/091) and are untouched; the DELETE
+-- trigger is column-agnostic and is left as-is.
+--
+-- Migrations are forward-only and immutable once merged, so 089/091 are NOT edited — the triggers/VIEW
+-- are DROPped and re-created here (numbered after 097). The runner wraps each file in its own
+-- transaction — no BEGIN/COMMIT.
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ai;
+CREATE TRIGGER delivery_graph_runs__du_ai AFTER INSERT ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, acknowledged_at, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.acknowledged_at, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_au;
+CREATE TRIGGER delivery_graph_runs__du_au AFTER UPDATE ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, acknowledged_at, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.acknowledged_at, NEW.created_at, NEW.updated_at);
+END;
+
+DROP VIEW IF EXISTS delivery_graph_runs__units;
+CREATE VIEW delivery_graph_runs__units AS
+SELECT
+  du.legacy_key AS run_key,
+  du.process_key AS process_key,
+  du.process_definition_id AS process_definition_id,
+  du.digest AS digest,
+  du.status AS status,
+  du.side_effecting AS side_effecting,
+  du.node_count AS node_count,
+  du.human_node_count AS human_node_count,
+  du.side_effect_count AS side_effect_count,
+  du.title AS title,
+  du.phase AS phase,
+  du.phase_node_id AS phase_node_id,
+  du.human_labels AS human_labels,
+  du.acknowledged_at AS acknowledged_at,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';
+
+-- Re-sync the stamp onto the existing aggregate rows (095's backfill fired the OLD, column-dropping
+-- trigger). Keyed by the aggregate's `legacy_key` = the run's `run_key`.
+UPDATE delivery_units
+   SET acknowledged_at = (
+     SELECT d.acknowledged_at FROM delivery_graph_runs d WHERE d.run_key = delivery_units.legacy_key
+   )
+ WHERE kind = 'delivery-graph';

package/openapi.yaml

@@ -5436,6 +5436,104 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-pr:
+    post:
+      operationId: acknowledgePr
+      summary: "Dismiss a TERMINAL pull request (issue #641). Stamps `acknowledged_at` on the
+        `pull_requests` row so the `pull_requests_read_model` VIEW recomputes its `list_bucket` to
+        'history' (and `ack_open` to 0), dropping the finished PR out of the Active convergence list
+        into History. The PR twin of acknowledge-done/acknowledge-epic: a PR is not parked at a user
+        task, so this completes no user task and touches no engine/ledger — it only stamps the row.
+        Keyed on the PR's `pr_key`. Rejects (409) a PR that is not yet terminal (still converging), so a
+        live PR stays visible in Active. Idempotent-safe (re-acknowledging keeps it in History)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - pr_key
+              properties:
+                pr_key:
+                  type: string
+                  minLength: 1
+                  description: The pull request's key (pull_requests.pr_key).
+      responses:
+        "200":
+          description: The terminal PR was acknowledged and moved to History.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field (pr_key) was missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No pull request matches the pr_key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "409":
+          description: The pull request is not terminal, so it cannot be dismissed yet.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+  /actions/acknowledge-delivery-graph:
+    post:
+      operationId: acknowledgeDeliveryGraph
+      summary: "Dismiss a TERMINAL delivery-graph run (issue #641). Stamps `acknowledged_at` on the
+        `delivery_graph_runs` row so the `delivery_graph_read_model` VIEW recomputes its `list_bucket`
+        to 'history' (and `ack_open` to 0), dropping the finished run out of the Active delivery-graph
+        list into History. The delivery-graph twin of acknowledge-done/acknowledge-epic/acknowledge-pr:
+        it completes no user task and touches no engine/ledger — it only stamps the row. Keyed on the
+        run's `run_key`. Rejects (409) a run that is not yet terminal (still awaiting-approval/running),
+        so a live run stays visible in Active. Idempotent-safe (re-acknowledging keeps it in History)."
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              type: object
+              additionalProperties: false
+              required:
+                - run_key
+              properties:
+                run_key:
+                  type: string
+                  minLength: 1
+                  description: The delivery-graph run's key (delivery_graph_runs.run_key).
+      responses:
+        "200":
+          description: The terminal delivery-graph run was acknowledged and moved to History.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "400":
+          description: A required field (run_key) was missing or invalid.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "404":
+          description: No delivery-graph run matches the run_key.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
+        "409":
+          description: The delivery-graph run is not terminal, so it cannot be dismissed yet.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/MessageResult"
   /hooks/agent-complete:
     post:
       operationId: agentCompleteEscalation

package/operations/acknowledgeDeliveryGraph.test.ts

@@ -0,0 +1,93 @@
+// Tests for the POST /app/api/actions/acknowledge-delivery-graph operation `acknowledgeDeliveryGraph`
+// (issue #641). The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL delivery-graph run. It stamps
+// `acknowledged_at`, which the `delivery_graph_read_model` VIEW (096) derives into `list_bucket` =
+// 'history' and `ack_open` = 0, dropping the finished run from the Active list into History. The
+// delivery-graph twin of acknowledge-done / acknowledge-epic / acknowledge-pr.
+//
+// The op's only write is the `acknowledged_at` (+ `updated_at`) stamp, gated on the base `status`
+// belonging to the terminal tier (`DELIVERY_GRAPH_TERMINAL_STATUSES`). These tests seed an in-memory
+// `delivery_graph_runs` store and assert the 400/404/409/200 gate + the stamp; the bucket derivation
+// itself is proven in app/deliveryGraphReadModel.test.ts.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { DELIVERY_GRAPH_TERMINAL_STATUSES } from "../app/deliveryGraphRun.ts";
+import handler from "./acknowledgeDeliveryGraph.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only fake data layer over dynamic row shapes.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only store.
+  const stores: Record<string, any[]> = { delivery_graph_runs: seed };
+  function tbl(name: string, pk = "id") {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: test-only.
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: test-only.
+      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 unknown as AppApi;
+  return { app, rows: stores.delivery_graph_runs };
+}
+
+async function call(app: AppApi, body: unknown) {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only op invocation.
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-delivery-graph: stamps acknowledged_at on a terminal run and returns 200", async () => {
+  const { app, rows } = memApp([{ run_key: "run-1", status: "done", acknowledged_at: null }]);
+  const res = await call(app, { run_key: "run-1" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(typeof rows[0].updated_at, "string");
+});
+
+test("acknowledge-delivery-graph: every terminal status is dismissable", async () => {
+  for (const status of DELIVERY_GRAPH_TERMINAL_STATUSES) {
+    const { app, rows } = memApp([{ run_key: "run-1", status, acknowledged_at: null }]);
+    const res = await call(app, { run_key: "run-1" });
+    assertEquals(res.status, 200, `status ${status} must be dismissable`);
+    assertEquals(typeof rows[0].acknowledged_at, "string");
+  }
+});
+
+test("acknowledge-delivery-graph: a live (running) run is rejected (409) and stays unstamped", async () => {
+  const { app, rows } = memApp([{ run_key: "run-2", status: "running", acknowledged_at: null }]);
+  const res = await call(app, { run_key: "run-2" });
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  assertEquals(rows[0].acknowledged_at, null);
+});
+
+test("acknowledge-delivery-graph: a missing run_key → 400", async () => {
+  const { app } = memApp([]);
+  assertEquals((await call(app, {})).status, 400);
+  assertEquals((await call(app, { run_key: "  " })).status, 400);
+});
+
+test("acknowledge-delivery-graph: no matching run → 404", async () => {
+  const { app } = memApp([]);
+  assertEquals((await call(app, { run_key: "run-404" })).status, 404);
+});
+
+test("acknowledge-delivery-graph: idempotent — re-acknowledging a terminal run re-stamps and returns 200", async () => {
+  const { app, rows } = memApp([{ run_key: "run-5", status: "failed", acknowledged_at: null }]);
+  assertEquals((await call(app, { run_key: "run-5" })).status, 200);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals((await call(app, { run_key: "run-5" })).status, 200);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+});

package/operations/acknowledgeDeliveryGraph.ts

@@ -0,0 +1,58 @@
+// POST /app/api/actions/acknowledge-delivery-graph → operationId `acknowledgeDeliveryGraph` (issue #641).
+// The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL delivery-graph run: an operator dismisses a
+// finished run (done / failed / abandoned) directly from the Overview "Active Delivery Graphs" or
+// delivery-graphs "In-flight delivery graphs" grid so it drops out of the Active list into History. It
+// is the delivery-graph twin of `acknowledgeDone` / `acknowledgeEpic` / `acknowledgePr` — a terminal
+// run 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 `delivery_graph_runs` row.
+//
+// `list_bucket`/`ack_open` are DERIVED by the `delivery_graph_read_model` VIEW (096, issue #641) from
+// the terminal-folded `derived_status` + `acknowledged_at` — a terminal, now-acknowledged run reads
+// `list_bucket` = 'history' and `ack_open` = 0 — so this op NEVER writes a derived projection. Keyed on
+// the row's `run_key`. Idempotent-safe: re-acknowledging re-stamps the timestamp and keeps it in
+// History.
+//
+// It rejects (409) a run that is NOT terminal (still awaiting-approval/running), so it can never pre-
+// seed the tick-off on a live run. The terminal check reads the base `status`: the delivery-graph
+// poller (app/deliveryGraphRun.ts) persists the terminal outcome to base `status` (done/failed/
+// abandoned), and the reconciler's `onTerminated` edge covers an out-of-band terminate.
+
+import { DELIVERY_GRAPH_TERMINAL_STATUSES, deliveryGraphRuns } from "../app/deliveryGraphRun.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgeDeliveryGraph", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-delivery-graph rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "run_key is required" } };
+  }
+
+  const runKey = str(body.run_key);
+  if (!runKey) return { status: 400, body: { ok: false, error: "run_key is required" } };
+
+  const table = deliveryGraphRuns(app.data);
+  const run = await table.get(runKey);
+  if (!run) {
+    app.log.warn("acknowledge-delivery-graph: no such run", { runKey });
+    return { status: 404, body: { ok: false, error: "no such delivery-graph run" } };
+  }
+
+  // Guard: only a TERMINAL run (a `DELIVERY_GRAPH_TERMINAL_STATUSES` status — the same set the read
+  // model's `list_bucket` folds to History) carries the Dismiss affordance. Acknowledging a live run
+  // would pre-seed `acknowledged_at`, so the moment it later settled the VIEW would drop it straight
+  // into History, skipping the operator tick-off this op exists to require.
+  if (!DELIVERY_GRAPH_TERMINAL_STATUSES.includes(run.status)) {
+    app.log.warn("acknowledge-delivery-graph rejected: run is not terminal", { runKey, status: run.status });
+    return { status: 409, body: { ok: false, error: "delivery-graph run is not terminal" } };
+  }
+
+  // Stamp the dismissal. `list_bucket` (→ 'history') and `ack_open` (→ 0) are derived by the
+  // `delivery_graph_read_model` VIEW from the terminal, now-acknowledged 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(runKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator dismissed terminal delivery-graph run", { runKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});

package/operations/acknowledgePr.test.ts

@@ -0,0 +1,94 @@
+// Tests for the POST /app/api/actions/acknowledge-pr operation `acknowledgePr` (issue #641).
+// The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL pull request. It stamps `acknowledged_at`,
+// which the `pull_requests_read_model` VIEW (094) derives into `list_bucket` = 'history' and `ack_open`
+// = 0, dropping the finished PR from the Active convergence list into History. Unlike acknowledge-
+// blocked it completes NO user task (a terminal PR is not parked). The PR twin of acknowledge-done /
+// acknowledge-epic.
+//
+// The op's only write is the `acknowledged_at` (+ `updated_at`) stamp, gated on the base `status`
+// belonging to the terminal tier (`PR_TERMINAL_STATUSES`). These tests seed an in-memory `pull_requests`
+// store and assert the 400/404/409/200 gate + the stamp; the bucket derivation itself is proven in
+// app/pullRequestReadModel.test.ts.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import { PR_TERMINAL_STATUSES } from "../app/pullRequestReadModel.ts";
+import handler from "./acknowledgePr.ts";
+
+// biome-ignore lint/suspicious/noExplicitAny: test-only fake data layer over dynamic row shapes.
+function memApp(seed: any[]): { app: AppApi; rows: any[] } {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only store.
+  const stores: Record<string, any[]> = { pull_requests: seed };
+  function tbl(name: string, pk = "id") {
+    // biome-ignore lint/suspicious/noExplicitAny: test-only.
+    const rows = (stores[name] ??= [] as any[]);
+    return {
+      // biome-ignore lint/suspicious/noExplicitAny: test-only.
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      // biome-ignore lint/suspicious/noExplicitAny: test-only.
+      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 unknown as AppApi;
+  return { app, rows: stores.pull_requests };
+}
+
+async function call(app: AppApi, body: unknown) {
+  // biome-ignore lint/suspicious/noExplicitAny: test-only op invocation.
+  return (await handler({ req: {} as any, params: {}, query: {}, body } as any, app)) as any;
+}
+
+test("acknowledge-pr: stamps acknowledged_at on a terminal PR and returns 200", async () => {
+  const { app, rows } = memApp([{ pr_key: "o/r#1", status: "merged", acknowledged_at: null }]);
+  const res = await call(app, { pr_key: "o/r#1" });
+  assertEquals(res.status, 200);
+  assertEquals(res.body.ok, true);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals(typeof rows[0].updated_at, "string");
+});
+
+test("acknowledge-pr: every terminal status is dismissable", async () => {
+  for (const status of PR_TERMINAL_STATUSES) {
+    const { app, rows } = memApp([{ pr_key: "o/r#1", status, acknowledged_at: null }]);
+    const res = await call(app, { pr_key: "o/r#1" });
+    assertEquals(res.status, 200, `status ${status} must be dismissable`);
+    assertEquals(typeof rows[0].acknowledged_at, "string");
+  }
+});
+
+test("acknowledge-pr: a live (still-converging) PR is rejected (409) and stays unstamped", async () => {
+  const { app, rows } = memApp([{ pr_key: "o/r#2", status: "converging", acknowledged_at: null }]);
+  const res = await call(app, { pr_key: "o/r#2" });
+  assertEquals(res.status, 409);
+  assertEquals(res.body.ok, false);
+  assertEquals(rows[0].acknowledged_at, null);
+});
+
+test("acknowledge-pr: a missing pr_key → 400", async () => {
+  const { app } = memApp([]);
+  assertEquals((await call(app, {})).status, 400);
+  assertEquals((await call(app, { pr_key: "  " })).status, 400);
+});
+
+test("acknowledge-pr: no matching PR → 404", async () => {
+  const { app } = memApp([]);
+  assertEquals((await call(app, { pr_key: "o/r#404" })).status, 404);
+});
+
+test("acknowledge-pr: idempotent — re-acknowledging a terminal PR re-stamps and returns 200", async () => {
+  const { app, rows } = memApp([{ pr_key: "o/r#5", status: "converged", acknowledged_at: null }]);
+  assertEquals((await call(app, { pr_key: "o/r#5" })).status, 200);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+  assertEquals((await call(app, { pr_key: "o/r#5" })).status, 200);
+  assertEquals(typeof rows[0].acknowledged_at, "string");
+});

package/operations/acknowledgePr.ts

@@ -0,0 +1,62 @@
+// POST /app/api/actions/acknowledge-pr → operationId `acknowledgePr` (issue #641).
+// The nwf UI's "Dismiss" (Done ✓) affordance for a TERMINAL pull request: an operator dismisses a
+// finished PR (merged / converged / abandoned / closed / failed) directly from the Overview "Active PR
+// convergences" or home "Pull requests" grid so it drops out of the Active convergence list into
+// History. It is the PR twin of `acknowledgeDone` (the feature-run tick-off) and `acknowledgeEpic` — a
+// terminal PR 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 `pull_requests` row.
+//
+// `list_bucket`/`ack_open` are DERIVED by the `pull_requests_read_model` VIEW (094, issue #641) from
+// the terminal-folded `derived_status` + `acknowledged_at` — a terminal, now-acknowledged PR reads
+// `list_bucket` = 'history' and `ack_open` = 0 — so this op NEVER writes a derived projection. Keyed on
+// the row's `pr_key`. Idempotent-safe: re-acknowledging re-stamps the timestamp and keeps it in
+// History.
+//
+// It rejects (409) a PR that is NOT terminal (still converging/waiting_review/…), so it can never
+// pre-seed the tick-off on a live PR: were `acknowledged_at` set early, the moment the PR later settled
+// the VIEW would drop it straight into History, skipping the operator dismiss this op exists to
+// require. The terminal check reads the base `status` — the reconciler's `onTerminated` edge persists
+// an out-of-band terminate to base `status` = 'abandoned', so a resolved PR is matched here too.
+
+import { PR_TERMINAL_STATUSES } from "../app/pullRequestReadModel.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const str = (v: unknown): string => (typeof v === "string" ? v.trim() : "");
+
+export default defineOperation("acknowledgePr", async ({ body }, app) => {
+  if (!body || typeof body !== "object") {
+    app.log.warn("acknowledge-pr rejected: missing request body");
+    return { status: 400, body: { ok: false, error: "pr_key is required" } };
+  }
+
+  const prKey = str(body.pr_key);
+  if (!prKey) return { status: 400, body: { ok: false, error: "pr_key is required" } };
+
+  const table = app.data.table<{ pr_key: string; status: string; acknowledged_at: string | null; updated_at: string }>(
+    "pull_requests",
+    "pr_key",
+  );
+  const pr = await table.get(prKey);
+  if (!pr) {
+    app.log.warn("acknowledge-pr: no such pull request", { prKey });
+    return { status: 404, body: { ok: false, error: "no such pull request" } };
+  }
+
+  // Guard: only a TERMINAL PR (a `PR_TERMINAL_STATUSES` status — the same set the read model's
+  // `list_bucket` folds to History) carries the Dismiss affordance. Acknowledging a live PR would
+  // pre-seed `acknowledged_at`, so the moment it later settled the VIEW would drop it straight into
+  // History, skipping the operator tick-off this op exists to require.
+  if (!PR_TERMINAL_STATUSES.includes(pr.status)) {
+    app.log.warn("acknowledge-pr rejected: PR is not terminal", { prKey, status: pr.status });
+    return { status: 409, body: { ok: false, error: "pull request is not terminal" } };
+  }
+
+  // Stamp the dismissal. `list_bucket` (→ 'history') and `ack_open` (→ 0) are derived by the
+  // `pull_requests_read_model` VIEW from the terminal, now-acknowledged 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(prKey, { acknowledged_at: now, updated_at: now });
+
+  app.log.info("operator dismissed terminal pull request", { prKey });
+  return { status: 200, body: { ok: true, message: "acknowledged" } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.166.0",
+  "version": "0.167.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/delivery-graphs.page.json

@@ -120,11 +120,11 @@
           "source": "app",
           "table": "delivery_graph_read_model",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["awaiting-approval", "running"] }]
+          "filter": [{ "field": "list_bucket", "in": ["active"] }]
         },
         "tabs": [
-          { "label": "In-flight", "filter": [{ "field": "status", "in": ["awaiting-approval", "running"] }] },
-          { "label": "History", "filter": [{ "field": "status", "in": ["done", "failed", "abandoned"] }] },
+          { "label": "In-flight", "filter": [{ "field": "list_bucket", "in": ["active"] }] },
+          { "label": "History", "filter": [{ "field": "list_bucket", "in": ["history"] }] },
           { "label": "All", "filter": [] }
         ],
         "columns": [
@@ -171,6 +171,15 @@
               "path": "/app/api/actions/delivery-graph/library/save",
               "body": { "name": "{{row.title}}", "digest": "{{row.digest}}" }
             }
+          },
+          {
+            "label": "Dismiss",
+            "confirm": "Dismiss this finished delivery graph? It acknowledges the terminal run and files it under History.",
+            "showWhenField": "ack_open",
+            "action": {
+              "path": "/app/api/actions/acknowledge-delivery-graph",
+              "body": { "run_key": "{{row.run_key}}" }
+            }
           }
         ]
       }

package/pages/home.page.json

@@ -119,23 +119,15 @@
         "data": {
           "kind": "datasource",
           "source": "app",
-          "table": "pull_requests",
+          "table": "pull_requests_read_model",
           "orderBy": {
             "field": "updated_at",
             "dir": "desc"
           },
           "filter": [
             {
-              "field": "status",
-              "in": [
-                "converging",
-                "waiting_review",
-                "escalated",
-                "waiting_deps",
-                "waiting_merge",
-                "queued",
-                "merging"
-              ]
+              "field": "list_bucket",
+              "in": ["active"]
             }
           ]
         },
@@ -144,16 +136,8 @@
             "label": "Active",
             "filter": [
               {
-                "field": "status",
-                "in": [
-                  "converging",
-                  "waiting_review",
-                  "escalated",
-                  "waiting_deps",
-                  "waiting_merge",
-                  "queued",
-                  "merging"
-                ]
+                "field": "list_bucket",
+                "in": ["active"]
               }
             ]
           },
@@ -161,12 +145,8 @@
             "label": "History",
             "filter": [
               {
-                "field": "status",
-                "in": [
-                  "converged",
-                  "merged",
-                  "abandoned"
-                ]
+                "field": "list_bucket",
+                "in": ["history"]
               }
             ]
           }
@@ -224,6 +204,17 @@
                 "processInstanceKey": "{{row.process_key}}"
               }
             }
+          },
+          {
+            "label": "Dismiss",
+            "confirm": "Dismiss this finished PR? It acknowledges the terminal pull request and files it under History.",
+            "showWhenField": "ack_open",
+            "action": {
+              "path": "/app/api/actions/acknowledge-pr",
+              "body": {
+                "pr_key": "{{row.pr_key}}"
+              }
+            }
           }
         ],
         "detail": {