@nanobpm/nano-workforce 0.180.0 → 0.182.0

package/openapi.yaml

@@ -1248,7 +1248,20 @@ components:
                 - markdown
             instructions:
               type: string
-              description: The section's markdown, with example commands keyed to this instance.
+              description: The section's markdown (or a bounded page of it when paginating), with example commands keyed to this instance.
+            start:
+              type: integer
+              description: The CHARACTER offset this page starts at (present only when paginating, issue #740).
+            length:
+              type: integer
+              description: The number of characters returned in this page (present only when paginating).
+            totalLength:
+              type: integer
+              description: The total number of characters in the fully-rendered section (present only when paginating).
+            nextStart:
+              type: integer
+              nullable: true
+              description: The `start` to pass for the next page, or null when this is the last page (present only when paginating).
     SubmitResult:
       type: object
       required:
@@ -1836,6 +1849,30 @@ components:
                   type: string
                   maxLength: 20000
                   description: OPTIONAL steering prompt appended to the node's job brief.
+                repository:
+                  type: string
+                  maxLength: 255
+                  pattern: '^[A-Za-z0-9-]+/(?!.*\.[Gg][Ii][Tt]$)[A-Za-z0-9._-]+$'
+                  description: >-
+                    OPTIONAL per-node `owner/repo` this agent node implements against (#739). A delivery
+                    graph provisions the `io.nanobpm.agentTask.repository` isolation envelope PER agent
+                    cell from THIS field, so a genuinely cross-repo graph (each node a different repo)
+                    isolates correctly without the operator ticking `repoless`. Absent → the node falls
+                    back to the run-level dispatch `repository`. When set it must be exactly `owner/repo`
+                    (a trailing `.git` and any non-`owner/repo` shape are rejected at submit), the same
+                    allowlist `repoEnvelopeVars`/the dispatch door apply. The `sequenceIssues` generator
+                    populates this automatically from the `owner/repo#N` each node implements.
+                baseBranch:
+                  type: string
+                  maxLength: 255
+                  pattern: '^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$'
+                  description: >-
+                    OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the
+                    harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own
+                    `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch`
+                    (else the node's repository default branch). A value that is not a plausible git
+                    branch name is rejected at submit; the pattern mirrors the authoritative server-side
+                    gate (`isPlausibleBranchName`, app/baseBranch.ts).
                 converge:
                   type: boolean
                   description: >-
@@ -2085,17 +2122,20 @@ components:
         action — this request carries NO graph and NO token (the graph is already staged; the operator's
         click is the approval).
 
-        Repository provisioning is REQUIRED by default (#729): the run either names EXACTLY the
-        `repository` + `baseBranch` its `agent` nodes implement against, OR opts out with `repoless: true`
-        for a genuinely checkout-less graph — never both, never neither. Modeled as `oneOf` named variants
-        (Camunda REST v2 pattern, as the convergence/plan/feature start bodies are) so the runtime rejects
-        the "neither/nor" and "both" shapes AT THE EDGE with a 400 that names the allowed shapes, rather
-        than the delegate being the only thing that enforces the mutual exclusivity. Dispatching without
-        either would silently share the worker's launch dir across concurrent fan-out agents (the issue
-        #684 field failure).
+        Repository provisioning is REQUIRED by default (#729) unless the graph is FULLY node-provisioned
+        (#739). The run EITHER names the run-level `repository` + `baseBranch` its `agent` nodes fall back
+        to, OR opts out with `repoless: true` for a genuinely checkout-less graph, OR — when EVERY `agent`
+        node declares its OWN `repository` (a cross-repo graph, #739) — supplies NEITHER (the node-
+        provisioned shape). Modeled as `oneOf` named variants (Camunda REST v2 pattern, as the
+        convergence/plan/feature start bodies are) so the runtime rejects the "both" shape AT THE EDGE
+        with a 400 that names the allowed shapes. The remaining invariant — that no `agent` node resolves
+        to NO repository on a non-`repoless` run — is enforced after the staged graph is loaded (the door
+        has the graph; the request alone does not), so a graph with an unprovisioned node still fails
+        loudly rather than silently sharing the worker's launch dir (the issue #684 field failure).
       oneOf:
         - $ref: "#/components/schemas/DeliveryGraphDispatchWithRepository"
         - $ref: "#/components/schemas/DeliveryGraphDispatchRepoless"
+        - $ref: "#/components/schemas/DeliveryGraphDispatchNodeProvisioned"
     DeliveryGraphDispatchWithRepository:
       description: >-
         The repository-provisioned dispatch shape (#729): names the `repository` + `baseBranch` the run's
@@ -2215,6 +2255,52 @@ components:
             fields are not members of this variant, so supplying either alongside `repoless: true` fails
             `oneOf` matching and is a 400. To provision a repository, use the repository variant (supply
             `repository` + `baseBranch`) and omit `repoless` entirely.
+    DeliveryGraphDispatchNodeProvisioned:
+      description: >-
+        The FULLY node-provisioned dispatch shape (#739): supplies NEITHER a run-level `repository`/
+        `baseBranch` NOR `repoless`, for a cross-repo graph in which EVERY `agent` node declares its own
+        `repository` (so the run needs no uniform fallback and no checkout-less opt-out). The runner
+        seeds each agent cell's `io.nanobpm.agentTask.repository` isolation envelope from that node's own
+        declared repository. The post-load invariant still holds: if ANY `agent` node resolves to no
+        repository under this shape (it declared none and there is no run-level fallback), the dispatch
+        fails loudly with a 400 rather than silently sharing the launch dir — so this shape is only valid
+        for a graph whose every agent node is self-provisioned. `repository`/`baseBranch`/`repoless` are
+        not members of this variant (`additionalProperties: false`), so supplying any of them selects a
+        different variant instead.
+      type: object
+      additionalProperties: false
+      required:
+        - digest
+      properties:
+        digest:
+          type: string
+          description: The staged proposal's content digest (its primary key) — the proposal to dispatch.
+        idempotencyKey:
+          type: string
+          maxLength: 255
+          description: OPTIONAL idempotency key. A re-dispatch with the same key (or, when omitted, the same digest) does not double-launch. Blank/whitespace is treated as absent.
+        nodeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA timeout for `agent`/`connector` nodes (#505) — the
+            bounded-timeout → escalate boundary bound every such node inherits unless it declares its own
+            per-node `timeout`. Absent → the `PT1H` default. An invalid duration is rejected at submit.
+        probeTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 poll budget for `wait` gates (#505) before they escalate. Absent →
+            the `PT30M` default. An invalid duration is rejected at submit.
+        escalationSlaTimeout:
+          type: string
+          pattern: '^[Pp](?!$)(\d+[Yy])?(\d+[Mm])?(\d+[Ww])?(\d+[Dd])?([Tt](?=\d)(\d+[Hh])?(\d+[Mm])?(\d+[Ss])?)?$'
+          maxLength: 64
+          description: >-
+            OPTIONAL run-level ISO-8601 SLA for `human` nodes (#505) before they record an `escalated`
+            outcome. Absent → the `P1D` default. An invalid duration is rejected at submit.
     DeliveryGraphDismissRequest:
       description: >-
         The OPERATOR dismiss request (#520). The cockpit's staged-proposals grid posts the content
@@ -2832,6 +2918,95 @@ components:
           description: >-
             A NAVIGATIONAL cockpit deep-link to the staged proposal (helps the agent hand the human a
             link). It is a pointer only — NOT a dispatch handle; nothing in this response can start a run.
+        superseded:
+          type: array
+          items:
+            type: string
+          description: >-
+            Digests of prior staged proposals sharing this graph's LOGICAL key (derived from its `name`)
+            that this stage replaced — flipped to `superseded` (issue #740). Empty on a first stage. Lets
+            the agent tell the operator precisely which proposals it retired.
+        siblingsStaged:
+          type: integer
+          description: >-
+            How many OTHER live staged proposals remain after this stage (a DIFFERENT logical key from
+            this one) — i.e. proposals this stage did NOT supersede (issue #740). A non-zero count flags
+            potential ORPHANED SIBLINGS (e.g. an earlier stage of the "same" runbook under a different
+            `name`, which supersede does not catch) cluttering the operator's Delivery Graphs list, so
+            the agent can name them for cleanup.
+    SequenceGate:
+      description: >-
+        An interleaved `wait` GATE (issue #740) that must go green before a given issue's agent starts
+        — reusing the exact probe schema `wait` nodes accept (`npm`/`github-check`/`http`/`command`/
+        `capability`/`pr`/`epic`). It lets an author splice e.g. "wait for `@nanobpm/agentic@0.13.0` to
+        publish" between two sequence steps without hand-authoring raw node/edge JSON.
+      type: object
+      additionalProperties: false
+      required:
+        - kind
+        - target
+      properties:
+        kind:
+          type: string
+          minLength: 1
+          description: >-
+            The wait-probe kind — one of the S3 vocabulary kinds (`npm`, `github-check`, `http`,
+            `command`, `capability`, `pr`, `epic`). An unknown kind is a 400.
+        target:
+          type: string
+          minLength: 1
+          description: >-
+            The probe target — kind-specific: `pkg@version` for `npm`, `owner/repo@ref` for
+            `github-check`, a URL for `http`, an `owner/repo#N` PR for `pr`, etc.
+        match:
+          type: object
+          description: >-
+            OPTIONAL kind-specific readiness match fields (e.g. `{ version }` for `npm`,
+            `{ conclusion, checkName }` for `github-check`).
+        poll:
+          type: object
+          additionalProperties: false
+          description: >-
+            OPTIONAL poll budget. Defaults to the bounded merge-gate budget (re-probe every 5 minutes,
+            budget 3 days) so a gate never falls into the 30-minute default trap.
+          properties:
+            everyMs:
+              type: integer
+              minimum: 1
+              description: How often to re-probe (milliseconds).
+            timeoutMs:
+              type: integer
+              minimum: 1
+              description: The total budget before the gate escalates/continues (milliseconds).
+        onTimeout:
+          type: string
+          enum:
+            - escalate
+            - continue
+          description: >-
+            What to do when the gate never goes green within its budget — `escalate` (default) parks on
+            a human; `continue` proceeds anyway. `fail` is not supported on a `wait` node.
+        credentialEnv:
+          type: string
+          minLength: 1
+          description: OPTIONAL env-key name supplying a credential for the probe (`http`/`capability`).
+    SequenceIssueEntry:
+      description: >-
+        One `issues[]` entry with an OPTIONAL leading gate (issue #740) — an object form of a sequence
+        step. The `issue` is implemented + converged + merged like a bare-string entry; the optional
+        `gate` must go green (in addition to the prior issue merging) before this issue's agent starts.
+      type: object
+      additionalProperties: false
+      required:
+        - issue
+      properties:
+        gate:
+          $ref: "#/components/schemas/SequenceGate"
+        issue:
+          type: string
+          minLength: 1
+          maxLength: 255
+          description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
     SequenceIssuesIntent:
       description: >-
         The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES
@@ -2843,15 +3018,21 @@ components:
         `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR
         0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) →
         `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic
-        `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an
-        unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.
+        `poll.timeoutMs`), threading the `pr` fact per §9.4. An `issues[]` entry may be a bare
+        `owner/repo#N` string OR a `{ gate?, issue }` object that interleaves a `wait` gate (the
+        `npm`/`github-check`/… vocabulary) before that issue's agent (issue #740). Invalid input (empty
+        `issues`, an unparseable ref, an unknown gate kind) is a 400 carrying `issues: [{ path, message
+        }]`; nothing is staged.
       type: object
       additionalProperties: false
       example:
-        behind: nanobpm/nano-ide#488
         issues:
-          - nanobpm/nano-workforce#567
-          - nanobpm/nano-workforce#568
+          - nanobpm/nano-ide#557
+          - gate:
+              kind: npm
+              target: "@nanobpm/agentic@0.13.0"
+            issue: jwulf/c8ctl-plugin-nano#186
+          - nanobpm/nano-workforce#738
       required:
         - issues
       properties:
@@ -2868,15 +3049,22 @@ components:
           minItems: 1
           maxItems: 64
           items:
-            type: string
-            minLength: 1
-            maxLength: 255
-            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+            oneOf:
+              - type: string
+                minLength: 1
+                maxLength: 255
+                description: A bare `owner/repo#N` issue reference (no gate) — today's behaviour, byte-for-byte.
+              - $ref: "#/components/schemas/SequenceIssueEntry"
+            description: >-
+              A sequence step — a bare `owner/repo#N` string, or a `{ gate?, issue }` object that
+              interleaves a `wait` gate before that issue's agent (issue #740).
           description: >-
             The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens
             a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once
-            the prior issue has merged. At least one; at most 64 (keeps the generated graph within the
-            compiler's node ceiling).
+            the prior issue has merged (and any interleaved gate has gone green). At least one; at most
+            64. The compiler's node ceiling is enforced SEPARATELY by a node-budget guard (interleaved
+            gates each add nodes, so a fully-gated 64-issue sequence can exceed the ceiling and is
+            rejected there) — `maxItems: 64` bounds the entry count, not the generated node count.
     SequenceIssuesRejected:
       description: >-
         A rejected `sequenceIssues` intent — the input failed validation (empty/oversized `issues`, an
@@ -3847,6 +4035,31 @@ paths:
             with no argument), e.g. `orient`, `submit-pr`, `submit-epic`, `escalations`, `lifecycle`,
             `debug`, `debug-models`, `unstick`, `raise-issue`, `delivery-graphs`, `tool-crosswalk`. Omit it to get the
             table of contents. An unknown id yields a 400 listing the valid ids.
+        - name: start
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 0
+            example: 0
+          description: >-
+            OPTIONAL pagination cursor (issue #740) — the CHARACTER offset into a `section`'s markdown to
+            start at. Passing `start` and/or `length` engages bounded-chunk retrieval so a large section
+            (e.g. `delivery-graphs`) can be paged through without overflowing a tool-result limit; the
+            response echoes `start`, `length`, `totalLength`, and a `nextStart` cursor (null on the last
+            page). Ignored when no `section` is given. Omit both `start` and `length` to get the whole
+            section unchanged.
+        - name: length
+          in: query
+          required: false
+          schema:
+            type: integer
+            minimum: 1
+            example: 12000
+          description: >-
+            OPTIONAL pagination window (issue #740) — the maximum number of CHARACTERS to return for a
+            `section`. Defaults to a bounded page size when `start` is given without `length`. Pair with
+            `start`/`nextStart` to page through an oversized section.
       responses:
         "200":
           description: Either the table of contents (no `section`) or a single section's markdown.
@@ -4161,14 +4374,17 @@ paths:
           application/json:
             schema:
               # BEGIN generated:mcp-body source=#/components/schemas/SequenceIssuesIntent (scripts/inline-mcp-bodies.ts — do not hand-edit)
-              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. Invalid input (empty `issues`, an unparseable ref) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
+              description: 'The `sequenceIssues` INTENT (epic nano-workforce#605, S4) — a high-level shape that GENERATES the canonical "implement issue → converge → merge" delivery graph (operator-guide §9.4) instead of making an agent hand-author its node/edge JSON. It names an ordered list of `issues` to sequence (each issue''s implementation starts once the PRIOR issue has merged) and an OPTIONAL leading `behind` gate (wait for that issue/epic/feature to be fully merged first, §9.5). The door GENERATES, then STAGES the graph through the same compile+stage flow as `compileDeliveryGraph` — it never dispatches (dispatch is an operator-only cockpit action, ADR 0005 Decision 7). For each issue it emits `agent` (`senior:feature`, emits a `pr` fact) → `connector` (`converge-merge`, late-binding that `pr`) → `wait[pr, merged]` (a realistic `poll.timeoutMs`), threading the `pr` fact per §9.4. An `issues[]` entry may be a bare `owner/repo#N` string OR a `{ gate?, issue }` object that interleaves a `wait` gate (the `npm`/`github-check`/… vocabulary) before that issue''s agent (issue #740). Invalid input (empty `issues`, an unparseable ref, an unknown gate kind) is a 400 carrying `issues: [{ path, message }]`; nothing is staged.'
               type: object
               additionalProperties: false
               example:
-                behind: nanobpm/nano-ide#488
                 issues:
-                  - nanobpm/nano-workforce#567
-                  - nanobpm/nano-workforce#568
+                  - nanobpm/nano-ide#557
+                  - gate:
+                      kind: npm
+                      target: '@nanobpm/agentic@0.13.0'
+                    issue: jwulf/c8ctl-plugin-nano#186
+                  - nanobpm/nano-workforce#738
               required:
                 - issues
               properties:
@@ -4182,11 +4398,66 @@ paths:
                   minItems: 1
                   maxItems: 64
                   items:
-                    type: string
-                    minLength: 1
-                    maxLength: 255
-                    description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
-                  description: The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged. At least one; at most 64 (keeps the generated graph within the compiler's node ceiling).
+                    oneOf:
+                      - type: string
+                        minLength: 1
+                        maxLength: 255
+                        description: A bare `owner/repo#N` issue reference (no gate) — today's behaviour, byte-for-byte.
+                      - description: "One `issues[]` entry with an OPTIONAL leading gate (issue #740) — an object form of a sequence step. The `issue` is implemented + converged + merged like a bare-string entry; the optional `gate` must go green (in addition to the prior issue merging) before this issue's agent starts."
+                        type: object
+                        additionalProperties: false
+                        required:
+                          - issue
+                        properties:
+                          gate:
+                            description: 'An interleaved `wait` GATE (issue #740) that must go green before a given issue''s agent starts — reusing the exact probe schema `wait` nodes accept (`npm`/`github-check`/`http`/`command`/ `capability`/`pr`/`epic`). It lets an author splice e.g. "wait for `@nanobpm/agentic@0.13.0` to publish" between two sequence steps without hand-authoring raw node/edge JSON.'
+                            type: object
+                            additionalProperties: false
+                            required:
+                              - kind
+                              - target
+                            properties:
+                              kind:
+                                type: string
+                                minLength: 1
+                                description: The wait-probe kind — one of the S3 vocabulary kinds (`npm`, `github-check`, `http`, `command`, `capability`, `pr`, `epic`). An unknown kind is a 400.
+                              target:
+                                type: string
+                                minLength: 1
+                                description: 'The probe target — kind-specific: `pkg@version` for `npm`, `owner/repo@ref` for `github-check`, a URL for `http`, an `owner/repo#N` PR for `pr`, etc.'
+                              match:
+                                type: object
+                                description: OPTIONAL kind-specific readiness match fields (e.g. `{ version }` for `npm`, `{ conclusion, checkName }` for `github-check`).
+                              poll:
+                                type: object
+                                additionalProperties: false
+                                description: OPTIONAL poll budget. Defaults to the bounded merge-gate budget (re-probe every 5 minutes, budget 3 days) so a gate never falls into the 30-minute default trap.
+                                properties:
+                                  everyMs:
+                                    type: integer
+                                    minimum: 1
+                                    description: How often to re-probe (milliseconds).
+                                  timeoutMs:
+                                    type: integer
+                                    minimum: 1
+                                    description: The total budget before the gate escalates/continues (milliseconds).
+                              onTimeout:
+                                type: string
+                                enum:
+                                  - escalate
+                                  - continue
+                                description: What to do when the gate never goes green within its budget — `escalate` (default) parks on a human; `continue` proceeds anyway. `fail` is not supported on a `wait` node.
+                              credentialEnv:
+                                type: string
+                                minLength: 1
+                                description: OPTIONAL env-key name supplying a credential for the probe (`http`/`capability`).
+                          issue:
+                            type: string
+                            minLength: 1
+                            maxLength: 255
+                            description: An `owner/repo#N` issue reference to implement + converge + merge, in sequence.
+                    description: "A sequence step — a bare `owner/repo#N` string, or a `{ gate?, issue }` object that interleaves a `wait` gate before that issue's agent (issue #740)."
+                  description: "The ordered issues to sequence — each is implemented by a `senior:feature` agent that opens a PR, driven to convergence + merge, and the NEXT issue's implementation starts only once the prior issue has merged (and any interleaved gate has gone green). At least one; at most 64. The compiler's node ceiling is enforced SEPARATELY by a node-budget guard (interleaved gates each add nodes, so a fully-gated 64-issue sequence can exceed the ceiling and is rejected there) — `maxItems: 64` bounds the entry count, not the generated node count."
               # END generated:mcp-body
       responses:
         "200":
@@ -4330,6 +4601,16 @@ paths:
                                 type: string
                                 maxLength: 20000
                                 description: OPTIONAL steering prompt appended to the node's job brief.
+                              repository:
+                                type: string
+                                maxLength: 255
+                                pattern: ^[A-Za-z0-9-]+/(?!.*\.[Gg][Ii][Tt]$)[A-Za-z0-9._-]+$
+                                description: OPTIONAL per-node `owner/repo` this agent node implements against (#739). A delivery graph provisions the `io.nanobpm.agentTask.repository` isolation envelope PER agent cell from THIS field, so a genuinely cross-repo graph (each node a different repo) isolates correctly without the operator ticking `repoless`. Absent → the node falls back to the run-level dispatch `repository`. When set it must be exactly `owner/repo` (a trailing `.git` and any non-`owner/repo` shape are rejected at submit), the same allowlist `repoEnvelopeVars`/the dispatch door apply. The `sequenceIssues` generator populates this automatically from the `owner/repo#N` each node implements.
+                              baseBranch:
+                                type: string
+                                maxLength: 255
+                                pattern: ^(?![/.-])(?!.*[/.]$)(?!.*\.\.)(?!.*//)(?!.*/\.)(?!.*\.lock(?:/|$))[A-Za-z0-9._/-]+$
+                                description: "OPTIONAL per-node base branch this agent node branches off (#739) — the `ref` the harness checks out in the isolated clone (the pre-PR shape: the agent cuts its own `feat/<node.id>` branch off this base). Absent → the run-level dispatch `baseBranch` (else the node's repository default branch). A value that is not a plausible git branch name is rejected at submit; the pattern mirrors the authoritative server-side gate (`isPlausibleBranchName`, app/baseBranch.ts)."
                               converge:
                                 type: boolean
                                 description: 'OPTIONAL first-class CONVERGE policy (ADR 0006 §3 / S5) — a DECLARED, compiler- validated completion-policy flag on this cell node. It declares that the node''s opened PR is to be driven through the review-convergence loop to green as an edge-gated completion policy; this slice adds and validates the flag, with the delivery-graph execution wiring that consumes it landing in a follow-up slice. It supersedes (in intent) the emergent `feature.bpmn` `gw-converge` gateway and the "un-draft + merge #B" prompt prose a delivery-graph `agent` node used to smuggle. Converge and merge are SEPARABLE phases; a node may converge without merging (stop at green and gate the landing behind a downstream node).'

package/operations/compileDeliveryGraph.test.ts

@@ -127,6 +127,10 @@ test("compile-delivery-graph: a changed graph with the same name SUPERSEDES the
     assert(a.body.digest !== b.body.digest, "the changed graph has a new digest");
     assertEquals((await deliveryGraphProposals(data).get(a.body.digest))?.status, "superseded");
     assertEquals((await deliveryGraphProposals(data).get(b.body.digest))?.status, "staged");
+    // The supersede is surfaced in the compile result body so the operator sees the retirement (#740).
+    assertEquals(b.body.superseded, [a.body.digest]);
+    assertEquals(b.body.siblingsStaged, 0);
+    assertEquals(a.body.superseded, []); // the first stage retired nothing
   });
 });
 

package/operations/dispatchDeliveryGraph.test.ts

@@ -318,23 +318,69 @@ describe("dispatchDeliveryGraph — operator dispatch by staged-proposal digest"
   // dispatch envelope-less and let concurrent fan-out agents share (and clobber) the worker's launch
   // dir (issue #684's field failure re-opened as a silent fallback). This "neither/nor" shape is now
   // rejected at the EDGE by the request `oneOf` (the two allowed variants), not only inside the door.
-  test("a dispatch with NEITHER repository/baseBranch NOR repoless is rejected at submit → 400, nothing launched (#729)", async () => {
+  test("a bare dispatch of a graph with an UNPROVISIONED agent node is rejected → 400, nothing launched (#729/#739)", async () => {
     const app = await boot();
     assert.ok(app.api);
     const api = app.api;
-    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    // SIDE_EFFECTING's `open-b` agent node declares NO repository, and this bare dispatch supplies no
+    // run-level fallback and no `repoless` — so the cell would silently share the worker's launch dir.
+    // The door rejects it LOUDLY (#729) rather than launching or degrading (#684).
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: SIDE_EFFECTING });
     const res = await api.call<{ ok?: boolean; error?: string }>("dispatchDeliveryGraph", {
       body: { digest: staged.body.digest },
     });
     assert.equal(res.status, 400);
-    // The `oneOf` edge validator names the two allowed shapes — the neither/nor body matches neither.
-    assert.ok(typeof res.body.error === "string" && res.body.error.length > 0);
+    assert.ok(typeof res.body.error === "string" && res.body.error.includes("open-b"), `error should name the unprovisioned node, got ${res.body.error}`);
     // Loud, not silent: nothing launched and the proposal stays staged (re-dispatchable once a repo /
     // repoless choice is supplied).
     assert.equal((await deliveryGraphRuns(app.db).all()).length, 0);
     assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "staged");
   });
 
+  test("a bare dispatch of a HUMAN-ONLY graph (nothing to provision) SUCCEEDS → 202 running (#739)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    // A graph with no `agent` nodes needs neither a run-level repository nor `repoless` — there is nothing
+    // to isolate. Under #739 a bare `{ digest }` dispatch (the node-provisioned variant) launches cleanly.
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: HUMAN_ONLY });
+    const res = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
+
+  test("a bare dispatch of a fully NODE-PROVISIONED agent graph SUCCEEDS → 202 running (#739)", async () => {
+    const app = await boot();
+    assert.ok(app.api);
+    const api = app.api;
+    // Every agent node declares its OWN repository, so the graph self-provisions each cell's isolation
+    // envelope — no run-level repository, no `repoless`. This is the cross-repo delivery graph #739 enables.
+    const NODE_PROVISIONED = {
+      name: "cross-repo",
+      nodes: [
+        { id: "open-b", kind: "agent", agent: { jobType: "senior:demo", prompt: "implement", repository: "acme/one" } },
+        { id: "publish", kind: "human", human: { prompt: "publish" } },
+      ],
+      edges: [{ from: "open-b", to: "publish" }],
+    };
+    const staged = await api.call<{ digest: string }>("compileDeliveryGraph", { body: NODE_PROVISIONED });
+    const res = await api.call<{ ok: boolean; status: string }>("dispatchDeliveryGraph", {
+      body: { digest: staged.body.digest },
+    });
+    assert.equal(res.status, 202);
+    assert.equal(res.body.ok, true);
+    assert.equal(res.body.status, "running");
+    await app.settle();
+    assert.equal((await deliveryGraphRuns(app.db).all()).length, 1);
+    assert.equal((await deliveryGraphProposals(app.db).get(staged.body.digest))?.status, "dispatched");
+  });
+
   test("a dispatch with ONLY repository (no baseBranch) is rejected → 400, nothing launched (#729)", async () => {
     const app = await boot();
     assert.ok(app.api);

package/operations/dispatchDeliveryGraph.ts

@@ -11,10 +11,12 @@
 // superseded / already-dispatched digest is a clean 400.
 
 import { isPlausibleBranchName } from "../app/baseBranch.ts";
+import { validateDeliveryGraph } from "../app/deliveryGraph.ts";
 import { dispatchDeliveryGraphRun } from "../app/deliveryGraphDispatch.ts";
 import { getStagedProposal, markProposalDispatched, markProposalExpired } from "../app/deliveryGraphProposals.ts";
+import { unresolvedAgentRepoNodes } from "../app/deliveryRunner.ts";
 import { isValidIsoDuration } from "../app/reviewWait.ts";
-import type { DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
+import type { DeliveryGraph, DeliveryGraphTextResult } from "../nano-generated/api-io.d.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 /** Cap an untrusted, rejected duration string before it is echoed into logs/response bodies. `openapi.yaml`
@@ -108,28 +110,27 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     baseBranch = baseRaw;
   }
 
-  // Repository provisioning is REQUIRED on this fan-out door (issue #729): a delivery-graph run whose
-  // `agent` nodes implement against a repo MUST be dispatched with a resolvable `repository` + base
-  // branch so every `senior:*` job provisions an ISOLATED clone. Silently dispatching envelope-less
-  // (issue #684's field failure, re-opened as a silent fallback) let concurrent fan-out workers on one
-  // host share — and clobber — a single launch-dir checkout. So the operator must EITHER supply BOTH
-  // `repository` and `baseBranch`, OR explicitly opt out with `repoless: true` for a genuinely
-  // checkout-less graph — the default can never silently share a checkout.
+  // Repository provisioning (issue #729 / #739): a delivery-graph run whose `agent` nodes implement
+  // against a repo MUST provision an ISOLATED clone per cell — silently dispatching envelope-less (issue
+  // #684's field failure) let concurrent fan-out workers on one host share and clobber a single launch
+  // dir. The operator supplies EITHER a run-level `repository` + `baseBranch` (the fallback default for
+  // nodes that don't declare their own), OR `repoless: true` for a genuinely checkout-less graph, OR —
+  // when every agent node declares its OWN `repository` (#739) — NEITHER. The remaining invariant (no
+  // agent node resolves to NO repository on a non-`repoless` run) is checked AFTER the staged graph is
+  // loaded below, since the request alone cannot see whether every node is self-provisioned.
   const hasRepoless = body !== null && typeof body === "object" && "repoless" in body;
   const repolessRaw = hasRepoless ? body.repoless : undefined;
   // `repoless` is a `true`-ONLY opt-out, exactly as the OpenAPI `oneOf` models it: it is `enum: [true]`
-  // on the repoless variant and NOT a member of the repository variant (`additionalProperties: false`).
+  // on the repoless variant and NOT a member of the other variants (`additionalProperties: false`).
   // So reject any present-but-not-`true` value — `false`, `"yes"`, `0`, … — rather than silently folding
-  // `repoless: false` into the "not repoless" path. Otherwise a caller that bypasses schema validation
-  // could send `{ digest, repository, baseBranch, repoless: false }` (or `{ digest, repoless: false }`)
-  // and slip through with a confusing tri-state the `oneOf` contract never permits.
+  // `repoless: false` into the "not repoless" path.
   if (hasRepoless && repolessRaw !== true) {
     app.log.warn("dispatch-delivery-graph rejected: repoless is a true-only opt-out", { type: typeof repolessRaw });
     return {
       status: 400,
       body: {
         ok: false,
-        error: "`repoless` is a `true`-only opt-out — omit it to provision a repository (with `repository` + `baseBranch`), or set `repoless: true` to dispatch a checkout-less graph",
+        error: "`repoless` is a `true`-only opt-out — omit it to provision a repository (with `repository` + `baseBranch`, or per-node declared repositories), or set `repoless: true` to dispatch a checkout-less graph",
       },
     };
   }
@@ -141,20 +142,6 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
       body: { ok: false, error: "`repoless: true` is mutually exclusive with `repository`/`baseBranch` — pass one or the other, not both" },
     };
   }
-  if (!repoless && (repository === undefined || baseBranch === undefined)) {
-    app.log.warn("dispatch-delivery-graph rejected: missing repository/baseBranch (no repoless opt-in)", {
-      hasRepository: repository !== undefined,
-      hasBaseBranch: baseBranch !== undefined,
-    });
-    return {
-      status: 400,
-      body: {
-        ok: false,
-        error:
-          "a delivery-graph dispatch must provision an isolated checkout: supply BOTH `repository` (`owner/repo`) and `baseBranch`, or set `repoless: true` to dispatch a checkout-less graph — dispatching without either would silently share the worker's launch dir across agents (issue #729)",
-      },
-    };
-  }
 
   // Load the live staged proposal for this digest — refuses an unknown/expired/superseded/already-
   // dispatched digest cleanly (no run is launched).
@@ -179,6 +166,36 @@ export default defineOperation("dispatchDeliveryGraph", async ({ body }, app) =>
     return { status: 400, body: { ok: false, error: `staged proposal ${digest} is corrupt: ${err instanceof Error ? err.message : String(err)}` } };
   }
 
+  // Per-node provisioning invariant (#739): now that the graph is loaded, reject a non-`repoless` run
+  // in which some `agent` node resolves to NO repository — it declared none AND no run-level fallback
+  // was supplied. Such a cell would silently share the worker's launch dir (issue #684), so fail loudly
+  // with a clean 400 here rather than surfacing later as a launch-time throw (a 500). A graph in which
+  // EVERY agent node resolves a repository (declared, or defaulted from the run level) passes — a fully
+  // node-provisioned cross-repo graph needs neither a run-level repository nor `repoless`. The runner
+  // re-enforces this at seed time (defense in depth). Guarded on a well-formed graph; a malformed one
+  // falls through to `dispatchDeliveryGraphRun`'s own validation below.
+  if (!repoless) {
+    const graphErrors = validateDeliveryGraph(graph);
+    if (graphErrors.length === 0) {
+      // biome-ignore lint/plugin: validated staged graph narrowed to its contract after validateDeliveryGraph
+      const typedGraph = graph as DeliveryGraph;
+      const unresolved = unresolvedAgentRepoNodes(typedGraph, { repository, baseBranch });
+      if (unresolved.length > 0) {
+        app.log.warn("dispatch-delivery-graph rejected: unprovisioned agent node(s)", { digest, unresolved });
+        return {
+          status: 400,
+          body: {
+            ok: false,
+            error:
+              `${unresolved.length} agent node(s) resolve to no repository (${unresolved.join(", ")}): each must declare its own ` +
+              "`repository`, or the dispatch must supply a run-level `repository` + `baseBranch` fallback, or set `repoless: true` " +
+              "for a genuinely checkout-less graph — dispatching an unprovisioned node would silently share the worker's launch dir (issue #684/#739)",
+          },
+        };
+      }
+    }
+  }
+
   const dispatched = await dispatchDeliveryGraphRun(app, graph, { runKey: idempotencyKey, title: proposal.title, repository, baseBranch, repoless, ...timeouts });
   if (!dispatched.ok) {
     app.log.warn("dispatch-delivery-graph refused: compile", { digest, errors: dispatched.errors.length });