@nanobpm/nano-workforce 0.189.1 → 0.189.3

package/app/stage.ts

@@ -109,12 +109,29 @@ export function deriveStage(run: StageInput): DerivedStage {
   };
 }
 
-/** The Active/History partition label (§5): `history` iff the row is in a truly-terminal status AND
+/** The Active/History partition label (§5): `history` iff the row is DISMISSABLE-terminal AND
  * acknowledged; otherwise `active` (live runs + terminal-but-UNACKNOWLEDGED runs). DERIVED on read from
  * the ONE `featureReadModel` `list_bucket` declaration — the same AST the VIEW compiles (migration 076),
  * NOT a write-time projection: the page's tabs filter the VIEW's derived `list_bucket`, and the stored
  * `feature_runs.list_bucket` base column is vestigial (retired as a write projection, issue #439). This
- * adapter is the TS lowering of that derivation, used off the write path (redispatch gating, tests). */
-export function deriveListBucket(status: string, acknowledgedAt: string | null | undefined): "active" | "history" {
-  return evalDerived<"active" | "history">("list_bucket", { [EFFECTIVE_STATUS_COLUMN]: status, acknowledged_at: acknowledgedAt ?? null });
+ * adapter is the TS lowering of that derivation, used off the write path (redispatch gating, tests).
+ *
+ * The `list_bucket` derivation is NOT a pure function of `status`/`acknowledged_at` alone: its
+ * DISMISSABLE-terminal predicate ({@link featureDismissableTerminal}) also reads `converge`/`pr_key` to
+ * carve out a mid-handoff `opened` transient (issue #808 follow-up). The optional `row` MUST therefore
+ * carry those two columns for any `opened` input, or the TS oracle diverges from the SQL VIEW for the
+ * mid-handoff case (SQL keeps it `active`; a converge/pr_key-blind oracle would drop an acked one to
+ * `history`) — the exact SQL/TS parity gap the PR #809 review flagged. Omit `row` only for a status
+ * that cannot be a mid-handoff `opened`. */
+export function deriveListBucket(
+  status: string,
+  acknowledgedAt: string | null | undefined,
+  row?: { pr_key?: string | null; converge?: number | boolean | null },
+): "active" | "history" {
+  return evalDerived<"active" | "history">("list_bucket", {
+    [EFFECTIVE_STATUS_COLUMN]: status,
+    acknowledged_at: acknowledgedAt ?? null,
+    pr_key: row?.pr_key ?? null,
+    converge: row?.converge ?? null,
+  });
 }

package/db/migrations/111_feature_read_model_ack_opened.sql

@@ -0,0 +1,61 @@
+-- Feature-run read model: widen the DISMISSABLE-terminal set of the `list_bucket` / `ack_open` derived
+-- columns to include `opened` (issue #808). SUPERSEDES 099's VIEW body — every DERIVED column is
+-- emitted VERBATIM from the ONE declaration in app/featureReadModel.ts, now with `list_bucket`/
+-- `ack_open` parameterised by the WIDER `FEATURE_ACK_TERMINAL_STATUSES` (= `STAGE_DONE_STATUSES` +
+-- `opened`) instead of `STAGE_DONE_STATUSES`. 099 is a MERGED, IMMUTABLE migration — never edited; this
+-- is a NEW migration superseding its VIEW body (the same pattern by which 099 superseded 081, 081
+-- superseded 076).
+--
+-- WHY. A raise-only feature run (converge not requested) ends at status `opened` after raising its PR.
+-- Issue #808 folds a COMPLETED such run's frozen `running` status to `opened` (`deriveFeatureCompletion`
+-- / `foldCompletedFeatureRun`) so it stops wedging in the Active bucket. But `opened` is deliberately a
+-- LIVE `PR open` pipeline STAGE, NOT a `Done` status, so it was excluded from `STAGE_DONE_STATUSES` —
+-- the set the `list_bucket`/`ack_open` derivations used. Result: the folded run had `ack_open=0` and
+-- `list_bucket='active'`, so `acknowledgeDone` still 409'd ("feature run is not terminal") and the run
+-- stayed wedged in Active — the exact wedge #808 aims to fix. This DECOUPLES the ack/History terminal
+-- set from the stage-`Done` set: `opened` is now dismissable into History (so a finished raise-only run
+-- can be ticked off) while the STAGE derivations still classify on `STAGE_DONE_STATUSES`, so the
+-- pipeline renders `opened` as `PR open`, never `Done`.
+--
+-- Every DERIVED column below is emitted VERBATIM from `featureReadModel.sqlSelectFor(col,
+-- { baseAlias: "fr" })` (which ALSO drives the runtime TS via `fnFor`); the `stage`/`stage_state`/
+-- `stage_skipped`/`attention` bodies are UNCHANGED from 099 and only `list_bucket`/`ack_open` gain the
+-- `'opened'` disjunct. The drift guard (app/featureReadModel.test.ts) fails if this file stops matching
+-- the declaration, and `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS unchanged from 099 EXCEPT the two `opened`-widened columns: the status-classifying columns
+-- still read the terminal-folded `feature_runs__tracking.derived_status`; base columns stay aliased
+-- identity pass-throughs; `acknowledged_at` still passes through so the read model can classify on it.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). `feature_runs__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 110.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."derived_status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'running'), 0) OR COALESCE(("fr"."derived_status" = 'escalated'), 0) OR COALESCE(("fr"."derived_status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."derived_status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND (NOT COALESCE(COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM feature_runs__tracking fr;

package/db/migrations/112_feature_read_model_opened_midhandoff.sql

@@ -0,0 +1,63 @@
+-- Feature-run read model: exclude a MID-HANDOFF `opened` run from the `list_bucket` / `ack_open`
+-- DISMISSABLE-terminal predicate (issue #808 follow-up). SUPERSEDES 111's VIEW body — every DERIVED
+-- column is emitted VERBATIM from the ONE declaration in app/featureReadModel.ts, now with `list_bucket`/
+-- `ack_open` driven by the `featureDismissableTerminal` PREDICATE instead of a plain status set. 111 is a
+-- MERGED, IMMUTABLE migration — never edited; this is a NEW migration superseding its VIEW body (the same
+-- pattern by which 111 superseded 099, 099 superseded 081, 081 superseded 076).
+--
+-- WHY. 111 (issue #808) made EVERY `opened` row dismissable-terminal so a finished raise-only run stops
+-- wedging in Active. But `record-feature` writes `status="opened"` for a converge-REQUESTED run TOO,
+-- BEFORE the `gw-converge` gateway routes it into `converge-feature` (which flips it to `converging`).
+-- In that in-between window the row reads `opened` while the feature engine instance is still ACTIVE, so
+-- 111's "any opened is dismissable" rule offered Dismiss on an in-flight convergence handoff — and a
+-- premature ack there stamps `acknowledged_at`, which would later drag a still-converging run to History.
+-- This is the SAME mid-flight failure mode the epic read model already guards against by excluding its
+-- own `converging` delivery (app/planReadModel.ts / app/listBucket.ts). The feature row distinguishes the
+-- transient from a finished run by its own columns: a converge-requested run that actually handed off
+-- carries `converge=1 AND pr_key IS NOT NULL` — exactly the window to exclude. Every other `opened` stays
+-- dismissable: a raise-only run (`converge=0`), or a keyless `opened` that never satisfied the gateway's
+-- `prKey != null` and fell through to `End` (`pr_key IS NULL`).
+--
+-- Every DERIVED column below is emitted VERBATIM from `featureReadModel.sqlSelectFor(col,
+-- { baseAlias: "fr" })` (which ALSO drives the runtime TS via `fnFor`); the `stage`/`stage_state`/
+-- `stage_skipped`/`attention` bodies are UNCHANGED from 111 and only `list_bucket`/`ack_open` gain the
+-- mid-handoff exclusion. The drift guard (app/featureReadModel.test.ts) fails if this file stops matching
+-- the declaration, and `assertReadModelParity` proves the SQL and TS lowerings agree.
+--
+-- SEMANTICS unchanged from 111 EXCEPT the two mid-handoff-narrowed columns: the status-classifying
+-- columns still read the terminal-folded `feature_runs__tracking.derived_status`; base columns stay
+-- aliased identity pass-throughs; `acknowledged_at` still passes through so the read model can classify
+-- on it. The STAGE derivations are untouched, so a mid-handoff `opened` still renders `PR open`.
+--
+-- Forward-only VIEW redefinition (DROP then CREATE). `feature_runs__tracking` is the managed VIEW urban
+-- provisions at mount; SQLite does not validate a view body at CREATE time, so this migration (which
+-- runs before that mount) is created fine and resolves once the managed VIEW exists. The runner wraps
+-- each file in its own transaction, so this file must NOT contain BEGIN/COMMIT. Numbered after 111.
+
+DROP VIEW IF EXISTS feature_read_model;
+
+CREATE VIEW feature_read_model AS
+SELECT
+  fr.feature_key AS feature_key,
+  fr.repo AS repo,
+  fr.issue_number AS issue_number,
+  fr.issue_url AS issue_url,
+  fr.title AS title,
+  fr.base_branch AS base_branch,
+  fr.status AS status,
+  fr.process_key AS process_key,
+  fr.pr_key AS pr_key,
+  fr.converge AS converge,
+  fr.auto_merge AS auto_merge,
+  fr.outcome AS outcome,
+  fr.delivery_label AS delivery_label,
+  fr.acknowledged_at AS acknowledged_at,
+  fr.created_at AS created_at,
+  fr.updated_at AS updated_at,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'Done' WHEN COALESCE(("fr"."derived_status" = 'converging'), 0) THEN 'Converging' WHEN COALESCE((COALESCE(("fr"."pr_key" <> ''), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) THEN 'PR open' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'running'), 0) OR COALESCE(("fr"."derived_status" = 'escalated'), 0) OR COALESCE(("fr"."derived_status" = 'awaiting_operator'), 0)), 0) THEN 'Implementing' ELSE 'Requested' END AS stage,
+  CASE WHEN COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0)), 0) THEN 'ok' WHEN COALESCE(("fr"."derived_status" = 'blocked'), 0) THEN 'blocked' WHEN COALESCE((COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0)), 0) THEN 'failed' ELSE NULL END AS stage_state,
+  CASE WHEN (NOT COALESCE("fr"."converge", 0)) THEN 'Converging Merging' WHEN (NOT COALESCE("fr"."auto_merge", 0)) THEN 'Merging' ELSE '' END AS stage_skipped,
+  CASE WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-blocked'), 0)), 0)) THEN 'blocked' WHEN EXISTS (SELECT 1 FROM "user_tasks" AS "__urban_proj_0" WHERE COALESCE((COALESCE(("__urban_proj_0"."subject_type" = 'feature'), 0) AND COALESCE(("__urban_proj_0"."subject_key" = "fr"."feature_key"), 0) AND COALESCE(("__urban_proj_0"."element_id" = 'feature-escalation'), 0)), 0)) THEN '⚠' ELSE NULL END AS attention,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND (NOT COALESCE(COALESCE((COALESCE(("fr"."derived_status" = 'opened'), 0) AND COALESCE(("fr"."converge" = 1), 0) AND COALESCE(("fr"."pr_key" = "fr"."pr_key"), 0)), 0), 0))), 0) AND COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0)), 0) THEN 'history' ELSE 'active' END AS list_bucket,
+  CASE WHEN COALESCE((COALESCE((COALESCE((COALESCE(("fr"."derived_status" = 'merged'), 0) OR COALESCE(("fr"."derived_status" = 'converged'), 0) OR COALESCE(("fr"."derived_status" = 'blocked'), 0) OR COALESCE(("fr"."derived_status" = 'failed'), 0) OR COALESCE(("fr"."derived_status" = 'skipped'), 0) OR COALESCE(("fr"."derived_status" = 'abandoned'), 0) OR COALESCE(("fr"."derived_status" = 'opened'), 0)), 0) AND (NOT COALESCE(COALESCE((COALESCE(("fr"."derived_status" = 'opened'), 0) AND COALESCE(("fr"."converge" = 1), 0) AND COALESCE(("fr"."pr_key" = "fr"."pr_key"), 0)), 0), 0))), 0) AND (NOT COALESCE(COALESCE(("fr"."acknowledged_at" = "fr"."acknowledged_at"), 0), 0))), 0) THEN 1 ELSE 0 END AS ack_open
+FROM feature_runs__tracking fr;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.189.1",
+  "version": "0.189.3",
   "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/workers/converge-feature/worker.ts

@@ -30,14 +30,23 @@ const handler: AppJobHandler<In, Record<string, never>> = async (job, app) => {
     await featureRuns(app.data).update(featureKey, { status: "opened", updated_at: new Date().toISOString() });
     return {};
   }
-  // `convergeOnly` is the inverse of auto-merge: converge-only stops at `converged`; auto-merge lets
-  // the merge-loop drive the merge. `submitPr` is idempotent on the PR key.
-  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey);
+  // Write `converging` BEFORE enrolling the PR (issue #808 / PR #809 review). The old order —
+  // `submitPr` then the status write — left an `opened` + `converge=1` + `pr_key` window spanning an
+  // ALREADY-SUBMITTED, live PR: a terminate/crash in that gap stranded a row whose PR was live while
+  // `pollFeatureDelivery`'s handoff edge (edge 3) read the FEATURE instance state alone and wrongly
+  // folded it to `abandoned`. Flipping to `converging` first shrinks the interrupted-handoff window to
+  // the (now converging-owned) gap BEFORE `submitPr`, which `pollFeatureDelivery`'s converging edge
+  // (edge 1) heals by re-enrolling when the PR row is still missing (idempotent, mirroring the
+  // promotion-PR re-enroll in `pollPromotion`). The reorder is safe: `submitPr` is idempotent on the PR
+  // key (it early-returns `alreadyRunning` for a non-terminal PR), and a `converging` row is owned by
+  // edge (1), never by the handoff edge. `convergeOnly` is the inverse of auto-merge: converge-only
+  // stops at `converged`; auto-merge lets the merge-loop drive the merge.
   await featureRuns(app.data).update(featureKey, {
     status: "converging",
     pr_key: parsed.prKey,
     updated_at: new Date().toISOString(),
   });
+  await submitPr(app.data, app.engine, parsed, [], MAX_ROUNDS, !autoMerge, featureKey);
   app.log.info("converge-feature: enrolled PR into convergence loop", {
     featureKey,
     prKey: parsed.prKey,