@nanobpm/nano-workforce 0.201.1 → 0.201.3

package/app/agentSlaEscalation.ts

@@ -0,0 +1,169 @@
+// Agent-task SLA-escalation reason builder (issue #879) — the single canonical, pure text builder for
+// the human-facing escalation raised when an agent service task's interrupting SLA timer boundary
+// fires. It distinguishes the two outcomes the old wording conflated:
+//
+//   • NEVER OBSERVED ACTIVATED — no worker was ever observed to pick the job up (almost certainly
+//     queue starvation / no capacity for the job type). The job sat CREATED for ~the whole SLA budget
+//     and was cancelled by the boundary. Telling the human it is "hung or looping" and to "check its
+//     progress" is a false diagnosis — the likely fix is CAPACITY, not intervention. The wording is
+//     hedged (a worker could lease it in the final moment before the boundary fires, between activation
+//     polls, unrecorded), so it reports the likely cause without over-claiming certainty.
+//   • STARTED BUT EXCEEDED — a worker leased the job (an agent ran) but did not complete within the
+//     budget — it may genuinely be hung or looping, and intervening / checking its progress is apt.
+//
+// The distinction is read from the durable activation ledger (`app/agentActivationLedger.ts`), which
+// the poller populates while the job is live. Every escalation names the JOB TYPE and HOW LONG it
+// waited, per the issue's acceptance criteria.
+//
+// Derivation over duplication: this is the ONE builder every agent-SLA recorder (implement-cell,
+// merge-cell, retro) routes through, so the never-started/hung wording can never drift between sites.
+// The pure `buildAgentSlaEscalationReason` is exhaustively testable; `agentSlaEscalationQuestion` is
+// the thin async wrapper that reads the ledger and calls it.
+import type { DataLayer } from "@nanobpm/urban";
+import { type AgentJobActivation, getAgentJobActivation } from "./agentActivationLedger.ts";
+import { isoDurationToMs } from "./reviewWait.ts";
+
+/** The activation facts the builder needs (a slice of the ledger row), or `null` when the poller never
+ * observed the job (activation unknown). */
+export interface AgentSlaActivation {
+  /** ISO ts a leasing worker was first observed; `null`/absent ⇒ never activated. */
+  activatedAt?: string | null;
+  /** ISO ts the job was first observed queued. */
+  firstSeenAt?: string | null;
+  /** The leasing worker's name, when known. */
+  worker?: string | null;
+}
+
+export interface AgentSlaEscalationInput {
+  /** The agent job type that timed out, e.g. `senior:feature`. Named in the reason. */
+  jobType: string;
+  /** The SLA budget (ISO-8601 duration) the boundary armed, e.g. `PT2H`. */
+  sla: string;
+  /** The activation record for this job, or `null` when the poller never observed it. */
+  activation: AgentSlaActivation | null;
+  /** The escalation moment (ISO ts) — the elapsed wait is measured against it. */
+  now: string;
+  /** How the human resumes after answering — appended verbatim so each caller keeps its own
+   * routing hint (e.g. "answer to resume … or abandon it"). */
+  recovery: string;
+}
+
+/** Humanise a millisecond span to a compact, human-facing string (e.g. `2h 5m`, `45m`, `30s`). A
+ * non-positive/NaN span renders `less than a minute`. */
+export function humanizeMs(ms: number): string {
+  if (!Number.isFinite(ms) || ms <= 0) return "less than a minute";
+  const totalMinutes = Math.floor(ms / 60_000);
+  if (totalMinutes < 1) return `${Math.max(1, Math.round(ms / 1000))}s`;
+  const days = Math.floor(totalMinutes / 1440);
+  const hours = Math.floor((totalMinutes % 1440) / 60);
+  const minutes = totalMinutes % 60;
+  const parts: string[] = [];
+  if (days > 0) parts.push(`${days}d`);
+  if (hours > 0) parts.push(`${hours}h`);
+  if (minutes > 0) parts.push(`${minutes}m`);
+  return parts.join(" ") || "less than a minute";
+}
+
+/** Humanise an ISO-8601 duration (the SLA budget) to the same compact form, via the canonical parser. */
+export function humanizeIsoDuration(iso: string): string {
+  return humanizeMs(isoDurationToMs(iso, iso));
+}
+
+const elapsedMs = (fromIso: string | null | undefined, toIso: string): number | null => {
+  if (!fromIso) return null;
+  const from = Date.parse(fromIso);
+  const to = Date.parse(toIso);
+  if (!Number.isFinite(from) || !Number.isFinite(to)) return null;
+  return to - from;
+};
+
+/** Build the accurate, self-contained agent-SLA escalation reason. Pure — distinguishes never-started
+ * (queue starvation) from started-but-hung, names the job type and how long it waited, then appends
+ * the caller's recovery hint. */
+export function buildAgentSlaEscalationReason(input: AgentSlaEscalationInput): string {
+  const { jobType, sla, activation, now, recovery } = input;
+  const slaHuman = humanizeIsoDuration(sla);
+  const activatedAt = activation?.activatedAt ?? null;
+
+  if (activatedAt) {
+    // STARTED BUT EXCEEDED: a worker leased the job, so it may genuinely be hung or looping.
+    const queueMs = elapsedMs(activation?.firstSeenAt, activatedAt);
+    const queuedClause = queueMs !== null && queueMs > 0
+      ? ` (after waiting ~${humanizeMs(queueMs)} in the queue)`
+      : "";
+    const ranMs = elapsedMs(activatedAt, now);
+    const ranClause = ranMs !== null && ranMs > 0 ? ` and then ran for ~${humanizeMs(ranMs)}` : "";
+    const workerClause = activation?.worker ? ` (worker "${activation.worker}")` : "";
+    return (
+      `The ${jobType} agent started${queuedClause}${workerClause}${ranClause} but exceeded its time budget ` +
+      `(SLA ${sla} ≈ ${slaHuman}) without completing — it may be hung or looping. ${recovery}`
+    );
+  }
+
+  // Measure the wait: from first-seen to now when the poller observed the queued job, else the full
+  // SLA budget (the boundary fired exactly one budget after the task was entered).
+  const waitedMs = elapsedMs(activation?.firstSeenAt, now);
+  const waited = waitedMs !== null && waitedMs > 0 ? humanizeMs(waitedMs) : slaHuman;
+
+  if (activation === null) {
+    // ACTIVATION UNKNOWN: the poller never observed the job (e.g. the activation poll was unavailable).
+    // Report the ambiguity honestly rather than guessing "hung" or "never started".
+    return (
+      `The ${jobType} agent did not complete within its time budget (SLA ${sla} ≈ ${slaHuman}), and no ` +
+      `worker-activation was ever recorded for it, so we cannot confirm whether a worker ever picked it ` +
+      `up — it may have been starved of capacity for ${jobType}, or started and hung. ${recovery}`
+    );
+  }
+
+  // NEVER OBSERVED ACTIVATED: seen queued, never seen leased. This is the best-effort observation of
+  // queue starvation — hedged, because a worker could in principle lease the job in the final moment
+  // before the boundary cancels it, between activation polls, and that would not be recorded. We report
+  // the likely diagnosis (and its capacity fix) without over-claiming certainty.
+  return (
+    `No worker was ever observed to pick up the ${jobType} agent's job for its entire SLA budget ` +
+    `(SLA ${sla} ≈ ${slaHuman}): it was seen queued for ~${waited}, then the SLA boundary cancelled it. ` +
+    `This is almost certainly queue starvation (no capacity for ${jobType}) rather than a hung or ` +
+    `looping agent, so the likely fix is to add capacity for ${jobType} (enrol a worker that serves it, ` +
+    `or reduce concurrent demand) rather than to check a non-existent agent's progress. (If a worker ` +
+    `leased it in the final moment before the boundary fired, between activation polls, that would not ` +
+    `have been recorded here.) ${recovery}`
+  );
+}
+
+/** Read the activation ledger for this job and build the escalation reason — the thin async wrapper the
+ * recorder workers call. `processInstanceKey` is the instance the agent job AND its SLA recorder share,
+ * so the lookup is by (instance, jobType). An absent ledger row ⇒ activation unknown. */
+export async function agentSlaEscalationQuestion(
+  data: DataLayer,
+  input: {
+    processInstanceKey: string;
+    jobType: string;
+    sla: string;
+    recovery: string;
+    now?: string;
+  },
+): Promise<string> {
+  const now = input.now ?? new Date().toISOString();
+  let activation: AgentSlaActivation | null = null;
+  if (input.processInstanceKey && input.processInstanceKey.length > 0) {
+    const row: AgentJobActivation | undefined = await getAgentJobActivation(
+      data,
+      input.processInstanceKey,
+      input.jobType,
+    );
+    if (row) {
+      activation = {
+        activatedAt: row.activated_at,
+        firstSeenAt: row.first_seen_at,
+        worker: row.worker,
+      };
+    }
+  }
+  return buildAgentSlaEscalationReason({
+    jobType: input.jobType,
+    sla: input.sla,
+    activation,
+    now,
+    recovery: input.recovery,
+  });
+}

package/app/agentSlaMarkerGuard.test.ts

@@ -0,0 +1,172 @@
+// DEFECT-CLASS GUARD (PR #881 review, thread r4214170285): `agentSlaJobType` is the marker that
+// selects the agent-SLA escalation builder in the four recorder workers (`pr.persist-escalation`,
+// `pr.record-feature-escalation`, `pr.record-trial-merge`, `pr.conformance-record`). It is set
+// ONLY by the BPMN SLA arm (an interrupting timer boundary's route), never by the agent — but the
+// c8ctl harness HOISTS the agent's result-JSON keys into the SAME process-variable namespace the
+// recorders read it from. So a NORMAL (non-SLA) agent result that happens to carry an
+// `agentSlaJobType` key would wrongly select the SLA builder and replace a genuine question or
+// audit summary with a timeout diagnosis.
+//
+// This is the exact defect class PR #864 (review r4181010853) already closed for the boolean
+// SLA-control flags `agentSlaElapsed` / `preserveConformance` — by pinning each to a LITERAL on
+// every recorder task's ioMapping so hoisted agent output can never select the internal control
+// path. `agentSlaJobType` was left unpinned. This guard closes that gap: every NORMAL-path recorder
+// (one that does NOT set the marker to a real job-type literal) must pin `agentSlaJobType` to the
+// `=null` literal, so a hoisted agent-supplied value is overridden to null on the normal path.
+// SLA-arm recorders legitimately pin it to a job-type literal (e.g. `="senior:feature"`); those
+// are the trusted source and are NOT required to pin null.
+//
+// The guard scans the deployed corpus and fails if any recorder task reads `agentSlaJobType`
+// without pinning it to a literal (null on the normal path, a job-type on an SLA arm) — so a
+// newly-added or edited recorder can never re-open the hole.
+//
+// EXCEPTION — merge-loop's SHARED SLA-sink recorders (PR #881 review, adversarial round 3): unlike
+// the other processes, merge-loop has NO dedicated `*-sla` recorder task. Its fix-ci / rebase
+// interrupting-SLA arms (`end_ci_sla` → "senior:fix-ci", `end_reb_sla` → "senior:rebase") and its
+// NON-SLA escalation arms CONVERGE on the SAME two recorders (`merge-esc-attempt`,
+// `merge-esc-conflict`). So those two recorders MUST READ `agentSlaJobType` from process scope
+// (set by the trusted SLA end event) — a blanket `=null` input pin there would clobber the
+// legitimate SLA job type and silently regress the issue-#879 never-started-vs-hung diagnosis. The
+// hoisted-agent-output hole is closed on these shared sinks a DIFFERENT way: every path that can
+// carry a hoisted (spoofable) value CLEARS `agentSlaJobType` to null via an OUTPUT mapping before
+// it reaches the recorder — at the loop head (`arm-merge`, scrubbing any stale/cross-iteration
+// value), on the two non-SLA escalate end events that bypass the loop head (`end_ci_esc`,
+// `end_reb_blocked`), and on the CI reconcile re-check exit (`end_ci_recheck`, which re-enters the
+// merge wait via `gw-merge-entry` without passing through `arm-merge`). Only the trusted SLA arms
+// leave it set. This guard therefore (a) requires the shared sinks to NOT pin, and (b) requires
+// those clears + the SLA-arm literals to exist.
+import { readFileSync } from "node:fs";
+import { test } from "node:test";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { assert } from "#test-assert";
+
+const PROCESSES_DIR = join(dirname(fileURLToPath(import.meta.url)), "../resources/processes");
+const PROCESS_FILES = [
+  "convergence-loop.bpmn",
+  "merge-loop.bpmn",
+  "implement-cell.bpmn",
+  "merge-cell.bpmn",
+  "plan-fanout.bpmn",
+  "retro.bpmn",
+];
+
+// The recorder job types that read `agentSlaJobType` to select the SLA builder.
+const RECORDER_TYPES = [
+  "pr.persist-escalation",
+  "pr.record-feature-escalation",
+  "pr.record-trial-merge",
+  "pr.conformance-record",
+];
+
+const SERVICE_TASK = /<bpmn:serviceTask\b[\s\S]*?<\/bpmn:serviceTask>/g;
+// A trusted pin is a LITERAL input: `=null` (normal path) or `="..."`/`=&#34;...&#34;` (SLA arm's
+// job-type). A process-variable REFERENCE (e.g. `=agentSlaJobType`) is NOT a pin — it would read
+// hoisted agent output, which is exactly the hole being closed.
+const LITERAL_PIN =
+  /<zeebe:input\s+source="=(?:null|&#[0-9]+;[^"]*&#[0-9]+;|"[^"]*")"\s+target="agentSlaJobType"\s*\/>/;
+
+// Any INPUT mapping on `agentSlaJobType` (literal OR reference) — used to assert the shared SLA-sink
+// recorders carry NONE (they must read the SLA arm's value from process scope, not shadow it).
+const ANY_INPUT_PIN = /<zeebe:input\s+source="=[^"]*"\s+target="agentSlaJobType"\s*\/>/;
+// A `=null` OUTPUT clear (writes process scope) — the fail-closed scrub on merge-loop's spoofable
+// non-SLA paths.
+const NULL_OUTPUT_CLEAR = /<zeebe:output\s+source="=null"\s+target="agentSlaJobType"\s*\/>/;
+
+// merge-loop's two SHARED SLA-sink recorders: both SLA and non-SLA arms converge on them, so they
+// MUST read `agentSlaJobType` from scope and MUST NOT pin it (see header).
+const SHARED_SLA_SINKS = new Set(["merge-esc-attempt", "merge-esc-conflict"]);
+
+/** Extract the XML block for a BPMN element by id (any element tag). */
+function elementBlock(xml: string, id: string): string | undefined {
+  const re = new RegExp(`<bpmn:(\\w+)\\b[^>]*\\bid="${id}"[\\s\\S]*?</bpmn:\\1>`);
+  return xml.match(re)?.[0];
+}
+
+test("DEFECT-CLASS GUARD: every SLA-builder recorder pins agentSlaJobType to a literal (agent output cannot select the SLA path)", () => {
+  let recorderCount = 0;
+  for (const file of PROCESS_FILES) {
+    const xml = readFileSync(join(PROCESSES_DIR, file), "utf8");
+    for (const [block] of xml.matchAll(SERVICE_TASK)) {
+      if (!RECORDER_TYPES.some((t) => block.includes(`type="${t}"`))) continue;
+      const id = block.match(/<bpmn:serviceTask\b[^>]*\bid="([^"]*)"/)?.[1] ?? "(unknown)";
+      // The shared SLA-sink recorders read the marker from scope — they must NOT pin it, else a
+      // `=null` pin would clobber the trusted SLA job type (issue #879 regression). They are
+      // protected by the OUTPUT clears asserted below, not by an input pin.
+      if (SHARED_SLA_SINKS.has(id)) {
+        assert(
+          !ANY_INPUT_PIN.test(block),
+          `${file}: shared SLA-sink recorder "${id}" must NOT pin agentSlaJobType — both the SLA ` +
+            `and non-SLA arms converge on it, so it must READ the SLA end event's value from ` +
+            `process scope. A =null pin here clobbers the trusted SLA job type and regresses the ` +
+            `never-started-vs-hung diagnosis (PR #881 adversarial review). Remove the pin; the ` +
+            `hole is closed by the =null OUTPUT clears on arm-merge / end_ci_esc / end_reb_blocked.`,
+        );
+        continue;
+      }
+      recorderCount++;
+      assert(
+        LITERAL_PIN.test(block),
+        `${file}: recorder task "${id}" reads agentSlaJobType but does not pin it to a literal ` +
+          `(=null on the normal path, a job-type literal on an SLA arm). A hoisted agent result ` +
+          `carrying agentSlaJobType would wrongly select the SLA escalation builder (PR #881 review ` +
+          `r4214170285). Pin it: <zeebe:input source="=null" target="agentSlaJobType" /> on the ` +
+          `normal path.`,
+      );
+    }
+  }
+  // Sanity: the guard is not vacuously green — the corpus really has these recorders (the
+  // normal-path recorders + the SLA arms across the six processes).
+  assert(recorderCount >= 11, `expected >=11 SLA-builder recorder tasks, found ${recorderCount}`);
+});
+
+test("DEFECT-CLASS GUARD: merge-loop's shared SLA sinks are fed a trusted agentSlaJobType (SLA arms set it; spoofable non-SLA paths clear it)", () => {
+  const xml = readFileSync(join(PROCESSES_DIR, "merge-loop.bpmn"), "utf8");
+
+  // The two shared sinks really exist and read from scope (no input pin) — guards against the file
+  // being renamed/removed and silently passing.
+  for (const id of SHARED_SLA_SINKS) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected shared SLA-sink recorder "${id}" to exist`);
+    assert(
+      !ANY_INPUT_PIN.test(block),
+      `merge-loop.bpmn: "${id}" must read agentSlaJobType from scope, not pin it`,
+    );
+  }
+
+  // The trusted SLA arms SET the job-type literal (this is the value the shared sinks must receive).
+  for (const [id, literal] of [
+    ["end_ci_sla", "senior:fix-ci"],
+    ["end_reb_sla", "senior:rebase"],
+  ] as const) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected SLA arm "${id}" to exist`);
+    const re = new RegExp(
+      `<zeebe:output\\s+source="=&#34;${literal.replace(/[-/\\^$*+?.()|[\]{}]/g, "\\$&")}&#34;"\\s+target="agentSlaJobType"\\s*/>`,
+    );
+    assert(
+      re.test(block),
+      `merge-loop.bpmn: SLA arm "${id}" must set agentSlaJobType to the "${literal}" literal via ` +
+        `an output mapping (the trusted source the shared sink reads).`,
+    );
+  }
+
+  // Every spoofable path that can carry a hoisted agentSlaJobType into a shared sink CLEARS it to
+  // null via output BEFORE the recorder: the loop head (stale/cross-iteration), the two non-SLA
+  // escalate end events that bypass the loop head (same-iteration agent spoof), and the CI
+  // reconcile re-check exit (`end_ci_recheck`), which re-enters the merge wait via `gw-merge-entry`
+  // — bypassing `arm-merge` — so a fix-ci result with status:"blocked"/pushed:false carrying a
+  // hoisted marker would otherwise reach `merge-esc-conflict` on a later draft/budget-exhausted
+  // merge with no SLA timer having fired (PR #881 review, "Previously missed" r5451284362).
+  for (const id of ["arm-merge", "end_ci_esc", "end_reb_blocked", "end_ci_recheck"]) {
+    const block = elementBlock(xml, id);
+    assert(block, `merge-loop.bpmn: expected "${id}" to exist`);
+    assert(
+      NULL_OUTPUT_CLEAR.test(block),
+      `merge-loop.bpmn: "${id}" must clear agentSlaJobType to null via ` +
+        `<zeebe:output source="=null" target="agentSlaJobType" /> so a hoisted (spoofable) agent ` +
+        `value can never reach the shared SLA-sink recorder and fabricate a never-started/hung ` +
+        `SLA diagnosis (PR #881 adversarial review).`,
+    );
+  }
+});

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",

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");

package/app/mergeLoopBehaviour.test.ts

@@ -28,7 +28,7 @@
 // Plus the terminate semantics the refactor had to preserve: `MergeAbandoned`
 // terminates the whole instance (it stays at the root, not inside a sub-process).
 import { after, test } from "node:test";
-import { assert, assertStringIncludes } from "#test-assert";
+import { assert, assertEquals, assertStringIncludes } from "#test-assert";
 import { readFileSync } from "node:fs";
 import {
   assertThatInstance,
@@ -562,6 +562,10 @@ test("the fix-ci agent SLA interrupts the sub-process and escalates", async () =
   await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
   assertStringIncludes(String(escalation(engine).question ?? ""), "time budget (SLA)", "the SLA escalation must name the SLA trigger");
+  // #879 regression: the trusted fix-ci SLA arm must deliver its job-type marker to the shared
+  // persist-escalation sink so the worker builds the never-started-vs-hung diagnosis — a =null
+  // input pin on the shared recorder silently clobbered this (PR #881 adversarial review).
+  assertEquals(escalation(engine).agentSlaJobType, "senior:fix-ci", "the fix-ci SLA arm must reach the recorder with its job-type marker");
 });
 
 // ---------------------------------------------------------------------------
@@ -613,8 +617,49 @@ test("the rebase agent SLA interrupts the sub-process and escalates as not-merge
   await engine.advanceTime(AGENT_SLA_MS + 1);
   await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
   assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  // #879 regression: the trusted rebase SLA arm must deliver its job-type marker to the shared sink.
+  assertEquals(escalation(engine).agentSlaJobType, "senior:rebase", "the rebase SLA arm must reach the recorder with its job-type marker");
 });
 
+test("a non-SLA escalation carrying a spoofed agentSlaJobType is scrubbed before the recorder (#879 fail-closed)", async () => {
+  // The c8ctl harness hoists an agent's result-JSON keys into process scope, so a NON-SLA rebase
+  // agent that returns a bogus `agentSlaJobType` must NOT be able to fabricate an SLA diagnosis on
+  // the shared persist-escalation sink. The loop head / non-SLA escalate end events clear it.
+  const engine = await boot({ responses: { "senior:rebase": { status: "blocked", agentSlaJobType: "senior:evil" } } });
+  await driveToRebase(engine);
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-attempt");
+  const spoofed = escalation(engine).agentSlaJobType;
+  assert(spoofed === null || spoofed === undefined, `a spoofed agentSlaJobType must be scrubbed, got ${JSON.stringify(spoofed)}`);
+});
+
+test("a spoofed agentSlaJobType surviving the CI-reconcile re-check route is scrubbed before a later merge-esc-conflict (#881 Previously-missed)", async () => {
+  // The CI reconcile route (fix-ci blocked/pushed:false → ci-reconcile → end_ci_recheck →
+  // gw-merge-entry) re-enters the merge wait WITHOUT passing through the loop head `arm-merge` or
+  // the non-SLA escalate clears. A hoisted (spoofable) agentSlaJobType from that fix-ci result
+  // would otherwise survive into a later draft / budget-exhausted merge and fabricate an SLA
+  // never-started/hung diagnosis on the shared merge-esc-conflict sink with NO SLA timer having
+  // fired. `end_ci_recheck` must clear it (PR #881 review, "Previously missed" r5451284362).
+  const engine = await boot({
+    responses: { "senior:fix-ci": { status: "blocked", pushed: false, agentSlaJobType: "senior:evil" } },
+  });
+  await driveToCiFix(engine); // blocked/pushed:false → ci-reconcile → end_ci_recheck → re-check mergeable
+  assertThatInstance(engine, byProcessId("merge-loop"))
+    .isActive()
+    .hasActiveElement("wait-mergeable")
+    .hasCompletedElements("ci-reconcile")
+    .hasVariable("ciBlockedReconciled", true);
+  assert(!completedElementIds(engine).has("merge-esc-conflict"), "the reconcile pass must not escalate yet");
+  // A later merge-ready reports the PR as draft → f_m_mDraft → merge-esc-conflict reads the marker
+  // directly (the fix-ci agent does NOT run again on this route).
+  await engine.publishMessage({ name: "merge-ready", correlationKey: "pr-1", variables: { mergeState: "draft" } });
+  await assertThatUserTask(engine, { instance: byProcessId("merge-loop"), elementId: "wait-merge-answer" }).isCreated();
+  assertThatInstance(engine, byProcessId("merge-loop")).hasCompletedElements("merge-esc-conflict");
+  const spoofed = escalation(engine).agentSlaJobType;
+  assert(spoofed === null || spoofed === undefined, `the reconcile-route spoof must be scrubbed, got ${JSON.stringify(spoofed)}`);
+  // The human gets the genuine draft question, not a fabricated SLA diagnosis.
+  assertStringIncludes(String(escalation(engine).question ?? ""), "draft", "the escalation must be the genuine draft question, not an SLA diagnosis");
+});
 // ---------------------------------------------------------------------------
 // Escalation user task (mergeEscalationUserTask #256, mergeEscalationQuestion #329/#454)
 // ---------------------------------------------------------------------------

package/app/plan.test.ts

@@ -244,10 +244,13 @@ test("startPlan pins the base branch: persisted on the row + seeded as baseBranc
   // Host-git provisioning (#684): the whole-epic repository envelope so each slice's implementation
   // agent gets an isolated clone. The epic seed checks out the BASE branch (`ref`) — each slice's
   // `feat/<task.id>` branch differs per MI child, so NO `branch.create` here (the agent branches).
-  const repo = seen["io.nanobpm.agentTask"].repository;
+  const ns = seen["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.url, "https://github.com/owner/repo.git");
   assertEquals(repo.ref, "epic/agent-protocol");
-  assertEquals("branch" in repo, false);
+  // No isolation branch on the epic seed — `branch` is a top-level sibling of `repository` (#882),
+  // and it is omitted entirely here.
+  assertEquals("branch" in ns, false);
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
 });