@nanobpm/nano-workforce 0.42.0 → 0.44.0

package/operations/startConvergenceLoop.ts

@@ -5,28 +5,40 @@
 //
 // The request body is FLAT (`{ pr | url, dependsOn?, maxRounds?, convergeOnly? }`), not wrapped in a
 // `variables` envelope: this is a purpose-built operation, not a generic engine "start process" call,
-// so it does not leak the engine's variable-map concept to callers. The runtime validates the body
-// against openapi.yaml; this delegate keeps the PR-parse guard because the reference format
-// (owner/repo#123 or a URL) is app logic, not something the JSON schema can express — an unparseable
-// reference is a 400.
+// so it does not leak the engine's variable-map concept to callers. The body is a `oneOf` — EXACTLY
+// ONE of `pr` or `url` — so the runtime rejects an empty or ambiguous target at the edge (a 400 that
+// names the allowed shapes); this delegate no longer coalesces `pr ?? url`, it just narrows the
+// validated variant. It keeps the PR-parse guard because the reference FORMAT (owner/repo#123 or a
+// URL) is app logic the JSON schema can't express — an unparseable reference is a 400.
 
 import { clampRounds, MAX_ROUNDS, parsePr, submitPr } from "../app/service.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startConvergenceLoop", async ({ body }, app) => {
-  const b = body ?? {};
-  const raw = String(b.pr ?? b.url ?? "").trim();
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500 from `in`.
+  if (!body || typeof body !== "object") {
+    app.log.warn("start-convergence rejected: missing request body");
+    return { status: 400, body: { error: "request body is required (owner/repo#123 or a PR URL)" } };
+  }
+  const raw = ("pr" in body ? body.pr : body.url).trim();
   const parsed = parsePr(raw);
   if (!parsed) {
+    app.log.warn("start-convergence rejected: unparseable PR reference", { raw });
     return { status: 400, body: { error: "could not parse PR (use owner/repo#123 or a PR URL)" } };
   }
-  const dependsOn = Array.isArray(b.dependsOn) ? b.dependsOn.map((d) => String(d)) : [];
-  const maxRounds = clampRounds(b.maxRounds, MAX_ROUNDS);
+  const dependsOn = body.dependsOn ?? [];
+  const maxRounds = clampRounds(body.maxRounds, MAX_ROUNDS);
   // Per-request review-only override: when true the PR stops at `converged` and is never
   // handed to the merge-loop, regardless of the global NANO_PR_AUTO_MERGE default.
-  const convergeOnly = b.convergeOnly === true;
-  return {
-    status: 202,
-    body: await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly),
-  };
+  const convergeOnly = body.convergeOnly === true;
+  const result = await submitPr(app.data, app.engine, parsed, dependsOn, maxRounds, convergeOnly);
+  app.log.info("convergence loop started", {
+    prKey: parsed.prKey,
+    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+    dependsOn: dependsOn.length,
+    maxRounds,
+    convergeOnly,
+  });
+  return { status: 202, body: result };
 });

package/operations/startPlanFanout.ts

@@ -6,17 +6,30 @@
 // short-circuits.
 //
 // The request body is FLAT (`{ issue | url }`), not wrapped in a `variables` envelope — this is a
-// purpose-built operation, not a generic engine "start process" call.
+// purpose-built operation, not a generic engine "start process" call. The body is a `oneOf` — EXACTLY
+// ONE of `issue` or `url` — so an empty or ambiguous target is a 400 at the edge; this delegate just
+// narrows the validated variant and keeps the issue-FORMAT parse guard (schema can't express it).
 
 import { parseIssue, startPlan } from "../app/plan.ts";
 import { defineOperation } from "../nano-generated/operations.ts";
 
 export default defineOperation("startPlanFanout", async ({ body }, app) => {
-  const b = body ?? {};
-  const raw = String(b.issue ?? b.url ?? "").trim();
+  // The runtime validates a well-formed body against openapi.yaml, but a directly-invoked delegate
+  // (or a missing body) leaves `body` undefined — guard so that becomes a 400, not a 500 from `in`.
+  if (!body || typeof body !== "object") {
+    app.log.warn("start-plan rejected: missing request body");
+    return { status: 400, body: { error: "request body is required (owner/repo#123 or an issue URL)" } };
+  }
+  const raw = ("issue" in body ? body.issue : body.url).trim();
   const parsed = parseIssue(raw);
   if (!parsed) {
+    app.log.warn("start-plan rejected: unparseable issue reference", { raw });
     return { status: 400, body: { error: "could not parse issue (use owner/repo#123 or an issue URL)" } };
   }
-  return { status: 202, body: await startPlan(app.data, app.engine, parsed) };
+  const result = await startPlan(app.data, app.engine, parsed);
+  app.log.info("plan fan-out started", {
+    planKey: parsed.planKey,
+    alreadyRunning: "alreadyRunning" in result && result.alreadyRunning === true,
+  });
+  return { status: 202, body: result };
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.42.0",
+  "version": "0.44.0",
   "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",

package/prompts/fix-ci.md

@@ -56,9 +56,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

@@ -67,10 +67,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/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/test/log.ts

@@ -0,0 +1,12 @@
+// A no-op `Logger` for test doubles. The runtime injects `app.log` into every operation delegate
+// and worker handler, but the in-memory `app` fakes the suite builds don't carry one — so a
+// delegate that logs on a covered path would throw on `app.log.info(...)`. `createLogger` (exported
+// from urban's runtime barrel since 0.42.0) builds a spec-correct Logger over a discarding sink, so
+// tests exercise the logging code paths without asserting on them and stay correct if the Logger
+// interface grows. Spread into the fake `app`: `{ ...data, log: noopLog() } as unknown as AppApi`.
+import { createLogger, type Logger } from "@nanobpm/urban/runtime";
+
+/** A `Logger` that silently discards every record (and whose `child()` does the same). */
+export function noopLog(): Logger {
+  return createLogger(() => {});
+}

package/workers/finalize/worker.test.ts

@@ -6,6 +6,7 @@
 // AND the request did not force convergence-only.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 import { MERGE_PROCESS_ID } from "../../app/service.ts";
 
@@ -48,7 +49,7 @@ function fakeApp() {
           return Promise.resolve({ processInstanceKey: "MERGE-1" });
         },
       },
-      log: () => undefined,
+      log: noopLog(),
     },
   };
 }

package/workers/finalize/worker.ts

@@ -83,10 +83,10 @@ const handler: AppJobHandler<In> = async (job, app) => {
       if (mergeProcessKey != null) {
         status = "waiting_deps";
       } else {
-        app.log("error", `finalize: merge-loop start returned no process key for ${prKey}; leaving PR converged`);
+        app.log.error(`finalize: merge-loop start returned no process key for ${prKey}; leaving PR converged`);
       }
     } catch (err) {
-      app.log("error", `finalize: could not start merge-loop for ${prKey}; leaving PR converged`, {
+      app.log.error(`finalize: could not start merge-loop for ${prKey}; leaving PR converged`, {
         err: String(err),
       });
     }

package/workers/merge/worker.test.ts

@@ -6,6 +6,7 @@
 // token transport and stubs `globalThis.fetch` so the single-PR GET reports `merged: true`.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
 import handler from "./worker.ts";
 
 function fakeApp() {
@@ -36,7 +37,7 @@ function fakeApp() {
           };
         },
       },
-      log: () => undefined,
+      log: noopLog(),
       engine: {},
     } as any,
     stores,

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);
+});