@nanobpm/urban 0.65.0 → 0.66.0

package/dist/runtime/core/manifest.d.ts

@@ -2,7 +2,8 @@ import type { HostContext } from "./host.ts";
 import type { AppManifest, InstanceTracking as SchemaInstanceTracking, Worker } from "@nanobpm/nano-app-schema";
 export type { ActionDecl, AppManifest, AppUi, ChatSurface, Connection, Data, DataSource, DomainField, DomainType, LlmBinding, Models, PagesSurface, Runtime, Security, Surfaces, TaskInboxSurface, Trigger, TriggerAction, Worker, } from "@nanobpm/nano-app-schema";
 /**
- * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector.
+ * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector and the
+ * `onWaitingHuman` wait-on-human edge (issue #355).
  *
  * `terminalStatuses` is landing in the canonical schema (`@nanobpm/nano-app-schema`,
  * Magikcraft/nano-bpm#769): an exclusion list — the runtime polls every row whose
@@ -16,6 +17,28 @@ export type InstanceTracking = SchemaInstanceTracking & {
     /** Values of `statusField` considered finished. When set, every row NOT in one of these
      *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
     readonly terminalStatuses?: readonly string[];
+    /**
+     * The reconciliation applied to a row whose instance is **parked waiting on a human** — the
+     * wait-state twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is
+     * waiting on a human *iff* it has an open user task, so the runtime derives this edge from
+     * engine truth (`openUserTasks`) rather than from a written column: on each poll, an active,
+     * non-terminated row whose instance has any open user task has this patch applied (typically
+     * `status = "awaiting_operator"`). Terminated wins over waiting-human (the {@link
+     * SchemaInstanceTracking.onTerminated} edge is applied first and excludes the key from this
+     * pass); a row with neither a terminated instance nor an open user task is left untouched, so
+     * the worker-owned transient status (running / converging / merging) survives.
+     *
+     * Optional and, like `terminalStatuses`, bridged locally until the canonical schema
+     * (`@nanobpm/nano-app-schema`) folds it in; drop this augmentation and re-export once the dep
+     * bump lands (No Drift Surfaces).
+     */
+    readonly onWaitingHuman?: {
+        /** Column → literal value patch written to a row whose instance has an open user task
+         *  (e.g. set the status to a "waiting on human" value). */
+        readonly set: {
+            readonly [k: string]: string | number | boolean | null;
+        };
+    };
 };
 /**
  * A status selector (`activeStatuses`/`terminalStatuses`) counts as *configured* only when it is

package/dist/runtime/core/modules/instance-tracking.d.ts

@@ -3,6 +3,12 @@ import { type InstanceTracking } from "../manifest.ts";
 import { type SchedulerDeps } from "./scheduler.ts";
 /** Default poll interval when a binding does not set `pollMs`. */
 export declare const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15000;
+/** Max in-flight `openUserTasks` probes per reconcile pass. The wait-on-human edge probes the
+ *  engine once per active, non-terminated key; probing them sequentially makes a pass O(N) network
+ *  round-trips and can make a single pass take longer than `pollMs` under a large active backlog.
+ *  Probing in bounded-parallel batches makes wall-clock time scale with max latency rather than
+ *  N×latency, while the cap keeps in-flight load on the engine bounded. */
+export declare const WAITING_HUMAN_PROBE_CONCURRENCY = 8;
 export interface InstanceTrackingHandle extends Mounted {
     /** `table.keyField` labels of the armed bindings, for `inspect()`. */
     readonly bindings: string[];
@@ -14,6 +20,14 @@ export interface InstanceTrackingHandle extends Mounted {
  *  once per TERMINATED key it discovers) and the cancel primitive (immediately when it terminates an
  *  instance) route through here, so the two can never drift on the patch or the log. */
 export declare function reconcileTerminatedKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
+/** Apply a binding's `onWaitingHuman.set` patch to the single row keyed by `processInstanceKey`
+ *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). The caller establishes
+ *  the precondition (the instance is non-terminated and has an open user task); this is the single
+ *  place that writes `onWaitingHuman.set` and logs the reconcile. Bindings without an
+ *  `onWaitingHuman` edge are no-ops, so callers can fan this over every binding. It skips the write
+ *  when the row already carries the patch (quiet-idempotent — a long-parked instance is re-polled
+ *  every tick and must not re-log). Returns rows changed. */
+export declare function reconcileWaitingHumanKey(api: Pick<AppApi, "data" | "log">, bindings: InstanceTracking[], processInstanceKey: string): Promise<number>;
 /**
  * Mount the `instanceTracking` reconciler: arm one poll loop per binding. Each loop selects
  * the active rows, asks the engine which of their instances are terminated, and applies the

package/dist/runtime/core/modules/instance-tracking.js

@@ -1,21 +1,45 @@
 // instance-tracking — the process-instance lifecycle reconciler (manifest `instanceTracking`).
 //
 // The problem it closes: an Urban app derives a row's status from the workers that run
-// along a process's *happy path*. When an instance instead reaches a terminal state with
-// no completion job — an operator/`cancelInstance` termination, or a crash — no worker
-// runs, so the read-model row stays "active" forever and any UI derived from it lies.
+// along a process's *happy path*. When an instance instead reaches an engine-truth state with
+// no worker to record it, the read-model row lies. Two such edges are reconciled declaratively:
 //
-// Each `instanceTracking` binding names a datasource table whose rows track an instance by
-// a key column. This module polls the engine for those rows' instances and, when one is
-// `TERMINATED`, applies the binding's `onTerminated.set` patch to the row. It deliberately
-// reconciles only on `TERMINATED` — the state that by definition runs no completion worker
-// — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
-// (reconciling it here would race that worker and could clobber a legitimately-completed
-// row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+//  - The **terminal** edge (`onTerminated`): each binding's poll asks the engine which of its
+//    active instances are `TERMINATED` and applies `onTerminated.set` (→ e.g. `abandoned`). A
+//    terminated instance runs no completion worker, so nothing else would ever close the row.
+//
+//  - The **wait-on-human** edge (`onWaitingHuman`, issue #355): the symmetric primitive for
+//    "this instance is parked waiting on a human." That state is authoritatively knowable — an
+//    instance is waiting on a human *iff* it has an open user task (`openUserTasks` =
+//    `searchUserTasks({state:"CREATED"})`) — for every process, forever, with no per-element
+//    registry. On each poll, an active, non-terminated row whose instance has any open user task
+//    has `onWaitingHuman.set` applied (typically `status = "awaiting_operator"`). This retires the
+//    per-subject imperative pattern (workers writing the status on escalate/answer plus a bespoke
+//    self-heal poller): the parked status becomes a derived view over the one user-task
+//    projection, so there is no second surface to drift (No Drift Surfaces).
+//
+// Precedence per active row, all derived from engine truth (never a worker write):
+//   terminated              -> onTerminated.set   (e.g. abandoned)      // terminal edge
+//   else has open user task  -> onWaitingHuman.set  (e.g. awaiting_operator)  // wait-on-human edge
+//   else                     -> leave the worker-owned transient status (running / converging / …)
+//
+// It deliberately reconciles the terminal edge only on `TERMINATED` — the state that by
+// definition runs no completion worker — and never on `COMPLETED`, whose terminal row-write the
+// app's own finalize worker owns (reconciling it here would race that worker and could clobber a
+// legitimately-completed row). The wait-on-human edge reads *open* user tasks via `openUserTasks`
+// (never a bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator`
+// onto a just-answered task). The poll is driven through the shared `SchedulerDeps` seam so tests
+// are deterministic.
 import { isConfiguredStatusSelector } from "../manifest.js";
 import { defaultScheduler, MAX_TIMER_DELAY_MS } from "./scheduler.js";
 /** Default poll interval when a binding does not set `pollMs`. */
 export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
+/** Max in-flight `openUserTasks` probes per reconcile pass. The wait-on-human edge probes the
+ *  engine once per active, non-terminated key; probing them sequentially makes a pass O(N) network
+ *  round-trips and can make a single pass take longer than `pollMs` under a large active backlog.
+ *  Probing in bounded-parallel batches makes wall-clock time scale with max latency rather than
+ *  N×latency, while the cap keeps in-flight load on the engine bounded. */
+export const WAITING_HUMAN_PROBE_CONCURRENCY = 8;
 /** Apply a binding's `onTerminated.set` patch to the single row keyed by `processInstanceKey`.
  *  Only the binding whose table owns that key has a matching row, so callers can fan this over
  *  every binding and let the no-match ones be no-ops. Returns rows changed. The single place that
@@ -40,8 +64,55 @@ export async function reconcileTerminatedKey(api, bindings, processInstanceKey)
     }
     return reconciled;
 }
+/** Whether `row` already satisfies `patch` on every column it sets — used to make the
+ *  wait-on-human writer quiet-idempotent. Unlike a terminated row (which flips to a terminal
+ *  status and then drops out of the active set), a row parked at a user task stays active and is
+ *  re-polled every tick, so re-writing/re-logging the same `awaiting_operator` patch on every poll
+ *  would be noise; skip the write when it would be a no-op. */
+function patchAlreadyApplied(row, set) {
+    return Object.entries(set).every(([col, value]) => row[col] === value);
+}
+/** Apply a binding's `onWaitingHuman.set` patch to the single row keyed by `processInstanceKey`
+ *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). The caller establishes
+ *  the precondition (the instance is non-terminated and has an open user task); this is the single
+ *  place that writes `onWaitingHuman.set` and logs the reconcile. Bindings without an
+ *  `onWaitingHuman` edge are no-ops, so callers can fan this over every binding. It skips the write
+ *  when the row already carries the patch (quiet-idempotent — a long-parked instance is re-polled
+ *  every tick and must not re-log). Returns rows changed. */
+export async function reconcileWaitingHumanKey(api, bindings, processInstanceKey) {
+    const key = String(processInstanceKey);
+    let reconciled = 0;
+    for (const binding of bindings) {
+        const onWaitingHuman = binding.onWaitingHuman;
+        if (!onWaitingHuman)
+            continue;
+        const table = api.data.table(binding.table, binding.keyField);
+        // Quiet-idempotence must consider EVERY row sharing this key, not just one. `keyField` need not
+        // be a unique column (e.g. a read model keyed on a non-PK `process_key`), and `table.update`
+        // patches ALL matching rows — so a `get()` (LIMIT 1) that happens to hit one already-patched row
+        // would skip the write and leave the OTHER matching rows unreconciled. Skip only when every
+        // matching row already carries the patch; otherwise fall through and re-patch them all.
+        const current = await table.find({ [binding.keyField]: key });
+        if (current.length > 0 && current.every((row) => patchAlreadyApplied(row, onWaitingHuman.set))) {
+            continue;
+        }
+        const changed = await table.update(key, onWaitingHuman.set);
+        if (changed > 0) {
+            reconciled += changed;
+            api.log("info", "instanceTracking: reconciled instance awaiting operator", {
+                table: binding.table,
+                keyField: binding.keyField,
+                processInstanceKey: key,
+                rowsChanged: changed,
+            });
+        }
+    }
+    return reconciled;
+}
 /** Poll one binding's instances once. Selects the active rows, asks the engine which of their
- *  instances are TERMINATED, and applies `onTerminated.set` to each. Returns how many keys were
+ *  instances are TERMINATED, and applies `onTerminated.set` to each; then, for the binding's
+ *  wait-on-human edge (`onWaitingHuman`, issue #355), applies `onWaitingHuman.set` to every
+ *  non-terminated active row whose instance has an open user task. Returns how many keys were
  *  scanned and how many rows were reconciled this tick. */
 async function reconcileOnce(api, binding) {
     const table = api.data.table(binding.table, binding.keyField);
@@ -97,13 +168,39 @@ async function reconcileOnce(api, binding) {
     // writes `onTerminated.set` and logs the reconcile — so the poll path and the cancel primitive
     // can never drift on the patch or its logging (No Drift Surfaces).
     let reconciled = 0;
+    const terminatedKeys = new Set();
     for (const snap of snapshots) {
         if (snap.state !== "TERMINATED")
             continue; // defensive; we asked for TERMINATED only
         if (!keyToRows.has(snap.processInstanceKey))
             continue; // not one we were tracking
+        terminatedKeys.add(snap.processInstanceKey);
         reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
     }
+    // Wait-on-human edge (issue #355), symmetric to onTerminated. Precedence: terminated wins, so a
+    // key reconciled as terminated above is excluded here. An instance is "waiting on a human" iff
+    // it has an open user task — the authoritative engine truth — so read `openUserTasks` (never a
+    // bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator` onto a
+    // just-answered task; issue #355 "instance B"). When there is no open user task the row is left
+    // untouched, so a worker-owned transient status (running / converging / merging) survives and a
+    // stale `awaiting_operator` is not re-latched. Because the condition is derived every tick, a
+    // re-escalation after an answer re-flips to `awaiting_operator` on the next poll by construction
+    // (issue #355 "instance A"). Probe in bounded-parallel batches (`WAITING_HUMAN_PROBE_CONCURRENCY`)
+    // so a pass over a large active backlog scales with max latency rather than N×latency.
+    if (binding.onWaitingHuman) {
+        const humanKeys = keys.filter((key) => !terminatedKeys.has(key)); // terminated already won
+        for (let i = 0; i < humanKeys.length; i += WAITING_HUMAN_PROBE_CONCURRENCY) {
+            const batch = humanKeys.slice(i, i + WAITING_HUMAN_PROBE_CONCURRENCY);
+            const perKey = await Promise.all(batch.map(async (key) => {
+                const openTasks = await api.engine.openUserTasks({ processInstanceKey: key });
+                if (openTasks.length === 0)
+                    return 0; // not parked on a human ⇒ leave the transient status
+                return reconcileWaitingHumanKey(api, [binding], key);
+            }));
+            for (const n of perKey)
+                reconciled += n;
+        }
+    }
     return { scanned: keys.length, reconciled };
 }
 /**

package/dist/runtime/core/validate.js

@@ -183,6 +183,21 @@ export function collectManifestIssues(m) {
                     message: "missing onTerminated.set patch (a non-empty column → value map)",
                 });
             }
+            // `onWaitingHuman` (issue #355) is the optional wait-on-human edge — the twin of
+            // `onTerminated`. It is optional (a binding may reconcile only the terminal edge), but when
+            // present its `set` must be a non-empty column → value patch for the same reason
+            // `onTerminated.set` must be: a reconciler with nothing to write is inert and almost
+            // certainly a mistake.
+            if (b?.onWaitingHuman !== undefined) {
+                const onWaitingHuman = isRecord(b.onWaitingHuman) ? b.onWaitingHuman : undefined;
+                const waitingSet = isRecord(onWaitingHuman?.set) ? onWaitingHuman.set : undefined;
+                if (!waitingSet || Object.keys(waitingSet).length === 0) {
+                    issues.push({
+                        path: `instanceTracking[${i}].onWaitingHuman.set`,
+                        message: "missing onWaitingHuman.set patch (a non-empty column → value map)",
+                    });
+                }
+            }
             // `activeStatuses` (fail-closed allow-list) and `terminalStatuses` (fail-open exclusion) are
             // both consumed as arrays of status strings. A malformed value — a bare string, or an array
             // holding a non-string/empty entry — would misbehave at runtime (`new Set("abandoned")`

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@nanobpm/urban",
-	"version": "0.65.0",
+	"version": "0.66.0",
 	"description": "Urban: build and run code-first apps on Nano — runtime, derivation toolkit, and CLI in one. Author durable processes with @nanobpm/workflow (defineFlow), a typed datasource, forms, triggers and surfaces from a nano.app.json manifest, on Node or Deno.",
 	"license": "Apache-2.0",
 	"type": "module",

package/src/runtime/core/manifest.ts

@@ -39,7 +39,8 @@ export type {
 } from "@nanobpm/nano-app-schema";
 
 /**
- * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector.
+ * `instanceTracking` binding, bridged to add the fail-open `terminalStatuses` selector and the
+ * `onWaitingHuman` wait-on-human edge (issue #355).
  *
  * `terminalStatuses` is landing in the canonical schema (`@nanobpm/nano-app-schema`,
  * Magikcraft/nano-bpm#769): an exclusion list — the runtime polls every row whose
@@ -53,6 +54,26 @@ export type InstanceTracking = SchemaInstanceTracking & {
   /** Values of `statusField` considered finished. When set, every row NOT in one of these
    *  is polled (fail-open). Requires `statusField`; mutually exclusive with `activeStatuses`. */
   readonly terminalStatuses?: readonly string[];
+  /**
+   * The reconciliation applied to a row whose instance is **parked waiting on a human** — the
+   * wait-state twin of {@link SchemaInstanceTracking.onTerminated} (issue #355). An instance is
+   * waiting on a human *iff* it has an open user task, so the runtime derives this edge from
+   * engine truth (`openUserTasks`) rather than from a written column: on each poll, an active,
+   * non-terminated row whose instance has any open user task has this patch applied (typically
+   * `status = "awaiting_operator"`). Terminated wins over waiting-human (the {@link
+   * SchemaInstanceTracking.onTerminated} edge is applied first and excludes the key from this
+   * pass); a row with neither a terminated instance nor an open user task is left untouched, so
+   * the worker-owned transient status (running / converging / merging) survives.
+   *
+   * Optional and, like `terminalStatuses`, bridged locally until the canonical schema
+   * (`@nanobpm/nano-app-schema`) folds it in; drop this augmentation and re-export once the dep
+   * bump lands (No Drift Surfaces).
+   */
+  readonly onWaitingHuman?: {
+    /** Column → literal value patch written to a row whose instance has an open user task
+     *  (e.g. set the status to a "waiting on human" value). */
+    readonly set: { readonly [k: string]: string | number | boolean | null };
+  };
 };
 
 /**

package/src/runtime/core/modules/instance-tracking.test.ts

@@ -9,11 +9,12 @@ import { makeGateway } from "./gateway.ts";
 import type { Table } from "./gateway.ts";
 import { DataLayer, type ProvisionedSource } from "./datasource.ts";
 import type { AppApi } from "../context.ts";
-import type { EngineClient, ProcessInstanceSnapshot } from "../host.ts";
+import type { EngineClient, ProcessInstanceSnapshot, UserTaskFilter, UserTaskSummary } from "../host.ts";
 import type { InstanceTracking } from "../manifest.ts";
 import {
   DEFAULT_INSTANCE_TRACKING_POLL_MS,
   mountInstanceTracking,
+  WAITING_HUMAN_PROBE_CONCURRENCY,
 } from "./instance-tracking.ts";
 import { MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./scheduler.ts";
 
@@ -63,13 +64,21 @@ function fakeScheduler(): SchedulerDeps & { advance: (ms: number) => Promise<voi
   };
 }
 
-/** An EngineClient whose only live method is searchProcessInstances, driven by a fixed map of
- *  processInstanceKey → state. Records the keys asked for on each call. */
-function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
+/** An EngineClient driven by a fixed map of processInstanceKey → state (for searchProcessInstances)
+ *  and an optional map of processInstanceKey → number-of-open-user-tasks (for openUserTasks, the
+ *  wait-on-human edge). Records the keys asked for on each call. `openUserTasks` models the engine
+ *  truth the reconciler derives `awaiting_operator` from — only *open* (CREATED) tasks count, so a
+ *  key absent from `openTasks` (or mapped to 0) reports no parked human. */
+function fakeEngine(
+  states: Record<string, ProcessInstanceSnapshot["state"]>,
+  openTasks: Record<string, number> = {},
+): {
   engine: EngineClient;
   queries: string[][];
+  userTaskQueries: (string | undefined)[];
 } {
   const queries: string[][] = [];
+  const userTaskQueries: (string | undefined)[] = [];
   const notUsed = (m: string) => (): never => {
     throw new Error(`fakeEngine.${m} is not exercised by this test`);
   };
@@ -91,18 +100,25 @@ function fakeEngine(states: Record<string, ProcessInstanceSnapshot["state"]>): {
       }
       return out;
     },
+    async openUserTasks(filter?: UserTaskFilter): Promise<UserTaskSummary[]> {
+      const key = filter?.processInstanceKey;
+      userTaskQueries.push(key);
+      const n = key ? (openTasks[key] ?? 0) : 0;
+      return Array.from({ length: n }, (_unused, i): UserTaskSummary => ({
+        userTaskKey: `${key}-t${i}`,
+      }));
+    },
     deployResources: notUsed("deployResources"),
     createInstance: notUsed("createInstance"),
     cancelInstance: notUsed("cancelInstance"),
     publishMessage: notUsed("publishMessage"),
     searchUserTasks: notUsed("searchUserTasks"),
-    openUserTasks: notUsed("openUserTasks"),
     getForm: notUsed("getForm"),
     completeUserTask: notUsed("completeUserTask"),
     registerWorker: notUsed("registerWorker"),
     close: notUsed("close"),
   };
-  return { engine, queries };
+  return { engine, queries, userTaskQueries };
 }
 
 interface Harness {
@@ -428,6 +444,176 @@ for (const bad of [0, -1000, Number.NaN]) {
 }
 
 
+// ── Wait-on-human edge (onWaitingHuman, issue #355) ────────────────────────────────────────────
+
+// A binding that reconciles both engine-truth edges: terminal (onTerminated) and wait-on-human
+// (onWaitingHuman). terminalStatuses (fail-open) keeps every non-abandoned row polled so a stale
+// worker-written transient status (converging/merging/running) is still reconciled to awaiting.
+const waitingBinding = (over: Partial<InstanceTracking> = {}): InstanceTracking => ({
+  table: "plans",
+  keyField: "process_key",
+  statusField: "status",
+  terminalStatuses: ["abandoned"],
+  onTerminated: { set: { status: "abandoned", note: null } },
+  onWaitingHuman: { set: { status: "awaiting_operator" } },
+  pollMs: 1000,
+  ...over,
+});
+
+test("derives awaiting_operator for a row whose instance has an open user task (forward)", async () => {
+  // The row carries a STALE worker-written transient status; the instance is parked at a user task.
+  // One reconcile pass must read it back as awaiting_operator — derived, not written.
+  const { engine } = fakeEngine({ pi1: "ACTIVE" }, { pi1: 1 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "converging", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  assert.equal((await h.table.get("pi1"))?.status, "awaiting_operator");
+  await handle.stop();
+  await h.close();
+});
+
+test("leaves the worker-owned transient status when the instance has NO open user task (backward)", async () => {
+  // No open user task and not terminated ⇒ the reconciler must not force awaiting_operator; the
+  // worker-owned transient status survives. This is the "must not remain awaiting_operator once the
+  // task completes" leg: a just-answered instance (task completed, worker wrote converging) is not
+  // re-latched to awaiting_operator.
+  const { engine } = fakeEngine({ pi1: "ACTIVE" }, { pi1: 0 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "converging", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  assert.equal((await h.table.get("pi1"))?.status, "converging");
+  await handle.stop();
+  await h.close();
+});
+
+test("re-escalation after an answer re-flips to awaiting_operator on the next poll (instance A)", async () => {
+  // The re-escalation-after-answer defect (nano-workforce#318): the row sits at converging after an
+  // answer; a re-escalation opens a NEW user task. Because the status is DERIVED every tick, the
+  // next poll re-flips it to awaiting_operator by construction — no bespoke poller, no stuck state.
+  const openTasks: Record<string, number> = { pi1: 0 }; // answered: task completed, none open
+  const { engine } = fakeEngine({ pi1: "ACTIVE" }, openTasks);
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "converging", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  assert.equal((await h.table.get("pi1"))?.status, "converging"); // still converging: no open task
+  openTasks.pi1 = 1; // re-escalation: a new user task opens
+  await sched.advance(1000);
+  assert.equal((await h.table.get("pi1"))?.status, "awaiting_operator"); // re-flipped
+  await handle.stop();
+  await h.close();
+});
+
+test("terminated wins over an open user task (precedence)", async () => {
+  // A terminated instance that also (transiently) reports an open user task must reconcile to the
+  // terminal patch, never awaiting_operator — onTerminated has precedence.
+  const { engine, userTaskQueries } = fakeEngine({ pi1: "TERMINATED" }, { pi1: 1 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "converging", note: "x" });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  const row = await h.table.get("pi1");
+  assert.equal(row?.status, "abandoned");
+  assert.equal(row?.note, null);
+  assert.deepEqual(userTaskQueries, []); // terminated key was excluded before the openUserTasks probe
+  await handle.stop();
+  await h.close();
+});
+
+test("does not re-write or re-log a row already at awaiting_operator (quiet-idempotent)", async () => {
+  // A long-parked instance is re-polled every tick. The wait-on-human writer must be a no-op when
+  // the row already carries the patch, so it does not re-log on every poll.
+  const { engine } = fakeEngine({ pi1: "ACTIVE" }, { pi1: 1 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  await sched.advance(1000);
+  assert.equal((await h.table.get("pi1"))?.status, "awaiting_operator");
+  const awaitingLogs = h.logs.filter((l) => l.msg.includes("awaiting operator"));
+  assert.equal(awaitingLogs.length, 0); // no-op patch never logged
+  await handle.stop();
+  await h.close();
+});
+
+test("a binding without onWaitingHuman never probes open user tasks (edge is opt-in)", async () => {
+  const { engine, userTaskQueries } = fakeEngine({ pi1: "ACTIVE" }, { pi1: 1 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "dispatched", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [planBinding()], sched); // planBinding has no onWaitingHuman
+  await sched.advance(1000);
+  assert.deepEqual(userTaskQueries, []); // never probed
+  assert.equal((await h.table.get("pi1"))?.status, "dispatched"); // untouched
+  await handle.stop();
+  await h.close();
+});
+
+test("reconciles EVERY row sharing a non-unique key, even when one is already patched (multi-row)", async () => {
+  // `keyField` (process_key) is NOT unique here, and table.update patches ALL matching rows. The
+  // quiet-idempotence check must consider every matching row, not a single get() (LIMIT 1): with two
+  // rows on the same process_key — one already awaiting_operator, one still converging — a LIMIT-1
+  // probe that hits the patched row would skip the write and strand the other. Both must converge.
+  const { engine } = fakeEngine({ pi1: "ACTIVE" }, { pi1: 1 });
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    await t.insert({ plan_key: "p1", process_key: "pi1", status: "awaiting_operator", note: null });
+    await t.insert({ plan_key: "p2", process_key: "pi1", status: "converging", note: null });
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  const rows = await h.table.find({ process_key: "pi1" });
+  assert.deepEqual(
+    rows.map((r) => r.status).sort(),
+    ["awaiting_operator", "awaiting_operator"],
+  );
+  await handle.stop();
+  await h.close();
+});
+
+test("reconciles every parked key across multiple probe batches (bounded-parallel probing)", async () => {
+  // More active keys than WAITING_HUMAN_PROBE_CONCURRENCY forces multiple probe batches. Every key
+  // with an open user task must still be probed and reconciled — the batching must not drop keys.
+  const total = WAITING_HUMAN_PROBE_CONCURRENCY * 2 + 3; // spans three batches
+  const states: Record<string, ProcessInstanceSnapshot["state"]> = {};
+  const openTasks: Record<string, number> = {};
+  for (let i = 0; i < total; i++) {
+    states[`pi${i}`] = "ACTIVE";
+    openTasks[`pi${i}`] = i % 2; // half parked on a human, half not
+  }
+  const { engine, userTaskQueries } = fakeEngine(states, openTasks);
+  const h = await withHarness(engine, PLANS_DDL, async (t) => {
+    for (let i = 0; i < total; i++) {
+      await t.insert({ plan_key: `p${i}`, process_key: `pi${i}`, status: "converging", note: null });
+    }
+  });
+  const sched = fakeScheduler();
+  const handle = mount(h, [waitingBinding()], sched);
+  await sched.advance(1000);
+  // Every active key was probed exactly once.
+  assert.equal(userTaskQueries.length, total);
+  assert.deepEqual([...userTaskQueries].sort(), Object.keys(states).sort());
+  for (let i = 0; i < total; i++) {
+    const expected = i % 2 === 1 ? "awaiting_operator" : "converging";
+    assert.equal((await h.table.get(`pi${i}`))?.status, expected, `pi${i}`);
+  }
+  await handle.stop();
+  await h.close();
+});
+
 function mount(h: Harness, bindings: InstanceTracking[], sched: SchedulerDeps) {
   h.api.manifest.instanceTracking = bindings;
   return mountInstanceTracking(

package/src/runtime/core/modules/instance-tracking.ts

@@ -1,17 +1,35 @@
 // instance-tracking — the process-instance lifecycle reconciler (manifest `instanceTracking`).
 //
 // The problem it closes: an Urban app derives a row's status from the workers that run
-// along a process's *happy path*. When an instance instead reaches a terminal state with
-// no completion job — an operator/`cancelInstance` termination, or a crash — no worker
-// runs, so the read-model row stays "active" forever and any UI derived from it lies.
+// along a process's *happy path*. When an instance instead reaches an engine-truth state with
+// no worker to record it, the read-model row lies. Two such edges are reconciled declaratively:
 //
-// Each `instanceTracking` binding names a datasource table whose rows track an instance by
-// a key column. This module polls the engine for those rows' instances and, when one is
-// `TERMINATED`, applies the binding's `onTerminated.set` patch to the row. It deliberately
-// reconciles only on `TERMINATED` — the state that by definition runs no completion worker
-// — and never on `COMPLETED`, whose terminal row-write the app's own finalize worker owns
-// (reconciling it here would race that worker and could clobber a legitimately-completed
-// row). The poll is driven through the shared `SchedulerDeps` seam so tests are deterministic.
+//  - The **terminal** edge (`onTerminated`): each binding's poll asks the engine which of its
+//    active instances are `TERMINATED` and applies `onTerminated.set` (→ e.g. `abandoned`). A
+//    terminated instance runs no completion worker, so nothing else would ever close the row.
+//
+//  - The **wait-on-human** edge (`onWaitingHuman`, issue #355): the symmetric primitive for
+//    "this instance is parked waiting on a human." That state is authoritatively knowable — an
+//    instance is waiting on a human *iff* it has an open user task (`openUserTasks` =
+//    `searchUserTasks({state:"CREATED"})`) — for every process, forever, with no per-element
+//    registry. On each poll, an active, non-terminated row whose instance has any open user task
+//    has `onWaitingHuman.set` applied (typically `status = "awaiting_operator"`). This retires the
+//    per-subject imperative pattern (workers writing the status on escalate/answer plus a bespoke
+//    self-heal poller): the parked status becomes a derived view over the one user-task
+//    projection, so there is no second surface to drift (No Drift Surfaces).
+//
+// Precedence per active row, all derived from engine truth (never a worker write):
+//   terminated              -> onTerminated.set   (e.g. abandoned)      // terminal edge
+//   else has open user task  -> onWaitingHuman.set  (e.g. awaiting_operator)  // wait-on-human edge
+//   else                     -> leave the worker-owned transient status (running / converging / …)
+//
+// It deliberately reconciles the terminal edge only on `TERMINATED` — the state that by
+// definition runs no completion worker — and never on `COMPLETED`, whose terminal row-write the
+// app's own finalize worker owns (reconciling it here would race that worker and could clobber a
+// legitimately-completed row). The wait-on-human edge reads *open* user tasks via `openUserTasks`
+// (never a bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator`
+// onto a just-answered task). The poll is driven through the shared `SchedulerDeps` seam so tests
+// are deterministic.
 
 import type { AppApi, Mounted, RuntimeContext } from "../context.ts";
 import { type InstanceTracking, isConfiguredStatusSelector } from "../manifest.ts";
@@ -20,6 +38,13 @@ import { defaultScheduler, MAX_TIMER_DELAY_MS, type SchedulerDeps } from "./sche
 /** Default poll interval when a binding does not set `pollMs`. */
 export const DEFAULT_INSTANCE_TRACKING_POLL_MS = 15_000;
 
+/** Max in-flight `openUserTasks` probes per reconcile pass. The wait-on-human edge probes the
+ *  engine once per active, non-terminated key; probing them sequentially makes a pass O(N) network
+ *  round-trips and can make a single pass take longer than `pollMs` under a large active backlog.
+ *  Probing in bounded-parallel batches makes wall-clock time scale with max latency rather than
+ *  N×latency, while the cap keeps in-flight load on the engine bounded. */
+export const WAITING_HUMAN_PROBE_CONCURRENCY = 8;
+
 export interface InstanceTrackingHandle extends Mounted {
   /** `table.keyField` labels of the armed bindings, for `inspect()`. */
   readonly bindings: string[];
@@ -56,8 +81,60 @@ export async function reconcileTerminatedKey(
   return reconciled;
 }
 
+/** Whether `row` already satisfies `patch` on every column it sets — used to make the
+ *  wait-on-human writer quiet-idempotent. Unlike a terminated row (which flips to a terminal
+ *  status and then drops out of the active set), a row parked at a user task stays active and is
+ *  re-polled every tick, so re-writing/re-logging the same `awaiting_operator` patch on every poll
+ *  would be noise; skip the write when it would be a no-op. */
+function patchAlreadyApplied(row: Row, set: Record<string, string | number | boolean | null>): boolean {
+  return Object.entries(set).every(([col, value]) => row[col] === value);
+}
+
+/** Apply a binding's `onWaitingHuman.set` patch to the single row keyed by `processInstanceKey`
+ *  — the wait-on-human twin of {@link reconcileTerminatedKey} (issue #355). The caller establishes
+ *  the precondition (the instance is non-terminated and has an open user task); this is the single
+ *  place that writes `onWaitingHuman.set` and logs the reconcile. Bindings without an
+ *  `onWaitingHuman` edge are no-ops, so callers can fan this over every binding. It skips the write
+ *  when the row already carries the patch (quiet-idempotent — a long-parked instance is re-polled
+ *  every tick and must not re-log). Returns rows changed. */
+export async function reconcileWaitingHumanKey(
+  api: Pick<AppApi, "data" | "log">,
+  bindings: InstanceTracking[],
+  processInstanceKey: string,
+): Promise<number> {
+  const key = String(processInstanceKey);
+  let reconciled = 0;
+  for (const binding of bindings) {
+    const onWaitingHuman = binding.onWaitingHuman;
+    if (!onWaitingHuman) continue;
+    const table = api.data.table<Row>(binding.table, binding.keyField);
+    // Quiet-idempotence must consider EVERY row sharing this key, not just one. `keyField` need not
+    // be a unique column (e.g. a read model keyed on a non-PK `process_key`), and `table.update`
+    // patches ALL matching rows — so a `get()` (LIMIT 1) that happens to hit one already-patched row
+    // would skip the write and leave the OTHER matching rows unreconciled. Skip only when every
+    // matching row already carries the patch; otherwise fall through and re-patch them all.
+    const current = await table.find({ [binding.keyField]: key });
+    if (current.length > 0 && current.every((row) => patchAlreadyApplied(row, onWaitingHuman.set))) {
+      continue;
+    }
+    const changed = await table.update(key, onWaitingHuman.set);
+    if (changed > 0) {
+      reconciled += changed;
+      api.log("info", "instanceTracking: reconciled instance awaiting operator", {
+        table: binding.table,
+        keyField: binding.keyField,
+        processInstanceKey: key,
+        rowsChanged: changed,
+      });
+    }
+  }
+  return reconciled;
+}
+
 /** Poll one binding's instances once. Selects the active rows, asks the engine which of their
- *  instances are TERMINATED, and applies `onTerminated.set` to each. Returns how many keys were
+ *  instances are TERMINATED, and applies `onTerminated.set` to each; then, for the binding's
+ *  wait-on-human edge (`onWaitingHuman`, issue #355), applies `onWaitingHuman.set` to every
+ *  non-terminated active row whose instance has an open user task. Returns how many keys were
  *  scanned and how many rows were reconciled this tick. */
 async function reconcileOnce(
   api: AppApi,
@@ -116,11 +193,38 @@ async function reconcileOnce(
   // writes `onTerminated.set` and logs the reconcile — so the poll path and the cancel primitive
   // can never drift on the patch or its logging (No Drift Surfaces).
   let reconciled = 0;
+  const terminatedKeys = new Set<string>();
   for (const snap of snapshots) {
     if (snap.state !== "TERMINATED") continue; // defensive; we asked for TERMINATED only
     if (!keyToRows.has(snap.processInstanceKey)) continue; // not one we were tracking
+    terminatedKeys.add(snap.processInstanceKey);
     reconciled += await reconcileTerminatedKey(api, [binding], snap.processInstanceKey);
   }
+
+  // Wait-on-human edge (issue #355), symmetric to onTerminated. Precedence: terminated wins, so a
+  // key reconciled as terminated above is excluded here. An instance is "waiting on a human" iff
+  // it has an open user task — the authoritative engine truth — so read `openUserTasks` (never a
+  // bare `searchUserTasks`, which lags a completion and would latch `awaiting_operator` onto a
+  // just-answered task; issue #355 "instance B"). When there is no open user task the row is left
+  // untouched, so a worker-owned transient status (running / converging / merging) survives and a
+  // stale `awaiting_operator` is not re-latched. Because the condition is derived every tick, a
+  // re-escalation after an answer re-flips to `awaiting_operator` on the next poll by construction
+  // (issue #355 "instance A"). Probe in bounded-parallel batches (`WAITING_HUMAN_PROBE_CONCURRENCY`)
+  // so a pass over a large active backlog scales with max latency rather than N×latency.
+  if (binding.onWaitingHuman) {
+    const humanKeys = keys.filter((key) => !terminatedKeys.has(key)); // terminated already won
+    for (let i = 0; i < humanKeys.length; i += WAITING_HUMAN_PROBE_CONCURRENCY) {
+      const batch = humanKeys.slice(i, i + WAITING_HUMAN_PROBE_CONCURRENCY);
+      const perKey = await Promise.all(
+        batch.map(async (key): Promise<number> => {
+          const openTasks = await api.engine.openUserTasks({ processInstanceKey: key });
+          if (openTasks.length === 0) return 0; // not parked on a human ⇒ leave the transient status
+          return reconcileWaitingHumanKey(api, [binding], key);
+        }),
+      );
+      for (const n of perKey) reconciled += n;
+    }
+  }
   return { scanned: keys.length, reconciled };
 }
 

package/src/runtime/core/validate.test.ts

@@ -166,6 +166,52 @@ test("an instanceTracking binding missing table/keyField/onTerminated.set is fla
   assert.ok(issues.some((i) => i.path === "instanceTracking[0].onTerminated.set"));
 });
 
+test("an instanceTracking binding with a well-formed onWaitingHuman.set has no issues", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        statusField: "status",
+        terminalStatuses: ["abandoned"],
+        onTerminated: { set: { status: "abandoned" } },
+        onWaitingHuman: { set: { status: "awaiting_operator" } },
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});
+
+test("an instanceTracking onWaitingHuman with an empty set patch is flagged", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        onTerminated: { set: { status: "abandoned" } },
+        onWaitingHuman: { set: {} },
+      },
+    ],
+  });
+  assert.ok(issues.some((i) => i.path === "instanceTracking[0].onWaitingHuman.set"));
+});
+
+test("an instanceTracking binding omitting onWaitingHuman is valid (the edge is opt-in)", () => {
+  const issues = collectManifestIssues({
+    ...valid,
+    instanceTracking: [
+      {
+        table: "plans",
+        keyField: "process_key",
+        onTerminated: { set: { status: "abandoned" } },
+      },
+    ],
+  });
+  assert.deepEqual(issues, []);
+});
+
 test("instanceTracking activeStatuses without statusField is flagged", () => {
   const issues = collectManifestIssues({
     ...valid,

package/src/runtime/core/validate.ts

@@ -201,6 +201,21 @@ export function collectManifestIssues(m: unknown): ValidationIssue[] {
           message: "missing onTerminated.set patch (a non-empty column → value map)",
         });
       }
+      // `onWaitingHuman` (issue #355) is the optional wait-on-human edge — the twin of
+      // `onTerminated`. It is optional (a binding may reconcile only the terminal edge), but when
+      // present its `set` must be a non-empty column → value patch for the same reason
+      // `onTerminated.set` must be: a reconciler with nothing to write is inert and almost
+      // certainly a mistake.
+      if (b?.onWaitingHuman !== undefined) {
+        const onWaitingHuman = isRecord(b.onWaitingHuman) ? b.onWaitingHuman : undefined;
+        const waitingSet = isRecord(onWaitingHuman?.set) ? onWaitingHuman.set : undefined;
+        if (!waitingSet || Object.keys(waitingSet).length === 0) {
+          issues.push({
+            path: `instanceTracking[${i}].onWaitingHuman.set`,
+            message: "missing onWaitingHuman.set patch (a non-empty column → value map)",
+          });
+        }
+      }
       // `activeStatuses` (fail-closed allow-list) and `terminalStatuses` (fail-open exclusion) are
       // both consumed as arrays of status strings. A malformed value — a bare string, or an array
       // holding a non-string/empty entry — would misbehave at runtime (`new Set("abandoned")`