@nanobpm/nano-workforce 0.61.0 → 0.62.0

package/CHANGELOG.md

@@ -1,3 +1,17 @@
+# [0.62.0](https://github.com/nanobpm/nano-workforce/compare/v0.61.1...v0.62.0) (2026-08-13)
+
+
+### Features
+
+* **feature-prompt:** claim the issue with a comment before starting work ([#207](https://github.com/nanobpm/nano-workforce/issues/207)) ([b1b23c9](https://github.com/nanobpm/nano-workforce/commit/b1b23c9928704616aa2173cfa056668a11d32e1c))
+
+## [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)
 
 

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 {
@@ -104,6 +104,8 @@ test("startFeature: seeds the single task slice + base-branch brief onto the ins
   assertEquals(v.task.prompt.includes("owner/repo#42"), true);
   assertEquals(v.converge, true);
   assertEquals(v.autoMerge, false);
+  // A single-issue run owns its issue, so the agent is told it may claim it (epic slices never set this).
+  assertEquals(v.claimIssue, true);
   assertEquals(v.baseBranch, "epic/x");
   // The brief is the authoritative base-branch override the agent gets via appendPrompt.
   assertEquals(v.baseBranchBrief.includes("epic/x"), true);
@@ -132,6 +134,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,
     });
@@ -148,6 +202,11 @@ export async function startFeature(
       // merge-loop. `converge=false` ⇒ merge is moot.
       converge,
       autoMerge,
+      // A single-issue feature run OWNS its issue (the whole issue is the slice), so the agent may
+      // claim it with a "starting work" comment on a first run (prompts/feature.md). Epic slices
+      // (plan-fanout) deliberately DO NOT set this — their `issue` is the shared parent epic, which
+      // must never be claimed per-slice.
+      claimIssue: true,
       // Seed the agent-result variables so the escalation loop + record worker can reference them
       // before the first `senior:feature` job completes (the harness merges the real values in).
       answer: null,

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/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,
@@ -1249,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`. */
@@ -1262,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");
       },
     );
   });

package/nano.app.json

@@ -132,6 +132,10 @@
       "taskType": "pr.record-feature",
       "handler": "workers/record-feature/worker.ts"
     },
+    {
+      "taskType": "pr.record-blocked-ack",
+      "handler": "workers/record-blocked-ack/worker.ts"
+    },
     {
       "taskType": "pr.converge-feature",
       "handler": "workers/converge-feature/worker.ts"

package/package.json

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

@@ -59,11 +59,11 @@
           "source": "app",
           "table": "feature_runs",
           "orderBy": { "field": "updated_at", "dir": "desc" },
-          "filter": [{ "field": "status", "in": ["running"] }]
+          "filter": [{ "field": "status", "in": ["running", "awaiting_operator"] }]
         },
         "tabs": [
-          { "label": "Active", "filter": [{ "field": "status", "in": ["running"] }] },
-          { "label": "History", "filter": [{ "field": "status", "in": ["opened", "converging", "blocked", "skipped", "failed", "abandoned"] }] },
+          { "label": "Active", "filter": [{ "field": "status", "in": ["running", "awaiting_operator"] }] },
+          { "label": "History", "filter": [{ "field": "status", "in": ["opened", "converging", "merged", "converged", "blocked", "skipped", "failed", "abandoned"] }] },
           { "label": "All", "filter": [] }
         ],
         "columns": [
@@ -71,6 +71,7 @@
           { "field": "status", "header": "Status", "link": { "kind": "processExplorer", "keyField": "process_key" } },
           { "field": "base_branch", "header": "Base branch" },
           { "field": "pr_key", "header": "PR", "link": { "kind": "page", "page": "home", "keyField": "pr_key" } },
+          { "field": "delivery_label", "header": "Delivery" },
           { "field": "converge", "header": "Converge" },
           { "field": "auto_merge", "header": "Auto-merge" },
           { "field": "outcome", "header": "Outcome" },

package/prompts/feature.md

@@ -22,16 +22,44 @@ You have `gh` / git authenticated for the target repository.
 
 Always use the branch **`feat/<task.id>`**. Because a resumed run gets a fresh
 process with no memory of your last run, the branch name MUST be derivable from
-`task.id` alone. On start, check whether it already exists on the remote
-(`git ls-remote --heads origin feat/<task.id>` or
-`gh pr list --head feat/<task.id> --state all`):
+`task.id` alone. On start, check whether it already exists on the remote with
+`git ls-remote --heads origin feat/<task.id>` — a non-empty result means the
+branch exists. Use this ref check as the authoritative first-run/resume signal:
+a remote branch can exist without any PR, so `gh pr list --head feat/<task.id> --state all`
+is reliable only as a *supplementary* PR lookup once `git ls-remote` has
+established the branch exists, never as the existence check itself:
 
 - **It does not exist** → this is a first run. Branch off the base branch (see
   the note below — usually the repository default branch, but an epic may pin an
-  integration branch in your appended task context).
+  integration branch in your appended task context). **Claim the issue now** — see
+  below.
 - **It exists** → this is a **resume**. `git fetch` and check it out, read its diff
   and any open (draft) PR, and **continue from there** — do not restart from
-  scratch. Fold in `variables.answer` as the guidance you were waiting on.
+  scratch. Fold in `variables.answer` as the guidance you were waiting on. Do
+  **not** re-claim — you already announced this run on your first pass.
+
+## Claim your issue on a first run (only when `variables.claimIssue` is true)
+
+So humans and other agents can see the work has been picked up, announce yourself
+on the issue **before implementing** — but ONLY on a first run (your
+`feat/<task.id>` branch did not yet exist, per the check above) AND only when
+**`variables.claimIssue` is true**:
+
+```sh
+gh issue comment <variables.issue> --body-file - <<'BODY'
+🤖 Starting work on this issue — branch `feat/<task.id>`.
+BODY
+```
+
+- `variables.claimIssue` is set **only for single-issue feature runs**, where
+  `variables.issue` IS the issue you implement and close, so claiming it is
+  correct. **Epic slices leave it unset** — their `variables.issue` is the shared
+  *parent epic*, which must never be claimed per-slice; when `claimIssue` is not
+  true, **skip this step entirely**.
+- The branch-existence check above is what makes this idempotent: a resumed run
+  (branch already exists) never re-claims, so the issue gets exactly one claim.
+- It is a courtesy claim, **not a gate** — if the comment fails (e.g. a transient
+  `gh` error), carry on and implement anyway.
 
 ## Your base branch (default branch, unless the epic pins one)
 
@@ -44,14 +72,16 @@ against the wrong base will not be merged into the epic.
 
 ## What to do
 
-1. Clone / check out your base branch (first run — the default branch, or the
+1. Claim your issue if `variables.claimIssue` is true and this is a first run (see
+   above).
+2. Clone / check out your base branch (first run — the default branch, or the
    pinned epic branch if your context names one) or your existing
    `feat/<task.id>` branch (resume — see above).
-2. Implement `task.prompt`. Keep the change scoped to this slice only.
-3. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the
+3. Implement `task.prompt`. Keep the change scoped to this slice only.
+4. Commit (sign off — this repo family enforces DCO: `git commit -s`), push the
    branch, and open a pull request with `gh pr create` describing the slice and
    linking the parent issue (`Depends-on:`/`Closes` as appropriate).
-4. Clean up any scratch clone/worktree you created outside the commit.
+5. Clean up any scratch clone/worktree you created outside the commit.
 
 > **Do not request the Copilot review yourself.** When you open a *ready* PR the
 > app enrolls it into the review-convergence loop and requests the initial

package/resources/forms/feature-blocked.form

@@ -0,0 +1,17 @@
+{
+  "id": "feature-blocked",
+  "schemaVersion": 18,
+  "type": "default",
+  "components": [
+    {
+      "type": "text",
+      "text": "This single-issue feature run is **blocked** — the implementation agent could not open a PR (it gave up, or the escalation was abandoned / timed out). It landed in your inbox so a blocked run is never a silent dead-end. Review the outcome, then acknowledge to close the run.",
+      "label": "Blocked feature run"
+    },
+    {
+      "type": "textarea",
+      "key": "note",
+      "label": "Disposition note (what you did / why — recorded on the run)"
+    }
+  ]
+}

package/resources/processes/feature.bpmn

@@ -63,10 +63,35 @@
       <bpmn:incoming>w_done</bpmn:incoming>
       <bpmn:incoming>w_abandon</bpmn:incoming>
       <bpmn:incoming>w_sla</bpmn:incoming>
-      <bpmn:outgoing>f_toConvergeGw</bpmn:outgoing>
+      <bpmn:outgoing>f_toBlockedGw</bpmn:outgoing>
+    </bpmn:serviceTask>
+    <bpmn:exclusiveGateway id="gw-blocked" name="blocked?" default="f_notBlocked">
+      <bpmn:incoming>f_toBlockedGw</bpmn:incoming>
+      <bpmn:outgoing>f_blocked</bpmn:outgoing>
+      <bpmn:outgoing>f_notBlocked</bpmn:outgoing>
+    </bpmn:exclusiveGateway>
+    <bpmn:userTask id="feature-blocked" name="Blocked run (human)">
+      <bpmn:extensionElements>
+        <zeebe:formDefinition formId="feature-blocked" />
+        <zeebe:userTask />
+        <zeebe:assignmentDefinition candidateGroups="operators" />
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_blocked</bpmn:incoming>
+      <bpmn:outgoing>f_toBlockedAck</bpmn:outgoing>
+    </bpmn:userTask>
+    <bpmn:serviceTask id="record-blocked-ack" name="Record acknowledgement">
+      <bpmn:extensionElements>
+        <zeebe:taskDefinition type="pr.record-blocked-ack" />
+        <zeebe:ioMapping>
+          <zeebe:input source="=featureKey" target="featureKey" />
+          <zeebe:input source="=if (is defined(note)) then note else null" target="note" />
+        </zeebe:ioMapping>
+      </bpmn:extensionElements>
+      <bpmn:incoming>f_toBlockedAck</bpmn:incoming>
+      <bpmn:outgoing>f_blockedEnd</bpmn:outgoing>
     </bpmn:serviceTask>
     <bpmn:exclusiveGateway id="gw-converge" name="converge?" default="f_noConverge">
-      <bpmn:incoming>f_toConvergeGw</bpmn:incoming>
+      <bpmn:incoming>f_notBlocked</bpmn:incoming>
       <bpmn:outgoing>f_converge</bpmn:outgoing>
       <bpmn:outgoing>f_noConverge</bpmn:outgoing>
     </bpmn:exclusiveGateway>
@@ -80,6 +105,7 @@
     <bpmn:endEvent id="End" name="Done">
       <bpmn:incoming>f_noConverge</bpmn:incoming>
       <bpmn:incoming>f_toEndConverged</bpmn:incoming>
+      <bpmn:incoming>f_blockedEnd</bpmn:incoming>
     </bpmn:endEvent>
     <bpmn:sequenceFlow id="f_toEnsureBase" sourceRef="Start" targetRef="ensure-base-branch" />
     <bpmn:sequenceFlow id="f_toImplement" sourceRef="ensure-base-branch" targetRef="implement-task" />
@@ -94,7 +120,13 @@
     </bpmn:sequenceFlow>
     <bpmn:sequenceFlow id="w_abandon" name="abandon" sourceRef="w_gw_answer" targetRef="record-feature" />
     <bpmn:sequenceFlow id="w_sla" name="SLA auto-abandon" sourceRef="be_feature_sla" targetRef="record-feature" />
-    <bpmn:sequenceFlow id="f_toConvergeGw" sourceRef="record-feature" targetRef="gw-converge" />
+    <bpmn:sequenceFlow id="f_toBlockedGw" sourceRef="record-feature" targetRef="gw-blocked" />
+    <bpmn:sequenceFlow id="f_blocked" name="blocked" sourceRef="gw-blocked" targetRef="feature-blocked">
+      <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=featureStatus = "blocked"</bpmn:conditionExpression>
+    </bpmn:sequenceFlow>
+    <bpmn:sequenceFlow id="f_notBlocked" name="not blocked" sourceRef="gw-blocked" targetRef="gw-converge" />
+    <bpmn:sequenceFlow id="f_toBlockedAck" sourceRef="feature-blocked" targetRef="record-blocked-ack" />
+    <bpmn:sequenceFlow id="f_blockedEnd" sourceRef="record-blocked-ack" targetRef="End" />
     <bpmn:sequenceFlow id="f_converge" name="converge" sourceRef="gw-converge" targetRef="converge">
       <bpmn:conditionExpression xsi:type="bpmn:tFormalExpression">=converge = true and featureStatus = "opened" and prKey != null</bpmn:conditionExpression>
     </bpmn:sequenceFlow>
@@ -133,19 +165,31 @@
       <bpmndi:BPMNShape id="BPMNShape_record-feature" bpmnElement="record-feature">
         <dc:Bounds x="1116" y="80" width="100" height="80" />
       </bpmndi:BPMNShape>
-      <bpmndi:BPMNShape id="BPMNShape_gw-converge" bpmnElement="gw-converge" isMarkerVisible="true">
+      <bpmndi:BPMNShape id="BPMNShape_gw-blocked" bpmnElement="gw-blocked" isMarkerVisible="true">
         <dc:Bounds x="1316" y="95" width="50" height="50" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1308" y="76" width="67" height="14" />
+          <dc:Bounds x="1311" y="76" width="60" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_feature-blocked" bpmnElement="feature-blocked">
+        <dc:Bounds x="1466" y="400" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_record-blocked-ack" bpmnElement="record-blocked-ack">
+        <dc:Bounds x="1666" y="400" width="100" height="80" />
+      </bpmndi:BPMNShape>
+      <bpmndi:BPMNShape id="BPMNShape_gw-converge" bpmnElement="gw-converge" isMarkerVisible="true">
+        <dc:Bounds x="1491" y="95" width="50" height="50" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1483" y="76" width="67" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_converge" bpmnElement="converge">
-        <dc:Bounds x="1466" y="240" width="100" height="80" />
+        <dc:Bounds x="1666" y="240" width="100" height="80" />
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_End" bpmnElement="End">
-        <dc:Bounds x="1666" y="102" width="36" height="36" />
+        <dc:Bounds x="1866" y="102" width="36" height="36" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1667" y="83" width="34" height="14" />
+          <dc:Bounds x="1867" y="83" width="34" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNShape>
       <bpmndi:BPMNShape id="BPMNShape_be_feature_sla" bpmnElement="be_feature_sla">
@@ -173,15 +217,22 @@
           <dc:Bounds x="875" y="98" width="32" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_toConvergeGw" bpmnElement="f_toConvergeGw">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toBlockedGw" bpmnElement="f_toBlockedGw">
         <di:waypoint x="1216" y="120" />
         <di:waypoint x="1316" y="120" />
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_noConverge" bpmnElement="f_noConverge">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_notBlocked" bpmnElement="f_notBlocked">
         <di:waypoint x="1366" y="120" />
-        <di:waypoint x="1666" y="120" />
+        <di:waypoint x="1491" y="120" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1390" y="98" width="78" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_noConverge" bpmnElement="f_noConverge">
+        <di:waypoint x="1541" y="120" />
+        <di:waypoint x="1866" y="120" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1481" y="98" width="71" height="14" />
+          <dc:Bounds x="1668" y="98" width="71" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_abandon" bpmnElement="w_abandon">
@@ -200,22 +251,39 @@
           <dc:Bounds x="646" y="206" width="67" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
-      <bpmndi:BPMNEdge id="BPMNEdge_f_converge" bpmnElement="f_converge">
+      <bpmndi:BPMNEdge id="BPMNEdge_f_blocked" bpmnElement="f_blocked">
         <di:waypoint x="1341" y="145" />
-        <di:waypoint x="1341" y="280" />
-        <di:waypoint x="1466" y="280" />
+        <di:waypoint x="1341" y="440" />
+        <di:waypoint x="1466" y="440" />
         <bpmndi:BPMNLabel>
-          <dc:Bounds x="1346" y="206" width="60" height="14" />
+          <dc:Bounds x="1346" y="286" width="53" height="14" />
+        </bpmndi:BPMNLabel>
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_converge" bpmnElement="f_converge">
+        <di:waypoint x="1516" y="145" />
+        <di:waypoint x="1516" y="280" />
+        <di:waypoint x="1666" y="280" />
+        <bpmndi:BPMNLabel>
+          <dc:Bounds x="1521" y="206" width="60" height="14" />
         </bpmndi:BPMNLabel>
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_toAnswerGw" bpmnElement="w_toAnswerGw">
         <di:waypoint x="866" y="280" />
         <di:waypoint x="966" y="280" />
       </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_toBlockedAck" bpmnElement="f_toBlockedAck">
+        <di:waypoint x="1566" y="440" />
+        <di:waypoint x="1666" y="440" />
+      </bpmndi:BPMNEdge>
+      <bpmndi:BPMNEdge id="BPMNEdge_f_blockedEnd" bpmnElement="f_blockedEnd">
+        <di:waypoint x="1766" y="440" />
+        <di:waypoint x="1884" y="440" />
+        <di:waypoint x="1884" y="138" />
+      </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_f_toEndConverged" bpmnElement="f_toEndConverged">
-        <di:waypoint x="1566" y="280" />
-        <di:waypoint x="1684" y="280" />
-        <di:waypoint x="1684" y="138" />
+        <di:waypoint x="1766" y="280" />
+        <di:waypoint x="1884" y="280" />
+        <di:waypoint x="1884" y="138" />
       </bpmndi:BPMNEdge>
       <bpmndi:BPMNEdge id="BPMNEdge_w_sla" bpmnElement="w_sla">
         <di:waypoint x="816" y="338" />

package/workers/record-blocked-ack/worker.test.ts

@@ -0,0 +1,49 @@
+// Unit coverage for pr.record-blocked-ack — the operator acknowledged a blocked feature run.
+// It must settle the parked (non-terminal `awaiting_operator`) row at terminal `blocked` and record
+// the operator's disposition note into `delivery_label` so the same issue can be re-dispatched.
+import { test } from "node:test";
+import { assertEquals } from "#test-assert";
+import { noopLog } from "../../test/log.ts";
+import handler from "./worker.ts";
+
+function fakeApp(rows: Record<string, unknown>[]) {
+  const stores: Record<string, Record<string, unknown>[]> = { feature_runs: rows };
+  return {
+    data: {
+      table(name: string, key: string) {
+        const store = (stores[name] ??= []);
+        return {
+          get: (k: any) => Promise.resolve(store.find((r) => r[key] === k)),
+          find: (q: any) => Promise.resolve(store.filter((r) => Object.entries(q).every(([f, v]) => r[f] === v))),
+          insert: (row: any) => {
+            store.push(row);
+            return Promise.resolve(store.length);
+          },
+          update: (k: any, patch: any) => {
+            const row = store.find((r) => r[key] === k);
+            if (row) Object.assign(row, patch);
+            return Promise.resolve(row);
+          },
+        };
+      },
+    },
+    log: noopLog(),
+  } as any;
+}
+
+test("record-blocked-ack: settles the parked run at terminal blocked and records the operator note", async () => {
+  const rows = [{ feature_key: "owner/repo#7", status: "awaiting_operator", delivery_label: null }];
+  const app = fakeApp(rows);
+  const out = await handler({ variables: { featureKey: "owner/repo#7", note: "reassigned to a human" } } as any, app);
+  assertEquals(out, {});
+  assertEquals(rows[0].status, "blocked");
+  assertEquals(rows[0].delivery_label, "operator: reassigned to a human");
+});
+
+test("record-blocked-ack: a blank note falls back to an 'acknowledged' label", async () => {
+  const rows = [{ feature_key: "owner/repo#8", status: "awaiting_operator", delivery_label: null }];
+  const app = fakeApp(rows);
+  await handler({ variables: { featureKey: "owner/repo#8", note: "   " } } as any, app);
+  assertEquals(rows[0].status, "blocked");
+  assertEquals(rows[0].delivery_label, "acknowledged");
+});

package/workers/record-blocked-ack/worker.ts

@@ -0,0 +1,36 @@
+// pr.record-blocked-ack — an operator acknowledged a blocked single-issue feature run (issue #172).
+//
+// A `blocked` outcome from `record-feature` is routed to the `feature-blocked` operator user task,
+// which keeps the instance alive (parked at the operators' inbox) and holds the row at the
+// NON-terminal `awaiting_operator` status so a re-dispatch of the same issue short-circuits instead
+// of spawning an orphaned parallel run. This worker fires once the operator completes that task: it
+// settles the row at the TERMINAL `blocked` status and records the operator's disposition note, so
+// the same issue can be re-dispatched afterwards. Persistence goes through the record gateway
+// (`app.data`), never hand-written SQL — matching the other record-* workers.
+import type { AppJobHandler } from "@nanobpm/urban";
+import { featureRuns } from "../../app/feature.ts";
+
+interface In extends Record<string, unknown> {
+  featureKey: string;
+  note?: unknown;
+}
+
+const str = (v: unknown): string | undefined =>
+  typeof v === "string" && v.trim().length > 0 ? v.trim() : undefined;
+
+const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
+  const featureKey = job.variables.featureKey;
+  const note = str(job.variables.note);
+  const ts = new Date().toISOString();
+
+  await featureRuns(app.data).update(featureKey, {
+    status: "blocked",
+    delivery_label: note ? `operator: ${note}` : "acknowledged",
+    updated_at: ts,
+  });
+  app.log.info("record-blocked-ack", { featureKey, note: note ?? null });
+
+  return {};
+};
+
+export default handler;

package/workers/record-feature/worker.ts

@@ -45,15 +45,21 @@ const handler: AppJobHandler<In, Out> = async (job, app) => {
   // (the run is complete), just with no `pr_key` to converge.
   const prKey = parsed?.prKey ?? null;
   const featureStatus: FeatureRunStatus = status;
+  // A `blocked` outcome is routed (via the `blocked?` gateway) to the `feature-blocked` operator user
+  // task, which keeps the instance ALIVE until a human acknowledges it. Persist the row as the
+  // NON-terminal `awaiting_operator` for that parked window so a re-dispatch of the same issue
+  // short-circuits (no orphaned parallel run); `record-blocked-ack` writes the terminal `blocked`
+  // once the operator completes the task. `opened`/`skipped` are already terminal — persist as-is.
+  const rowStatus: FeatureRunStatus = status === "blocked" ? "awaiting_operator" : status;
   const ts = new Date().toISOString();
 
   await featureRuns(app.data).update(featureKey, {
-    status: featureStatus,
+    status: rowStatus,
     pr_key: prKey,
     outcome: summary ?? null,
     updated_at: ts,
   });
-  app.log.info("record-feature", { featureKey, featureStatus, prKey });
+  app.log.info("record-feature", { featureKey, featureStatus, rowStatus, prKey });
 
   return { featureStatus, prKey };
 };