@nanobpm/nano-workforce 0.57.0 → 0.58.1

package/.github/workflows/ci.yml

@@ -47,6 +47,13 @@ jobs:
       - name: Check agent prompt templates
         run: npm run check:prompts
 
+      # Merge-safety gate: migrations are applied in numeric-prefix order, but each fan-out branch
+      # picks "the next" prefix independently, so parallel siblings silently collide on one slot
+      # (the historical 004/005/006/007 pairs; recurred on epic #142). This fails the build on any
+      # new duplicate prefix so the collision can't merge unnoticed.
+      - name: Check migration prefixes (no collisions)
+        run: npm run check:migrations
+
       # Runs the full *.test.ts suite under Node's built-in test runner (node:test), which strips
       # TypeScript types on the fly (Node >= 22.6) — no build step.
       - name: Test (Node)

package/AGENTS.md

@@ -79,6 +79,20 @@ GENERATED, never hand-edited.**
   stale. It runs in `.github/workflows/ci.yml`, so a flow change that forgets the
   relayout **cannot merge**. Run `npm run layout` and commit the result whenever
   the check flags a model.
+- **`cancelActivity="true"` is the BPMN default and `bpmn-auto-layout`
+  canonicalises it away.** Don't hand-add it back to an interrupting boundary
+  event — the serializer strips it, so a hand-written `cancelActivity="true"`
+  makes `layout:check` drift on the next relayout. Interrupting is the default;
+  only `cancelActivity="false"` (non-interrupting) is emitted.
+- **One task owns each `.bpmn` file — never fan two parallel tasks onto the same
+  process diagram.** `layoutBpmn` regenerates the *entire* `<bpmndi:BPMNDiagram>`
+  block, so two independently relaid-out copies of one process diverge across
+  every shape and edge. Each PR is green alone, but the second to land collides
+  in the DI and — even after a text-merge — leaves the committed diagram stale
+  vs. the merged semantic model, so `layout:check` fails on a combined state that
+  no single PR's CI ever exercised. When decomposing a fleet, coarsen the tasks
+  that touch a shared process file into one; do **not** paper the collision over
+  with a `dependsOn` edge added purely to serialise otherwise-parallel work.
 
 ## Engine capabilities (Zeebe parity — use them, don't work around them)
 
@@ -105,6 +119,29 @@ cannot yet express event-based gateways or boundary events (its `FlowNode` union
 has no such node). This app authors BPMN as XML, so author those constructs in
 the XML directly; `layoutBpmn` lays them out correctly.
 
+## Testing flows against the testkit (WASM) engine
+
+Unit tests boot the app against an in-process WASM build of the engine. Two
+non-obvious behaviours bite user-task / escalation tests — budget for them
+instead of rediscovering them:
+
+- **A COMPLETED instance's variables are folded away.** `snapshot()` reports
+  `instance.variables = {}` once an instance completes, and a completed
+  `userTask` carries no vars — so you cannot assert a typed completion variable
+  from a finished instance. Either read variables while the instance is still
+  ACTIVE (parked on the next wait), or route the resume through a FEEL gateway
+  condition and assert `app.snapshot().takenSequenceFlows`. `takenSequenceFlows`
+  is engine-**global** and cumulative, so assert it with a single instance per
+  booted app.
+- **A `zeebe:input source="=null"` seed shadows a job-completion value at an
+  immediately-following gateway inside a multi-instance subProcess.** The gate
+  reads the stale `null` and takes its default. Don't seed a var that an
+  in-subprocess gateway reads; instead hoist it into the MI-child scope with a
+  `zeebe:output source="=var" target="var"` mapping on the service task (a no-op
+  on the production nano engine, which updates the nearest scope, but it keeps
+  per-child isolation in the testkit). Only vars read by an in-subprocess gateway
+  need this — output-only vars (e.g. `summary`, `pr`) are fine.
+
 ## Data envelopes are scalar-only
 
 `nano:dataEnvelope` shapes support only **scalar** `nano:extend` types
@@ -113,6 +150,30 @@ must carry a list (e.g. failing check names), join it to a scalar (e.g.
 `\n`-separated) in the publisher before it crosses the envelope, and split it on
 the far side if needed.
 
+## Urban page runtime: rendering primitives are not JS-truthy
+
+The `@nanobpm/urban` page runtime (`pages.ts`, ~0.46) renders `pages/*.page.json`
+with primitive-specific gating and linking rules that do **not** match ordinary JS
+truthiness. Getting these wrong renders stray badges on every row or drops a link
+silently — cheap to avoid, annoying to debug after the fact.
+
+- **`badge` columns gate on non-empty string, not truthiness.** A column badge
+  renders whenever `String(value).trim() !== ""`. So an `INTEGER NOT NULL DEFAULT
+  0` flag renders the badge on *every* non-set row (value `0` → `"0"` → non-empty).
+  For a "show a badge only when set" flag, store **`NULL`** (not `0`) when
+  not-set, in the **canonical derivation** *and* everywhere else that clears it —
+  a single `0`-writer re-lights the badge.
+- **`detail.fields` render as plain text — no per-field links.** The detail panel
+  emits `label + String(value)` per field; there is no per-field `linkField`/
+  `link`. Clickable links exist only on **grid columns** (`col.linkField`,
+  http(s)-gated — see `issue_url`/`issue_number` in `pages/epic.page.json`) and on
+  the single block-level `detail.linkField`. To make a value clickable, add it as
+  a grid column with `linkField`, not a `detail.fields` entry.
+- **`showWhenField` *does* use JS truthiness.** Unlike `badge`, a control gated by
+  `showWhenField` is hidden for `0`/`null`/`""` alike — so a `0`-or-`NULL` flag
+  correctly hides it either way. (This is why the same flag can need `NULL` for a
+  badge yet work as `0` for a `showWhenField` button.)
+
 ## The poller owns liveness/reconciliation
 
 `main.ts` runs a **self-scheduling** poll loop (`pollOnce` in `app/service.ts`),
@@ -135,6 +196,10 @@ Migrations live in `db/migrations/*.sql` and are **auto-applied on boot** from
 - **Destructive drops are a separate, later contract phase**, shipped only after
   a release stopped reading the old shape.
 - Number a new migration after the current highest prefix (they apply in order).
+  Check `origin/main`, not your branch point — a fan-out epic branch forks at one
+  prefix while `main` keeps advancing, so the branch-local "next" number collides
+  on merge. Two files must never share a prefix; `npm run check:migrations`
+  (a CI gate) enforces this and fails the build on any new duplicate.
 
 ## Runtime & CI gates
 
@@ -148,14 +213,31 @@ npm run typecheck                                     # tsc --noEmit (Node)
 npm run check                                         # urban check (manifest validation)
 npm run layout:check                                  # BPMN diagram freshness (no drift)
 npm run check:prompts                                 # agent-prompt template resolution
+npm run check:migrations                              # migration prefixes (no collisions)
 npm test                                              # unit tests (node --test)
 ```
 
 CI (`.github/workflows/ci.yml`) gates lint, typecheck, `urban check`, `layout:check`,
-the prompt check, and the Node test suite. Run `npm run layout <file.bpmn>` after
+the prompt check, the migration-prefix check, and the Node test suite. Run `npm run layout <file.bpmn>` after
 any BPMN flow change and commit the regenerated diagram — the `layout:check`
 gate fails the build otherwise.
 
+### Generated facades are gitignored — regenerate before running a single test file
+
+`nano-generated/*` (the materialised Nano SDK facades — `operations.ts`, etc.) is
+**gitignored** and produced by `urban gen`. Two consequences that have bitten
+agents:
+
+- **Never `git add nano-generated/`** — there is nothing to commit; `gen:check`
+  and `typecheck` validate its freshness on disk. `npm run gen` (or the
+  `pretypecheck`/`pretest` hook) refreshes it.
+- **Run `npm run gen` before running a single delegate test file directly**, e.g.
+  `node --test operations/foo.test.ts`. A raw single-file run does **not** fire an
+  `urban gen` hook, so the delegate import fails with a cryptic
+  `ERR_MODULE_NOT_FOUND` for `nano-generated/operations.ts`. `npm test`/`npm run
+  e2e`/`typecheck` regenerate it first via a pre-hook, so full-suite runs are
+  fine.
+
 ## Repo conventions
 
 - **DCO sign-off is enforced.** Every commit needs a `Signed-off-by` trailer —

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.58.1](https://github.com/nanobpm/nano-workforce/compare/v0.58.0...v0.58.1) (2026-08-13)
+
+
+### Bug Fixes
+
+* regenerate nano-generated/ before start (prestart: urban gen) ([#195](https://github.com/nanobpm/nano-workforce/issues/195)) ([d45fe22](https://github.com/nanobpm/nano-workforce/commit/d45fe22de58766730721f51cbcb7e97d6f4f06c8)), closes [#192](https://github.com/nanobpm/nano-workforce/issues/192)
+
+# [0.58.0](https://github.com/nanobpm/nano-workforce/compare/v0.57.0...v0.58.0) (2026-08-13)
+
+
+### Features
+
+* single-issue feature run — one issue → one PR (+ optional converge/merge) ([#194](https://github.com/nanobpm/nano-workforce/issues/194)) ([7557439](https://github.com/nanobpm/nano-workforce/commit/7557439e7f88383a5da62fda45994a37f6262007)), closes [post-#192](https://github.com/post-/issues/192) [#172](https://github.com/nanobpm/nano-workforce/issues/172) [#172](https://github.com/nanobpm/nano-workforce/issues/172) [owner/repo#N](https://github.com/owner/repo/issues/N)
+
 # [0.57.0](https://github.com/nanobpm/nano-workforce/compare/v0.56.0...v0.57.0) (2026-08-13)
 
 

package/README.md

@@ -255,7 +255,7 @@ active epic already targets the same custom base. See
 | `NANO_PR_GITHUB_TRANSPORT` | `auto` | how the poller reads GitHub: `gh` (host CLI), `token` (`GITHUB_TOKEN` over HTTP), or `auto` |
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
 | `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `POST /app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`); unset = open |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `POST /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
 | `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the `convergeOnly` field on `start/convergence-loop` (`true` forces review-only for that PR) |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |

package/SPEC.md

@@ -31,10 +31,10 @@ surface are proposed and open for adjustment.
                      ▼
             ┌───────────────────┐        review-ready (msg)      ┌──────────┐
             │  convergence-loop │◀───────────────────────────────│  poller  │
-            │      (BPMN)       │        escalation-answered (msg)└────┬─────┘
+            │      (BPMN)       │                                 └────┬─────┘
             └─────────┬─────────┘◀───────────────┐                    │ polls
-                      │ senior:pr-review job      │ answer POST        │ GitHub
-                      ▼                           │                    ▼
+                      │ senior:pr-review job      │ userTask complete  │ GitHub
+                      ▼                           │ (inbox)            ▼
             ┌───────────────────┐          ┌──────┴───────┐     ┌────────────┐
             │  decoupled agent  │          │   web UI +   │     │   SQLite   │
             │ (c8ctl nano work) │          │  API routes  │────▶│ (app.db)   │
@@ -197,16 +197,16 @@ Consequences the prompt (`prompts/review-round.md`) encodes:
 |---|---|---|---|
 | `pr-submitted` | — (start) | submit route/webhook | `{repo, prNumber, prUrl, prKey}` |
 | `review-ready` | `prKey` | **poller** | `{reviewId, reviewState, submittedAt}` |
-| `escalation-answered` | `prKey` | UI answer route | `{answer, escalationId}` |
+| `escalation-answered` | `prKey` | merge-loop answer (`answerEscalation`) | `{answer, escalationId}` |
 | `deps-cleared` | `prKey` | **poller** (merge) | — (all `Depends-on` PRs merged) |
 | `merge-ready` | `prKey` | **poller** (merge) | `{mergeState}` (`ready` \| `conflict` \| `blocked`); when `blocked`, also `{failingChecks, failingChecksList}` for the `senior:fix-ci` branch |
 | `merge-landed` | `prKey` | **poller** (merge) | — (queued PR merged, or merged out-of-band) |
 
-Note `escalation-answered` is reused by both processes (`convergence-loop` and
-`merge-loop`); only one is ever active for a given `prKey`, so correlation is
-unambiguous. Each `.bpmn` gives it a distinct message **id** (and distinct
-envelope shape ids) to avoid duplicate-id collisions when the manifest deploys
-both files.
+Note `escalation-answered` is now used only by the `merge-loop` process (the
+`convergence-loop` review escalation is a native `userTask` answered through the
+task inbox, not this message). The merge-loop `.bpmn` gives it a distinct message
+**id** (and distinct envelope shape ids) to avoid duplicate-id collisions when the
+manifest deploys both files.
 
 ## 7. Domain model (SQLite — `db/migrations/001_init.sql`) — PROPOSED
 
@@ -262,9 +262,9 @@ The UI is authored declaratively as `pages/home.page.json` and served by the
 generic Urban **page runtime** (`@nanobpm/app`, ADR 0042) — no hand-written SPA.
 The page defines status-filtered tabs (active vs. history), a submit form, a
 per-row **Cancel** action, and an expandable detail with the round/escalation
-child grids, a lazily-loaded transcript, and a conditional **answer** form shown
-when the PR has an open escalation (`open_escalation_id`, denormalised onto the
-row by migration `003`).
+child grids and a lazily-loaded transcript. The round/escalation grids are
+read-only audit; escalations are answered through the **task inbox** surface at
+`/tasks` (native `userTask`s), not an inline form on this page.
 
 The app-specific business-logic endpoints are **OpenAPI operations** mounted
 under `api.base` (`/app/api`), each implemented by a delegate module in
@@ -280,8 +280,7 @@ The full, authoritative contract is `openapi.yaml` (Swagger UI at
 | `GET` | `/app/api/version` | app + engine version |
 | `POST` | `/app/api/actions/start/convergence-loop` | parse the PR ref → create the aggregate + start the process (the ONE submit door — page + external callers) |
 | `POST` | `/app/api/actions/start/plan-fanout` | parse the issue ref → start a plan fan-out run (the ONE plan door) |
-| `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open escalation → publish `escalation-answered` |
-| `POST` | `/app/api/hooks/feature-answer` | answer an implementation-phase task escalation out of band (optional shared-secret) |
+| `POST` | `/app/api/actions/message` (`escalation-answered`) | answer an open merge-loop escalation → publish `escalation-answered` (the four #156 escalation kinds are native user tasks answered via the task inbox) |
 | `GET`/`POST` | `/app/api/hooks/blackboard` | per-plan coordination blackboard (capability-token side-channel) |
 | `GET` | `/app/api/hooks/abandon` | cooperative abandon check (per-PR capability token) |
 
@@ -397,8 +396,8 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   waits for `merge-landed` (poller detects the landed PR). Every attempt is
   recorded in the `merges` audit table.
 - **Escalation** — a conflict or a failing gate raises the same
-  `pr.persist-escalation` worker / UI answer form as the review stage (status
-  `escalated`); answering re-arms and retries.
+  `pr.persist-escalation` worker as the review stage (status `escalated`), answered
+  via the merge-loop `escalation-answered` message; answering re-arms and retries.
 - **Terminal** — `merged` (with `merged_at`), or `converged` when
   `NANO_PR_AUTO_MERGE=0` (review-only), or `abandoned` on cancel.
 
@@ -415,7 +414,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `GITHUB_TOKEN` | — | GitHub API (poller + agent) |
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
-| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret for the `/app/api/hooks/feature-answer` webhook operation (`X-Hook-Secret`) |
+| `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`X-Hook-Secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
 | `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
@@ -526,11 +525,11 @@ It runs only for `headCount >= 2` on non-mergify repos (`shouldRunTrialMerge`).
 
 Flow (`resources/processes/plan-fanout.bpmn`): `gw-trial-needed` → `trial-merge`
 (`senior:trial-merge`) → `record-trial-merge` (audit row in `plan_trial_merges`) →
-`gw-trial` (`trial red?`). On red it persists a plan-level escalation
-(`pr.persist-task-escalation`, task id `trial-merge-wave-<N>`, corrKey
-`<plan_key>:trial-merge-wave-<N>`) and parks at `wait-trial-answer`
-(`feature-escalation-answered`). The operator answers exactly `proceed` to override and
-continue, or anything else to **rerun** the trial after pushing a fix.
+`gw-trial` (`trial red?`). On red it opens a plan-level **user task**
+(`trial-merge-decision`, task id `trial-merge-wave-<N>`) and parks at
+`wait-trial-answer` until it is completed through the task inbox. The operator
+answers with `action: "proceed"` to override and continue, or `"rebase"`/`"abandon"`
+to **rerun** the trial after pushing a fix (or give up).
 
 **Known gap — inherited vs emergent failures (issue #129, PLANNED).** As shipped, D3
 escalates on *any* red combined suite, including a failure that was **already red on

package/app/agentCompletion.test.ts

@@ -0,0 +1,337 @@
+// Red/green unit coverage for the agent-answerable escalation completer (epic #156, slice U6;
+// ADR 0046). Drives the canonical attributed completer + the agent/revert entry points against an
+// in-memory data layer and a stub engine, asserting the three things U6 promises:
+//
+//   1. an AGENT assignee completes the SAME typed form a human would — the engine `completeUserTask`
+//      is called with the EXACT variables (no parallel path), and the process resume is driven;
+//   2. attribution is recorded — a `task_completions` ledger row captures actor_kind=agent + the
+//      agent id + the submitted variables;
+//   3. the completion is reversible — a human can revert an agent completion (recording who + when),
+//      while a human completion is NOT reversible and a completion can be reverted only once.
+//
+// The taxonomy/spine slices proved the form + resume round-trip end to end (the e2e does too, on the
+// real process); this suite pins the host-side attribution + reversibility contract in isolation.
+
+import { test } from "node:test";
+import { assert, assertEquals, assertRejects } from "#test-assert";
+import {
+  completeEscalationAsAgent,
+  completeUserTaskAttributed,
+  latestCompletion,
+  revertAgentCompletion,
+  type TaskCompletion,
+} from "./agentCompletion.ts";
+
+/** A minimal in-memory `Table<T>`: AUTOINCREMENT ids on insert, structural `find`, `get`, `update`. */
+function memTable(rows: any[], key: string) {
+  let seq = rows.reduce((m, r) => Math.max(m, Number(r[key]) || 0), 0);
+  return {
+    insert: (row: any) => {
+      const id = ++seq;
+      const stored = key === "id" ? { ...row, id } : { ...row };
+      rows.push(stored);
+      return Promise.resolve(key === "id" ? id : stored[key]);
+    },
+    get: (k: any) => Promise.resolve(rows.find((r) => r[key] === k)),
+    find: (q: any = {}) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    findOne: (q: any = {}) =>
+      Promise.resolve(rows.find((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+    update: (k: any, patch: any) => {
+      const r = rows.find((x) => x[key] === k);
+      if (r) Object.assign(r, patch);
+      return Promise.resolve(r ? 1 : 0);
+    },
+    delete: (k: any) => {
+      const i = rows.findIndex((r) => r[key] === k);
+      if (i >= 0) rows.splice(i, 1);
+      return Promise.resolve(i >= 0 ? 1 : 0);
+    },
+    count: (q: any = {}) =>
+      Promise.resolve(rows.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)).length),
+    all: () => Promise.resolve(rows.slice()),
+  };
+}
+
+function memData(stores: Record<string, { rows: any[]; key: string }>) {
+  return {
+    table: (name: string, key: string) =>
+      memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+}
+
+/** A stub engine recording every `completeUserTask`, with a seeded set of open user tasks. */
+function fakeEngine(openTasks: Array<{ userTaskKey: string; elementId?: string }>) {
+  const completed: Array<{ userTaskKey: string; variables?: Record<string, unknown> }> = [];
+  const engine = {
+    searchUserTasks: (_filter?: Record<string, unknown>) => Promise.resolve(openTasks),
+    completeUserTask: (userTaskKey: string, variables?: Record<string, unknown>) => {
+      completed.push({ userTaskKey, variables });
+      return Promise.resolve();
+    },
+  } as any;
+  return { engine, completed };
+}
+
+test("agent completion resumes with the exact typed vars a human submits AND records agent attribution", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([
+    { userTaskKey: "ut-1", elementId: "feature-escalation" },
+  ]);
+
+  const r = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-1",
+    agentId: "senior:answer-bot",
+    variables: { resolution: "answer", answer: "use v2" },
+  });
+
+  assertEquals(r.ok, true);
+  assertEquals(r.elementId, "feature-escalation");
+
+  // Same resume path a human drives: completeUserTask called with the identical typed variables.
+  assertEquals(completed.length, 1);
+  assertEquals(completed[0].userTaskKey, "ut-1");
+  assertEquals(completed[0].variables, { resolution: "answer", answer: "use v2" });
+
+  // Attribution recorded: an agent completion, its id, and the submitted variables.
+  const row = stores.task_completions.rows[0] as TaskCompletion;
+  assertEquals(row.actor_kind, "agent");
+  assertEquals(row.actor_id, "senior:answer-bot");
+  assertEquals(row.element_id, "feature-escalation");
+  assertEquals(JSON.parse(row.variables_json), { resolution: "answer", answer: "use v2" });
+  assertEquals(row.reversible, 1, "an agent completion is reversible");
+  assertEquals(row.reverted, 0);
+});
+
+test("agent completer refuses a non-escalation user task (scoped to the migrated escalation tasks)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-x", elementId: "decide" }]);
+
+  const r = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-x",
+    agentId: "bot",
+    variables: { decision: "approve" },
+  });
+
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "not an escalation task");
+  assertEquals(completed.length, 0, "a non-escalation task is never completed");
+  assertEquals(stores.task_completions.rows.length, 0, "and no attribution row is written");
+});
+
+test("agent completer is a no-op for an unknown userTaskKey", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([
+    { userTaskKey: "ut-1", elementId: "feature-escalation" },
+  ]);
+
+  const r = await completeEscalationAsAgent(data, engine, {
+    userTaskKey: "ut-missing",
+    agentId: "bot",
+    variables: { resolution: "abandon" },
+  });
+
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "no open escalation task");
+  assertEquals(completed.length, 0);
+});
+
+test("a human can revert/override an agent completion (recording who + when + corrective note)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-1", elementId: "feature-escalation" }]);
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey: "ut-1", elementId: "feature-escalation", variables: { resolution: "answer", answer: "guess" } },
+    { kind: "agent", id: "bot" },
+  );
+
+  const r = await revertAgentCompletion(data, completionId, { kind: "human", id: "alice" }, "wrong — use v3");
+  assertEquals(r.ok, true);
+
+  const row = (await latestCompletion(data, "ut-1"))!;
+  assertEquals(row.reverted, 1);
+  assertEquals(row.reverted_by, "alice");
+  assertEquals(row.reverted_note, "wrong — use v3", "the human's correction is captured");
+  assert(typeof row.reverted_at === "string" && row.reverted_at.length > 0, "reverted_at is stamped");
+});
+
+test("the ledger rolls back when the engine completion fails (never claims a completion that did not happen)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const engine = {
+    searchUserTasks: () => Promise.resolve([{ userTaskKey: "ut-1", elementId: "feature-escalation" }]),
+    completeUserTask: () => Promise.reject(new Error("engine rejected the completion")),
+  } as any;
+
+  let threw: unknown;
+  try {
+    await completeUserTaskAttributed(
+      data,
+      engine,
+      { userTaskKey: "ut-1", elementId: "feature-escalation", variables: { resolution: "answer", answer: "x" } },
+      { kind: "agent", id: "bot" },
+    );
+  } catch (err) {
+    threw = err;
+  }
+  assert(threw instanceof Error && /engine rejected/.test(threw.message), "the engine failure propagates");
+  assertEquals(stores.task_completions.rows.length, 0, "the attribution row was rolled back on failure");
+});
+
+test("a human completion is NOT reversible (it is already the authority)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-2", elementId: "plan-review-decision" }]);
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey: "ut-2", elementId: "plan-review-decision", variables: { directive: "proceed", notes: "" } },
+    { kind: "human", id: "operator" },
+  );
+
+  const stored = (await latestCompletion(data, "ut-2"))!;
+  assertEquals(stored.reversible, 0);
+
+  const r = await revertAgentCompletion(data, completionId, { kind: "human", id: "bob" });
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "completion is not reversible");
+});
+
+test("an agent completion can be reverted only once", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-3", elementId: "trial-merge-decision" }]);
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey: "ut-3", elementId: "trial-merge-decision", variables: { action: "proceed" } },
+    { kind: "agent", id: "bot" },
+  );
+
+  assertEquals((await revertAgentCompletion(data, completionId, { kind: "human", id: "alice" })).ok, true);
+  const second = await revertAgentCompletion(data, completionId, { kind: "human", id: "bob" });
+  assertEquals(second.ok, false);
+  assertEquals(second.reason, "completion already reverted");
+});
+
+test("reverting an unknown completion id is a no-op", async () => {
+  const data = memData({ task_completions: { rows: [], key: "id" } });
+  const r = await revertAgentCompletion(data, 999, { kind: "human", id: "alice" });
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "no such completion");
+});
+
+test("only a human may revert a completion (an agent identity cannot weaken the audit trail)", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine } = fakeEngine([{ userTaskKey: "ut-4", elementId: "feature-escalation" }]);
+
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey: "ut-4", elementId: "feature-escalation", variables: { resolution: "answer", answer: "x" } },
+    { kind: "agent", id: "bot" },
+  );
+
+  const r = await revertAgentCompletion(data, completionId, { kind: "agent", id: "other-bot" });
+  assertEquals(r.ok, false);
+  assertEquals(r.reason, "only a human may revert a completion");
+
+  const row = (await latestCompletion(data, "ut-4"))!;
+  assertEquals(row.reverted, 0, "the completion is left un-reverted when a non-human attempts it");
+});
+
+test("the attributed completer normalizes keys and rejects blank attribution", async () => {
+  const stores = { task_completions: { rows: [] as any[], key: "id" } };
+  const data = memData(stores);
+  const { engine, completed } = fakeEngine([{ userTaskKey: "ut-5", elementId: "feature-escalation" }]);
+
+  // Whitespace around the key + actor id is trimmed before it reaches the ledger and the engine.
+  const { completionId } = await completeUserTaskAttributed(
+    data,
+    engine,
+    { userTaskKey: "  ut-5  ", elementId: "feature-escalation", variables: { resolution: "answer", answer: "x" } },
+    { kind: "agent", id: "  bot  " },
+  );
+  assert(completionId > 0);
+  assertEquals(completed[0].userTaskKey, "ut-5", "the engine is completed with the trimmed key");
+  const row = stores.task_completions.rows[0] as TaskCompletion;
+  assertEquals(row.user_task_key, "ut-5");
+  assertEquals(row.actor_id, "bot");
+
+  // A blank key / actor id is rejected upfront — the ledger never records blank attribution.
+  await assertRejects(() =>
+    completeUserTaskAttributed(
+      data,
+      engine,
+      { userTaskKey: "   ", variables: {} },
+      { kind: "human", id: "operator" },
+    ),
+  );
+  await assertRejects(() =>
+    completeUserTaskAttributed(
+      data,
+      engine,
+      { userTaskKey: "ut-5", variables: {} },
+      { kind: "human", id: "  " },
+    ),
+  );
+  assertEquals(stores.task_completions.rows.length, 1, "no ledger row is written for a rejected completion");
+});
+
+test("a rollback failure never masks the original engine error", async () => {
+  const engine = {
+    searchUserTasks: () => Promise.resolve([{ userTaskKey: "ut-6", elementId: "feature-escalation" }]),
+    completeUserTask: () => Promise.reject(new Error("engine rejected the completion")),
+  } as any;
+
+  // A data layer whose ledger delete (the rollback) also throws — the engine error must still win.
+  const data = {
+    table: () => ({
+      insert: () => Promise.resolve(1),
+      delete: () => Promise.reject(new Error("ledger delete failed")),
+    }),
+  } as any;
+
+  let threw: unknown;
+  try {
+    await completeUserTaskAttributed(
+      data,
+      engine,
+      { userTaskKey: "ut-6", elementId: "feature-escalation", variables: { resolution: "answer", answer: "x" } },
+      { kind: "agent", id: "bot" },
+    );
+  } catch (err) {
+    threw = err;
+  }
+  assert(
+    threw instanceof Error && /engine rejected/.test(threw.message),
+    "the engine failure propagates, not the rollback failure",
+  );
+});
+
+test("latestCompletion returns the newest row by id regardless of insertion order", async () => {
+  const stores = {
+    task_completions: {
+      rows: [
+        { id: 3, user_task_key: "ut-x", actor_kind: "agent", actor_id: "bot", variables_json: "{}", reversible: 1, reverted: 0, created_at: "t3" },
+        { id: 1, user_task_key: "ut-x", actor_kind: "human", actor_id: "alice", variables_json: "{}", reversible: 0, reverted: 0, created_at: "t1" },
+        { id: 2, user_task_key: "ut-other", actor_kind: "agent", actor_id: "bot", variables_json: "{}", reversible: 1, reverted: 0, created_at: "t2" },
+      ] as any[],
+      key: "id",
+    },
+  };
+  const data = memData(stores);
+
+  const newest = (await latestCompletion(data, "ut-x"))!;
+  assertEquals(newest.id, 3, "the highest-id row for the key wins, not the first found");
+  assertEquals(stores.task_completions.rows[0].id, 3, "the backing array is not reordered");
+});