@nanobpm/nano-workforce 0.201.1 → 0.201.3

package/app/repoEnvelope.test.ts

@@ -0,0 +1,139 @@
+// Contract test for the agent-task repository envelope (issue #882): the producer
+// (`app/repoEnvelope.ts`) and the consumer (the c8ctl nano worker harness's
+// `normalizeTaskEnvelope`, c8ctl-plugin.js) must agree on WHERE the deterministic
+// `branch.create` lives. The harness reads it from the TOP LEVEL of the envelope
+// (`raw.branch`), NOT nested under `repository`. The producer once nested it under
+// `repository.branch` — a shape the consumer never reads — so `branch.create`
+// silently never took effect (retries couldn't resume their WIP checkpoint, pushes
+// were refused off the work branch; nanobpm/nano-bpm#1344). This is the
+// two-sides-of-one-contract drift #227 guards against, so this test round-trips the
+// emitted envelope through a faithful mirror of the harness's normalizer shape and
+// asserts the consumer actually recovers `branch.create` — pinning producer and
+// consumer together so they cannot drift again.
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import { agentNodeRepoEnvelope, flattenAgentTaskEnvelope, repoEnvelopeVars } from "./repoEnvelope.ts";
+
+// ─── A faithful mirror of the harness's consumer shape ───────────────────────────────
+// These mirror the EXACT semantics of c8ctl-plugin-nano `normalizeTaskEnvelope`
+// (c8ctl-plugin.js): `collectEnvelopeFrom` reassembles the reserved
+// `io.nanobpm.agentTask` namespace out of BOTH a whole-object/JSON value AND flattened
+// dotpath keys, `deepMerge`s the two sources, and `normalizeTaskEnvelope` then reads
+// `branch` from the TOP LEVEL of the merged envelope (`isPlainObject(raw.branch)`),
+// NOT from `raw.repository.branch`. Keeping this mirror in lock-step with the harness
+// is the point of the test: if the producer emits a shape the consumer doesn't read,
+// the round-trip below drops `branch.create` and fails.
+const AGENT_TASK_NS = "io.nanobpm.agentTask";
+
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return v != null && typeof v === "object" && !Array.isArray(v);
+}
+
+function deepMerge(base: unknown, over: unknown): unknown {
+  if (!isPlainObject(base)) return isPlainObject(over) ? deepMerge({}, over) : over;
+  const out: Record<string, unknown> = { ...base };
+  if (!isPlainObject(over)) return out;
+  for (const [k, v] of Object.entries(over)) {
+    if (v === undefined) continue;
+    out[k] = isPlainObject(v) && isPlainObject(out[k]) ? deepMerge(out[k], v) : v;
+  }
+  return out;
+}
+
+function setPath(obj: Record<string, unknown>, path: string[], value: unknown): void {
+  let cur = obj;
+  for (let i = 0; i < path.length - 1; i++) {
+    const k = path[i];
+    if (!isPlainObject(cur[k])) cur[k] = {};
+    cur = cur[k] as Record<string, unknown>;
+  }
+  cur[path[path.length - 1]] = value;
+}
+
+/** Mirror of the harness's `collectEnvelopeFrom`: reassemble the reserved namespace from a
+ * whole-object/JSON value AND flattened dotpath keys (element templates / task headers emit the
+ * latter). */
+function collectEnvelopeFrom(source: Record<string, unknown>): Record<string, unknown> {
+  const out: Record<string, unknown> = {};
+  if (!isPlainObject(source)) return out;
+  const whole = source[AGENT_TASK_NS];
+  if (whole != null) {
+    let val: unknown = whole;
+    if (typeof whole === "string") {
+      try {
+        val = JSON.parse(whole);
+      } catch {
+        val = undefined;
+      }
+    }
+    if (isPlainObject(val)) Object.assign(out, deepMerge(out, val));
+  }
+  const prefix = `${AGENT_TASK_NS}.`;
+  for (const [key, value] of Object.entries(source)) {
+    if (!key.startsWith(prefix)) continue;
+    const rest = key.slice(prefix.length);
+    if (!rest) continue;
+    setPath(out, rest.split("."), value);
+  }
+  return out;
+}
+
+/** Mirror of the harness's `normalizeTaskEnvelope` branch slice: it reads `branch` from the TOP
+ * LEVEL of the merged envelope — `isPlainObject(raw.branch) ? raw.branch : {}` — never from
+ * `raw.repository.branch`. Returns the consumer's recovered `branch.create` (undefined when the
+ * producer put it somewhere the consumer doesn't look). */
+function harnessReadsBranchCreate(customHeaders: Record<string, unknown>, variables: Record<string, unknown>): string | undefined {
+  const raw = deepMerge(collectEnvelopeFrom(customHeaders), collectEnvelopeFrom(variables)) as Record<string, unknown>;
+  const branch = isPlainObject(raw.branch) ? raw.branch : {};
+  const create = branch.create;
+  return create == null ? undefined : String(create);
+}
+
+// ─── The round-trip contract ──────────────────────────────────────────────────────────
+
+test("contract: repoEnvelopeVars emits branch.create where the harness reads it (envelope TOP LEVEL, not repository.branch) (#882)", () => {
+  // The pre-PR implementation path: a deterministic feat/<task.id> branch the harness must cut.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7");
+  // Round-trip the emitted PROCESS-VARIABLE envelope through the harness normalizer shape.
+  const recovered = harnessReadsBranchCreate({}, vars);
+  assertEquals(
+    recovered,
+    "feat/issue-7",
+    "the harness reads branch.create from the envelope top level — nesting it under repository.branch drops it",
+  );
+});
+
+test("contract: repoEnvelopeVars PR path (ref == create == head) round-trips branch.create to the harness (#882/#231)", () => {
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/issue-12");
+});
+
+test("contract: agentNodeRepoEnvelope round-trips the deterministic per-node branch through the harness (#882/#776)", () => {
+  const vars = agentNodeRepoEnvelope("acme/one", "main", "feat/n1");
+  assertEquals(harnessReadsBranchCreate({}, vars), "feat/n1");
+});
+
+test("contract: the FLATTENED per-cell task headers round-trip branch.create to the harness (#882/#739)", () => {
+  // The delivery-graph path delivers the envelope as FLAT dotted task headers, which the harness
+  // reassembles via collectEnvelopeFrom's dotpath branch. Round-trip the flattened headers through
+  // the same normalizer shape so the header channel can't drift from the consumer either.
+  const envelope = agentNodeRepoEnvelope("acme/one", "main", "feat/open-b");
+  const flat = flattenAgentTaskEnvelope(envelope);
+  // The flattened key must be the TOP-LEVEL `branch.create`, NOT `repository.branch.create`.
+  assert(
+    "io.nanobpm.agentTask.branch.create" in flat,
+    `expected a top-level io.nanobpm.agentTask.branch.create header, got ${JSON.stringify(Object.keys(flat))}`,
+  );
+  assert(
+    !("io.nanobpm.agentTask.repository.branch.create" in flat),
+    "branch.create must NOT be nested under repository — the harness never reads it there",
+  );
+  const recovered = harnessReadsBranchCreate(flat, {});
+  assertEquals(recovered, "feat/open-b", "the harness reassembles the flattened header into branch.create");
+});
+
+test("contract: an envelope with NO branch round-trips to undefined (the consumer's default), never a bogus value (#882)", () => {
+  // A blank branchCreate omits the key entirely; the harness must then see no branch.create.
+  const vars = repoEnvelopeVars("owner/repo", "main", null, null, null);
+  assertEquals(harnessReadsBranchCreate({}, vars), undefined);
+});

package/app/repoEnvelope.ts

@@ -187,19 +187,25 @@ export function repoEnvelopeVars(
         // omission — the harness then clones the head branch tip, the pre-#324 behaviour. Omitted too
         // when the PR has no durable push-checkpoint yet.
         ...(isCommitSha(commitSha) ? { sha: commitSha } : {}),
-        // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
-        // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
-        // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
-        // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
-        // hand — making the isolated clone land on the right branch deterministically across a resume.
-        // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
-        // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
-        // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
-        // head branch. Only a blank/omitted value drops the key.
-        ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
-          ? { branch: { create: branchCreate.trim() } }
-          : {}),
       },
+      // Pre-PR provisioning (issue #684): the implementation path (feature.bpmn / plan-fanout's
+      // implement-cell) dispatches its agent BEFORE any PR exists, so `ref` is the BASE branch, not a
+      // head. `branchCreate` asks the harness to cut the deterministic `feat/<task.id>` feature branch
+      // off that base itself (the agent-guide's `feat/*` convention) instead of the agent branching by
+      // hand — making the isolated clone land on the right branch deterministically across a resume.
+      // The PR-based paths (review/fix-ci/rebase) ALSO pass `branchCreate = ref` (the PR head): without
+      // it the harness's base-branch guard (jwulf/c8ctl-plugin-nano#231) cuts a throwaway
+      // `nano/agent-work/*` fallback OFF the PR; with `ref == create == head` it commits/pushes to the
+      // head branch. Only a blank/omitted value drops the key.
+      //
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root (`isPlainObject(raw.branch)`), NOT from
+      // `repository.branch`. Nesting it under `repository` was the two-sides-of-one-contract drift
+      // (#227) that left `branch.create` silently unread (retries couldn't resume, pushes were
+      // refused — nanobpm/nano-bpm#1344).
+      ...(typeof branchCreate === "string" && branchCreate.trim() !== ""
+        ? { branch: { create: branchCreate.trim() } }
+        : {}),
       // Repo-provisioning auth gate (issue #770): c8ctl-plugin-nano (≥1.60.2) only resolves the
       // git credential (GITHUB_TOKEN, or the `gh` default when it's absent) for repository
       // provisioning when `task.allowPr` is truthy — `resolveJobSecrets` pulls the token behind that
@@ -251,10 +257,13 @@ export function agentNodeRepoEnvelope(repo: string, base: string | null, branchC
         // A per-node base (declared, or defaulted from the run level) — the branch the harness cuts its
         // `feat/<node.id>` off. Omitted when unknown so the harness clones the repo's default branch.
         ...(ref ? { ref, baseRef: ref } : {}),
-        // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
-        // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
-        ...(create ? { branch: { create } } : {}),
       },
+      // The deterministic isolation branch the harness cuts (issue #776), so the agent can never be
+      // left committing on the checked-out base branch. Off `ref` when known, else off the default tip.
+      // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness's
+      // `normalizeTaskEnvelope` reads it from the envelope root, NOT from `repository.branch`, so the
+      // flattened per-cell header is `io.nanobpm.agentTask.branch.create` (not `…repository.branch.create`).
+      ...(create ? { branch: { create } } : {}),
       // Repo-provisioning auth gate (issue #770): as in `repoEnvelopeVars`, a repo-backed cell must
       // opt the harness into git-credential resolution (`task.allowPr`) or the clone fails with
       // `unable to get password from user`. Emitted on every resolved cell (past the `owner/repo`

package/app/service.test.ts

@@ -1415,27 +1415,30 @@ test("repoEnvelopeVars emits the push-checkpoint under the harness-read `sha` ke
 // to `ref`) so the harness commits/pushes to the PR head branch instead of cutting a throwaway
 // `nano/agent-work/*` fallback (jwulf/c8ctl-plugin-nano#231); see the PR-path test below.
 test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#684)", () => {
-  const repo = (repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any)["io.nanobpm.agentTask"]
-    .repository;
+  const envelope = repoEnvelopeVars("owner/repo", "main", null, null, "feat/issue-7") as any;
+  const ns = envelope["io.nanobpm.agentTask"];
+  const repo = ns.repository;
   assertEquals(repo.ref, "main", "the pre-PR envelope checks out the BASE branch as its ref");
-  assertEquals(repo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the
+  // envelope root, NOT from `repository.branch`.
+  assertEquals(ns.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch off the base");
+  assertEquals("branch" in repo, false, "branch must NOT be nested under repository — the harness never reads it there");
   // Still branch-scoped and blobless like the PR-based envelope.
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
   // A whitespace-tainted branch is trimmed; a blank/absent one omits the `branch` key entirely so the
   // PR-based paths (and any caller that doesn't pre-create a branch) are unaffected.
   assertEquals(
-    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"].repository
+    (repoEnvelopeVars("owner/repo", "main", null, null, "  feat/issue-9  ") as any)["io.nanobpm.agentTask"]
       .branch.create,
     "feat/issue-9",
   );
   for (const blank of [null, undefined, "", "   "]) {
-    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"]
-      .repository;
+    const r = (repoEnvelopeVars("owner/repo", "main", null, null, blank as any) as any)["io.nanobpm.agentTask"];
     assertEquals("branch" in r, false, `expected no branch key for ${JSON.stringify(blank)}`);
   }
   // The default (4-arg) PR-based call never emits a branch.create.
-  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"].repository, false);
+  assertEquals("branch" in (repoEnvelopeVars("owner/repo", "feat/x", "main") as any)["io.nanobpm.agentTask"], false);
 });
 
 // PR-path provisioning (jwulf/c8ctl-plugin-nano#231): the review-round / fix-ci / rebase call sites
@@ -1445,11 +1448,13 @@ test("repoEnvelopeVars emits branch.create only for a non-blank pre-PR branch (#
 // `ref == create == head` the harness does a no-op `checkout -B <head>` and commits/pushes to the PR
 // head branch itself.
 test("repoEnvelopeVars emits branch.create = head on the PR path (ref == create == head) (#231)", () => {
-  const repo = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
+  const ns = (repoEnvelopeVars("owner/repo", "feat/issue-12", "main", null, "feat/issue-12") as any)[
     "io.nanobpm.agentTask"
-  ].repository;
+  ];
+  const repo = ns.repository;
   assertEquals(repo.ref, "feat/issue-12", "the PR-path envelope checks out the head branch");
-  assertEquals(repo.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
+  // `branch` is a TOP-LEVEL sibling of `repository` (issue #882), read by the harness from the root.
+  assertEquals(ns.branch.create, "feat/issue-12", "and asks the harness to work on that same head branch, not a fallback");
   // Still branch-scoped and blobless, and the base tip stays reachable for the 3-dot diff.
   assertEquals(repo.singleBranch, true);
   assertEquals(repo.filter, "blob:none");
@@ -1496,9 +1501,9 @@ test("submitPr threads the resolved PR head into the envelope branch.create (#23
       url: "https://github.com/owner/repo/pull/12",
       prKey: "owner/repo#12",
     });
-    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
-    assertEquals(repo?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
-    assertEquals(repo?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-12", "submitPr checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-12", "submitPr passes headRef as branch.create, not a fallback");
   });
 });
 
@@ -1521,9 +1526,9 @@ test("startMerge threads the resolved PR head into the envelope branch.create (#
       prKey: "owner/repo#13",
       round: 2,
     });
-    const repo = (get()?.["io.nanobpm.agentTask"] as any)?.repository;
-    assertEquals(repo?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
-    assertEquals(repo?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
+    const ns = get()?.["io.nanobpm.agentTask"] as any;
+    assertEquals(ns?.repository?.ref, "feat/issue-13", "startMerge checks out the PR head branch");
+    assertEquals(ns?.branch?.create, "feat/issue-13", "startMerge passes headRef as branch.create, not a fallback");
   });
 });
 

package/app/service.ts

@@ -10,6 +10,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 { AGENT_SLA_JOB_TYPES, recordAgentJobObservation } from "./agentActivationLedger.ts";
 import { completeEscalationAutoApplied, escalationFormId } from "./agentCompletion.ts";
 import { AGENT_SLA_TIMEOUT } from "./agentSla.ts";
 import {
@@ -1733,6 +1734,98 @@ interface JobSearchItem {
   /** The job's `zeebe:taskDefinition` type — read to defensively re-filter the wire `$in` type
    * filter so a non-agent job can never masquerade as a leasing convergence agent. */
   type?: string;
+  /** The owning process instance — keyed into the activation ledger (issue #879). */
+  processInstanceKey?: string;
+  /** The engine job key — the unique id of THIS job attempt. The activation ledger uses it to tell one
+   * attempt of a retrying agent task from the next (issue #879 review). */
+  jobKey?: string;
+}
+
+/** One agent-activation ledger poll pass (issue #879). Unlike {@link pollJobActivationImpl} (which
+ * tracks only the review-round for the pages grid), this records — for EVERY bounded agent job type —
+ * whether a worker ever picked the job up, into the durable `agent_job_activations` ledger. When an
+ * agent-task SLA boundary later cancels a job, the job's engine state is gone, so the escalation
+ * recorder cannot ask the engine whether it was ever activated; this ledger, captured WHILE the job is
+ * live, is what lets the escalation distinguish a NEVER-ACTIVATED (queue-starved) job from an
+ * ACTIVATED-but-hung one.
+ *
+ * It reads the same activation signal as the review-round pass: the Camunda-8 `/v2/jobs/search` wire
+ * API collapses Activated -> CREATED (no ACTIVATED enum), so a leased job is recognised by its
+ * `worker`/`deadline` fields. One paged search across all bounded agent types per pass upserts the
+ * ledger by (processInstanceKey, type), keyed to the current attempt by `jobKey`. Best-effort: a
+ * transport failure leaves the ledger untouched and the next pass retries. */
+async function pollAgentActivations(
+  data: DataLayer,
+  restAddress: string,
+  engineToken: string | undefined,
+) {
+  const base = restAddress.replace(/\/+$/, "");
+  const headers: Record<string, string> = { "content-type": "application/json" };
+  if (engineToken) headers.authorization = `Bearer ${engineToken}`;
+  await pollAgentActivationsImpl(data, base, headers);
+}
+
+/** Testable core of {@link pollAgentActivations}: query the engine for every CREATED bounded-agent job
+ * and upsert the activation ledger. Split out so tests can drive it with a stubbed `fetch`. */
+export async function pollAgentActivationsImpl(
+  data: DataLayer,
+  base: string,
+  headers: Record<string, string>,
+) {
+  // Page through EVERY matching open job: a single first-page read would, under fleet saturation, let
+  // long-lived jobs occupy the page on every pass while later jobs time out with their activation never
+  // recorded — exactly when the never-started/hung distinction matters most. Mirror the paging contract
+  // the other engine sweeps use (`page: { from, limit }`, stop on a short page). (#881 review)
+  const ts = now();
+  const limit = 200;
+  let from = 0;
+  for (let guard = 0; guard < 1000; guard++) {
+    let items: JobSearchItem[] = [];
+    try {
+      const res = await fetch(`${base}/jobs/search`, {
+        method: "POST",
+        headers,
+        body: JSON.stringify({
+          filter: {
+            type: { $in: [...AGENT_SLA_JOB_TYPES] },
+            // A merely-created (queued) AND an activated-but-not-yet-completed job both project to
+            // CREATED on the wire (Camunda has no ACTIVATED enum) — so this one filter captures both,
+            // and the leasing `worker` field discriminates them at upsert time.
+            state: "CREATED",
+          },
+          page: { from, limit },
+        }),
+      });
+      if (!res.ok) return; // engine unhappy → keep the ledger as-is, retry next pass
+      // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
+      const body = (await res.json()) as { items?: JobSearchItem[] };
+      items = body.items ?? [];
+    } catch (err) {
+      console.error(`[poller] agent-activation search: ${err}`);
+      return;
+    }
+    for (const j of items) {
+      const jobType = j.type ?? "";
+      const pik = j.processInstanceKey ?? "";
+      // Defensively re-filter the wire `$in` type filter and require a process instance to key on.
+      if (pik.length === 0 || !AGENT_SLA_JOB_TYPES.includes(jobType)) continue;
+      const worker = typeof j.worker === "string" && j.worker.length > 0 ? j.worker : null;
+      const jobKey = typeof j.jobKey === "string" && j.jobKey.length > 0 ? j.jobKey : null;
+      try {
+        await recordAgentJobObservation(data, {
+          processInstanceKey: pik,
+          jobType,
+          worker,
+          jobKey,
+          now: ts,
+        });
+      } catch (err) {
+        console.error(`[poller] agent-activation upsert ${pik}:${jobType}: ${err}`);
+      }
+    }
+    if (items.length < limit) break; // last page
+    from += items.length;
+  }
 }
 
 /** One job-activation poll pass. The `converging` status means the process is parked at a
@@ -3717,6 +3810,7 @@ export async function pollOnce(
     await pollWaveGatesImpl(data, engine, token, base, headers);
     await pollCapabilityGatesImpl(data, engine, base, headers);
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
+    await pollAgentActivations(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);
   }
 }

package/db/migrations/119_agent_job_activations.sql

@@ -0,0 +1,50 @@
+-- 119_agent_job_activations.sql — issue #879: distinguish a NEVER-ACTIVATED (queue-starved) agent
+-- job from an ACTIVATED-but-hung one when an agent-task SLA boundary fires.
+--
+-- The agent-task SLA timer (`<bpmn:timeDuration>=agentSlaTimeout`) starts when the service task is
+-- ENTERED, so it measures QUEUE time + RUN time. When no worker can take the job type (fleet
+-- saturation / no capacity), the job sits CREATED (never leased) for the whole budget and the
+-- boundary fires — yet the escalation reported it as "hung or looping", telling the human to "check
+-- its progress" when there is none. (The reported case: a `senior:feature` job queued 2h, never
+-- activated, then cancelled by its SLA boundary.)
+--
+-- The engine tracks JobState::Created vs ::Activated, but the Camunda-8 `/v2/jobs/search` wire API
+-- collapses Activated -> CREATED (no ACTIVATED enum value); activation is read off the `worker` +
+-- `deadline` fields — an activated job carries a leasing worker's name and a lock deadline, a
+-- merely-queued one carries neither (same signal `pull_requests.active_worker`/`lease_until` use for
+-- the review-round, migration 005). This ledger generalises that observation to EVERY bounded agent
+-- job type (not just the review-round) and PERSISTS it, so when the SLA boundary cancels the job the
+-- escalation recorder can still tell whether a worker ever picked it up.
+--
+-- The poller (`pollAgentActivations`, app/service.ts) upserts one row per (process_instance_key,
+-- job_type) each pass: `first_seen_at` on first observation (job CREATED), and `activated_at` +
+-- `worker` the first time it observes a leasing worker. The SLA-escalation recorders read it by the
+-- same key (the agent job and its escalation recorder share one process instance) to word the
+-- escalation accurately — "never started (queue starvation)" vs "started but exceeded its budget" —
+-- including the job type and how long it waited.
+--
+-- `job_key` holds the engine job key of the CURRENT attempt so the row tracks that attempt, not a
+-- stale earlier one: the same (process_instance_key, job_type) runs MULTIPLE times within one instance
+-- when its cell retries (implement-cell `ic_reImplement`, merge-cell `mc_rerun`, merge-loop fix-ci /
+-- rebase reloops). Keyed only by (instance, job_type) a sticky first-activation would make a later
+-- queued retry read the EARLIER attempt's worker and misdiagnose it as started/hung. When the poller
+-- observes a different `job_key` for the pair it RESETS the row to the new attempt (first_seen_at /
+-- activated_at / worker), so the escalation always reflects the attempt the SLA boundary cancelled.
+--
+-- Keyed by a surrogate TEXT id (`<process_instance_key>:<job_type>`) so the single-pk `data.table`
+-- accessor can upsert it; the (process_instance_key, job_type) pair is unique per id. FK-free by
+-- design — the owning instance lives in the durable ENGINE store, not app.db, so there is no app-tier
+-- parent row to reference (mirrors `worker_durable_resume`/`worker_harness_protocol`). EXPAND
+-- (additive) phase: one new table; nothing is dropped or renamed. The runner wraps each file in its
+-- own transaction, so this file must NOT contain BEGIN/COMMIT.
+CREATE TABLE IF NOT EXISTS agent_job_activations (
+  id                   TEXT PRIMARY KEY,  -- surrogate: `<process_instance_key>:<job_type>`
+  process_instance_key TEXT NOT NULL,     -- the engine instance the agent job (and its SLA recorder) runs in
+  job_type             TEXT NOT NULL,     -- the agent job's `<zeebe:taskDefinition>` type (e.g. senior:feature)
+  first_seen_at        TEXT NOT NULL,     -- ISO ts the poller first observed the job (CREATED/queued)
+  activated_at         TEXT,              -- ISO ts first observed ACTIVATED (leasing worker seen); NULL = never started
+  worker               TEXT,              -- the leasing worker's name at activation; NULL until activated
+  job_key              TEXT,              -- the engine job key of the CURRENT attempt; a new key RESETS the row (retry isolation)
+  updated_at           TEXT NOT NULL
+);
+CREATE INDEX IF NOT EXISTS ix_agent_job_activations_instance ON agent_job_activations (process_instance_key);

package/e2e/agent-sla-boundary.e2e.ts

@@ -307,13 +307,25 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       );
       const task = await openTaskById(app, processKey, "trial-merge-decision");
       assert.ok(task?.userTaskKey, "the merge-cell parked a completable trial-merge decision task");
+
+      // UNKNOWN activation fixture (issue #881 review): no activation-ledger row exists for this attempt
+      // (the in-test poller records none), so the recorder must word the escalation honestly as
+      // "activation unknown" — never the removed blanket "hung or looping".
+      const slaAudit = (
+        await app.db
+          .table<{ id: number; plan_key: string; summary: string | null }>("plan_trial_merges", "id")
+          .find({ plan_key: "owner/repo#1" })
+      ).sort((a, b) => b.id - a.id)[0];
+      assert.ok(
+        (slaAudit?.summary ?? "").includes("no worker-activation was ever recorded"),
+        `an unobserved job escalates with honest ambiguity (got: ${slaAudit?.summary})`,
+      );
     } finally {
       await app.stop();
       rmSync(dbDir, { recursive: true, force: true });
     }
   });
 
-  // Regression for PR #864 review r3: on an SLA during a RERUN the recorder must not replay the
   // prior COMPLETED attempt's process-scope `result`/`summary`/`conflicts`/`failing`. The
   // `=null` ioMapping on `trial-merge` is task-local, so without a dedicated SLA recorder the
   // interrupted second attempt would inherit attempt one's stale verdict. Drive ONE instance: a
@@ -381,6 +393,19 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       );
 
       // The second agent hangs; the SLA fires. The DEDICATED SLA recorder must pin the TIMEOUT verdict.
+      // Seed an ACTIVATED activation-ledger fixture for THIS attempt (issue #881 review) so the recorder
+      // reads the ledger and produces the activation-aware "started but hung" reason — exercising the
+      // builder's activated branch end-to-end through record-trial-merge-sla, not just the pure builder.
+      await app.db.table("agent_job_activations", "id").insert({
+        id: `${processKey}:senior:trial-merge`,
+        process_instance_key: processKey,
+        job_type: "senior:trial-merge",
+        first_seen_at: "2024-01-01T00:00:00Z",
+        activated_at: "2024-01-01T00:05:00Z",
+        worker: "agent-stuck",
+        job_key: "rerun-attempt",
+        updated_at: "2024-01-01T00:05:00Z",
+      });
       await advancePastTimer(app, PAST_AGENT_SLA_MS);
       flows = takenFlows(app);
       assert.ok(
@@ -402,11 +427,15 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
         .find({ plan_key: "owner/repo#1" });
       const slaRow = audits.sort((a, b) => b.id - a.id)[0];
       assert.equal(slaRow.result, "suite-failed", "the SLA row records the timeout verdict");
-      assert.equal(
-        slaRow.summary,
-        `The trial-merge agent exceeded its time budget (SLA ${AGENT_SLA_TIMEOUT}) without returning a machine-readable result — it is hung or looping. Acknowledge to record the timeout and decide whether to rerun the trial merge.`,
-        "the SLA row pins the timeout summary, not the stale prior-attempt summary",
+      // Activation-aware summary: names the job type, the leasing worker, and the hung diagnosis — NOT
+      // the stale first-attempt summary, and NOT the removed blanket wording.
+      assert.ok(
+        (slaRow.summary ?? "").includes("senior:trial-merge") &&
+          (slaRow.summary ?? "").includes("hung or looping") &&
+          (slaRow.summary ?? "").includes("agent-stuck"),
+        `the SLA row pins the activation-aware timeout summary (got: ${slaRow.summary})`,
       );
+      assert.equal((slaRow.summary ?? "").includes("stale prior-attempt summary"), false, "not the stale summary");
       assert.equal(slaRow.conflicts, null, "the SLA row clears the stale prior-attempt conflicts");
       assert.equal(slaRow.failing, null, "the SLA row clears the stale prior-attempt failing list");
     } finally {
@@ -552,7 +581,20 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
       assert.equal(filed?.status, "filed", "the conformance verdict was filed before synthesize");
       assert.equal(filed?.slices_met, 3);
 
-      // Fire the synthesize SLA.
+      // Fire the synthesize SLA. Seed a QUEUED (never-activated) activation-ledger fixture for the
+      // synthesize (senior:retro) attempt (issue #881 review) so the recorder reads it and APPENDS the
+      // activation-aware never-observed-activated reason — exercising the builder's queued branch
+      // end-to-end through conformance-record, not just the pure builder.
+      await app.db.table("agent_job_activations", "id").insert({
+        id: `${processKey}:senior:retro`,
+        process_instance_key: processKey,
+        job_type: "senior:retro",
+        first_seen_at: "2024-01-01T00:00:00Z",
+        activated_at: null,
+        worker: null,
+        job_key: "synthesize-attempt",
+        updated_at: "2024-01-01T00:00:00Z",
+      });
       await advancePastTimer(app, PAST_AGENT_SLA_MS);
       const flows = takenFlows(app);
       assert.ok(
@@ -587,8 +629,9 @@ describe("agent-task SLA boundary — rerouted recorder→escalation arms (#849
         `the audit summary is preserved and the SLA reason appended (got: ${row?.summary})`,
       );
       assert.ok(
-        (row?.summary ?? "").includes("retrospective-synthesis agent exceeded its time budget"),
-        "the synthesis-timeout context is appended to the summary",
+        (row?.summary ?? "").includes("No worker was ever observed to pick up") &&
+          (row?.summary ?? "").includes("senior:retro"),
+        `the activation-aware synthesis-timeout context is appended to the summary (got: ${row?.summary})`,
       );
     } finally {
       await app.stop();

package/e2e/feature-run.e2e.ts

@@ -133,11 +133,11 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     // carries — proof the implement-cell agent gets an ISOLATED clone (base branch + a harness-cut
     // `feat/<task.id>`) instead of inheriting the worker's launch dir. It rides the process variable
     // all the way down through feature.bpmn's `implement` callActivity into the cell's agent job.
-    let agentRepo: any = null;
+    let agentTask: any = null;
     await withApp(
       {
         "senior:feature": (job) => {
-          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
           return { status: "opened", pr: "owner/repo#101", summary: "built it" };
         },
       },
@@ -150,10 +150,12 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
         );
         assert.ok(!flows.includes("gw-converge->converge"), "the converge hand-off branch was NOT taken");
 
-        assert.ok(agentRepo, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        assert.ok(agentTask, "the senior:feature job carried the io.nanobpm.agentTask repository envelope");
+        const agentRepo = agentTask.repository;
         assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
         assert.equal(agentRepo.ref, "epic/e2e", "a PRE-PR job checks out the BASE branch, not a head");
-        assert.equal(agentRepo.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch");
+        // `branch` is a TOP-LEVEL sibling of `repository` (issue #882) — the harness reads it from the root.
+        assert.equal(agentTask.branch.create, "feat/issue-7", "the harness cuts the deterministic feature branch");
 
         const run = await featureRow(app, featureKey);
         assert.equal(run.status, "opened", "the run settled at opened");

package/e2e/plan-fanout.e2e.ts

@@ -131,22 +131,24 @@ describe("plan-fanout escalations (U2 — task + plan-review + trial-merge → u
     // rides down through the wave subprocess + `implement-cell-call` callActivity into each agent job.
     // The epic seed carries the BASE branch as `ref` but NO `branch.create` — each slice's
     // `feat/<task.id>` differs per MI child, so the agent cuts its own branch inside the clone.
-    let agentRepo: any = null;
+    let agentTask: any = null;
     await withApp(
       {
         "senior:plan": singleTaskPlan,
         "senior:plan-review": approveReview,
         "senior:feature": (job) => {
-          agentRepo = (job.variables as Record<string, any>)["io.nanobpm.agentTask"]?.repository ?? null;
+          agentTask = (job.variables as Record<string, any>)["io.nanobpm.agentTask"] ?? null;
           return { status: "blocked", summary: "n/a" };
         },
       },
       async ({ app }) => {
         await app.settle();
-        assert.ok(agentRepo, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        assert.ok(agentTask, "the epic slice's senior:feature job carried the io.nanobpm.agentTask envelope");
+        const agentRepo = agentTask.repository;
         assert.equal(agentRepo.url, "https://github.com/owner/repo.git", "the harness clones the target repo");
         assert.equal(agentRepo.ref, "epic/e2e", "the epic seed checks out the BASE (integration) branch");
-        assert.equal("branch" in agentRepo, false, "the epic seed omits branch.create — the agent branches per slice");
+        // `branch` is a top-level sibling of `repository` (#882); the epic seed omits it entirely.
+        assert.equal("branch" in agentTask, false, "the epic seed omits branch.create — the agent branches per slice");
         assert.equal(agentRepo.singleBranch, true, "the blobless/single-branch monorepo shaping rides along");
         assert.equal(agentRepo.filter, "blob:none");
       },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.201.1",
+  "version": "0.201.3",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",