@nanobpm/nano-workforce 0.60.0 → 0.61.1

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+## [0.61.1](https://github.com/nanobpm/nano-workforce/compare/v0.61.0...v0.61.1) (2026-08-13)
+
+
+### Bug Fixes
+
+* **feature:** reconcile Feature-history status + escalate blocked runs ([#204](https://github.com/nanobpm/nano-workforce/issues/204)) ([5ef9461](https://github.com/nanobpm/nano-workforce/commit/5ef94613f09b557806eb9254545df1984025077c)), closes [#171](https://github.com/nanobpm/nano-workforce/issues/171)
+
+# [0.61.0](https://github.com/nanobpm/nano-workforce/compare/v0.60.0...v0.61.0) (2026-08-13)
+
+
+### Features
+
+* prompts as linked resources (bindingType: latest) — live mid-epic updates ([#198](https://github.com/nanobpm/nano-workforce/issues/198)) ([#203](https://github.com/nanobpm/nano-workforce/issues/203)) ([24a83e0](https://github.com/nanobpm/nano-workforce/commit/24a83e01f7e7b4f6e5296ce90c63fa44105aa058)), closes [#169](https://github.com/nanobpm/nano-workforce/issues/169) [#169](https://github.com/nanobpm/nano-workforce/issues/169)
+
 # [0.60.0](https://github.com/nanobpm/nano-workforce/compare/v0.59.0...v0.60.0) (2026-08-13)
 
 

package/README.md

@@ -156,7 +156,8 @@ capability):
 
 - `--command 'copilot -p - --allow-all-tools'` starts the Copilot CLI reading its
   prompt from **stdin** (`-p -`). The harness pipes the whole job JSON (prompt +
-  `job.variables`) to stdin; the relevant `prompts/*.md` template tells the agent how
+  `job.variables`) to stdin; the relevant `prompts/*.md` resource (linked into the task
+  and fetched by the harness at activation) tells the agent how
   to read it and where to write its result.
 - **`--allow-all-tools` is essential** for an unattended worker — without it Copilot
   pauses for permission before each tool call and the job stalls.
@@ -280,10 +281,18 @@ The `senior:*` tasks are serviced by **external** workers — they are **not** i
 manifest `workers[]`. Point a `c8ctl nano work` daemon (or any Zeebe-style worker) at
 the task types; each job carries its variables (e.g. `senior:pr-review` gets `{prUrl,
 repo, prNumber, round, answer?}` and returns `{status, summary, question?}`). An
-agent's base prompt is **not** in the job payload — it is delivered via a model
-**template header** (`{{review-round}}`, `{{plan}}`, `{{feature}}`, `{{fix-ci}}`, …)
-substituted at deploy time from `prompts/*.md` (`models.templates` in `nano.app.json`);
-per-instance context (e.g. a human's escalation answer) is appended by the harness.
+agent's base prompt is **not** in the job payload — it is delivered as a
+**linked resource** (likewise `plan.md`, `feature.md`, `fix-ci.md`, …):
+
+```xml
+<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>
+```
+
+that the engine resolves to the latest deployed `prompts/*.md` at job
+activation (the prompts deploy as generic resources via a `models` glob in
+`nano.app.json`); per-instance context (e.g. a human's escalation answer) is appended
+by the harness. Because the binding is `latest`, redeploying one `prompts/*.md` updates
+the prompt for the next activation in a **running** epic — see SPEC §9.
 
 ---
 

package/SPEC.md

@@ -86,11 +86,11 @@ known at submit time, carried as a process variable and stored on the DB row.
       │
       ▼
 [Register PR]  (script/handler)   → insert DB row; round = 1
-      │                              (base prompt delivered via the {{review-round}} model
-      │                               template header, not a process variable)
+      │                              (base prompt delivered via the review-round.md
+      │                               linked resource, not a process variable)
       ▼
 ┌──▶ [Review round]  (service task, taskType: senior:pr-review)
-│         in : prUrl, repo, prNumber, round, answer?   (prompt via task header)
+│         in : prUrl, repo, prNumber, round, answer?   (prompt via linked resource)
 │         out: status, summary, question?
 │         │
 │         ▼
@@ -153,10 +153,11 @@ Notes:
 | `round` | int | 1-based round counter |
 | `answer` | string? | present only when resuming from an escalation |
 
-The base instructions are **not** a job variable: they are delivered as a model
-**template header** on the `senior:pr-review` task — header key
-`io.nanobpm.agentTask.task.prompt` with value `{{review-round}}`, substituted with
-`prompts/review-round.md` at deploy time.
+The base instructions are **not** a job variable: they are delivered as a
+**linked resource** on the `senior:pr-review` task —
+`<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>`,
+which the engine resolves to the latest deployed `prompts/review-round.md` at job
+activation.
 
 **Output** (job result variables):
 | var | type | notes |
@@ -292,24 +293,54 @@ tracked row to `abandoned` via the `instanceTracking` `onTerminated.set` patch.
 `deno task purge` wipes and re-migrates the app db (used
 when the engine data is purged, to keep app state and engine state consistent).
 
-## 9. Prompt delivery — model-authored template headers
+## 9. Prompt delivery — linked resources (`bindingType: latest`)
 
-Each agent task's base prompt lives **only** in its `prompts/*.md` side-car and is
-authored **into the model** as a deploy-time `{{stem}}` template. `nano.app.json`
-declares `models.templates: ["prompts/*.md"]`, and each agent service task carries a
-`io.nanobpm.agentTask.task.prompt = {{stem}}` task header (`{{review-round}}`,
-`{{plan}}`, `{{plan-review}}`, `{{feature}}`, `{{fix-ci}}`). At deploy the template
-substitutes the file content into the header, so the host no longer reads prompt
-assets or carries them as process variables.
+Each agent task's base prompt lives **only** in its `prompts/*.md` side-car, deployed
+as a **generic resource** and **linked** — not baked — into the model (issue #169).
+`nano.app.json` lists `prompts/*.md` in a `models` deploy glob, so `@nanobpm/urban`
+deploys each file as an `application/octet-stream` resource whose deployed **name is
+the file's basename** (`prompts/review-round.md` → resource `review-round.md`). Each
+agent service task links it:
 
-Per-instance dynamic context rides **`appendPrompt`**: an ioMapping sets a job-local
-`appendPrompt` string (a plan's rejection findings, a feature task's brief, the
-failing-check list) which the agent harness concatenates **verbatim** onto the header
-base — the model owns any separator, and a null/empty append leaves the base
+```xml
+<zeebe:linkedResources>
+  <zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt" />
+</zeebe:linkedResources>
+```
+
+At **job activation** the engine resolves the *latest deployed* key for that
+`resourceId` and hands the content to the harness in the `linkedResources` activation
+header; the harness fetches by key and uses it as the base prompt. Because the binding
+is `latest`, **redeploying a single `prompts/*.md` changes the prompt for the next task
+activation in a running epic** — no process redeploy, no in-flight epic restart. This
+is the live-prompt debugging loop: edit one Markdown file, `urban deploy` (or restart
+the app, which deploys on boot), and the next agent job of that type picks it up.
+
+> **Latest-for-now, audited.** The engine currently keeps only the latest version per
+> `resourceId` (`deployment`/`versionTag` bindings degrade to latest — no pinning yet).
+> We accept `latest` (ideal for active debugging) and rely on the harness recording the
+> resolved `resourceKey` per job for "which prompt did this run use?". True
+> `deployment`-binding pinning for reproducible production epics is an engine follow-up,
+> not part of #169.
+
+> **The engine silently omits an unresolvable link.** A typo'd or undeployed
+> `resourceId` is dropped from the activation header (no incident) — the agent would
+> then run prompt-less. `scripts/check-agent-prompts.ts` (CI gate `check:prompts`)
+> guards against this: every `linkName="prompt"` link's `resourceId` must match a
+> prompt file the app actually deploys (a file in a `models` deploy glob), each linked
+> prompt must be non-blank and teach the agent to emit a machine-readable result
+> (`$AGENT_RESULT_FILE` / `::nano:result::`), and no task may still carry the retired
+> baked `io.nanobpm.agentTask.task.prompt` header.
+
+Per-instance dynamic context still rides **`appendPrompt`** (unchanged): an ioMapping
+sets a job-local `appendPrompt` string (a plan's rejection findings, a feature task's
+brief, the failing-check list) which the agent harness concatenates **verbatim** onto
+the linked base — the model owns any separator, and a null/empty append leaves the base
 untouched. Base prompts can't be composed in FEEL (they are quote-heavy, and XML
 attribute escaping would corrupt a FEEL string literal), so composition happens via
-this append seam rather than inline in FEEL. Requires `@nanobpm/urban` with
-deploy-time template substitution.
+this append seam rather than inline in FEEL. Requires an `@nanobpm/urban` deploy that
+emits generic-resource deployments for `prompts/*.md` and a harness that consumes
+`linkedResources` and fetches the resource by key.
 
 ## 10. Poller
 
@@ -365,7 +396,7 @@ start ─► wait: deps merged ─► arm merge ─► wait: mergeable ─┬─
 
 - **CI auto-fix** — a `blocked` verdict means a **required check failed**
   (`classifyMergeability`). Rather than escalate immediately, the stage dispatches a
-  `senior:fix-ci` agent (base prompt via the `{{fix-ci}}` template header; the failing
+  `senior:fix-ci` agent (base prompt via the `fix-ci.md` linked resource; the failing
   check names ride `appendPrompt`) to green the checks on the branch, then re-arms the
   poller. It repeats while `ciFixRound < ciFixMax`
   (`NANO_PR_MAX_CI_FIX_ROUNDS`, default 3; `0` disables). Only when the budget is
@@ -432,7 +463,7 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
 ```
 
 - **`plan`** — service task, job type `senior:plan`. Its base prompt is delivered
-  via the `{{plan}}` model template header (`prompts/plan.md`); when a prior review
+  via the `plan.md` linked resource (`bindingType: latest`); when a prior review
   rejected the plan, the rejection findings ride `appendPrompt` (an ioMapping over
   `planFindings`) rather than being concatenated in FEEL. The agent reads the issue
   via `gh` and emits `tasks: [{ id, title, prompt }]`.
@@ -442,8 +473,8 @@ Start(issue) → plan → record-plan → implement (parallel MI) → record-res
   iterates the canonical list.
 - **`implement`** — service task, job type `senior:feature`, **parallel
   multi-instance** over `=tasks` (`inputElement="task"`,
-  `outputCollection="results"`). Its base prompt is delivered via the `{{feature}}`
-  model template header (`prompts/feature.md`); each child's per-task brief
+  `outputCollection="results"`). Its base prompt is delivered via the `feature.md`
+  linked resource (`bindingType: latest`); each child's per-task brief
   (`"\n\n---\n\n" + task.prompt`) rides `appendPrompt` — an input mapping evaluated
   **per child** (Zeebe parity: the inner activity keeps its own `zeebe:ioMapping`,
   applied on each inner-instance activation with `task`/`loopCounter` bound). Each

package/app/feature.test.ts

@@ -7,7 +7,7 @@
 // process variables (the single `task` slice + the base-branch brief).
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { FEATURE_PROCESS_ID, featureTaskId, startFeature } from "./feature.ts";
+import { FEATURE_PROCESS_ID, FEATURE_TERMINAL_STATUSES, featureTaskId, startFeature } from "./feature.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -132,6 +132,30 @@ test("startFeature: an already-running run short-circuits (no new instance)", as
   assertEquals(result.processKey, "PI-OLD");
 });
 
+test("startFeature: a run parked at the operator task (awaiting_operator) short-circuits a re-dispatch", async () => {
+  // A blocked run parked at the feature-blocked user task is NON-terminal, so re-dispatching the
+  // same issue must not spawn an orphaned parallel instance — it short-circuits until the operator
+  // acknowledges it (which settles it to terminal `blocked`).
+  assertEquals(FEATURE_TERMINAL_STATUSES.includes("awaiting_operator" as any), false);
+  const stores = {
+    feature_runs: {
+      rows: [{ feature_key: "owner/repo#42", status: "awaiting_operator", process_key: "PI-PARK" }],
+      key: "feature_key",
+    },
+  };
+  let created = 0;
+  const engine = {
+    createInstance: () => {
+      created += 1;
+      return Promise.resolve({ processInstanceKey: "PI-NEW" });
+    },
+  } as any;
+  const result = await startFeature(memData(stores), engine, PARSED, "main", false, false);
+  assertEquals(created, 0);
+  assertEquals("alreadyRunning" in result && (result as any).alreadyRunning, true);
+  assertEquals(result.processKey, "PI-PARK");
+});
+
 test("startFeature: a settled run is restarted in place (status reset, pr/outcome cleared)", async () => {
   const stores = {
     feature_runs: {

package/app/feature.ts

@@ -39,6 +39,12 @@ export interface FeatureRun {
   converge: number;
   auto_merge: number;
   outcome: string | null;
+  /** Human rollup detail. Projected by `pollFeatureDelivery` (fix: Feature history stuck at
+   * `converging`) and also written by `pr.record-blocked-ack` with the operator's disposition
+   * note when a blocked run is acknowledged. NULL until there is a signal. The reconciled TERMINAL
+   * outcome is written to `status` itself; this carries the sub-state / note (e.g. "merged",
+   * "waiting_review", or "operator: <note>"). */
+  delivery_label: string | null;
   created_at: string;
   updated_at: string;
 }
@@ -47,24 +53,70 @@ export const FEATURE_RUN_STATUSES = [
   "running", // the agent is implementing (including while parked at an escalation user task)
   "opened", // a PR was raised and the run ends here (converge was not requested)
   "converging", // the opened PR was handed to the convergence loop (live state via pr_key → pull_requests)
+  "awaiting_operator", // NON-terminal: the run is blocked and parked at the feature-blocked operator user task
+  "merged", // reconciled: the handed-off PR MERGED (pollFeatureDelivery, from pull_requests.status)
+  "converged", // reconciled: the handed-off PR converged but did not merge (auto-merge off)
   "blocked", // the agent could not open a PR (gave up / escalation abandoned)
   "skipped", // nothing to do
   "failed", // an unexpected failure
-  "abandoned", // the process instance was cancelled (set by instanceTracking.onTerminated)
+  "abandoned", // reconciled: the handed-off PR was abandoned (pollFeatureDelivery), or the process
+  // instance itself was cancelled (set by instanceTracking.onTerminated)
 ] as const;
 export type FeatureRunStatus = typeof FEATURE_RUN_STATUSES[number];
 
 /** A feature run is finished once it leaves `running`. Mirrors PLAN_TERMINAL_STATUSES: a
- * re-dispatch of the same issue restarts only when the prior run has settled. */
+ * re-dispatch of the same issue restarts only when the prior run has settled. `converging` stays
+ * terminal-for-redispatch even though `pollFeatureDelivery` may later advance it to
+ * `merged`/`converged`/`abandoned` — those are equally terminal, so redispatch gating is unaffected.
+ * `awaiting_operator` is deliberately EXCLUDED (non-terminal): while a blocked run is parked at the
+ * feature-blocked operator user task its instance is still alive, so a re-dispatch of the same issue
+ * must short-circuit (no orphaned parallel instance) until the operator acknowledges it. */
 export const FEATURE_TERMINAL_STATUSES: readonly FeatureRunStatus[] = [
   "opened",
   "converging",
+  "merged",
+  "converged",
   "blocked",
   "skipped",
   "failed",
   "abandoned",
 ];
 
+/** Reconciled delivery outcome for a single feature run, derived from its handed-off PR's
+ * `pull_requests.status`. Pure and read-only — the source of truth for the denormalised
+ * `feature_runs.status` transition + `feature_runs.delivery_label` that `pollFeatureDelivery`
+ * projects. Only meaningful for a run currently `converging` with a `pr_key`. */
+export interface FeatureDeliveryRollup {
+  /** The reconciled `feature_runs.status`. Stays `converging` while the PR is still in flight
+   * (or its row is missing); advances to the matching terminal outcome once the PR settles. */
+  status: FeatureRunStatus;
+  /** Human rollup detail for the row (`delivery_label`). */
+  label: string;
+}
+
+/** Map a handed-off PR's `pull_requests.status` to the feature run's reconciled outcome.
+ *
+ * - `merged` → `merged` (the win). `converged` → `converged` (review done, not merged — auto-merge
+ *   was off). `abandoned` → `abandoned`.
+ * - in-flight PR statuses (`converging`/`waiting_review`/`escalated`) keep the run `converging`,
+ *   surfacing the live sub-state as the label so the grid stops looking frozen.
+ * - `null` (the `pull_requests` row is missing — DB desync) keeps the run `converging` and labels
+ *   it so the desync is visible, never a false-positive terminal. */
+export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryRollup {
+  switch (prStatus) {
+    case "merged":
+      return { status: "merged", label: "merged" };
+    case "converged":
+      return { status: "converged", label: "converged (not merged)" };
+    case "abandoned":
+      return { status: "abandoned", label: "PR abandoned" };
+    case null:
+      return { status: "converging", label: "PR record missing" };
+    default:
+      return { status: "converging", label: prStatus };
+  }
+}
+
 export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
 
 /** The deterministic task id for a single-issue run — the implementation agent branches
@@ -104,6 +156,7 @@ export async function startFeature(
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
       outcome: null,
+      delivery_label: null,
       updated_at: ts,
     });
   } else {
@@ -119,6 +172,7 @@ export async function startFeature(
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,
       outcome: null,
+      delivery_label: null,
       created_at: ts,
       updated_at: ts,
     });

package/app/featureDelivery.test.ts

@@ -0,0 +1,117 @@
+// Read-model derivation test for the FEATURE-run delivery reconcile (fix: Feature history stuck at
+// `converging`). A single-issue feature run hands its opened PR to the convergence loop and ENDS with
+// `feature_runs.status = 'converging'`; the PR's live outcome then lives only on `pull_requests`
+// (keyed by `pr_key`). `deriveFeatureDelivery` is the pure source of truth for the status transition
+// + `delivery_label` that `pollFeatureDelivery` projects onto the row so the grid stops looking frozen.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import { deriveFeatureDelivery } from "./feature.ts";
+import { pollFeatureDelivery } from "./service.ts";
+
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+test("deriveFeatureDelivery: merged PR advances the run to merged", () => {
+  assertEquals(deriveFeatureDelivery("merged"), { status: "merged", label: "merged" });
+});
+
+test("deriveFeatureDelivery: converged (review-only, unmerged) PR advances to converged", () => {
+  assertEquals(deriveFeatureDelivery("converged"), { status: "converged", label: "converged (not merged)" });
+});
+
+test("deriveFeatureDelivery: abandoned PR advances to abandoned", () => {
+  assertEquals(deriveFeatureDelivery("abandoned"), { status: "abandoned", label: "PR abandoned" });
+});
+
+test("deriveFeatureDelivery: an in-flight PR keeps the run converging, surfacing the sub-state", () => {
+  for (const s of ["converging", "waiting_review", "escalated"]) {
+    assertEquals(deriveFeatureDelivery(s), { status: "converging", label: s }, `status ${s}`);
+  }
+});
+
+test("deriveFeatureDelivery: a missing PR row keeps converging, never a false-positive terminal", () => {
+  assertEquals(deriveFeatureDelivery(null), { status: "converging", label: "PR record missing" });
+});
+
+test("pollFeatureDelivery: a converging run whose PR merged is reconciled to merged", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#1", status: "converging", pr_key: "o/r#5", delivery_label: null },
+  ];
+  stores.pull_requests = [{ pr_key: "o/r#5", status: "merged" }];
+
+  await pollFeatureDelivery(data);
+
+  assertEquals(stores.feature_runs[0].status, "merged");
+  assertEquals(stores.feature_runs[0].delivery_label, "merged");
+});
+
+test("pollFeatureDelivery: a run with a still-in-flight PR stays converging with a live label", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#2", status: "converging", pr_key: "o/r#6", delivery_label: null },
+  ];
+  stores.pull_requests = [{ pr_key: "o/r#6", status: "waiting_review" }];
+
+  await pollFeatureDelivery(data);
+
+  assertEquals(stores.feature_runs[0].status, "converging");
+  assertEquals(stores.feature_runs[0].delivery_label, "waiting_review");
+});
+
+test("pollFeatureDelivery: only touches converging runs with a pr_key", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#3", status: "opened", pr_key: null, delivery_label: null }, // not converging
+    { feature_key: "o/r#4", status: "converging", pr_key: null, delivery_label: null }, // no PR to read
+    { feature_key: "o/r#5", status: "blocked", pr_key: "o/r#9", delivery_label: null }, // terminal, not converging
+  ];
+  stores.pull_requests = [{ pr_key: "o/r#9", status: "merged" }];
+
+  await pollFeatureDelivery(data);
+
+  assertEquals(stores.feature_runs[0].status, "opened");
+  assertEquals(stores.feature_runs[1].status, "converging");
+  assertEquals(stores.feature_runs[1].delivery_label, null);
+  assertEquals(stores.feature_runs[2].status, "blocked");
+});
+
+test("pollFeatureDelivery: a dangling pr_key (missing PR row) stays converging, never a false terminal", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#6", status: "converging", pr_key: "o/r#404", delivery_label: null },
+  ];
+  stores.pull_requests = [];
+
+  await pollFeatureDelivery(data);
+
+  assertEquals(stores.feature_runs[0].status, "converging");
+  assertEquals(stores.feature_runs[0].delivery_label, "PR record missing");
+});

package/app/mergeRebaseArm.test.ts

@@ -62,9 +62,9 @@ test("rebase arm mirrors the fix-ci arm: budget gate → agent → result gate",
   assert(hasFlow("gw-rebase", "merge-esc-conflict"), "gw-rebase → merge-esc-conflict (budget exhausted) missing");
   assertStringIncludes(flat, "rebaseRound < rebaseMax");
 
-  // The agent is the senior:rebase fleet task, carrying its base prompt via the {{rebase}} header.
+  // The agent is the senior:rebase fleet task, carrying its base prompt via the rebase.md linked resource.
   assertStringIncludes(flat, 'type="senior:rebase"');
-  assertStringIncludes(flat, 'value="{{rebase}}"');
+  assertStringIncludes(flat, 'resourceId="rebase.md"');
 
   // Agent → result gate; the round counter advances so the budget can actually be exhausted.
   assert(hasFlow("rebase", "gw-rebase-result"), "rebase → gw-rebase-result missing");

package/app/plan.ts

@@ -31,11 +31,12 @@ export const ESCALATION_SLA_TIMEOUT = escalationSlaTimeout(
 const now = () => new Date().toISOString();
 
 // Agent prompts are no longer read by the host. The `senior:plan`, `senior:plan-review`, and
-// `senior:feature` prompts are authored in the model as `{{plan}}` / `{{plan-review}}` /
-// `{{feature}}` deploy-time templates (see `models.templates` in nano.app.json) substituted into
-// each task's `io.nanobpm.agentTask.task.prompt` header. Per-instance dynamic context (a plan's
-// rejection findings, a task's brief) rides `appendPrompt`, which the harness concatenates onto
-// the header base. The host only carries runtime identity + `planFindings`.
+// `senior:feature` prompts are generic resources (`prompts/plan.md` / `prompts/plan-review.md` /
+// `prompts/feature.md`, deployed via a `models` glob in nano.app.json) linked into each task as
+// `<zeebe:linkedResource … bindingType="latest" linkName="prompt"/>` and resolved by the engine at
+// job activation. Per-instance dynamic context (a plan's rejection findings, a task's brief) rides
+// `appendPrompt`, which the harness concatenates onto the linked base. The host only carries
+// runtime identity + `planFindings`.
 
 export interface Plan {
   plan_key: string;

package/app/retro.ts

@@ -161,7 +161,7 @@ export async function gatherRetro(data: DataLayer, planKey: string): Promise<Ret
 }
 
 /** Render the digest as the compact markdown brief handed to the retro agent (rides `appendPrompt`,
- * concatenated after the base `{{retro}}` prompt — so it owns its own leading separator). */
+ * concatenated after the base `retro.md` linked-resource prompt — so it owns its own leading separator). */
 export function renderRetroBrief(d: RetroDigest): string {
   const lines: string[] = [
     "",

package/app/service.ts

@@ -9,6 +9,7 @@
 // `Table<T>` surface), not hand-written SQL. Row shapes are declared inline here.
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
+import { deriveFeatureDelivery, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
   ensureFreshHeadRun,
@@ -85,10 +86,11 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
   (process.env.NANO_PR_MERGE_ADMIN ?? "0").trim().toLowerCase(),
 );
 
-// The `senior:pr-review` agent prompt is no longer read by the host: it is authored in the
-// model as a `{{review-round}}` deploy-time template (see `models.templates` in nano.app.json)
-// substituted into the task's `io.nanobpm.agentTask.task.prompt` header. The host only carries
-// runtime PR identity + the round counter now.
+// The `senior:pr-review` agent prompt is no longer read by the host: it is a generic resource
+// (`prompts/review-round.md`, deployed via a `models` glob in nano.app.json) linked into the task
+// as `<zeebe:linkedResource resourceId="review-round.md" bindingType="latest" linkName="prompt"/>`
+// and resolved by the engine at job activation. The host only carries runtime PR identity + the
+// round counter now.
 
 const now = () => new Date().toISOString();
 
@@ -1248,6 +1250,39 @@ export async function pollDelivery(data: DataLayer) {
   }
 }
 
+/** Reconcile each in-flight FEATURE run against its handed-off PR (fix: Feature history stuck at
+ * `converging`). A feature run ends its own process with `status = converging` and its PR's live
+ * outcome (merged / converged / abandoned) thereafter lives only on the `pull_requests` row keyed
+ * by `pr_key` — so the Feature history grid, which reads `feature_runs`, showed `converging` forever.
+ * This is the `feature_runs` twin of `pollDelivery` (which does the same for epic `plans`): for each
+ * run currently `converging` with a `pr_key`, project the PR's status onto `feature_runs.status`
+ * (advancing it to the matching terminal outcome once the PR settles) + a human `delivery_label`.
+ * Never touches a run that isn't `converging` — additive/derived only, idempotent, best-effort. */
+export async function pollFeatureDelivery(data: DataLayer) {
+  // Preload every PR status once per pass (mirrors pollDelivery — avoids an N+1 `prs(data).get`).
+  const statusByPrKey = new Map<string, string>();
+  for (const pr of await prs(data).all()) statusByPrKey.set(pr.pr_key, pr.status);
+  // Only `converging` runs are ever reconciled — query them via the `feature_runs(status)` index
+  // (db/migrations/028) instead of scanning all history, so this pass stays O(in-flight), not
+  // O(total runs), as the table grows.
+  for (const run of await featureRuns(data).find({ status: "converging" })) {
+    if (!run.pr_key) continue;
+    try {
+      const prStatus = statusByPrKey.get(run.pr_key) ?? null;
+      const { status, label } = deriveFeatureDelivery(prStatus);
+      if (run.status !== status || run.delivery_label !== label) {
+        await featureRuns(data).update(run.feature_key, {
+          status,
+          delivery_label: label,
+          updated_at: now(),
+        });
+      }
+    } catch (err) {
+      console.error(`[poller] feature delivery ${run.feature_key}: ${err}`);
+    }
+  }
+}
+
 /** One full poll pass: advance the review stage, the merge stage, the wave-merge barrier, and
  * (when the engine REST endpoint is supplied) the job-activation visibility pass and the
  * technical-incident surfacing pass. Called on the self-scheduling loop in `main.ts`. */
@@ -1261,6 +1296,7 @@ export async function pollOnce(
   await pollMerges(data, engine, token);
   await pollWaveGates(data, engine, token);
   await pollDelivery(data);
+  await pollFeatureDelivery(data);
   if (engineRest) {
     await pollJobActivation(data, engineRest.restAddress, engineRest.token);
     await pollIncidents(data, engineRest.restAddress, engineRest.token);

package/db/migrations/030_feature_delivery.sql

@@ -0,0 +1,21 @@
+-- Feature-run delivery reconcile (fix: Feature history stuck at `converging`).
+--
+-- A single-issue feature run hands its opened PR to the convergence loop and then
+-- ENDS with `feature_runs.status = 'converging'` (terminal for the run's own
+-- process). The PR's live outcome (merged / converged / abandoned) thereafter
+-- lives only on the `pull_requests` row keyed by `pr_key`, so the Feature history
+-- grid — which reads `feature_runs` — showed `converging` forever even after the
+-- PR merged. The epic side already solves the identical gap for `plans` via
+-- `pollDelivery` → `plans.delivery` (issue #171); this brings the same reconcile
+-- to `feature_runs`.
+--
+-- `delivery_label` is the human rollup detail projected onto the row by
+-- `pollFeatureDelivery` (e.g. "merged", "converged (not merged)", "PR abandoned",
+-- or an in-flight sub-state like "waiting_review"). It is also written by
+-- `pr.record-blocked-ack` with the operator's disposition note (e.g. "operator:
+-- <note>" / "acknowledged") when a blocked run is acknowledged. NULL until there
+-- is a signal (no `pr_key`, or the run never reached `converging` and was not
+-- acknowledged). The reconciled terminal
+-- outcome is written to `status` itself (converging → merged | converged |
+-- abandoned) so the existing Status column becomes accurate.
+ALTER TABLE feature_runs ADD COLUMN delivery_label TEXT;

package/e2e/feature-run.e2e.ts

@@ -55,6 +55,7 @@ interface FeatureRow {
   process_key: string | null;
   status: string;
   pr_key: string | null;
+  delivery_label: string | null;
 }
 interface PrRow {
   pr_key: string;
@@ -160,16 +161,40 @@ describe("single-issue feature run (#172 — feature.bpmn)", () => {
     );
   });
 
-  test("blocked: a non-opened result never enrolls a PR and settles blocked", async () => {
+  test("blocked: parks at the operators' user task (non-terminal), never enrolls a PR, settles on ack", async () => {
     await withApp(
       { "senior:feature": () => ({ status: "blocked", summary: "could not proceed" }) },
       { baseBranch: "epic/e2e", converge: true },
-      async ({ app, featureKey }) => {
+      async ({ app, featureKey, processKey }) => {
         const flows = takenFlows(app);
-        assert.ok(flows.includes("gw-converge->End"), "a blocked run takes the raise-only branch even with converge=true");
-        const run = await featureRow(app, featureKey);
-        assert.equal(run.status, "blocked");
-        assert.equal(run.pr_key, null);
+        assert.ok(
+          flows.includes("gw-blocked->feature-blocked"),
+          `a blocked run routes to the operators' user task, not the converge gateway (flows: ${flows.join(", ")})`,
+        );
+        assert.ok(!flows.includes("gw-blocked->gw-converge"), "a blocked run never reaches the converge gateway");
+
+        // The instance stays alive parked at a completable native user task (operators inbox) — a
+        // blocked run is never a silent dead-end — and the row is NON-terminal `awaiting_operator`
+        // so a re-dispatch of the same issue short-circuits (no orphaned parallel run).
+        const tasks = await app.engine.searchUserTasks({ processInstanceKey: processKey });
+        const task = tasks.find((t) => t.elementId === "feature-blocked") as InboxTask | undefined;
+        assert.ok(task?.userTaskKey, "the blocked outcome parked a completable native user task");
+
+        const parked = await featureRow(app, featureKey);
+        assert.equal(parked.status, "awaiting_operator", "while parked the run is non-terminal awaiting_operator");
+        assert.equal(parked.pr_key, null);
+        const prs = await app.db.table<PrRow>("pull_requests", "pr_key").find({});
+        assert.equal(prs.length, 0, "a blocked run never enrolled a PR into the convergence loop");
+
+        // Acknowledging the blocked run records the note, settles it terminal `blocked`, and ends.
+        await app.engine.completeUserTask(task!.userTaskKey, { note: "reassigned to a human" });
+        await app.settle();
+        const flows2 = takenFlows(app);
+        assert.ok(flows2.includes("feature-blocked->record-blocked-ack"), "ack routes through record-blocked-ack");
+        assert.ok(flows2.includes("record-blocked-ack->End"), "the acknowledged run ends");
+        const settled = await featureRow(app, featureKey);
+        assert.equal(settled.status, "blocked", "the acknowledged run settles at terminal blocked");
+        assert.equal(settled.delivery_label, "operator: reassigned to a human", "the operator note is recorded");
       },
     );
   });