@nanobpm/nano-workforce 0.189.2 → 0.189.3

package/CHANGELOG.md

@@ -1,3 +1,9 @@
+## [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/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,