@nanobpm/urban 0.64.0 → 0.66.0

package/dist/context/binding/identity.js

@@ -0,0 +1,159 @@
+// Slice S1 (binding) — context *identity*: the private-per-app /
+// shared-on-same-name semantics.
+//
+// A context is named by its `(repo, ref)` pair. Two apps (or two Nano
+// instances) that name the SAME context — the same normalised repo and the same
+// ref — resolve to the SAME shared substrate; a distinct name stays private.
+// This module turns a binding into a stable, canonical **identity key** that
+// the resolver uses both to memoise in-process and to derive an on-disk
+// location, so "same name ⇒ same substrate" holds within a process AND across
+// processes/instances that share a cache root.
+import { createHash } from "node:crypto";
+import { isAbsolute, resolve as resolvePath } from "node:path";
+import { fileURLToPath } from "node:url";
+const SHORTHAND = /^[\w.-]+\/[\w.-]+$/;
+const SCHEME_URL = /^[a-z][a-z0-9+.-]*:\/\//i;
+const SCP_LIKE = /^[\w.-]+@([\w.-]+):(.+)$/; // git@github.com:owner/name.git
+function stripGitSuffix(value) {
+    // Trim trailing slashes BEFORE stripping `.git` so a trailing-slash spelling
+    // (`owner/name.git/`, a URL pathname ending `.git/`) still has its `.git`
+    // suffix removed — otherwise `.git$` would not match and equivalent repo
+    // spellings would canonicalise to different identities (different substrates).
+    // Trim once more afterwards to drop any slash exposed by removing the suffix.
+    return value.replace(/\/+$/, "").replace(/\.git$/i, "").replace(/\/+$/, "");
+}
+// A URL's scheme-default port is equivalent to omitting the port, so it must not
+// split identity. `URL` already strips the default port for the web schemes it
+// knows (http/https/ws/…), but NOT for git transports like ssh:// and git://, so
+// their defaults are normalised here explicitly.
+const DEFAULT_PORTS = {
+    "http:": "80",
+    "https:": "443",
+    "ssh:": "22",
+    "git:": "9418",
+    "ftp:": "21",
+};
+/**
+ * The canonical authority (`host` or `host:port`) for a scheme URL identity.
+ * Excludes any `user:pass@` userinfo (uses `hostname`, never `host`) so
+ * credentials never affect identity, and drops a scheme's DEFAULT port while
+ * retaining any NON-default port as a distinguishing factor.
+ */
+function canonicalAuthority(parsed) {
+    const host = parsed.hostname.toLowerCase();
+    const defaultPort = DEFAULT_PORTS[parsed.protocol.toLowerCase()];
+    if (parsed.port && parsed.port !== defaultPort) {
+        return `${host}:${parsed.port}`;
+    }
+    return host;
+}
+/**
+ * Resolve a `file://` URL to an absolute filesystem path, honouring the host
+ * component and percent-encoding. Falls back to naive `file://` stripping for a
+ * malformed URL so identity stays stable rather than throwing.
+ */
+function fileUrlToAbsPath(raw) {
+    try {
+        return resolvePath(fileURLToPath(raw));
+    }
+    catch {
+        return resolvePath(raw.slice("file://".length));
+    }
+}
+/**
+ * Classify a binding `repo` field into a concrete clone URL plus a normalised
+ * canonical form for identity. Public git is NOT hard-coded: local/`file://`
+ * paths and arbitrary git hosts are first-class, leaving a seam for a future
+ * PII/mutable or self-hosted substrate backend.
+ */
+function classifyRepo(repo) {
+    const raw = repo.trim();
+    // Local filesystem path or file:// URL — used for tests and self-hosted
+    // substrates. Canonicalised by absolute path so two spellings of one path
+    // share identity. `file://` URLs are parsed via `fileURLToPath` so the host
+    // component (e.g. `file://localhost/…`) and percent-encoding are handled and
+    // equivalent spellings map to one identity.
+    if (raw.startsWith("file://")) {
+        const abs = fileUrlToAbsPath(raw);
+        return { url: raw, canonical: `file:${abs}` };
+    }
+    if (raw.startsWith(".") || isAbsolute(raw)) {
+        const abs = resolvePath(raw);
+        return { url: abs, canonical: `file:${abs}` };
+    }
+    // owner/name shorthand ⇒ GitHub HTTPS clone URL.
+    if (SHORTHAND.test(raw)) {
+        const canonical = `github.com/${stripGitSuffix(raw).toLowerCase()}`;
+        return { url: `https://github.com/${stripGitSuffix(raw)}.git`, canonical };
+    }
+    // scp-like git URL: git@host:owner/name(.git)
+    const scp = SCP_LIKE.exec(raw);
+    if (scp) {
+        const host = scp[1].toLowerCase();
+        const path = stripGitSuffix(scp[2]).toLowerCase();
+        return { url: raw, canonical: `${host}/${path}` };
+    }
+    // scheme URL: https://, ssh://, git://, http://
+    if (SCHEME_URL.test(raw)) {
+        try {
+            const parsed = new URL(raw);
+            // Build the authority from `hostname` (never `host`) so any `user:pass@`
+            // userinfo is excluded — credentials never affect identity. The port is
+            // *normalised*, not dropped: a scheme's DEFAULT port collapses to the
+            // portless spelling (so `https://h:443/o/n` ≡ `https://h/o/n` and
+            // `ssh://h:22/o/n` ≡ `ssh://h/o/n`), but a NON-default port is retained as
+            // a distinguishing factor — two remotes on the same host but different
+            // ports are genuinely different repos and MUST NOT share a substrate.
+            const host = canonicalAuthority(parsed);
+            const path = stripGitSuffix(parsed.pathname).replace(/^\/+/, "").toLowerCase();
+            return { url: raw, canonical: `${host}/${path}` };
+        }
+        catch {
+            // Fall through to the opaque case below.
+        }
+    }
+    // Anything else: treat opaquely but still stable.
+    return { url: raw, canonical: stripGitSuffix(raw).toLowerCase() };
+}
+function toSlug(canonical, ref, hash) {
+    const readable = `${canonical}@${ref}`
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 48);
+    // Suffix with the FULL identity key (sha256 hex), not a truncated prefix: the
+    // on-disk location is derived from the slug, so a truncated suffix would make
+    // two distinct keys collide onto one `localPath` (breaking "distinct names
+    // stay private") far sooner than the key itself collides. Deriving the suffix
+    // from the whole key keeps on-disk uniqueness exactly as strong as the
+    // in-process sharing key — a single source of truth, distinct keys ⇒ distinct
+    // slugs.
+    return `${readable || "context"}-${hash}`;
+}
+/**
+ * Compute the canonical {@link ContextIdentity} for a binding. Deterministic and
+ * pure: equal `(repo, ref)` names (after normalisation) always produce an equal
+ * `key` and `slug`. Distinct names are collision-resistant, not collision-proof:
+ * both `key` and `slug` are sha256-derived, so two distinct names collide only on
+ * a full sha256 collision (the `slug` embeds the whole `key`, so it is exactly as
+ * strong as the `key`).
+ */
+export function resolveContextIdentity(binding) {
+    const { url, canonical } = classifyRepo(binding.repo);
+    const ref = binding.ref.trim();
+    const canonicalName = `${canonical}#${ref}`;
+    const key = createHash("sha256").update(canonicalName, "utf8").digest("hex");
+    return { key, repo: url, ref, slug: toSlug(canonical, ref, key) };
+}
+/**
+ * The stable identity key of a binding — the sharing primitive. Two bindings
+ * resolve to the same shared substrate iff this returns the same value for
+ * both.
+ */
+export function contextIdentityKey(binding) {
+    return resolveContextIdentity(binding).key;
+}
+/** `true` iff two bindings name the same shared context (same substrate). */
+export function sameContext(a, b) {
+    return contextIdentityKey(a) === contextIdentityKey(b);
+}

package/dist/context/binding/index.d.ts

@@ -1 +1,5 @@
-export {};
+export { type ContextBinding, ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.ts";
+export { type ContextIdentity, contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.ts";
+export { type ResolvedContextHandle, type SubstrateBackend, type SubstrateResolveOptions, } from "./backend.ts";
+export { GitSubstrateBackend, type GitRunner, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.ts";
+export { ContextResolver, type ContextResolverOptions, type ResolveOptions, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.ts";

package/dist/context/binding/index.js

@@ -1 +1,14 @@
-export {};
+// @nanobpm/urban/context/binding — slice S1.
+//
+// The bindable `context` resource: the binding descriptor (`uses: context:
+// { repo, ref }`) plus local↔remote resolution to a resolved handle, with
+// private-per-app / shared-on-same-name identity semantics. This is one half of
+// the published contract nanobpm/nano-workforce#291 builds against.
+//
+// Downstream: S3 (git substrate/governance) and S4 (retrieval) consume the
+// ResolvedContextHandle; the SubstrateBackend interface is the seam for a
+// future PII/mutable or self-hosted backend.
+export { ContextBindingError, isContextBinding, parseContextBinding, } from "./descriptor.js";
+export { contextIdentityKey, resolveContextIdentity, sameContext, } from "./identity.js";
+export { GitSubstrateBackend, GIT_SAFETY_CONFIG, hardenedGitArgs, SubstrateResolveError, } from "./git-backend.js";
+export { ContextResolver, defaultContextCacheRoot, resolveContextBinding, } from "./resolver.js";

package/dist/context/binding/resolver.d.ts

@@ -0,0 +1,61 @@
+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 declare function defaultContextCacheRoot(env?: Record<string, string | undefined>): string;
+/**
+ * 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 declare class ContextResolver {
+    #private;
+    constructor(options?: ContextResolverOptions);
+    /** The cache root this resolver clones into. */
+    get cacheRoot(): string;
+    /**
+     * 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.
+     */
+    resolve(binding: unknown, options?: ResolveOptions): Promise<ResolvedContextHandle>;
+}
+/**
+ * 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 declare function resolveContextBinding(binding: unknown, options?: ContextResolverOptions & ResolveOptions): Promise<ResolvedContextHandle>;

package/dist/context/binding/resolver.js

@@ -0,0 +1,125 @@
+// 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.js";
+import { resolveContextIdentity } from "./identity.js";
+import { GitSubstrateBackend } from "./git-backend.js";
+/**
+ * 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 = process.env) {
+    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() {
+    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 {
+    #cacheRoot;
+    #backend;
+    // 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.
+    #resolutions = new Map();
+    constructor(options = {}) {
+        // 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() {
+        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, options = {}) {
+        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: 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, options = {}) {
+    const { cacheRoot, backend, ...resolveOptions } = options;
+    return new ContextResolver({ cacheRoot, backend }).resolve(binding, resolveOptions);
+}

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.64.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",