@nanobpm/nano-workforce 0.51.0 → 0.53.0

package/app/agentic/families/relay.family.ts

@@ -0,0 +1,331 @@
+// nano-workforce — the relay ring + transcript store agentic family (ADR 0056, H3 / #146).
+//
+// This is a sibling slice of the agentic-visibility epic (#142). It plugs into the H0 (#143)
+// family-registration SEAM (`../registry.ts`) as ONE NEW FILE and NOTHING ELSE — it never edits
+// `main.ts`, `drainAndExit`, or any shared boot line. The auto-discovery loader (`../loader.ts`)
+// finds it by the `*.family.ts` suffix and the seam mounts + tears it down.
+//
+// It composes two published primitives — it re-implements NEITHER:
+//   - `@nanobpm/agentic/relay`      — the bounded replay ring, three-lane QoS scheduler
+//     (control > interactive > bulk), resume-from-offset, and incarnation/generation fencing,
+//     all inside {@link RelayHub}. We mount it on the hub's `registerFamilyHandler` seam.
+//   - `@nanobpm/agentic/transcript` — {@link TranscriptStore}, retention-by-lifecycle over the app's
+//     SQLite DataLayer. Ephemeral streams flush the ring to a durable transcript on job completion;
+//     long-lived streams retain chunks so a reconnecting consumer resumes-from-offset (reattach).
+//
+// Its DB schema ships as the reserved forward-only additive migration
+// `db/migrations/024_agentic_transcript.sql` (H0 pre-allocated prefix 024 for H3), a byte-for-byte
+// mirror of the package's canonical `TRANSCRIPT_SCHEMA_SQL`, drift-guarded by this slice's test.
+//
+// Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+// is untouched — the agentic channel is the only new conversation; advisory semantics preserved (the
+// relay/transcript never hard-lock or gate a BPMN sequence flow).
+import type { ConnectionRegistry } from "@nanobpm/agentic/channel";
+import type { Frame } from "@nanobpm/agentic/protocol";
+import { RELAY_FAMILY, RelayHub, type RelayHubOptions } from "@nanobpm/agentic/relay";
+import {
+  type SqliteDb,
+  type TranscriptLifecycle,
+  type TranscriptRing,
+  type TranscriptSlice,
+  TranscriptStore,
+  type TranscriptStoreOptions,
+  type TranscriptStream,
+} from "@nanobpm/agentic/transcript";
+import type { Logger } from "@nanobpm/urban";
+import type { AgenticContext, AgenticFamily } from "../registry.ts";
+
+/** The stable family name this slice registers under the seam (distinct from the wire family key). */
+export const RELAY_FAMILY_NAME = "relay";
+
+/** Read a property off an unknown value without an unsafe `as` cast (mirrors the loader's helper). */
+function readProp(value: unknown, key: string): unknown {
+  if (!value || typeof value !== "object") return undefined;
+  return Object.hasOwn(value, key) ? Object.getOwnPropertyDescriptor(value, key)?.value : undefined;
+}
+
+/**
+ * A resume-from-offset source with no retained chunks — used to flush/complete a stream that a
+ * producer opened logically but never wrote to, so its transcript is still stamped `completed`
+ * rather than left dangling `open`.
+ */
+const EMPTY_SOURCE: TranscriptRing = { since: () => ({ entries: [] }), nextOffset: 0 };
+
+/** Per-stream bookkeeping the service keeps to drive lifecycle-aware persistence. */
+interface StreamState {
+  /** Retention lifecycle: `ephemeral` (flush+complete on job end) vs `long-lived` (reattach). */
+  lifecycle: TranscriptLifecycle;
+  /** The connection id of the most recent producer, for disconnect-driven completion. */
+  producer?: string;
+  /** Set once an ephemeral stream has been flushed & completed (so it is not re-completed). */
+  completed: boolean;
+}
+
+export interface RelayTranscriptServiceOptions {
+  /** The app-tier hub; the service claims the `relay` family key via its registration seam. */
+  readonly hub: {
+    registerFamilyHandler(family: string, handler: (frame: Frame, conn: RelayConnectionCtx) => void): void;
+  };
+  /** The shared connection registry — its `has(id)` is the liveness source of truth. */
+  readonly registry: ConnectionRegistry;
+  /** The raw SQLite handle (the app DataLayer's `source().db`); absent → transcripts disabled. */
+  readonly db: SqliteDb | undefined;
+  /** A structured logger for lifecycle lines. */
+  readonly log: Logger;
+  /** Options forwarded to the underlying {@link RelayHub} (ring/bulk capacity, default credit). */
+  readonly relay?: RelayHubOptions;
+  /** Options forwarded to the {@link TranscriptStore} (retention window, injectable clock). */
+  readonly transcript?: TranscriptStoreOptions;
+  /**
+   * Apply the transcript DDL from the store on mount (idempotent `CREATE ... IF NOT EXISTS`).
+   * Default `true`: the boot migration is the canonical path, but this makes the service usable
+   * against a bare source too (and is harmless when the migration already ran).
+   */
+  readonly ensureSchema?: boolean;
+}
+
+/** The minimal per-connection surface the relay handler receives from the hub (a {@link RelayHub} `RelayConnection`). */
+interface RelayConnectionCtx {
+  readonly id: string;
+  readonly registry: { has(id: string): boolean };
+  send(frame: Frame): void;
+}
+
+/**
+ * Composes the S5 relay ({@link RelayHub}) with the S6 transcript store ({@link TranscriptStore})
+ * and wires retention-by-lifecycle. It owns NO ring/scheduler/store logic of its own — it observes
+ * `produce` ownership so an ephemeral stream is flushed & completed when its producer disconnects,
+ * and exposes the completion/checkpoint/reattach/sweep surface H6 (#149) and the app drive.
+ */
+export class RelayTranscriptService {
+  /** The mounted relay hub (ring + QoS scheduler + incarnation fence). Exposed for inspection/tests. */
+  readonly relay: RelayHub;
+  /** The transcript store, or `undefined` when no DataLayer is mounted (relay still works, unpersisted). */
+  readonly store: TranscriptStore | undefined;
+
+  readonly #registry: ConnectionRegistry;
+  readonly #log: Logger;
+  readonly #streams = new Map<string, StreamState>();
+
+  constructor(options: RelayTranscriptServiceOptions) {
+    this.#registry = options.registry;
+    this.#log = options.log;
+    // Persistence is advisory: a store that can't be constructed or whose schema can't be applied
+    // (locked/permission-denied/unavailable SQLite) must NOT fail the family mount — fall back to
+    // running the relay unpersisted rather than tearing down the whole agentic channel.
+    let store: TranscriptStore | undefined;
+    if (options.db) {
+      try {
+        store = new TranscriptStore(options.db, options.transcript);
+        if (options.ensureSchema !== false) store.ensureSchema();
+      } catch (err) {
+        this.#log.warn("agentic transcript store unavailable — relay runs unpersisted", {
+          err: String(err),
+        });
+        store = undefined;
+      }
+    }
+    this.store = store;
+
+    this.relay = new RelayHub({
+      ...options.relay,
+      onFenced: (stream, incarnation, current) => {
+        this.#log.warn("agentic relay fenced a stale producer", { stream, incarnation, current });
+        options.relay?.onFenced?.(stream, incarnation, current);
+      },
+      onError: (err, connectionId) => {
+        this.#log.warn("agentic relay message error", { connectionId, err: String(err) });
+        options.relay?.onError?.(err, connectionId);
+      },
+    });
+
+    // Register the `relay` family ourselves (rather than via `registerRelayFamily`) so we can observe
+    // `produce` ownership before delegating to the hub — the hub's own routing still derives purely
+    // from this single registration, and a second `relay` registration is rejected by the seam.
+    options.hub.registerFamilyHandler(RELAY_FAMILY, (frame, conn) => this.#onFrame(frame, conn));
+  }
+
+  /** The tracked stream names (those a producer opened or that were declared). */
+  streams(): string[] {
+    return [...this.#streams.keys()];
+  }
+
+  /**
+   * Declare a stream's retention lifecycle before (or independently of) its first `produce`. The
+   * durable store records lifecycle write-once (first call wins there); in memory the latest call
+   * wins until the stream completes, which is how {@link checkpointStream} upgrades an as-yet
+   * ephemeral stream to `long-lived`. No-op once the stream has already been completed.
+   */
+  declareLifecycle(stream: string, lifecycle: TranscriptLifecycle): void {
+    const state = this.#stateFor(stream);
+    if (!state.completed) state.lifecycle = lifecycle;
+  }
+
+  /**
+   * Complete a stream on job end: flush the relay ring (its whole retained window) to the durable
+   * transcript under the stream's lifecycle. For an `ephemeral` stream this stamps `completed_at`
+   * (so {@link reattach} then serves the durable transcript and {@link sweep} may later retire it);
+   * for a `long-lived` stream it is a snapshot checkpoint that leaves the stream `open`. Idempotent:
+   * re-completing already-persisted offsets is a no-op. Returns the number of newly-persisted chunks.
+   */
+  completeStream(stream: string): number {
+    if (!this.store) return 0;
+    const state = this.#stateFor(stream);
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    let flushed: number;
+    try {
+      flushed = this.store.flush(stream, source, state.lifecycle);
+    } catch (err) {
+      // Persistence is advisory: a flush failure must not bubble into the hub's frame handler and
+      // take down unrelated streams. Log and leave the stream uncompleted so a later pass retries.
+      this.#log.warn("agentic relay stream flush failed — leaving stream uncompleted", {
+        stream,
+        lifecycle: state.lifecycle,
+        err: String(err),
+      });
+      return 0;
+    }
+    if (state.lifecycle === "ephemeral") state.completed = true;
+    // Drop producer ownership so a later reconcile does not re-flush a completed stream.
+    state.producer = undefined;
+    this.#log.info("agentic relay stream flushed", {
+      stream,
+      lifecycle: state.lifecycle,
+      flushed,
+      completed: state.completed,
+    });
+    return flushed;
+  }
+
+  /**
+   * Snapshot a long-lived stream's ring into the durable transcript without completing it — the
+   * checkpoint path a growing stream uses so a reconnecting consumer can {@link reattach} past the
+   * ring's resume window. Returns the number of newly-persisted chunks.
+   */
+  checkpointStream(stream: string): number {
+    if (!this.store) return 0;
+    this.declareLifecycle(stream, "long-lived");
+    const source = this.relay.ring(stream) ?? EMPTY_SOURCE;
+    try {
+      return this.store.flush(stream, source, "long-lived");
+    } catch (err) {
+      // Advisory: a checkpoint failure keeps the relay usable — return 0, the stream stays open.
+      this.#log.warn("agentic relay checkpoint flush failed", { stream, err: String(err) });
+      return 0;
+    }
+  }
+
+  /**
+   * Reattach a consumer from offset `from` (inclusive) against the durable transcript — mirrors the
+   * relay ring's `since` contract exactly, so a late/reconnecting consumer resumes identically
+   * whether from the live ring or the persisted transcript. Returns `undefined` with no store.
+   */
+  reattach(stream: string, from: number): TranscriptSlice | undefined {
+    return this.store?.since(stream, from);
+  }
+
+  /** Retention sweep: retire completed-ephemeral transcripts past the retention window. */
+  sweep(now?: number): string[] {
+    const retired = this.store?.sweep(now) ?? [];
+    // Forget the in-memory state of every retired stream so `#streams` stays bounded (and
+    // `#reconcile`'s scan stays cheap) even after many ephemeral streams complete and age out.
+    for (const stream of retired) this.#streams.delete(stream);
+    return retired;
+  }
+
+  /** A stream's persisted transcript metadata, if any (lifecycle/status/offset window). */
+  transcriptOf(stream: string): TranscriptStream | undefined {
+    return this.store?.get(stream);
+  }
+
+  /**
+   * Complete every still-open ephemeral stream (e.g. on shutdown) so no in-flight terminal is lost,
+   * then forget all tracking. Long-lived streams are left for reattach and are not force-completed.
+   */
+  teardown(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.lifecycle === "ephemeral" && !state.completed) this.completeStream(stream);
+    }
+    this.#streams.clear();
+  }
+
+  /** Handle one inbound `relay` frame: reconcile dead producers, observe ownership, then delegate. */
+  #onFrame(frame: Frame, conn: RelayConnectionCtx): void {
+    this.#reconcile();
+    this.#observe(frame, conn);
+    this.relay.handle(frame, conn);
+  }
+
+  /** Record `produce` ownership so a producer disconnect can drive ephemeral completion. */
+  #observe(frame: Frame, conn: RelayConnectionCtx): void {
+    if (readProp(frame.payload, "op") !== "produce") return;
+    const stream = readProp(frame.payload, "stream");
+    if (typeof stream !== "string" || stream === "") return;
+    this.#stateFor(stream).producer = conn.id;
+  }
+
+  /**
+   * Flush + complete every ephemeral stream whose producer connection is no longer live (the S1
+   * registry dropped it on close or liveness timeout). Lazy, like the relay hub's own dead-subscriber
+   * prune: it runs on each inbound frame, and shutdown covers the quiescent tail via {@link teardown}.
+   */
+  #reconcile(): void {
+    for (const [stream, state] of this.#streams) {
+      if (state.completed || state.lifecycle !== "ephemeral") continue;
+      if (state.producer !== undefined && !this.#registry.has(state.producer)) {
+        this.completeStream(stream);
+      }
+    }
+  }
+
+  #stateFor(stream: string): StreamState {
+    let state = this.#streams.get(stream);
+    if (state === undefined) {
+      state = { lifecycle: "ephemeral", completed: false };
+      this.#streams.set(stream, state);
+    }
+    return state;
+  }
+}
+
+/**
+ * Build the H3 relay family. Copy-of-the-seam pattern: it constructs the {@link RelayTranscriptService}
+ * in `mount` (threading the seam's hub/registry/DataLayer/log) and tears it down in `teardown`. The
+ * created service is exposed to `onMounted` so a driver (H6 correlation, tests) can reach the
+ * completion/reattach surface without re-mounting anything.
+ */
+export function createRelayFamily(options: {
+  readonly relay?: RelayHubOptions;
+  readonly transcript?: TranscriptStoreOptions;
+  readonly ensureSchema?: boolean;
+  /** Called with the live service once mounted, so a driver can drive completion/reattach. */
+  readonly onMounted?: (service: RelayTranscriptService) => void;
+} = {}): AgenticFamily {
+  let service: RelayTranscriptService | undefined;
+  return {
+    name: RELAY_FAMILY_NAME,
+    mount(ctx: AgenticContext): void {
+      service = new RelayTranscriptService({
+        hub: ctx.hub,
+        registry: ctx.registry,
+        // The app's SQLite handle: the same store the advisory blackboard uses. Absent → relay runs
+        // unpersisted (still advisory-correct), rather than failing the whole channel boot.
+        db: ctx.data ? ctx.data.source().db : undefined,
+        log: ctx.log,
+        relay: options.relay,
+        transcript: options.transcript,
+        ensureSchema: options.ensureSchema,
+      });
+      options.onMounted?.(service);
+    },
+    teardown(): void {
+      service?.teardown();
+      service = undefined;
+    },
+  };
+}
+
+/** The discovered family instance (the loader picks up this `family` export). */
+export const family: AgenticFamily = createRelayFamily();
+
+export default family;

package/db/migrations/023_agentic_presence.sql

@@ -0,0 +1,30 @@
+-- Agentic visibility plane — presence & registry (ADR 0056, H1 / #144).
+--
+-- The durable supply mirror behind the agentic channel's presence family. A worker that opens the
+-- channel and sends `register` lands one row here (keyed by its instance id) carrying its declared
+-- enrolment capability (cognition/weight/family/host — an ENROLMENT attribute, NEVER a routing
+-- token), the connection it registered on, and its own heartbeat-refreshed `last_seen` liveness.
+-- Heartbeats refresh `last_seen`; `deregister`, an observed disconnect, or the presence-TTL sweep
+-- remove the row. This is the read-only supply feed the enrolment epic (#152) reads — it is advisory
+-- and NEVER gates a BPMN sequence flow.
+--
+-- The very same DDL is the single source of truth the runtime's `PresenceStore` applies through
+-- `ensureSchema()` (@nanobpm/agentic/presence, `PRESENCE_SCHEMA_SQL`). Keeping the two application
+-- paths (this boot migration and the store's guard) statement-for-statement identical is what stops
+-- a production/boot schema drift. Forward-only and additive: `CREATE ... IF NOT EXISTS` only.
+--
+-- This is the reserved prefix H0 pre-allocated for H1 (023) so parallel wave-1 siblings never
+-- independently grab "the next" migration number (H3 → 024_agentic_transcript, H4 → 025_agentic_blackboard).
+CREATE TABLE IF NOT EXISTS agentic_presence (
+  instance      TEXT PRIMARY KEY,
+  connection_id TEXT NOT NULL,
+  identity      TEXT NOT NULL,
+  cognition     TEXT,
+  weight        REAL,
+  family        TEXT,
+  host          TEXT,
+  registered_at TEXT NOT NULL,
+  last_seen     INTEGER NOT NULL
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_last_seen ON agentic_presence (last_seen);
+CREATE INDEX IF NOT EXISTS idx_agentic_presence_connection ON agentic_presence (connection_id);

package/db/migrations/024_agentic_transcript.sql

@@ -0,0 +1,43 @@
+-- Agentic visibility plane (ADR 0056, epic #142) — H3 relay transcript store (#146).
+--
+-- The relay family (app/agentic/families/relay.family.ts) mounts @nanobpm/agentic/relay (a bounded
+-- replay ring + three-lane QoS scheduler + incarnation fence) on the app-tier agentic channel and
+-- persists terminal transcripts through @nanobpm/agentic/transcript with retention-by-lifecycle:
+--
+--   • ephemeral streams  → the relay ring is flushed to a durable transcript on job completion
+--                          (and the stream marked `completed`, then retired by a retention sweep);
+--   • long-lived streams → chunks are retained/checkpointed so a reconnecting consumer can resume
+--                          from any offset (reattach), bounded by a rolling offset window.
+--
+-- This DDL is the forward-only, additive boot migration the DataLayer runner applies from
+-- nano.app.json (`data.sources.app.migrations`). It is a byte-for-byte mirror of the package's
+-- canonical `TRANSCRIPT_SCHEMA_SQL` (@nanobpm/agentic/transcript `schema.ts`), which the store also
+-- applies via `ensureSchema()`. The two application paths are kept from drifting by the drift-guard
+-- test `app/agentic/families/relay.family.test.ts` — divergence is a red test, not a silent boot vs.
+-- store mismatch. Additive only (CREATE ... IF NOT EXISTS): it adds no column to an existing table
+-- and drops nothing, so it is safe to apply forward over any earlier schema.
+--
+-- H0 (#143) pre-allocated this exact prefix (024) for H3 so no two sibling slices independently grab
+-- "the next" number (H1=023_agentic_presence, H4=025_agentic_blackboard). `chunk_offset` (not
+-- `offset`) is deliberate: OFFSET is a SQLite keyword, so the column avoids quoting in every query.
+--
+-- Invariants (ADR 0056): app-tier only, never the engine; the Camunda-8 job protocol (worker⇄engine)
+-- is untouched — the agentic channel is the only new conversation; advisory semantics preserved (the
+-- transcript never hard-locks or gates a BPMN sequence flow).
+CREATE TABLE IF NOT EXISTS agentic_transcript_stream (
+  stream        TEXT PRIMARY KEY,
+  lifecycle     TEXT NOT NULL,
+  status        TEXT NOT NULL DEFAULT 'open',
+  created_at    TEXT NOT NULL,
+  completed_at  TEXT,
+  first_offset  INTEGER,
+  next_offset   INTEGER NOT NULL DEFAULT 0
+);
+CREATE TABLE IF NOT EXISTS agentic_transcript_chunk (
+  stream        TEXT NOT NULL,
+  chunk_offset  INTEGER NOT NULL,
+  chunk         TEXT NOT NULL,
+  appended_at   TEXT NOT NULL,
+  PRIMARY KEY (stream, chunk_offset)
+);
+CREATE INDEX IF NOT EXISTS idx_agentic_transcript_stream_retention ON agentic_transcript_stream (lifecycle, status, completed_at);

package/docs/adr/0002-escalations-are-user-tasks-and-forms.md

@@ -0,0 +1,167 @@
+# ADR 0002 — Escalations are user tasks + forms
+
+Status: **Proposed.**
+Date: 2026-08-13.
+
+> **Scope note.** This is a **nano-workforce-local** ADR — it governs how *this app's* agent workforce
+> models human (and agent) decision points. Platform-wide ADRs live in `Magikcraft/nano-bpm/docs/adr`
+> (referenced by number + repo, e.g. "nano-bpm ADR 0026"). nano-workforce's own series continues here
+> after ADR 0001.
+
+Relates to:
+nano-bpm **ADR 0026** (Urban human surfaces + run model — the `taskInbox` surface this ADR builds on:
+a hosted task list backed by the engine's user-task search that renders a linked `.form` and posts
+completion),
+nano-bpm **ADR 0037** (execution + task listeners — the user-task lifecycle hooks this ADR leans on),
+nano-bpm **ADR 0046** (agent-as-worker vs agent-in-the-node — the duality that lets an **agent** be a
+task assignee, answering the same form a human would),
+nano-bpm **ADR 0051** (nano-workforce — the crew orchestrator whose escalations this reshapes),
+nano-bpm **ADR 0056** (the Nano agentic protocol — this ADR is the **durable** human-in-the-loop lane,
+complementary to that ADR's **ephemeral** live-steering cockpit),
+nano-workforce **ADR 0001** (this repo's ADR series),
+and the current bespoke escalation subsystem in this repo: `app/plan.ts` (`plan_escalations`,
+`plan_review_escalations`, `answerTaskEscalation`, `answerPlanEscalation`, `refreshOpenTaskEscalation`),
+`app/service.ts` (the `open_escalation_*` pointer on `pull_requests`), the `pr.persist-*-escalation`
+service workers, and the `feature-escalation-answered` / `plan-escalation-answered` resume messages in
+`resources/processes/plan-fanout.bpmn`.
+
+## Context
+
+When a fanned-out agent task cannot proceed on its own — an open question, a trial-merge conflict, a
+plan-review budget cap, a stuck PR-review loop — nano-workforce **escalates**: it parks the process and
+waits for a human decision. Today that is a hand-rolled subsystem, and the same shape recurs three times:
+
+1. **Task escalation** (`plan_escalations`, issue #25) — a fanned-out task's open question. In
+   `plan-fanout.bpmn`: an `exclusiveGateway` (`escalated?`) routes to a **service task**
+   `persist-task-escalation` (`pr.persist-task-escalation`) which writes the row + a denormalised
+   `open_task_escalation_id` pointer on the plan, then an **intermediate message-catch**
+   `wait-feature-answer` parks on `feature-escalation-answered` (correlationKey `=escalationCorrKey`).
+2. **Plan-review escalation** (`plan_review_escalations`) — a plan-review cap; a human returns a
+   `proceed | revise` directive. Same persist-service-task → message-catch shape
+   (`plan-escalation-answered`); the table is **append-only** and the review **epoch** is derived from
+   the count of answered rows.
+3. **PR review-loop escalation** (`open_escalation_*` columns on `pull_requests`, #597/#599) — a review
+   convergence that will not settle; surfaced via denormalised columns on the PR row.
+
+Answering, in every case, means: an app worker records the answer, **mirrors** it onto the task/PR row,
+**publishes the resume message**, and **re-surfaces** the next open escalation by rewriting a denormalised
+"oldest open" pointer. The "form" is a bespoke Urban page that fires when a pointer is set and prints the
+free-text `question`; the answer is a free-text string.
+
+This is a **user task + form, re-implemented by hand** — and the bug tail proves it. Every incident is a
+denormalised-pointer or free-text-contract failure: stale rows resurfacing a *dead* form after a re-plan
+(`refreshOpenTaskEscalation`), the "addressed-escalation paradox," `blank question fabricates an
+answerable escalation` (a hack to avoid an incident on an empty question), and per-run one-by-one row
+cleanup. None of these can occur under a single-source-of-truth user-task lifecycle.
+
+Crucially, **the primitives already exist**:
+
+- The engine has **native user tasks** — `UserTaskProps`, `Command::CompleteUserTask` / `UpdateUserTask`,
+  task listeners (ADR 0037), and `zeebe:assignmentDefinition` / priority / schedule parsed off the
+  `userTask` element (`engine-core/src/bpmn.rs`, `model.rs`).
+- Urban ships the **`taskInbox` surface** (ADR 0026): `GET /tasks` (list), `GET /tasks/api/tasks`
+  (`engine.searchUserTasks`), `POST /tasks/api/complete` (`engine.completeUserTask(key, variables)`),
+  rendering the linked **`.form`**. It is manifest-enabled (`surfaces.taskInbox`) and unused by nwf today.
+- Forms are `.form` assets; the Urban **form editor** (the "Delphi" authoring surface) is the tool that
+  authors them. This ADR is that editor's **first real internal customer**.
+
+## Decision
+
+**Model every decision-required escalation in nano-workforce as a native BPMN `userTask` with a linked
+`.form`, surfaced through Urban's `taskInbox`, completed with typed variables that resume the process.**
+Retire the bespoke `persist-escalation` service task → message-catch → resume-publish → denormalised-pointer
+machinery.
+
+### 1. A tiered taxonomy — not everything is a task
+
+The current code conflates three tiers; draw the line explicitly at each raise site:
+
+| Tier | Example | Mechanism |
+| --- | --- | --- |
+| **Transient** | empty-status backstop, re-request a review, a retriable step | stays **in-process** (retry / default arm) — **no task** |
+| **Advisory** | a hint, a note for the next agent | the **blackboard** (`app/blackboard.ts`) — never gates a flow |
+| **Decision-required** | proceed/revise, answer an open question, resolve a conflict, abandon | **user task + form** |
+
+Only the third tier becomes a user task. This retires the "fabricate a blank answerable escalation" hack:
+an empty question is a *non-escalation*, not a task.
+
+### 2. `serviceTask(persist) + message-catch(wait)` → one `userTask`
+
+Each `persist-*-escalation` service task and its paired intermediate message-catch collapse into a single
+`userTask` bearing a `zeebe:formDefinition` (linked `.form`) and a `zeebe:assignmentDefinition`. The engine
+owns the wait, the correlation, and the work-item state — so `escalationCorrKey`, the
+`feature-escalation-answered` / `plan-escalation-answered` messages, and the `pr.persist-*-escalation`
+workers are deleted. Completing the task carries typed variables straight back into the process.
+
+### 3. Forms are the typed escalation contract
+
+Each escalation kind gets a `.form` whose schema *is* its interface — replacing free-text question/answer:
+
+- **Task escalation** → `{ resolution: "answer" | "abandon", answer?: string }`.
+- **Plan-review escalation** → `{ directive: "proceed" | "revise", notes?: string }` — deleting the
+  hand-rolled `parsePlanEscalationDirective`; the enum + required-field validation live in the form/FEEL.
+- **Trial-merge escalation** → `{ action: "proceed" | "rebase" | "abandon", notes?: string }`.
+- **PR review-loop escalation** → `{ answer: string }` (or a kind-specific action enum).
+
+### 4. One queryable task list replaces three denormalised pointers
+
+`open_task_escalation_id`, `open_plan_escalation_id`, and the `open_escalation_*` columns on
+`pull_requests` all collapse into `engine.searchUserTasks(...)` — filterable by assignee, candidate group,
+process instance, element, age. There is **no "surfaced" field to go stale**, so the resurface / dead-form
+bug class is eliminated at the root. The plans page and any inbox read the live task search; the
+`inbox_entries` seed is the natural home for the cross-plan view.
+
+### 5. The assignee may be a human **or** an agent
+
+`zeebe:assignmentDefinition` routes a task to a specific human, a **candidate group** (e.g. the operator /
+crew leads), or — per ADR 0046 — an **agent**. An LLM worker can complete the *same* form a human would,
+via the `chat`/agent surface or a job-worker-style completer. This makes "auto-resolve with a
+slower/smarter model, else route to a human" a single lifecycle with one contract — something the bespoke
+subsystem cannot express. Agent-answered completion is still a first-class, audited task completion.
+
+### 6. SLA via a timer boundary
+
+A user task carries a due date; a **timer boundary event** provides escalation-of-the-escalation —
+reassign, notify, or auto-proceed on a default — the durable replacement for the review poller's ad-hoc
+nudge. A decision no longer hangs forever with no deadline.
+
+### 7. Audit trail from user-task history
+
+`plan_review_escalations` is append-only because the **review epoch** = count of answered plan-review
+escalations. Under this ADR the epoch is derived from **completed plan-review user tasks** (native user-task
+history / completion events), so the dedicated audit table is retired without losing the audit.
+
+## Consequences
+
+- **A whole bug class disappears.** No denormalised "surfaced" pointer ⇒ no stale/dead-form resurfacing, no
+  addressed-escalation paradox, no blank-question fabrication. The engine's single-source-of-truth
+  user-task lifecycle replaces three hand-maintained mirrors.
+- **Less code.** Delete `pr.persist-*-escalation` workers, the two resume messages + their catch events,
+  `escalationCorrKey`, `answerTaskEscalation`/`answerPlanEscalation`/`refreshOpenTaskEscalation`, the
+  denormalised columns, and the bespoke answer page — replaced by `userTask` nodes + `.form`s + the
+  existing `taskInbox` surface.
+- **Dogfoods the Delphi vision.** nwf becomes the first real consumer of the Urban form editor + user-task
+  inbox, exercising forms end to end on a live app.
+- **The third human-in-the-loop lane.** Enrolment (#152) = what work exists; visibility (#142) =
+  watch/nudge a *live* agent (ephemeral); **escalation-as-user-task** = decide *durably* when blocked. The
+  cockpit can list a worker's open escalation tasks; the two planes reinforce each other.
+- **Migration is a real refactor, not a rename.** The bespoke tables encode edge cases (epoch-from-count,
+  re-plan cleanup, trial-merge "proceed" override). The migration must preserve those semantics on the new
+  substrate and run behind tests, phased kind-by-kind.
+- **New dependency on engine user-task depth.** Assignment, candidate groups, task listeners, and timer
+  boundaries on user tasks must be exercised (some may surface gaps to file against the engine). Form
+  rendering richness is bounded by the `taskInbox`/form-editor state of the art.
+
+## Open questions
+
+- **Form-rendering fidelity.** The current `taskInbox` page is minimal (lists key/element). How rich a
+  `.form` render is needed before the answer page can be deleted — and is that the form editor's job or a
+  `taskInbox` upgrade (an nano-ide concern)?
+- **Agent-answer policy (§5).** When may an agent auto-complete vs must-route-to-human — a per-kind policy,
+  a confidence gate, or an operator toggle? How is an agent completion attributed and reversible?
+- **Assignment model.** Candidate group vs named assignee for each kind; where the operator's routing
+  preference is persisted (manifest vs app state).
+- **Cross-plan inbox surface.** Does nwf embed `taskInbox` directly, or render its own plan-aware inbox
+  page over `searchUserTasks` (matching the existing plans page), keyed through `inbox_entries`?
+- **Back-compat window.** Do in-flight escalations at migration time drain on the old path, or are they
+  re-issued as user tasks? (Prefer drain-old, issue-new, per kind.)