@nanobpm/nano-workforce 0.43.0 → 0.44.1

package/.github/workflows/ci.yml

@@ -51,3 +51,10 @@ jobs:
       # TypeScript types on the fly (Node >= 22.6) — no build step.
       - name: Test (Node)
         run: npm test
+
+      # End-to-end pilot (nano-ide issue #157, S3): boots the whole app in-process against the WASM
+      # engine + a virtual clock via @nanobpm/urban-testkit and drives the real /app/api operations.
+      # Hermetic (no socket, no GitHub network), so it runs on every push like the unit suite.
+      - name: E2E (urban-testkit)
+        run: npm run e2e
+

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.44.1](https://github.com/nanobpm/nano-workforce/compare/v0.44.0...v0.44.1) (2026-08-11)
+
+
+### Bug Fixes
+
+* provision isolated agent workspaces via the c8ctl repository envelope ([#124](https://github.com/nanobpm/nano-workforce/issues/124)) ([79c999b](https://github.com/nanobpm/nano-workforce/commit/79c999bc34dd7984ceffd7746a4538705565f2a5))
+
+# [0.44.0](https://github.com/nanobpm/nano-workforce/compare/v0.43.0...v0.44.0) (2026-08-11)
+
+
+### Features
+
+* **merge-loop:** wait on a blocking PR instead of escalating to a human ([#122](https://github.com/nanobpm/nano-workforce/issues/122)) ([aec738f](https://github.com/nanobpm/nano-workforce/commit/aec738f165df5a216b9094b4eb9b5b6d4a7ac419))
+
 # [0.43.0](https://github.com/nanobpm/nano-workforce/compare/v0.42.0...v0.43.0) (2026-08-11)
 
 

package/SPEC.md

@@ -173,7 +173,7 @@ triaging, editing/replying/pushing, and (when `addressed`) re-requesting review.
 Workspace isolation is the **worker harness's** responsibility, not this app's and
 not the prompt's. The `c8ctl nano work` host-git provisioning (frozen v1 envelope)
 gives **each job its own `mkdtemp` run-dir + fresh clone**, runs the agent with
-`cwd` set to it (`AGENT_WORKSPACE`/`REPO_URL`/`REPO_BRANCH`/`REPO_REF` env), and
+`cwd` set to it (`AGENT_WORKSPACE`/`AGENT_REPO_URL`/`AGENT_REPO_BRANCH`/`AGENT_REPO_REF` env), and
 **reaps that run-dir when the job ends**. So multiple agents on one host do **not**
 collide even in host mode — the isolation lives below the agent.
 
@@ -183,8 +183,13 @@ Consequences the prompt (`prompts/review-round.md`) encodes:
 - The agent **cleans up anything it creates outside the commit** before returning
   (worktrees, scratch branches/clones, temp files), so host mode does not leak.
 - The harness checks out the PR's **existing head branch** and pushes back to it
-  (no new branch/PR). The `c8ctl` integration provisions the repo and resolves the
-  head branch from `prNumber`/`prUrl` — the app does not pass a `headBranch` var.
+  (no new branch/PR). Provisioning only fires when the job carries a
+  `io.nanobpm.agentTask.repository.url`; the **app** supplies it — plus the head
+  branch as `…repository.ref` — as a process variable at `createInstance`
+  (`repoEnvelopeVars` in `app/service.ts`, resolving the head via `fetchPrMeta`/
+  `fetchPrHead`). The harness is PR-agnostic: it does **not** derive the head branch
+  from `prNumber`/`prUrl`. When the head can't be resolved the envelope is omitted and
+  the agent falls back to the worker's launch directory (the legacy behavior).
 
 ## 6. Signals
 
@@ -368,11 +373,21 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
   exhausted, the agent reports `blocked`, or the branch is in `conflict` does it fall
   through to the human escalation path.
 
+- **Discovered dependency** — a `senior:fix-ci` or `senior:rebase` agent may find that
+  the PR cannot land because **another PR must merge first** (a required linked-issue
+  gate a sibling PR will close, a stacked base PR, or a `Depends-on:` the agent read
+  from the PR/issue text). That is an ordering **wait, not a human decision**: the
+  agent returns `status: "waiting-on-pr"` with a `dependsOn` list of `owner/repo#N`
+  refs. `pr.record-dependency` appends those edges to `pr_dependencies` and parks the
+  PR back at *wait: deps merged*, so the same poller pass lands it automatically once
+  the named PRs merge — no escalation is opened.
+
 - **Dependencies** — `pr_dependencies(pr_key, depends_on_key)` (migration 004).
-  Declared two ways: a `Depends-on: owner/repo#N` line in the PR body (parsed on
-  submit) and/or a `dependsOn` array on the submit request. `merge-loop` parks at
-  *wait: deps merged*; the poller checks each dependency (own tracked row first,
-  else GitHub `merged` state) and publishes `deps-cleared` once all have landed.
+  Declared three ways: a `Depends-on: owner/repo#N` line in the PR body (parsed on
+  submit), a `dependsOn` array on the submit request, and/or **discovered at merge
+  time** by a `fix-ci`/`rebase` agent (`status: "waiting-on-pr"`, above). `merge-loop`
+  parks at *wait: deps merged*; the poller checks each dependency (own tracked row
+  first, else GitHub `merged` state) and publishes `deps-cleared` once all have landed.
 - **Mergeability** — the poller classifies GitHub's `mergeStateStatus`:
   `CLEAN`/`HAS_HOOKS`/`UNSTABLE`/`BEHIND` → `ready`; `DIRTY` → `conflict`;
   `BLOCKED` → `blocked` if a required check is failing, else keep waiting;
@@ -500,9 +515,10 @@ the loop runs one parallel `implement` MI fan-out per wave:
 
 - **Provisioning the existing PR branch** — resolved: the `c8ctl` host-git
   integration provisions the repo and checks out the PR's head branch (it must
-  already give the worker repo access to work at all), resolving the branch from
-  `prNumber`/`prUrl`. The app does **not** pass a `headBranch` job variable; the
-  job stays engine-shaped and the worker stays a pure provisioner.
+  already give the worker repo access to work at all). The **app** resolves the head
+  branch and passes it in the `io.nanobpm.agentTask.repository.{url,ref}` envelope
+  (a `createInstance` process variable — see `repoEnvelopeVars`); the harness is
+  PR-agnostic and provisions from that envelope. The worker stays a pure provisioner.
 - **review-ready via GitHub webhook** — same message, swappable faster trigger,
   when the app is publicly reachable. Deferred (poller-only for v1).
 - **Supervised vs external worker** — the agent runs as an external

package/app/github.ts

@@ -177,6 +177,10 @@ async function useGh(): Promise<boolean> {
 export interface PrMeta {
   title: string | null;
   body: string;
+  /** The PR's head branch name (e.g. `feat/issue-12`). Drives the c8ctl harness's isolated
+   * workspace checkout (`io.nanobpm.agentTask.repository.ref`) so the review agent lands on the
+   * PR branch instead of the worker's launch directory. `null` when GitHub doesn't return it. */
+  headRef: string | null;
 }
 
 export async function fetchPrMeta(
@@ -185,10 +189,10 @@ export async function fetchPrMeta(
   token: string,
 ): Promise<PrMeta | null> {
   if (await useGh()) {
-    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body"]);
+    const out = await runGh(["pr", "view", String(number), "--repo", repo, "--json", "title,body,headRefName"]);
     // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-    const j = JSON.parse(out) as { title?: string; body?: string };
-    return { title: j.title ?? null, body: j.body ?? "" };
+    const j = JSON.parse(out) as { title?: string; body?: string; headRefName?: string | null };
+    return { title: j.title ?? null, body: j.body ?? "", headRef: j.headRefName ?? null };
   }
   if (!token) return null;
   const r = await fetch(`https://api.github.com/repos/${repo}/pulls/${number}`, {
@@ -196,8 +200,8 @@ export async function fetchPrMeta(
   });
   if (!r.ok) throw new Error(`github ${r.status} ${r.statusText}`.trim());
   // biome-ignore lint/plugin: runtime/framework contract boundary for external data shape
-  const j = (await r.json()) as { title?: string; body?: string };
-  return { title: j.title ?? null, body: j.body ?? "" };
+  const j = (await r.json()) as { title?: string; body?: string; head?: { ref?: string | null } };
+  return { title: j.title ?? null, body: j.body ?? "", headRef: j.head?.ref ?? null };
 }
 
 /** A PR's merge state, narrowed to what the merge poller needs to classify landability.

package/app/persist-escalation.test.ts

@@ -57,6 +57,18 @@ test("escalation arm without the flag still records the round", async () => {
   assertEquals((inserts.rounds[0] as any).round_no, 3);
 });
 
+// The servicing worker name (harness `agent` var) is stamped on both the round it recorded and
+// the escalation it opened, so the durable history identifies who did the work.
+test("persist-escalation records the servicing worker on the round and escalation", async () => {
+  const { app, inserts } = fakeApp();
+  const job = {
+    variables: { prKey: "o/r#1", round: 3, status: "blocked", question: "max rounds", agent: "senior" },
+  };
+  await handler(job as any, app as any);
+  assertEquals((inserts.rounds[0] as any).worker, "senior", "the round carries the worker name");
+  assertEquals((inserts.escalations[0] as any).worker, "senior", "the escalation carries the worker name");
+});
+
 // When the convergence-loop passes repo/prNumber and the FK parent is missing (engine/app.db
 // desync), persist-escalation reconstructs the `pull_requests` row before the rounds/escalations
 // inserts so opening an escalation never dies with an opaque FOREIGN KEY constraint failure.

package/app/persist-round.test.ts

@@ -56,6 +56,23 @@ for (const status of ["addressed", "waiting"]) {
   });
 }
 
+// The harness completes each agent job with `agent` (its profile name); persist-round records it
+// on the round so a human can identify the servicing worker from the durable history.
+test("persist-round records the servicing worker name from the agent variable", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 1, status: "addressed", agent: "senior" } };
+  await handler(job as any, app as any);
+  assertEquals((inserts.rounds[0] as any).worker, "senior", "the round carries the worker name");
+});
+
+// A blank/absent agent name leaves the nullable column NULL (the write boundary omits undefined).
+test("persist-round leaves worker undefined when the agent name is blank", async () => {
+  const { app, inserts } = fakeApp();
+  const job = { variables: { prKey: "o/r#1", round: 1, status: "addressed", agent: "  " } };
+  await handler(job as any, app as any);
+  assertEquals((inserts.rounds[0] as any).worker, undefined, "blank worker -> NULL column");
+});
+
 // When the convergence-loop passes repo/prNumber and the FK parent is missing (engine/app.db
 // desync), persist-round reconstructs the `pull_requests` row before recording the round so the
 // insert never dies with an opaque FOREIGN KEY constraint failure.

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { pollIncidentsImpl, submitPr } from "./service.ts";
+import { pollIncidentsImpl, repoEnvelopeVars, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -331,3 +331,19 @@ test("submitPr defaults convergeOnly to false so the global auto-merge default g
     assertEquals(get(), false);
   });
 });
+
+// The repository envelope drives the c8ctl harness's isolated workspace provisioning: it is
+// emitted under the reserved `io.nanobpm.agentTask` namespace with the PR head branch as the
+// checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness
+// falls back to the legacy launch-dir behavior instead of cloning the wrong default branch).
+test("repoEnvelopeVars emits the repository envelope keyed on the PR head branch", () => {
+  const vars = repoEnvelopeVars("owner/repo", "feat/issue-12");
+  const env = (vars as any)["io.nanobpm.agentTask"];
+  assertEquals(env.repository.url, "https://github.com/owner/repo.git");
+  assertEquals(env.repository.ref, "feat/issue-12");
+  assertEquals(env.repository.provider, "github");
+});
+
+test("repoEnvelopeVars emits nothing when the head branch is unresolved", () => {
+  assertEquals(Object.keys(repoEnvelopeVars("owner/repo", null)).length, 0);
+});

package/app/service.ts

@@ -12,6 +12,7 @@ import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import {
   classifyMergeability,
   ensureFreshHeadRun,
+  fetchPrHead,
   fetchPrMeta,
   fetchPrReviews,
   fetchPrState,
@@ -277,6 +278,27 @@ async function registerDependencies(data: DataLayer, prKey: string, depKeys: str
   }
 }
 
+/** The reserved namespace key the c8ctl nano worker harness reads the agent-task envelope from
+ * (headers ∪ variables, deep-merged). See c8ctl `normalizeTaskEnvelope`. */
+const AGENT_TASK_NS = "io.nanobpm.agentTask";
+
+/** Build the repository slice of the agent-task envelope for a PR-based agent job (review-round,
+ * fix-ci, rebase). Delivered as a *process variable* under the reserved `io.nanobpm.agentTask`
+ * key so the harness provisions an isolated clone checked out on the PR's head branch — instead of
+ * the agent inheriting whatever directory the worker was launched from (which only happened to be
+ * a usable checkout for repos already present locally). `ref` MUST be the PR head branch; when it
+ * is unresolved we emit nothing (no `repository.url`) so the harness falls back to the legacy
+ * launch-dir behavior rather than silently cloning the repo's default branch. The static
+ * `task.prompt` header on the service task deep-merges with this over the same namespace. */
+export function repoEnvelopeVars(repo: string, ref: string | null): Record<string, unknown> {
+  if (!ref) return {};
+  return {
+    [AGENT_TASK_NS]: {
+      repository: { provider: "github", url: `https://github.com/${repo}.git`, ref },
+    },
+  };
+}
+
 /** Register a PR row (if new) and start the convergence process. Idempotent on prKey. Optional
  * `dependsOn` (explicit refs) is unioned with any `Depends-on:` line parsed from the PR body and
  * recorded as the PR's merge-stage dependency set. */
@@ -298,16 +320,23 @@ export async function submitPr(
   // A transport failure (no gh/token) must not block submission — we just skip enrichment.
   const token = process.env.GITHUB_TOKEN ?? "";
   let title: string | null = null;
+  let headRef: string | null = null;
   const depKeys = new Set(dependsOn.map((d) => parsePr(d)?.prKey).filter((k): k is string => !!k));
   try {
     const meta = await fetchPrMeta(parsed.repo, parsed.number, token);
     if (meta) {
       title = meta.title;
+      headRef = meta.headRef;
       for (const k of parseDependsOn(meta.body)) depKeys.add(k);
     }
   } catch (err) {
     console.warn(`[submit] ${parsed.prKey} meta fetch: ${err}`);
   }
+  if (!headRef) {
+    // Without the head branch the harness can't check out the PR; the review agent then falls
+    // back to the worker's launch dir (the legacy behavior) and escalates if it isn't a checkout.
+    console.warn(`[submit] ${parsed.prKey} head branch unresolved — agent workspace won't be provisioned`);
+  }
   await registerDependencies(data, parsed.prKey, [...depKeys]);
 
   const ts = now();
@@ -375,6 +404,10 @@ export async function submitPr(
       // review-round agent's prompt, so it can stop before pushing if the run is cancelled.
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
+      // Host-git provisioning (c8ctl): deliver the repository envelope so the `senior:pr-review`
+      // harness clones an isolated workspace checked out on the PR head branch. Spread last so an
+      // unresolved head (`{}`) leaves the other vars untouched.
+      ...repoEnvelopeVars(parsed.repo, headRef),
     },
   });
   const processKey = processInstanceKey == null ? null : String(processInstanceKey);
@@ -400,6 +433,19 @@ export async function startMerge(
     await prs(data).update(pr.prKey, { abandon_token: abandonToken, updated_at: now() });
   }
   const abUrl = abandonUrl(abandonToken);
+  // Resolve the PR head branch so the merge agents (fix-ci, rebase) get an isolated clone checked
+  // out on it (same host-git provisioning path as review-round). Best-effort: an unresolved head
+  // means the envelope is omitted and the agent falls back to the worker's launch dir.
+  const token = process.env.GITHUB_TOKEN ?? "";
+  let headRef: string | null = null;
+  try {
+    headRef = (await fetchPrHead(pr.repo, pr.number, token))?.headRef ?? null;
+  } catch (err) {
+    console.warn(`[startMerge] ${pr.prKey} head branch fetch: ${err}`);
+  }
+  if (!headRef) {
+    console.warn(`[startMerge] ${pr.prKey} head branch unresolved — merge-agent workspace won't be provisioned`);
+  }
   const { processInstanceKey } = await engine.createInstance({
     processDefinitionId: MERGE_PROCESS_ID,
     variables: {
@@ -414,6 +460,9 @@ export async function startMerge(
       rebaseMax: MAX_REBASE_ROUNDS,
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
+      // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
+      // fix-ci/rebase agents operate on an isolated checkout of the PR head branch.
+      ...repoEnvelopeVars(pr.repo, headRef),
     },
   });
   if (processInstanceKey != null) {

package/db/migrations/018_round_worker.sql

@@ -0,0 +1,9 @@
+-- Identify the servicing worker on the durable history. The c8ctl harness completes each agent
+-- job with an `agent` variable (its profile name, e.g. `senior`), which propagates to the
+-- downstream `pr.persist-round` / `pr.persist-escalation` jobs. Recording it next to the round /
+-- escalation the agent produced lets a human tell *which* worker did the work when reading the
+-- transcript — without cross-referencing the transient `pull_requests.active_worker` lease (which
+-- is cleared once the agent finishes).
+
+ALTER TABLE rounds ADD COLUMN worker TEXT;
+ALTER TABLE escalations ADD COLUMN worker TEXT;

package/e2e/convergence-loop.e2e.ts

@@ -0,0 +1,175 @@
+// End-to-end pilot for @nanobpm/urban-testkit (nano-ide issue #157, slice S3).
+//
+// Boots this whole Urban app in-process against the WASM engine and a virtual clock via
+// `bootTestApp`, then drives its real ADR-0059 OpenAPI operations by `operationId` — the same
+// spec-driven `/app/api/*` surface a browser, a CI relay, or Swagger hit in production. No socket
+// is opened, no wall-clock is waited on, and no GitHub network is touched.
+//
+// Network isolation: the app's GitHub transport (app/github.ts) is forced to `token` mode with no
+// token, so every best-effort GitHub read short-circuits to `null`/idle instead of reaching out.
+// That keeps the pilot hermetic and deterministic in CI.
+//
+// Run with `npm run e2e` (a dedicated node:test invocation, kept out of the fast unit `npm test`).
+
+import assert from "node:assert/strict";
+import { fileURLToPath } from "node:url";
+import { dirname, join, resolve } from "node:path";
+import { mkdtempSync, rmSync, readFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { after, before, describe, test } from "node:test";
+import { bootTestApp, type TestApp } from "@nanobpm/urban-testkit";
+
+// The app root is this repo's root (one level up from `e2e/`) — where nano.app.json + openapi.yaml
+// + db/migrations + resources/processes live.
+const APP_ROOT = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+
+// Provision the app's SQLite in a throwaway temp dir so the pilot never touches (or leaks into) the
+// repo's real ./app.db, and every run starts from a freshly-migrated, empty schema.
+const DB_DIR = mkdtempSync(join(tmpdir(), "nwf-e2e-"));
+
+// Derive the reconciler's poll interval from the app manifest (its single source of truth) rather
+// than hard-coding it, so this test tracks nano.app.json instead of duplicating the value: a change
+// to `pollMs` there stays correct here. Read the `pull_requests` instanceTracking entry's pollMs.
+interface InstanceTrackingEntry {
+  table: string;
+  pollMs: number;
+}
+interface AppManifest {
+  instanceTracking?: InstanceTrackingEntry[];
+}
+const APP_MANIFEST: AppManifest = JSON.parse(
+  readFileSync(join(APP_ROOT, "nano.app.json"), "utf8"),
+);
+const PR_TRACKING = APP_MANIFEST.instanceTracking?.find((e) => e.table === "pull_requests");
+assert.ok(PR_TRACKING, "nano.app.json declares a pull_requests instanceTracking entry");
+const PR_POLL_MS = PR_TRACKING.pollMs;
+
+// Force the app fully offline. github.ts reads `process.env` directly (not the harness env overlay),
+// so seal the GitHub transport on process.env: `token` mode with no GITHUB_TOKEN means every
+// best-effort GitHub read in submitPr short-circuits to null instead of shelling out to `gh`/fetch.
+const GITHUB_ENV_OVERRIDES: Record<string, string> = {
+  NANO_PR_GITHUB_TRANSPORT: "token",
+  GITHUB_TOKEN: "",
+};
+const savedEnv = new Map<string, string | undefined>();
+
+// The harness `env` overlay drives the runtime's `${NANO_APP_DB_URL}` resolution — provision the
+// app's SQLite in a throwaway temp dir so the pilot never touches (or leaks into) the repo's real
+// ./app.db, and every run starts from a freshly-migrated, empty schema.
+const HARNESS_ENV = {
+  NANO_APP_DB_URL: `file:${join(DB_DIR, "app.db")}`,
+} as const;
+
+describe("nano-workforce e2e (urban-testkit pilot)", () => {
+  let app: TestApp;
+
+  before(async () => {
+    for (const [k, v] of Object.entries(GITHUB_ENV_OVERRIDES)) {
+      savedEnv.set(k, process.env[k]);
+      process.env[k] = v;
+    }
+    app = await bootTestApp(APP_ROOT, { env: HARNESS_ENV });
+    // This app declares an `api` binding, so the spec-driven driver must be present.
+    assert.ok(app.api, "app.api driver should be defined (nano.app.json declares an `api` binding)");
+  });
+
+  after(async () => {
+    await app?.stop();
+    for (const [k, v] of savedEnv) {
+      if (v === undefined) delete process.env[k];
+      else process.env[k] = v;
+    }
+    rmSync(DB_DIR, { recursive: true, force: true });
+  });
+
+  test("drives the blackboard operations round-trip through the OpenAPI driver", async () => {
+    const api = app.api;
+    assert.ok(api);
+
+    // Seed a plan with a capability token — the credential the blackboard operations authorize on.
+    const token = "pilot-blackboard-token";
+    const planKey = "acme/widgets#7";
+    const nowIso = new Date(app.now()).toISOString();
+    await app.db.table("plans", "plan_key").insert({
+      plan_key: planKey,
+      repo: "acme/widgets",
+      issue_number: 7,
+      issue_url: "https://github.com/acme/widgets/issues/7",
+      title: "Pilot plan",
+      status: "planning",
+      task_count: 0,
+      blackboard_token: token,
+      created_at: nowIso,
+      updated_at: nowIso,
+    });
+
+    // POST an entry via the `appendBlackboard` operation (operationId → /app/api/hooks/blackboard).
+    const appended = await api.call<{ id: number; inserted: boolean }>("appendBlackboard", {
+      query: { token },
+      body: { author_task: "t1", kind: "note", body: "hello from the pilot" },
+    });
+    assert.equal(appended.status, 201, "append returns 201 Created");
+    assert.equal(appended.body.inserted, true, "entry was inserted");
+    assert.ok(Number.isFinite(appended.body.id), "append returns a numeric entry id");
+
+    // GET it back via `readBlackboard` — the entry the POST just wrote must be visible.
+    const read = await api.call<{ planKey: string; entries: Array<{ id: number; body: string }> }>(
+      "readBlackboard",
+      { query: { token } },
+    );
+    assert.equal(read.status, 200, "read returns 200 OK");
+    assert.equal(read.body.planKey, planKey, "read is scoped to the seeded plan");
+    assert.equal(read.body.entries.length, 1, "exactly the one appended entry is returned");
+    assert.equal(read.body.entries[0].body, "hello from the pilot", "round-tripped body matches");
+    assert.equal(read.body.entries[0].id, appended.body.id, "read id matches the appended id");
+
+    // An unknown token is a 404 (never leaks which plans exist).
+    const unknown = await api.call("readBlackboard", { query: { token: "nope" } });
+    assert.equal(unknown.status, 404, "an unknown token is a 404, not a leak");
+  });
+
+  test("starts the convergence loop and reconciles its tracking row when terminated", async () => {
+    const api = app.api;
+    assert.ok(api);
+
+    const prKey = "acme/widgets#42";
+    // POST the real production door for starting a review: `startConvergenceLoop`. `convergeOnly`
+    // keeps the run off the merge-loop; the offline env keeps `submitPr`'s best-effort GitHub
+    // enrichment from touching the network.
+    const started = await api.call<{ prKey: string }>("startConvergenceLoop", {
+      body: { pr: prKey, convergeOnly: true },
+    });
+    assert.equal(started.status, 202, "start returns 202 Accepted");
+    assert.equal(started.body.prKey, prKey, "the response echoes the parsed PR key");
+
+    // The operation registered the PR aggregate (instanceTracking table) and started a real engine
+    // instance — synchronously, before any worker ran (we never settled).
+    const prs = app.db.table<{ pr_key: string; status: string; process_key: string | null }>(
+      "pull_requests",
+      "pr_key",
+    );
+    const row = await prs.findOne({ pr_key: prKey });
+    assert.ok(row, "a pull_requests row was registered");
+    assert.equal(row?.status, "converging", "the PR is tracked as actively converging");
+    assert.ok(row?.process_key, "the row carries the engine process-instance key");
+
+    const processInstanceKey = row!.process_key!;
+    const before = await app.engine.searchProcessInstances({
+      processInstanceKeys: [processInstanceKey],
+    });
+    assert.equal(before.length, 1, "the engine has exactly one instance for this PR");
+
+    // Terminate the instance out-of-band (the class of event the reconciler exists to catch — a
+    // PR merged or cancelled independently of the loop). The row is still `converging` until a poll.
+    await app.engine.cancelInstance({ processInstanceKey });
+    const stillActive = await prs.findOne({ pr_key: prKey });
+    assert.equal(stillActive?.status, "converging", "row not yet reconciled before any poll fires");
+
+    // Advance past the instanceTracking pollMs (derived from nano.app.json above, plus a margin):
+    // the reconciler observes TERMINATED and applies the manifest `onTerminated.set` → status
+    // `abandoned`, escalation pointers cleared.
+    await app.advanceTime(PR_POLL_MS + 1000);
+    const reconciled = await prs.findOne({ pr_key: prKey });
+    assert.equal(reconciled?.status, "abandoned", "reconciler abandoned the terminated PR's row");
+  });
+});

package/nano.app.json

@@ -87,6 +87,10 @@
       "taskType": "pr.mark-merged",
       "handler": "workers/mark-merged/worker.ts"
     },
+    {
+      "taskType": "pr.record-dependency",
+      "handler": "workers/record-dependency/worker.ts"
+    },
     {
       "taskType": "pr.record-plan",
       "handler": "workers/record-plan/worker.ts"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.43.0",
+  "version": "0.44.1",
   "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",
@@ -41,14 +41,16 @@
     "layout:check": "node --experimental-strip-types scripts/layout-bpmn.ts --check",
     "dev": "urban dev",
     "test": "node --experimental-strip-types --test",
-    "lint": "biome check app operations workers pages components scripts main.ts",
-    "lint:fix": "biome check --write app operations workers pages components scripts main.ts"
+    "e2e": "node --experimental-strip-types --test \"e2e/**/*.e2e.ts\"",
+    "lint": "biome check app operations workers pages components scripts e2e main.ts",
+    "lint:fix": "biome check --write app operations workers pages components scripts e2e main.ts"
   },
   "dependencies": {
     "@nanobpm/urban": "^0.42.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.11",
+    "@nanobpm/urban-testkit": "^0.3.0",
     "@semantic-release/changelog": "^6.0.3",
     "@semantic-release/git": "^10.0.1",
     "@semantic-release/npm": "^13.1.5",

package/pages/home.page.json

@@ -109,6 +109,7 @@
               "columns": [
                 { "field": "round_no", "header": "#" },
                 { "field": "status", "header": "Result" },
+                { "field": "worker", "header": "Worker" },
                 { "field": "summary", "header": "Summary" }
               ],
               "lazyField": { "field": "transcript", "label": "Transcript", "lazy": true }
@@ -123,6 +124,7 @@
               "columns": [
                 { "field": "round_no", "header": "#" },
                 { "field": "kind", "header": "Kind" },
+                { "field": "worker", "header": "Worker" },
                 { "field": "question", "header": "Question" },
                 { "field": "status", "header": "Status" },
                 { "field": "answer", "header": "Answer" }

package/prompts/fix-ci.md

@@ -16,6 +16,15 @@ protocol with a status URL is appended below: **before you push the fix, curl th
 `-fsS`) and stop immediately if the check **fails** or reports `"abandoned": true`. Re-check right
 before the push.
 
+## Workspace (host mode) — read this first
+
+When the worker harness (e.g. `c8ctl nano work`) provisions a workspace, your **current
+working directory is a fresh, isolated clone of the repo checked out on the PR's head
+branch** — exposed via `AGENT_WORKSPACE`, `AGENT_REPO_URL`, `AGENT_REPO_BRANCH`, `AGENT_REPO_REF`.
+When it does, **work only inside `cwd`**, do **not** re-clone, `cd` elsewhere, or add a
+`git worktree`, and do not touch global/host state — other jobs get their own clones. If
+`AGENT_WORKSPACE` is **unset** (no provisioning), check out the PR head branch yourself.
+
 ## Job input (`job.variables`)
 
 | var        | meaning                                                            |
@@ -32,7 +41,8 @@ the PR's checks yourself (`gh pr checks`, `gh run view`).
 
 ## What to do
 
-1. Check out the PR's head branch (it already exists on the remote).
+1. Check out the PR's head branch (already provisioned as your `cwd` in host mode; else it
+   exists on the remote).
 2. For each failing check, read its logs to find the **root cause** — a real
    failure (a bug, a broken test, a lint/type error, a missing file). Do **not**
    paper over it (no `--no-verify`, no disabling the check, no `it.skip`, no
@@ -56,9 +66,20 @@ the PR's checks yourself (`gh pr checks`, `gh run view`).
 Return a structured result:
 
 - `status: "fixed"` — you pushed a fix you believe makes the failing checks pass.
-- `status: "blocked"` — you could **not** fix it (e.g. the failure needs a human
-  decision, a secret, or an upstream change). Set `question` to a concise,
-  specific description of what is blocking and what a human must decide.
+- `status: "waiting-on-pr"` — the PR cannot merge yet because **another PR must land
+  first**, and this is an ordering constraint, not a defect: e.g. the failing check
+  is a required linked-issue / "closes #N" gate that a sibling PR will satisfy, the
+  PR is stacked on a base PR that has not merged, or the PR body / an issue it
+  references says it depends on another PR. This is a **wait, not an escalation** — do
+  **not** ask a human to babysit it. Set `dependsOn` to the PR(s) that must merge
+  first, as `owner/repo#N` refs (or PR URLs), separated by commas or spaces. The
+  process records the dependency and automatically re-attempts the merge once every
+  named PR has landed.
+- `status: "blocked"` — you could **not** fix it and it genuinely needs a human
+  **decision** (a secret, an upstream change, or a judgement call). Set `question` to a
+  concise, specific description of what is blocking and what a human must decide.
+  Reserve this for a real decision — if the PR is merely waiting on another PR, use
+  `waiting-on-pr` instead so no human is pulled in.
 
 Never report `fixed` unless you actually pushed a change. If nothing was wrong on
 the branch (the failure was transient infrastructure), say so in `summary` and

package/prompts/rebase.md

@@ -17,6 +17,15 @@ with a status URL is appended below: **before you push the rebased branch, curl
 `-fsS`) and stop immediately if the check **fails** or reports `"abandoned": true`. Re-check right
 before the push.
 
+## Workspace (host mode) — read this first
+
+When the worker harness (e.g. `c8ctl nano work`) provisions a workspace, your **current
+working directory is a fresh, isolated clone of the repo checked out on the PR's head
+branch** — exposed via `AGENT_WORKSPACE`, `AGENT_REPO_URL`, `AGENT_REPO_BRANCH`, `AGENT_REPO_REF`.
+When it does, **work only inside `cwd`**, do **not** re-clone, `cd` elsewhere, or add a
+`git worktree`, and do not touch global/host state — other jobs get their own clones. If
+`AGENT_WORKSPACE` is **unset** (no provisioning), check out the PR head branch yourself.
+
 ## Job input (`job.variables`)
 
 | var           | meaning                                                          |
@@ -29,7 +38,8 @@ before the push.
 
 ## What to do
 
-1. Check out the PR's head branch (it already exists on the remote) and identify
+1. Check out the PR's head branch (already provisioned as your `cwd` in host mode; else it
+   already exists on the remote) and identify
    the base branch (`gh pr view <prNumber> --repo <repo> --json baseRefName`).
 2. Update the branch onto the current base. Prefer a **rebase**
    (`git fetch origin && git rebase origin/<base>`); if the repo's history policy
@@ -67,10 +77,20 @@ Return a structured result:
 - `status: "rebased"` — the branch tip now contains the latest base: you resolved
   any conflicts mechanically and pushed, **or** it was already up to date. The
   process will re-attempt the merge.
+- `status: "waiting-on-pr"` — the PR cannot merge yet because **another PR must land
+  first**, and this is an ordering constraint, not a conflict you can resolve: e.g.
+  the branch is stacked on a base PR that has not merged, or the PR body / an issue
+  it references says it depends on another PR that must close a blocking issue first.
+  This is a **wait, not an escalation** — do **not** ask a human to babysit it. Set
+  `dependsOn` to the PR(s) that must merge first, as `owner/repo#N` refs (or PR URLs),
+  separated by commas or spaces. The process records the dependency and automatically
+  re-attempts the merge once every named PR has landed.
 - `status: "blocked"` — you could **not** resolve it mechanically (a genuine
   semantic conflict where two changes contradict and a human must decide which
   behaviour wins, or the branch is un-rebaseable). Set `question` to a concise,
   specific description of the conflicting intent and the decision a human must make.
+  Reserve this for a real decision — if the PR is merely waiting on another PR to land
+  first, use `waiting-on-pr` instead so no human is pulled in.
 
 Report `rebased` when the branch tip now contains the latest base — either
 because you pushed a resolved update, or because it was **already up to date**

package/prompts/review-round.md

@@ -31,7 +31,7 @@ cancel can land anytime.
 The worker harness (e.g. `c8ctl nano work`) has **already provisioned an isolated,
 per-job workspace for you**: your **current working directory is a fresh clone of
 the repo, checked out on the PR's head branch**. The harness exposes it via the
-`AGENT_WORKSPACE`, `REPO_URL`, `REPO_BRANCH` and `REPO_REF` environment variables,
+`AGENT_WORKSPACE`, `AGENT_REPO_URL`, `AGENT_REPO_BRANCH` and `AGENT_REPO_REF` environment variables,
 and it **reaps that workspace after the job ends**.
 
 Because several agents may run on the same host at once:

package/resources/processes/merge-loop.bpmn

@@ -76,6 +76,7 @@
           <nano:extend name="status" type="string" />
           <nano:extend name="summary" type="string" optional="true" />
           <nano:extend name="question" type="string" optional="true" />
+          <nano:extend name="dependsOn" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="RebaseIn" name="Rebase — input">
           <nano:extend name="prKey" type="string" />
@@ -88,6 +89,11 @@
           <nano:extend name="status" type="string" />
           <nano:extend name="summary" type="string" optional="true" />
           <nano:extend name="question" type="string" optional="true" />
+          <nano:extend name="dependsOn" type="string" optional="true" />
+        </nano:shape>
+        <nano:shape id="RecordDepIn" name="Record discovered dependency — input">
+          <nano:extend name="prKey" type="string" />
+          <nano:extend name="dependsOn" type="string" optional="true" />
         </nano:shape>
         <nano:shape id="MergeEscalationAnswered" name="escalation-answered message payload">
           <nano:extend name="answer" type="string" />
@@ -100,6 +106,7 @@
     </bpmn:startEvent>
     <bpmn:intermediateCatchEvent id="wait-deps" name="Wait: dependencies merged">
       <bpmn:incoming>f_m_start</bpmn:incoming>
+      <bpmn:incoming>f_dep_rewait</bpmn:incoming>
       <bpmn:outgoing>f_m_deps</bpmn:outgoing>
       <bpmn:messageEventDefinition id="med_depsCleared" messageRef="Message_depsCleared" />
     </bpmn:intermediateCatchEvent>
@@ -237,6 +244,7 @@
     <bpmn:exclusiveGateway id="gw-ci-result" name="fixed?" default="f_ci_blocked">
       <bpmn:incoming>f_ci_done</bpmn:incoming>
       <bpmn:outgoing>f_ci_fixed</bpmn:outgoing>
+      <bpmn:outgoing>f_ci_wait</bpmn:outgoing>
       <bpmn:outgoing>f_ci_blocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
     <bpmn:exclusiveGateway id="gw-rebase" name="auto-rebase?" default="f_reb_giveup">
@@ -265,8 +273,20 @@
     <bpmn:exclusiveGateway id="gw-rebase-result" name="rebased?" default="f_reb_blocked">
       <bpmn:incoming>f_reb_done</bpmn:incoming>
       <bpmn:outgoing>f_reb_rebased</bpmn:outgoing>
+      <bpmn:outgoing>f_reb_wait</bpmn:outgoing>
       <bpmn:outgoing>f_reb_blocked</bpmn:outgoing>
     </bpmn:exclusiveGateway>
+    <bpmn:serviceTask id="record-merge-dep" name="Wait on another PR">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.record-dependency" />
+        <zeebe:properties>
+          <zeebe:property name="io.nanobpm.dataEnvelope.in" value="RecordDepIn" />
+        </zeebe:properties>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_ci_wait</bpmn:incoming>
+      <bpmn:incoming>f_reb_wait</bpmn:incoming>
+      <bpmn:outgoing>f_dep_rewait</bpmn:outgoing>
+    </bpmn:serviceTask>
     <bpmn:sequenceFlow id="f_m_start" sourceRef="MergeStart" targetRef="wait-deps" />
     <bpmn:sequenceFlow id="f_m_deps" sourceRef="wait-deps" targetRef="arm-merge" />
     <bpmn:sequenceFlow id="f_m_arm" sourceRef="arm-merge" targetRef="wait-mergeable" />
@@ -290,6 +310,9 @@
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "fixed"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_ci_blocked" name="could not fix" sourceRef="gw-ci-result" targetRef="merge-esc-attempt" />
+    <bpmn:sequenceFlow id="f_ci_wait" name="waits on another PR" sourceRef="gw-ci-result" targetRef="record-merge-dep">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "waiting-on-pr"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_reb_go" name="within budget" sourceRef="gw-rebase" targetRef="rebase">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=rebaseRound &lt; rebaseMax</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -299,6 +322,10 @@
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "rebased"</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="f_reb_blocked" name="could not resolve" sourceRef="gw-rebase-result" targetRef="merge-esc-attempt" />
+    <bpmn:sequenceFlow id="f_reb_wait" name="waits on another PR" sourceRef="gw-rebase-result" targetRef="record-merge-dep">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=status = "waiting-on-pr"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_dep_rewait" sourceRef="record-merge-dep" targetRef="wait-deps" />
     <bpmn:sequenceFlow id="f_m_attempt" sourceRef="attempt-merge" targetRef="gw-merge" />
     <bpmn:sequenceFlow id="f_m_gMerged" name="merged" sourceRef="gw-merge" targetRef="mark-merged">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=mergeStatus = "merged"</bpmn:conditionExpression>
@@ -327,7 +354,7 @@
       <bpmndi:BPMNShape id="BPMNShape_wait-deps" bpmnElement="wait-deps">
         <dc:Bounds x="216" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="190" y="143" width="88" height="42" />
+          <dc:Bounds x="190" y="55" width="88" height="42" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_arm-merge" bpmnElement="arm-merge">
@@ -415,14 +442,17 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_rebase" bpmnElement="rebase">
-        <dc:Bounds x="1038" y="1040" width="100" height="80" />
+        <dc:Bounds x="1038" y="1200" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_gw-rebase-result" bpmnElement="gw-rebase-result" isMarkerVisible="true">
-        <dc:Bounds x="1238" y="1055" width="50" height="50" />
+        <dc:Bounds x="1238" y="1215" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1233" y="1036" width="60" height="14" />
+          <dc:Bounds x="1173" y="1233" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record-merge-dep" bpmnElement="record-merge-dep">
+        <dc:Bounds x="1388" y="1040" width="100" height="80" />
+      </bpmndi:BPMNShape>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_start" bpmnElement="f_m_start">
         <di:waypoint x="116" y="120" />
         <di:waypoint x="216" y="120" />
@@ -473,7 +503,7 @@
         <di:waypoint x="1438" y="920" />
         <di:waypoint x="1438" y="640" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1319" y="898" width="89" height="14" />
+          <dc:Bounds x="1319" y="928" width="89" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_giveup" bpmnElement="f_reb_giveup">
@@ -485,11 +515,12 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_blocked" bpmnElement="f_reb_blocked">
-        <di:waypoint x="1288" y="1080" />
-        <di:waypoint x="1438" y="1080" />
+        <di:waypoint x="1263" y="1215" />
+        <di:waypoint x="1263" y="1020" />
+        <di:waypoint x="1438" y="1020" />
         <di:waypoint x="1438" y="640" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1331" y="1047" width="64" height="28" />
+          <dc:Bounds x="1319" y="987" width="64" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_eg_landed" bpmnElement="f_eg_landed">
@@ -552,17 +583,33 @@
           <dc:Bounds x="893" y="839" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_ci_wait" bpmnElement="f_ci_wait">
+        <di:waypoint x="1288" y="920" />
+        <di:waypoint x="1438" y="920" />
+        <di:waypoint x="1438" y="1040" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1326" y="887" width="75" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_go" bpmnElement="f_reb_go">
         <di:waypoint x="913" y="280" />
         <di:waypoint x="933" y="280" />
         <di:waypoint x="933" y="305" />
         <di:waypoint x="1158" y="305" />
-        <di:waypoint x="1158" y="1080" />
-        <di:waypoint x="1138" y="1080" />
+        <di:waypoint x="1158" y="1240" />
+        <di:waypoint x="1138" y="1240" />
         <bpmndi:BPMNLabel>
           <dc:Bounds x="1101" y="310" width="49" height="28" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_reb_wait" bpmnElement="f_reb_wait">
+        <di:waypoint x="1263" y="1215" />
+        <di:waypoint x="1263" y="1080" />
+        <di:waypoint x="1388" y="1080" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1288" y="1047" width="75" height="28" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_gQueued" bpmnElement="f_m_gQueued">
         <di:waypoint x="1088" y="145" />
         <di:waypoint x="1088" y="280" />
@@ -593,12 +640,12 @@
         <di:waypoint x="1238" y="920" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_done" bpmnElement="f_reb_done">
-        <di:waypoint x="1138" y="1100" />
-        <di:waypoint x="1158" y="1100" />
-        <di:waypoint x="1158" y="1125" />
-        <di:waypoint x="1238" y="1125" />
-        <di:waypoint x="1263" y="1125" />
-        <di:waypoint x="1263" y="1105" />
+        <di:waypoint x="1138" y="1260" />
+        <di:waypoint x="1158" y="1260" />
+        <di:waypoint x="1158" y="1285" />
+        <di:waypoint x="1238" y="1285" />
+        <di:waypoint x="1263" y="1285" />
+        <di:waypoint x="1263" y="1265" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_ci_fixed" bpmnElement="f_ci_fixed">
         <di:waypoint x="1263" y="945" />
@@ -610,14 +657,20 @@
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_reb_rebased" bpmnElement="f_reb_rebased">
-        <di:waypoint x="1263" y="1105" />
-        <di:waypoint x="1263" y="1140" />
-        <di:waypoint x="402" y="1140" />
+        <di:waypoint x="1263" y="1265" />
+        <di:waypoint x="1263" y="1300" />
+        <di:waypoint x="402" y="1300" />
         <di:waypoint x="402" y="160" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="806" y="1118" width="53" height="14" />
+          <dc:Bounds x="806" y="1278" width="53" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_dep_rewait" bpmnElement="f_dep_rewait">
+        <di:waypoint x="1438" y="1120" />
+        <di:waypoint x="1438" y="1320" />
+        <di:waypoint x="234" y="1320" />
+        <di:waypoint x="234" y="138" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_m_evicted" bpmnElement="f_m_evicted">
         <di:waypoint x="1438" y="458" />
         <di:waypoint x="1438" y="478" />

package/tsconfig.json

@@ -45,7 +45,8 @@
     "src/**/*.ts",
     "scripts/**/*.ts",
     "actions/**/*.ts",
-    "test/**/*.ts"
+    "test/**/*.ts",
+    "e2e/**/*.ts"
   ],
   "exclude": [
     "node_modules",

package/workers/persist-escalation/worker.ts

@@ -44,6 +44,13 @@ function transcriptOf(vars: Record<string, unknown>): string | null {
   return typeof env?.output === "string" ? env.output : null;
 }
 
+// The c8ctl harness completes each agent job with an `agent` variable (its profile name), which
+// propagates here. Record it on the round/escalation so a human can identify the servicing worker
+// from the durable history. Reuses the `nonBlank` domain rule (blank/absent -> NULL column).
+function workerOf(vars: Record<string, unknown>): string | undefined {
+  return nonBlank(vars.agent);
+}
+
 // Synthesize a concrete, answerable question when the agent left one blank. A blank question is
 // almost always a *no-result* round: a prompt-less agent that never wrote its result file, so
 // `status` is empty and `gw-status` falls through its default `f_escalate` arm (the empty
@@ -72,6 +79,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
   const rawStatus = nonBlank(job.variables.status);
   const status = rawStatus ?? "needs_input";
   const transcript = transcriptOf(job.variables);
+  const worker = workerOf(job.variables);
   // A blank question must never open an unanswerable escalation. Every legitimate arm sets a
   // concrete question — the agent contract requires one for needs_input/blocked, and the
   // max-rounds + review-timeout arms set a literal via the model. When one is still missing
@@ -110,6 +118,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
       status,
       summary,
       transcript,
+      worker,
       started_at: now,
       ended_at: now,
     });
@@ -120,6 +129,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
     kind,
     question,
     transcript,
+    worker,
     status: "open",
     asked_at: now,
   });

package/workers/persist-round/worker.ts

@@ -34,6 +34,14 @@ function transcriptOf(vars: Record<string, unknown>): string | null {
   return typeof env?.output === "string" ? env.output : null;
 }
 
+// The c8ctl harness completes each agent job with an `agent` variable (its profile name), which
+// propagates here. Record it on the round so a human can identify the servicing worker from the
+// durable history. Undefined (blank/absent) leaves the nullable `worker` column NULL.
+function workerOf(vars: Record<string, unknown>): string | undefined {
+  const v = vars.agent;
+  return typeof v === "string" && v.trim() !== "" ? v.trim() : undefined;
+}
+
 const handler: AppJobHandler<In> = async (job, app) => {
   // This worker is the "addressed"/"waiting" path, so `status` resolves to one of those
   // domain values. `summary` is left undefined when absent: the write boundary omits it so the
@@ -66,6 +74,7 @@ const handler: AppJobHandler<In> = async (job, app) => {
     status,
     summary,
     transcript: transcriptOf(job.variables),
+    worker: workerOf(job.variables),
     started_at: now,
     ended_at: now,
   });

package/workers/record-dependency/worker.test.ts

@@ -0,0 +1,116 @@
+// pr.record-dependency: a merge-stage agent that discovers "this PR must wait for another PR to
+// merge first" turns that into a durable dependency wait (parking the PR back in `waiting_deps`)
+// instead of a human escalation — the wait, not the escalation, is the correct outcome.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import handler from "./worker.ts";
+
+interface DepRow {
+  pr_key: string;
+  depends_on_key: string;
+  created_at: string;
+}
+
+function fakeApp(seedDeps: DepRow[] = []) {
+  const logs: { level: string; msg: string }[] = [];
+  const stores: Record<string, Record<string, unknown>[]> = {
+    pr_dependencies: seedDeps as unknown as Record<string, unknown>[],
+    pull_requests: [{ pr_key: "o/r#1", status: "waiting_merge" }],
+  };
+  return {
+    app: {
+      data: {
+        table(name: string, key: string) {
+          const store = (stores[name] ??= []);
+          return {
+            get: (k: unknown) => Promise.resolve(store.find((r) => r[key] === k)),
+            find: (q: Record<string, unknown>) =>
+              Promise.resolve(
+                store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v)),
+              ),
+            insert: (row: Record<string, unknown>) => {
+              store.push(row);
+              return Promise.resolve(store.length);
+            },
+            update: (k: unknown, patch: Record<string, unknown>) => {
+              const row = store.find((r) => r[key] === k);
+              if (row) Object.assign(row, patch);
+              return Promise.resolve(row);
+            },
+            delete: (k: unknown) => {
+              for (let i = store.length - 1; i >= 0; i--) if (store[i][key] === k) store.splice(i, 1);
+              return Promise.resolve(undefined);
+            },
+          };
+        },
+      },
+      log: (level: string, msg: string) => logs.push({ level, msg }),
+      engine: {},
+      // biome-ignore lint/suspicious/noExplicitAny: minimal test double for AppContext
+    } as any,
+    stores,
+    logs,
+  };
+}
+
+const job = (variables: Record<string, unknown>) => ({ variables }) as never;
+
+test("records a discovered dependency from a string ref and parks the PR in waiting_deps", async () => {
+  const { app, stores } = fakeApp();
+  await handler(job({ prKey: "o/r#1", dependsOn: "o/r#2" }), app);
+
+  assertEquals(stores.pr_dependencies.length, 1);
+  assertEquals(stores.pr_dependencies[0].pr_key, "o/r#1");
+  assertEquals(stores.pr_dependencies[0].depends_on_key, "o/r#2");
+  assertEquals(stores.pull_requests[0].status, "waiting_deps");
+});
+
+test("parses several refs (commas/spaces/URLs), dedupes, and never waits on itself", async () => {
+  const { app, stores } = fakeApp();
+  await handler(
+    job({
+      prKey: "o/r#1",
+      dependsOn: "o/r#2, o/r#2 https://github.com/o/r/pull/3 o/r#1",
+    }),
+    app,
+  );
+
+  const keys = stores.pr_dependencies.map((d) => d.depends_on_key).sort();
+  assertEquals(keys, ["o/r#2", "o/r#3"]); // #2 deduped, self #1 dropped
+  assertEquals(stores.pull_requests[0].status, "waiting_deps");
+});
+
+test("appends to existing edges without wiping them and skips already-recorded ones", async () => {
+  const { app, stores } = fakeApp([
+    { pr_key: "o/r#1", depends_on_key: "o/r#9", created_at: "t0" },
+  ]);
+  await handler(job({ prKey: "o/r#1", dependsOn: ["o/r#9", "o/r#2"] }), app);
+
+  const keys = stores.pr_dependencies.map((d) => d.depends_on_key).sort();
+  assertEquals(keys, ["o/r#2", "o/r#9"]); // pre-existing #9 preserved, only #2 added
+});
+
+test("no parseable ref still parks in waiting_deps and logs the miswiring loudly", async () => {
+  const { app, stores, logs } = fakeApp();
+  await handler(job({ prKey: "o/r#1", dependsOn: "not-a-pr" }), app);
+
+  assertEquals(stores.pr_dependencies.length, 0);
+  assertEquals(stores.pull_requests[0].status, "waiting_deps");
+  assertEquals(logs.some((l) => l.level === "error"), true);
+});
+
+test("heals a missing pull_requests parent row before parking so the merge poller can watch it", async () => {
+  const { app, stores } = fakeApp();
+  stores.pull_requests.length = 0; // engine/app.db desync: no parent row for o/r#1
+
+  await handler(job({ prKey: "o/r#1", dependsOn: "o/r#2" }), app);
+
+  // ensurePr reconstructed the row, and the subsequent update landed on it (not a silent no-op).
+  assertEquals(stores.pull_requests.length, 1);
+  const healed = stores.pull_requests[0];
+  assertEquals(healed.pr_key, "o/r#1");
+  assertEquals(healed.repo, "o/r");
+  assertEquals(healed.number, 1);
+  assertEquals(healed.status, "waiting_deps");
+  assertEquals(stores.pr_dependencies.length, 1);
+});

package/workers/record-dependency/worker.ts

@@ -0,0 +1,109 @@
+// pr.record-dependency — a merge-stage agent discovered that this PR cannot land until ANOTHER
+// PR merges first (e.g. a stacked base PR must land, or a sibling PR closes an issue this one
+// requires). That is a WAIT, not a human escalation: record the discovered edge(s) in the
+// `pr_dependencies` DAG and park the PR back in `waiting_deps` so the merge poller's dependency
+// pass (`pollMerges` block 1) advances it — publishing `deps-cleared` — once every named PR has
+// merged. The process re-enters its existing `wait-deps` catch, so no human has to babysit an
+// ordering constraint the machinery already knows how to satisfy.
+//
+// `dependsOn` is whatever the agent returned (see prompts/fix-ci.md, prompts/rebase.md): a
+// string of one or more `owner/repo#N` refs (or PR URLs) separated by commas/whitespace/newlines,
+// or an array of such tokens. We parse each robustly (reusing `parsePr`), drop self-references and
+// duplicates, and insert missing edges idempotently — a worker retry never double-inserts, and an
+// already-recorded edge is a no-op.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { ensurePr, parsePr } from "../../app/service.ts";
+
+interface In extends Record<string, unknown> {
+  prKey: string;
+  dependsOn?: unknown;
+}
+
+interface DependencyRow {
+  pr_key: string;
+  depends_on_key: string;
+  created_at: string;
+}
+
+/** Normalize the agent's `dependsOn` into a de-duplicated list of `owner/repo#N` keys.
+ * Accepts a string (split on commas/whitespace/newlines) or an array of such tokens; unparseable
+ * tokens are ignored, mirroring `parseDependsOn`'s tolerance for the `Depends-on:` PR-body line. */
+function parseDependsOn(raw: unknown): string[] {
+  const tokens: string[] = [];
+  if (typeof raw === "string") {
+    tokens.push(...raw.split(/[,\s]+/));
+  } else if (Array.isArray(raw)) {
+    for (const item of raw) {
+      if (typeof item === "string") tokens.push(...item.split(/[,\s]+/));
+    }
+  }
+  const out = new Set<string>();
+  for (const tok of tokens) {
+    const parsed = parsePr(tok);
+    if (parsed) out.add(parsed.prKey);
+  }
+  return [...out];
+}
+
+const handler: AppJobHandler<In> = async (job, app) => {
+  const prKey = job.variables.prKey;
+  const depKeys = parseDependsOn(job.variables.dependsOn);
+  const ts = new Date().toISOString();
+
+  const depTable = app.data.table<DependencyRow>("pr_dependencies", "pr_key");
+
+  // Append the discovered edges to whatever the plan DAG already declared — never wipe the set
+  // (a `registerDependencies`-style replace would drop still-relevant sibling ordering). Dedupe
+  // against existing rows so this is safe to retry.
+  const existing = await depTable.find({ pr_key: prKey });
+  const have = new Set(existing.map((d) => d.depends_on_key));
+  let recorded = 0;
+  for (const depKey of depKeys) {
+    if (depKey === prKey || have.has(depKey)) continue; // never wait on self; skip known edges
+    await depTable.insert({ pr_key: prKey, depends_on_key: depKey, created_at: ts });
+    have.add(depKey);
+    recorded += 1;
+  }
+
+  if (depKeys.length === 0) {
+    // The agent signalled "waiting-on-pr" but named no parseable PR. Whether this actually strands
+    // the PR depends on the existing DAG: with no other edges the poller clears it immediately (an
+    // empty dep set trivially "all merged"); if prior edges already exist it will keep waiting on
+    // those. Either way the miswiring — a "waiting-on-pr" signal with no parseable ref — is a
+    // defect worth logging loudly.
+    const clause =
+      have.size === 0
+        ? "it will clear immediately (no other dependencies recorded)"
+        : `it still has ${have.size} previously-recorded dependency edge(s) to wait on`;
+    app.log(
+      "error",
+      `record-dependency: ${prKey} reported waiting-on-pr but no parseable dependsOn ref; ` +
+        `${clause}. Raw: ${JSON.stringify(job.variables.dependsOn)}`,
+    );
+  }
+
+  // Heal a missing FK parent (engine/app.db desync) before updating `pull_requests`; otherwise the
+  // update silently no-ops and the instance re-enters `wait-deps` with no row for the merge poller
+  // to watch — wedging the merge loop. Mirrors persist-round's heal; repo/number are derived from
+  // the canonical `owner/repo#N` prKey since the RecordDepIn envelope carries only prKey/dependsOn.
+  const parsed = parsePr(prKey);
+  if (parsed) {
+    await ensurePr(app.data, { prKey, repo: parsed.repo, number: parsed.number, url: parsed.url });
+  }
+
+  // Park the PR back in the merge-stage dependency wait so `pollMerges` block 1 watches it.
+  await app.data.table("pull_requests", "pr_key").update(prKey, {
+    status: "waiting_deps",
+    updated_at: ts,
+  });
+
+  app.log("info", `record-dependency: ${prKey} waiting on ${depKeys.length} PR(s)`, {
+    prKey,
+    dependsOn: depKeys,
+    recorded,
+  });
+
+  return {};
+};
+
+export default handler;