@nanobpm/nano-workforce 0.189.3 → 0.191.0

package/app/readiness.ts

@@ -63,6 +63,11 @@ export type Backoff = "fixed" | "exponential";
 // is added here without a matching vocabulary entry (AGENTS.md: no drift surfaces).
 export const PROBE_KINDS: readonly ProbeKind[] = ["http", "command", "npm", "github-check", "capability", "pr", "epic"];
 export const ON_TIMEOUTS: readonly OnTimeout[] = ["escalate", "fail", "continue"];
+// The DEFAULT `onTimeout` an omitted value takes — the single source of truth `parseProbe` fills in and
+// the compiler's display drops as an effective default (writing it explicitly is behaviourally identical
+// to omitting it, so surfacing it would fork `semanticBpmn`/the digest from the omitted-equivalent
+// graph; issue #778 review — thread deliveryGraphCompiler.ts:1398).
+export const DEFAULT_ON_TIMEOUT: OnTimeout = "escalate";
 export const BACKOFFS: readonly Backoff[] = ["fixed", "exponential"];
 export const PR_CONDITIONS: readonly PrCondition[] = ["ready", "merged", "mergeable", "checks-green"];
 export const EPIC_CONDITIONS: readonly EpicCondition[] = ["merged", "done"];
@@ -237,7 +242,7 @@ export function parseProbe(raw: unknown, opts?: { allowLateBoundTarget?: boolean
   if (onTimeoutRaw !== "" && !isOnTimeout(onTimeoutRaw)) {
     throw new Error(`readiness probe: invalid onTimeout '${onTimeoutRaw}' (expected ${ON_TIMEOUTS.join(", ")})`);
   }
-  const onTimeout: OnTimeout = onTimeoutRaw === "" ? "escalate" : onTimeoutRaw;
+  const onTimeout: OnTimeout = onTimeoutRaw === "" ? DEFAULT_ON_TIMEOUT : onTimeoutRaw;
 
   const match = isRecord(raw.match) ? parseMatch(raw.match) : undefined;
   // A capability edge whose ref or package is blank can never resolve — fail loudly here rather than
@@ -307,7 +312,7 @@ export function parseProbe(raw: unknown, opts?: { allowLateBoundTarget?: boolean
 
 // Membership guards that narrow a validated string to its union without a type assertion (the
 // `no-unsafe-type-assertion` gate bans `as`).
-function isProbeKind(v: string): v is ProbeKind {
+export function isProbeKind(v: string): v is ProbeKind {
   for (const k of PROBE_KINDS) if (k === v) return true;
   return false;
 }
@@ -318,7 +323,7 @@ function isOnTimeout(v: string): v is OnTimeout {
 
 // `isBackoff` narrows a validated string to its union without a type assertion (the
 // `no-unsafe-type-assertion` gate bans `as`).
-function isBackoff(v: string): v is Backoff {
+export function isBackoff(v: string): v is Backoff {
   for (const b of BACKOFFS) if (b === v) return true;
   return false;
 }
@@ -414,7 +419,17 @@ export function normalizePoll(poll: ProbePoll | undefined): Required<ProbePoll>
   const everyMs = typeof everyRaw === "number" && everyRaw >= 1 ? Math.trunc(everyRaw) : DEFAULT_EVERY_MS;
   const timeoutMs =
     typeof timeoutRaw === "number" && timeoutRaw >= 1 ? Math.trunc(timeoutRaw) : DEFAULT_TIMEOUT_MS;
-  return { everyMs: Math.min(everyMs, MAX_EVERY_MS), timeoutMs, backoff: poll?.backoff ?? DEFAULT_BACKOFF };
+  // TRIM `backoff` to match `parseProbe` (`parsePoll` does `str(raw.backoff).trim()`): a padded
+  // `" exponential "` runs as the SAME `exponential` policy, so leaving the whitespace here would make
+  // the compiler's display path (`normalizePoll(p.poll)`) emit a spurious non-default `Poll:` line for a
+  // runtime-default poll — forking `semanticBpmn`/the digest from the omitted-equivalent graph and
+  // letting a re-stage bypass the idempotency fence to duplicate the run (issue #778 review — thread
+  // deliveryGraphCompiler.ts:1414). A whitespace-only / unrecognised value falls back to the default
+  // (the compiler display path takes raw JSON; a genuinely invalid backoff fails loudly later in
+  // `parseProbe`, so defaulting the DISPLAY is safe and keeps the effective-policy render honest).
+  const backoffTrimmed = typeof poll?.backoff === "string" ? poll.backoff.trim() : undefined;
+  const backoff = backoffTrimmed && isBackoff(backoffTrimmed) ? backoffTrimmed : DEFAULT_BACKOFF;
+  return { everyMs: Math.min(everyMs, MAX_EVERY_MS), timeoutMs, backoff };
 }
 
 /** The delay (ms) before the `attempt`-th retry (1-based). Fixed backoff returns `everyMs`;
@@ -1157,10 +1172,221 @@ export function redactTarget(probe: ReadinessProbe): string {
   return `${probe.kind}:${redactString(probe.target)}`;
 }
 
+/** The ONE canonical embedded-`//<userinfo>@` credential-userinfo span, shared by the redactor
+ * ({@link redactString}, which REWRITES the span to `//***@`) and the semantic reject path
+ * ({@link hasEmbeddedCredential}, used by `validateDeliveryGraph` to REJECT a credential-bearing
+ * `agent.jobType`). Keeping ONE source string means the "what counts as an embedded credential" rule
+ * can never drift between the two — the redactor must strip exactly what the validator rejects, or a
+ * credential the validator misses would be echoed un-redacted. The userinfo class is `[^/?#]` (NOT
+ * `[^/@\s]`, and NOT the earlier `[^/@]`/`[^/]`): it deliberately spans WHITESPACE up to the `@`, so a
+ * malformed-but-operator-authored `//user:secret pass@host` (a literal space in the userinfo) is
+ * caught, not left to leak verbatim into the executable `<zeebe:taskDefinition type=…>` / compiled BPMN
+ * (issue #778 review — thread deliveryGraph.ts:570). The userinfo colon is DELIBERATELY OPTIONAL
+ * (`[^/?#]*@`, not `[^/?#]*:[^/?#]*@`):
+ * a passwordless, username-only `//token@host` is a bearer/OAuth token riding the userinfo and MUST be
+ * caught too — a plain worker-routing job type never contains a `//…@` span at all (with or without a
+ * colon), so requiring a colon would only re-open a real leak for no legitimate gain (issue #778 review
+ * — thread readiness.ts:1170). `[^/?#]*@` is a single-quantifier match — linear, no catastrophic
+ * backtracking.
+ *
+ * The userinfo class is `[^/?#]` (NOT `[^/@]`): per RFC 3986 the userinfo runs to the LAST `@` before the
+ * authority's path, so a malformed-but-accepted multi-`@` value (`//user:pass@ss@host`) must collapse
+ * through EVERY `@` up to the path — an earlier `[^/@]*@` stopped at the FIRST `@`, rewriting only
+ * `//user:pass@` and leaking the `ss@host` suffix into the display artifact (issue #778 review — thread
+ * readiness.ts:1175).
+ *
+ * The class also EXCLUDES `?` and `#` (NOT the earlier `[^/]`): per RFC 3986 a raw `?`/`#` starts the
+ * query/fragment and so ENDS the authority — a `//host?token=secret@tail` carries its `@` INSIDE the
+ * query, with no userinfo at all. An unbounded `[^/]*@` greedily consumed the `?` marker
+ * (`//host?token=secret@` → `//***@`), so the follow-on `?query`/`#fragment` strip in {@link redactString}
+ * found no marker and left `tail` visible. Bounding the userinfo before `?`/`#` keeps the marker in
+ * place so the whole query/fragment (incl. any `@tail`) is redacted, while a genuine `//user:pass@host?…`
+ * still collapses its userinfo AND has its query stripped (issue #778 review — thread readiness.ts:1199).
+ * `[^/?#]` still excludes `/` (so it never crosses into the path), and the trailing `@` is anchored
+ * greedily to the last one before a `/`/`?`/`#`; `[^/?#]*@` remains a single-quantifier match, so it is
+ * linear with no catastrophic backtracking. */
+export const EMBEDDED_CREDENTIAL_SRC = "\\/\\/[^/?#]*@";
+
 /** Strip credential-bearing pieces from a free-form target string for logging: any `user:pass@`
- * userinfo and any `?query`/`#fragment` (a token often rides the query). */
+ * userinfo and any `?query`/`#fragment` (a token often rides the query). The query/fragment strip uses
+ * `[\s\S]*` (NOT `.*$`, which cannot cross a line break) so an embedded CR/LF after the `?`/`#` — e.g.
+ * `https://host/?token=secret\nnext` — cannot leave the token un-redacted; everything from the first
+ * `?`/`#` to end-of-string is consumed regardless of intervening newlines. The userinfo class is
+ * `[^/?#]` (NOT `[^/@\s]`, NOT the earlier `[^/@ ]`/`[^/@ \t]`/`[^/@]`, and NOT the later `[^/]`): ANY character smuggled
+ * INSIDE the
+ * userinfo up to the `@` — a raw CR/LF (`https://user:pa\nss@host`), an embedded TAB
+ * (`https://user:pa\tss@host`), a literal SPACE (`https://user:secret pass@host`, a malformed but
+ * operator-authored value), OR an extra raw `@` (`https://user:pass@ss@host`, whose userinfo per RFC
+ * 3986 runs to the LAST `@`) — must not break the `//…@` match and leave the credential tail visible.
+ * An earlier `[^/@ ]` bounded the userinfo at a SPACE to avoid over-matching prose, and `[^/@]` stopped
+ * at the FIRST `@` (leaking a multi-`@` suffix), but both let a credential escape into an
+ * operator-visible display artifact; since the RAW value
+ * still reaches runtime unmodified and only the DISPLAY doc is affected, redacting more (through the
+ * last `@` before the path) is the safe direction (issue #778 review). The `?`/`#` exclusion is the
+ * INVERSE correction: a `[^/]` userinfo crossed a raw query/fragment delimiter — a `?token=…@tail` query
+ * (no userinfo; the `@` rides the query) collapsed to `//***@tail`, consuming the `?` marker so the
+ * follow-on `?query`/`#fragment` strip below found nothing and LEAKED `tail`. Bounding the userinfo at
+ * `?`/`#` keeps the marker so the query strip redacts the whole tail (issue #778 review — thread
+ * readiness.ts:1199). `[^/?#]*@` remains a
+ * single-quantifier match, so it is
+ * linear with no catastrophic backtracking. Callers that surface the result in a display artifact must
+ * first pass it through `stripXmlInvalidChars` so an XML-forbidden control (e.g. U+000B) inside the
+ * userinfo cannot split the `//…@` match and be re-joined at render. */
 export function redactString(s: string): string {
-  return s
-    .replace(/\/\/[^/@\s]*@/g, "//***@")
-    .replace(/[?#].*$/, (m) => `${m[0]}***`);
+  return redactEmbeddedCredential(s).replace(/[?#][\s\S]*$/, (m) => `${m[0]}***`);
+}
+
+/** Strip ONLY the embedded `//<userinfo>@` credential span(s) from a string, collapsing each to
+ * `//***@` and leaving everything else (including any `?query`/`#fragment`, which may be a MEANINGFUL
+ * opaque-token character rather than URL syntax) untouched. Shares the ONE canonical
+ * {@link EMBEDDED_CREDENTIAL_SRC} span so "what counts as an embedded credential" can never drift from
+ * the redactor ({@link redactString}) or the validator ({@link hasEmbeddedCredential}). A `//<userinfo>@`
+ * span is UNAMBIGUOUSLY a credential wherever it sits — a plain opaque identifier
+ * (`slack:#releases`, `owner/repo#42`, `pkg@version`) never contains one — so it is safe to strip
+ * regardless of the value's URL-shape or the span's position, which is why {@link redactConnectorValue}
+ * runs it on a NON-URL-shaped free-form value (a probe target / PR ref) whose credential rides AFTER a
+ * prefix (`prefix //user:pass@host#42`) that the anchored {@link isUrlShaped} check would miss (issue
+ * #778 review — thread deliveryGraph.ts:162/566). `[^/]*@` is a single-quantifier match — linear, no
+ * catastrophic backtracking. */
+export function redactEmbeddedCredential(s: string): string {
+  return s.replace(new RegExp(EMBEDDED_CREDENTIAL_SRC, "g"), "//***@");
+}
+
+/** The ONE canonical embedded SCHEME-RELATIVE credential-URL token: a `//<userinfo>@authority…` run
+ * (bounded by the next literal space) whose `//` carries userinfo. The `@` UNAMBIGUOUSLY marks the run a
+ * URL — an opaque ref (`//host#42`, `slack:#releases`, `owner/repo#42`) never carries `//user@` — so its
+ * `?query`/`#fragment` IS URL syntax and may hide a token, exactly like an explicit-scheme
+ * {@link EMBEDDED_SCHEME_URL_SRC}. Distinct from the userinfo-ONLY {@link EMBEDDED_CREDENTIAL_SRC}, which
+ * strips just the `//user:pass@` span and (correctly, for an opaque `//host#42`) LEAVES the tail: a
+ * userinfo-bearing `//user:pass@host?token=secret` embedded after a non-URL prefix is scheme-relative,
+ * so the anchored whole-value {@link isUrlShaped} check misses it (non-URL prefix) and the userinfo-only
+ * strip leaks the `?token=secret` tail (issue #778 review — thread deliveryGraph.ts:188). Requiring the
+ * `@` keeps genuine opaque `//host#42` refs (no userinfo) untouched. The token runs to the next literal
+ * SPACE (`[^ ]*`), NOT the wider `\s` class, so it CROSSES an XML-valid internal TAB/LF/CR and still
+ * redacts a `?query` secret sitting past it. The userinfo class is `[^/?#]` (NOT the earlier `[^/]`):
+ * bounding it before a raw `?`/`#` stops the userinfo span crossing the query/fragment delimiter — a
+ * `//host?token=secret@tail` (no userinfo; the `@` rides the query) no longer collapses to `//***@tail`
+ * (leaking `tail`); it instead falls through to {@link redactEmbeddedSchemeRelativeUrl}, which strips the
+ * whole `?query` (issue #778 review — thread readiness.ts:1199, mirroring the {@link EMBEDDED_CREDENTIAL_SRC}
+ * fix). `[^/?#]*@` and `[^ ]*` are separated by the literal `@`
+ * anchor, so the match stays linear with no catastrophic backtracking. */
+const EMBEDDED_CREDENTIAL_URL_SRC = "\\/\\/[^/?#]*@[^ ]*";
+
+/** Redact each embedded SCHEME-RELATIVE credential-URL (`//<userinfo>@authority…`) token IN PLACE via
+ * {@link redactString} — stripping its `//user:pass@` userinfo AND any `?query`/`#fragment` — while
+ * leaving opaque `//host#42` refs (no userinfo) untouched. Lets {@link redactConnectorValue} catch a
+ * query/fragment secret riding a credential-bearing scheme-relative URL after a non-URL prefix
+ * (`prefix //user:pass@host?token=secret`) that the anchored {@link isUrlShaped} whole-value check AND
+ * the userinfo-only {@link redactEmbeddedCredential} both miss (issue #778 review — thread
+ * deliveryGraph.ts:188). Deterministic and total. */
+export function redactEmbeddedCredentialUrl(s: string): string {
+  return s.replace(new RegExp(EMBEDDED_CREDENTIAL_URL_SRC, "g"), (m) => redactString(m));
+}
+
+/** The ONE canonical embedded ABSOLUTE-URL token: an EXPLICIT-scheme `scheme://authority…` run bounded
+ * by whitespace. Deliberately requires an explicit `scheme:` before the `//` (NOT the scheme-relative
+ * `//authority` {@link isUrlShaped} also accepts): an absolute URL's `?query`/`#fragment` are
+ * UNAMBIGUOUSLY URL syntax and may hide a token, so they are safe to strip; a scheme-relative
+ * `//host#42` (or an opaque `slack:#releases`, `owner/repo#42`) instead carries a MEANINGFUL opaque
+ * `#`/`?` (a `parsePrTarget` PR ref) that must survive, so it is left to the userinfo-only
+ * {@link redactEmbeddedCredential}. The scheme may be followed by XML-attribute whitespace
+ * (`\s*` — TAB/LF/CR/space) BEFORE the `//` authority, exactly like {@link isUrlShaped}: those are valid
+ * XML `Char`s that `stripXmlInvalidChars` does NOT remove, so an embedded `scheme<whitespace>//authority`
+ * after a non-URL prefix (`prefix https:\t//user:pass@host?token=secret`) is not whole-value URL-shaped,
+ * escapes the anchored {@link isUrlShaped} check, and — without this `\s*` — was missed here too, leaving
+ * the fallback {@link redactEmbeddedCredential} to strip only the `//…@` userinfo and LEAK the
+ * `?token=secret` tail. Keeping this token's `scheme:` + `\s*` + `//` shape aligned with `isUrlShaped`
+ * closes that gap (issue #778 review — thread readiness.ts:1239). The token then runs to the next literal
+ * (`[^ ]+`), NOT the wider `\s` class, so it CROSSES an XML-valid internal TAB/LF/CR (0x09/0x0A/0x0D —
+ * the only whitespace `stripXmlInvalidChars` keeps) and still redacts a `?query`/`#fragment` secret
+ * sitting past it (`https://host/pa\tth?token=secret`); a `\s`-bounded token stopped at that internal
+ * whitespace and leaked the tail (#778 review — thread deliveryGraph.ts:188). Over-redacting across an
+ * internal newline is the safe direction. `\s*` and `[^ ]+` are separated by the literal `:`/`//`
+ * anchors, so the match stays linear with no catastrophic backtracking. */
+const EMBEDDED_SCHEME_URL_SRC = "[a-z][a-z0-9+.-]*:\\s*\\/\\/[^ ]+";
+
+/** Redact each embedded ABSOLUTE-URL (explicit `scheme://…`) token in a free-form value IN PLACE via
+ * {@link redactString} — stripping that token's `user:pass@` userinfo AND `?query`/`#fragment` — while
+ * leaving surrounding prose and any scheme-relative/opaque `//…`/`#`/`?` run untouched (those are
+ * handled, credential-only, by {@link redactEmbeddedCredential}). Lets {@link redactConnectorValue}
+ * catch a query/fragment secret riding an embedded absolute URL after a non-URL prefix
+ * (`prefix https://host/path?token=secret`) that the anchored {@link isUrlShaped} whole-value check
+ * misses (issue #778 review — thread deliveryGraph.ts:181). Deterministic and total. */
+export function redactEmbeddedUrl(s: string): string {
+  return s.replace(new RegExp(EMBEDDED_SCHEME_URL_SRC, "gi"), (m) => redactString(m));
+}
+
+/** The ONE canonical embedded SCHEME-RELATIVE URL token that carries a `?query`: a userinfo-LESS
+ * `//authority…?query…` run (bounded by the next literal space). Distinct from the userinfo-bearing
+ * {@link EMBEDDED_CREDENTIAL_URL_SRC} (which the `@` marks a URL) and the explicit-scheme
+ * {@link EMBEDDED_SCHEME_URL_SRC}: a `senior:feature //host?token=secret` embedded after a non-URL prefix
+ * has NO userinfo `@` and NO explicit `scheme:`, so the anchored {@link isUrlShaped} whole-value check,
+ * {@link redactEmbeddedCredentialUrl}, and {@link redactEmbeddedUrl} ALL miss it — leaking the
+ * `?token=secret` tail (issue #778 review — thread deliveryGraph.ts:633). A scheme-relative `//authority`
+ * whose `?` is present is UNAMBIGUOUSLY URL syntax — an opaque ref (`owner/repo#42`, `//host#42`) uses a
+ * `#<digits>` fragment (`parsePrTarget`), never a `//…?…` query — so its query is safe to strip while a
+ * userinfo-less opaque `//host#42` (no `?`) is left to keep its meaningful `#42`. The token runs to the
+ * next literal SPACE (`[^ ]*`), NOT the wider `\s` class, so it CROSSES an XML-valid internal TAB/LF/CR
+ * and still redacts a `?query` secret sitting past it. `[^ ]*` before/after the literal `?` anchor keeps
+ * the match linear with no catastrophic backtracking. */
+const EMBEDDED_SCHEME_RELATIVE_URL_SRC = "\\/\\/[^ ]*\\?[^ ]*";
+
+/** Redact each embedded SCHEME-RELATIVE URL (`//authority…?query…`, no userinfo, no explicit scheme)
+ * token IN PLACE via {@link redactString} — stripping its `?query`/`#fragment` — while leaving a
+ * userinfo-less opaque `//host#42` PR ref (no `?`) untouched. Lets {@link redactConnectorValue} catch a
+ * query secret riding a scheme-relative URL after a non-URL prefix (`prefix //host?token=secret`) that
+ * the anchored {@link isUrlShaped} check, {@link redactEmbeddedCredentialUrl}, and {@link redactEmbeddedUrl}
+ * all miss (issue #778 review — thread deliveryGraph.ts:633). Deterministic and total. */
+export function redactEmbeddedSchemeRelativeUrl(s: string): string {
+  return s.replace(new RegExp(EMBEDDED_SCHEME_RELATIVE_URL_SRC, "g"), (m) => redactString(m));
+}
+
+/** The canonical scheme-relative `//` authority marker — the `//` that opens an authority in ANY URL
+ * form (absolute `scheme://`, scheme-relative `//`, credential `//user@`). A worker-routing job type
+ * never legitimately contains it. */
+const SCHEME_RELATIVE_AUTHORITY_SRC = "\\/\\/";
+
+/** True when `value` embeds a scheme-relative `//authority` token (see {@link SCHEME_RELATIVE_AUTHORITY_SRC}).
+ * A plain worker-routing job type / opaque id NEVER contains `//` — so a match (whether it carries
+ * userinfo, an explicit scheme, a `?query`, a `#fragment`, or nothing) is illegitimate in an
+ * `agent.jobType` and must be rejected, closing the userinfo-less scheme-relative gap
+ * (`senior:feature //host?token=secret`) that {@link hasEmbeddedCredential} (needs `@`),
+ * {@link hasEmbeddedUrl} (needs an explicit scheme), and the anchored {@link isUrlShaped} (whole-value
+ * only) all miss (issue #778 review — thread deliveryGraph.ts:633). */
+export function hasSchemeRelativeAuthority(value: string): boolean {
+  return new RegExp(SCHEME_RELATIVE_AUTHORITY_SRC).test(value);
+}
+
+/** True when `value` embeds a `//<userinfo>@host` credential token (see {@link EMBEDDED_CREDENTIAL_SRC};
+ * the userinfo colon is optional, so a passwordless `//token@host` bearer token also matches).
+ * A plain worker-routing job type / opaque id never contains one, so a match is a credential leak to reject. */
+export function hasEmbeddedCredential(value: string): boolean {
+  return new RegExp(EMBEDDED_CREDENTIAL_SRC).test(value);
+}
+
+/** True when `value` embeds an absolute-URL token (`scheme://authority…`; see
+ * {@link EMBEDDED_SCHEME_URL_SRC}). A plain worker-routing job type / opaque id never contains one, so a
+ * match is a URL whose `?query`/`#fragment` can hide a token and which — since the executable
+ * `<zeebe:taskDefinition type=…>` carries the job type VERBATIM — would leak into the compiled BPMN.
+ * Distinct from {@link hasEmbeddedCredential}: that catches only a `//<userinfo>@` credential span and
+ * misses a userinfo-less `senior:feature https://host?token=secret` (issue #778 review — thread
+ * deliveryGraph.ts:602). */
+export function hasEmbeddedUrl(value: string): boolean {
+  return new RegExp(EMBEDDED_SCHEME_URL_SRC, "i").test(value);
+}
+
+/** The ONE canonical "is this value a URL?" classifier — a `scheme://authority` OR scheme-relative
+ * `//authority` form, either of which can hide a credential in userinfo/query/fragment. It is the single
+ * source of truth for URL-shape detection shared by the connector/jobType display redactor
+ * ({@link redactString} callers in the compiler) AND the semantic validation boundary
+ * (`validateDeliveryGraph`), so the "what counts as credential-bearing/URL-shaped" rule can never drift
+ * between the redact path and the reject path (issue #778 review — thread deliveryGraphCompiler.ts:1606).
+ * Classify on the TRIMMED value so leading whitespace (` //user:pass@host` — the OpenAPI edge caps
+ * length but does not trim) cannot bypass the anchored check. The scheme may be followed by
+ * XML-attribute whitespace (TAB/LF/CR/space) before the `//` authority: those characters are valid XML
+ * `Char`s that `stripXmlInvalidChars` does NOT remove, so `https:\t//user:pass@host` must still classify
+ * as URL-shaped or its credential escapes redaction as "not a URL" (issue #778 review — thread
+ * readiness.ts:1191). Deterministic and total. */
+export function isUrlShaped(value: string): boolean {
+  return /^([a-z][a-z0-9+.-]*:\s*)?\/\//i.test(value.trim());
 }

package/db/migrations/113_delivery_graph_run_identity.sql

@@ -0,0 +1,37 @@
+-- Delivery Graphs: persist a LOSSLESS graph-identity fingerprint per run in a dedicated SIDE TABLE
+-- (issue #778 review — thread dispatchDeliveryGraph.ts:332).
+--
+-- A run is keyed by `run_key` (an explicit operator `idempotencyKey`, else the content `digest`). The
+-- `digest` is content-addressed over the REDACTED `semanticBpmn`, so two graphs differing ONLY in a
+-- redacted-away secret (a URL credential, a `command` target, a match secret, a free-form connector
+-- `payload`, …) SHARE one digest. When an operator supplies an explicit `idempotencyKey`, a re-dispatch
+-- short-circuits onto the existing running row — but the lossy `digest` on that row cannot prove the
+-- short-circuited run is THIS exact secret-bearing graph vs. a credential-different graph re-staged under
+-- the same key. The dispatch door therefore refused EVERY such short-circuit with 409, which also broke
+-- the idempotency contract for a legitimate SAME-payload retry (a lost response / double-click of the
+-- identical proposal): it received 409 and lingered `staged` instead of short-circuiting successfully.
+--
+-- `graph_fingerprint` stores the run's lossless content identity — `sha256(digest \0
+-- canonicalJson(digestInvisibleRawValues(graph)))` (the SAME identity `stableProposalRunKey` folds into
+-- the keyless run key) — captured at launch. On an explicit-key short-circuit the door compares the
+-- incoming graph's fingerprint against the stored one: a MATCH is a same-payload retry (allow the
+-- short-circuit + consume the proposal); a MISMATCH — or a MISSING row (a run that predates this table)
+-- — is unprovable, so the door refuses (the safe pre-existing 409 behaviour) and it self-heals once the
+-- run turns over.
+--
+-- WHY A SIDE TABLE, not a column on `delivery_graph_runs`: that base table is projected COLUMN-FOR-COLUMN
+-- by several drift-guarded surfaces — the `delivery_graph_runs__units` compat VIEW served from the
+-- `delivery_units` aggregate (091/098) and the `delivery_graph_read_model`/`__tracking` VIEWs (087/096),
+-- each of which asserts full base-column pass-through parity. This identity fingerprint is an INTERNAL
+-- dispatch concern surfaced to no read model, so it belongs off to the side rather than threaded through
+-- (and re-drift-guarded across) every projection.
+--
+-- Forward-only, additive (expand). The runner wraps each file in its own transaction — no BEGIN/COMMIT.
+-- Numbered after 112 (the current highest on origin/main; this branch forked before 103–112 and must not
+-- reuse a prefix main already occupies).
+
+CREATE TABLE IF NOT EXISTS delivery_graph_run_identity (
+  run_key TEXT PRIMARY KEY,
+  graph_fingerprint TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);

package/db/migrations/114_delivery_graph_proposals_stage_seq.sql

@@ -0,0 +1,21 @@
+-- A MONOTONIC per-write stage revision for delivery-graph proposals (issue #778 review, thread
+-- app/deliveryGraphProposals.ts:245). The supersede reconcile ("exactly one live proposal per logical
+-- graph, the LATEST stage wins") breaks a same-millisecond `updated_at` tie between two staged siblings
+-- with a deterministic secondary key. That key used to be SQLite's `rowid` (insertion order) — but a
+-- RE-STAGE of an existing digest is an `UPDATE` that bumps `updated_at` while LEAVING the `rowid`
+-- unchanged, so a re-stage that lands in the same millisecond as a different digest's fresh stage could
+-- be selected as the OLDER row (its stale, lower rowid) and be immediately superseded, inverting the
+-- "latest stage wins" invariant this tie-break exists to uphold.
+--
+-- `stage_seq` fixes that: it is reassigned to `MAX(stage_seq)+1` on EVERY stage write — a fresh insert
+-- AND a re-stage update alike — so the most-recently-written row always holds the strictly-highest value
+-- regardless of its rowid or a coincident `updated_at`. Additive/expand (nullable-equivalent `DEFAULT 0`,
+-- no data rewrite): existing rows read as `0` and are re-sequenced the next time they are staged.
+ALTER TABLE delivery_graph_proposals ADD COLUMN stage_seq INTEGER NOT NULL DEFAULT 0;
+
+-- Index `stage_seq` so the atomic `MAX(stage_seq)+1` allocation in `stageProposal` (issue #778 review,
+-- thread app/deliveryGraphProposals.ts:237) is an O(1) reverse-index seek of the single highest value
+-- rather than a full scan of the retained proposal history (staged + terminal rows accumulate; a bare
+-- aggregate would grow linearly with them).
+CREATE INDEX IF NOT EXISTS idx_delivery_graph_proposals_stage_seq
+  ON delivery_graph_proposals (stage_seq);

package/docs/adr/0005-agent-authored-delivery-graphs.md

@@ -113,7 +113,7 @@ The closed set (extensible only by a deliberate ADR/PR, never by graph authors):
 > PR back to `converging`. `submitPr`'s own `prKey` idempotency additionally makes a resumed re-perform
 > double-safe on a still-live row. This retires the manual `land-*` human gate whose only job was "go run convergence
 > yourself" — the canonical shape is now `agent (opens PR) → connector[converge-merge] →
-> wait[pr, merged]` with no human node. The payload is `{ pr, convergeOnly?, dependsOn? }`; the `pr`
+> wait[pr, merged]` with no human node. The payload is `{ pr, autoMerge?, dependsOn? }`; the `pr`
 > may be a literal `owner/repo#N`, a `<node>.pr` fact reference late-bound from an upstream `agent`
 > node's emitted `pr` fact, or omitted to auto-bind the single incoming `pr` fact (issue #548 —
 > shipped: the connector resolves it via `resolveConvergePr`, and the `wait[pr]` target is late-bound

package/docs/agent-guide.md

@@ -73,7 +73,7 @@ The body is flat. Fields:
 | field | type | meaning |
 |---|---|---|
 | `pr` (or `url`) | string | the PR — `owner/repo#123` or a full PR URL. Required. |
-| `convergeOnly` | boolean | **`true` = review only.** The PR stops at `converged` and is **never** handed to the merge loop, even when `NANO_PR_AUTO_MERGE` is on. Omit / `false` = converge **then merge**. |
+| `autoMerge` | boolean | **Positive per-request setting.** `false` = review only, stopping at `converged`, regardless of the global default; `true` = converge **then merge** when `NANO_PR_AUTO_MERGE` is enabled. |
 | `maxRounds` | integer | per-submit cap before escalating (clamped 1–100; default from `NANO_PR_MAX_ROUNDS`, 20). |
 | `dependsOn` | string[] | other `prKey`s that must land before this one merges (merge-loop barrier). |
 
@@ -84,12 +84,12 @@ The body is flat. Fields:
 # or is only after a review pass):
 curl -sS -X POST __BASE__/actions/start/convergence-loop \
   -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#123", "convergeOnly": true }'
+  -d '{ "pr": "owner/repo#123", "autoMerge": false }'
 
 # Converge then merge, with a dependency barrier and a tighter round cap:
 curl -sS -X POST __BASE__/actions/start/convergence-loop \
   -H 'content-type: application/json' \
-  -d '{ "pr": "owner/repo#42", "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
+  -d '{ "pr": "owner/repo#42", "autoMerge": true, "maxRounds": 8, "dependsOn": ["owner/repo#40"] }'
 ```
 
 Submitting is **idempotent on the PR key** — re-POSTing the same PR refreshes the
@@ -311,7 +311,7 @@ the answer becomes the agent's next-round context.
 ```
  submit ──► convergence-loop
    round (senior:pr-review) ──► addressed ──► wait review-ready ─┐
-                             ├─ converged  ──► finalize ──► merge-loop (unless convergeOnly)
+                             ├─ converged  ──► finalize ──► merge-loop (when autoMerge and NANO_PR_AUTO_MERGE are enabled)
                              └─ needs_input/blocked ──► escalate ──► wait-answer userTask (task inbox)
  merge-loop: wait deps ─► arm merge ─► (queue-aware) merge / land
              blocked (CI red) ─► senior:fix-ci ─► retry     conflict ─► senior:rebase ─► retry
@@ -774,13 +774,13 @@ only job was "go run convergence yourself".
 - **`converge-merge`** — the **unit-level** land: drive review convergence **and then the merge
   loop**, landing the PR onto **its own base branch** (for a unit inside an epic that base is the
   epic integration branch, never `main` directly — ADR 0003 base-branch admission). Equivalent to a
-  submit with `convergeOnly: false`.
+  submit with `autoMerge: true`.
 - **`merge-main`** — the **graph-level** top-level land: the second level of the two-level merge
   (ADR 0006 §3), landing the graph/epic **integration** PR onto **`main`**. Dispatch-identical to
   `converge-merge` (both enroll + merge); the distinction is the *level*, kept a first-class literal
   so the two levels are authored explicitly rather than left emergent.
 - **`converge`** — **converge-only**: drive review convergence and stop at `converged`, never
-  handing off to the merge loop (equivalent to `convergeOnly: true`).
+  handing off to the merge loop (equivalent to `autoMerge: false`).
 
 > **converge/merge are cell POLICY, not raw nodes.** A raw `senior:converge` / `senior:merge`
 > **agent** job is **not expressible** — the compiler rejects it (`raw-converge-node`). Express
@@ -788,10 +788,10 @@ only job was "go run convergence yourself".
 > policy flags (`merge` requires `converge`), or, for enrolling an already-open PR, the
 > `connector` targets above (ADR 0006 §3 / S5).
 
-**Payload:** `{ pr: "owner/repo#123", convergeOnly?: boolean, dependsOn?: string[] }`. `pr` is
+**Payload:** `{ pr: "owner/repo#123", autoMerge?: boolean, dependsOn?: string[] }`. `pr` is
 required (a literal `owner/repo#N`, identical to how a `wait: pr` node targets a known PR).
-`convergeOnly` defaults from the target and may be overridden per-node; `dependsOn` is unioned
-into the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
+`autoMerge` defaults from the target and may be overridden per-node; `dependsOn` is unioned into
+the PR's merge-stage dependency set. The enrollment is idempotent (the connector's
 at-least-once dedupe fence **plus** `submitPr`'s own `prKey` idempotency), so a graph resume /
 redelivery never double-enrolls.
 

package/openapi.yaml

@@ -1823,11 +1823,13 @@ components:
           type: integer
           minimum: 1
           description: Values above 100 are accepted and clamped to 100 by the delegate.
+        autoMerge:
+          type: boolean
+          description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
         convergeOnly:
           type: boolean
-          description: When true, run convergence only and stop at `converged` — the PR is never
-            handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A
-            per-request review-only override; defaults to false (the global auto-merge default applies).
+          deprecated: true
+          description: "Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`."
     ConvergenceStartByUrl:
       type: object
       additionalProperties: false
@@ -1845,11 +1847,13 @@ components:
           type: integer
           minimum: 1
           description: Values above 100 are accepted and clamped to 100 by the delegate.
+        autoMerge:
+          type: boolean
+          description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
         convergeOnly:
           type: boolean
-          description: When true, run convergence only and stop at `converged` — the PR is never
-            handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A
-            per-request review-only override; defaults to false (the global auto-merge default applies).
+          deprecated: true
+          description: "Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`."
     PlanStart:
       description: The start-plan-fanout request body. Names the target issue by EXACTLY ONE of
         `issue` (an `owner/repo#123` reference) or `url` (a bare issue URL), plus a REQUIRED
@@ -3435,8 +3439,8 @@ components:
         autoMerge:
           type: boolean
           description: >-
-            When true (and `converge` is true), drive the merge-loop after convergence — mirrors
-            `convergeOnly`/`NANO_PR_AUTO_MERGE` inverted. When false the run stops at `converged`.
+            When true (and `converge` is true), drive the merge-loop after convergence only when
+            `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`.
             Moot when `converge` is false.
         confirmDefaultBase:
           type: boolean
@@ -4573,9 +4577,13 @@ paths:
                       type: integer
                       minimum: 1
                       description: Values above 100 are accepted and clamped to 100 by the delegate.
+                    autoMerge:
+                      type: boolean
+                      description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
                     convergeOnly:
                       type: boolean
-                      description: When true, run convergence only and stop at `converged` — the PR is never handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A per-request review-only override; defaults to false (the global auto-merge default applies).
+                      deprecated: true
+                      description: 'Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`.'
                 - type: object
                   additionalProperties: false
                   required:
@@ -4592,9 +4600,13 @@ paths:
                       type: integer
                       minimum: 1
                       description: Values above 100 are accepted and clamped to 100 by the delegate.
+                    autoMerge:
+                      type: boolean
+                      description: Preferred per-request setting. When false, stop at `converged`; when true, run the merge-loop after convergence only if `NANO_PR_AUTO_MERGE` is enabled. When omitted, the global default applies.
                     convergeOnly:
                       type: boolean
-                      description: When true, run convergence only and stop at `converged` — the PR is never handed to the merge-loop even if auto-merge is on globally (`NANO_PR_AUTO_MERGE`). A per-request review-only override; defaults to false (the global auto-merge default applies).
+                      deprecated: true
+                      description: 'Deprecated negative alias. If `autoMerge` is omitted, `true` means `autoMerge: false`; `false` means `autoMerge: true` (still gated by `NANO_PR_AUTO_MERGE`). Prefer `autoMerge`.'
               type: object
               # END generated:mcp-body
       responses:
@@ -5809,9 +5821,9 @@ paths:
                           type: string
                           enum: [real, forward-declared]
                           description: real ⇒ dispatches a real side effect; forward-declared ⇒ a no-op stub.
-                        convergeOnlyDefault:
+                        autoMergeDefault:
                           type: boolean
-                          description: The default `convergeOnly` for a real converge target.
+                          description: The default `autoMerge` for a real converge target.
                         summary:
                           type: string
                           description: What the target does.
@@ -5872,7 +5884,7 @@ paths:
                       optionalFields: [dedupeKey, payload]
                       sideEffecting: true
                       mayEmit: true
-                      summary: "An automated outbound action; payload for a converge target is { pr, convergeOnly?, dependsOn? }."
+                      summary: "An automated outbound action; payload for a converge target is { pr, autoMerge?, dependsOn? }."
                   factTypes: [string, number, boolean, artifact, version, url, pr]
                   guardScalarTypes: [string, number, boolean]
                   waitProbeKinds:
@@ -5893,15 +5905,15 @@ paths:
                   connectorTargets:
                     - target: converge
                       status: real
-                      convergeOnlyDefault: true
+                      autoMergeDefault: false
                       summary: "Converge-only: drive review convergence and stop at converged."
                     - target: converge-merge
                       status: real
-                      convergeOnlyDefault: false
+                      autoMergeDefault: true
                       summary: "Unit-level land: converge AND merge onto the PR's own base branch."
                     - target: merge-main
                       status: real
-                      convergeOnlyDefault: false
+                      autoMergeDefault: true
                       summary: "Graph-level top-level land onto main (two-level merge)."
                     - target: "<any other target>"
                       status: forward-declared
@@ -6168,7 +6180,7 @@ paths:
                       description: When true, hand the opened PR to the convergence loop (review rounds) as a follow-on step. When false (default) the run ends at "PR raised, not reviewed".
                     autoMerge:
                       type: boolean
-                      description: When true (and `converge` is true), drive the merge-loop after convergence — mirrors `convergeOnly`/`NANO_PR_AUTO_MERGE` inverted. When false the run stops at `converged`. Moot when `converge` is false.
+                      description: When true (and `converge` is true), drive the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is enabled. When false the run stops at `converged`. Moot when `converge` is false.
                     confirmDefaultBase:
                       type: boolean
                       description: Acknowledge that `baseBranch` is the repository default branch (the PR would target it directly). See `PlanStartByIssue.confirmDefaultBase`.