@nanobpm/nano-workforce 0.201.3 → 0.201.5

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.5](https://github.com/nanobpm/nano-workforce/compare/v0.201.4...v0.201.5) (2026-10-11)
+
+### Bug Fixes
+
+* protect engine-owned process vars from agent-completion clobber (Closes [#887](https://github.com/nanobpm/nano-workforce/issues/887)) ([#888](https://github.com/nanobpm/nano-workforce/issues/888)) ([4245287](https://github.com/nanobpm/nano-workforce/commit/4245287e3d7553881f29bdda50cbd6d2b60b6268))
+
+## [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

package/SPEC.md

@@ -428,6 +428,79 @@ Notes:
   `answer`/`scopePending` (inputs the agent consumes) stay cleared on the
   review-round output.
 
+- **Engine-owned process variables are restored around every external-agent task
+  (issue #887).** The engine merges **every** variable an external agent returns
+  into process scope **unfiltered** — the `io.nanobpm.dataEnvelope.out` shape is
+  codegen/typing-only and applies **no** runtime filtering or coercion. An agent
+  that echoes an engine-owned variable with a colliding name or drifted type (a
+  `senior:pr-review` job that returned `round: "4"` — a string) therefore
+  overwrites the real process value, and the next FEEL guard that reads it
+  (`round >= maxRounds` at `gw-guard`) raises `comparison not defined for string
+  and number` and wedges the loop on an unrecoverable incident. The categorical
+  guard is a **snapshot/restore** on each external-agent task (`review-round`,
+  `adversarial-review`, `classify-scope`): before the agent runs, each
+  engine-owned variable is copied into a task-**local** `guard<Name>` input
+  (`<zeebe:input source="=round" target="guardRound"/>` …), and the task's output
+  mapping **restores** the process variable from that snapshot
+  (`<zeebe:output source="=guardRound" target="round"/>`). Because the snapshot
+  holds the pre-merge value, the restore overwrites whatever the completion
+  merged in, so the agent's real outputs (`status`/`summary`/`question`,
+  `adversarialFindings`, the scope verdict) flow through but it can never alter
+  the protected set. The protected set is **every engine-owned variable the loop
+  relies on that the agent does not own as an output**: the control counters and
+  budgets (`round`, `maxRounds`, `advPass`, `advMax`, `ackRetryRound`,
+  `ackRetryMax`, `huskRetries`, `reviewWaitTimeout`), the `prKey` correlation
+  key, **and** the PR identity inputs (`repo`, `prNumber`, `prUrl`) — the last
+  three because the unfiltered merge lets an input-echo replace the identity that
+  `progress-check`, `converge-gate`, and `finalize` go on to read (a wrong
+  `prNumber` would make `finalize` start the merge loop for the wrong PR) — **and**
+  the gate controls `humanApproval` and `convergeOnly`. These last two are
+  decision flags the loop acts on after the agent returns: `humanApproval = true`
+  routes a converged PR through the `gw-approval` human gate instead of
+  auto-merging, and `convergeOnly = true` ends a review-only run without ever
+  handing the PR to the merge loop. Left unguarded, a converged completion that
+  echoed `humanApproval: false` would **bypass** the approval gate, and one that
+  echoed `convergeOnly: false` would hand a review-only PR to the merge loop.
+  `convergeOnly` is a plain seeded constant, so the usual `=guardConvergeOnly`
+  restore applies. `humanApproval` is the one engine-owned flag that is **also
+  legitimately mutated mid-flight** — a gated caller that adopts a live loop
+  raises it `false → true` via `engine.setVariables` (`submitPr` in
+  `app/service.ts`); it is **monotonic** (only ever rises). A plain
+  `=guardHumanApproval` restore would clobber that concurrent host-set true, so
+  the restore is the monotonic join
+  `=(guardHumanApproval = true) or (humanApproval = true)`: it recovers the
+  snapshot's `true`, honours a concurrent adopter's `true`, and ignores an agent
+  echo of `false`. The direction is **fail-safe** — the only state it can force
+  is *more* human review, never a merge the loop would otherwise have gated. The
+  protected set also covers the two **progress bookkeeping** values the loop
+  reads back after the agent returns: `reviewStale` (the converge-gate's
+  stale-body signal — `f_guardMax` escalates only when `round >= maxRounds and
+  reviewStale != true`, so a forged `reviewStale: true` would suppress the
+  max-round escalation) and `roundEntryHead` (the within-round baseline
+  `pr.capture-head` captures and `pr.progress-check` consumes — a forged head
+  would falsify the no-progress decision). Both are plain process-owned reads, so
+  the usual `=guardReviewStale` / `=guardRoundEntryHead` restore pins them. The
+  protected set further covers the two **seeded cooperative-abandon** reads:
+  `abandonUrl` (the capability `pr.persist-round`/`pr.persist-escalation`/
+  `pr.finalize` record for a human — a forged echo would redirect the abandon
+  token) and `abandonBrief` (which feeds the NEXT agent task's `appendPrompt`
+  input `=(if abandonBrief = null then "" else abandonBrief)` — a non-string echo
+  would carry a wrong/non-string brief into that later prompt). Both are plain
+  process-owned reads, pinned by the usual `=guardAbandonUrl` / `=guardAbandonBrief`
+  restore. The reserved **`io.nanobpm.agentTask`** repository envelope is
+  *deliberately not* in this list: it is a flat dotted framework key with no
+  FEEL-path access, so snapshotting it would need backtick-escaped FEEL
+  (`` =`io.nanobpm.agentTask` ``) that has no precedent on this engine and would,
+  if evaluated as the default dotted path, resolve to `null` and **null the
+  fleet-critical envelope on restore** — a strictly worse failure than the
+  hypothetical clobber (an agent would have to emit a result-JSON key literally
+  named `io.nanobpm.agentTask`). A counter the task itself advances is incremented
+  **from the snapshot** (`adversarial-review` computes `advPass` as
+  `(if guardAdvPass = null then 0
+  else guardAdvPass) + 1`), never from the mergeable process variable. Any new
+  external-agent task added to this loop must apply the same guard to every
+  engine-owned variable in scope.
+
 
 ## 5. Agent job contract (`senior:pr-review`)
 
@@ -646,11 +719,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
@@ -803,6 +890,37 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   `pr.persist-escalation` worker as the review stage (status `escalated`), answered
   via the native `wait-merge-answer` `userTask` (the same `completeUserTask` door as
   the review escalation, #256); answering re-arms and retries.
+- **Engine-owned variable guard (issue #887)** — the merge-loop applies the same
+  snapshot/restore invariant as the convergence loop (§4) around its external-agent
+  tasks (`fix-ci`, `rebase`). Each guards the loop counters and budgets
+  (`ciFixRound`, `ciFixMax`, `rebaseRound`, `rebaseMax`, `mergeRetryRound`,
+  `mergeRetryMax`, `mergeStallRounds`, `mergeStallMax`), the `prKey` correlation
+  key, and the PR identity inputs (`repo`, `prNumber`, `prUrl`) — the last three
+  because `pr.merge` reads them directly for GitHub operations after the agent
+  re-arms the poller, so an input-echo that replaced them would merge the wrong
+  PR. It further guards the **lifecycle marker and timeout config** the loop
+  re-arms on every pass: `ciBlockedReconciled` (arm-merge seeds it `null`;
+  `ci-reconcile` sets it `true`; `gw-ci-blocked` runs the one-shot ground-truth
+  reconcile exactly once per episode while it is `!= true`) and the seeded timer
+  durations (`agentSlaTimeout`, `landedWaitTimeout`, `mergeableWaitTimeout`,
+  `mergeableRepollInterval`). Left unguarded, a `{status:"blocked", pushed:false,
+  ciBlockedReconciled:true}` completion would **skip** the mandatory first
+  reconcile and page a human immediately, and a clobbered timeout would silently
+  reshape a wait a later loop pass re-arms. The guard also pins the two values
+  `pr.merge` (attempt-merge) consumes directly after a successful fix/rebase
+  re-arms the poller: `round` (the converged round `ensurePr` records on the
+  merge audit row) and `abandonUrl` (the cooperative-abandon capability URL whose
+  token the merge worker extracts). A completion echoing either would corrupt the
+  recorded round or replace the abandon token, so `=guardRound` /
+  `=guardAbandonUrl` restores pin both. It likewise guards `abandonBrief`, which
+  feeds the fix-ci/rebase `appendPrompt` input (`=(if abandonBrief = null then ""
+  else abandonBrief)`) on the next re-arm — a non-string echo would carry a
+  non-string brief into that later prompt. (As in the convergence loop (§4), the
+  reserved dotted `io.nanobpm.agentTask` repository envelope is *not* guarded: it
+  has no FEEL-path access and a backtick-escaped restore, untested on this engine,
+  would risk nulling the envelope used for later agent provisioning.) The counter
+  the task advances is incremented from the snapshot (`ciFixRound`/`rebaseRound`
+  become `guard<Name> + 1`).
 - **Terminal** — `merged` (with `merged_at`), or `converged` when
   `NANO_PR_AUTO_MERGE=0` (review-only), or `abandoned` on cancel.