@nanobpm/nano-workforce 0.200.6 → 0.200.8

package/app/contracts.ts

@@ -296,9 +296,9 @@ export const ENV_CONTRACTS = {
   NANO_PR_AGENT_SLA_TIMEOUT: {
     category: "env",
     name: "NANO_PR_AGENT_SLA_TIMEOUT",
-    owner: "app/service.ts",
+    owner: "app/agentSla.ts",
     semantics:
-      "SLA timeout for an agent (service) task before its boundary timer fires and the PR escalates for human attention (ISO-8601 duration). A malformed value falls back to the default.",
+      "SLA timeout for an external agent (service) task before its interrupting boundary timer fires and the process escalates for human attention (ISO-8601 duration). Seeded as the `agentSlaTimeout` process variable at every process start that hosts an external agent task (issue #849): convergence-loop (service.ts `submitPr`), merge-loop (service.ts `startMerge`), feature (feature.ts), plan-fanout (plan.ts), retro (retro.ts), and delivery-graph runs (deliveryRunner.ts). A malformed value falls back to the default.",
     default: "PT2H",
   },
   NANO_CAPS_WAIT_TIMEOUT: {

package/app/deliveryRunner.ts

@@ -18,6 +18,7 @@ import { createHash, randomUUID } from "node:crypto";
 import type { EngineClient } from "@nanobpm/urban";
 import type { DeliveryFact, DeliveryGraph, DeliveryNode } from "../nano-generated/api-io.d.ts";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import { isPlausibleBranchName } from "./baseBranch.ts";
 import { AGENT_REPO_SPEC_HEADER, AGENT_TERMINAL_SUCCESS_STATUSES, assertNever, compileDeliveryGraph, DELIVERY_GRAPH_PROCESS_ID, redactFreeText } from "./deliveryGraphCompiler.ts";
 import { DEFAULT_EVERY_MS, msToIsoDuration, parseProbe, readinessPollEvery, readinessTimeout } from "./readiness.ts";
@@ -239,6 +240,10 @@ export async function runDeliveryGraph(
       // node ioMapping in deliveryGraphCompiler). Seeded once at the run root — the same value for
       // every node — and read down into each agent job via `=transcriptUrlBase`.
       [TRANSCRIPT_URL_BASE_VAR]: transcriptUrlBaseFor(),
+      // Agent-task liveness SLA (issue #849): the compiled graph's per-node `=nodeTimeout` boundary
+      // bounds a node's whole retry budget; this seeds the shared `agentSlaTimeout` knob so any
+      // agent cell modelled with the fleet-wide SLA boundary resolves it too.
+      agentSlaTimeout: AGENT_SLA_TIMEOUT,
     },
   });
   // The engine can yield a numeric key; `DeliveryRunHandle.processInstanceKey` is typed `string` and

package/app/feature.ts

@@ -16,6 +16,7 @@
 // SQL — matching app/plan.ts and app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { TRANSCRIPT_URL_BASE_VAR, transcriptUrlBaseFor } from "./agentic/transcript-url.ts";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import { coalesceTitle, fetchIssueTitle } from "./github.ts";
 import { derivedTrackingTable } from "./instanceTracking.ts";
 import { ESCALATION_SLA_TIMEOUT, normalizeBaseBranch, type ParsedIssue, renderBaseBranchBrief } from "./plan.ts";
@@ -531,6 +532,10 @@ export async function startFeature(
       // `feature-escalation` user task's interrupting timer boundary and assignment definition.
       escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
       escalationAssignee: null,
+      // Agent-task liveness SLA (issue #849): bounds the implement-cell's external agent task
+      // (`implement-task`) — its interrupting timer boundary evaluates `=agentSlaTimeout` at timer
+      // creation, so a hung or looping implementation agent escalates instead of parking forever.
+      agentSlaTimeout: AGENT_SLA_TIMEOUT,
       // Base branch (ADR 0003): the branch the agent branches off and opens its PR against. The
       // brief rides `appendPrompt` in the implement task, exactly like the epic implementer.
       baseBranch: base,

package/app/plan.ts

@@ -10,6 +10,7 @@
 // the process. Data access goes through the record gateway (`data.table`), never
 // hand-written SQL — matching app/service.ts.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import {
   InvalidBaseBranchError,
   isPlausibleBranchName,
@@ -1021,6 +1022,17 @@ export async function startPlan(
       // `operators` candidate group); an operator/agent can claim/reassign via the task inbox.
       escalationSlaTimeout: ESCALATION_SLA_TIMEOUT,
       escalationAssignee: null,
+      // Agent-task liveness SLA (issue #849): PRE-SEED the canonical bound for the fan-out's
+      // external agent tasks. Each slice's implementation agent (via the implement-cell
+      // callActivity's explicit `agentSlaTimeout` input mapping) is bounded today; the wave's own
+      // inline `trial-merge` agent (`plan-fanout.bpmn:524-542`) is NOT — it is a separate external
+      // task from the standalone `merge-cell` process (which has no callActivity caller), sits on a
+      // rerun back-edge, and its SLA boundary is deferred to #868 alongside the planner (`plan`) and
+      // plan reviewer (`review-plan`), whose back-edge loop the layouter cannot yet route (layouter
+      // bug #867). For those three this seed is preparation, not yet an armed bound. Each bounded
+      // task's interrupting timer boundary evaluates `=agentSlaTimeout` at timer creation, so a hung
+      // or looping agent escalates to a human instead of parking forever.
+      agentSlaTimeout: AGENT_SLA_TIMEOUT,
       // Capability-barrier bound (#289): the validated ISO-8601 duration read by the
       // `wait-caps-timeout` timer arm of the `wait-caps-resolved` event-based gateway. A task whose
       // declared cross-repo capabilities never resolve (most acutely an unresolvable capabilityRef the

package/app/retro.test.ts

@@ -4,6 +4,7 @@ import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { memBlackboardSource } from "../test/blackboardDb.ts";
 import { withTrackingViews } from "../test/trackingViews.ts";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import { appendEntry } from "./blackboard.ts";
 import { recordTaskDelta } from "./taskDelta.ts";
 import {
@@ -308,6 +309,10 @@ test("maybeStartRetro: starts the retro exactly once when the last PR lands with
   assertEquals(started.length, 1);
   assertEquals(started[0].processDefinitionId, "retro");
   assertEquals(started[0].variables.planKey, PLAN);
+  // The retro seed must carry the canonical agent-SLA bound through its PRODUCTION start path
+  // (not just the e2e, which supplies agentSlaTimeout manually) — else the two external agent
+  // tasks (`conformance` / `synthesize`) would run unbounded (Previously-missed advisory, PR #864).
+  assertEquals(started[0].variables.agentSlaTimeout, AGENT_SLA_TIMEOUT);
   assert(stores["plans"][0].retro_started_at, "retro_started_at must be stamped");
   assertEquals(stores["plan_retro_starts"].length, 1);
 

package/app/retro.ts

@@ -14,6 +14,7 @@
 // Data access goes through the record gateway (`data.table`), never hand-written SQL — matching
 // app/plan.ts, app/blackboard.ts, and app/taskDelta.ts.
 import type { DataLayer, EngineClient, Logger } from "@nanobpm/urban";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import { type BlackboardEntry, isUniqueViolation, readBlackboard } from "./blackboard.ts";
 import { hasDeliveredImplementationForPlan } from "./conformance.ts";
 import { TERMINAL_STATUSES } from "./delivery.ts";
@@ -355,6 +356,9 @@ export async function maybeStartRetro(
           planKey,
           repo: digest.repo,
           issueUrl: digest.issueUrl,
+          // Agent-task liveness SLA (issue #849): bounds the retro's two external agent tasks
+          // (`conformance`, `synthesize`) — a hung agent escalates to a human instead of parking.
+          agentSlaTimeout: AGENT_SLA_TIMEOUT,
         },
       }));
     } catch (err) {

package/app/service.ts

@@ -11,7 +11,7 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { ABANDONED_STATUS, abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { matchAdjudication, prAdjudications, resetAdjudications } from "./adjudications.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
-import { agentSlaTimeout } from "./agentSla.ts";
+import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import {
   CAPS_RESOLVED_MESSAGE,
   type CapabilityNeed,
@@ -214,13 +214,25 @@ export const MAX_ADVERSARIAL_PASSES = clampCiFixBudget(
  * (allows 0 = escalate immediately, ceiling-capped). */
 export const MAX_MERGE_STALL_ROUNDS = clampCiFixBudget(process.env.NANO_PR_MAX_MERGE_STALL_ROUNDS, 3);
 
-/** How long a merge-loop AGENT service task (rebase / fix-ci) may sit without completing before its
- * interrupting timer boundary fires and the PR escalates for human attention. Seeded as the
- * `agentSlaTimeout` process variable at merge start and evaluated by those tasks' boundary timers.
- * Unlike a human-decision escalation (PT24H), an agent task has no human in the loop — if its
- * capability is unstaffed or the agent hangs/crashes without failing the job, the token would
- * otherwise park forever. Override with `NANO_PR_AGENT_SLA_TIMEOUT` (ISO-8601 duration). */
-export const AGENT_SLA_TIMEOUT = agentSlaTimeout(process.env.NANO_PR_AGENT_SLA_TIMEOUT);
+/** How long an external AGENT service task may sit without completing before its interrupting
+ * timer boundary fires and the process escalates for human attention. Seeded as the
+ * `agentSlaTimeout` process variable at every process start that hosts an external agent task
+ * (issue #849), and evaluated by the BOUNDED subset's boundary timers
+ * (`<bpmn:timeDuration>=agentSlaTimeout`, FEEL at timer creation): the implement-cell, the
+ * merge-cell's trial-merge, the merge-loop's rebase / fix-ci, and retro's conformance / synthesize.
+ * The convergence-loop (review-round / adversarial-review / classify-scope) and plan-fanout (plan /
+ * review-plan) tasks are only PRE-SEEDED here — their boundaries are intentionally deferred to #868
+ * (a bpmn-auto-layout back-edge routing limitation, #867). Plan-fanout's inline wave `trial-merge`
+ * (`plan-fanout.bpmn:524-542`) is likewise deferred: it is a separate external agent task from the
+ * standalone `merge-cell` (which has no callActivity caller) on a rerun back-edge with no boundary
+ * yet. For all of these this seed is preparation, not yet an armed bound. Unlike a human-decision
+ * escalation (PT24H), an agent task has no human in
+ * the loop — if its capability is unstaffed or the agent hangs/crashes without failing the job, the
+ * token would otherwise park forever. Override with `NANO_PR_AGENT_SLA_TIMEOUT` (ISO-8601 duration).
+ * The canonical validated constant lives in the leaf module `app/agentSla.ts` (re-exported here) so
+ * `app/feature.ts`, `app/plan.ts`, `app/retro.ts`, and `app/deliveryRunner.ts` seed it without an
+ * import cycle. */
+export { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 
 /** How long the convergence loop waits for a fresh review before escalating to a human. Seeded as
  * the `reviewWaitTimeout` process variable at submit and evaluated by the process's
@@ -761,6 +773,13 @@ async function submitPrCritical(
       round: 1,
       maxRounds: clampRounds(maxRounds, MAX_ROUNDS),
       reviewWaitTimeout: REVIEW_WAIT_TIMEOUT,
+      // Agent-task liveness SLA (issue #849): PRE-SEED the bound for the loop's external agent
+      // tasks (review-round / adversarial-review / classify-scope). Those tasks sit on a
+      // back-edge loop whose boundary the layouter cannot yet route, so their SLA boundaries are
+      // intentionally deferred to #868 (layouter bug #867) — this seed is preparation for that
+      // follow-up, not yet an armed bound on this loop. (The merge-loop's rebase / fix-ci, seeded
+      // from the same constant, ARE bounded today.)
+      agentSlaTimeout: AGENT_SLA_TIMEOUT,
       // Bounded agent auto-ack (issue #796): the convergence loop re-dispatches the review-round
       // agent up to `ackRetryMax` times to ack suppressed advisories when the converge-gate blocks
       // solely on unacked ones, before escalating to a human. `ackRetryRound` counts those passes.

package/docs/agent-guide.md

@@ -116,6 +116,15 @@ blank/absent base is rejected with a 400. Starting a
 plan is idempotent on the plan key; an already-running plan short-circuits. The
 response (202) echoes the `planKey` and engine `processKey`.
 
+**Single issue, one PR (feature run, `startFeature`)** — no planning or fan-out. Same body and
+base-branch admission, plus `converge` (enrol the PR in §1) and `autoMerge`:
+
+```bash
+curl -sS -X POST __BASE__/actions/start/feature \
+  -H 'content-type: application/json' \
+  -d '{ "issue": "owner/repo#123", "baseBranch": "main", "confirmDefaultBase": true, "converge": true, "autoMerge": true }'
+```
+
 ### Base-branch admission (ADR 0003)
 
 `startPlanFanout` admits the base through one fail-fast gate before any task fans out.