@nanobpm/nano-workforce 0.200.7 → 0.200.9

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.200.9](https://github.com/nanobpm/nano-workforce/compare/v0.200.8...v0.200.9) (2026-10-05)
+
+### Bug Fixes
+
+* **implement-cell:** accurate escalation reason, adopt/retry a claimed completion without delivery ([#869](https://github.com/nanobpm/nano-workforce/issues/869)) ([9d7b3a8](https://github.com/nanobpm/nano-workforce/commit/9d7b3a83a4728ca831c519ffc3ad4eade00cc45e)), closes [#865](https://github.com/nanobpm/nano-workforce/issues/865) [#863](https://github.com/nanobpm/nano-workforce/issues/863) [#865](https://github.com/nanobpm/nano-workforce/issues/865) [#865](https://github.com/nanobpm/nano-workforce/issues/865)
+
+## [0.200.8](https://github.com/nanobpm/nano-workforce/compare/v0.200.7...v0.200.8) (2026-10-05)
+
+### Bug Fixes
+
+* **processes:** bound external agent tasks with an SLA timer boundary (implement-cell, merge-cell, retro) ([#864](https://github.com/nanobpm/nano-workforce/issues/864)) ([0ea4955](https://github.com/nanobpm/nano-workforce/commit/0ea4955cc2ec0fe61fbc81e8d7dcb9e842d29313)), closes [#849](https://github.com/nanobpm/nano-workforce/issues/849) [#849](https://github.com/nanobpm/nano-workforce/issues/849) [#849](https://github.com/nanobpm/nano-workforce/issues/849) [#867](https://github.com/nanobpm/nano-workforce/issues/867) [#868](https://github.com/nanobpm/nano-workforce/issues/868) [#849](https://github.com/nanobpm/nano-workforce/issues/849) [#867](https://github.com/nanobpm/nano-workforce/issues/867) [#868](https://github.com/nanobpm/nano-workforce/issues/868) [#868](https://github.com/nanobpm/nano-workforce/issues/868) [#227](https://github.com/nanobpm/nano-workforce/issues/227) [#868](https://github.com/nanobpm/nano-workforce/issues/868)
+
 ## [0.200.7](https://github.com/nanobpm/nano-workforce/compare/v0.200.6...v0.200.7) (2026-10-05)
 
 ### Documentation

package/SPEC.md

@@ -790,6 +790,47 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT30M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |
 | `NANO_PR_REVIEW_NUDGE_MINUTES` | 5 | cooldown between poller Copilot re-request nudges per PR (clamped 1–1440) |
+| `NANO_PR_AGENT_SLA_TIMEOUT` | PT2H | ISO-8601 liveness bound on an external **agent** service task (see §12.1); seeded as `agentSlaTimeout` at every process start that hosts one. Malformed → default |
+
+### 12.1 Agent-task liveness SLA (issue #849)
+
+An external **agent** service task (`<zeebe:agentDefinition agentType="external"/>`) is a durable
+wait on an external actor with **no human in the loop**: the worker renews the job's deadline for as
+long as the agent process is alive, so an unstaffed capability or a hung/looping agent that never
+fails its job would otherwise park the token forever (no incident, no escalation — the
+`classify-scope` 7h27m incident, nanobpm/nano-bpm#1308). The agent-task SLA closes that gap with a
+durable, in-process backstop — no external watchdog.
+
+- **Mechanism.** Every process start that hosts an external agent task seeds the validated
+  `agentSlaTimeout` process variable (`app/agentSla.ts` `AGENT_SLA_TIMEOUT`, env
+  `NANO_PR_AGENT_SLA_TIMEOUT`, default `PT2H`). Each *bounded* agent task carries an **interrupting
+  timer boundary** whose `<bpmn:timeDuration>=agentSlaTimeout` is evaluated at timer creation
+  (FEEL-expression duration). When the SLA elapses the boundary fires, cancels the stuck job, and
+  routes the token to the process's escalation path so a human is pulled in. It is deliberately much
+  shorter than the human-decision escalation SLA (`NANO_ESCALATION_SLA_TIMEOUT`, PT24H) so a stuck
+  agent surfaces quickly without interrupting a legitimately long task.
+- **Bounded today:** the implement-cell (`implement-task`), the merge-cell's trial-merge
+  (`trial-merge`), the merge-loop's `rebase` / `fix-ci`, and retro's `conformance` / `synthesize`.
+  The implement-cell is reached by **both** parents — a standalone `feature` run and a plan-fanout
+  wave slice — and each parent's callActivity maps `agentSlaTimeout` into the child explicitly.
+- **Pre-seeded, not yet bounded:** the convergence-loop (`review-round` / `adversarial-review` /
+  `classify-scope`) and plan-fanout (`plan` / `review-plan`) agent tasks sit on a back-edge loop
+  whose boundary the auto-layouter cannot yet route (#867), so their SLA boundaries are
+  intentionally deferred to #868. Plan-fanout's **inline** wave `trial-merge`
+  (`plan-fanout.bpmn:524-542`) — distinct from the standalone `merge-cell` process, which has no
+  callActivity caller — is likewise an external agent task with rerun back-edges and no
+  `agentSlaTimeout` boundary, and is deferred to #868 alongside them. They are seeded now as
+  preparation; the defect-class guard
+  (`app/agentic/vocab/agent-sla-boundary.test.ts`) covers exactly the bounded subset so a regression
+  on a *bounded* process is caught while the deferred ones stay out.
+- **Escalation routing.** The boundary never drops the token on the floor: implement-cell routes
+  `be_implement_sla` → `record-escalation-sla` (synthesises an SLA-specific question) → the shared
+  `human-escalation` cell; merge-cell routes `be_trial_agent_sla` → `record-trial-merge-sla` (its dedicated SLA recorder,
+  distinct from the normal-path `record-trial-merge`; persists a trial-merge audit row + answerable
+  question for the timed-out attempt) → `gw-trial` → `trial-merge-decision`;
+  retro routes each agent boundary → a `record-*-sla` task (persists a `plan_conformance` row at
+  `review_status='reviewing'` so the always-following `conformance-ack` settles it) →
+  `conformance-escalation`. Runtime coverage: `e2e/agent-sla-boundary.e2e.ts`.
 
 ## 13. Planning fan-out (`plan-fanout.bpmn`) — issue #14
 

package/app/agentSla.test.ts

@@ -5,8 +5,15 @@
 // `node --test`.
 
 import assert from "node:assert/strict";
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { test } from "node:test";
 import { agentSlaTimeout, DEFAULT_AGENT_SLA_TIMEOUT } from "./agentSla.ts";
+import { readEnv } from "./contracts.ts";
+
+const REPO_ROOT = dirname(dirname(fileURLToPath(import.meta.url)));
+const AGENT_SLA_SOURCE = readFileSync(join(REPO_ROOT, "app", "agentSla.ts"), "utf8");
 
 test("agentSlaTimeout: blank / absent / malformed → default", () => {
   assert.equal(agentSlaTimeout(undefined), DEFAULT_AGENT_SLA_TIMEOUT);
@@ -37,3 +44,44 @@ test("the default is itself a well-formed ISO-8601 duration (never an uninterpre
   assert.notEqual(DEFAULT_AGENT_SLA_TIMEOUT, sentinel);
   assert.equal(agentSlaTimeout(DEFAULT_AGENT_SLA_TIMEOUT, sentinel), DEFAULT_AGENT_SLA_TIMEOUT);
 });
+
+test("the canonical constant reads NANO_PR_AGENT_SLA_TIMEOUT through the ONE typed env schema", () => {
+  // Regression for review r3 (PR #864): the constant must go through `readEnv` (the typed
+  // ENV_CONTRACTS reader), not a raw `process.env` lookup. `readEnv` trims and collapses a
+  // blank/whitespace value to `undefined`, so this composition is only blank-safe when the constant
+  // is built from `readEnv(...)` — a raw `process.env.NANO_PR_AGENT_SLA_TIMEOUT` would pass the
+  // untrimmed blank straight through. (The synonym/typo rejection is the compile-time half, pinned
+  // by `npm run check:contracts`; this pins the runtime half.)
+  assert.equal(agentSlaTimeout(readEnv("NANO_PR_AGENT_SLA_TIMEOUT", {})), DEFAULT_AGENT_SLA_TIMEOUT);
+  assert.equal(
+    agentSlaTimeout(readEnv("NANO_PR_AGENT_SLA_TIMEOUT", { NANO_PR_AGENT_SLA_TIMEOUT: "   " })),
+    DEFAULT_AGENT_SLA_TIMEOUT,
+    "a blank env value collapses to undefined → default, never an uninterpretable timer",
+  );
+  assert.equal(
+    agentSlaTimeout(readEnv("NANO_PR_AGENT_SLA_TIMEOUT", { NANO_PR_AGENT_SLA_TIMEOUT: "  pt90m  " })),
+    "PT90M",
+    "a valid operator override is trimmed, validated, and honoured",
+  );
+});
+
+test("SOURCE GUARD: AGENT_SLA_TIMEOUT is built from readEnv, never a raw process.env read", () => {
+  // Regression for review r8 (PR #864, "Previously missed"): the composition test above recomputes
+  // `agentSlaTimeout(readEnv(...))` inline, so it stays green even if the exported constant regresses
+  // to `agentSlaTimeout(process.env.NANO_PR_AGENT_SLA_TIMEOUT)` — a raw read that bypasses the typed
+  // schema's trim/blank-collapse AND the compile-time synonym/typo check. `AGENT_SLA_TIMEOUT` is
+  // frozen once at import time, so a same-process test cannot re-drive it with a controlled env; the
+  // deterministic guard is source-level. Pin both halves: (1) no raw `process.env` read of the key
+  // anywhere in the module, and (2) the constant is composed from the typed `readEnv` reader.
+  assert.equal(
+    AGENT_SLA_SOURCE.includes("process.env.NANO_PR_AGENT_SLA_TIMEOUT"),
+    false,
+    "agentSla.ts must not read process.env.NANO_PR_AGENT_SLA_TIMEOUT directly — route it through " +
+      "readEnv (the ONE typed env schema) so a synonym/typo is a compile-time error",
+  );
+  assert.match(
+    AGENT_SLA_SOURCE,
+    /AGENT_SLA_TIMEOUT\s*=\s*agentSlaTimeout\(\s*readEnv\(\s*"NANO_PR_AGENT_SLA_TIMEOUT"/,
+    "AGENT_SLA_TIMEOUT must be composed from readEnv(\"NANO_PR_AGENT_SLA_TIMEOUT\")",
+  );
+});

package/app/agentSla.ts

@@ -1,24 +1,39 @@
-// Agent-task liveness SLA policy — kept as a pure module (no env, no I/O) so it is trivially
-// testable, mirroring app/escalationSla.ts. `app/service.ts` seeds the validated `agentSlaTimeout`
-// process variable when it starts the merge-loop; the merge-loop's AGENT service tasks (rebase,
-// fix-ci) carry an interrupting timer boundary whose `<bpmn:timeDuration>=agentSlaTimeout` evaluates
-// it at timer creation (FEEL-expression timer durations, engine-native).
+// Agent-task liveness SLA policy — kept as a pure module (the only I/O is the single canonical
+// env read for the constant, through the ONE typed env schema) so it is trivially testable,
+// mirroring app/escalationSla.ts. Every
+// process start that hosts an external agent task seeds the validated `agentSlaTimeout` process
+// variable (issue #849): `app/service.ts` for the convergence- and merge-loops, `app/feature.ts`
+// for a single-issue feature run, `app/plan.ts` for the epic plan-fanout, `app/retro.ts` for the
+// retrospective, and `app/deliveryRunner.ts` for a compiled delivery graph. Only a SUBSET of those
+// tasks is currently bounded — the implement-cell, the merge-cell's trial-merge, the merge-loop's
+// rebase / fix-ci, and retro's conformance / synthesize each carry an interrupting timer boundary
+// whose `<bpmn:timeDuration>=agentSlaTimeout` evaluates the seeded variable at timer creation
+// (FEEL-expression timer durations, engine-native). The convergence-loop and plan-fanout agent
+// tasks are only PRE-SEEDED here — their boundaries are intentionally deferred to #868 (a
+// bpmn-auto-layout back-edge routing limitation, #867). That deferred set is the convergence-loop's
+// review-round / adversarial-review / classify-scope and plan-fanout's plan / review-plan, PLUS
+// plan-fanout's inline wave `trial-merge` (`plan-fanout.bpmn:524-542`) — a separate external agent
+// task from the standalone `merge-cell` (which has no callActivity caller) that sits on a rerun
+// back-edge with no boundary yet. Seeding them now is preparation, not a claim of effective
+// coverage.
 //
 // This closes the agent-task liveness gap: unlike an escalation *user* task (whose SLA the
 // escalationSla policy already bounds), an AGENT service task has no human in the loop — if no
 // worker holds its capability, or the agent hangs/crashes without failing the job, the token parks
 // on the task forever (no incident, no escalation). The boundary timer makes that impossible: when
 // the SLA elapses the boundary fires, cancels the stuck job, and routes the token to the existing
-// merge escalation so a human is pulled in. It is a durable, in-process backstop — no external
+// escalation path so a human is pulled in. It is a durable, in-process backstop — no external
 // watchdog required.
 
+import { readEnv } from "./contracts.ts";
 import { isoDuration } from "./reviewWait.ts";
 
-/** Default agent-task SLA (ISO-8601 duration): how long a merge-loop agent service task (rebase /
- * fix-ci) may sit without completing before its interrupting timer boundary fires and the process
- * escalates for human attention. Deliberately much shorter than the human-decision escalation SLA
- * (PT24H): an agent that has not even started (unstaffed capability) or is stuck should surface to a
- * human quickly, while still being generous enough not to interrupt a legitimately long rebase. */
+/** Default agent-task SLA (ISO-8601 duration): how long an external agent service task may sit
+ * without completing before its interrupting timer boundary fires and the process escalates for
+ * human attention. Deliberately much shorter than the human-decision escalation SLA (PT24H): an
+ * agent that has not even started (unstaffed capability) or is stuck should surface to a human
+ * quickly, while still being generous enough not to interrupt a legitimately long task (e.g. an
+ * implementation slice). */
 export const DEFAULT_AGENT_SLA_TIMEOUT = "PT2H";
 
 /** Validate the operator-supplied agent SLA (env `NANO_PR_AGENT_SLA_TIMEOUT`, ISO-8601 duration),
@@ -31,3 +46,13 @@ export function agentSlaTimeout(
 ): string {
   return isoDuration(raw, def);
 }
+
+/** The one canonical, validated agent-task SLA every process start seeds as `agentSlaTimeout`
+ * (issue #849). Lives in this leaf module (not `app/service.ts`) so every seeder — service,
+ * feature, plan, retro, deliveryRunner — imports it without an import cycle. Seeding is universal,
+ * but only the bounded subset (implement-cell, merge-cell, merge-loop, retro) evaluates it via a
+ * boundary timer today; convergence-loop / plan-fanout are pre-seeded for #868. The env key is read
+ * through the ONE typed env schema (`readEnv` over the `NANO_PR_AGENT_SLA_TIMEOUT` registry entry,
+ * AGENTS.md issue #227) — never `process.env` directly — so a synonym/typo is a compile-time error,
+ * not a silent runtime fallback. */
+export const AGENT_SLA_TIMEOUT = agentSlaTimeout(readEnv("NANO_PR_AGENT_SLA_TIMEOUT"));

package/app/agentic/vocab/agent-sla-boundary.test.ts

@@ -0,0 +1,170 @@
+// DEFECT-CLASS GUARD for the agent-task liveness SLA (issue #849): every deployed
+// `<zeebe:agentDefinition agentType="external" />` service task must carry an interrupting
+// TIMER boundary event, so a hung or looping agent escalates within its SLA instead of parking
+// the process forever (the nanobpm/nano-bpm#1308 incident: `classify-scope` ran 7h27m unbounded
+// while the worker kept renewing the job's deadline).
+//
+// The guard parses the BOUNDED_PROCESSES subset of `resources/processes/*.bpmn` and fails if any
+// external agent task in them lacks an attached interrupting timer boundary — a newly-added agent
+// task on a *bounded* process can't ship unbounded. The convergence-loop and plan-fanout agent
+// tasks are deliberately excluded (their back-edge-loop boundaries are deferred to #868; see
+// BOUNDED_PROCESSES below), so the guard does not yet cover the whole deployed corpus. It
+// mirrors the sibling defect-class guard for the external AgentTask marker itself
+// (`agent-marker.test.ts`, issue #745): the scan helper lives in `app/agentic/vocab/job-types.ts`
+// and this test applies it to the bounded subset of the deployed corpus (see BOUNDED_PROCESSES).
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert, assertEquals } from "#test-assert";
+import { externalAgentTasksMissingSlaBoundary } from "./job-types.ts";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../../../resources/processes");
+
+test("externalAgentTasksMissingSlaBoundary flags an external agent task with no timer boundary", () => {
+  const xml = `
+    <bpmn:serviceTask id="agent">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:feature" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>`;
+  assertEquals(externalAgentTasksMissingSlaBoundary(xml), ["agent"]);
+});
+
+test("externalAgentTasksMissingSlaBoundary passes a bounded 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:feature" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_agent_sla" attachedToRef="agent">
+      <bpmn:outgoing>f_agent_sla</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_agent_sla">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=agentSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:sequenceFlow id="f_agent_sla" sourceRef="be_agent_sla" targetRef="somewhere" />`;
+  assertEquals(externalAgentTasksMissingSlaBoundary(xml), []);
+});
+
+test("externalAgentTasksMissingSlaBoundary rejects a non-timer boundary and a non-interrupting one", () => {
+  const xml = `
+    <bpmn:serviceTask id="msgBounded">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:a" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_msg" attachedToRef="msgBounded">
+      <bpmn:messageEventDefinition id="med_msg" messageRef="Message_x" />
+    </bpmn:boundaryEvent>
+    <bpmn:serviceTask id="nonInterrupting">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:b" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_ni" attachedToRef="nonInterrupting" cancelActivity="false">
+      <bpmn:timerEventDefinition id="ted_ni">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=agentSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:serviceTask id="nonInterruptingZero">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:c" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_ni0" attachedToRef="nonInterruptingZero" cancelActivity="0">
+      <bpmn:outgoing>f_ni0</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_ni0">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=agentSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:sequenceFlow id="f_ni0" sourceRef="be_ni0" targetRef="esc" />`;
+  // cancelActivity="0" is the OTHER XSD-boolean false form — it is just as non-interrupting as
+  // "false", so the guard must reject it too (else a hung agent runs on past the boundary).
+  assertEquals(externalAgentTasksMissingSlaBoundary(xml), ["msgBounded", "nonInterrupting", "nonInterruptingZero"]);
+});
+
+// The defect class a too-loose scanner would bless (review finding): an interrupting TIMER boundary
+// is necessary but NOT sufficient — it must also arm the canonical `=agentSlaTimeout` duration AND
+// route somewhere. Each case below is a boundary that LOOKS like an SLA bound but is not.
+test("externalAgentTasksMissingSlaBoundary rejects a timer with no timeDuration, a wrong expression, or no outgoing flow", () => {
+  const xml = `
+    <bpmn:serviceTask id="noDuration">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:a" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_no_duration" attachedToRef="noDuration">
+      <bpmn:outgoing>f_no_duration</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_no_duration" />
+    </bpmn:boundaryEvent>
+    <bpmn:sequenceFlow id="f_no_duration" sourceRef="be_no_duration" targetRef="esc" />
+    <bpmn:serviceTask id="wrongExpr">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:b" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_wrong_expr" attachedToRef="wrongExpr">
+      <bpmn:outgoing>f_wrong_expr</bpmn:outgoing>
+      <bpmn:timerEventDefinition id="ted_wrong_expr">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">PT2H</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>
+    <bpmn:sequenceFlow id="f_wrong_expr" sourceRef="be_wrong_expr" targetRef="esc" />
+    <bpmn:serviceTask id="disconnected">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="senior:c" />
+        <zeebe:agentDefinition agentType="external" />
+      </bpmn:extensionElements>
+    </bpmn:serviceTask>
+    <bpmn:boundaryEvent id="be_disconnected" attachedToRef="disconnected">
+      <bpmn:timerEventDefinition id="ted_disconnected">
+        <bpmn:timeDuration xsi:type="bpmn:tFormalExpression">=agentSlaTimeout</bpmn:timeDuration>
+      </bpmn:timerEventDefinition>
+    </bpmn:boundaryEvent>`;
+  // noDuration: timer without a timeDuration never arms the SLA. wrongExpr: a hard-coded PT2H does
+  // not track the seeded `agentSlaTimeout`. disconnected: a boundary with no outgoing flow cancels
+  // the agent without escalating. All three must be flagged.
+  assertEquals(externalAgentTasksMissingSlaBoundary(xml), ["noDuration", "wrongExpr", "disconnected"]);
+});
+
+// Processes whose external agent tasks are bounded by an SLA timer boundary (issue #849).
+// convergence-loop.bpmn and plan-fanout.bpmn are INTENTIONALLY absent: their agent tasks
+// (`review-round` / `adversarial-review` / `classify-scope`, and `plan`) sit on a back-edge-loop
+// target, and bpmn-auto-layout cannot route a bottom-exit timer boundary there (ROUTING_FAILED —
+// layouter bug #867; the bound-the-rest follow-up is #868). They are bounded once the layouter
+// fix lands; until then this list is the landed scope, and the corpus assertion below covers
+// exactly these processes so a regression on a *bounded* process is caught while the deferred
+// two stay out. merge-loop.bpmn's agent tasks (`fix-ci` / `rebase`) were bounded in an earlier
+// #849 commit, so it belongs here too — every already-bounded process stays regression-guarded.
+const BOUNDED_PROCESSES = ["implement-cell.bpmn", "merge-cell.bpmn", "merge-loop.bpmn", "retro.bpmn"] as const;
+
+test("DEFECT-CLASS GUARD: every external agent task in a bounded process carries an interrupting timer SLA boundary", () => {
+  let anyAgentTasks = false;
+  for (const file of BOUNDED_PROCESSES) {
+    const xml = readFileSync(join(PROCESSES_DIR, file), "utf8");
+    if (/<(?:\w+:)?agentDefinition\b[^>]*\bagentType="external"/.test(xml)) anyAgentTasks = true;
+    const missing = externalAgentTasksMissingSlaBoundary(xml);
+    assert(
+      missing.length === 0,
+      `${file}: external agent task(s) with no interrupting timer SLA boundary — ${missing.join(", ")} ` +
+        `(issue #849: an unbounded agent task parks the process forever; attach a timer boundary ` +
+        `whose <bpmn:timeDuration>=agentSlaTimeout routes to the process's escalation path)`,
+    );
+  }
+  // Sanity: the bounded models really do declare external agent tasks (guard is not vacuously green).
+  assert(anyAgentTasks, "the bounded models declare external agent tasks");
+});

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

@@ -214,3 +214,63 @@ export function agentTaskTypesOptedOutMissingExternalMarker(xml: string): string
   }
   return offending;
 }
+
+// A `<bpmn:boundaryEvent>` block with an interrupting TIMER definition attached to a given task.
+// The SLA bound is only real when the boundary carries a `<bpmn:timerEventDefinition>` (a message
+// or signal boundary would not bound a hung agent) and is interrupting (`cancelActivity` absent —
+// interrupting is the BPMN default — or explicitly `"true"`/`"1"`); a non-interrupting boundary would
+// leave the stuck job running. `cancelActivity` is an XSD boolean, so BOTH false lexical forms
+// (`"false"` and `"0"`) mark it non-interrupting — reject either, or the guard would bless a
+// `cancelActivity="0"` boundary that leaves the hung agent running.
+const BOUNDARY_EVENT = /<(?:\w+:)?boundaryEvent\b[^>]*>[\s\S]*?<\/(?:\w+:)?boundaryEvent>/g;
+const BOUNDARY_ATTACHED_TO = /\battachedToRef="([^"]*)"/;
+const BOUNDARY_ID = /<(?:\w+:)?boundaryEvent\b[^>]*\bid="([^"]*)"/;
+const TIMER_DEFINITION = /<(?:\w+:)?timerEventDefinition\b/;
+const NON_INTERRUPTING = /\bcancelActivity="(?:false|0)"/;
+const SERVICE_TASK_ID = /<(?:\w+:)?serviceTask\b[^>]*\bid="([^"]*)"/;
+// The boundary must actually arm the seeded SLA: a `<bpmn:timeDuration>` whose FEEL expression is
+// `=agentSlaTimeout`. A timer with no duration (or a hard-coded/other expression) does not bound the
+// agent by the canonical SLA, so it is not a real SLA boundary. Match the duration body loosely
+// (whitespace/`xsi:type` attribute agnostic) and require the `=agentSlaTimeout` reference.
+const SLA_DURATION = /<(?:\w+:)?timeDuration\b[^>]*>\s*=\s*agentSlaTimeout\s*<\/(?:\w+:)?timeDuration>/;
+// A sequence flow sourced from a node id (`sourceRef="<id>"`). The boundary must route SOMEWHERE —
+// a disconnected timer would cancel the agent without escalating, so a boundary with no outgoing
+// flow is not a valid SLA bound.
+const sequenceFlowFrom = (id: string): RegExp =>
+  new RegExp(`<(?:\\w+:)?sequenceFlow\\b[^>]*\\bsourceRef="${id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}"`);
+
+/**
+ * DEFECT-CLASS GUARD (issue #849): scan one BPMN document for the ids of EXTERNAL agent service
+ * tasks (`<zeebe:agentDefinition agentType="external" />`) that have NO interrupting timer
+ * boundary event attached. An external agent task is a durable wait on an external actor — the
+ * worker renews the job's deadline for as long as the agent process is alive, so a hung or
+ * looping agent parks the token forever with no incident and no escalation (the
+ * nanobpm/nano-bpm#1308 incident: `classify-scope` ran 7h27m unbounded). Every external agent
+ * task must carry an interrupting timer boundary (conventionally
+ * `<bpmn:timeDuration>=agentSlaTimeout</bpmn:timeDuration>`, seeded at instance start) that routes
+ * to the process's escalation path. Returns the offending task ids in first-occurrence order
+ * (empty when every external agent task is bounded).
+ */
+export function externalAgentTasksMissingSlaBoundary(xml: string): string[] {
+  const bounded = new Set<string>();
+  for (const [block] of xml.matchAll(BOUNDARY_EVENT)) {
+    // A real SLA bound is an INTERRUPTING TIMER boundary …
+    if (!TIMER_DEFINITION.test(block) || NON_INTERRUPTING.test(block)) continue;
+    // … that arms the canonical seeded SLA (`=agentSlaTimeout`) …
+    if (!SLA_DURATION.test(block)) continue;
+    const attached = block.match(BOUNDARY_ATTACHED_TO)?.[1];
+    if (!attached) continue;
+    // … and routes somewhere (a disconnected boundary cancels the agent without escalating).
+    const boundaryId = block.match(BOUNDARY_ID)?.[1];
+    if (!boundaryId || !sequenceFlowFrom(boundaryId).test(xml)) continue;
+    bounded.add(attached);
+  }
+  const missing: string[] = [];
+  for (const [block] of xml.matchAll(SERVICE_TASK)) {
+    if (!EXTERNAL_AGENT_MARKER.test(extensionElementsOf(block))) continue;
+    const id = block.match(SERVICE_TASK_ID)?.[1];
+    if (id === undefined || id.length === 0 || bounded.has(id)) continue;
+    missing.push(id);
+  }
+  return missing;
+}

package/app/conformance.test.ts

@@ -11,6 +11,7 @@ import {
   gatherConformance,
   hasDeliveredImplementation,
   hasDeliveredImplementationForPlan,
+  markConformanceSynthesisSla,
   recordConformance,
   renderConformanceBrief,
 } from "./conformance.ts";
@@ -312,3 +313,116 @@ test("acknowledgeConformance: a blank note settles the row without changing the
   assertEquals(stores["plan_conformance"][0].review_status, "reviewed");
   assertEquals(stores["plan_conformance"][0].summary, "auth cache unverified");
 });
+
+// Synthesis-SLA preserve path (PR #864 review): the synthesize-SLA arm runs AFTER record-conformance
+// already filed a verdict, so it must NOT overwrite the audit — only flip review_status + append the
+// synthesis-timeout context.
+test("markConformanceSynthesisSla: preserves a filed verdict, only marks reviewing + appends the SLA reason", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#issuecomment-1",
+    slicesMet: 4,
+    slicesReduced: 1,
+    slicesNotVerified: 0,
+    deviationsRaised: 1,
+    deviationsUnraised: 0,
+    hasDeviations: true,
+    summary: "6 items, 4 met",
+    report: "full conformance report",
+  });
+  await markConformanceSynthesisSla(data, PLAN, {
+    summary: "The retrospective-synthesis agent exceeded its time budget without completing.",
+    processKey: "p9",
+  });
+  assertEquals(stores["plan_conformance"].length, 1, "must not duplicate the plan_key row");
+  const row = stores["plan_conformance"][0];
+  // The filed verdict survives untouched.
+  assertEquals(row.status, "filed");
+  assertEquals(row.comment_url, "https://x/7#issuecomment-1");
+  assertEquals(row.slices_met, 4);
+  assertEquals(row.slices_reduced, 1);
+  assertEquals(row.has_deviations, 1);
+  assertEquals(row.report, "full conformance report");
+  // Only review_status flips and the SLA reason is APPENDED to the existing summary.
+  assertEquals(row.review_status, "reviewing");
+  assertEquals(row.process_key, "p9");
+  assertEquals(
+    row.summary,
+    "6 items, 4 met\n\nThe retrospective-synthesis agent exceeded its time budget without completing.",
+  );
+});
+
+test("markConformanceSynthesisSla: appends the SLA reason even when the prior summary is null", async () => {
+  const { data, stores } = memData();
+  stores["plan_conformance"] = [
+    { plan_key: PLAN, process_key: "p1", review_status: "reviewed", status: "skipped", summary: null },
+  ];
+  await markConformanceSynthesisSla(data, PLAN, { summary: "synthesis timed out", processKey: "p2" });
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.status, "skipped", "verdict preserved");
+  assertEquals(row.review_status, "reviewing");
+  assertEquals(row.summary, "synthesis timed out", "no prior text -> the reason stands alone");
+});
+
+test("markConformanceSynthesisSla: inserts a minimal reviewing placeholder when no verdict row exists", async () => {
+  const { data, stores } = memData();
+  await markConformanceSynthesisSla(data, PLAN, { summary: "synthesis timed out", processKey: "p3" });
+  assertEquals(stores["plan_conformance"].length, 1, "a placeholder row is created so the ack never wedges");
+  const row = stores["plan_conformance"][0];
+  assertEquals(row.status, "skipped");
+  assertEquals(row.review_status, "reviewing");
+  assertEquals(row.process_key, "p3");
+  assertEquals(row.summary, "synthesis timed out");
+});
+
+// At-least-once worker delivery can retry `record-synthesize-sla` after it already updated the row
+// but before the job completes. The preserve-append must be idempotent: a retry carrying the same
+// timeout text must NOT append a duplicate paragraph to the audit trail.
+test("markConformanceSynthesisSla: is idempotent on an at-least-once retry (no duplicate SLA paragraph)", async () => {
+  const { data, stores } = memData();
+  await recordConformance(data, PLAN, {
+    status: "filed",
+    commentUrl: "https://x/7#issuecomment-1",
+    slicesMet: 4,
+    slicesReduced: 1,
+    slicesNotVerified: 0,
+    deviationsRaised: 1,
+    deviationsUnraised: 0,
+    hasDeviations: true,
+    summary: "6 items, 4 met",
+    report: "full conformance report",
+  });
+  const sla = {
+    summary: "The retrospective-synthesis agent exceeded its time budget without completing.",
+    processKey: "p9",
+  };
+  await markConformanceSynthesisSla(data, PLAN, sla);
+  await markConformanceSynthesisSla(data, PLAN, sla); // retry
+  const row = stores["plan_conformance"][0];
+  assertEquals(
+    row.summary,
+    "6 items, 4 met\n\nThe retrospective-synthesis agent exceeded its time budget without completing.",
+    "a retry must not append the timeout paragraph twice",
+  );
+});
+
+// The placeholder-insert branch is likewise retry-safe: a retry finds the row it inserted and must
+// not append a second copy of the reason it already carries.
+test("markConformanceSynthesisSla: placeholder insert is idempotent on retry", async () => {
+  const { data, stores } = memData();
+  const sla = { summary: "synthesis timed out", processKey: "p3" };
+  await markConformanceSynthesisSla(data, PLAN, sla);
+  await markConformanceSynthesisSla(data, PLAN, sla); // retry
+  assertEquals(stores["plan_conformance"].length, 1);
+  assertEquals(stores["plan_conformance"][0].summary, "synthesis timed out", "no duplicate reason on retry");
+});
+
+test("markConformanceSynthesisSla: rejects an untrackable reviewing row with a null processKey", async () => {
+  const { data } = memData();
+  await assertRejects(
+    () => markConformanceSynthesisSla(data, PLAN, { summary: "synthesis timed out", processKey: null }),
+    Error,
+    "no process_key",
+  );
+});

package/app/conformance.ts

@@ -298,6 +298,78 @@ export async function recordConformance(
   }
 }
 
+/** Mark a conformance row whose *synthesis* (retro) agent blew its SLA — WITHOUT touching the filed
+ * verdict. The synthesize-SLA arm (`record-synthesize-sla` in retro.bpmn) runs AFTER
+ * `record-conformance` has already persisted a real audit (the token must pass through it to reach
+ * `synthesize`), so routing it through the upsert above would rewrite `status`/counts/`report` with
+ * blanks/zeros and clobber `summary` (incl. any operator acknowledgement) with the timeout text —
+ * destroying the verdict the escalation is supposed to surface (PR #864 review). Instead this only
+ * flips `review_status` to `reviewing` (so the shared `conformance-escalation` ack task is tracked)
+ * and APPENDS the synthesis-timeout context to the existing `summary`, leaving the audit intact.
+ *
+ * Edge: if no row exists yet (a bypassed/gather-only path where `record-conformance` never ran),
+ * insert a minimal placeholder so the ack's `acknowledgeConformance` — which throws on a missing row
+ * — still settles, and the escalation is never untrackable. */
+export async function markConformanceSynthesisSla(
+  data: DataLayer,
+  planKey: string,
+  input: { summary: string; processKey: string | null },
+): Promise<void> {
+  const ts = now();
+  const processKey = input.processKey ?? null;
+  // Same trackability invariant as recordConformance: a `reviewing` row with no process_key can
+  // never be surfaced by `pollUserTasks` nor cleared by `onTerminated` — it wedges forever.
+  if (processKey == null) {
+    throw new Error(
+      `markConformanceSynthesisSla: ${planKey} would persist review_status='reviewing' with no process_key — ` +
+        "refusing to record an untrackable synthesis-SLA escalation that no poller or onTerminated binding can clear",
+    );
+  }
+  const existing = await conformanceTbl(data).get(planKey);
+  if (!existing) {
+    // No conformance verdict was recorded (record-conformance never ran). Persist a minimal
+    // `reviewing` placeholder carrying only the synthesis-timeout reason so the ack settles it.
+    await conformanceTbl(data).insert({
+      plan_key: planKey,
+      created_at: ts,
+      status: "skipped",
+      comment_url: null,
+      slices_met: 0,
+      slices_reduced: 0,
+      slices_not_verified: 0,
+      deviations_raised: 0,
+      deviations_unraised: 0,
+      has_deviations: 0,
+      summary: input.summary,
+      report: null,
+      process_key: processKey,
+      review_status: CONFORMANCE_REVIEWING_STATUS,
+      updated_at: ts,
+    });
+    return;
+  }
+  // Preserve the filed verdict: only flip review_status and append the synthesis-timeout context to
+  // the existing summary (never replace it — it may carry the audit's own text + an operator ack).
+  // At-least-once worker semantics can retry `record-synthesize-sla` after it already updated the
+  // row but before the job completes; the append below is NOT idempotent, so a retry would duplicate
+  // the identical timeout paragraph. If the row is already parked at `reviewing` and its summary
+  // already ends with this exact reason, the update already landed — short-circuit so the retry is a
+  // no-op (mirrors acknowledgeConformance's idempotency guard). A genuinely later timeout only
+  // recurs after the operator ack flips status back to `reviewed`, so that path still appends afresh.
+  const existingSummary = typeof existing.summary === "string" ? existing.summary : "";
+  if (existing.review_status === CONFORMANCE_REVIEWING_STATUS && existingSummary.endsWith(input.summary)) {
+    return;
+  }
+  const prior = typeof existing.summary === "string" && existing.summary.trim() ? existing.summary : null;
+  const summary = prior ? `${prior}\n\n${input.summary}` : input.summary;
+  await conformanceTbl(data).update(planKey, {
+    process_key: processKey,
+    review_status: CONFORMANCE_REVIEWING_STATUS,
+    summary,
+    updated_at: ts,
+  });
+}
+
 /** Settle a conformance run's escalation once the operator acknowledges it: flip `review_status` to
  * `reviewed` so `pollUserTasks` stops scanning it (its inbox row is already gone once the ack task
  * closes) and stamp the disposition note into `summary` for the audit trail. Needed because the