@nanobpm/nano-workforce 0.46.0 → 0.46.2

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.46.2](https://github.com/nanobpm/nano-workforce/compare/v0.46.1...v0.46.2) (2026-08-12)
+
+
+### Bug Fixes
+
+* **prompts:** make merge-phase agents emit a machine-readable result ([#133](https://github.com/nanobpm/nano-workforce/issues/133)) ([6584092](https://github.com/nanobpm/nano-workforce/commit/6584092b3ef8f15159c024c080b312ead7484076)), closes [Magikcraft/nano-bpm#746](https://github.com/Magikcraft/nano-bpm/issues/746)
+
+## [0.46.1](https://github.com/nanobpm/nano-workforce/compare/v0.46.0...v0.46.1) (2026-08-12)
+
+
+### Bug Fixes
+
+* **trial-merge:** durable "needs attention" resolution + robust escalation key ([#131](https://github.com/nanobpm/nano-workforce/issues/131)) ([71200e8](https://github.com/nanobpm/nano-workforce/commit/71200e814a8c035a79f1eec37303781c70b6e6c0))
+
 # [0.46.0](https://github.com/nanobpm/nano-workforce/compare/v0.45.0...v0.46.0) (2026-08-12)
 
 

package/app/plan.test.ts

@@ -5,7 +5,7 @@
 // planner could revise forever. `positiveIntEnv` must fall back to the default on any value that
 // is not a positive integer, so the loop is always bounded.
 import { test } from "node:test";
-import { assertEquals, assertThrows } from "#test-assert";
+import { assertEquals, assertRejects, assertThrows } from "#test-assert";
 import { positiveIntEnv } from "./plan.ts";
 
 const KEY = "NANO_PLAN_REVIEW_ROUNDS_TEST";
@@ -303,6 +303,64 @@ test("answerTaskEscalation is a no-op when no open escalation matches the correl
   assertEquals(r.ok, false);
 });
 
+// Red/green regression (PR #131 suppressed advisory, app/plan.ts:455).
+//
+// Clearing a trial-merge wave's "Needs attention" row (`resolveTrialMergeAttention`)
+// is a best-effort cosmetic cleanup, but it must be RETRIABLE: if it ran only AFTER
+// the escalation was committed as `answered` and the resume message was published,
+// a transient DB error there would 500 the whole answer flow while the escalation is
+// already answered/resumed — a retry then 404s (no open escalation) and the red row
+// is pinned forever (the very failure the insert-first ordering elsewhere avoids).
+// The fix runs the idempotent resolution BEFORE the commit/publish, so a failure
+// leaves the escalation OPEN and nothing is orphaned — the caller can safely retry.
+test("answerTaskEscalation stays retriable (escalation open, no orphaned resume) when clearing 'Needs attention' fails", async () => {
+  const stores = escalationStores([
+    {
+      id: 1,
+      plan_key: "owner/repo#9",
+      task_id: "trial-merge-wave-0",
+      corr_key: "owner/repo#9:trial-merge-wave-0",
+      question: "Q",
+      status: "open",
+      answer: null,
+    },
+  ]);
+  stores.plan_trial_merges = {
+    rows: [{ id: 100, plan_key: "owner/repo#9", wave: 0, resolved: 0 }],
+    key: "id",
+  };
+  const base = memData(stores);
+  // Inject a transient failure in the trial-merge audit table's `update` only.
+  const data = {
+    table: (name: string, key: string) => {
+      const t = base.table(name, key);
+      if (name === "plan_trial_merges") {
+        return { ...t, update: () => Promise.reject(new Error("transient DB error")) };
+      }
+      return t;
+    },
+  } as any;
+
+  const published: any[] = [];
+  const engine = {
+    publishMessage: (m: any) => {
+      published.push(m);
+      return Promise.resolve();
+    },
+  } as any;
+
+  await assertRejects(() =>
+    answerTaskEscalation(data, engine, "owner/repo#9:trial-merge-wave-0", "proceed")
+  );
+
+  // Escalation must remain OPEN so a retry can recover (never committed as answered).
+  const esc = stores.plan_escalations.rows.find((x: any) => x.id === 1) as any;
+  assertEquals(esc.status, "open");
+  assertEquals(esc.answer, null);
+  // No orphaned resume message was published.
+  assertEquals(published.length, 0);
+});
+
 test("currentPlanReviewEpoch counts answered plan-review escalations only", async () => {
   const stores = {
     plan_review_escalations: {

package/app/plan.ts

@@ -13,6 +13,7 @@ import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { blackboardUrl, mintBlackboardToken, renderCoordinationBrief } from "./blackboard.ts";
 import { clearExclusions } from "./mergeExclusion.ts";
 import { clearTaskDeltas } from "./taskDelta.ts";
+import { resolveTrialMergeAttention, trialMergeWaveFromTaskId } from "./trialMerge.ts";
 
 /** The BPMN process this module drives (resources/processes/plan-fanout.bpmn). */
 export const PLAN_PROCESS_ID = "plan-fanout";
@@ -433,6 +434,20 @@ export async function answerTaskEscalation(
     .sort((a, b) => b.id - a.id)[0];
   if (!open) return { ok: false, reason: "no open escalation" };
   const ts = now();
+  // A trial-merge escalation (task_id `trial-merge-wave-<wave>`) leaves an
+  // append-only red audit row in `plan_trial_merges`. Answering it clears that
+  // row from the page's "Needs attention" tab — including a "proceed" override
+  // that records no re-run row (a re-run would supersede it, but a proceed would
+  // not, pinning the red row forever).
+  //
+  // Resolve it FIRST, before the escalation is committed as answered and the
+  // resume message is published. `resolveTrialMergeAttention` is idempotent, so
+  // if this throws (e.g. a transient DB error) the escalation is still open and
+  // the whole operation retries cleanly. Running it AFTER the commit/publish
+  // would make a failure here unrecoverable: the escalation is already answered,
+  // a retry 404s (no open escalation), and the red row is pinned forever.
+  const trialWave = trialMergeWaveFromTaskId(open.task_id);
+  if (trialWave != null) await resolveTrialMergeAttention(data, open.plan_key, trialWave);
   await planEscalations(data).update(open.id, { answer, status: "answered", answered_at: ts });
   // Mirror onto the task row so a re-dispatched agent (and the UI) sees the answer.
   for (const t of await planTasks(data).find({ plan_key: open.plan_key, task_id: open.task_id })) {

package/app/trialMerge.test.ts

@@ -1,6 +1,12 @@
 import { test } from "node:test";
-import { assertEquals } from "#test-assert";
-import { shouldRunTrialMerge, trialMergeDecision } from "./trialMerge.ts";
+import { assertEquals, assertRejects } from "#test-assert";
+import {
+  recordTrialMergeAudit,
+  resolveTrialMergeAttention,
+  shouldRunTrialMerge,
+  trialMergeDecision,
+  trialMergeWaveFromTaskId,
+} from "./trialMerge.ts";
 
 test("trialMergeDecision only escalates clean-merge suite failures", () => {
   assertEquals(trialMergeDecision("clean"), "proceed");
@@ -14,3 +20,89 @@ test("shouldRunTrialMerge skips lone heads and mergify queues", () => {
   assertEquals(shouldRunTrialMerge(2, { land: { method: "mergify-queue" } }), false);
   assertEquals(shouldRunTrialMerge(2, { land: { method: "gh-merge" } }), true);
 });
+
+// In-memory `plan_trial_merges` table backing the audit-resolution tests.
+function memData() {
+  const rows: any[] = [];
+  let nextId = 1;
+  const table = {
+    async insert(row: any) {
+      const r = { id: nextId++, ...row };
+      rows.push(r);
+      return r.id;
+    },
+    async find(where: any = {}) {
+      return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v)).map((r) => ({ ...r }));
+    },
+    async update(id: any, patch: any) {
+      const r = rows.find((x) => x.id === id);
+      if (r) Object.assign(r, patch);
+    },
+  };
+  const data = { table: () => table } as any;
+  return { data, rows, table };
+}
+
+test("recordTrialMergeAudit supersedes prior rows for the same wave", async () => {
+  const { data, rows } = memData();
+  // Wave 1 fails, then re-runs clean; wave 2 is independent.
+  const first = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 2, result: "suite-failed" });
+  const rerun = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean" });
+
+  const byId = (id: number) => rows.find((r) => r.id === id);
+  assertEquals(byId(first).resolved, 1, "the superseded wave-1 red row is resolved");
+  assertEquals(byId(rerun).resolved, 0, "the fresh wave-1 row stays unresolved");
+  // The unrelated wave-2 row is untouched (still needs attention).
+  assertEquals(rows.filter((r) => r.wave === 2)[0].resolved, 0);
+});
+
+test("recordTrialMergeAudit updates a re-reporting job in place without superseding", async () => {
+  const { data, rows } = memData();
+  const id = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed", jobKey: "j1" });
+  const again = await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean", jobKey: "j1" });
+  assertEquals(again, id, "the same job_key updates its row in place");
+  assertEquals(rows.length, 1, "no duplicate/supersede row is created");
+  assertEquals(rows[0].result, "clean");
+  assertEquals(rows[0].resolved, 0);
+});
+
+test("recordTrialMergeAudit keeps the wave flagged if the superseding insert fails", async () => {
+  const { data, rows, table } = memData();
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  // Simulate a crash/failure on the superseding insert. The new row must be
+  // inserted BEFORE prior rows are resolved, so a failure here must not leave
+  // the wave with zero unresolved rows (which would silently clear "Needs
+  // attention").
+  table.insert = async () => {
+    throw new Error("insert failed");
+  };
+  await assertRejects(() => recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "clean" }));
+  const unresolved = rows.filter((r) => r.wave === 1 && r.resolved !== 1);
+  assertEquals(unresolved.length, 1, "the wave still has an unresolved row after the failed insert");
+});
+
+test("resolveTrialMergeAttention clears every unresolved row for the wave", async () => {
+  const { data, rows } = memData();
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 1, result: "suite-failed" });
+  await recordTrialMergeAudit(data, { planKey: "o/r#1", wave: 3, result: "suite-failed" });
+  const cleared = await resolveTrialMergeAttention(data, "o/r#1", 1);
+  assertEquals(cleared, 1);
+  assertEquals(rows.filter((r) => r.wave === 1)[0].resolved, 1);
+  assertEquals(rows.filter((r) => r.wave === 3)[0].resolved, 0, "another wave is untouched");
+  // Idempotent: a second call resolves nothing new.
+  assertEquals(await resolveTrialMergeAttention(data, "o/r#1", 1), 0);
+});
+
+test("trialMergeWaveFromTaskId parses only trial-merge task ids", () => {
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-2"), 2);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-0"), 0);
+  assertEquals(trialMergeWaveFromTaskId("some-feature-task"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-x"), null);
+  // Empty suffix must not silently map to wave 0 (Number("") === 0).
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-"), null);
+  // Non-integer / signed / whitespace suffixes are rejected.
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-1.5"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-+2"), null);
+  assertEquals(trialMergeWaveFromTaskId("trial-merge-wave-12"), 12);
+});

package/app/trialMerge.ts

@@ -28,6 +28,7 @@ export interface TrialMergeAuditRow {
   failing: string | null;
   summary: string | null;
   job_key: string | null;
+  resolved: number;
   created_at: string;
   updated_at: string;
 }
@@ -46,6 +47,17 @@ export function trialMergeTaskId(wave: number): string {
   return `${TRIAL_MERGE_TASK_PREFIX}${Math.max(0, Math.trunc(wave))}`;
 }
 
+/** Inverse of {@link trialMergeTaskId}: the wave a trial-merge escalation
+ * `task_id` refers to, or `null` when `taskId` is not a trial-merge escalation
+ * (e.g. an ordinary feature escalation). */
+export function trialMergeWaveFromTaskId(taskId: string): number | null {
+  if (!taskId.startsWith(TRIAL_MERGE_TASK_PREFIX)) return null;
+  const suffix = taskId.slice(TRIAL_MERGE_TASK_PREFIX.length);
+  if (!/^\d+$/.test(suffix)) return null;
+  const wave = Number(suffix);
+  return Number.isInteger(wave) && wave >= 0 ? wave : null;
+}
+
 const auditTable = (data: DataLayer) => data.table<TrialMergeAuditRow>("plan_trial_merges", "id");
 
 function jsonOrNull(v: unknown): string | null {
@@ -76,6 +88,8 @@ export async function recordTrialMergeAudit(
   if (jobKey) {
     const existing = (await table.find({ plan_key: row.planKey, job_key: jobKey })).sort((a, b) => b.id - a.id)[0];
     if (existing) {
+      // Same job re-reporting (a retry before its wait subscription opened):
+      // update in place — it is the same logical attempt, not a supersede.
       await table.update(existing.id, {
         result: row.result,
         heads: jsonOrNull(row.heads),
@@ -87,16 +101,57 @@ export async function recordTrialMergeAudit(
       return existing.id;
     }
   }
-  return Number(await table.insert({
-    plan_key: row.planKey,
-    wave: row.wave,
-    result: row.result,
-    heads: jsonOrNull(row.heads),
-    conflicts: jsonOrNull(row.conflicts),
-    failing: jsonOrNull(row.failing),
-    summary: row.summary ?? null,
-    job_key: jobKey,
-    created_at: ts,
-    updated_at: ts,
-  }));
+  // A fresh audit row for this wave supersedes every prior row for the same
+  // (plan_key, wave): those are now history, so mark them resolved. Without this
+  // the append-only log leaves an old red row in the page's "Needs attention"
+  // tab forever, even after the wave was re-run clean (issue: the tab never
+  // cleared). The newly-inserted row defaults `resolved = 0`, so a still-red
+  // latest attempt keeps showing until it too is superseded or answered.
+  //
+  // Insert the new (unresolved) row FIRST, then resolve the older rows — never
+  // the reverse. Resolving priors before the insert would leave the wave with
+  // zero unresolved rows if the insert (or the process) failed in between,
+  // silently clearing the "Needs attention" tab. Insert-first guarantees the
+  // wave always has at least one unresolved row through the transition.
+  const id = Number(
+    await table.insert({
+      plan_key: row.planKey,
+      wave: row.wave,
+      result: row.result,
+      heads: jsonOrNull(row.heads),
+      conflicts: jsonOrNull(row.conflicts),
+      failing: jsonOrNull(row.failing),
+      summary: row.summary ?? null,
+      job_key: jobKey,
+      resolved: 0,
+      created_at: ts,
+      updated_at: ts,
+    }),
+  );
+  for (const prior of await table.find({ plan_key: row.planKey, wave: row.wave })) {
+    if (prior.id !== id && prior.resolved !== 1) await table.update(prior.id, { resolved: 1, updated_at: ts });
+  }
+  return id;
+}
+
+/** Mark every trial-merge audit row for `(planKey, wave)` resolved, so the epic
+ * page's "Needs attention" tab stops surfacing it. Called when the wave's trial
+ * escalation is answered — including a "proceed" override that records no
+ * re-run row and so would otherwise leave the old red row pinned forever.
+ * Returns the number of rows newly resolved. */
+export async function resolveTrialMergeAttention(
+  data: DataLayer,
+  planKey: string,
+  wave: number,
+): Promise<number> {
+  const table = auditTable(data);
+  const ts = now();
+  let resolved = 0;
+  for (const r of await table.find({ plan_key: planKey, wave })) {
+    if (r.resolved !== 1) {
+      await table.update(r.id, { resolved: 1, updated_at: ts });
+      resolved++;
+    }
+  }
+  return resolved;
 }

package/db/migrations/021_trial_merge_resolved.sql

@@ -0,0 +1,44 @@
+-- Durable "needs attention" resolution for the trial-merge audit log (issue: the
+-- epic page's "Needs attention" tab never cleared).
+--
+-- `plan_trial_merges` is an append-only audit trail: a re-run after a suite
+-- failure INSERTs a fresh row but never supersedes the old red one, so a
+-- `merge-conflict`/`suite-failed` row stayed in "Needs attention" forever even
+-- after the escalation was answered and the wave re-run clean. Add an explicit
+-- `resolved` flag so the page can hide history, and backfill it for existing
+-- rows. Going forward `recordTrialMergeAudit` marks prior same-(plan,wave) rows
+-- resolved on each new insert (supersede-on-insert).
+--
+-- NB: the migration runner wraps each file in its own transaction — this file
+-- must NOT contain BEGIN/COMMIT.
+
+ALTER TABLE plan_trial_merges ADD COLUMN resolved INTEGER NOT NULL DEFAULT 0;
+
+-- Backfill 1 (supersede): any audit row that has a NEWER row (higher id) for the
+-- same (plan_key, wave) is superseded history — resolve it. The newest row per
+-- wave stays unresolved so a still-red latest attempt keeps showing.
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE EXISTS (
+  SELECT 1 FROM plan_trial_merges AS newer
+  WHERE newer.plan_key = plan_trial_merges.plan_key
+    AND newer.wave = plan_trial_merges.wave
+    AND newer.id > plan_trial_merges.id
+);
+
+-- Backfill 2 (answered): a red (needs-attention) row whose trial escalation has
+-- already been answered is resolved — even if no re-run row was ever recorded
+-- (e.g. the operator answered "proceed"/override). The trial escalation's
+-- task_id is 'trial-merge-wave-<wave>' (see app/trialMerge.ts trialMergeTaskId).
+UPDATE plan_trial_merges
+SET resolved = 1
+WHERE result IN ('merge-conflict', 'suite-failed')
+  AND EXISTS (
+    SELECT 1 FROM plan_escalations AS e
+    WHERE e.plan_key = plan_trial_merges.plan_key
+      AND e.task_id = 'trial-merge-wave-' || plan_trial_merges.wave
+      AND e.status = 'answered'
+  );
+
+CREATE INDEX IF NOT EXISTS idx_plan_trial_merges_attention
+  ON plan_trial_merges(plan_key, resolved, result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.46.0",
+  "version": "0.46.2",
   "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/pages/epic.page.json

@@ -273,12 +273,18 @@
           "source": "app",
           "table": "plan_trial_merges",
           "orderBy": { "field": "created_at", "dir": "desc" },
-          "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+          "filter": [
+            { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+            { "field": "resolved", "in": [0] }
+          ]
         },
         "tabs": [
           {
             "label": "Needs attention",
-            "filter": [{ "field": "result", "in": ["merge-conflict", "suite-failed"] }]
+            "filter": [
+              { "field": "result", "in": ["merge-conflict", "suite-failed"] },
+              { "field": "resolved", "in": [0] }
+            ]
           },
           {
             "label": "Clean",

package/prompts/fix-ci.md

@@ -84,3 +84,48 @@ Return a structured result:
 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
 return `blocked` so a human can decide whether to just retry the merge.
+
+### How to return it (the wire mechanism)
+
+Your result variables only reach the process if you emit them through the harness's
+result channel. Prose in your normal output is **not** parsed — if you only "say"
+your status in the transcript, the process can't read it, falls back to its safe
+default (a merge escalation a human must clear), and the merge stalls. So emit a
+machine-readable result one of two ways:
+
+1. **Write a JSON object to the file at `$AGENT_RESULT_FILE`** (an env var the
+   harness sets for you). The object's keys become process variables. Examples:
+
+   ```sh
+   # pushed a fix you believe turns the failing checks green:
+   printf '%s' '{"status":"fixed","summary":"Fixed the flaky timeout in auth.test.ts and pushed"}' > "$AGENT_RESULT_FILE"
+   # ordering constraint — must wait for another PR to land first:
+   printf '%s' '{"status":"waiting-on-pr","summary":"Blocked by the linked-issue gate","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
+   # genuinely stuck — a human must decide:
+   printf '%s' '{"status":"blocked","summary":"CI needs an NPM_TOKEN secret I cannot set","question":"Add the NPM_TOKEN repo secret, then answer to rerun."}' > "$AGENT_RESULT_FILE"
+   ```
+
+   Write this file **once**, at the very end, with your final result. Keep it a flat
+   JSON object of exactly the variables named in the return contract above.
+
+2. **Fallback** (only if you truly cannot write the file): print a single line to
+   stdout of the form `::nano:result:: {json}` — e.g.
+
+   ```
+   ::nano:result:: {"status":"fixed","summary":"Corrected the type error in handler.ts and pushed"}
+   ```
+
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
+   accepted as a last resort.
+
+Do not put the result file inside the repo checkout or `git add` it — it lives
+outside your workspace. Exit `0` for every status (including `blocked`/`waiting-on-pr`);
+a non-zero exit means a genuine crash and the job is retried.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** It is the last thing you do on every path out of this job (including after
+a push, or when you conclude nothing can be fixed). If you are ever unsure which status
+applies, return **`blocked`** with a `summary` and a concrete `question` rather than
+leaving without a result — a missing result is treated as an unclassified merge
+escalation that pulls in a human and stalls the merge, so relying on that default
+wastes the attempt.

package/prompts/rebase.md

@@ -100,3 +100,48 @@ was needed, so the process simply re-attempts the merge; the rebase budget
 bounds how many times a still-stuck PR can loop here before it escalates. Reserve
 `blocked` for a genuine semantic conflict you cannot resolve mechanically (or a
 branch that is un-rebaseable), so a human can decide.
+
+### How to return it (the wire mechanism)
+
+Your result variables only reach the process if you emit them through the harness's
+result channel. Prose in your normal output is **not** parsed — if you only "say"
+your status in the transcript, the process can't read it, falls back to its safe
+default (a merge escalation a human must clear), and the merge stalls. So emit a
+machine-readable result one of two ways:
+
+1. **Write a JSON object to the file at `$AGENT_RESULT_FILE`** (an env var the
+   harness sets for you). The object's keys become process variables. Examples:
+
+   ```sh
+   # branch tip now contains the latest base (you pushed a resolved rebase, or it was already up to date):
+   printf '%s' '{"status":"rebased","summary":"Rebased onto main, resolved 2 conflicts in router.ts, pushed"}' > "$AGENT_RESULT_FILE"
+   # ordering constraint — must wait for another PR to land first:
+   printf '%s' '{"status":"waiting-on-pr","summary":"Stacked on the base PR that has not merged","dependsOn":"owner/repo#123"}' > "$AGENT_RESULT_FILE"
+   # genuine semantic conflict — a human must decide which behaviour wins:
+   printf '%s' '{"status":"blocked","summary":"main and this branch both rewrote retry() incompatibly","question":"Should retries stay capped at 3 (main) or become unbounded (this PR)?"}' > "$AGENT_RESULT_FILE"
+   ```
+
+   Write this file **once**, at the very end, with your final result. Keep it a flat
+   JSON object of exactly the variables named in the return contract above.
+
+2. **Fallback** (only if you truly cannot write the file): print a single line to
+   stdout of the form `::nano:result:: {json}` — e.g.
+
+   ```
+   ::nano:result:: {"status":"rebased","summary":"Already up to date; no push needed"}
+   ```
+
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
+   accepted as a last resort.
+
+Do not put the result file inside the repo checkout or `git add` it — it lives
+outside your workspace. Exit `0` for every status (including `blocked`/`waiting-on-pr`);
+a non-zero exit means a genuine crash and the job is retried.
+
+**Emitting a machine-readable result is your mandatory final step — never exit
+silently.** It is the last thing you do on every path out of this job (including after
+a force-push, or when the branch was already up to date). If you are ever unsure which
+status applies and the branch tip contains the latest base, return **`rebased`** with a
+`summary`; otherwise return **`blocked`** with a concrete `question` — never leave
+without a result. A missing result is treated as an unclassified merge escalation that
+pulls in a human and stalls the merge, so relying on that default wastes the attempt.

package/prompts/review-round.md

@@ -181,7 +181,7 @@ default, and you waste a round. So emit a machine-readable result one of two way
    ::nano:result:: {"status":"converged","summary":"No actionable comments left"}
    ```
 
-   The harness reads the **last** such line. A trailing ```json fenced block is also
+   The harness reads the **last** such line. A trailing fenced JSON code block is also
    accepted as a last resort.
 
 Do not put the result file inside the repo checkout or `git add` it — it lives

package/resources/processes/plan-fanout.bpmn

@@ -2,7 +2,7 @@
 <bpmn:definitions xmlns:bpmn="http://www.omg.org/spec/BPMN/20100524/MODEL" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:bpmndi="http://www.omg.org/spec/BPMN/20100524/DI" xmlns:dc="http://www.omg.org/spec/DD/20100524/DC" xmlns:di="http://www.omg.org/spec/DD/20100524/DI" xmlns:zeebe="http://camunda.org/schema/zeebe/1.0" id="Definitions_nano_workforce_plan" targetNamespace="http://nanobpm.io/nano-workforce">
   <bpmn:message id="Message_featureEscalationAnswered" name="feature-escalation-answered">
     <bpmn:extensionElements>
-      <zeebe:subscription correlationKey="=planKey + &#34;:&#34; + task.id" />
+      <zeebe:subscription correlationKey="=escalationCorrKey" />
     </bpmn:extensionElements>
   </bpmn:message>
   <bpmn:message id="Message_planEscalationAnswered" name="plan-escalation-answered">

package/scripts/check-agent-prompts.test.ts

@@ -30,11 +30,11 @@ function fixture(files: Record<string, string>): string {
   return root;
 }
 
-test("passes when every {{token}} resolves to a non-blank template", async () => {
+test("passes when every {{token}} resolves to a non-blank template that emits a result", async () => {
   const root = await fixture({
     "nano.app.json": MANIFEST,
     "resources/processes/loop.bpmn": header("{{review-round}}"),
-    "prompts/review-round.md": "# Round\nDo the thing.",
+    "prompts/review-round.md": "# Round\nDo the thing, then write your result to `$AGENT_RESULT_FILE`.",
   });
   const res = checkAgentPrompts(root);
   assertEquals(res.errors, []);
@@ -75,6 +75,31 @@ test("fails when a reserved agent-prompt header is blank", async () => {
   assert(res.errors.some((e) => e.includes("is empty")));
 });
 
+test("fails when an agent-prompt template omits the machine-readable result mechanism", async () => {
+  // A prompt wired as an agent's base prompt must tell it to write $AGENT_RESULT_FILE (or use the
+  // ::nano:result:: fallback). Without it the agent finishes with prose only, `status` comes back
+  // blank, and the status gateway escalates/stalls — the fix-ci/rebase gap behind #746's stuck merge.
+  const root = await fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "prompts/review-round.md": "# Round\nReturn status: converged. (but never says how to emit it)",
+  });
+  const res = checkAgentPrompts(root);
+  assert(!res.ok);
+  assert(res.errors.some((e) => e.includes("{{review-round}}") && e.includes("AGENT_RESULT_FILE")));
+});
+
+test("passes when an agent-prompt template emits via the ::nano:result:: fallback", async () => {
+  const root = await fixture({
+    "nano.app.json": MANIFEST,
+    "resources/processes/loop.bpmn": header("{{review-round}}"),
+    "prompts/review-round.md": "# Round\nEmit `::nano:result:: {\"status\":\"converged\"}` at the end.",
+  });
+  const res = checkAgentPrompts(root);
+  assertEquals(res.errors, []);
+  assert(res.ok);
+});
+
 test("checks the real repo: all committed agent prompts resolve", () => {
   // The guard must be green against the actual app it protects — this is the case CI relies on.
   const repoRoot = decodeURIComponent(new URL("../", import.meta.url).pathname);
@@ -82,7 +107,7 @@ test("checks the real repo: all committed agent prompts resolve", () => {
   assertEquals(res.errors, []);
   assert(res.ok);
   // Every senior:* agent prompt header in the three processes must have resolved.
-  for (const t of ["review-round", "fix-ci", "plan", "plan-review", "feature", "trial-merge"]) {
+  for (const t of ["review-round", "fix-ci", "plan", "plan-review", "feature", "trial-merge", "rebase", "retro"]) {
     assert(res.resolved.includes(t), `expected template ${t} to resolve`);
   }
 });

package/scripts/check-agent-prompts.ts

@@ -72,6 +72,33 @@ function hasBlankAgentPromptHeader(bpmn: string): boolean {
   return false;
 }
 
+// The template tokens a model wires as an agent's base prompt, e.g. the `fix-ci` in
+// `value="{{fix-ci}}"` on an `io.nanobpm.agentTask.task.prompt` header. These templates *drive an
+// agent*, so each must teach it to emit a machine-readable result (see agentPromptEmitsResult).
+function agentPromptTokens(bpmn: string): string[] {
+  const tokens: string[] = [];
+  const re = /<zeebe:header\s+key="([^"]*)"\s+value="([^"]*)"\s*\/?>/g;
+  let m = re.exec(bpmn);
+  while (m !== null) {
+    if (m[1] === AGENT_PROMPT_HEADER) {
+      const tok = /^\{\{\s*([^}]+?)\s*\}\}$/.exec(m[2].trim());
+      if (tok) tokens.push(tok[1]);
+    }
+    m = re.exec(bpmn);
+  }
+  return tokens;
+}
+
+// A prompt that drives an agent must tell it how to return a machine-readable result — the
+// `$AGENT_RESULT_FILE` write (or the `::nano:result::` stdout fallback). Without it the agent can
+// finish with prose only, its `status` variable comes back empty, the status gateway falls through
+// to its default escalation arm, and the run parks a human escalation / stalls the merge (the
+// fix-ci/rebase gap behind Magikcraft/nano-bpm#746's stuck merge). Prose is never parsed, so this
+// instruction is load-bearing, not documentation.
+function agentPromptEmitsResult(body: string): boolean {
+  return body.includes("AGENT_RESULT_FILE") || body.includes("::nano:result::");
+}
+
 export interface CheckResult {
   ok: boolean;
   errors: string[];
@@ -82,6 +109,7 @@ export interface CheckResult {
 export function checkAgentPrompts(root: string): CheckResult {
   const errors: string[] = [];
   const resolved = new Set<string>();
+  const agentTokens = new Set<string>();
 
   const manifestPath = join(root, "nano.app.json");
   if (!existsSync(manifestPath)) {
@@ -127,6 +155,20 @@ export function checkAgentPrompts(root: string): CheckResult {
     if (hasBlankAgentPromptHeader(content)) {
       errors.push(`${rel}: a reserved "${AGENT_PROMPT_HEADER}" header is empty (agent would run prompt-less)`);
     }
+    for (const tok of agentPromptTokens(content)) agentTokens.add(tok);
+  }
+
+  // Every template wired as an agent's base prompt must teach the agent to emit a machine-readable
+  // result; a prose-only agent leaves `status` blank and the process escalates/stalls.
+  for (const tok of [...agentTokens].sort()) {
+    const body = templates[tok];
+    if (body != null && body.trim() !== "" && !agentPromptEmitsResult(body)) {
+      errors.push(
+        `template {{${tok}}} drives an agent but never tells it to write $AGENT_RESULT_FILE ` +
+          `(or the ::nano:result:: fallback) — the agent can finish with prose only, leaving its ` +
+          `status blank so the process escalates/stalls`,
+      );
+    }
   }
 
   return { ok: errors.length === 0, errors, resolved: [...resolved].sort() };

package/workers/persist-task-escalation/worker.ts

@@ -36,6 +36,7 @@ interface In extends Record<string, unknown> {
 }
 interface Out extends Record<string, unknown> {
   escalationId: number;
+  escalationCorrKey: string;
 }
 
 // A non-blank trimmed string, else undefined. A blank question/PR must not reach
@@ -106,7 +107,14 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   }
 
   await refreshOpenTaskEscalation(app.data, planKey);
-  return { escalationId };
+  // Emit the correlation key as a single scalar so the downstream
+  // `feature-escalation-answered` catch subscribes on `=escalationCorrKey`
+  // (freshly set, in scope) rather than re-deriving `=planKey + ":" + task.id`.
+  // The concatenation form errored to an empty, unmatchable key whenever `task`
+  // was not a Map at subscription-open, parking the token forever (see the
+  // engine incident fix). The value is identical to `featureCorrKey(planKey,
+  // taskId)`, so the app's answer-publish path still matches.
+  return { escalationId, escalationCorrKey: corrKey };
 };
 
 export default handler;