@nanobpm/nano-workforce 0.201.2 → 0.201.4

package/.github/workflows/ci.yml

@@ -58,6 +58,17 @@ jobs:
       - name: Check agent prompt templates
         run: npm run check:prompts
 
+      # Agent-definition gate (issue #884): every `senior:*` agent service task the app deploys —
+      # hand-authored in resources/processes/*.bpmn OR produced by the delivery-graph compiler — must
+      # carry `<zeebe:agentDefinition agentType="external"/>`, or the engine refuses to mint an
+      # AgentInstance for it and the run persists no durable agentic transcript (the 269 failed
+      # creates on omarchy). Compiled agent cells are deliberately prompt-LESS (the resolved #884
+      # "Decide", Option (a)): the compiler emits the marker on EVERY agent cell unconditionally, and
+      # the gate keys agent-ness on the `<rank>:<task>` colon-form type (the type-keyed scanner), so a
+      # compiled cell that drops the marker fails here, not silently at runtime.
+      - name: Check agent task definitions (external marker)
+        run: npm run check:agent-definitions
+
       # Merge-safety gate: migrations are applied in numeric-prefix order, but each fan-out branch
       # picks "the next" prefix independently, so parallel siblings silently collide on one slot
       # (the historical 004/005/006/007 pairs; recurred on epic #142). This fails the build on any

package/AGENTS.md

@@ -393,13 +393,15 @@ npm run typecheck                                     # tsc --noEmit (Node)
 npm run check                                         # urban check (manifest validation)
 npm run layout:check                                  # BPMN diagram freshness (no drift)
 npm run check:prompts                                 # agent-prompt linkedResource resolution
+npm run check:agent-definitions                       # every senior:* agent task (authored corpus + compiled delivery-graph output) carries the agentDefinition marker
 npm run check:migrations                              # migration prefixes + immutability (no rename/delete/edit of a merged migration)
 npm run check:contracts                               # contract registry (no synonyms / undeclared env keys)
 npm test                                              # unit tests (node --test)
 ```
 
 CI (`.github/workflows/ci.yml`) gates lint, typecheck, `urban check`, `layout:check`,
-the prompt check, the migration-prefix check, the contract-registry check, and the Node test suite. Run `npm run layout <file.bpmn>` after
+the prompt check, the agent-definition check, the migration-prefix check, the
+contract-registry check, and the Node test suite. Run `npm run layout <file.bpmn>` after
 any BPMN flow change and commit the regenerated diagram — the `layout:check`
 gate fails the build otherwise.
 

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.201.4](https://github.com/nanobpm/nano-workforce/compare/v0.201.3...v0.201.4) (2026-10-11)
+
+### Bug Fixes
+
+* **delivery-graph:** emit zeebe:agentDefinition marker on every compiled agent cell (prompt-less, Option (a)) ([#886](https://github.com/nanobpm/nano-workforce/issues/886)) ([1e4fa4f](https://github.com/nanobpm/nano-workforce/commit/1e4fa4f46aad542b2e6fc175a3af0b46d0980f50)), closes [#464](https://github.com/nanobpm/nano-workforce/issues/464) [#745](https://github.com/nanobpm/nano-workforce/issues/745) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#776](https://github.com/nanobpm/nano-workforce/issues/776) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884) [#884](https://github.com/nanobpm/nano-workforce/issues/884)
+
+## [0.201.3](https://github.com/nanobpm/nano-workforce/compare/v0.201.2...v0.201.3) (2026-10-10)
+
+### Bug Fixes
+
+* **repo-envelope:** emit branch.create as a top-level sibling of repository ([#885](https://github.com/nanobpm/nano-workforce/issues/885)) ([abb7b1c](https://github.com/nanobpm/nano-workforce/commit/abb7b1cc8439229724668fa85ffac22afd95c470)), closes [nanobpm/nano-bpm#1344](https://github.com/nanobpm/nano-bpm/issues/1344) [#227](https://github.com/nanobpm/nano-workforce/issues/227) [#882](https://github.com/nanobpm/nano-workforce/issues/882)
+
 ## [0.201.2](https://github.com/nanobpm/nano-workforce/compare/v0.201.1...v0.201.2) (2026-10-08)
 
 ### Bug Fixes

package/SPEC.md

@@ -646,11 +646,25 @@ the app, which deploys on boot), and the next agent job of that type picks it up
 > marker is CI-enforced over the deployed `resources/` process models
 > (`agentTaskTypesMissingExternalMarker`,
 > `agent-marker.test.ts`), so no prompt-bearing agent task in those models relies on
-> prompt-link-only discovery. (The delivery-graph compiler's GENERATED agent BPMN —
-> deployed at run time by `runDeliveryGraph`, not authored under `resources/` — is a
-> separate deployed path NOT covered by this static guard; whether its generated cells
-> should also carry the marker/opt-out convention is tracked separately under issue #745,
-> not #779.) To **exclude** a task from `--auto` — one that must be served only by a
+> prompt-link-only discovery. The delivery-graph compiler's GENERATED agent BPMN —
+> deployed at run time by `runDeliveryGraph`, not authored under `resources/` — is the
+> second producer of agent service tasks, and it is covered too (issue #884): the
+> compiler emits the marker on **every** `agent` cell it compiles. Per the resolved
+> "Decide" half of #884 (Option (a), PR #886 review) a compiled cell carries **no**
+> base-prompt link — the hand-authored process prompts (`prompts/feature.md`, …) are
+> process-specific contracts that require process variables (`variables.task`/
+> `variables.issue`) and a `feat/<task.id>` branch the generic compiled cell never
+> supplies (it seeds only `{jobType, appendPrompt, timeout}` and the harness provisions
+> `feat/<node.id>`, #776), so linking one would hand the cell instructions referencing
+> missing inputs and a conflicting branch. The cell is deliberately prompt-less, steered
+> by its per-node `appendPrompt` alone; the marker alone fixes the #884
+> `createAgentInstance` failure. `npm run check:agent-definitions`
+> (CI gate `check:agent-definitions`, `scripts/check-agent-definitions.ts`) compiles a
+> representative graph — including a prompt-less probe cell — and scans the
+> output with both the prompt-keyed scanner and the prompt-link-independent
+> `externalAgentTaskTypesMissingMarker` (a task is an agent by its `<rank>:<task>`
+> colon-form type alone), so a compiler regression that drops the marker fails the
+> build rather than silently at runtime. To **exclude** a task from `--auto` — one that must be served only by a
 > worker that explicitly subscribes (`--job-type <type>` / a profile capability) — add
 > the inert opt-out property inside its `extensionElements`, nested in the
 > `<zeebe:properties>` wrapper the models and engine expect (as

package/app/agentic/vocab/agent-marker.test.ts

@@ -9,7 +9,8 @@ import { test } from "node:test";
 import { dirname, join, relative } from "node:path";
 import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
-import { agentTaskTypesMissingExternalMarker, promptBearingTaskTypes } from "./job-types.ts";
+import { compileDeliveryGraph } from "../../deliveryGraphCompiler.ts";
+import { agentTaskTypesMissingExternalMarker, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -72,3 +73,31 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent task carries the e
   // Sanity: the models really do declare agent tasks (guard is not vacuously green).
   assert(anyAgentTasks, "the deployed models declare prompt-bearing agent tasks");
 });
+
+test("DEFECT-CLASS GUARD (compiler output, issue #884): every COMPILED delivery-graph agent cell carries the marker", async () => {
+  // The hand-authored corpus above is only HALF the class — the delivery-graph COMPILER
+  // (`app/deliveryGraphCompiler.ts`) is the other producer of agent service tasks, and it emitted
+  // cells with NO `agentDefinition` until #884: every delivery-graph agent run failed AgentInstance
+  // creation (`… has no agentDefinition`) and persisted no durable transcript (269 failed creates on
+  // omarchy). Per the resolved "Decide" half of #884 (Option (a), PR #886 review) a compiled cell is
+  // prompt-LESS (no base-prompt link), so the prompt-keyed scanner cannot see it — it is the
+  // type-keyed half of the union scanner (`missingExternalMarkerAgentTaskTypes`, keyed by the
+  // `<rank>:<task>` colon-form type) that sees these cells. Apply the SAME union to the compiler's
+  // OUTPUT so a compiler regression that drops the marker fails here — not silently at runtime.
+  const r = await compileDeliveryGraph({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+    ],
+    edges: [{ from: "impl", to: "review" }],
+  });
+  assert(r.ok, `expected the graph to compile, got ${JSON.stringify(r)}`);
+  // The compiled agent cells are prompt-LESS (Option (a)), so the prompt-keyed scan sees none — the
+  // union's type-keyed half is what covers them.
+  assertEquals(promptBearingTaskTypes(r.bpmn), []);
+  const missing = missingExternalMarkerAgentTaskTypes(r.bpmn);
+  assert(
+    missing.length === 0,
+    `compiled delivery-graph agent cell(s) missing <zeebe:agentDefinition agentType="external" /> — ${missing.join(", ")}`,
+  );
+});

package/app/agentic/vocab/job-types.test.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 import { assert, assertEquals } from "#test-assert";
 import type { Capability } from "@nanobpm/agentic/protocol";
 import { crewResolver } from "./crew-vocab.ts";
-import { jobTypeToRoutingToken, promptBearingTaskTypes } from "./job-types.ts";
+import { externalAgentTaskTypesMissingMarker, jobTypeToRoutingToken, missingExternalMarkerAgentTaskTypes, promptBearingTaskTypes } from "./job-types.ts";
 
 const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
 
@@ -105,3 +105,135 @@ test("DEFECT-CLASS GUARD: every deployed prompt-bearing agent job type resolves
     );
   }
 });
+
+test("externalAgentTaskTypesMissingMarker flags an UNMAPPED (prompt-less) agent task with no marker", () => {
+  // The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) cannot see this block — it has no
+  // prompt link. The marker scan must key on the colon-form job type ALONE (issue #886 review): a
+  // compiled delivery-graph cell for a bespoke `senior:<task>` (no deployed base prompt, deliberately
+  // prompt-less) must still carry the marker or it runs transcript-less.
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker passes a marked prompt-less agent task and ignores a plain host task", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("externalAgentTaskTypesMissingMarker flags a marked-outside-extensionElements task (placement contract)", () => {
+  // A marker sitting OUTSIDE `<bpmn:extensionElements>` is ignored by the engine, so it must not
+  // "cover" the task here either (the same placement scope the prompt-keyed scanner enforces).
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <zeebe:agentDefinition agentType="external" />
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), ["senior:bespoke"]);
+});
+
+test("externalAgentTaskTypesMissingMarker ignores malformed/non-agent types (no false positives)", () => {
+  // Only a `<rank>:<task>` colon-form type (the `jobTypeToRoutingToken` grammar) keys a block as an
+  // agent task: a dot-form host job, a typeless block, and a malformed colon form are all out of
+  // scope — the scanner must not flag them as unmarked agents.
+  const xml = `
+    <bpmn:serviceTask id="host1">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host2">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature:extra" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host3">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="host4">
+      <bpmn:extensionElements>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTaskTypesMissingMarker(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes unions BOTH scanners — catches a prompt-bearing AND a prompt-less unmarked agent task", () => {
+  // The single "every agent task carries the external marker" invariant (PR #886 review): a
+  // prompt-BEARING senior:* task that loses its marker is caught only by the prompt-keyed scanner,
+  // while a prompt-LESS senior:* task that loses its marker is caught only by the type-keyed scanner.
+  // Scanning by just one leaves the other's blind spot open, so the union must flag BOTH in one pass.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature", "senior:bespoke"]);
+});
+
+test("missingExternalMarkerAgentTaskTypes passes when every agent task is marked and ignores host tasks", () => {
+  const xml = `
+    <bpmn:serviceTask id="host">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.finalize" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:serviceTask id="bespoke">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:bespoke" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), []);
+});
+
+test("missingExternalMarkerAgentTaskTypes de-duplicates a type caught by both scanners", () => {
+  // A prompt-bearing task missing its marker is seen by BOTH the prompt-keyed and the type-keyed
+  // scanner; the union must report it ONCE, not twice.
+  const xml = `
+    <bpmn:serviceTask id="prompted">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:linkedResources>
+          <zeebe:linkedResource resourceId="prompts/feature.md" linkName="prompt" />
+        </zeebe:linkedResources>
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(missingExternalMarkerAgentTaskTypes(xml), ["senior:feature"]);
+});

package/app/agentic/vocab/job-types.ts

@@ -140,6 +140,63 @@ export function agentTaskTypesMissingExternalMarker(xml: string): string[] {
   return missing;
 }
 
+/**
+ * Scan one BPMN document for the job types of agent service tasks — keyed by their `<rank>:<task>`
+ * colon-form `<zeebe:taskDefinition type>` ALONE, NOT by a prompt link — that are MISSING the
+ * engine-native AgentTask marker `<zeebe:agentDefinition agentType="external" />` (issue #884,
+ * PR #886 review). The prompt-keyed scanner (`agentTaskTypesMissingExternalMarker`) is blind to a
+ * DELIBERATELY prompt-less agent task — and EVERY compiled delivery-graph cell is prompt-less (the
+ * resolved #884 "Decide", Option (a): the cell carries the marker alone and is steered by its
+ * per-node `appendPrompt`, never a linked base prompt) — so a marker regression on exactly those
+ * cells would pass that scan vacuously. This scan keys a service task as an AGENT by the same grammar
+ * the crew bridge uses (`jobTypeToRoutingToken`: a single-colon `<rank>:<task>` whose rank is a bare
+ * routing segment), which needs no prompt link, so EVERY agent task — prompt-bearing or not — is
+ * inspected for the marker independently of its prompt status. A dot-form host job (`pr.finalize`),
+ * a typeless block, and a malformed colon form (`senior:feature:extra`) are not agent job types and
+ * are ignored (no false positives). The marker check is scoped to the block's
+ * `<bpmn:extensionElements>` (the engine-honoured PLACEMENT scope, via `extensionElementsOf`) — a
+ * marker sitting outside `extensionElements` is ignored by the engine, so it must not "cover" a
+ * task here either. Returns the offending task types in first-occurrence order (empty when every
+ * agent task is marked).
+ */
+export function externalAgentTaskTypesMissingMarker(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    const type = block.match(TASK_DEFINITION_TYPE)?.[1];
+    if (type === undefined || jobTypeToRoutingToken(type) === undefined) continue;
+    if (EXTERNAL_AGENT_MARKER.test(extensionElementsOf(block))) continue;
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
+/**
+ * The SINGLE "every agent service task carries the engine-native `<zeebe:agentDefinition
+ * agentType="external" />` marker" invariant (issue #745/#884, PR #886 review), as the UNION of both
+ * marker scanners. The two scanners each have a blind spot: `agentTaskTypesMissingExternalMarker` keys
+ * a task as an agent by its PROMPT link, so it cannot see a deliberately prompt-less agent cell;
+ * `externalAgentTaskTypesMissingMarker` keys it by its `<rank>:<task>` colon-form type, so it covers
+ * the prompt-less case but is the newer path. Scanning a corpus with only one leaves the other's blind
+ * spot open — a hand-authored (or compiled) `senior:*` task that loses BOTH its prompt link and its
+ * marker would pass a prompt-keyed-only gate. Every producer of agent tasks (the hand-authored corpus
+ * AND the delivery-graph compiler) is checked against THIS union, so neither half can regress through
+ * the other's blind spot. Returns the distinct offending task types in first-occurrence order (the
+ * prompt-keyed matches first, then any type-keyed-only ones), empty when every agent task is marked.
+ */
+export function missingExternalMarkerAgentTaskTypes(xml: string): string[] {
+  const seen = new Set<string>();
+  const missing: string[] = [];
+  for (const type of [...agentTaskTypesMissingExternalMarker(xml), ...externalAgentTaskTypesMissingMarker(xml)]) {
+    if (seen.has(type)) continue;
+    seen.add(type);
+    missing.push(type);
+  }
+  return missing;
+}
+
 /**
  * Scan one BPMN document for the job types of agent service tasks that OPT OUT of the harness
  * `--auto` reconciliation (issue #779) — those carrying `<zeebe:property

package/app/contracts.ts

@@ -448,9 +448,9 @@ export const WIRE_CONTRACTS = {
     name: "io.nanobpm.agentTask.repository",
     owner: "app/repoEnvelope.ts",
     semantics:
-      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create`. On the PRE-PR path `branch.create` is the deterministic `feat/<task.id>` (emitted for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). On the PR-based paths `branch.create` is set to the PR HEAD branch itself (equal to `ref`, jwulf/c8ctl-plugin-nano#231): without it the harness's base-branch guard treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR head branch. So `branch.create` is present on both the pre-PR and PR-based paths (only a blank/omitted value drops the key). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231).",
+      "Repo-provisioning envelope the app emits as a `createInstance` process variable (`repoEnvelopeVars`, app/repoEnvelope.ts) and the c8ctl worker harness consumes to provision an isolated clone — instead of the agent inheriting the worker's launch dir (issue #684). `ref` is the branch checked out: the PR HEAD branch on the PR-based paths (review-round / fix-ci / rebase), or — on the PRE-PR implementation path (feature.bpmn / plan-fanout's `implement-cell`, issue #684; the delivery-graph runner's agent cells, issue #686) — the BASE branch, off which the harness cuts a new feature branch named by the optional `branch.create`. On the PRE-PR path `branch.create` is the deterministic `feat/<task.id>` (emitted for a single-task feature run AND — per issue #776 — the deterministic `feat/<node.id>` for each single-instance delivery-graph agent cell, injected per-cell by `agentNodeRepoEnvelope`/`app/deliveryRunner.ts` so a forgetful agent can never be left committing on the base branch and stranding its run on a non-ff push; the epic plan-fanout seed still omits it because its MI children each cut a per-child `feat/<task.id>` the app can't name at compile time, so those agents branch themselves). On the PR-based paths `branch.create` is set to the PR HEAD branch itself (equal to `ref`, jwulf/c8ctl-plugin-nano#231): without it the harness's base-branch guard treats the checkout as base-like and cuts a throwaway `nano/agent-work/<base>-<run>` fallback, stranding the round's commits OFF the PR; with `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR head branch. So `branch.create` is present on both the pre-PR and PR-based paths (only a blank/omitted value drops the key). Beyond `{provider,url,ref}`, it carries clone-shaping fields for large monorepos (issue #287): `singleBranch:true` + `filter:\"blob:none\"` (a branch-scoped, blobless partial clone — trees fetched up-front, blobs lazily, no `--depth 1` so the merge-base/3-dot diff stays valid) and an optional `baseRef` (the PR base branch, emitted only when resolvable, so the harness fetches its tip and keeps `origin/<base>` reachable) and a `cloneTimeoutMs` (from `NANO_PR_CLONE_TIMEOUT_MS`, default 600000 = 10 min) that raises the harness's 120s default so a large monorepo's blobless single-branch clone provisions instead of dying at 120s (issue #694). World-restore (issue #324, ADR 0062 Slice 4/5): an optional `sha` — the last durable push-checkpoint — is emitted so a REPLACEMENT activation on a fresh worktree reconstructs the tree to the EXACT pushed SHA (inverting the round's `git push` into `git fetch && git checkout <sha>`), omitted when the PR has no checkpoint yet. The field is named `sha` because that is the field the c8ctl harness's `provisionRepo` reads to drive the checkout — an earlier `commitSha` key was a silent no-op (issue #695). Alongside the `repository` slice the envelope carries a sibling `task.allowPr: true` (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the git credential (GITHUB_TOKEN, or the `gh` default) for repo provisioning behind that flag, so every repo-backed envelope sets it or the clone dies with `unable to get password from user`; the repoless path emits no envelope and so no `task`. Gated on c8ctl provisioner support (jwulf/c8ctl-plugin-nano#91, branch-cut guard jwulf/c8ctl-plugin-nano#231). PLACEMENT (issue #882): `branch` is emitted as a TOP-LEVEL sibling of `repository` (and of `task`) under the namespace — the harness `normalizeTaskEnvelope` reads `branch` from the envelope ROOT (`isPlainObject(raw.branch)`), never from `repository.branch`, so the producer must not nest it there (nesting was the #227 two-sides-of-one-contract drift that left `branch.create` silently unread — nanobpm/nano-bpm#1344). The round-trip contract test `app/repoEnvelope.test.ts` pins producer and consumer together.",
     shape:
-      'io.nanobpm.agentTask: { repository: { provider: "github", url: string, ref?: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string, branch?: { create: string } }, task: { allowPr: true } }',
+      'io.nanobpm.agentTask: { repository: { provider: "github", url: string, ref?: string, singleBranch: true, filter: "blob:none", cloneTimeoutMs: number, baseRef?: string, sha?: string }, branch?: { create: string }, task: { allowPr: true } }  — `branch` is a TOP-LEVEL sibling of `repository` (issue #882): the harness `normalizeTaskEnvelope` reads it from the envelope root (`isPlainObject(raw.branch)`), NOT from `repository.branch`, so the flattened header is `io.nanobpm.agentTask.branch.create` (never `…repository.branch.create`).',
   },
   "epicSet.submit": {
     category: "wire",
@@ -538,9 +538,9 @@ export const WIRE_CONTRACTS = {
   "agentTask.agentDefinition": {
     category: "wire",
     name: "agentTask.agentDefinition",
-    owner: "resources/processes/*.bpmn",
+    owner: "resources/processes/*.bpmn + app/deliveryGraphCompiler.ts",
     semantics:
-      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
+      "The engine-native AgentTask marker (issue #745, umbrella #746 — Camunda 8.10 parity). Every `senior:*` agent service task carries `<zeebe:agentDefinition agentType=\"external\" />` INSIDE its `<bpmn:extensionElements>`, COEXISTING with the existing `<zeebe:taskDefinition type=\"senior:*\"/>` dispatch verb (the verb stays, per #464). The marker makes the element eligible for engine-native AgentInstance minting by the worker harness (jwulf/c8ctl-plugin-nano#194): the harness mints Create/Update/Complete AgentInstance/AgentHistory records against the pinned engine (`@nanobpm/engine-wasm` 0.8.6, broker REST, SDK) while the element still emits its NORMAL `senior:*` job. `agentType=\"external\"` means the agent runs OUTSIDE the engine (a remote fleet worker), not an engine-embedded model call. This is the PRODUCER half; the durable AgentInstance/AgentHistory it mints is read back by the Cockpit historical view via `searchAgentInstanceHistory` (the CONSUMER half — see the `agentTask.historyRead` contract; the read path landed on `@nanobpm/urban`'s EngineClient in urban 0.93 / nanobpm/nano-ide#563). It is authored in the hand-written BPMN semantic model, NOT the generated `<bpmndi:…>` DI, and survives `npm run layout` untouched. The class is EVERY agent service task the app generates (issue #884): the hand-authored corpus AND every delivery-graph-compiler `agent` cell. The compiler emits the marker on EVERY cell and — per the resolved \"Decide\" half of #884 (Option (a), PR #886 review) — NO base-prompt link: the hand-authored process prompts are process-specific contracts (they require process variables and a `feat/<task.id>` branch the generic compiled cell never supplies), so a compiled cell is deliberately prompt-LESS and steered by its per-node `appendPrompt` alone. `npm run check:agent-definitions` (scripts/check-agent-definitions.ts, in CI) gates BOTH producers: it scans the compiled output with the prompt-keyed `agentTaskTypesMissingExternalMarker` AND the prompt-link-independent `externalAgentTaskTypesMissingMarker` (an agent task is keyed by its `<rank>:<task>` colon-form type alone, so a marker regression on a prompt-less cell cannot hide). Add the marker to a NEW `senior:*` agent task — never a second/synonym marker element.",
     shape: '<zeebe:agentDefinition agentType="external" /> (sibling of <zeebe:taskDefinition> in a senior:* service task\'s extensionElements)',
   },
   "agentTask.autoSubscribe": {

package/app/deliveryGraphCompiler.test.ts

@@ -14,6 +14,7 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DeliveryGraph } from "../nano-generated/api-io.d.ts";
+import { missingExternalMarkerAgentTaskTypes } from "./agentic/vocab/job-types.ts";
 import { compileDeliveryGraph, digestInvisibleRawValues, graphCarriesRedactedSecrets, nodeDisplay, redactFreeText, resumeValidVar } from "./deliveryGraphCompiler.ts";
 import { isDeliveryEscalationTwin } from "./deliveryHuman.ts";
 
@@ -158,6 +159,86 @@ test("trust bound: every node inlines an embedded subProcess delegating to an al
   assert(/<bpmn:userTask id="delivery-human-task__n\d+__esc"/.test(r.bpmn), "a bounded node inlines an escalation user task");
 });
 
+test("#884 agentDefinition: every compiled agent cell carries the engine-native AgentTask marker (durable transcript)", async () => {
+  // Issue #884: a compiled `agent` cell's service task carried NO
+  // `<zeebe:agentDefinition agentType="external"/>`, so the engine refused to attach an AgentInstance
+  // to it (`createAgentInstance failed — … has no agentDefinition`) and every delivery-graph agent run
+  // persisted NO durable agentic transcript. The hand-authored processes declare the marker on every
+  // `senior:*` task (issue #745); the compiler must emit it on every agent cell it generates — the
+  // defect CLASS is "every agent service task the app generates", so this guards the compiler output
+  // through the SAME canonical union scanner (`missingExternalMarkerAgentTaskTypes`, the one the
+  // repo-wide gate in `check-agent-definitions.ts` uses) rather than a second, driftable regex.
+  const r = await compileOk(RELEASE_RUNBOOK);
+  // RELEASE_RUNBOOK has exactly one agent node (`open-b` → `senior:feature`); its compiled service
+  // task is `<el>_task`. A compiled agent cell is prompt-LESS (the resolved #884 "Decide", Option (a)),
+  // so it is the type-keyed half of the union scanner (keyed by the `<rank>:<task>` colon-form type)
+  // that sees it — and the marker must be present on THAT cell, not merely somewhere in the document
+  // (a stray marker on a DIFFERENT element would not make THIS cell eligible for AgentInstance minting).
+  const taskBlock = [...r.bpmn.matchAll(/<bpmn:serviceTask id="n\d+_task"[\s\S]*?<\/bpmn:serviceTask>/g)]
+    .map((m) => m[0])
+    .find((b) => b.includes('<zeebe:taskDefinition type="senior:feature" />')) ?? "";
+  assert(taskBlock !== "", "the agent node compiles to an inner senior:feature service task");
+  const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(taskBlock)?.[0] ?? "";
+  assert(
+    /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+    `the compiled agent cell carries <zeebe:agentDefinition agentType="external" /> inside its extensionElements, got:\n${taskBlock}`,
+  );
+  // The marker is a SIBLING of the dispatch verb, which stays (per #464): both must be present.
+  assert(/<zeebe:taskDefinition type="senior:feature" \/>/.test(ext), "the dispatch verb stays alongside the marker");
+  // And the CANONICAL union scanner — the one the repo-wide guard applies — finds NO unmarked agent
+  // task in the whole compiled document (it keys an agent by its colon-form type, which every compiled
+  // agent cell carries; a connector/wait/host task is not colon-form and is correctly ignored).
+  assertEquals(missingExternalMarkerAgentTaskTypes(r.bpmn), []);
+});
+
+test("#884 agentDefinition: EVERY agent cell in a multi-agent graph is marked (not just the first)", async () => {
+  // A marker emitted once (or only on a specific shape) would leave sibling agent cells transcript-less
+  // — the 269 failed creates on omarchy came from several processes. Compile a graph whose agent nodes
+  // differ (distinct job types, one with a repo spec + emits, one bare) and assert EVERY compiled
+  // `<el>_task` service task carries the marker inside its own extensionElements.
+  const r = await compileOk({
+    nodes: [
+      { id: "impl", kind: "agent", agent: { jobType: "senior:feature", repository: "nanobpm/nano-workforce", prompt: "implement #1" }, emits: [{ name: "pr", type: "pr" }] },
+      { id: "review", kind: "agent", agent: { jobType: "senior:pr-review" } },
+      { id: "ship", kind: "agent", agent: { jobType: "senior:trial-merge", prompt: "merge it" } },
+    ],
+    edges: [
+      { from: "impl", to: "review" },
+      { from: "review", to: "ship" },
+    ],
+  });
+  const taskBlocks = [...r.bpmn.matchAll(/<bpmn:serviceTask id="(n\d+_task)"[\s\S]*?<\/bpmn:serviceTask>/g)];
+  assertEquals(taskBlocks.length, 3, "all three agent nodes compile to an inner service task");
+  for (const [block, id] of taskBlocks) {
+    const ext = /<bpmn:extensionElements>[\s\S]*?<\/bpmn:extensionElements>/.exec(block)?.[0] ?? "";
+    assert(
+      /<zeebe:agentDefinition agentType="external" \/>/.test(ext),
+      `agent cell ${id} is missing <zeebe:agentDefinition agentType="external" /> in its extensionElements`,
+    );
+  }
+});
+
+test("#884 prompt-less: a compiled agent cell carries NO base-prompt link (Option (a))", async () => {
+  // The resolved "Decide" half of #884 (Option (a), PR #886 review): a compiled agent cell is
+  // deliberately prompt-LESS. The hand-authored process prompts (`prompts/feature.md`, …) are
+  // process-specific contracts — they require process variables (`variables.task`/`variables.issue`)
+  // and a `feat/<task.id>` branch the generic compiled cell never supplies (it seeds only
+  // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776) — so linking
+  // one hands the cell instructions referencing missing inputs and a conflicting branch. The cell is
+  // steered by its per-node `appendPrompt` alone; the marker alone fixes the createAgentInstance
+  // failure. Pin that NO compiled agent cell emits a prompt `linkedResource` — for a mapped-looking
+  // type, a bespoke type, AND a prototype-chain jobType (which must never resolve to a bogus link).
+  for (const jobType of ["senior:feature", "senior:pr-review", "senior:no-such-prompt", "constructor", "__proto__", "toString"]) {
+    const r = await compileOk({ nodes: [{ id: "p", kind: "agent", agent: { jobType } }], edges: [] });
+    assert(
+      !r.bpmn.includes('linkName="prompt"'),
+      `compiled agent cell ${JSON.stringify(jobType)} must link NO base prompt (prompt-less, Option (a)), got:\n${
+        r.bpmn.split("\n").filter((l) => l.includes("linkedResource")).join("\n")
+      }`,
+    );
+  }
+});
+
 test("late-binding: a fact-qualified edge threads a boundFacts input into the consumer subProcess", async () => {
   const r = await compileOk(RELEASE_RUNBOOK);
   // `publish.resolvedArtifact -> consume`: the connector subProcess receives the human's emitted fact as

package/app/deliveryGraphCompiler.ts

@@ -1931,7 +1931,7 @@ function innerBodyLines(w: NodeWiring, requiredEmits: ReadonlySet<string>, displ
       // be a leak here), but the `descriptor` is embedded by `serviceBodyLines` into the operator-visible
       // timeout / producer-contract escalation FEEL `prompt` — so it takes the SAME display redaction
       // `nodeDisplay` applies, never the raw value (issue #778 review — thread deliveryGraphCompiler.ts:1606).
-      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits);
+      return serviceBodyLines(el, node.id, attr("type", node.agent.jobType), [], redactConnectorValue(node.agent.jobType), contractGate, agentRepoSpecHeaderLines(node), displayName, "agent", nodeEmits, undefined);
     }
     case "connector": {
       // TRIM the target before building the escalation descriptor — `nodeDisplay` and the connector
@@ -2113,6 +2113,27 @@ function serviceBodyLines(
   const taskExt = [
     "        <bpmn:extensionElements>",
     `          <zeebe:taskDefinition ${taskDefAttr} />`,
+    // Issue #884: an `agent` cell MUST carry the engine-native AgentTask marker
+    // (`<zeebe:agentDefinition agentType="external"/>`, the `agentTask.agentDefinition` contract —
+    // issue #745) INSIDE its extensionElements, as a sibling of the dispatch verb. Without it the
+    // engine refuses to attach an AgentInstance to the element (`createAgentInstance failed — … has
+    // no agentDefinition`), so every delivery-graph agent run persisted NO durable agentic
+    // transcript (269 failed creates on omarchy). The hand-authored `senior:*` tasks all declare it
+    // (guarded by `agent-marker.test.ts`); the compiler emits it on EVERY agent cell it generates —
+    // the defect class is "every agent service task the app generates". A `connector` delegates to a
+    // HOST worker (`pr.delivery-connector`), not an external agent, so it is NOT marked.
+    ...(kind === "agent" ? ['          <zeebe:agentDefinition agentType="external" />'] : []),
+    // Issue #884 (the "Decide" half — resolved Option (a), PR #886 review): an agent cell carries ONLY
+    // the marker above and NO base-prompt `linkedResource`. The hand-authored process prompts
+    // (`prompts/feature.md`, `prompts/review-round.md`, …) are PROCESS-specific contracts, not generic
+    // cell contracts — they require process variables (`variables.task`/`variables.issue`) and a branch
+    // (`feat/<task.id>`) the generic compiled cell never supplies (it seeds only
+    // `{jobType, appendPrompt, timeout}` and the harness provisions `feat/<node.id>`, #776). Linking one
+    // would hand every compiled cell instructions referencing missing inputs and a conflicting branch.
+    // The cell is therefore deliberately prompt-LESS: the per-node `appendPrompt` FEEL (runner-seeded
+    // from `node.agent.prompt` + the emit/producer contracts) is its sole steering channel, matching the
+    // historically-intentional design (`deliveryRunner.ts` — "the delivery agent node carries no
+    // base-prompt resource"). The marker alone is what fixes the #884 `createAgentInstance` failure.
     ...(taskProps.length > 0 ? ["          <zeebe:properties>", ...taskProps, "          </zeebe:properties>"] : []),
     ...taskHeaders,
     "          <zeebe:ioMapping>",

package/app/deliveryRunner.test.ts

@@ -533,7 +533,7 @@ test("prepareDeliveryGraph injects the repository envelope PER agent cell from t
   assert(headers.some((h) => h.includes('task.allowPr" value="true"')), `expected a task.allowPr header, got ${JSON.stringify(headers)}`);
   // The deterministic per-node isolation branch (issue #776): the harness cuts `feat/<node.id>` itself,
   // so the agent can never be left committing on the base branch (a non-ff push that strands the run).
-  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/open-b"')), `expected a per-node branch.create header, got ${JSON.stringify(headers)}`);
+  assert(headers.some((h) => h.includes('io.nanobpm.agentTask.branch.create" value="feat/open-b"')), `expected a per-node branch.create header, got ${JSON.stringify(headers)}`);
   // No `__repoSpec` marker survives injection — it is the compiler's digest-stable anchor only.
   assert(!p.bpmn.includes("__repoSpec"), "the __repoSpec marker is fully replaced");
   // No run-root `io.nanobpm.agentTask` variable — the envelope rides headers now, not a run variable.
@@ -590,7 +590,7 @@ test("a declared repository WITHOUT a base branch omits ref/baseRef — the harn
   assert(!headers.some((h) => h.includes("repository.baseRef")), "no baseRef either");
   // Even without a known base, the deterministic isolation branch is still emitted (issue #776): the
   // harness cuts `feat/<node.id>` off the cloned default tip, so the agent never commits on the default.
-  assert(headers.some((h) => h.includes('repository.branch.create" value="feat/a"')), `expected branch.create even without a base, got ${JSON.stringify(headers)}`);
+  assert(headers.some((h) => h.includes('io.nanobpm.agentTask.branch.create" value="feat/a"')), `expected branch.create even without a base, got ${JSON.stringify(headers)}`);
 });
 
 test("each agent cell gets its OWN deterministic feat/<node.id> branch.create — never a shared branch (#776)", async () => {
@@ -603,7 +603,7 @@ test("each agent cell gets its OWN deterministic feat/<node.id> branch.create
     edges: [{ from: "impl-a", to: "impl-b" }],
   };
   const p = await prepareOk(graph, {});
-  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("io.nanobpm.agentTask.branch.create"));
   // Two distinct cells → two distinct per-node branches, so no two agents can collide on one branch.
   assert(branches.some((h) => h.includes('value="feat/impl-a"')), `expected feat/impl-a, got ${JSON.stringify(branches)}`);
   assert(branches.some((h) => h.includes('value="feat/impl-b"')), `expected feat/impl-b, got ${JSON.stringify(branches)}`);
@@ -612,7 +612,7 @@ test("each agent cell gets its OWN deterministic feat/<node.id> branch.create
 
 test("an explicit repoless run emits NO branch.create — no envelope at all (#776/#729)", async () => {
   const p = await prepareOk(GRAPH, { repoless: true });
-  assert(!p.bpmn.includes("repository.branch.create"), "a repoless run carries no isolation branch either");
+  assert(!p.bpmn.includes("io.nanobpm.agentTask.branch.create"), "a repoless run carries no isolation branch either");
 });
 
 test("a node id that derives an invalid git ref degrades to NO branch.create — never emits an unusable feat/... (#776)", async () => {
@@ -630,7 +630,7 @@ test("a node id that derives an invalid git ref degrades to NO branch.create —
     edges: [{ from: "a..b", to: "a.lock" }, { from: "a.lock", to: "ok" }],
   };
   const p = await prepareOk(graph, {});
-  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("repository.branch.create"));
+  const branches = agentHeaders(p.bpmn).filter((h) => h.includes("io.nanobpm.agentTask.branch.create"));
   // Only the valid-id cell keeps a branch.create; the two invalid-ref ids emit none (their agents still
   // provision an isolated clone, they just cut their own branch inside it — the pre-#776 fallback).
   assertEquals(branches.length, 1, `only the valid id keeps a branch.create, got ${JSON.stringify(branches)}`);
@@ -638,16 +638,19 @@ test("a node id that derives an invalid git ref degrades to NO branch.create —
 });
 
 test("agentNodeRepoEnvelope emits branch.create off the base when known, off the default when not, and omits it when blank (#776)", () => {
-  const withBase = (agentNodeRepoEnvelope("acme/one", "main", "feat/n1") as any)["io.nanobpm.agentTask"].repository;
-  assertEquals(withBase.ref, "main", "known base → checked-out ref");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the
+  // envelope root, NOT from `repository.branch`.
+  const withBase = (agentNodeRepoEnvelope("acme/one", "main", "feat/n1") as any)["io.nanobpm.agentTask"];
+  assertEquals(withBase.repository.ref, "main", "known base → checked-out ref");
   assertEquals(withBase.branch.create, "feat/n1", "the harness cuts feat/<node.id> off the base");
-  const noBase = (agentNodeRepoEnvelope("acme/one", null, "feat/n2") as any)["io.nanobpm.agentTask"].repository;
-  assertEquals("ref" in noBase, false, "no base → clone the default branch");
+  assertEquals("branch" in withBase.repository, false, "branch must NOT be nested under repository");
+  const noBase = (agentNodeRepoEnvelope("acme/one", null, "feat/n2") as any)["io.nanobpm.agentTask"];
+  assertEquals("ref" in noBase.repository, false, "no base → clone the default branch");
   assertEquals(noBase.branch.create, "feat/n2", "branch.create is still emitted off the default tip");
   // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key (pre-#776 behaviour).
-  assertEquals((agentNodeRepoEnvelope("acme/one", "main", "  feat/n3  ") as any)["io.nanobpm.agentTask"].repository.branch.create, "feat/n3");
+  assertEquals((agentNodeRepoEnvelope("acme/one", "main", "  feat/n3  ") as any)["io.nanobpm.agentTask"].branch.create, "feat/n3");
   for (const blank of [null, undefined, "", "   "]) {
-    const r = (agentNodeRepoEnvelope("acme/one", "main", blank as any) as any)["io.nanobpm.agentTask"].repository;
+    const r = (agentNodeRepoEnvelope("acme/one", "main", blank as any) as any)["io.nanobpm.agentTask"];
     assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
   }
 });

package/app/feature.test.ts

@@ -196,11 +196,13 @@ test("startFeature: seeds the pre-PR repository envelope so the harness provisio
   // shared launch dir; with it, the harness clones a throwaway workspace. The implementation path is
   // PRE-PR, so it checks out the BASE branch (`ref`) and the harness cuts the deterministic
   // `feat/<task.id>` feature branch off it (`branch.create`).
-  const repo = (captured.variables as Record<string, any>)["io.nanobpm.agentTask"].repository;
+  const ns = (captured.variables as Record<string, any>)["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.url, "https://github.com/owner/repo.git");
   assertEquals(repo.ref, "epic/x");
-  assertEquals(repo.branch.create, "feat/issue-42");
-  assertEquals(repo.branch.create, `feat/${featureTaskId(PARSED.number)}`);
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the root.
+  assertEquals(ns.branch.create, "feat/issue-42");
+  assertEquals(ns.branch.create, `feat/${featureTaskId(PARSED.number)}`);
   // The blobless/single-branch monorepo shaping rides along, exactly like the PR-based envelope.
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");