@nanobpm/nano-workforce 0.189.2 → 0.190.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.190.0](https://github.com/nanobpm/nano-workforce/compare/v0.189.3...v0.190.0) (2026-09-21)
+
+### Features
+
+* **ui:** make Convergence auto-merge opt-in ([#752](https://github.com/nanobpm/nano-workforce/issues/752)) ([db18b17](https://github.com/nanobpm/nano-workforce/commit/db18b17ceadc1cccd48e50a12c98d867f657f3d5)), closes [#751](https://github.com/nanobpm/nano-workforce/issues/751)
+
+## [0.189.3](https://github.com/nanobpm/nano-workforce/compare/v0.189.2...v0.189.3) (2026-09-20)
+
+### Bug Fixes
+
+* **feature:** reconcile a COMPLETED feature-run engine instance to terminal (raise-only runs wedge in Active) ([#809](https://github.com/nanobpm/nano-workforce/issues/809)) ([39add8c](https://github.com/nanobpm/nano-workforce/commit/39add8c81f419ef41c7c4596adb1f5ad05c80e5a)), closes [#624](https://github.com/nanobpm/nano-workforce/issues/624) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#808](https://github.com/nanobpm/nano-workforce/issues/808) [#3](https://github.com/nanobpm/nano-workforce/issues/3) [704/#497](https://github.com/704/nano-workforce/issues/497) [503/#704](https://github.com/503/nano-workforce/issues/704) [#810](https://github.com/nanobpm/nano-workforce/issues/810) [#810](https://github.com/nanobpm/nano-workforce/issues/810) [#806](https://github.com/nanobpm/nano-workforce/issues/806)
+
 ## [0.189.2](https://github.com/nanobpm/nano-workforce/compare/v0.189.1...v0.189.2) (2026-09-18)
 
 ### Bug Fixes

package/README.md

@@ -285,9 +285,10 @@ branch before escalating (`NANO_PR_MAX_CI_FIX_ROUNDS`, default 3). Conflicts, an
 exhausted budget, or an agent that can't fix the build escalate to a human; answer in
 the UI and the process re-arms and retries.
 
-A single submission can pin **review-only** regardless of the global default by
-passing `convergeOnly: true` on the `start/convergence-loop` request — the PR stops at
-`converged` and is never handed to `merge-loop`, even with `NANO_PR_AUTO_MERGE` on.
+A single submission can choose its merge behavior explicitly with the positive
+`autoMerge` field on the `start/convergence-loop` request: `false` stops at
+`converged` regardless of the global default, while `true` enables the merge-loop
+after convergence only when `NANO_PR_AUTO_MERGE` is enabled.
 
 ### Fleet mode: hand it an issue (plan → implement → converge)
 
@@ -356,7 +357,7 @@ agent at that URL to author, compile, and submit a graph unaided. See
 | `NANO_PR_POLL_MS` | `60000` | review-ready poll interval |
 | `NANO_PR_MAX_ROUNDS` | `20` | default cap: escalate after N rounds (per-submit override via the form / the `maxRounds` field on `start/convergence-loop`; clamped 1–100) |
 | `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `GET /app/api/agent`, `/app/api/version`, `/app/api/status`); unset = open |
-| `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the `convergeOnly` field on `start/convergence-loop` (`true` forces review-only for that PR) |
+| `NANO_PR_AUTO_MERGE` | `1` | after convergence, run the merge stage; `0` = stop at `converged` (review-only). Per-submit override via the positive `autoMerge` field on `start/convergence-loop` |
 | `NANO_PR_MERGE_METHOD` | `squash` | merge method: `squash`, `merge`, or `rebase` |
 | `NANO_PR_MERGE_ADMIN` | `0` | pass `--admin` to override failing non-required checks (use with care) |
 | `NANO_PR_MAX_CI_FIX_ROUNDS` | `3` | max `senior:fix-ci` attempts to green a `blocked` PR before escalating; `0` disables (escalate immediately), clamped 0–20 |

package/SPEC.md

@@ -582,10 +582,10 @@ same `prKey`, sharing the datasource and poller. It merges the PR, honouring
 merge-queue branches and cross-PR dependencies, and reuses the review stage's
 escalation machinery for anything it can't resolve autonomously.
 
-A per-submit `convergeOnly: true` on the `start/convergence-loop` request pins that PR
-to review-only regardless of the global default: `pr.finalize` reads the flag off the
-instance and rests the PR at `converged` without starting `merge-loop`. The flag only
-ever narrows (it never forces the merge stage on when `NANO_PR_AUTO_MERGE` is off).
+A per-submit `autoMerge` setting on the `start/convergence-loop` request is the preferred
+positive control: `false` pins that PR to review-only regardless of the global default, while
+`true` enables the merge-loop after convergence only when `NANO_PR_AUTO_MERGE` is on. No per-submit
+setting forces the merge stage on when the global toggle is off.
 
 Flow:
 
@@ -691,7 +691,7 @@ queries skip (`merging`), so a slow pass can't double-signal.
 | `NANO_PR_POLL_MS` | 60000 | poll interval |
 | `NANO_PR_MAX_ROUNDS` | 20 | default round cap (per-submit `maxRounds` override, clamped 1–100) |
 | `NANO_PR_WEBHOOK_SECRET` | — | optional shared secret (`x-hook-secret`) for guarded operations (e.g. `/app/api/agent`, `/app/api/version`, `/app/api/status`) |
-| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `convergeOnly: true` override) |
+| `NANO_PR_AUTO_MERGE` | 1 | run the merge stage after convergence (`0` = review-only; per-submit `autoMerge: false` override) |
 | `NANO_PR_MERGE_METHOD` | squash | `squash` \| `merge` \| `rebase` |
 | `NANO_PR_MERGE_ADMIN` | 0 | pass `--admin` on merge |
 | `NANO_PR_REVIEW_WAIT_TIMEOUT` | PT30M | ISO-8601 wait before a stalled review escalates (timer arm of the `wait-review` event-based gateway); malformed → default |

package/app/agentGuide.ts

@@ -31,7 +31,7 @@ const RAW_GUIDE: string = (() => {
       "Key endpoints (under the app control-API base `__BASE__`):",
       "- `GET /status` — every PR in flight, with its engine `processKey` and any open escalation.",
       "- `GET /version` — which code is live.",
-      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, convergeOnly?, maxRounds?, dependsOn? }`).",
+      "- `POST /actions/start/convergence-loop` — submit a PR (`{ pr, autoMerge?, maxRounds?, dependsOn? }`; `autoMerge` is the positive per-request merge control).",
       "- `POST /actions/start/plan-fanout` — submit an epic (`{ issue, baseBranch }` or `{ url, baseBranch }`; base is required — a missing `epic/*` base is auto-created, and `confirmDefaultBase`/`allowSharedBase` gate the default-branch and shared-base cases — see ADR 0003).",
       "- `POST /actions/complete-user-task` — answer an escalation (`{ userTaskKey, variables }`); the parked user task's key comes from `GET /status`/the Tasks inbox, and the typed variables match its `.form` (e.g. a PR escalation's `{ answer }`).",
       "- `POST /actions/message` — publish a BPMN message (optionally correlated) into the engine.",

package/app/deliveryGraphVocabulary.ts

@@ -67,7 +67,7 @@ export interface WaitProbeEntry {
 export interface ConnectorTargetEntry {
   target: string;
   status: "real" | "forward-declared";
-  convergeOnlyDefault?: boolean;
+  autoMergeDefault?: boolean;
   summary: string;
 }
 
@@ -143,7 +143,7 @@ const NODE_KIND_DETAIL: Record<string, Omit<NodeKindEntry, "kind">> = {
     mayEmit: true,
     summary:
       "An automated, side-effecting outbound action. `payload` for a converge target is " +
-      "`{ pr, convergeOnly?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
+      "`{ pr, autoMerge?, dependsOn? }` (`pr` may be a literal `owner/repo#N`, a `<node>.pr` fact " +
       "reference, or omitted to auto-bind the single incoming `pr` fact). Carries a `dedupeKey` " +
       "(at-least-once safe). See connectorTargets for which targets are real vs. forward-declared.",
   },
@@ -218,13 +218,13 @@ const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
   {
     target: CONVERGE_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_TARGET),
-    summary: "Converge-only: drive review convergence and STOP at `converged`, never handing off to the merge loop.",
+    autoMergeDefault: !convergeOnlyForTarget(CONVERGE_TARGET),
+    summary: "Review-only: drive convergence and STOP at `converged`, never handing off to the merge loop.",
   },
   {
     target: CONVERGE_MERGE_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
+    autoMergeDefault: !convergeOnlyForTarget(CONVERGE_MERGE_TARGET),
     summary:
       "Unit-level land: drive review convergence AND the merge loop, landing the PR onto its OWN base branch " +
       "(for a unit inside an epic that base is the epic integration branch, never `main` directly).",
@@ -232,7 +232,7 @@ const REAL_CONNECTOR_TARGETS: ConnectorTargetEntry[] = [
   {
     target: MERGE_MAIN_TARGET,
     status: "real",
-    convergeOnlyDefault: convergeOnlyForTarget(MERGE_MAIN_TARGET),
+    autoMergeDefault: !convergeOnlyForTarget(MERGE_MAIN_TARGET),
     summary:
       "Graph-level top-level land (two-level merge, ADR 0006 §3): land the graph/epic INTEGRATION PR onto `main`. " +
       "Dispatch-identical to `converge-merge`; the distinction is the LEVEL, kept a first-class literal.",

package/app/feature.test.ts

@@ -8,7 +8,7 @@
 import { after, test } from "node:test";
 import { assertEquals } from "#test-assert";
 import { withTrackingViews } from "../test/trackingViews.ts";
-import { FEATURE_PROCESS_ID, FEATURE_TERMINAL_STATUSES, featureTaskId, startFeature } from "./feature.ts";
+import { FEATURE_PROCESS_ID, FEATURE_TERMINAL_STATUSES, featureTaskId, foldCompletedFeatureRun, startFeature } from "./feature.ts";
 
 // `startFeature` now fetches the issue title (issue #248) via the GitHub transport. Force the token
 // transport with no token so the fetch is a hermetic no-op (returns null) — no `gh` subprocess, no
@@ -55,6 +55,28 @@ function memData(stores: Record<string, { rows: any[]; key: string }>) {
     // rows — a base row with no explicitly-seeded `derived_status` folds `derived_status := status`.
     table: withTrackingViews((name: string, key: string) =>
       memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key)),
+    // Minimal `open().exec()` for the guarded CAS folds (`foldCompletedFeatureRun`), so the re-seed-
+    // window regression below can drive the real CAS predicate (same feature_key + process_key +
+    // status = the observed transient, now a bound param) against the mid-reseed row.
+    open: () => ({
+      exec: (sql: string, params: any[]) => {
+        if (!/UPDATE "feature_runs" SET .* WHERE "feature_key" = \? AND "process_key" = \? AND "status" = \?/.test(sql)) {
+          throw new Error(`memData.exec: unhandled sql: ${sql}`);
+        }
+        const [status, label, updated_at, feature_key, process_key, expect_status] = params;
+        const rows = stores.feature_runs?.rows ?? [];
+        let changed = 0;
+        for (const r of rows) {
+          if (r.feature_key === feature_key && r.process_key === process_key && r.status === expect_status) {
+            r.status = status;
+            r.delivery_label = label;
+            r.updated_at = updated_at;
+            changed += 1;
+          }
+        }
+        return Promise.resolve({ changed });
+      },
+    }),
   } as any;
 }
 
@@ -277,6 +299,57 @@ test("startFeature: a settled run is restarted in place (status reset, pr/outcom
   assertEquals(row.process_key, "PI-2");
 });
 
+// Issue #808 (TOCTOU review follow-up, RED first): the re-seed of a settled run flips `status` back to
+// `running` but installs the NEW process key only AFTER `createInstance` returns. If the OLD
+// `process_key` were left in place across that await, the poller's guarded fold
+// (`foldCompletedFeatureRun`, keyed on the OLD key + `status='running'`) would still match the fresh
+// incarnation mid-reseed and terminalize it. The reset now clears `process_key` to NULL atomically
+// with the status reset, so throughout the window the guard matches ZERO rows. This test fires the
+// exact interval: inside the `createInstance` stub (the window after the reset, before the new key is
+// written) it runs the real CAS against the OLD key and asserts it is a no-op and the row is untouched.
+test("startFeature: the re-seed window nulls process_key so a concurrent COMPLETED fold on the OLD key is a no-op (issue #808)", async () => {
+  const stores = {
+    feature_runs: {
+      rows: [{
+        feature_key: "owner/repo#42",
+        repo: "owner/repo",
+        issue_number: 42,
+        status: "opened", // a prior settled incarnation
+        process_key: "PI-OLD",
+        pr_key: "owner/repo#100",
+        delivery_label: "PR raised",
+        converge: 0,
+        auto_merge: 0,
+      }],
+      key: "feature_key",
+    },
+  };
+  const data = memData(stores);
+  let windowStatus: string | undefined;
+  let windowProcessKey: string | undefined;
+  let foldWon: boolean | undefined;
+  const engine = {
+    // Runs DURING the re-seed window: the row has been reset to `running` but the new key is not yet
+    // installed. Simulate the poller's guarded fold on the OLD key racing here.
+    createInstance: async () => {
+      const row = stores.feature_runs.rows[0];
+      windowStatus = row.status;
+      windowProcessKey = row.process_key;
+      foldWon = await foldCompletedFeatureRun(data, "owner/repo#42", "PI-OLD", "opened", "PR raised");
+      return { processInstanceKey: "PI-NEW" };
+    },
+  } as any;
+  await startFeature(data, engine, PARSED, "main", false, false);
+  // Mid-reseed the row was `running` with process_key CLEARED, so the OLD-key guard matched nothing.
+  assertEquals(windowStatus, "running");
+  assertEquals(windowProcessKey, null);
+  assertEquals(foldWon, false); // the concurrent fold was a no-op — the fresh incarnation is safe
+  const row = stores.feature_runs.rows[0];
+  // The run finished the reseed uncorrupted: still `running`, now carrying the NEW key.
+  assertEquals(row.status, "running");
+  assertEquals(row.process_key, "PI-NEW");
+});
+
 test("startFeature: an in-place restart clears a stale acknowledged_at (re-earn the tick-off)", async () => {
   const stores = {
     feature_runs: {

package/app/feature.ts

@@ -167,6 +167,23 @@ export function deriveFeatureDelivery(prStatus: string | null): FeatureDeliveryR
   }
 }
 
+/** Reconciled TERMINAL outcome for a feature run whose ENGINE instance read COMPLETED while the base
+ * `status` is still the non-terminal `running` (issue #808). A normally-completing raise-only (or
+ * nothing-to-do) run has no PR loop to reconcile it — `pollFeatureDelivery`'s converging reconcile and
+ * `instanceTracking`'s TERMINATED → `abandoned` edge both skip it — so it would wedge in the Active
+ * bucket forever (the "poller owns liveness; never leave a run on a status no pass scans" rule,
+ * AGENTS.md). The terminal is derived from the run's own durable completion shape, ENGINE-truth-gated
+ * by the caller (only ever applied on a real COMPLETED read): a run that raised a PR (its `pr_key`
+ * survives on the row from `record-feature`) folds to `opened`; a run that raised none folds to
+ * `skipped`. Pure and idempotent — the caller writes only when this differs from the current status. */
+export interface FeatureCompletion {
+  status: FeatureRunStatus;
+  label: string;
+}
+export function deriveFeatureCompletion(run: Pick<FeatureRun, "pr_key">): FeatureCompletion {
+  return run.pr_key ? { status: "opened", label: "PR raised" } : { status: "skipped", label: "nothing to do" };
+}
+
 /** The `feature-escalation` user-task element id (feature.bpmn) — the native operator wait a run
  * parks on when the agent escalates. `pollUserTasks` reads the engine's open task for this element to
  * project it onto the `user_tasks` Tasks inbox. */
@@ -236,6 +253,39 @@ export const FEATURE_BLOCKED_ELEMENT = "feature-blocked";
  * that reproduces the reconciler bypass). */
 export const featureRuns = (data: DataLayer) => data.table<FeatureRun>("feature_runs", "feature_key");
 
+/** Guarded CAS fold of a settled feature run to its terminal delivery `status` + `delivery_label`
+ * (issue #808). This is NOT a blind `featureRuns(data).update(feature_key, …)`: the poller reads the
+ * engine instance state (`searchProcessInstances`) BEFORE it writes, and in that window `startFeature`
+ * can re-seed the SAME `feature_key` row to a FRESH `running` incarnation with a NEW `process_key`
+ * (the old instance completed, a resubmit relaunched). A blind write keyed on `feature_key` alone
+ * would clobber that newer incarnation to `opened`/`skipped` while its new instance is still active.
+ * The single guarded UPDATE requires the row to still be the exact incarnation we read (same
+ * `feature_key` + `process_key` + `status = expectStatus`, the transient the caller observed — the
+ * normally-completing fold reads `running`; the mid-handoff reconcile — {@link pollFeatureDelivery}'s
+ * handoff edge — reads `opened`), so a lost race matches zero rows and is a no-op. This is safe across
+ * the FULL re-seed window because `startFeature` clears `process_key` to NULL atomically with its
+ * `status = 'running'` reset (issue #808) and only reinstalls the new key after `createInstance`
+ * returns — so throughout the interval the fresh incarnation carries no key that this guard's OLD
+ * `process_key` predicate can match. Mirrors the `markProposalExpired`/`claimRunForLaunch` CAS pattern.
+ * Returns whether the write flipped a row (`res.changed > 0`) — `false` means a concurrent re-seed won
+ * the race, OR the observed transient had already advanced. */
+export async function foldCompletedFeatureRun(
+  data: DataLayer,
+  featureKey: string,
+  processKey: string,
+  status: string,
+  label: string,
+  expectStatus: FeatureRunStatus = "running",
+): Promise<boolean> {
+  const res = await data
+    .open()
+    .exec(
+      `UPDATE "feature_runs" SET "status" = ?, "delivery_label" = ?, "updated_at" = ? WHERE "feature_key" = ? AND "process_key" = ? AND "status" = ?`,
+      [status, label, new Date().toISOString(), featureKey, processKey, expectStatus],
+    );
+  return res.changed > 0;
+}
+
 /** A `feature_runs` row as seen through its derived tracking VIEW (`feature_runs__tracking`): the base
  * columns plus urban's ADR-0065 `derived_status`, which FOLDS the reconciler's terminal edge
  * (out-of-band terminate / in-app cancel → `abandoned`) over the worker-owned transient. Since urban
@@ -380,6 +430,23 @@ export async function startFeature(
       base_branch: base,
       issue_url: parsed.url,
       title,
+      // Clear the OLD process key ATOMICALLY with the status reset (issue #808). The re-seed flips the
+      // row back to `running` but does not install the new process key until AFTER `createInstance`
+      // returns below; leaving the stale `process_key` in place across that await opens a TOCTOU window
+      // where the poller's guarded fold (`foldCompletedFeatureRun`, keyed on the OLD process_key +
+      // `status='running'`) would still match this fresh incarnation and terminalize it to
+      // `opened`/`skipped`. Nulling it here — exactly as the insert branch below does — makes that
+      // guard match zero rows during the window, so the race collapses to a no-op. The new key is
+      // written back once the instance is created.
+      //
+      // DEFERRED (issue #810): nulling `process_key` across the `createInstance` await also opens a
+      // SECOND, distinct window — a concurrent `startFeature` for the same key sees `process_key=null`
+      // and, because the already-active guard is null-blind by design, can launch a DUPLICATE instance
+      // that orphans the first. This is a pre-existing intake-path race (the fresh-insert branch below
+      // already nulls the key the same way), out of scope for this reconciliation PR. The race-free fix
+      // — a launch-generation claim / serialized re-seed-and-recheck on the intake path — is tracked in
+      // issue #810; do NOT expand this PR back into the intake path to fix it here.
+      process_key: null,
       pr_key: null,
       converge: converge ? 1 : 0,
       auto_merge: autoMerge ? 1 : 0,