@nanobpm/nano-workforce 0.191.0 → 0.192.0

package/.github/workflows/mirror-install-dispatch.yml

@@ -2,16 +2,16 @@
 #
 # https://nanobpm.io/install.sh is served as the ACTUAL bytes of THIS repo's
 # install.sh (GitHub Pages can't 301-redirect a `curl … | sh` URL). The site is
-# built in a DIFFERENT repo (Magikcraft/nano-bpm) whose Pages workflow re-fetches
+# built in a DIFFERENT repo (nanobpm/nano-bpm) whose Pages workflow re-fetches
 # install.sh on every deploy — but that deploy only triggers on changes to files
 # in that repo, so an edit here would otherwise not reach the published mirror
 # until the nightly backstop cron. This job pokes that repo's Pages deploy via a
 # `repository_dispatch` (event type `install-sh-updated`) so the mirror refreshes
 # within minutes of merging an install.sh change.
 #
-# Requires a token that can write to Magikcraft/nano-bpm — the default
+# Requires a token that can write to nanobpm/nano-bpm — the default
 # GITHUB_TOKEN is scoped to THIS repo only. Store a fine-grained PAT (or GitHub
-# App token) with `Contents: read and write` on Magikcraft/nano-bpm as the repo
+# App token) with `Contents: read and write` on nanobpm/nano-bpm as the repo
 # secret PAGES_DISPATCH_TOKEN. Absent the secret, the job no-ops (the nightly
 # cron on the site keeps the mirror eventually-consistent).
 name: Refresh nanobpm.io install mirror
@@ -45,10 +45,10 @@ jobs:
             -H 'Accept: application/vnd.github+json' \
             -H "Authorization: Bearer ${DISPATCH_TOKEN}" \
             -H 'X-GitHub-Api-Version: 2022-11-28' \
-            https://api.github.com/repos/Magikcraft/nano-bpm/dispatches \
+            https://api.github.com/repos/nanobpm/nano-bpm/dispatches \
             -d '{"event_type":"install-sh-updated"}')
           if [ "$code" != "204" ]; then
-            echo "::error::repository_dispatch to Magikcraft/nano-bpm returned HTTP ${code} (expected 204). Check PAGES_DISPATCH_TOKEN scope (fine-grained PAT: Contents: read & write)."
+            echo "::error::repository_dispatch to nanobpm/nano-bpm returned HTTP ${code} (expected 204). Check PAGES_DISPATCH_TOKEN scope (fine-grained PAT: Contents: read & write)."
             exit 1
           fi
-          echo "dispatched install-sh-updated to Magikcraft/nano-bpm (HTTP 204)"
+          echo "dispatched install-sh-updated to nanobpm/nano-bpm (HTTP 204)"

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.192.0](https://github.com/nanobpm/nano-workforce/compare/v0.191.1...v0.192.0) (2026-09-28)
+
+### Features
+
+* **world:** self-heal a no-advance round onto a reachable push-checkpoint ([#819](https://github.com/nanobpm/nano-workforce/issues/819)) ([891add2](https://github.com/nanobpm/nano-workforce/commit/891add2a217042dd2abaa37c8f12b1f1877c89fc)), closes [26/#28](https://github.com/26/nano-workforce/issues/28) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [#818](https://github.com/nanobpm/nano-workforce/issues/818) [704/#497](https://github.com/704/nano-workforce/issues/497)
+
+## [0.191.1](https://github.com/nanobpm/nano-workforce/compare/v0.191.0...v0.191.1) (2026-09-26)
+
+### Bug Fixes
+
+* **tasks:** show full delivery human-step context and lift an embedded link ([#814](https://github.com/nanobpm/nano-workforce/issues/814)) ([cca3374](https://github.com/nanobpm/nano-workforce/commit/cca33740607f80816504dd2b5c60b785cb1440c6)), closes [#813](https://github.com/nanobpm/nano-workforce/issues/813) [#fragment](https://github.com/nanobpm/nano-workforce/issues/fragment) [#778](https://github.com/nanobpm/nano-workforce/issues/778) [#813](https://github.com/nanobpm/nano-workforce/issues/813)
+
 ## [0.191.0](https://github.com/nanobpm/nano-workforce/compare/v0.190.0...v0.191.0) (2026-09-23)
 
 ### Features

package/app/deliveryGraph.ts

@@ -487,7 +487,7 @@ export function validateDeliveryGraph(graph: unknown): DeliveryGraphError[] {
         }
         // A `wait` node's `onTimeout: fail` cannot be honored yet: the compiler would emit a terminate
         // end on the not-ready-at-boundary path, but the engine treats terminate-end events as
-        // parsed-not-executed (Magikcraft/nano-bpm bpmn.rs), so `fail` would silently degrade to a plain
+        // parsed-not-executed (nanobpm/nano-bpm bpmn.rs), so `fail` would silently degrade to a plain
         // end — the "declared knob silently ignored" defect class. Reject it loudly (path-qualified)
         // until engine parity lands (Magikcraft/nano-bpm#978), rather than mis-compile it. `escalate`
         // (default) and `continue` ARE honored.

package/app/deliveryGraphRun.test.ts

@@ -201,7 +201,7 @@ test("computeRunKey: a non-blank caller key wins; a blank/absent key falls back
 });
 
 // ── buildHumanLabels / parseHumanLabels ───────────────────────────────────────
-test("buildHumanLabels: maps each human node's compiled user-task element id → its instruction label", async () => {
+test("buildHumanLabels: maps each human node's compiled user-task element id → its FULL instruction", async () => {
   const graph = {
     nodes: [
       { id: "open-b", kind: "agent", agent: { jobType: "j" } },
@@ -216,7 +216,9 @@ test("buildHumanLabels: maps each human node's compiled user-task element id →
   const labels = buildHumanLabels(compiled);
   const publishEl = compiled.resolved.nodes.find((n) => n.id === "publish")?.element ?? "";
   const ackEl = compiled.resolved.nodes.find((n) => n.id === "ack")?.element ?? "";
-  assertEquals(labels[humanTaskElementId(publishEl)], "run the manual OTP publish"); // first line only
+  // The FULL prompt is stored (issue #813) — not a clamped first line — so the Tasks "Decision
+  // context" can show the whole instruction. The phase pill clamps this at display (deriveDeliveryPhase).
+  assertEquals(labels[humanTaskElementId(publishEl)], "run the manual OTP publish\nsecond line");
   assertEquals(labels[humanTaskElementId(ackEl)], "ack"); // fallback to node id
 });
 
@@ -264,6 +266,16 @@ test("deriveDeliveryPhase: ACTIVE with an open human task → parked on that nod
   assertEquals(p.phase_node_id, el);
 });
 
+test("deriveDeliveryPhase: clamps a long/multi-line stored instruction to a first-line phase pill (#813)", () => {
+  const el = humanTaskElementId("n2");
+  const full = `Review the console dependency-adopt PR opened by adopt-console (bumps the ranges).\nSecond line.`;
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], { [el]: full });
+  // Full instruction is stored for the Decision context, but the phase pill shows only the clamped
+  // first line (77 chars + …), never the second line.
+  assertEquals(p.phase, "Parked on human node: Review the console dependency-adopt PR opened by adopt-console (bumps the ran…");
+  assert(!p.phase.includes("Second line"));
+});
+
 test("deriveDeliveryPhase: a parked node with no stored label falls back to the element id", () => {
   const el = humanTaskElementId("n5");
   const p = deriveDeliveryPhase("ACTIVE", [{ elementId: el }], {});
@@ -271,6 +283,17 @@ test("deriveDeliveryPhase: a parked node with no stored label falls back to the
   assertEquals(p.phase_node_id, el);
 });
 
+test("deliveryHuman: a parked bounded-timeout twin (`…__esc`) resolves the base node's stored label in the phase pill (#813)", () => {
+  // The twin's exact `…__esc` id is never stamped into `human_labels` (only the base id is), so the
+  // phase-pill lookup must strip `__esc` — the same fallback the Tasks Decision-context helpers use —
+  // else a parked timeout twin shows the raw element id instead of the instruction's first line.
+  const base = humanTaskElementId("n2");
+  const twin = `${base}__esc`;
+  const p = deriveDeliveryPhase("ACTIVE", [{ elementId: twin }], { [base]: "manual OTP publish" });
+  assertEquals(p.phase, "Parked on human node: manual OTP publish");
+  assertEquals(p.phase_node_id, twin);
+});
+
 test("deriveDeliveryPhase: ACTIVE with only a non-human open task (or none) → a bare Running", () => {
   assertEquals(deriveDeliveryPhase("ACTIVE", [], {}), { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null });
   assertEquals(deriveDeliveryPhase("ACTIVE", [{ elementId: "some-service-task" }], {}), {

package/app/deliveryGraphRun.ts

@@ -206,9 +206,12 @@ function firstLine(text: string | undefined | null): string {
   return line.length > 80 ? `${line.slice(0, 77)}…` : line;
 }
 
-/** Map each human node's compiled user-task element id → a display label (its instruction's first
- * line, else its author node id), from the S1 compile result. Stamped on the run row at dispatch so
- * the poller renders the parked-node phase without recompiling the graph. */
+/** Map each human node's compiled user-task element id → its FULL instruction, from the S1 compile
+ * result. Stamped on the run row at dispatch so the poller can (a) render the parked-node phase label
+ * — clamped at display by {@link deriveDeliveryPhase} — and (b) surface the WHOLE instruction as the
+ * Tasks-inbox "Decision context" (issue #813). Storing the full prompt (not a clamped first line) is
+ * what lets the operator read the entire instruction, and lets a URL embedded in the prompt reach the
+ * task's clickable link. Falls back to the node id when a human node declares no prompt. */
 export function buildHumanLabels(compiled: CompileDeliveryGraphResult): Record<string, string> {
   const elementByNodeId = new Map(compiled.resolved.nodes.map((n) => [n.id, n.element]));
   const labels: Record<string, string> = {};
@@ -220,8 +223,11 @@ export function buildHumanLabels(compiled: CompileDeliveryGraphResult): Record<s
     // task's Decision context in the Tasks inbox, so a URL credential in a human prompt (`//user:pass@…`)
     // must be stripped here too — else it is persisted and shown unredacted even though the BPMN display
     // path redacts it. The RAW prompt still reaches the runtime user task unmodified (issue #778 review).
-    const safePrompt = typeof stop.prompt === "string" ? redactFreeText(stop.prompt) : "";
-    labels[humanTaskElementId(element)] = firstLine(safePrompt) || stop.nodeId;
+    // The FULL redacted prompt is stored (not a clamped first line) so the Tasks "Decision context" can
+    // show the whole instruction and surface an embedded link; the phase pill clamps it at display via
+    // `firstLine` in `deriveDeliveryPhase` below (issue #813).
+    const safePrompt = typeof stop.prompt === "string" ? redactFreeText(stop.prompt).trim() : "";
+    labels[humanTaskElementId(element)] = safePrompt || stop.nodeId;
   }
   return labels;
 }
@@ -267,7 +273,13 @@ export function deriveDeliveryPhase(
     .filter((id): id is string => typeof id === "string" && isDeliveryHumanElement(id))
     .sort()[0];
   if (parkedOn !== undefined) {
-    const label = humanLabels[parkedOn] ?? parkedOn;
+    // Clamp the compact phase label to the instruction's first line (the full prompt is stored in
+    // `human_labels` for the Tasks "Decision context" — issue #813 — but the phase pill wants a short
+    // one-liner). Use the SAME exact-then-`__esc`-stripped lookup as `deliveryHumanContext*` so a
+    // parked bounded-timeout twin (`…__esc`, whose exact id is never stamped) resolves to its base
+    // node's label instead of showing the raw element id. A missing label falls back to the raw id.
+    const stored = humanLabels[parkedOn] ?? humanLabels[parkedOn.replace(/__esc$/, "")];
+    const label = firstLine(stored) || parkedOn;
     return { status: "running", phase: `Parked on human node: ${label}`, phase_node_id: parkedOn };
   }
   return { status: "running", phase: DELIVERY_PHASE.RUNNING, phase_node_id: null };

package/app/deliveryHuman.test.ts

@@ -11,7 +11,9 @@ import {
   bindHumanEmits,
   DELIVERY_HUMAN_ELEMENT,
   deliveryHumanContextQuestion,
+  deliveryHumanContextUrl,
   deriveHumanCategory,
+  firstHttpUrl,
   GENERIC_HUMAN_FORM,
   HUMAN_ACK_FORM,
   HUMAN_PUBLISH_FORM,
@@ -21,6 +23,7 @@ import {
   renderHumanEmitBrief,
   resolveHumanForm,
 } from "./deliveryHuman.ts";
+import { redactFreeText } from "./deliveryGraphCompiler.ts";
 import { ESCALATION_TASK_ELEMENTS } from "./agentCompletion.ts";
 import { USER_TASK_KIND_LABELS } from "./userTasks.ts";
 
@@ -322,8 +325,82 @@ test("deliveryHumanContextQuestion: derives the node instruction from human_labe
   );
 });
 
-test("deliveryHumanContextQuestion: falls back to a static message when no label is stored", () => {
-  // A parked human step must never render a blank Decision context — an untracked/absent label still
+test("firstHttpUrl: extracts the first http(s) URL and trims trailing prose punctuation (#813)", () => {
+  assertEquals(firstHttpUrl("see https://github.com/o/r/pull/5 for details"), "https://github.com/o/r/pull/5");
+  // Trailing sentence punctuation / closing bracket is stripped so the link resolves.
+  assertEquals(firstHttpUrl("Review the PR (https://github.com/o/r/pull/5)."), "https://github.com/o/r/pull/5");
+  assertEquals(firstHttpUrl("http://example.test/a,"), "http://example.test/a");
+  // A balanced closing bracket is part of the URL and preserved (not truncated into a broken link).
+  assertEquals(
+    firstHttpUrl("see https://en.wikipedia.org/wiki/Nano_(technology) here"),
+    "https://en.wikipedia.org/wiki/Nano_(technology)",
+  );
+  // A balanced bracket followed by prose punctuation: strip only the punctuation, keep the pair.
+  assertEquals(
+    firstHttpUrl("ref https://en.wikipedia.org/wiki/Nano_(technology)."),
+    "https://en.wikipedia.org/wiki/Nano_(technology)",
+  );
+  // An UNBALANCED wrapping bracket is prose and still stripped.
+  assertEquals(firstHttpUrl("(https://github.com/o/r/pull/9)"), "https://github.com/o/r/pull/9");
+  // Multiple/nested UNBALANCED trailing closers + prose punctuation are all peeled off in one linear
+  // pass (guards the O(n) trim refactor — #813 review), while an inner balanced pair is preserved.
+  assertEquals(
+    firstHttpUrl("(see [https://en.wikipedia.org/wiki/Nano_(technology)])."),
+    "https://en.wikipedia.org/wiki/Nano_(technology)",
+  );
+  assertEquals(firstHttpUrl("look: {[(https://example.test/a)]}"), "https://example.test/a");
+  // An apostrophe is a valid URL sub-delimiter and preserved WITHIN the URL (not truncated at it)…
+  assertEquals(
+    firstHttpUrl("see https://en.wikipedia.org/wiki/It's_a_Wonderful_Life here"),
+    "https://en.wikipedia.org/wiki/It's_a_Wonderful_Life",
+  );
+  // …while a TRAILING apostrophe (a prose quote closer) is still trimmed.
+  assertEquals(firstHttpUrl("the link 'https://example.test/a' works"), "https://example.test/a");
+  // Scheme match is case-insensitive (RFC 3986 schemes are case-insensitive).
+  assertEquals(firstHttpUrl("see HTTPS://github.com/o/r/pull/5 now"), "HTTPS://github.com/o/r/pull/5");
+  assertEquals(firstHttpUrl("Http://example.test/b"), "Http://example.test/b");
+  // First wins when several are present.
+  assertEquals(firstHttpUrl("a https://one.test b https://two.test"), "https://one.test");
+  // No URL / non-string → null (preserves today's linkless behaviour).
+  assertEquals(firstHttpUrl("merge the PR opened by adopt-console"), null);
+  assertEquals(firstHttpUrl(undefined), null);
+});
+
+test("deliveryHumanContextUrl: lifts a prompt-embedded URL onto the task link (base + __esc twin), else null (#813)", () => {
+  const labels = {
+    "delivery-human-task__n7": "Review the adopt PR at https://github.com/nanobpm/nano-ide/pull/42 and merge it.",
+    "delivery-human-task__n8": "Confirm CI is green, then merge — no link here.",
+  };
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__n7"), "https://github.com/nanobpm/nano-ide/pull/42");
+  // The bounded-timeout twin resolves the same node instruction.
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__n7__esc"), "https://github.com/nanobpm/nano-ide/pull/42");
+  // A node whose instruction names no URL yields null (the linkless default).
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__n8"), null);
+  assertEquals(deliveryHumanContextUrl(undefined, "delivery-human-task__n1"), null);
+});
+
+test("deliveryHumanContextUrl: declines to link a redaction-altered URL, links a credential-free one (#814)", () => {
+  // The stored `human_labels` are display-REDACTED via the SAME `redactFreeText` `buildHumanLabels` uses,
+  // so build the labels through it to mirror production exactly.
+  const withQuery = redactFreeText("Review the checks tab at https://example.test/o/r/pull/5?tab=checks now");
+  const withCred = redactFreeText("Open https://user:pass@example.test/o/r/pull/5 to review");
+  const withFragment = redactFreeText("Jump to https://example.test/o/r/pull/5#files section");
+  const clean = redactFreeText("Review the PR at https://example.test/o/r/pull/5 and merge it");
+  const labels = {
+    "delivery-human-task__q": withQuery,
+    "delivery-human-task__c": withCred,
+    "delivery-human-task__f": withFragment,
+    "delivery-human-task__ok": clean,
+  };
+  // A redacted query/userinfo/fragment would publish a DIFFERENT, broken link → decline (null).
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__q"), null);
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__c"), null);
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__f"), null);
+  // A credential-free URL is untouched by redaction and links faithfully.
+  assertEquals(deliveryHumanContextUrl(labels, "delivery-human-task__ok"), "https://example.test/o/r/pull/5");
+});
+
+test("deliveryHumanContextQuestion: falls back to a static message when no label is stored", () => {  // A parked human step must never render a blank Decision context — an untracked/absent label still
   // yields actionable guidance rather than null (which would leave the panel empty, issue #772).
   assertEquals(
     deliveryHumanContextQuestion({}, "delivery-human-task__n1"),

package/app/deliveryHuman.ts

@@ -83,6 +83,98 @@ export function deliveryHumanContextQuestion(
   return label || "A scheduled delivery-graph step is waiting to be completed.";
 }
 
+/** The clickable link for a parked delivery-graph `human` node's Tasks-inbox row (issue #813): the
+ *  first `http(s)` URL embedded in the node's stored instruction, or `null` when it names none. The
+ *  Tasks page renders the "Decision context" as PLAIN, non-clickable text (a `detail.fields` entry),
+ *  and links only through the http(s)-gated `subject_url` `linkField` — so an author who wants the
+ *  operator to have a clickable link (e.g. the PR to review) writes the URL into the node prompt and
+ *  this lifts it onto `subject_url`. Uses the SAME exact-then-`__esc`-stripped lookup as the context
+ *  question so the twin escalation task resolves to its real node's instruction. Returns `null` (not a
+ *  fabricated link) when no URL is present, preserving today's linkless behaviour. */
+export function deliveryHumanContextUrl(
+  humanLabels: Record<string, string> | undefined,
+  elementId: string,
+): string | null {
+  const labels = humanLabels ?? {};
+  const base = elementId.replace(/__esc$/, "");
+  const instruction = labels[elementId] ?? labels[base] ?? "";
+  const url = firstHttpUrl(instruction);
+  // The stored `human_labels` are display-REDACTED (`redactFreeText` in `buildHumanLabels`): a URL that
+  // carried a credential — `//user:pass@` userinfo, or a `?query`/`#fragment` (which can hide a signed/
+  // authenticating token) — has that component collapsed to the `***` sentinel (`//***@`, `?***`, `#***`).
+  // Lifting such an altered URL onto `subject_url` would publish a DIFFERENT, broken link (a truncated
+  // query changes the referenced resource; a signed URL becomes unusable). We cannot recover the real URL
+  // here — the raw prompt is deliberately NOT stored (issue #778) — so decline to link rather than silently
+  // publishing a redaction-mangled one. A URL with no credential component is untouched by redaction and
+  // links faithfully (issue #813 review). Callers wanting a clickable link should embed a credential-free
+  // URL in the prompt.
+  return url !== null && urlBearsRedactionMarker(url) ? null : url;
+}
+
+/** The `***` sentinel {@link redactFreeText}/`redactString` leaves where it collapsed a URL's credential
+ *  span — `//***@` (userinfo), `?***` (query), `#***` (fragment). Its presence in an extracted URL means
+ *  redaction ALTERED the link, so it must not be published as a `subject_url` (issue #813 review). */
+const URL_REDACTION_MARKER = /\/\/\*\*\*@|[?#]\*\*\*/;
+
+function urlBearsRedactionMarker(url: string): boolean {
+  return URL_REDACTION_MARKER.test(url);
+}
+
+const URL_TRAILING_CLOSERS: Readonly<Record<string, string>> = { ")": "(", "]": "[", "}": "{" };
+
+const URL_TRAILING_PUNCTUATION = ".,;:!?'\"";
+
+/** Trim trailing prose punctuation a URL commonly picks up when embedded in a sentence (`.,;:!?'"` and
+ *  a wrapping `)`/`]`/`}`), WITHOUT corrupting a URL that legitimately ends in a closing bracket. A
+ *  closing bracket is only stripped when it is UNBALANCED within the URL (a prose wrapper, e.g. the `)`
+ *  in "see (https://x/y)"); a balanced pair — e.g. Wikipedia `…/Foo_(disambiguation)` — is part of the
+ *  URL and preserved, so the persisted link isn't truncated into a broken one. Bracket balance is
+ *  tracked in running per-pair counts (seeded by one linear scan, then decremented as trailing closers
+ *  are stripped) so the whole trim is a single O(n) pass — NOT the prior re-`split()`-the-prefix-each-
+ *  step quadratic (issue #813 review). */
+function trimUrlTrailingPunctuation(url: string): string {
+  const opens: Record<string, number> = { "(": 0, "[": 0, "{": 0 };
+  const closes: Record<string, number> = { ")": 0, "]": 0, "}": 0 };
+  for (const ch of url) {
+    if (ch in opens) opens[ch] += 1;
+    else if (ch in closes) closes[ch] += 1;
+  }
+  let end = url.length;
+  while (end > 0) {
+    const ch = url[end - 1];
+    const opener = URL_TRAILING_CLOSERS[ch];
+    if (opener !== undefined) {
+      // `opens`/`closes` reflect url[0:end]; only trailing closers are ever removed below, so they stay
+      // accurate. Balanced (opener count ≥ closer count) → the bracket belongs to the URL; stop.
+      if (opens[opener] >= closes[ch]) break;
+      closes[ch] -= 1;
+      end -= 1;
+      continue;
+    }
+    if (URL_TRAILING_PUNCTUATION.includes(ch)) {
+      end -= 1;
+      continue;
+    }
+    break;
+  }
+  return url.slice(0, end);
+}
+
+/** Extract the first `http(s)` URL from free text, trimming trailing sentence punctuation/brackets a
+ *  prose author commonly appends (`).,;` etc.) so the link resolves — but preserving a bracket that is
+ *  BALANCED within the URL (e.g. Wikipedia `…_(technology)`), so a valid URL is never truncated into a
+ *  broken task link. An apostrophe is a valid URL sub-delimiter (RFC 3986 §2.2), so it is allowed WITHIN
+ *  the URL and only stripped when trailing (a prose quote closer) by `trimUrlTrailingPunctuation` — the
+ *  same way a wrapping `)` is handled — so a link such as `…/It's_a_Wonderful_Life` is not truncated at
+ *  the apostrophe (issue #813 review). The scheme match is case-insensitive (RFC 3986 schemes are
+ *  case-insensitive). Returns `null` when none. */
+export function firstHttpUrl(text: string | undefined | null): string | null {
+  if (typeof text !== "string") return null;
+  const match = text.match(/https?:\/\/[^\s<>"`]+/i);
+  if (!match) return null;
+  return trimUrlTrailingPunctuation(match[0]) || null;
+}
+
 /** The GENERIC fallback form (Decision 4, step 3): captures ONE typed value into the node's single
  *  declared emitted fact, so a human node with no explicit/category form can STILL emit downstream. */
 export const GENERIC_HUMAN_FORM = "delivery-human-generic";

package/app/github.test.ts

@@ -3,7 +3,7 @@
 // the merge-exclusion graph. Force the token transport and stub `globalThis.fetch`.
 import { test } from "node:test";
 import { assertEquals, assertRejects } from "#test-assert";
-import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, type GhReview, type Mergeability, type PrState } from "./github.ts";
+import { BaseBranchMustExistError, checkConclusions, classifyMergeability, classifyPrLiveness, coalesceTitle, compareCommits, createPullRequest, ensureBaseBranch, ensurePromotionPr, fetchBranchHead, fetchIssueTitle, fetchPrFiles, fetchPrHead, fetchPrReviews, isNotAPullRequestError, listPrsForHead, updateBranchRef, type GhReview, type Mergeability, type PrState } from "./github.ts";
 import { DEFAULT_MERGE_PROTOCOL, type MergeProtocol, type RequiredCheck } from "./mergeProtocol.ts";
 
 // A fake `fetch` that serves `pages` of file batches; each page N (1-based) returns `pages[N-1]`
@@ -956,3 +956,225 @@ test("fetchBranchHead: percent-encodes a special-character branch ref (preservin
   );
   assertEquals(sha, "cafef00d");
 });
+
+// ── No-advance self-heal transports (issue #818) ────────────────────────────
+// The self-heal's compare (`compareCommits`) and NON-force ref move (`updateBranchRef`) are
+// safety-critical: a regression in the ahead/behind parsing or the `force:false` / 422-refusal
+// handling silently changes whether a recovery mutates a PR head. These pin the token transport of
+// both — a request-capturing fetch stub so the method/body/path and the refusal branch are covered.
+async function withCapturingFetch<T>(
+  serve: (req: { path: string; method: string; body: unknown }) => { status: number; statusText?: string; body: unknown },
+  fn: () => Promise<T>,
+): Promise<T> {
+  const prevMode = process.env["NANO_PR_GITHUB_TRANSPORT"];
+  const prevFetch = globalThis.fetch;
+  process.env["NANO_PR_GITHUB_TRANSPORT"] = "token";
+  globalThis.fetch = ((url: string | URL | Request, init?: RequestInit): Promise<Response> => {
+    const path = new URL(String(url)).pathname.replace(/^\/repos\//, "");
+    const method = (init?.method ?? "GET").toUpperCase();
+    const body = typeof init?.body === "string" ? JSON.parse(init.body) : undefined;
+    const { status, statusText, body: resp } = serve({ path, method, body });
+    return Promise.resolve(new Response(JSON.stringify(resp), { status, statusText }));
+  }) as typeof fetch;
+  try {
+    return await fn();
+  } finally {
+    globalThis.fetch = prevFetch;
+    if (prevMode === undefined) delete process.env["NANO_PR_GITHUB_TRANSPORT"];
+    else process.env["NANO_PR_GITHUB_TRANSPORT"] = prevMode;
+  }
+}
+
+test("compareCommits: parses an 'ahead' fast-forward response and encodes the compare refs", async () => {
+  const cmp = await withCapturingFetch(
+    ({ path, method }) => {
+      assertEquals(method, "GET");
+      // Each ref segment is percent-encoded (`#` → %23) around the compare API's own `...` separator.
+      assertEquals(path, "o/r/compare/feat/x%23123...deadbeef");
+      return { status: 200, body: { status: "ahead", ahead_by: 3, behind_by: 0 } };
+    },
+    () => compareCommits("o/r", "feat/x#123", "deadbeef", "tok"),
+  );
+  assertEquals(cmp, { status: "ahead", aheadBy: 3, behindBy: 0 });
+});
+
+test("compareCommits: coerces an unknown status to 'diverged' and defaults missing counts to 0", async () => {
+  const cmp = await withCapturingFetch(
+    () => ({ status: 200, body: { status: "wat" } }),
+    () => compareCommits("o/r", "base", "head", "tok"),
+  );
+  assertEquals(cmp, { status: "diverged", aheadBy: 0, behindBy: 0 });
+});
+
+// Reject COERCED/UNSAFE compare counts at the transport boundary (Copilot review of #819). A bare
+// `Number(...)` would turn a malformed/tampered response into a spurious ancestry proof — a string
+// `"1"` or boolean `true` coerces to `1`, and an unsafe magnitude passes `Number.isInteger` — either
+// of which could fast-forward the ref WITHOUT a genuine GitHub proof. A present count must be a real,
+// non-negative SAFE integer number; anything else throws so the self-heal escalates rather than heals.
+test("compareCommits: rejects a string-coerced count (throws, never a spurious integer proof)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: "1", behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: rejects a boolean-coerced count", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: 1, behind_by: true } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid behind_by",
+  );
+});
+
+test("compareCommits: rejects an unsafe-magnitude integer count (passes Number.isInteger but is not a safe integer)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: 1e21, behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: rejects a negative count", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 200, body: { status: "ahead", ahead_by: -3, behind_by: 0 } }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "invalid ahead_by",
+  );
+});
+
+test("compareCommits: no token → null (idle transport, never a throw)", async () => {
+  const cmp = await withCapturingFetch(
+    () => {
+      throw new Error("fetch must not be called without a token");
+    },
+    () => compareCommits("o/r", "base", "head", ""),
+  );
+  assertEquals(cmp, null);
+});
+
+test("compareCommits: a non-2xx transport response throws (an outage is not a silent 'diverged')", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 500, statusText: "Server Error", body: {} }),
+        () => compareCommits("o/r", "base", "head", "tok"),
+      ),
+    Error,
+    "500",
+  );
+});
+
+test("updateBranchRef: a successful fast-forward PATCHes force:false and returns true", async () => {
+  let seen: { path: string; method: string; body: unknown } | undefined;
+  const moved = await withCapturingFetch(
+    (req) => {
+      seen = req;
+      return { status: 200, body: { ref: "refs/heads/feat/x", object: { sha: "deadbeef" } } };
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+  );
+  assertEquals(moved, true);
+  assertEquals(seen?.method, "PATCH", "the ref move is a PATCH");
+  assertEquals(seen?.path, "o/r/git/refs/heads/feat/x", "targeting the head ref");
+  // The whole point of the self-heal transport: it NEVER force-updates — GitHub must be free to
+  // refuse a non-fast-forward. A regression flipping this to force:true would rewrite history.
+  assertEquals(seen?.body, { sha: "deadbeef", force: false });
+});
+
+test("updateBranchRef: GitHub's 422 non-fast-forward refusal returns false, never throws", async () => {
+  const moved = await withCapturingFetch(
+    () => ({ status: 422, statusText: "Unprocessable Entity", body: { message: "Update is not a fast forward" } }),
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+  );
+  assertEquals(moved, false, "a refused non-fast-forward is a safe false (→ the caller escalates)");
+});
+
+test("updateBranchRef: a non-422 transport error throws (a real outage is not a silent refusal)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => ({ status: 500, statusText: "Server Error", body: { message: "boom" } }),
+        () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok"),
+      ),
+    Error,
+    "500",
+  );
+});
+
+test("updateBranchRef: no token in token mode throws (no usable transport to move the ref)", async () => {
+  await assertRejects(
+    () =>
+      withCapturingFetch(
+        () => {
+          throw new Error("fetch must not be called without a token");
+        },
+        () => updateBranchRef("o/r", "feat/x", "deadbeef", ""),
+      ),
+    Error,
+    "no GitHub transport available",
+  );
+});
+
+// ── updateBranchRef compare-and-swap (Copilot review on #819) ────────────────
+// When `expectedSha` is given the move is a CAS on the ref's prior value: read the ref right before
+// the PATCH and refuse unless it still equals the validated base, so a head advanced/replaced by a
+// concurrent (superseded) run after the caller's fast-forward proof is never PATCHed.
+test("updateBranchRef: CAS advances when the ref still equals expectedSha (reads then PATCHes)", async () => {
+  const seen: string[] = [];
+  const moved = await withCapturingFetch(
+    (req) => {
+      seen.push(`${req.method} ${req.path}`);
+      if (req.method === "GET") return { status: 200, body: { object: { sha: "basebase" } } };
+      return { status: 200, body: { ref: "refs/heads/feat/x", object: { sha: "deadbeef" } } };
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, true, "the ref still pointed at the validated base, so the fast-forward applied");
+  assertEquals(
+    seen,
+    ["GET o/r/git/ref/heads/feat/x", "PATCH o/r/git/refs/heads/feat/x"],
+    "the CAS reads the ref before mutating it",
+  );
+});
+
+test("updateBranchRef: CAS refuses (false, no PATCH) when the ref has moved off expectedSha", async () => {
+  const methods: string[] = [];
+  const moved = await withCapturingFetch(
+    (req) => {
+      methods.push(req.method);
+      if (req.method === "GET") return { status: 200, body: { object: { sha: "movedmoved" } } };
+      throw new Error("must not PATCH once the compare-and-swap has lost");
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, false, "a ref moved off the validated base refuses the move (→ the caller escalates)");
+  assertEquals(methods, ["GET"], "a lost CAS never issues the PATCH");
+});
+
+test("updateBranchRef: CAS refuses (false) when the ref is absent/unreadable (null)", async () => {
+  const moved = await withCapturingFetch(
+    (req) => {
+      if (req.method === "GET") return { status: 404, statusText: "Not Found", body: { message: "Not Found" } };
+      throw new Error("must not PATCH when the base ref is gone");
+    },
+    () => updateBranchRef("o/r", "feat/x", "deadbeef", "tok", "basebase"),
+  );
+  assertEquals(moved, false, "a deleted/unreadable base ref is not the validated state, so the move is refused");
+});