@nanobpm/nano-workforce 0.200.1 → 0.200.3

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.200.3](https://github.com/nanobpm/nano-workforce/compare/v0.200.2...v0.200.3) (2026-10-04)
+
+### Bug Fixes
+
+* **readiness:** accept a PR URL in the pr probe via the canonical parsePr ([#857](https://github.com/nanobpm/nano-workforce/issues/857)) ([cc194b7](https://github.com/nanobpm/nano-workforce/commit/cc194b74265392a4fbc5c1166e50f8e40068dee5)), closes [/host#N](https://github.com/nanobpm//host/issues/N) [#856](https://github.com/nanobpm/nano-workforce/issues/856) [owner/repo#N](https://github.com/owner/repo/issues/N) [#856](https://github.com/nanobpm/nano-workforce/issues/856) [owner/repo#N](https://github.com/owner/repo/issues/N) [owner/repo#N](https://github.com/owner/repo/issues/N) [owner/github.com#42](https://github.com/owner/github.com/issues/42) [owner/repo#N](https://github.com/owner/repo/issues/N) [owner/github.com#N](https://github.com/owner/github.com/issues/N) [owner/repo#123](https://github.com/owner/repo/issues/123)
+
+## [0.200.2](https://github.com/nanobpm/nano-workforce/compare/v0.200.1...v0.200.2) (2026-10-03)
+
+### Documentation
+
+* **agent-guide:** require repository on every delivery-graph agent node ([#851](https://github.com/nanobpm/nano-workforce/issues/851)) ([d6770ae](https://github.com/nanobpm/nano-workforce/commit/d6770ae2f6acc490e102aecaf0cab17ca5d10119)), closes [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [#505](https://github.com/nanobpm/nano-workforce/issues/505) [#850](https://github.com/nanobpm/nano-workforce/issues/850) [739/#776](https://github.com/739/nano-workforce/issues/776) [#505](https://github.com/nanobpm/nano-workforce/issues/505)
+
 ## [0.200.1](https://github.com/nanobpm/nano-workforce/compare/v0.200.0...v0.200.1) (2026-10-03)
 
 ### Performance Improvements

package/app/deliveryGraph.ts

@@ -23,7 +23,7 @@ import { isPlausibleBranchName } from "./baseBranch.ts";
 import { isEnvKey } from "./contracts.ts";
 import { isConvergeTarget } from "./convergeTargets.ts";
 import { isRawConvergeMergeJobType, NODE_COMPLETION_POLICIES } from "./nodePolicy.ts";
-import { BACKOFFS, hasEmbeddedCredential, hasEmbeddedUrl, hasSchemeRelativeAuthority, isBackoff, isUrlShaped, parsePrTarget, redactEmbeddedCredentialUrl, redactEmbeddedSchemeRelativeUrl, redactEmbeddedUrl, redactString } from "./readiness.ts";
+import { BACKOFFS, hasEmbeddedCredential, hasEmbeddedUrl, hasSchemeRelativeAuthority, isBackoff, isUrlShaped, redactEmbeddedCredentialUrl, redactEmbeddedSchemeRelativeUrl, redactEmbeddedUrl, redactString } from "./readiness.ts";
 import { isResolvableRepo } from "./repoEnvelope.ts";
 
 /** The CLOSED node-kind allowlist (ADR 0005 Decision 2) — the trust boundary. Extensible only by a
@@ -163,7 +163,7 @@ export function hasXmlInvalidChars(value: string): boolean {
  * scheme-relative `//authority` form ({@link isUrlShaped}), either of which can hide a credential in
  * userinfo/query/fragment (`redactString` redacts both) — is redacted in FULL (userinfo AND
  * `?query`/`#fragment`). But an embedded `//<userinfo>@` credential can also ride AFTER a non-URL
- * prefix in a free-form value that later parsers accept (`parsePrTarget` takes any prefix before
+ * prefix in a free-form value that keeps a meaningful `#<digits>` PR-number handle (any prefix before
  * `#<digits>`, so `prefix //user:pass@host#42`), which the anchored {@link isUrlShaped} check misses.
  * Because a `//<userinfo>@` span is UNAMBIGUOUSLY a credential wherever it sits (an opaque id never
  * contains one), a scheme-relative `//<userinfo>@authority…` run is treated as an embedded URL and
@@ -188,14 +188,14 @@ export function redactConnectorValue(value: string): string {
   const cleaned = stripXmlInvalidChars(value);
   // A whole-value URL gets the full redact (userinfo + query/fragment) — EXCEPT a whole-value opaque
   // scheme-relative PR ref (`//host#42`: no explicit scheme, no `//…@` credential, no `?query`), whose
-  // only URL-ish payload is a MEANINGFUL `#<digits>` fragment (a `parsePrTarget` PR ref). `isUrlShaped`
+  // only URL-ish payload is a MEANINGFUL `#<digits>` fragment (a PR-number handle). `isUrlShaped`
   // matches such a ref (scheme-relative `//authority`), so the whole-value branch would `redactString`
   // its `#42` → `#***` — yet the EMBEDDED contract deliberately PRESERVES the same `//host#42` (the
   // embedded redactors leave a userinfo-/query-less `//host#42` untouched). Route it through the embedded
   // path so a whole-value `//host#42` keeps its `#42` exactly like `prefix //host#42`, closing that
   // whole-value/embedded inconsistency (issue #778 review — thread deliveryGraph.ts:198). Only a
-  // NUMERIC `#<digits>` fragment is a valid `parsePrTarget` PR handle — `//host#access-token` is an
-  // ordinary URL fragment that can hide a secret, so the exception REQUIRES `parsePrTarget` to accept
+  // NUMERIC `#<digits>` fragment is a valid PR-number handle — `//host#access-token` is an
+  // ordinary URL fragment that can hide a secret, so the exception REQUIRES the `//host#<digits>` shape to match
   // the whole (trimmed) value; a non-numeric fragment falls to the full whole-value redact like any
   // other URL fragment (issue #778 review — thread deliveryGraph.ts:206). An explicit
   // `scheme://host#42`, a `//user:pass@host#…` credential, or a userinfo-less `//host?token=…` query all
@@ -211,7 +211,10 @@ export function redactConnectorValue(value: string): string {
     cleaned.trim().startsWith("//") &&
     !hasEmbeddedCredential(cleaned) &&
     !cleaned.includes("?") &&
-    parsePrTarget(cleaned) !== null;
+    // A NUMERIC `#<digits>` fragment after a non-empty authority (`//host#42`). Deliberately a local
+    // fragment-shape test, not the PR parser: this is a redaction exemption over a free-form value,
+    // and `parsePrTarget` now follows the canonical `parsePr` grammar (#856), which has no `//host` form.
+    /^\/\/[^#]+#\d+$/.test(cleaned.trim());
   return isUrlShaped(cleaned) && !isOpaqueSchemeRelativePrRef
     ? redactString(cleaned)
     : redactEmbeddedSchemeRelativeUrl(redactEmbeddedCredentialUrl(redactEmbeddedUrl(cleaned)));

package/app/deliveryGraphVocabulary.test.ts

@@ -6,7 +6,9 @@
 // key sets are byte-identical to the closed sets in `app/deliveryGraph.ts` / `app/readiness.ts` /
 // `app/convergeTargets.ts` (AGENTS.md — "no drift surfaces").
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
 import { test } from "node:test";
+import { parse as parseYaml } from "yaml";
 import { CONVERGE_MERGE_TARGET, CONVERGE_TARGET, isConvergeTarget, MERGE_MAIN_TARGET } from "./convergeTargets.ts";
 import { DELIVERY_FACT_TYPES, DELIVERY_GUARD_SCALAR_TYPES, DELIVERY_NODE_KINDS } from "./deliveryGraph.ts";
 import { deliveryGraphVocabulary } from "./deliveryGraphVocabulary.ts";
@@ -100,3 +102,80 @@ test("fact-threading rule names the unbound-pr rejection", () => {
   const vocab = deliveryGraphVocabulary();
   assert.match(vocab.factThreading.rule, /unbound-pr/);
 });
+
+// Resolve a node kind's per-kind CONFIG sub-schema (the authoritative OpenAPI contract for that
+// kind's body) from the parsed spec. `DeliveryNode<Kind>` is `allOf: [DeliveryNodeCommon, { properties:
+// { <configKey>: {…} } }]`, so find the allOf member carrying the `<configKey>` sub-schema and return
+// that member's `<configKey>` VALUE. For most kinds that value is the inline config object; for the
+// `wait` kind it is the `{ $ref: "#/components/schemas/ReadinessProbe" }` object (the config is
+// referenced, not inlined), which this helper returns AS-IS — the caller follows the reference itself.
+// Returns null only when the kind's node schema has NO inline `<configKey>` member at all (which the
+// caller's assert.ok rejects), never for the `wait` kind.
+function nodeConfigSchema(
+  spec: Record<string, any>,
+  nodeSchemaName: string,
+  configKey: string,
+): Record<string, any> | null {
+  const schema = spec?.components?.schemas?.[nodeSchemaName];
+  if (!schema) return null;
+  const sub = (schema.allOf as Array<Record<string, any>> | undefined)?.map((m) => m?.properties?.[configKey]).find(Boolean);
+  return sub ?? null;
+}
+
+/** Derive the (sorted) required + optional field sets from a config sub-schema's own `required`/`properties`. */
+function fieldSets(configSchema: Record<string, any>): { required: string[]; optional: string[] } {
+  const required = [...((configSchema.required as string[] | undefined) ?? [])].sort();
+  const optional = Object.keys((configSchema.properties as Record<string, unknown>) ?? {})
+    .filter((k) => !required.includes(k))
+    .sort();
+  return { required, optional };
+}
+
+test("every node-kind entry's field sets are DERIVED from its OpenAPI DeliveryNode<Kind>.<configKey> contract (#739/#850)", () => {
+  // The #850 failure mode is drift between a `DeliveryNode<Kind>.<configKey>` (the authoritative
+  // OpenAPI contract) and this vocabulary surface. A literal field list duplicated here would NOT
+  // catch it: if OpenAPI adds or removes a config property, a hand-copied list stays green while the
+  // surface lies. So derive the required/optional sets from the PARSED spec and compare the sets
+  // directly — the vocabulary cannot silently drift from the contract it claims to mirror. This
+  // guards EVERY kind, not just `agent`: the connector entry omitting the real `timeout` field
+  // (PR #851 review) is the same drift class the agent-only guard missed.
+  const ROOT = decodeURIComponent(new URL("../", import.meta.url).pathname);
+  const spec = parseYaml(readFileSync(`${ROOT}openapi.yaml`, "utf8")) as Record<string, any>;
+
+  const vocab = deliveryGraphVocabulary();
+  for (const entry of vocab.nodeKinds) {
+    const nodeSchemaName = `DeliveryNode${entry.kind[0]!.toUpperCase()}${entry.kind.slice(1)}`;
+    let configSchema = nodeConfigSchema(spec, nodeSchemaName, entry.configKey);
+    assert.ok(
+      configSchema,
+      `openapi.yaml components.schemas.${nodeSchemaName} must carry an inline '${entry.configKey}' config sub-schema`,
+    );
+    // The `wait` kind's config is `$ref: "#/components/schemas/ReadinessProbe"` — follow the reference.
+    if (typeof configSchema!.$ref === "string") {
+      const refName = configSchema!.$ref.replace(/^#\/components\/schemas\//, "");
+      configSchema = spec?.components?.schemas?.[refName];
+      assert.ok(configSchema?.properties, `${refName} (the wait config contract) must declare its properties`);
+    }
+    const { required, optional } = fieldSets(configSchema!);
+    assert.deepEqual(
+      [...entry.requiredFields].sort(),
+      required,
+      `${entry.kind}.requiredFields drifted from ${nodeSchemaName}.${entry.configKey}.required in openapi.yaml`,
+    );
+    assert.deepEqual(
+      [...entry.optionalFields].sort(),
+      optional,
+      `${entry.kind}.optionalFields drifted from ${nodeSchemaName}.${entry.configKey}'s optional properties in openapi.yaml`,
+    );
+  }
+
+  // The non-obvious rules an authoring agent must learn from the surface prose: an ABSENT repository
+  // is not compile-rejected (a run-level fallback can satisfy it) — it fails at the OPERATOR's
+  // Dispatch; and the per-node SLA timeout override exists.
+  const agent = vocab.nodeKinds.find((n) => n.kind === "agent");
+  assert.ok(agent, "agent node-kind entry must exist");
+  assert.match(agent.summary, /resolve to no repository/, "names the dispatch-time failure the author must pre-empt");
+  assert.match(agent.summary, /invalid-node-repository/, "names the compile-time validation for a present value");
+  assert.match(agent.summary, /repoless/, "names the checkout-less opt-out");
+  assert.match(agent.summary, /per-node ISO-8601 `timeout`/, "names the per-node SLA timeout override (#505)");
+});

package/app/deliveryGraphVocabulary.ts

@@ -105,13 +105,29 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   agent: {
     configKey: "agent",
     requiredFields: ["jobType"],
-    optionalFields: ["prompt", "converge", "merge"],
+    optionalFields: ["repository", "baseBranch", "prompt", "converge", "merge", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
-      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`). First-class " +
+      "A worker runs an agent job type (the fan-out body, e.g. `senior:feature`) in an isolated " +
+      "checkout. Per-node provisioning (#739/#776): declare `repository` (`owner/repo`, no `.git`/URL) " +
+      "on EVERY agent node — the harness clones it at `baseBranch` (omit it to use the run-level " +
+      "dispatch `baseBranch`, else the repo's default branch) and cuts `feat/<node.id>` off it " +
+      "(when that derived ref is a valid Git branch name; an id like `a..b`/`a.lock` yields an " +
+      "ill-formed ref, so the harness omits `branch.create` and the agent cuts its own branch). A node " +
+      "with no `repository` can only be satisfied by the run-level dispatch fallback, so COMPILE " +
+      "stages it without a warning; at Dispatch it resolves to the run-level `repository` + `baseBranch` " +
+      "fallback when the operator supplies one, and the Dispatch fails with `N agent node(s) " +
+      "resolve to no repository (…)` ONLY when neither the node nor the run supplies a repository " +
+      "(a present value IS compile-validated: `invalid-node-repository`/" +
+      "`invalid-node-base-branch`); a genuinely checkout-less graph must be dispatched `repoless: true`, " +
+      "which strips isolation from every node. First-class " +
       "`converge?`/`merge?` cell-policy flags declare review-convergence / landing intent (`merge` " +
       "requires `converge`); a raw `senior:converge`/`senior:merge` jobType is rejected (`raw-converge-node`). " +
+      "An optional per-node ISO-8601 `timeout` (#505) overrides the run-level `nodeTimeout` (and the " +
+      "`PT1H` default) for THIS node's bounded-timeout → escalate boundary, so a legitimately-long node " +
+      "(e.g. a full `senior:feature`) outlasts a quick gate without a spurious escalation; absent → the " +
+      "run/default value. " +
       "An `agent` that opens a PR emits it as a `pr`-typed fact so downstream connector/wait nodes late-bind it.",
   },
   wait: {
@@ -138,14 +154,16 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
   connector: {
     configKey: "connector",
     requiredFields: ["target"],
-    optionalFields: ["dedupeKey", "payload"],
+    optionalFields: ["dedupeKey", "payload", "timeout"],
     sideEffecting: true,
     mayEmit: true,
     summary:
       "An automated, side-effecting outbound action. `payload` for a converge target is " +
       "`{ pr, autoMerge?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
       "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
-      "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
+      "(at-least-once safe). An optional per-node ISO-8601 `timeout` (#505) overrides the run-level " +
+      "`nodeTimeout` (and the `PT1H` default) for THIS node's bounded-timeout → escalate boundary; " +
+      "absent → the run/default value. See connectorTargets for which targets are real vs. forward-declared.",
   },
 };
 

package/app/github.ts

@@ -17,6 +17,7 @@ import { createHash } from "node:crypto";
 // `fetchRepoFile` from here): `classifyMergeability` reads a repo's declared required checks to gate
 // a merge independently of GitHub branch protection.
 import type { MergeProtocol } from "./mergeProtocol.ts";
+import { parsePr } from "./prParse.ts";
 
 /** A GitHub pull-request review, narrowed to the fields the poller needs. */
 export interface GhReview {
@@ -2020,9 +2021,9 @@ export async function createPullRequest(
     ]);
     // `gh pr create` prints the new PR's URL on stdout; parse its number from the canonical path.
     const url = out.trim().split(/\s+/).pop() ?? "";
-    const m = url.match(/\/pull\/(\d+)/);
-    if (!m) throw new Error(`could not parse a PR number from \`gh pr create\` output: ${out.trim()}`);
-    return { number: Number(m[1]), url };
+    const pr = parsePr(url); // the ONE PR-shape grammar (#856)
+    if (!pr) throw new Error(`could not parse a PR number from \`gh pr create\` output: ${out.trim()}`);
+    return { number: pr.number, url };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls`, {

package/app/mcpToolSurface.ts

@@ -116,8 +116,14 @@ export const MCP_TOOL_COUNT_BUDGET = 60;
  * `startFeature` body variants (`FeatureStartByIssue`/`FeatureStartByUrl`) — the Feature tab's
  * "Human approval before merge" checkbox. Measured 87,293 bytes serialized (86,862 → 87,293 — over
  * the old ceiling's 138-byte headroom). Deliberate, documented growth — not schema fat.
+ *
+ * RAISE PROVENANCE — 87_500 → 88_000 (#857): the `pr`-kind probe now also accepts a GitHub PR URL
+ * (`https://github.com/owner/repo/pull/123`) alongside the `owner/repo#123` shorthand, so the shared
+ * `target` description in `openapi.yaml` documents the new accepted handle. Measured 87,559 bytes
+ * serialized (87,497 → 87,559 — over the old ceiling's 3-byte headroom). Deliberate, documented
+ * growth of a real new accepted input format — not schema fat.
  */
-export const MCP_SURFACE_BYTES_BUDGET = 87_500;
+export const MCP_SURFACE_BYTES_BUDGET = 88_000;
 
 /**
  * The eagerly-loaded curated subset MUST stay materially smaller than the full surface — otherwise it

package/app/parseIssue.test.ts

@@ -0,0 +1,87 @@
+// #857 — pin `parseIssue`'s accepted grammar. Its shorthand branch delegates to the canonical
+// `parsePr` (single `owner/repo#N` grammar, #856), and `parsePr` ALSO accepts a `/pull/<n>` URL — so
+// without a guard, every issue-target door (startPlan/startFeature/startEpicSet, plan deps) would
+// silently widen to admit a PR URL. These tests pin that `parseIssue`:
+//   • accepts an `/issues/<n>` URL and the bare `owner/repo#N` shorthand, and
+//   • REJECTS a PR URL (and any other non-`/issues/` GitHub URL), failing closed rather than
+//     resolving it by accident off the shared issue/PR number space.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { parseIssue } from "./plan.ts";
+
+test("parseIssue: accepts an /issues/<n> URL", () => {
+  assertEquals(parseIssue("https://github.com/o/r/issues/42"), {
+    repo: "o/r",
+    number: 42,
+    url: "https://github.com/o/r/issues/42",
+    planKey: "o/r#42",
+  });
+});
+
+test("parseIssue: accepts the bare owner/repo#N shorthand (delegated to the canonical parsePr)", () => {
+  assertEquals(parseIssue("o/r#42"), {
+    repo: "o/r",
+    number: 42,
+    url: "https://github.com/o/r/issues/42",
+    planKey: "o/r#42",
+  });
+  // trims surrounding whitespace like every caller's `.trim()` path
+  assertEquals(parseIssue("  o/r#7  ")?.planKey, "o/r#7");
+});
+
+test("parseIssue: accepts shorthand whose repo is literally named github.com (host-spelling gate, not bare substring) (#857)", () => {
+  // The non-issue-URL gate keys on the `github.com/` HOST spelling, so a valid shorthand carrying
+  // `github.com` as a REPO NAME still parses — parsePr accepts `owner/github.com#N`, so parseIssue must.
+  assertEquals(parseIssue("owner/github.com#42"), {
+    repo: "owner/github.com",
+    number: 42,
+    url: "https://github.com/owner/github.com/issues/42",
+    planKey: "owner/github.com#42",
+  });
+});
+
+test("parseIssue: REJECTS a spoofed/non-GitHub host, userinfo trick, or prose-wrapped issue URL (anchored) (#857)", () => {
+  // The `/issues/<n>` URL branch was UNANCHORED (`/github\.com\/…/`), so `github.com` matched as a
+  // SUBSTRING — a spoofed host suffix (`notgithub.com`), a userinfo trick (`github.com@evil.com`),
+  // or a prose-wrapped occurrence (`see https://github.com/…`) all parsed, and issue intake then
+  // operated on the embedded `owner/repo` — a DIFFERENT target than the submitted value. The branch
+  // must anchor the whole value to the exact GitHub host, mirroring the hardened `parsePr` URL
+  // branch, and fail closed on every one of these.
+  for (const bad of [
+    "https://notgithub.com/o/r/issues/42",
+    "https://evilgithub.com/o/r/issues/42",
+    "https://github.com.evil.com/o/r/issues/42",
+    "https://github.com@evil.com/o/r/issues/42",
+    "see https://github.com/o/r/issues/42",
+    "https://github.com/o/r/issues/42 and more text",
+    "ftp://github.com/o/r/issues/42",
+  ]) {
+    assertEquals(parseIssue(bad), null, `expected null for ${JSON.stringify(bad)}`);
+  }
+});
+
+test("parseIssue: still ACCEPTS canonical issue URLs incl. case-insensitive host, www., and suffixes (#857)", () => {
+  // Anchoring must not narrow the documented grammar: optional scheme, optional `www.`, a
+  // case-insensitive host, and the same trailing `/path`/`?query`/`#fragment` suffixes `parsePr`
+  // preserves all still parse.
+  assertEquals(parseIssue("https://github.com/o/r/issues/42")?.planKey, "o/r#42");
+  assertEquals(parseIssue("github.com/o/r/issues/42")?.planKey, "o/r#42");
+  assertEquals(parseIssue("https://www.github.com/o/r/issues/42")?.planKey, "o/r#42");
+  assertEquals(parseIssue("HTTPS://GITHUB.COM/o/r/issues/42")?.planKey, "o/r#42");
+  assertEquals(parseIssue("https://github.com/o/r/issues/42#issuecomment-1")?.planKey, "o/r#42");
+  assertEquals(parseIssue("https://github.com/o/r/issues/42?foo=bar")?.planKey, "o/r#42");
+});
+
+test("parseIssue: REJECTS a PR URL — parsePr would accept it, but a PR URL is not an issue target (#857)", () => {
+  assertEquals(parseIssue("https://github.com/o/r/pull/7"), null);
+  // even with a trailing path segment or embedded in prose, the non-issue GitHub URL is rejected
+  assertEquals(parseIssue("https://github.com/o/r/pull/7/files"), null);
+  assertEquals(parseIssue("please land https://github.com/o/r/pull/7 now"), null);
+});
+
+test("parseIssue: REJECTS other non-/issues/ GitHub URLs (commit, blob, …) and junk", () => {
+  assertEquals(parseIssue("https://github.com/o/r/commit/deadbeef"), null);
+  assertEquals(parseIssue("https://github.com/o/r"), null);
+  assertEquals(parseIssue(""), null);
+  assertEquals(parseIssue("not a ref"), null);
+});

package/app/plan.ts

@@ -29,6 +29,7 @@ import {
 } from "./github.ts";
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
+import { parsePr } from "./prParse.ts";
 import type { ReadinessProbe } from "./readiness.ts";
 import { requireRepoEnvelopeVars } from "./repoEnvelope.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
@@ -473,21 +474,39 @@ export interface ParsedIssue {
   planKey: string;
 }
 
-/** Parse "owner/repo#123" or a canonical issue URL into its parts. Mirrors parsePr
- * (app/service.ts) but for the /issues/ path. */
+/** Parse "owner/repo#123" or a canonical issue URL into its parts. The URL branch is the /issues/
+ * spelling; the shorthand branch DELEGATES to the canonical {@link parsePr} (`app/prParse.ts`) — the
+ * single source of truth for the `owner/repo#N` shape — rather than carrying a second copy of its
+ * regex (#856/#857: a duplicated shorthand grammar is exactly the drift the single-grammar guard bans).
+ *
+ * `parseIssue` admits an ISSUE reference, and `parsePr` ALSO accepts a `/pull/<n>` URL, so delegating
+ * raw input to it would silently widen every issue-target door (startPlan/startFeature/startEpicSet,
+ * plan deps) to accept a PR URL — resolvable-by-accident (issues and PRs share GitHub's number space)
+ * but undocumented and off-contract (#857). So only the bare `owner/repo#N` shorthand is delegated: a
+ * GitHub URL that is not the `/issues/` spelling handled above (a PR URL, a commit URL, …) fails closed
+ * here. The gate keys on the `github.com/` HOST spelling (host + path separator), which every GitHub
+ * URL carries but the `owner/repo#N` shorthand never does — NOT the bare `github.com` substring, which
+ * a valid shorthand CAN carry as a repository name (`owner/github.com#42`, which `parsePr` accepts).
+ * So the host-spelling gate rejects every non-issue GitHub URL while leaving the shorthand — including
+ * a repo literally named `github.com` — to the one canonical grammar. */
 export function parseIssue(input: string): ParsedIssue | null {
   const s = input.trim();
-  let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)/i);
+  // ANCHORED to the whole string with an exact `github.com` host (optional scheme + `www.`),
+  // mirroring the hardened `parsePr` URL branch: the old UNANCHORED `github\.com/…` matched
+  // `github.com` as a SUBSTRING — a spoofed host suffix (`notgithub.com`), a userinfo trick
+  // (`github.com@evil.com`), or any prose-wrapped occurrence — and issue intake then operated on the
+  // embedded `owner/repo`, a DIFFERENT target than the submitted value (#857 review). Supported URL
+  // suffixes (`?query`, `#fragment`) are preserved via the trailing group.
+  const m = s.match(/^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/issues\/(\d+)(?:[/?#].*)?$/i);
   if (m) {
     const repo = `${m[1]}/${m[2]}`;
     const number = Number(m[3]);
     return { repo, number, url: `https://github.com/${repo}/issues/${number}`, planKey: `${repo}#${number}` };
   }
-  m = s.match(/^([^/]+\/[^#]+)#(\d+)$/);
-  if (m) {
-    const repo = m[1];
-    const number = Number(m[2]);
-    return { repo, number, url: `https://github.com/${repo}/issues/${number}`, planKey: `${repo}#${number}` };
+  if (/github\.com\//i.test(s)) return null;
+  const pr = parsePr(s);
+  if (pr) {
+    return { repo: pr.repo, number: pr.number, url: `https://github.com/${pr.repo}/issues/${pr.number}`, planKey: pr.prKey };
   }
   return null;
 }

package/app/prParse.ts

@@ -18,13 +18,26 @@ export function parsePr(input: unknown): ParsedPr | null {
   // a retrying job. Fail closed to `null` here so every caller resolves safely instead of throwing.
   if (typeof input !== "string") return null;
   const s = input.trim();
-  let m = s.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/i);
+  // ANCHORED to the whole string with an exact `github.com` host (optional scheme + `www.`): an
+  // unanchored `github\.com/…` matched `github.com` as a SUBSTRING — a spoofed host suffix
+  // (`notgithub.com`), a userinfo trick (`github.com@evil.com`), or any prose-wrapped occurrence —
+  // and the pr/epic probe would then silently poll the embedded `owner/repo` (a DIFFERENT target
+  // than the submitted value) or time out (#857). Supported URL suffixes (`/files`, `?query`,
+  // `#fragment`) are preserved via the trailing group. This is the ONE PR-URL grammar; every
+  // downstream (`parsePrTarget`/`parsePlanKey` in readiness.ts, etc.) inherits the anchoring.
+  let m = s.match(/^(?:https?:\/\/)?(?:www\.)?github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)(?:[/?#].*)?$/i);
   if (m) {
     const repo = `${m[1]}/${m[2]}`;
     const number = Number(m[3]);
     return { repo, number, url: `https://github.com/${repo}/pull/${number}`, prKey: `${repo}#${number}` };
   }
-  m = s.match(/^([^/]+\/[^#]+)#(\d+)$/);
+  // The shorthand is EXACTLY `owner/repo#N` — precisely one `/`. The old capture (`[^/]+/[^#]+`)
+  // admitted EXTRA slashes, so a URL-shaped value (`https://example.com/o/r#7`, `//host/o/r#7`) or a
+  // multi-slash path (`a/b/c#9`) parsed to a "PR" whose repo is the whole multi-slash string, and a
+  // canonical-grammar caller (readiness `parsePrTarget`, the workers) then polled that wrong target
+  // via `gh` (#857 review). Fail closed on every extra-slash impersonator: a repo segment carries no
+  // `/`, so the only slash in a valid shorthand is the owner/repo separator.
+  m = s.match(/^([^/#]+\/[^/#]+)#(\d+)$/);
   if (m) {
     const repo = m[1];
     const number = Number(m[2]);

package/app/prShapeSingleGrammar.test.ts

@@ -0,0 +1,154 @@
+// #856 — ONE PR-shape grammar. `app/prParse.ts` `parsePr` is the single source of truth for "is this a
+// PR reference" (`owner/repo#N` or a GitHub PR URL). A second, stricter PR regex in the readiness probe
+// made a delivery-graph `wait[pr merged]` incident on a PR URL the agent contract explicitly allows,
+// while the converge-merge connector (canonical parser) accepted it. Guard the class: no other
+// production module may carry its own copy of EITHER `parsePr` branch — the `/pull/<digits>` URL
+// spelling OR the `owner/repo#<digits>` shorthand (the original #856 duplicate was the shorthand, so
+// guarding only the URL spelling would let the exact failure mode regrow).
+import assert from "node:assert/strict";
+import { readdirSync, readFileSync, statSync } from "node:fs";
+import { join, relative, resolve } from "node:path";
+import { test } from "node:test";
+
+const ROOT = resolve(import.meta.dirname, "..");
+const DIRS = ["app", "workers", "operations", "actions"];
+// The scan must cover EVERY production source file, not only the package subdirs above: the repo's
+// production entrypoint + host glue (`main.ts`) lives at the repo ROOT, so a duplicate grammar added
+// there would leave all three guards green while reopening the #856 class. Include every root-level
+// `.ts` module (not just a hardcoded `main.ts`) so any future root production source is covered too.
+const ROOT_FILES_FILTER = (f: string) => f.endsWith(".ts") && !f.endsWith(".test.ts");
+// The canonical home of each single-source grammar: the PR-shape parser lives in app/prParse.ts, and
+// the issue-shape parser (its `/issues/<n>` URL branch) lives in app/plan.ts `parseIssue`.
+const PARSE_PR = "app/prParse.ts";
+const PARSE_ISSUE = "app/plan.ts";
+
+function walk(dir: string, out: string[]) {
+  let entries: string[];
+  try {
+    entries = readdirSync(dir);
+  } catch {
+    return;
+  }
+  for (const e of entries) {
+    const p = join(dir, e);
+    if (statSync(p).isDirectory()) walk(p, out);
+    else if (p.endsWith(".ts") && !p.endsWith(".test.ts")) out.push(p);
+  }
+}
+
+// The spellings of a duplicate reference-shape grammar, matched against a module's SOURCE TEXT. Each
+// is matched DIGIT-CLASS-, ANCHOR-, and CAPTURE-SPELLING-AGNOSTICALLY — pinned to a capture group
+// (plain OR named) opening on a digit atom (`\d` or `[0-9]`), NOT to one verbatim `#(\d+)$` spelling —
+// so a drifted duplicate cannot stay green by respelling the capture (#857 review): `#(\d+)`,
+// `#([0-9]+)$`, `#(\d+)\b`, `issues/([0-9]+)`, AND the named-capture forms `#(?<number>\d+)`,
+// `/pull/(?<number>\d+)`, `/issues/(?<n>[0-9]+)` are ALL caught. Pinning the scan to a BARE `(` before
+// the digit atom was the fail-open gap: a named capture inserts `?<name>` between the `(` and the
+// digit, so the old `…\(${DIGITS}` patterns never matched it and a duplicate grammar in that spelling
+// regressed the single-grammar invariant while every guard stayed green:
+//  1. the PR-URL branch — a `/pull/(<digits>` capture regex (`github\.com/…/pull/(\d+)`);
+//  2. the PR shorthand branch — a `#(<digits>` capture regex (`^([^/]+/[^#]+)#(\d+)$`), the exact
+//     duplicate that caused #856 — matched with no trailing `)$` so any drifted spelling is caught;
+//  3. the issue-URL branch — an `/issues/(<digits>` capture regex (`parseIssue`'s URL spelling).
+// Written per-branch so this guard's own pattern stays self-consistent with the ban it enforces (a
+// combined `#(\d+)` scan would flag the pattern text).
+const DIGITS = /(?:\\d|\[0-9\])/.source; // `\d` or `[0-9]` as it appears in regex SOURCE text
+// A capture-group OPENING in regex source: a bare `(` OR a named capture `(?<name>` — the `?<name>`
+// prefix is what the old bare-`\(` scan missed. `(?:\?<[A-Za-z_][A-Za-z0-9_]*>)?` is the optional
+// named-capture tag, so both `(\d+)` and `(?<number>\d+)` match. (Lookahead/lookbehind `(?=…)`/`(?<=…)`
+// and non-capturing `(?:…)` openers are not capture groups a parser extracts a number from, so they are
+// intentionally out of scope — the guard bans a duplicate *capture* of the digits.)
+const CAPTURE_OPEN = `\\((?:\\?<[A-Za-z_][A-Za-z0-9_]*>)?`;
+const PULL_URL_REGEX = new RegExp(`\\\\/pull\\\\/${CAPTURE_OPEN}${DIGITS}`);
+const HASH_NUMBER_REGEX = new RegExp(`#${CAPTURE_OPEN}${DIGITS}`);
+const ISSUES_URL_REGEX = new RegExp(`\\\\/issues\\\\/${CAPTURE_OPEN}${DIGITS}`);
+
+function collectProductionFiles(): string[] {
+  const files: string[] = [];
+  for (const d of DIRS) walk(join(ROOT, d), files);
+  // Root-level production modules (e.g. main.ts) are not under any package dir — scan them too.
+  for (const e of readdirSync(ROOT)) {
+    const p = join(ROOT, e);
+    if (!statSync(p).isDirectory() && ROOT_FILES_FILTER(e)) files.push(p);
+  }
+  return files;
+}
+
+function offenders(regex: RegExp, allowed: string): string[] {
+  return collectProductionFiles()
+    .map((f) => relative(ROOT, f))
+    .filter((rel) => rel !== allowed)
+    .filter((rel) => regex.test(readFileSync(join(ROOT, rel), "utf8")));
+}
+
+test("#856/#857: the grammar guard scans the root production entrypoint (main.ts), not only the package dirs", () => {
+  // A duplicate grammar in the root entrypoint/host glue must not slip past the three guards below.
+  const scanned = collectProductionFiles().map((f) => relative(ROOT, f));
+  assert.ok(
+    scanned.includes("main.ts"),
+    "the guard's scanned set must include the root main.ts production entrypoint",
+  );
+});
+
+test("#856: only app/prParse.ts defines a PR-URL regex (`/pull/<digits>`) — everyone else calls parsePr", () => {
+  assert.deepEqual(
+    offenders(PULL_URL_REGEX, PARSE_PR),
+    [],
+    "use parsePr from app/prParse.ts instead of a local PR-URL regex",
+  );
+});
+
+test("#856/#857: only app/prParse.ts defines the `owner/repo#<digits>` shorthand regex — everyone else calls parsePr", () => {
+  // The original #856 duplicate grammar was the SHORTHAND branch (`/^(.+?)#(\d+)$/`), with no
+  // `/pull/` fragment — a URL-only guard stays green while the exact failure mode regrows. Ban the
+  // shorthand capture regex everywhere outside the canonical module too (a `#<digits>` fragment-SHAPE
+  // test with no capture group, e.g. the deliveryGraph redaction exemption, is not a PR parser and
+  // is not matched).
+  assert.deepEqual(
+    offenders(HASH_NUMBER_REGEX, PARSE_PR),
+    [],
+    "use parsePr from app/prParse.ts instead of a local owner/repo#N regex",
+  );
+});
+
+test("#857: only app/plan.ts defines the issue-URL regex (`/issues/<digits>`) — everyone else calls parseIssue", () => {
+  // `parseIssue` is the single source of the issue-shape grammar, exactly as `parsePr` is for the PR
+  // shape. Its `/issues/<n>` URL branch was unguarded, so a second issue-URL parser could drift in and
+  // reopen the #856 class on the issue side. Ban the capture regex everywhere outside app/plan.ts.
+  assert.deepEqual(
+    offenders(ISSUES_URL_REGEX, PARSE_ISSUE),
+    [],
+    "use parseIssue from app/plan.ts instead of a local /issues/<n> regex",
+  );
+});
+
+test("#857: the guard's scan catches a duplicate grammar in ANY capture spelling (mutation fixtures)", () => {
+  // The scan must be CAPTURE-SPELLING-AGNOSTIC: a duplicate parser that respells the capture group
+  // (named capture, `[0-9]` for `\d`, a drifted anchor) must still be flagged, or the single-grammar
+  // invariant regresses behind a green guard. These are the regex SOURCE fragments a duplicate parser
+  // would carry; each must match its branch's scan regex. (The canonical modules' own real spellings
+  // are covered by the allowlist in the tests above — these fixtures prove the *detector* fires on the
+  // drifted forms a copy-paste would actually produce.)
+  // Fixtures are written as the duplicate's regex SOURCE TEXT appears in a `.ts` module — slashes
+  // escaped (`\/`) and the digit atom as `\d` / `[0-9]` — exactly what `readFileSync` reads and the
+  // scan regexes are built to match.
+  const dupSpellings: Array<{ branch: RegExp; src: string; why: string }> = [
+    // PR-URL branch — plain, named-capture, and [0-9] spellings of `/pull/(<digits>`:
+    { branch: PULL_URL_REGEX, src: "github\\.com\\/([^/]+)\\/([^/]+)\\/pull\\/(\\d+)", why: "plain /pull/(\\d+)" },
+    { branch: PULL_URL_REGEX, src: "\\/pull\\/(?<number>\\d+)", why: "named /pull/(?<number>\\d+)" },
+    { branch: PULL_URL_REGEX, src: "\\/pull\\/([0-9]+)", why: "[0-9] /pull/([0-9]+)" },
+    // PR shorthand branch — plain and named-capture spellings of `#(<digits>`:
+    { branch: HASH_NUMBER_REGEX, src: "^([^/]+\\/[^#]+)#(\\d+)$", why: "plain #(\\d+)" },
+    { branch: HASH_NUMBER_REGEX, src: "#(?<number>\\d+)", why: "named #(?<number>\\d+)" },
+    { branch: HASH_NUMBER_REGEX, src: "#([0-9]+)\\b", why: "[0-9] #([0-9]+)" },
+    // Issue-URL branch — plain and named-capture spellings of `/issues/(<digits>`:
+    { branch: ISSUES_URL_REGEX, src: "\\/issues\\/(\\d+)", why: "plain /issues/(\\d+)" },
+    { branch: ISSUES_URL_REGEX, src: "\\/issues\\/(?<n>[0-9]+)", why: "named /issues/(?<n>[0-9]+)" },
+  ];
+  for (const { branch, src, why } of dupSpellings) {
+    assert.ok(branch.test(src), `the guard must flag a duplicate spelled as ${why} (${src})`);
+  }
+  // And a NON-capturing numeric match (no capture group — `(?:\d+)` or a bare `\d+`) is NOT a parser
+  // extraction and must NOT be flagged, so the guard does not false-positive on innocent digit matches.
+  assert.ok(!HASH_NUMBER_REGEX.test("#(?:\\d+)"), "a non-capturing #(?:\\d+) is not a duplicate parser");
+  assert.ok(!PULL_URL_REGEX.test("\\/pull\\/(?:\\d+)"), "a non-capturing /pull/(?:\\d+) is not a duplicate parser");
+});

package/app/readiness.test.ts

@@ -4,6 +4,7 @@
 // pure surface: descriptor parse/validation, each kind's matcher, the injectable `probeOnce`
 // dispatch (no network / subprocess), backoff, the ms→ISO timeout derivation, and log redaction.
 import { test } from "node:test";
+import { parsePr } from "./prParse.ts";
 import { assert, assertEquals, assertRejects, assertStringIncludes, assertThrows } from "#test-assert";
 import {
   type CommandResult,
@@ -33,6 +34,7 @@ import {
   type EpicObservation,
   isFactRefTarget,
   parseEpicLineage,
+  parsePlanKey,
   summariseCapabilityCandidates,
   parsePrView,
   parseReleases,
@@ -525,6 +527,113 @@ test("parseProbe: a valid pr probe round-trips its prState", () => {
   assertEquals(p.match?.prState, "mergeable");
 });
 
+// ── #856: a PR URL is a valid pr target — the agent contract allows "a URL or owner/repo#N" ──────────
+// Field incident (merlin, graph 5e36636255ab): an agent returned its `pr` as a GitHub URL — explicitly
+// allowed by the injected agent contract — the converge-merge connector accepted it (canonical
+// `parsePr`), but the downstream `wait[pr merged]` probe threw at parse (a second, stricter PR regex)
+// and the job incidented with no retries.
+test("#856 parseProbe: a PR URL target parses (same shapes as the canonical parsePr)", () => {
+  const p = parseProbe({ kind: "pr", target: "https://github.com/nanobpm/nano-supervisor/pull/32", match: { prState: "merged" } });
+  assertEquals(p.kind, "pr");
+});
+
+test("#856 probeOnce pr: a PR URL target reads the right repo + number", async () => {
+  const cap: { cmd?: string } = {};
+  const exec = stubExec({ command: { code: 0, stdout: JSON.stringify({ state: "MERGED", mergedAt: "2026-01-01T00:00:00Z" }), stderr: "" }, capture: cap });
+  const p = parseProbe({ kind: "pr", target: "https://github.com/nanobpm/nano-supervisor/pull/32", match: { prState: "merged" } });
+  await probeOnce(p, exec, {});
+  assertStringIncludes(cap.cmd ?? "", "gh pr view '32'");
+  assertStringIncludes(cap.cmd ?? "", "--repo 'nanobpm/nano-supervisor'");
+});
+
+test("#856 parsePrTarget agrees with the canonical parsePr on every PR shape (no second PR-shape grammar)", () => {
+  const cases = ["o/r#12", "https://github.com/o/r/pull/12", "github.com/o/r/pull/12", " o/r#12 ", "o/r@12", "o/r", "#12", "o/r/pull/12"];
+  for (const c of cases) {
+    const canon = parsePr(c);
+    assertEquals(parsePrTarget(c), canon ? { repo: canon.repo, number: String(canon.number) } : null, c);
+  }
+});
+
+// ── #857: an epic target is a CANONICAL planKey (`owner/repo#N`) — never a URL ────────────────────
+// The epic probe keys off the durable lineage root (`owner/repo#N`, `parseIssue`'s `planKey` shape).
+// Delegating its validation to `parsePr` (whose grammar includes GitHub PR URLs) let a URL pass the
+// epic check; `probeOnce` then queried `/lineage?root=<the URL>`, which matches no lineage root, so
+// the probe could only time out instead of failing loudly at submission. Epic targets stay
+// canonical-key-only; URLs are a `pr`-kind-only shape.
+test("#857 parseProbe: an epic probe REJECTS a GitHub PR URL target (a planKey is owner/repo#N, never a URL)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "epic", target: "https://github.com/nanobpm/nano-ide/pull/488", match: { epicState: "merged" } }),
+    Error,
+    "planKey",
+  );
+});
+
+test("#857 parseProbe: an epic probe REJECTS an issue-URL target too (only the canonical key shape)", () => {
+  assertThrows(
+    () => parseProbe({ kind: "epic", target: "https://github.com/nanobpm/nano-ide/issues/488", match: { epicState: "merged" } }),
+    Error,
+    "planKey",
+  );
+});
+
+test("#857 parseProbe: an epic probe still accepts the canonical owner/repo#N planKey", () => {
+  const p = parseProbe({ kind: "epic", target: "nanobpm/nano-ide#488", match: { epicState: "merged" } });
+  assertEquals(p.kind, "epic");
+});
+
+test("#857 probeOnce epic: the lineage read is keyed by the CANONICAL planKey even when the target is padded", async () => {
+  // probeOnce must query `/lineage?root=<owner/repo#N>` — the shape lineage roots are stored under —
+  // derived from the parsed key, not the raw target string, so a padded/oddly-cased literal cannot
+  // silently miss every lineage thread and burn the whole wait budget as a timeout.
+  const capture: { url?: string } = {};
+  const exec: ProbeExec = {
+    async httpGet(url) {
+      capture.url = url;
+      return { status: 200, body: JSON.stringify({ count: 1, threads: [{ rootRequestKey: "o/r#7", stage: "merged", active: false, prCount: 1 }] }) };
+    },
+    async run() {
+      return { code: 0, stdout: "", stderr: "" };
+    },
+  };
+  const r = await probeOnce(parseProbe({ kind: "epic", target: " o/r#7 " }), exec, { NANO_WORKFORCE_BASE_URL: "http://host:3000" });
+  assert(r.ready, "a fully-merged epic goes green");
+  assertStringIncludes(capture.url ?? "", "/app/api/lineage?root=o%2Fr%237");
+});
+
+// ── #857 review: parsePlanKey must FAIL CLOSED on URL-shaped / multi-slash impersonators ──────────
+// `pr.prKey === target.trim()` only proves the value ROUND-TRIPS through `parsePr`; the shorthand
+// branch's repo capture admits extra `/`, so a URL-shaped value round-trips to an identical prKey and
+// was wrongly accepted as a canonical planKey (the epic probe then queried it as a lineage root and
+// could only time out). The discriminator must require EXACTLY `owner/repo` (one slash).
+test("#857 parsePlanKey: REJECTS a URL-shaped value that round-trips through parsePr (https://example.com/o/r#7)", () => {
+  // The exact advisory case: not github.com, but the shorthand branch still parses it (extra `/` in
+  // the repo capture) and `prKey === target` held — so it slipped past the old discriminator.
+  assertEquals(parsePlanKey("https://example.com/o/r#7"), null);
+});
+
+test("#857 parsePlanKey: REJECTS a scheme-relative URL-shaped value (//host/o/r#7)", () => {
+  assertEquals(parsePlanKey("//host/o/r#7"), null);
+});
+
+test("#857 parsePlanKey: REJECTS a multi-slash path that is not owner/repo (a/b/c#9)", () => {
+  assertEquals(parsePlanKey("a/b/c#9"), null);
+});
+
+test("#857 parsePlanKey: still REJECTS a real GitHub PR URL (prKey never equals the URL)", () => {
+  assertEquals(parsePlanKey("https://github.com/o/r/pull/7"), null);
+});
+
+test("#857 parsePlanKey: still ACCEPTS the canonical owner/repo#N key (exactly one slash)", () => {
+  assertEquals(parsePlanKey("owner/repo#7"), { planKey: "owner/repo#7" });
+});
+
+test("#857 parsePlanKey: still ACCEPTS a repo literally named github.com (owner/github.com#42 — one slash)", () => {
+  // Regression guard: the discriminator keys on the slash COUNT, not the host substring, so the
+  // legitimate `owner/github.com#42` shorthand (which `parseIssue`/`parsePr` deliberately allow) is
+  // not collateral damage.
+  assertEquals(parsePlanKey("owner/github.com#42"), { planKey: "owner/github.com#42" });
+});
+
 // ── #570: a fact-bound pr/epic target DISPATCHES (late-binding), a malformed literal still fails ──
 test("parseProbe: a FACT-BOUND pr target (`<node>.<fact>`) parses (resolved at dispatch, not a literal here) — #570", () => {
   // The documented canonical `agent → converge-merge → wait[pr merged]` shape wires the wait's

package/app/readiness.ts

@@ -19,6 +19,7 @@
 // declared {@link EnvKey}; ADR 0004 pinned decision 2) and is redacted from every log line.
 import { isEnvKey, readEnv, readEnvOr } from "./contracts.ts";
 import { allCheckNames, checkConclusions, classifyMergeability, failingCheckNames, type PrState, pendingCheckNames } from "./github.ts";
+import { parsePr } from "./prParse.ts";
 import { isoDuration, isoDurationToMs } from "./reviewWait.ts";
 
 /** The built-in readiness sources. `command` is the escape hatch that subsumes the long tail
@@ -276,14 +277,18 @@ export function parseProbe(raw: unknown, opts?: { allowLateBoundTarget?: boolean
   // compiler rewrite, so a fact-ref target there can never resolve — it must fail loudly at submit.
   if (kind === "pr" && !(allowLateBoundTarget && isFactRefTarget(target)) && !parsePrTarget(target)) {
     throw new Error(
-      `readiness probe (pr): 'target' ('${target}') must be an 'owner/repo#<number>' PR reference (e.g. 'nanobpm/nano-workforce#377')`,
+      `readiness probe (pr): 'target' ('${target}') must be an 'owner/repo#<number>' PR reference or a GitHub PR URL (e.g. 'nanobpm/nano-workforce#377')`,
     );
   }
   // An epic edge is keyed by the durable `planKey` (`owner/repo#NN`, the epic issue) — the stable
   // business id, so a resubmit/replay still resolves (issue #568). Validate it as a literal planKey,
   // exempting a fact-bound reference for the same #548 late-binding reason as `pr` above (and gated
   // on the same `allowLateBoundTarget` opt-in, so a non-delivery-graph caller still fails loudly).
-  if (kind === "epic" && !(allowLateBoundTarget && isFactRefTarget(target)) && !parsePrTarget(target)) {
+  // The validator is the CANONICAL-KEY-ONLY {@link parsePlanKey}, NOT `parsePrTarget`: `parsePr`'s
+  // grammar includes GitHub PR URLs, but a lineage root is only ever stored as `owner/repo#N`, so a
+  // URL target here would pass a `parsePrTarget` check and then query `/lineage?root=<the URL>`,
+  // matching nothing — the probe could only time out instead of failing loudly at submission (#857).
+  if (kind === "epic" && !(allowLateBoundTarget && isFactRefTarget(target)) && !parsePlanKey(target)) {
     throw new Error(
       `readiness probe (epic): 'target' ('${target}') must be an 'owner/repo#<number>' planKey (the epic issue, e.g. 'nanobpm/nano-workforce#374')`,
     );
@@ -813,19 +818,36 @@ export function matchPr(match: ProbeMatch | undefined, pr: PrObservation): Probe
   }
 }
 
-/** Split an `owner/repo#123` PR reference into its repo + numeric PR number, or `null` when it
- * carries no numeric id (so `parseProbe` can reject a never-resolvable target loudly). The `#`
- * separator is the canonical — and only — PR handle: an `@N` form is deliberately NOT accepted, as
- * `owner/repo@<ref>` is the repo-ref syntax used elsewhere (`parseRepoRef`), so a numeric `@N` there
- * would ambiguously mis-parse a git ref as a PR number. Matches the OpenAPI contract + `parseProbe`
- * error, both of which document `owner/repo#N` only. */
+/** Split a PR reference into its repo + numeric PR number, or `null` when it is not one (so
+ * `parseProbe` can reject a never-resolvable target loudly). A THIN ADAPTER over the canonical
+ * {@link parsePr} (`app/prParse.ts`) — the single PR-shape grammar — so every surface agrees on what a PR
+ * reference is: `owner/repo#N` or a GitHub PR URL (`https://github.com/owner/repo/pull/N`). The agent
+ * contract tells producers to return "a URL or `owner/repo#N`" and the converge-merge connector accepts
+ * both; a second, stricter regex here made the downstream `wait[pr merged]` incident on a URL (#856).
+ * An `@N` form is still NOT a PR (`owner/repo@<ref>` is the repo-ref syntax, `parseRepoRef`). */
 export function parsePrTarget(target: string): { repo: string; number: string } | null {
-  const t = target.trim();
-  const m = t.match(/^(.+?)#(\d+)$/);
-  if (!m) return null;
-  const repo = m[1].trim();
-  if (repo === "") return null;
-  return { repo, number: m[2] };
+  const pr = parsePr(target);
+  return pr ? { repo: pr.repo, number: String(pr.number) } : null;
+}
+
+/** Split an epic probe target into its canonical planKey, or `null` when it is not one. Unlike
+ * {@link parsePrTarget} this accepts ONLY the canonical `owner/repo#<number>` key shape — never a
+ * GitHub URL. An epic probe is keyed by the durable lineage root (`owner/repo#N`, the epic issue's
+ * planKey, issue #568), and the lineage read-model stores roots in exactly that shape: admitting a
+ * URL here (via `parsePr`'s wider grammar) would let `probeOnce` query `/lineage?root=<the URL>`,
+ * which matches no root, so the probe could only time out instead of failing loudly at submission
+ * (#857). Derived from the canonical {@link parsePr} (no second grammar): a URL-shaped input parses
+ * fine there, so it is rejected by shape, not by a stricter regex. */
+export function parsePlanKey(target: string): { planKey: string } | null {
+  const pr = parsePr(target);
+  // Canonical-key discriminator: `pr.prKey === target.trim()` proves the value ROUND-TRIPS through
+  // `parsePr` to EXACTLY the submitted string, which only the bare `owner/repo#N` shorthand does — a
+  // URL parses to a *different* prKey (`…/pull/7` → `o/r#7`), so it is rejected by shape. No extra
+  // slash-count check is needed: the shorthand branch's repo capture is now exactly one `/`
+  // (`[^/#]+/[^/#]+`, #857 review), so a URL-shaped/multi-slash value no longer parses at all and the
+  // round-trip test alone is the discriminator. The legitimate `owner/github.com#42` (a repo
+  // literally named `github.com`, one slash) still round-trips.
+  return pr && pr.prKey === target.trim() ? { planKey: pr.prKey } : null;
 }
 
 /** Build the `gh pr view` command that reads a PR's merge-state fields. `gh` reads its token from the
@@ -957,12 +979,16 @@ export async function probeOnce(
       // "Fully merged" is the app's AGGREGATE, not a GitHub read — observe it over the app's own
       // lineage read-model (level-triggered, same poll machinery as `pr`). A fact-bound target that is
       // still unresolved (`<node>.<fact>`) is not a literal planKey, so treat it as "not ready" and
-      // keep waiting rather than issue a malformed request.
-      if (!parsePrTarget(probe.target)) return { ready: false, detail: "epic: unresolved/unparseable planKey (not ready)" };
-      const url = epicLineageUrl(probe.target, readEnvOr("NANO_WORKFORCE_BASE_URL", "", env));
+      // keep waiting rather than issue a malformed request. Key the read (and the thread match) by the
+      // CANONICAL planKey from {@link parsePlanKey} — the shape lineage roots are stored under — never
+      // the raw target string, so a padded literal cannot silently miss every thread and burn the wait
+      // budget, and a URL-shaped value is rejected here rather than queried as a root (#857).
+      const key = parsePlanKey(probe.target);
+      if (!key) return { ready: false, detail: "epic: unresolved/unparseable planKey (not ready)" };
+      const url = epicLineageUrl(key.planKey, readEnvOr("NANO_WORKFORCE_BASE_URL", "", env));
       const resp = await exec.httpGet(url, { accept: "application/json" });
       if (resp.status < 200 || resp.status >= 300) return { ready: false, detail: `epic: lineage read HTTP ${resp.status} (not ready)` };
-      return matchEpic(probe.match, parseEpicLineage(parseJson(resp.body), probe.target));
+      return matchEpic(probe.match, parseEpicLineage(parseJson(resp.body), key.planKey));
     }
   }
 }

package/app/service.test.ts

@@ -1565,6 +1565,61 @@ test("parsePr still resolves a well-formed prKey and PR URL", () => {
   assertEquals(parsePr("https://github.com/owner/repo/pull/7")?.repo, "owner/repo");
 });
 
+// #857 (Copilot "Previously missed" advisory, app/readiness.ts:829/852): the canonical PR-URL
+// branch's host regex was UNANCHORED, so `github.com` matched as a substring of another host
+// (`notgithub.com`), as userinfo of a different host (`github.com@evil.com`), or anywhere inside a
+// prose-wrapped string — the pr/epic probe would then silently poll the embedded `owner/repo`
+// (a DIFFERENT target than the submitted value) or time out. Fail CLOSED on every non-canonical
+// host/wrap; anchoring the ONE grammar fixes both `parsePrTarget` and `parsePlanKey` at once.
+test("#857 parsePr REJECTS a spoofed/non-github host, userinfo trick, or prose-wrapped URL (anchored)", () => {
+  for (const bad of [
+    "https://notgithub.com/o/r/pull/7",
+    "https://evilgithub.com/o/r/pull/7",
+    "https://github.com.evil.com/o/r/pull/7",
+    "https://github.com@evil.com/o/r/pull/7",
+    "see https://github.com/o/r/pull/7",
+    "https://github.com/o/r/pull/7 and more text",
+    "ftp://github.com/o/r/pull/7",
+  ]) {
+    assertEquals(parsePr(bad), null, `expected null for ${JSON.stringify(bad)}`);
+  }
+});
+
+test("#857 parsePr still ACCEPTS canonical GitHub PR URLs incl. supported suffixes", () => {
+  assertEquals(parsePr("https://github.com/owner/repo/pull/7")?.prKey, "owner/repo#7");
+  assertEquals(parsePr("github.com/owner/repo/pull/7")?.prKey, "owner/repo#7");
+  assertEquals(parsePr("https://www.github.com/owner/repo/pull/7")?.prKey, "owner/repo#7");
+  assertEquals(parsePr("https://github.com/owner/repo/pull/7/files")?.prKey, "owner/repo#7");
+  assertEquals(parsePr("https://github.com/owner/repo/pull/7?diff=split")?.prKey, "owner/repo#7");
+  assertEquals(parsePr("https://github.com/owner/repo/pull/7#issuecomment-1")?.prKey, "owner/repo#7");
+});
+
+// #857 (Copilot review, app/prParse.ts): the SHORTHAND branch's repo capture (`[^/]+/[^#]+`) admitted
+// EXTRA `/` characters, so a URL-shaped value (`https://example.com/o/r#7`) or a multi-slash path
+// (`a/b/c#9`) parsed to a "PR" whose repo is the whole multi-slash string — and readiness/worker
+// callers treat this parser as canonical, so that malformed target reached `gh` and polled the wrong
+// repository. The documented grammar is EXACTLY `owner/repo#N` (one slash) or a GitHub PR URL — fail
+// closed on every extra-slash impersonator. This also retires the slash-count discriminator
+// `parsePlanKey` carried (app/readiness.ts): the grammar now IS one-slash.
+test("#857 parsePr REJECTS a shorthand whose repo carries extra slashes (exactly owner/repo#N)", () => {
+  for (const bad of [
+    "https://example.com/o/r#7", // the exact advisory case — a non-GitHub URL via the shorthand branch
+    "https://github.com/o/r#7", // a GitHub URL that is NOT the /pull/<n> spelling
+    "//host/o/r#7", // scheme-relative URL-shaped
+    "a/b/c#9", // a multi-slash path is not owner/repo
+    "a/b/c/d#9",
+  ]) {
+    assertEquals(parsePr(bad), null, `expected null for ${JSON.stringify(bad)}`);
+  }
+});
+
+test("#857 parsePr still ACCEPTS the canonical one-slash shorthand (incl. a repo literally named github.com)", () => {
+  assertEquals(parsePr("owner/repo#7")?.prKey, "owner/repo#7");
+  // A repo literally named `github.com` is ONE slash — the grammar keys on the slash count, not the
+  // host substring, so this legitimate shorthand is not collateral damage (parseIssue relies on it).
+  assertEquals(parsePr("owner/github.com#42")?.prKey, "owner/github.com#42");
+});
+
 // Red/green regression for the level-triggered wave-merge barrier (issue #262). The barrier is
 // armed (`plans.gate_wave = W`) at wave handoff, long BEFORE the token traverses the slow
 // `trial-merge` agent job and finally opens the `wait-wave-merged` subscription. The old

package/docs/agent-guide.md

@@ -564,10 +564,33 @@ layer schedules, it does not re-implement execution):
 
 | kind | config | what it does | may `emits`? |
 |---|---|---|---|
-| `agent` | `agent: { jobType, prompt?, converge?, merge? }` | a worker runs an agent job type (the fan-out body). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. | yes |
+| `agent` | `agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }` | a worker runs an agent job type (the fan-out body) in a fresh checkout of its `repository` (see *Provision every agent node* below). **Side-effecting.** First-class **`converge?` / `merge?`** cell policy (§9.4) — a **declared, compiler-validated** completion-policy flag that *declares* review-convergence / landing intent (`merge` requires `converge`); a raw `senior:converge`/`senior:merge` job is rejected. This slice adds + validates the flags; the delivery-graph execution wiring that consumes them lands in a follow-up slice. **`timeout?`** is an OPTIONAL per-node ISO-8601 SLA (#505) that overrides the run-level `nodeTimeout` (and the `PT1H` default) for this node's bounded-timeout → escalate boundary, so a legitimately-long node outlasts a quick gate without a spurious escalation. | yes |
 | `wait` | `wait: <ReadinessProbe>` | a durable, bounded readiness probe — kind ∈ `http`, `command`, `npm`, `github-check`, `capability`, `pr`, `epic`. Read-only. | yes (binds observed facts) |
 | `human` | `human?: { formKey?, prompt? }` | a scheduled user task + form (the Tasks inbox, §3). Blocks dependents, SLA-bounded, answerable by a human **or** an agent. | yes |
-| `connector` | `connector: { target, dedupeKey?, payload? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. | yes |
+| `connector` | `connector: { target, dedupeKey?, payload?, timeout? }` | an automated, side-effecting outbound action. Carries a `dedupeKey` (at-least-once safe). Three **real targets** ship today — **`converge`**, **`converge-merge`** (unit → base branch) and **`merge-main`** (graph → `main`, the two-level top-level land) (§9.4); other targets are a forward-declared stub. **`timeout?`** — a per-node ISO-8601 SLA (#505), same semantics as the `agent` row. | yes |
+
+> **Provision every `agent` node with a repository — compile will NOT catch it.** Each `agent` cell
+> runs in an isolated checkout: the harness clones the node's **`repository`** (`owner/repo`, no
+> `.git`/URL) at **`baseBranch`** and cuts `feat/<node.id>` off it (#739/#776). `baseBranch` resolves
+> **per field** — the node's own, else the **run-level dispatch `baseBranch`**, else the repo default
+> (an id yielding an ill-formed ref like `a..b`/`a.lock` makes the harness skip `branch.create`, so
+> the agent cuts its own branch). A node with **no `repository`** is staged by compile **without a
+> warning**, then — absent a **run-level fallback** supplied *at dispatch* — Dispatch fails with
+> `N agent node(s) resolve to no repository (…)`. So:
+>
+> - **Declare `repository` on EVERY `agent` node** (and `baseBranch` when it is neither the run-level
+>   base nor the default): a single-repo graph repeats one value; a cross-repo graph names each node's
+>   own repo. Every repo a node's prompt changes must be that node's `repository`.
+> - **`repoless` is a RUN-WIDE mode, not a per-node escape hatch** — it strips isolation from *every*
+>   node. Use it only when **every** `agent` node is checkout-less (pure research/comment work); if
+>   even one needs a checkout, provision repositories instead.
+> - **Self-check before handing over the digest:** every `"kind": "agent"` node has a `repository`;
+>   if you leave some unset, tell the operator which, and that they must pick the run-level
+>   **repository + base-branch fallback** in the Dispatch form (the default mode rejects the graph).
+>
+> A **present** `repository`/`baseBranch` is validated at compile (`invalid-node-repository` /
+> `invalid-node-base-branch`); an **absent `repository`** defers to dispatch (and can fail there); an
+> **absent `baseBranch` is always valid** — it inherits the run-level base, else the repo default.
 
 A **`wait` node's `wait` is a `ReadinessProbe` verbatim** (the same shape feature-run
 intake uses): `{ kind, target, onTimeout?, match?, poll? }`, where `poll` is
@@ -720,12 +743,12 @@ publish and records the version → open+merge PR #303 (repo 3) consuming that v
       "wait": { "kind": "pr", "target": "acme/repo-1#101", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } },
     { "id": "undraft-merge-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-2", "converge": true, "merge": true, "prompt": "Take draft PR acme/repo-2#202 out of draft; converge it to green and land it." } },
     { "id": "manual-publish", "kind": "human",
       "human": { "prompt": "Run the manual OTP-authenticated `npm publish` for @acme/widget and set up OIDC trusted publishing. Record the exact published version." },
       "emits": [ { "name": "publishedVersion", "type": "version", "description": "The version just published to npm." } ] },
     { "id": "open-pr-c", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo-3", "prompt": "Bump @acme/widget to the published version in acme/repo-3 and open PR #303." } },
     { "id": "merge-c", "kind": "wait",
       "wait": { "kind": "pr", "target": "acme/repo-3#303", "match": { "prState": "merged" },
                 "poll": { "everyMs": 300000, "timeoutMs": 259200000 }, "onTimeout": "escalate" } }
@@ -804,7 +827,7 @@ author never knows the PR number at compose time, so reference it by fact:
   "name": "open → converge+merge → wait merged",
   "nodes": [
     { "id": "open", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement the change in acme/repo and open a PR." },
+      "agent": { "jobType": "senior:feature", "repository": "acme/repo", "prompt": "Implement the change in acme/repo and open a PR." },
       "emits": [ { "name": "pr", "type": "pr" } ] },
     { "id": "land", "kind": "connector",
       "connector": { "target": "converge-merge", "payload": { "pr": "open.pr" } } },
@@ -870,7 +893,7 @@ babysitting a `confirm` gate.
                 "onTimeout": "escalate" },
       "emits": [ { "name": "prCount", "type": "number" } ] },
     { "id": "start-b", "kind": "agent",
-      "agent": { "jobType": "senior:feature", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
+      "agent": { "jobType": "senior:feature", "repository": "nanobpm/nano-workforce", "prompt": "Implement nanobpm/nano-workforce#567 and open a PR." } }
   ],
   "edges": [ { "from": "gate-epic", "to": "start-b" } ]
 }

package/openapi.yaml

@@ -1959,7 +1959,7 @@ components:
         target:
           type: string
           minLength: 1
-          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue #548/#570); this rewrite exists ONLY on the delivery-graph dispatch path — other surfaces (e.g. feature-intake readiness) have no such resolver, so they must supply a literal handle.
+          description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference OR a GitHub PR URL (`https://github.com/owner/repo/pull/123`) for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue #548/#570); this rewrite exists ONLY on the delivery-graph dispatch path — other surfaces (e.g. feature-intake readiness) have no such resolver, so they must supply a literal handle.
         onTimeout:
           type: string
           enum: [escalate, fail, continue]
@@ -2025,6 +2025,7 @@ components:
             kind: agent
             agent:
               jobType: senior:feature
+              repository: nanobpm/nano-workforce
               prompt: Implement nanobpm/nano-workforce#567 and open a PR.
         edges:
           - { from: gate-epic, to: start-b }
@@ -2406,7 +2407,7 @@ components:
       # cockpit paste). `previewDeliveryGraph` takes `{ "graphJson": "<serialized DeliveryGraph>" }`.
       example:
         graphJson: >-
-          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
+          {"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}
       required:
         - graphJson
       properties:
@@ -5016,6 +5017,7 @@ paths:
                     kind: agent
                     agent:
                       jobType: senior:feature
+                      repository: nanobpm/nano-workforce
                       prompt: Implement nanobpm/nano-workforce#567 and open a PR.
                 edges:
                   - from: gate-epic
@@ -5176,7 +5178,7 @@ paths:
                               target:
                                 type: string
                                 minLength: 1
-                                description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
+                                description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference OR a GitHub PR URL (`https://github.com/owner/repo/pull/123`) for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
                               onTimeout:
                                 type: string
                                 enum:
@@ -5467,7 +5469,7 @@ paths:
               type: object
               additionalProperties: false
               example:
-                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
+                graphJson: '{"name":"start #567 once epic #488 has fully merged","nodes":[{"id":"gate-epic","kind":"wait","wait":{"kind":"epic","target":"nanobpm/nano-ide#488","match":{"epicState":"merged"},"poll":{"everyMs":300000,"timeoutMs":259200000},"onTimeout":"escalate"},"emits":[{"name":"prCount","type":"number"}]},{"id":"start-b","kind":"agent","agent":{"jobType":"senior:feature","repository":"nanobpm/nano-workforce","prompt":"Implement nanobpm/nano-workforce#567 and open a PR."}}],"edges":[{"from":"gate-epic","to":"start-b"}]}'
               required:
                 - graphJson
               properties:
@@ -5876,10 +5878,10 @@ paths:
                     - kind: agent
                       configKey: agent
                       requiredFields: [jobType]
-                      optionalFields: [prompt, converge, merge]
+                      optionalFields: [repository, baseBranch, prompt, converge, merge, timeout]
                       sideEffecting: true
                       mayEmit: true
-                      summary: "A worker runs an agent job type; an agent that opens a PR emits it as a `pr` fact."
+                      summary: "A worker runs an agent job type in an isolated checkout; declare `repository` (`owner/repo`) on every agent node — the harness clones it at `baseBranch` (else the run-level dispatch base, else the repo default). Optional per-node ISO-8601 `timeout`, plus `converge?`/`merge?` cell-policy flags. An agent that opens a PR emits it as a `pr` fact."
                     - kind: wait
                       configKey: wait
                       requiredFields: [kind, target]
@@ -5890,7 +5892,7 @@ paths:
                     - kind: connector
                       configKey: connector
                       requiredFields: [target]
-                      optionalFields: [dedupeKey, payload]
+                      optionalFields: [dedupeKey, payload, timeout]
                       sideEffecting: true
                       mayEmit: true
                       summary: "An automated outbound action; payload for a converge target is { pr, autoMerge?, dependsOn? }."
@@ -6228,7 +6230,7 @@ paths:
                           target:
                             type: string
                             minLength: 1
-                            description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
+                            description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference OR a GitHub PR URL (`https://github.com/owner/repo/pull/123`) for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
                           onTimeout:
                             type: string
                             enum:
@@ -6376,7 +6378,7 @@ paths:
                           target:
                             type: string
                             minLength: 1
-                            description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
+                            description: The kind-specific target (a URL, a shell command, a `pkg@version`, an `owner/repo@ref`, `github-releases:owner/repo`, an `owner/repo#123` PR reference OR a GitHub PR URL (`https://github.com/owner/repo/pull/123`) for the `pr` kind, or an `owner/repo#NN` planKey — the epic issue — for the `epic` kind). For a `pr`/`epic` target used in a **delivery-graph `wait` node** it may instead be a `<nodeId>.<fact>` late-binding reference the delivery-graph compiler resolves at dispatch (issue
                           onTimeout:
                             type: string
                             enum:

package/operations/getAgentInstructions.test.ts

@@ -61,10 +61,15 @@ test("the guide documents the delivery-graph surface (ADR 0005)", async () => {
   // The closed node vocabulary: assert the exact config snippet for each of the four kinds,
   // so the test fails if §9's node-kind table is removed or reworded — not merely if the bare
   // words "agent"/"wait"/"human"/"connector" appear anywhere else in the guide.
-  assert(md.includes("agent: { jobType, prompt?, converge?, merge? }"), "documents the agent node config");
+  assert(md.includes("agent: { jobType, repository?, baseBranch?, prompt?, converge?, merge?, timeout? }"), "documents the agent node config");
+  // Per-node repository provisioning is only enforced at DISPATCH (a run-level fallback can satisfy it),
+  // so compile stages an unprovisioned graph silently — the guide must tell the authoring agent to
+  // declare `repository` on every agent node, or the operator's Dispatch fails out of the agent's loop.
+  assert(md.includes("Provision every `agent` node with a repository"), "documents per-node repository provisioning");
+  assert(md.includes("resolve to no repository"), "quotes the dispatch-time failure the agent must pre-empt");
   assert(md.includes("wait: <ReadinessProbe>"), "documents the wait node config");
   assert(md.includes("human?: { formKey?, prompt? }"), "documents the human node config");
-  assert(md.includes("connector: { target, dedupeKey?, payload? }"), "documents the connector node config");
+  assert(md.includes("connector: { target, dedupeKey?, payload?, timeout? }"), "documents the connector node config");
   // The fact-edge syntax: an edge is `{ from, to }` and `from` may be a qualified `<nodeId>.<fact>`.
   assert(md.includes("each edge is `{ from, to }`"), "documents the edge shape");
   assert(md.includes("qualified `<nodeId>.<fact>`"), "documents the qualified fact-edge syntax");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.200.1",
+  "version": "0.200.3",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",
@@ -71,7 +71,7 @@
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
     "@nanobpm/urban-testkit": "^1.4.0",
-    "@nanobpm/workflow": "^0.14.0",
+    "@nanobpm/workflow": "^0.15.0",
     "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/git": "^11.0.0",
     "@semantic-release/npm": "^13.1.5",

package/test/deliveryGraphVocabulary-mcp.test.ts

@@ -60,3 +60,35 @@ test("the served payload matches the response schema's required keys (data ⇄ c
     assert(key in payload, `served vocabulary is missing required schema key '${key}'`);
   }
 });
+
+test("the worked example's nodeKind field contract cannot drift from the runtime vocabulary", () => {
+  // The spec's `example:` is a hand-authored YAML copy of the served payload (the runtime cannot be
+  // called from a static spec). It is a deliberately curated SUBSET (fewer kinds / terser summaries),
+  // but the per-kind FIELD CONTRACT it advertises is consumer-facing: a stale `optionalFields` makes
+  // agents author nodes that omit real fields (#739/#776 — `repository`/`baseBranch`/`timeout`), and a
+  // stale `configKey`/`sideEffecting`/`mayEmit` misleads them the same way. Guard the class, not one
+  // field: every nodeKind the example shows must carry EXACTLY the runtime kind's whole contract object
+  // — `kind`, `configKey`, `requiredFields`, `optionalFields`, `sideEffecting`, `mayEmit` — so no part
+  // of the two surfaces can drift apart again. Only `summary` is excluded: the example's is a
+  // deliberately terser curated paraphrase of the runtime's (see this block's preamble).
+  const doc = parseYaml(SPEC_TEXT) as Record<string, any>;
+  const exampleKinds = doc.paths["/delivery-graph/vocabulary"].get.responses["200"].content["application/json"].schema
+    .example?.nodeKinds as Array<Record<string, unknown>> | undefined;
+  assert(Array.isArray(exampleKinds) && exampleKinds.length > 0, "the worked example must list nodeKinds");
+
+  // Compare the full per-kind contract minus `summary` (the sole intentionally-divergent field).
+  const contract = ({ summary: _summary, ...rest }: Record<string, unknown>): Record<string, unknown> => rest;
+
+  const runtimeByKind = new Map(
+    (deliveryGraphVocabulary().nodeKinds as Array<Record<string, unknown>>).map((k) => [k.kind, k]),
+  );
+  for (const shown of exampleKinds) {
+    const runtime = runtimeByKind.get(shown.kind);
+    assert(runtime, `example nodeKind '${String(shown.kind)}' is not a real runtime kind (stale/removed)`);
+    assert.deepEqual(
+      contract(shown),
+      contract(runtime!),
+      `example nodeKind '${String(shown.kind)}' field contract (configKey/requiredFields/optionalFields/sideEffecting/mayEmit) drifted from runtime`,
+    );
+  }
+});