@nanobpm/urban 0.64.0 → 0.66.0

package/src/context/binding/resolver.ts

@@ -0,0 +1,176 @@
+// Slice S1 (binding) — the resolver: bind → validate → identity → resolved
+// handle, with private-per-app / shared-on-same-name semantics enforced two
+// ways:
+//
+//  1. In-process: a ContextResolver memoises by identity key, so two resolves of
+//     the same name return the SAME handle (and never double-clone), while
+//     distinct names get distinct handles.
+//  2. Across processes/instances: the on-disk location is derived
+//     deterministically from the identity slug under a shared cache root, so two
+//     Nano instances naming the same context share one working copy on disk.
+//     Known first-use limitation (deferred past slice S1): the single-flight in
+//     (1) is in-process only, so concurrent *first* resolves of the same context
+//     across instances can race materialisation (clone/pin). Sharing is reliable
+//     once the substrate exists; a follow-up slice adds an inter-process lock to
+//     make concurrent first-use safe too — see GitSubstrateBackend.materialise.
+
+import { homedir, tmpdir } from "node:os";
+import { join, resolve as resolvePath } from "node:path";
+import { parseContextBinding } from "./descriptor.ts";
+import { resolveContextIdentity } from "./identity.ts";
+import { GitSubstrateBackend } from "./git-backend.ts";
+import type { ResolvedContextHandle, SubstrateBackend } from "./backend.ts";
+
+/** Options for a {@link ContextResolver}. */
+export interface ContextResolverOptions {
+  /**
+   * Root directory under which per-context working copies are cloned. Two
+   * resolvers sharing a `cacheRoot` share substrates on disk. Defaults to
+   * {@link defaultContextCacheRoot}.
+   */
+  readonly cacheRoot?: string;
+  /**
+   * The substrate backend. Defaults to a git backend ({@link GitSubstrateBackend}).
+   * Injecting a different backend is the seam for a future PII/mutable or
+   * self-hosted substrate.
+   */
+  readonly backend?: SubstrateBackend;
+}
+
+/** Per-resolution overrides. */
+export interface ResolveOptions {
+  /**
+   * Controls whether a re-resolution re-fetches the substrate. Note the
+   * {@link ContextResolver} memoises per identity: once an identity has resolved,
+   * repeat resolves return the cached handle and do **not** re-fetch unless you
+   * explicitly pass `refresh: true`, which forces a fresh materialisation (a
+   * fetch + re-pin on the backend). While a materialisation is still in flight,
+   * concurrent resolves — including `refresh: true` — coalesce onto it rather
+   * than starting a second one. The backend's own default (fetch on an existing
+   * clone) therefore only applies the first time an identity is materialised or
+   * when `refresh: true` is passed. Defaults to `undefined` (reuse the memoised
+   * handle).
+   */
+  readonly refresh?: boolean;
+}
+
+/**
+ * The default cache root for context working copies. Honours
+ * `URBAN_CONTEXT_CACHE_DIR`, then `XDG_CACHE_HOME`, then `~/.cache`, falling
+ * back to the OS temp dir when no home directory is available.
+ */
+export function defaultContextCacheRoot(
+  env: Record<string, string | undefined> = process.env,
+): string {
+  if (env.URBAN_CONTEXT_CACHE_DIR) return env.URBAN_CONTEXT_CACHE_DIR;
+  if (env.XDG_CACHE_HOME) return join(env.XDG_CACHE_HOME, "urban", "context");
+  const home = safeHomedir();
+  if (home) return join(home, ".cache", "urban", "context");
+  return join(tmpdir(), "urban", "context");
+}
+
+/** `os.homedir()`, but tolerant: returns `undefined` if the home dir can't be
+ * determined (Node can throw here) so callers fall back to the temp dir. */
+function safeHomedir(): string | undefined {
+  try {
+    return homedir() || undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Resolves context bindings to concrete local working copies. A single resolver
+ * instance enforces shared-on-same-name in-process by memoising per identity
+ * key; distinct names stay private.
+ */
+export class ContextResolver {
+  readonly #cacheRoot: string;
+  readonly #backend: SubstrateBackend;
+  // Per-identity resolution record. Despite serving the single-flight guarantee,
+  // this map is NOT purged once a resolution settles: the settled record is
+  // retained as the long-lived memoisation cache backing shared-on-same-name, so
+  // repeat resolves return the identical handle. Entries are removed only on
+  // rejection (so a failed materialise can be retried); a fulfilled entry lives
+  // for the resolver's lifetime. Do not add "drop settled entries" cleanup here
+  // without also giving up memoisation.
+  readonly #resolutions = new Map<string, { promise: Promise<ResolvedContextHandle>; settled: boolean }>();
+
+  constructor(options: ContextResolverOptions = {}) {
+    // Normalise to an absolute path so a relative `cacheRoot` (or a relative
+    // `URBAN_CONTEXT_CACHE_DIR`) still yields an absolute `localPath`, honouring
+    // `SubstrateResolveOptions.localPath` ("Absolute path…"). Note this resolves
+    // a relative `cacheRoot` against *this* process's CWD, so the cross-process
+    // sharing promised in the module header only holds for an ABSOLUTE
+    // `cacheRoot`; a relative one is shared only among instances that happen to
+    // share a working directory.
+    this.#cacheRoot = resolvePath(options.cacheRoot ?? defaultContextCacheRoot());
+    this.#backend = options.backend ?? new GitSubstrateBackend();
+  }
+
+  /** The cache root this resolver clones into. */
+  get cacheRoot(): string {
+    return this.#cacheRoot;
+  }
+
+  /**
+   * Resolve a binding (validated first) to a {@link ResolvedContextHandle}. Two
+   * bindings that name the same context return the identical handle from this
+   * resolver; distinct names return distinct handles.
+   */
+  async resolve(
+    binding: unknown,
+    options: ResolveOptions = {},
+  ): Promise<ResolvedContextHandle> {
+    const parsed = parseContextBinding(binding);
+    const identity = resolveContextIdentity(parsed);
+    const localPath = join(this.#cacheRoot, identity.slug);
+
+    // Shared-on-same-name: concurrent or repeated resolves of one identity share
+    // a single materialisation. Coalesce onto an in-flight one regardless of
+    // `refresh` — it is already producing a fresh working copy, so starting a
+    // second `materialise()` would double-clone into the same `localPath` and
+    // break the single-in-flight guarantee. Only re-materialise once the prior
+    // resolution has settled AND the caller explicitly asked to `refresh`.
+    const existing = this.#resolutions.get(identity.key);
+    if (existing && (!existing.settled || options.refresh !== true)) {
+      return existing.promise;
+    }
+
+    const record: { promise: Promise<ResolvedContextHandle>; settled: boolean } = {
+      promise: this.#backend
+        .materialise(identity, { localPath, refresh: options.refresh })
+        .catch((error) => {
+          if (this.#resolutions.get(identity.key) === record) {
+            this.#resolutions.delete(identity.key);
+          }
+          throw error;
+        }),
+      settled: false,
+    };
+    this.#resolutions.set(identity.key, record);
+    record.promise.then(
+      () => {
+        record.settled = true;
+      },
+      () => {
+        // Rejection is surfaced to the caller via the returned promise; the map
+        // entry is already removed in the catch above.
+      },
+    );
+    return record.promise;
+  }
+}
+
+/**
+ * One-shot convenience: resolve a single binding with a fresh resolver. Prefer a
+ * long-lived {@link ContextResolver} when resolving many bindings so sharing is
+ * memoised across calls.
+ */
+export function resolveContextBinding(
+  binding: unknown,
+  options: ContextResolverOptions & ResolveOptions = {},
+): Promise<ResolvedContextHandle> {
+  const { cacheRoot, backend, ...resolveOptions } = options;
+  return new ContextResolver({ cacheRoot, backend }).resolve(binding, resolveOptions);
+}

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 };
 }