@nanobpm/nano-workforce 0.153.0 → 0.155.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## [0.155.0](https://github.com/nanobpm/nano-workforce/compare/v0.154.0...v0.155.0) (2026-08-29)
+
+### Features
+
+* **delivery-units:** delivery_units aggregate table (ADR 0006 S2, [#589](https://github.com/nanobpm/nano-workforce/issues/589)) ([#601](https://github.com/nanobpm/nano-workforce/issues/601)) ([6949fc4](https://github.com/nanobpm/nano-workforce/commit/6949fc4d3ee567b95497e43391ba15e9367a88e0))
+
+## [0.154.0](https://github.com/nanobpm/nano-workforce/compare/v0.153.0...v0.154.0) (2026-08-29)
+
+### Features
+
+* **onboarding:** three-state GitHub credential preflight in install.sh ([#599](https://github.com/nanobpm/nano-workforce/issues/599)) ([7e9f592](https://github.com/nanobpm/nano-workforce/commit/7e9f592632fc85cfea9f89843252c0128cec6c8d)), closes [#588](https://github.com/nanobpm/nano-workforce/issues/588)
+
 ## [0.153.0](https://github.com/nanobpm/nano-workforce/compare/v0.152.0...v0.153.0) (2026-08-29)
 
 ### Features

package/README.md

@@ -97,6 +97,23 @@ instance count each), hires each with `--rank senior --protocol acp --permission
 yolo`, composes a declarative **workforce manifest** (`c8 nano workforce add`),
 and brings it up (`c8 nano start` then `c8 nano workforce start`).
 
+**GitHub access preflight.** Because a workforce with no GitHub credential can
+neither review, push, nor merge, the preflight checks for a **usable** credential
+on this host before hiring: a `GITHUB_TOKEN`/`GH_TOKEN` in the environment
+*(validated with `gh api user` / a raw `api.github.com/user` probe, not trusted
+merely for being set — in the rare case where neither `gh` nor `curl` is present
+to probe with, it cannot validate and warns that it is proceeding on trust)*, or
+the `gh` CLI *installed, authenticated, and proven with
+`gh api user`*. It
+distinguishes gh missing, installed-but-unauthenticated, and
+authenticated-but-unusable (expired token, missing `repo` scope, SAML SSO), warns
+(but does not fail) on a missing `workflow` scope, and checks `git` too. It prints
+a platform-aware install hint and the `gh auth login` / `GITHUB_TOKEN` remediation
+— it never runs `gh auth login` for you. Interactive runs let you fix it and
+re-check, or confirm-to-continue (default no); non-interactive runs **fail** unless
+you pass `--allow-no-github`. The check covers **this host only** — remote worker
+hosts each need their own credential.
+
 **Phase 2 — the app.** It then talks to the nano console the engine brought up to
 install the `@nanobpm/nano-workforce` extension, scaffold a **Workforce** project
 from the `nano-workforce` template, write its `ProjectConfig.env` (including

package/app/deliveryUnit.test.ts

@@ -0,0 +1,244 @@
+// Coverage for ADR 0006 slice S2 (#589) — the `delivery_units` aggregate and its DB-level sync.
+//
+// Proves, against a REAL in-memory SQLite with the full migration set applied:
+//   1. VOCABULARY PARITY — the TS `DELIVERY_UNIT_KINDS` closed enum matches the `CHECK (kind IN (…))`
+//      constraint in migration 088 (the two lowerings of the §2 kind enum can't drift).
+//   2. DERIVATION PARITY — for every source status of every shape, the DB triggers/backfill derive the
+//      same canonical `delivery_status` as the S1 read models (app/deliveryUnitStatus.ts) and the same
+//      `dispatch_status` as the TS `dispatchStatusForDelivery` (the SQL and TS lowerings agree).
+//   3. IDENTITY — the derived `unit_id` matches the TS `*UnitId` helpers, and an epic slice node hangs
+//      under its epic (`parent_unit_id`), so the aggregate's universal key is what the door will name.
+//   4. COMPAT-VIEW PARITY — each legacy-shaped `<table>__units` VIEW is row-for-row identical to its
+//      base table over insert/update/delete, so a read path can swap onto the aggregate losslessly.
+import { DatabaseSync } from "node:sqlite";
+import { test } from "node:test";
+import { applyMigrationSet, readMigrationSetFromDisk } from "#test-migrations";
+import { assert, assertEquals } from "#test-assert";
+import {
+  DELIVERY_UNIT_KINDS,
+  deliveryGraphUnitId,
+  dispatchStatusForDelivery,
+  epicUnitId,
+  featureUnitId,
+  planTaskUnitId,
+} from "./deliveryUnit.ts";
+import {
+  type DeliveryUnitStatus,
+  deliveryGraphDeliveryStatus,
+  featureDeliveryStatus,
+  planDeliveryStatus,
+  PLAN_STATUSES,
+  planTaskDeliveryStatus,
+  toDeliveryUnitStatus,
+} from "./deliveryUnitStatus.ts";
+import { DELIVERY_GRAPH_RUN_STATUSES } from "./deliveryGraphRun.ts";
+import { FEATURE_RUN_STATUSES } from "./feature.ts";
+import { PLAN_TASK_STATUSES } from "./plan.ts";
+
+function freshDb(): DatabaseSync {
+  const db = new DatabaseSync(":memory:");
+  db.exec("PRAGMA foreign_keys = ON;");
+  applyMigrationSet(db, readMigrationSetFromDisk());
+  return db;
+}
+
+const NOW = "2026-01-01T00:00:00Z";
+const row = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).get(...(p as never[])) as Record<string, unknown>;
+const rows = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).all(...(p as never[])) as Record<string, unknown>[];
+const exec = (db: DatabaseSync, sql: string, ...p: unknown[]) => db.prepare(sql).run(...(p as never[]));
+
+test("VOCABULARY PARITY: DELIVERY_UNIT_KINDS matches migration 088's CHECK (kind IN (…))", () => {
+  const mig = readMigrationSetFromDisk().find((m) => m.name === "088_delivery_units.sql");
+  assert(mig, "088_delivery_units.sql must exist");
+  const m = mig.sql.match(/kind IN \(([^)]*)\)/);
+  assert(m, "088 must declare a CHECK (kind IN (…)) constraint");
+  const declared = m[1].split(",").map((s) => s.trim().replace(/^'|'$/g, ""));
+  assertEquals(declared, [...DELIVERY_UNIT_KINDS], "the SQL kind enum and the TS enum must agree");
+});
+
+test("DERIVATION PARITY: feature triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  FEATURE_RUN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${100 + i}`;
+    exec(
+      db,
+      `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?,?)`,
+      key, "o/r", 100 + i, "u", "main", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", featureUnitId(key));
+    const canonical = toDeliveryUnitStatus(featureDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "feature");
+    assertEquals(u.delivery_status, canonical, `feature ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `feature ${status} → dispatch`);
+    assertEquals(u.status, status, "raw legacy status is preserved verbatim");
+  });
+});
+
+test("DERIVATION PARITY: epic (plans) triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  PLAN_STATUSES.forEach((status, i) => {
+    const key = `o/r#${200 + i}`;
+    exec(
+      db,
+      `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at)
+       VALUES(?,?,?,?,?,?,?)`,
+      key, "o/r", 200 + i, "u", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", epicUnitId(key));
+    const canonical = toDeliveryUnitStatus(planDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "epic");
+    assertEquals(u.delivery_status, canonical, `epic ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `epic ${status} → dispatch`);
+  });
+});
+
+test("DERIVATION PARITY + IDENTITY: plan-task nodes derive status and hang under their epic", () => {
+  const db = freshDb();
+  const planKey = "o/r#300";
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+    planKey, "o/r", 300, "u", "dispatched", NOW, NOW,
+  );
+  PLAN_TASK_STATUSES.forEach((status, i) => {
+    exec(
+      db,
+      `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`,
+      planKey, i, `t${i}`, status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", planTaskUnitId(planKey, i));
+    const canonical = toDeliveryUnitStatus(planTaskDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "plan-task");
+    assertEquals(u.delivery_status, canonical, `plan-task ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `plan-task ${status} → dispatch`);
+    assertEquals(u.parent_unit_id, epicUnitId(planKey), "a node hangs under its epic composition");
+    assertEquals(u.node_index, i, "the node carries its slice ordinal");
+  });
+});
+
+test("DERIVATION PARITY: delivery-graph triggers derive the S1 canonical + dispatch status for every source status", () => {
+  const db = freshDb();
+  DELIVERY_GRAPH_RUN_STATUSES.forEach((status, i) => {
+    const key = `dg${i}`;
+    exec(
+      db,
+      `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+      key, "abc", status, NOW, NOW,
+    );
+    const u = row(db, "SELECT * FROM delivery_units WHERE unit_id=?", deliveryGraphUnitId(key));
+    const canonical = toDeliveryUnitStatus(deliveryGraphDeliveryStatus, status) as DeliveryUnitStatus;
+    assertEquals(u.kind, "delivery-graph");
+    assertEquals(u.delivery_status, canonical, `delivery-graph ${status} → canonical`);
+    assertEquals(u.dispatch_status, dispatchStatusForDelivery(canonical), `delivery-graph ${status} → dispatch`);
+  });
+});
+
+test("FAIL CLOSED: an unknown legacy status yields NULL delivery_status AND NULL dispatch_status (no inconsistent row)", () => {
+  // The legacy `status` columns are plain TEXT NOT NULL without a CHECK, so an unexpected value can
+  // reach the triggers. `dispatch_status` is derived FROM the canonical `delivery_status`, so when the
+  // status is unrecognised (delivery_status → NULL) dispatch_status MUST also be NULL — never a
+  // dangling 'dispatched'/'settled' on a row whose delivery_status is NULL.
+  const db = freshDb();
+  const cases: [string, () => void, string][] = [
+    [
+      "feature",
+      () =>
+        exec(
+          db,
+          `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?,?)`,
+          "o/r#900", "o/r", 900, "u", "main", "bogus-status", NOW, NOW,
+        ),
+      featureUnitId("o/r#900"),
+    ],
+    [
+      "epic",
+      () =>
+        exec(
+          db,
+          `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`,
+          "o/r#901", "o/r", 901, "u", "bogus-status", NOW, NOW,
+        ),
+      epicUnitId("o/r#901"),
+    ],
+    [
+      "delivery-graph",
+      () =>
+        exec(
+          db,
+          `INSERT INTO delivery_graph_runs(run_key,digest,status,created_at,updated_at) VALUES(?,?,?,?,?)`,
+          "dg900", "abc", "bogus-status", NOW, NOW,
+        ),
+      deliveryGraphUnitId("dg900"),
+    ],
+  ];
+  for (const [kind, insert, unitId] of cases) {
+    insert();
+    const u = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", unitId);
+    assertEquals(u.delivery_status, null, `${kind} unknown status → NULL delivery_status`);
+    assertEquals(u.dispatch_status, null, `${kind} unknown status → NULL dispatch_status (fail closed)`);
+  }
+
+  // plan-task needs a parent epic row first.
+  exec(db, `INSERT INTO plans(plan_key,repo,issue_number,issue_url,status,created_at,updated_at) VALUES(?,?,?,?,?,?,?)`, "o/r#902", "o/r", 902, "u", "planning", NOW, NOW);
+  exec(db, `INSERT INTO plan_tasks(plan_key,task_index,task_id,status,created_at,updated_at) VALUES(?,?,?,?,?,?)`, "o/r#902", 0, "t0", "bogus-status", NOW, NOW);
+  const pt = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", planTaskUnitId("o/r#902", 0));
+  assertEquals(pt.delivery_status, null, "plan-task unknown status → NULL delivery_status");
+  assertEquals(pt.dispatch_status, null, "plan-task unknown status → NULL dispatch_status (fail closed)");
+});
+
+// ── COMPAT-VIEW PARITY — each `<table>__units` VIEW is byte-identical to its base table. ────────────
+const norm = (r: Record<string, unknown>[]) =>
+  JSON.stringify(r.map((x) => Object.fromEntries(Object.entries(x).sort())));
+
+function assertViewParity(db: DatabaseSync, base: string, view: string) {
+  assertEquals(norm(rows(db, `SELECT * FROM ${base} ORDER BY 1`)), norm(rows(db, `SELECT * FROM ${view} ORDER BY 1`)), `${view} must equal ${base}`);
+}
+
+test("COMPAT-VIEW PARITY: every legacy surface is served row-for-row from the aggregate across insert/update/delete", () => {
+  const db = freshDb();
+  exec(
+    db,
+    `INSERT INTO feature_runs(feature_key,repo,issue_number,issue_url,base_branch,status,converge,auto_merge,outcome,delivery_label,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#1", "o/r", 1, "u", "main", "running", 1, 0, null, null, "Feat", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plans(plan_key,repo,issue_number,issue_url,title,status,task_count,base_branch,epic_phase,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", "o/r", 2, "u", "Epic", "planning", 2, "main", "Planning", NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO plan_tasks(plan_key,task_index,task_id,title,prompt,status,pr_key,summary,wave,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "o/r#2", 0, "t0", "Slice", "do it", "pending", null, null, 1, NOW, NOW,
+  );
+  exec(
+    db,
+    `INSERT INTO delivery_graph_runs(run_key,process_key,digest,status,side_effecting,node_count,human_node_count,side_effect_count,title,created_at,updated_at)
+     VALUES(?,?,?,?,?,?,?,?,?,?,?)`,
+    "dg1", null, "deadbeef", "awaiting-approval", 1, 5, 2, 3, "Graph", NOW, NOW,
+  );
+
+  const pairs: [string, string][] = [
+    ["feature_runs", "feature_runs__units"],
+    ["plans", "plans__units"],
+    ["plan_tasks", "plan_tasks__units"],
+    ["delivery_graph_runs", "delivery_graph_runs__units"],
+  ];
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // UPDATE — a status transition (and a projected column) must re-project onto the aggregate.
+  exec(db, "UPDATE feature_runs SET status=?, pr_key=?, updated_at=? WHERE feature_key=?", "merged", "o/r#5", "2026-02", "o/r#1");
+  const fu = row(db, "SELECT delivery_status, dispatch_status FROM delivery_units WHERE unit_id=?", featureUnitId("o/r#1"));
+  assertEquals(fu.delivery_status, "merged");
+  assertEquals(fu.dispatch_status, "settled");
+  for (const [b, v] of pairs) assertViewParity(db, b, v);
+
+  // DELETE — the aggregate row is dropped with the legacy row.
+  exec(db, "DELETE FROM plan_tasks WHERE plan_key=?", "o/r#2");
+  assertEquals(rows(db, "SELECT * FROM delivery_units WHERE kind='plan-task'").length, 0, "deleting a slice drops its node unit");
+  assertViewParity(db, "plan_tasks", "plan_tasks__units");
+});

package/app/deliveryUnit.ts

@@ -0,0 +1,109 @@
+// ADR 0006 slice S2 (#589) — the `delivery_units` aggregate, TS side.
+//
+// S2 collapses the four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+// `delivery_graph_runs`) onto ONE kind-tagged aggregate table (`db/migrations/088_delivery_units.sql`).
+// The data-level sync is done at the DB layer — triggers mirror every legacy write into the aggregate
+// (089), a backfill seeds pre-existing rows (090), and legacy-shaped compat VIEWs are served FROM the
+// aggregate (091) — so this module carries NO write path of its own; it is the canonical TS home for
+// the aggregate's VOCABULARY (the closed `kind` enum, the `dispatch_status` lifecycle), the universal
+// `unit_id` derivation, and the `dispatch_status` derivation. The last two are also lowered to SQL in
+// the trigger/backfill migrations; app/deliveryUnit.test.ts proves the two lowerings agree over the
+// full status/shape matrix (the same declare-once / parity-guard discipline S1 uses for the status
+// union — derivation over duplication).
+//
+// SCOPE (S2). This owns the aggregate's identity + dispatch vocabulary and a read gateway. The single
+// dispatch door (S3) will key on `dispatch_status`; repointing live writers onto `delivery_units` and
+// retiring the legacy write paths is the later CONTRACT phase (S3), sequenced after the
+// `instanceTracking` doors move. Nothing here changes existing behaviour.
+
+import type { DataLayer, Table } from "@nanobpm/urban";
+import { type DeliveryUnitStatus, isDeliveryUnitSettled } from "./deliveryUnitStatus.ts";
+
+/**
+ * The closed §2 `kind` enum covering every delivery unit. A run of an epic is ONE unit (`kind='epic'`,
+ * a composition over its slices); each slice is a `plan-task` node under it. `feature` is the
+ * degenerate 1-node unit; `delivery-graph` is the arbitrary-DAG unit. `bugfix`/`chore` are reserved
+ * §2 members with no legacy table yet. Kept in lockstep with the `CHECK (kind IN (…))` constraint in
+ * migration 088 — a parity test pins the two.
+ */
+export const DELIVERY_UNIT_KINDS = ["feature", "epic", "plan-task", "delivery-graph", "bugfix", "chore"] as const;
+export type DeliveryUnitKind = (typeof DELIVERY_UNIT_KINDS)[number];
+
+/**
+ * The `dispatch_status` lifecycle — the single dispatch door's status (ADR 0006 §4; the S3 door
+ * collapses onto it). Derived from the canonical {@link DeliveryUnitStatus}:
+ *  - `pending`    — created, not yet dispatched to an executor (canonical `requested`).
+ *  - `dispatched` — a live executor/instance is working the unit (a live/parked non-terminal status).
+ *  - `settled`    — terminal, or a live PR resting stage (`opened`/`converging`): re-dispatchable. This
+ *                   is exactly the {@link isDeliveryUnitSettled} predicate, so the dispatch door's
+ *                   short-circuit gate matches the redispatch-settled semantics S1 defined.
+ */
+export const DISPATCH_STATUSES = ["pending", "dispatched", "settled"] as const;
+export type DeliveryUnitDispatchStatus = (typeof DISPATCH_STATUSES)[number];
+
+/**
+ * Derive the `dispatch_status` from a canonical delivery-unit status — the TS lowering of the CASE the
+ * sync-trigger/backfill migrations (089/090) apply in SQL. `requested` ⇒ `pending`; a settled status
+ * (terminal or a PR resting stage) ⇒ `settled`; every other (live/parked) status ⇒ `dispatched`.
+ */
+export function dispatchStatusForDelivery(status: DeliveryUnitStatus): DeliveryUnitDispatchStatus {
+  if (status === "requested") return "pending";
+  if (isDeliveryUnitSettled(status)) return "settled";
+  return "dispatched";
+}
+
+// ── Universal `unit_id` — the cross-representation fact every agent can name and the dispatch door
+//    keys on (#464 "What survives" #4). Kept in lockstep with the `unit_id` expressions the
+//    trigger/backfill migrations build; app/deliveryUnit.test.ts pins the two. ─────────────────────
+
+/** The `feature:<feature_key>` unit id for a single-issue feature run. */
+export const featureUnitId = (featureKey: string): string => `feature:${featureKey}`;
+
+/** The `epic:<plan_key>` unit id for an epic (the `plans` aggregate row). */
+export const epicUnitId = (planKey: string): string => `epic:${planKey}`;
+
+/**
+ * The `plan-task:<plan_key>#<task_index>` unit id for one epic slice NODE. Its composition parent is
+ * {@link epicUnitId}(planKey) — the epic unit it hangs under.
+ */
+export const planTaskUnitId = (planKey: string, taskIndex: number): string => `plan-task:${planKey}#${taskIndex}`;
+
+/** The `delivery-graph:<run_key>` unit id for a delivery-graph run. */
+export const deliveryGraphUnitId = (runKey: string): string => `delivery-graph:${runKey}`;
+
+/**
+ * One row of the `delivery_units` aggregate. `unit_id`/`kind` are the identity pair; `delivery_status`
+ * is the canonical S1 union value; `status` is the raw legacy source status (kept verbatim so the
+ * compat VIEWs reconstruct legacy rows losslessly); `dispatch_status` is the door lifecycle. The
+ * per-shape legacy columns ride the same row (nullable off-kind). Read-only for S2 — the physical
+ * write target stays the legacy tables (the triggers mirror in).
+ */
+export interface DeliveryUnitRow {
+  unit_id: string;
+  kind: DeliveryUnitKind;
+  legacy_key: string | null;
+  legacy_id: number | null;
+  parent_unit_id: string | null;
+  node_index: number | null;
+  delivery_status: DeliveryUnitStatus | null;
+  dispatch_status: DeliveryUnitDispatchStatus | null;
+  status: string | null;
+  repo: string | null;
+  issue_number: number | null;
+  issue_url: string | null;
+  title: string | null;
+  base_branch: string | null;
+  process_key: string | null;
+  pr_key: string | null;
+  outcome: string | null;
+  created_at: string | null;
+  updated_at: string | null;
+}
+
+/**
+ * The read gateway over the `delivery_units` aggregate, keyed on the universal `unit_id`. Read-only in
+ * S2 (writes flow through the legacy tables + the sync triggers); the S3 dispatch door will own the
+ * write path once the legacy writers retire.
+ */
+export const deliveryUnits = (data: DataLayer): Table<DeliveryUnitRow> =>
+  data.table<DeliveryUnitRow>("delivery_units", "unit_id");

package/db/migrations/088_delivery_units.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — the `delivery_units` aggregate: ONE kind-tagged table consolidating the
+-- four legacy delivery-unit representations (`feature_runs`, `plans`, `plan_tasks`,
+-- `delivery_graph_runs`) that ADR 0006 §2 declared to be one aggregate. S1 (#494) delivered the derived
+-- status union (app/deliveryUnitStatus.ts); this is its data-aggregate half.
+--
+-- EXPAND phase (ADR 0006 §S2 rollout, expand-and-contract): this migration + 089 (sync triggers) + 090
+-- (backfill) ADD the aggregate and keep it in lockstep with the legacy tables, which stay the physical
+-- WRITE target through S2 (the framework `instanceTracking` bindings + every app writer still target
+-- them; ADR 0065 makes `instanceTracking` a SOURCE that no longer writes base rows, so the legacy base
+-- `status` is only ever written through the app gateways — mirrored here at the DB level). 091 adds the
+-- legacy-shaped compat VIEWs served FROM this aggregate, parity-tested against the base tables
+-- (app/deliveryUnit.test.ts). Repointing live writers onto `delivery_units` and retiring the legacy
+-- write paths is the later CONTRACT phase (S3), which the ADR sequences after the `instanceTracking`
+-- doors move.
+--
+-- Identity (#464 "What survives"): `unit_id` is the universal, human-nameable cross-representation key
+-- the dispatch door (S3) keys on — `feature:<key>` / `epic:<plan_key>` / `plan-task:<plan_key>#<idx>` /
+-- `delivery-graph:<run_key>`. A run of an epic is ONE unit (`kind='epic'`); each of its slices is a
+-- `kind='plan-task'` node under it (`parent_unit_id = 'epic:<plan_key>'`). `kind` is the closed §2 enum.
+-- `dispatch_status` is the single dispatch door's status (S3 collapses onto it): 'pending' (created,
+-- not yet dispatched), 'dispatched' (a live executor/instance), 'settled' (terminal or a live PR
+-- resting stage — re-dispatchable), derived from the canonical `delivery_status`.
+--
+-- Every column except the identity pair (`unit_id`/`kind`) is nullable so a sync trigger over a
+-- partial legacy row can never trip a NOT NULL. `delivery_status` is the canonical S1 union value;
+-- `status` is the raw legacy source status (kept verbatim so the compat VIEWs reconstruct the legacy
+-- rows losslessly). The runner wraps each file in its own transaction — no BEGIN/COMMIT here. Numbered
+-- after the current highest prefix (087).
+
+CREATE TABLE IF NOT EXISTS delivery_units (
+  unit_id TEXT PRIMARY KEY,
+  kind TEXT NOT NULL CHECK (kind IN ('feature', 'epic', 'plan-task', 'delivery-graph', 'bugfix', 'chore')),
+  legacy_key TEXT,
+  legacy_id INTEGER,
+  parent_unit_id TEXT,
+  node_index INTEGER,
+  delivery_status TEXT,
+  dispatch_status TEXT,
+  repo TEXT,
+  issue_number INTEGER,
+  issue_url TEXT,
+  title TEXT,
+  base_branch TEXT,
+  status TEXT,
+  process_key TEXT,
+  pr_key TEXT,
+  outcome TEXT,
+  acknowledged_at TEXT,
+  list_bucket TEXT,
+  created_at TEXT,
+  updated_at TEXT,
+  converge INTEGER,
+  auto_merge INTEGER,
+  delivery_label TEXT,
+  stage TEXT,
+  stage_state TEXT,
+  stage_skipped TEXT,
+  attention TEXT,
+  task_count INTEGER,
+  gate_wave INTEGER,
+  blackboard_token TEXT,
+  retro_started_at TEXT,
+  epic_phase TEXT,
+  promotion_pr TEXT,
+  promotion_state TEXT,
+  ack_open INTEGER,
+  wait_gate TEXT,
+  wait_gate_label TEXT,
+  bound_artifacts TEXT,
+  task_id TEXT,
+  prompt TEXT,
+  summary TEXT,
+  wave INTEGER,
+  open_question TEXT,
+  answer TEXT,
+  draft_pr_key TEXT,
+  corr_key TEXT,
+  process_definition_id TEXT,
+  digest TEXT,
+  side_effecting INTEGER,
+  node_count INTEGER,
+  human_node_count INTEGER,
+  side_effect_count INTEGER,
+  phase TEXT,
+  phase_node_id TEXT,
+  human_labels TEXT
+);
+
+CREATE INDEX IF NOT EXISTS ix_delivery_units_kind ON delivery_units (kind);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_dispatch_status ON delivery_units (dispatch_status);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_parent ON delivery_units (parent_unit_id);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_process_key ON delivery_units (process_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_pr_key ON delivery_units (pr_key);
+CREATE INDEX IF NOT EXISTS ix_delivery_units_legacy_key ON delivery_units (legacy_key);

package/db/migrations/089_delivery_units_sync_triggers.sql

@@ -0,0 +1,94 @@
+-- ADR 0006 slice S2 (#589) — DB-level sync triggers mirroring every legacy delivery-unit write into
+-- the `delivery_units` aggregate (088). AFTER INSERT/UPDATE/DELETE on each of the four legacy tables
+-- keeps the aggregate in perfect lockstep regardless of WHICH writer touched the base row — the app
+-- gateways (app/feature.ts, app/plan.ts, app/deliveryGraphRun.ts), the plan/wave/results workers, the
+-- service pollers, AND the raw-SQL compare-and-swap in `claimRunForLaunch` (app/deliveryGraphRun.ts)
+-- that bypasses the gateway. A trigger fires at the DB level, so there is no drift surface and no
+-- write-path code to keep in sync (derivation over duplication). ADR 0065 makes `instanceTracking` a
+-- SOURCE that no longer writes base rows, so the base `status` these triggers read is always the
+-- worker-owned transient — the terminal fold stays derived on the legacy `__tracking` VIEWs.
+--
+-- `INSERT OR REPLACE` on the derived `unit_id` makes each trigger idempotent (an update re-projects
+-- the whole row). `delivery_status` (canonical S1 union) and `dispatch_status` are computed by the
+-- same CASE lowerings app/deliveryUnit.ts mirrors in TS, guarded at parity by app/deliveryUnit.test.ts.
+-- The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP TRIGGER IF EXISTS feature_runs__du_ai;
+CREATE TRIGGER feature_runs__du_ai AFTER INSERT ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_au;
+CREATE TRIGGER feature_runs__du_au AFTER UPDATE ON feature_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  VALUES ('feature:' || NEW.feature_key, 'feature', NEW.feature_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'converging' THEN 'converging' WHEN NEW.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN NEW.status = 'merged' THEN 'merged' WHEN NEW.status = 'converged' THEN 'converged' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.base_branch, NEW.status, NEW.process_key, NEW.pr_key, NEW.converge, NEW.auto_merge, NEW.outcome, NEW.delivery_label, NEW.acknowledged_at, NEW.stage, NEW.stage_state, NEW.stage_skipped, NEW.attention, NEW.list_bucket, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS feature_runs__du_ad;
+CREATE TRIGGER feature_runs__du_ad AFTER DELETE ON feature_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'feature:' || OLD.feature_key;
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ai;
+CREATE TRIGGER plans__du_ai AFTER INSERT ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_au;
+CREATE TRIGGER plans__du_au AFTER UPDATE ON plans
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  VALUES ('epic:' || NEW.plan_key, 'epic', NEW.plan_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'planning' THEN 'requested' WHEN NEW.status = 'dispatched' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('planning') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('dispatched') THEN 'dispatched' ELSE NULL END, NEW.repo, NEW.issue_number, NEW.issue_url, NEW.title, NEW.status, NEW.task_count, NEW.process_key, NEW.outcome, NEW.gate_wave, NEW.blackboard_token, NEW.retro_started_at, NEW.base_branch, NEW.epic_phase, NEW.promotion_pr, NEW.promotion_state, NEW.acknowledged_at, NEW.list_bucket, NEW.ack_open, NEW.wait_gate, NEW.wait_gate_label, NEW.bound_artifacts, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS plans__du_ad;
+CREATE TRIGGER plans__du_ad AFTER DELETE ON plans
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'epic:' || OLD.plan_key;
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ai;
+CREATE TRIGGER plan_tasks__du_ai AFTER INSERT ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_au;
+CREATE TRIGGER plan_tasks__du_au AFTER UPDATE ON plan_tasks
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  VALUES ('plan-task:' || NEW.plan_key || '#' || NEW.task_index, 'plan-task', NEW.plan_key, NEW.id, 'epic:' || NEW.plan_key, NEW.task_index, CASE WHEN NEW.status = 'pending' THEN 'requested' WHEN NEW.status = 'opened' THEN 'opened' WHEN NEW.status = 'blocked' THEN 'blocked' WHEN NEW.status = 'skipped' THEN 'skipped' WHEN NEW.status = 'escalated' THEN 'escalated' WHEN NEW.status = 'waiting-for-lane' THEN 'waiting' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('pending') THEN 'pending' WHEN NEW.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN NEW.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END, NEW.title, NEW.prompt, NEW.status, NEW.pr_key, NEW.summary, NEW.wave, NEW.open_question, NEW.answer, NEW.draft_pr_key, NEW.corr_key, NEW.created_at, NEW.updated_at, NEW.task_id);
+END;
+
+DROP TRIGGER IF EXISTS plan_tasks__du_ad;
+CREATE TRIGGER plan_tasks__du_ad AFTER DELETE ON plan_tasks
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'plan-task:' || OLD.plan_key || '#' || OLD.task_index;
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ai;
+CREATE TRIGGER delivery_graph_runs__du_ai AFTER INSERT ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_au;
+CREATE TRIGGER delivery_graph_runs__du_au AFTER UPDATE ON delivery_graph_runs
+BEGIN
+  INSERT OR REPLACE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  VALUES ('delivery-graph:' || NEW.run_key, 'delivery-graph', NEW.run_key, NULL, NULL, NULL, CASE WHEN NEW.status = 'awaiting-approval' THEN 'requested' WHEN NEW.status = 'running' THEN 'running' WHEN NEW.status = 'done' THEN 'done' WHEN NEW.status = 'failed' THEN 'failed' WHEN NEW.status = 'abandoned' THEN 'abandoned' ELSE NULL END, CASE WHEN NEW.status IN ('awaiting-approval') THEN 'pending' WHEN NEW.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN NEW.status IN ('running') THEN 'dispatched' ELSE NULL END, NEW.process_key, NEW.process_definition_id, NEW.digest, NEW.status, NEW.side_effecting, NEW.node_count, NEW.human_node_count, NEW.side_effect_count, NEW.title, NEW.phase, NEW.phase_node_id, NEW.human_labels, NEW.created_at, NEW.updated_at);
+END;
+
+DROP TRIGGER IF EXISTS delivery_graph_runs__du_ad;
+CREATE TRIGGER delivery_graph_runs__du_ad AFTER DELETE ON delivery_graph_runs
+BEGIN
+  DELETE FROM delivery_units WHERE unit_id = 'delivery-graph:' || OLD.run_key;
+END;

package/db/migrations/090_delivery_units_backfill.sql

@@ -0,0 +1,120 @@
+-- ADR 0006 slice S2 (#589) — backfill the `delivery_units` aggregate (088) from the existing rows of
+-- the four legacy tables, using the SAME projection the sync triggers (089) apply going forward. Idempotent
+-- (`INSERT OR IGNORE` on the `unit_id` PK) so re-running the migration set — or upgrading an install
+-- whose triggers already mirrored some rows — never double-inserts. Runs AFTER the triggers so a fresh
+-- install with seeded legacy rows is fully covered either way (triggers fire on live writes; this seeds
+-- pre-existing rows). The runner wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, base_branch, status, process_key, pr_key, converge, auto_merge, outcome, delivery_label, acknowledged_at, stage, stage_state, stage_skipped, attention, list_bucket, created_at, updated_at)
+  SELECT 'feature:' || feature_runs.feature_key AS unit_id,
+         'feature' AS kind,
+         feature_runs.feature_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN feature_runs.status = 'running' THEN 'running' WHEN feature_runs.status = 'escalated' THEN 'escalated' WHEN feature_runs.status = 'opened' THEN 'opened' WHEN feature_runs.status = 'converging' THEN 'converging' WHEN feature_runs.status = 'awaiting_operator' THEN 'awaiting_operator' WHEN feature_runs.status = 'merged' THEN 'merged' WHEN feature_runs.status = 'converged' THEN 'converged' WHEN feature_runs.status = 'blocked' THEN 'blocked' WHEN feature_runs.status = 'skipped' THEN 'skipped' WHEN feature_runs.status = 'failed' THEN 'failed' WHEN feature_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN feature_runs.status IN ('opened', 'converging', 'merged', 'converged', 'blocked', 'skipped', 'failed', 'abandoned') THEN 'settled' WHEN feature_runs.status IN ('running', 'escalated', 'awaiting_operator') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         feature_runs.repo AS repo,
+         feature_runs.issue_number AS issue_number,
+         feature_runs.issue_url AS issue_url,
+         feature_runs.title AS title,
+         feature_runs.base_branch AS base_branch,
+         feature_runs.status AS status,
+         feature_runs.process_key AS process_key,
+         feature_runs.pr_key AS pr_key,
+         feature_runs.converge AS converge,
+         feature_runs.auto_merge AS auto_merge,
+         feature_runs.outcome AS outcome,
+         feature_runs.delivery_label AS delivery_label,
+         feature_runs.acknowledged_at AS acknowledged_at,
+         feature_runs.stage AS stage,
+         feature_runs.stage_state AS stage_state,
+         feature_runs.stage_skipped AS stage_skipped,
+         feature_runs.attention AS attention,
+         feature_runs.list_bucket AS list_bucket,
+         feature_runs.created_at AS created_at,
+         feature_runs.updated_at AS updated_at
+  FROM feature_runs;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, repo, issue_number, issue_url, title, status, task_count, process_key, outcome, gate_wave, blackboard_token, retro_started_at, base_branch, epic_phase, promotion_pr, promotion_state, acknowledged_at, list_bucket, ack_open, wait_gate, wait_gate_label, bound_artifacts, created_at, updated_at)
+  SELECT 'epic:' || plans.plan_key AS unit_id,
+         'epic' AS kind,
+         plans.plan_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN plans.status = 'planning' THEN 'requested' WHEN plans.status = 'dispatched' THEN 'running' WHEN plans.status = 'done' THEN 'done' WHEN plans.status = 'failed' THEN 'failed' WHEN plans.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plans.status IN ('planning') THEN 'pending' WHEN plans.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN plans.status IN ('dispatched') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plans.repo AS repo,
+         plans.issue_number AS issue_number,
+         plans.issue_url AS issue_url,
+         plans.title AS title,
+         plans.status AS status,
+         plans.task_count AS task_count,
+         plans.process_key AS process_key,
+         plans.outcome AS outcome,
+         plans.gate_wave AS gate_wave,
+         plans.blackboard_token AS blackboard_token,
+         plans.retro_started_at AS retro_started_at,
+         plans.base_branch AS base_branch,
+         plans.epic_phase AS epic_phase,
+         plans.promotion_pr AS promotion_pr,
+         plans.promotion_state AS promotion_state,
+         plans.acknowledged_at AS acknowledged_at,
+         plans.list_bucket AS list_bucket,
+         plans.ack_open AS ack_open,
+         plans.wait_gate AS wait_gate,
+         plans.wait_gate_label AS wait_gate_label,
+         plans.bound_artifacts AS bound_artifacts,
+         plans.created_at AS created_at,
+         plans.updated_at AS updated_at
+  FROM plans;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, title, prompt, status, pr_key, summary, wave, open_question, answer, draft_pr_key, corr_key, created_at, updated_at, task_id)
+  SELECT 'plan-task:' || plan_tasks.plan_key || '#' || plan_tasks.task_index AS unit_id,
+         'plan-task' AS kind,
+         plan_tasks.plan_key AS legacy_key,
+         plan_tasks.id AS legacy_id,
+         'epic:' || plan_tasks.plan_key AS parent_unit_id,
+         plan_tasks.task_index AS node_index,
+         CASE WHEN plan_tasks.status = 'pending' THEN 'requested' WHEN plan_tasks.status = 'opened' THEN 'opened' WHEN plan_tasks.status = 'blocked' THEN 'blocked' WHEN plan_tasks.status = 'skipped' THEN 'skipped' WHEN plan_tasks.status = 'escalated' THEN 'escalated' WHEN plan_tasks.status = 'waiting-for-lane' THEN 'waiting' WHEN plan_tasks.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN plan_tasks.status IN ('pending') THEN 'pending' WHEN plan_tasks.status IN ('opened', 'blocked', 'skipped', 'abandoned') THEN 'settled' WHEN plan_tasks.status IN ('escalated', 'waiting-for-lane') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         plan_tasks.title AS title,
+         plan_tasks.prompt AS prompt,
+         plan_tasks.status AS status,
+         plan_tasks.pr_key AS pr_key,
+         plan_tasks.summary AS summary,
+         plan_tasks.wave AS wave,
+         plan_tasks.open_question AS open_question,
+         plan_tasks.answer AS answer,
+         plan_tasks.draft_pr_key AS draft_pr_key,
+         plan_tasks.corr_key AS corr_key,
+         plan_tasks.created_at AS created_at,
+         plan_tasks.updated_at AS updated_at,
+         plan_tasks.task_id AS task_id
+  FROM plan_tasks;
+
+INSERT OR IGNORE INTO delivery_units (unit_id, kind, legacy_key, legacy_id, parent_unit_id, node_index, delivery_status, dispatch_status, process_key, process_definition_id, digest, status, side_effecting, node_count, human_node_count, side_effect_count, title, phase, phase_node_id, human_labels, created_at, updated_at)
+  SELECT 'delivery-graph:' || delivery_graph_runs.run_key AS unit_id,
+         'delivery-graph' AS kind,
+         delivery_graph_runs.run_key AS legacy_key,
+         NULL AS legacy_id,
+         NULL AS parent_unit_id,
+         NULL AS node_index,
+         CASE WHEN delivery_graph_runs.status = 'awaiting-approval' THEN 'requested' WHEN delivery_graph_runs.status = 'running' THEN 'running' WHEN delivery_graph_runs.status = 'done' THEN 'done' WHEN delivery_graph_runs.status = 'failed' THEN 'failed' WHEN delivery_graph_runs.status = 'abandoned' THEN 'abandoned' ELSE NULL END AS delivery_status,
+         CASE WHEN delivery_graph_runs.status IN ('awaiting-approval') THEN 'pending' WHEN delivery_graph_runs.status IN ('done', 'failed', 'abandoned') THEN 'settled' WHEN delivery_graph_runs.status IN ('running') THEN 'dispatched' ELSE NULL END AS dispatch_status,
+         delivery_graph_runs.process_key AS process_key,
+         delivery_graph_runs.process_definition_id AS process_definition_id,
+         delivery_graph_runs.digest AS digest,
+         delivery_graph_runs.status AS status,
+         delivery_graph_runs.side_effecting AS side_effecting,
+         delivery_graph_runs.node_count AS node_count,
+         delivery_graph_runs.human_node_count AS human_node_count,
+         delivery_graph_runs.side_effect_count AS side_effect_count,
+         delivery_graph_runs.title AS title,
+         delivery_graph_runs.phase AS phase,
+         delivery_graph_runs.phase_node_id AS phase_node_id,
+         delivery_graph_runs.human_labels AS human_labels,
+         delivery_graph_runs.created_at AS created_at,
+         delivery_graph_runs.updated_at AS updated_at
+  FROM delivery_graph_runs;

package/db/migrations/091_delivery_units_read_models.sql

@@ -0,0 +1,111 @@
+-- ADR 0006 slice S2 (#589) — legacy-shaped compatibility VIEWs served FROM the `delivery_units`
+-- aggregate (088). Each VIEW reconstructs one legacy table's exact column set from the kind-tagged
+-- aggregate row, so a read path can swap onto the aggregate with byte-identical results — the
+-- "legacy tables become VIEWs/rows over the aggregate" surface of ADR 0006 §2, guarded by the parity
+-- tests in app/deliveryUnit.test.ts (each VIEW is proven row-for-row equal to its base table over the
+-- full status/shape matrix). These are ADDITIVE read surfaces; the live pages/read-models keep binding
+-- the physical base tables until S3 moves the writers, so no behaviour changes here.
+--
+-- A single plain `CREATE VIEW … SELECT … FROM delivery_units` per shape (one top-level FROM, every
+-- column aliased) so the static pages<->schema contract guard can parse the column list. The runner
+-- wraps each file in its own transaction — no BEGIN/COMMIT here.
+
+DROP VIEW IF EXISTS feature_runs__units;
+CREATE VIEW feature_runs__units AS
+SELECT
+  du.legacy_key AS feature_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.base_branch AS base_branch,
+  du.status AS status,
+  du.process_key AS process_key,
+  du.pr_key AS pr_key,
+  du.converge AS converge,
+  du.auto_merge AS auto_merge,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.delivery_label AS delivery_label,
+  du.title AS title,
+  du.acknowledged_at AS acknowledged_at,
+  du.stage AS stage,
+  du.stage_state AS stage_state,
+  du.stage_skipped AS stage_skipped,
+  du.attention AS attention,
+  du.list_bucket AS list_bucket
+FROM delivery_units du
+WHERE du.kind = 'feature';
+
+DROP VIEW IF EXISTS plans__units;
+CREATE VIEW plans__units AS
+SELECT
+  du.legacy_key AS plan_key,
+  du.repo AS repo,
+  du.issue_number AS issue_number,
+  du.issue_url AS issue_url,
+  du.title AS title,
+  du.status AS status,
+  du.task_count AS task_count,
+  du.process_key AS process_key,
+  du.outcome AS outcome,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.gate_wave AS gate_wave,
+  du.blackboard_token AS blackboard_token,
+  du.retro_started_at AS retro_started_at,
+  du.base_branch AS base_branch,
+  du.epic_phase AS epic_phase,
+  du.promotion_pr AS promotion_pr,
+  du.promotion_state AS promotion_state,
+  du.acknowledged_at AS acknowledged_at,
+  du.list_bucket AS list_bucket,
+  du.ack_open AS ack_open,
+  du.wait_gate AS wait_gate,
+  du.wait_gate_label AS wait_gate_label,
+  du.bound_artifacts AS bound_artifacts
+FROM delivery_units du
+WHERE du.kind = 'epic';
+
+DROP VIEW IF EXISTS plan_tasks__units;
+CREATE VIEW plan_tasks__units AS
+SELECT
+  du.legacy_id AS id,
+  du.legacy_key AS plan_key,
+  du.node_index AS task_index,
+  du.task_id AS task_id,
+  du.title AS title,
+  du.prompt AS prompt,
+  du.status AS status,
+  du.pr_key AS pr_key,
+  du.summary AS summary,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at,
+  du.wave AS wave,
+  du.open_question AS open_question,
+  du.answer AS answer,
+  du.draft_pr_key AS draft_pr_key,
+  du.corr_key AS corr_key
+FROM delivery_units du
+WHERE du.kind = 'plan-task';
+
+DROP VIEW IF EXISTS delivery_graph_runs__units;
+CREATE VIEW delivery_graph_runs__units AS
+SELECT
+  du.legacy_key AS run_key,
+  du.process_key AS process_key,
+  du.process_definition_id AS process_definition_id,
+  du.digest AS digest,
+  du.status AS status,
+  du.side_effecting AS side_effecting,
+  du.node_count AS node_count,
+  du.human_node_count AS human_node_count,
+  du.side_effect_count AS side_effect_count,
+  du.title AS title,
+  du.phase AS phase,
+  du.phase_node_id AS phase_node_id,
+  du.human_labels AS human_labels,
+  du.created_at AS created_at,
+  du.updated_at AS updated_at
+FROM delivery_units du
+WHERE du.kind = 'delivery-graph';

package/install.sh

@@ -79,6 +79,8 @@ DRY_RUN=0
 ASSUME_YES=0
 SHELL_OVERRIDE=''
 INSTALL_ADAPTERS=0        # auto-install missing adapters without prompting
+ALLOW_NO_GITHUB=0        # non-interactive: proceed even without usable GitHub access
+GITHUB_DEGRADED=''       # non-empty => the GitHub preflight passed in a degraded state; repeated in the final summary
 SKIP_APP=0               # phase 1 only: bring up engine + workforce, don't install the app
 PROJECT_NAME=''          # console project name for the Nano Workforce app (default: Workforce)
 CLI_HARNESS_SPECS=''      # newline-separated name[:model][:instances] from --harness
@@ -97,6 +99,19 @@ ADAPTERS_PRESENT="${NANO_INSTALL_ADAPTERS_PRESENT:-}"
 if [ "${NANO_INSTALL_HARNESSES_OVERRIDE+set}" = set ]; then HARNESS_OVERRIDE_SET=1; else HARNESS_OVERRIDE_SET=0; fi
 if [ "${NANO_INSTALL_ADAPTERS_PRESENT+set}" = set ]; then ADAPTERS_PRESENT_SET=1; else ADAPTERS_PRESENT_SET=0; fi
 
+# Test hooks for the GitHub credential preflight (undocumented; keep the smoke
+# test hermetic on runners that may or may not ship an authenticated gh):
+#   NANO_INSTALL_GH_STATE    — force gh state: missing|unauthed|unusable|ok
+#   NANO_INSTALL_GH_SCOPES   — comma/space list of token scopes gh reports
+#   NANO_INSTALL_GIT_STATE   — force git state: missing|present
+#   NANO_INSTALL_TOKEN_STATE — force env-token validity: ok|bad (skips the real
+#                              gh/api.github.com probe so tests need no network)
+# A set-but-empty override still counts as set, so the probe never falls back to
+# the real command -v / gh and the smoke test stays hermetic.
+if [ "${NANO_INSTALL_GH_STATE+set}" = set ]; then GH_STATE_OVERRIDE_SET=1; else GH_STATE_OVERRIDE_SET=0; fi
+if [ "${NANO_INSTALL_GIT_STATE+set}" = set ]; then GIT_STATE_OVERRIDE_SET=1; else GIT_STATE_OVERRIDE_SET=0; fi
+if [ "${NANO_INSTALL_TOKEN_STATE+set}" = set ]; then TOKEN_STATE_OVERRIDE_SET=1; else TOKEN_STATE_OVERRIDE_SET=0; fi
+
 CLI=''      # resolved c8ctl / c8 binary
 TTY=''      # /dev/tty if usable, else empty
 
@@ -219,6 +234,10 @@ Options:
   -y, --yes          Skip the confirmation summary.
   --install-adapters Auto-install a selected harness's missing ACP adapter
                      (claude/pi) instead of prompting/skipping.
+  --allow-no-github  Proceed even when no usable GitHub access is detected. In a
+                     non-interactive run the preflight otherwise fails, since a
+                     workforce with no GitHub credential cannot review, push, or
+                     merge. Interactive runs prompt instead.
   --project-name <name>
                      Console project name for the Nano Workforce app
                      (default: Workforce). [A-Za-z0-9._-] only.
@@ -261,6 +280,7 @@ parse_args() {
         shift ;;
       --yes|-y) ASSUME_YES=1; shift ;;
       --install-adapters) INSTALL_ADAPTERS=1; shift ;;
+      --allow-no-github) ALLOW_NO_GITHUB=1; shift ;;
       --skip-app) SKIP_APP=1; shift ;;
       --project-name)
         [ $# -ge 2 ] || die "--project-name requires a value"
@@ -277,6 +297,210 @@ parse_args() {
   done
 }
 
+# ---------------------------------------------------------------------------
+# GitHub credential preflight (nanobpm/nano-workforce#588)
+#
+# Two consumers need GitHub access and fail differently: the nwf app (review
+# poller + merge stage) and each hired agent worker (shells out to gh/git). The
+# real predicate is "a usable credential exists on this host", not "gh is
+# installed" — a token in GITHUB_TOKEN/GH_TOKEN satisfies both without gh.
+#
+# Detection distinguishes three states beyond present/absent: not installed,
+# installed-but-unauthenticated, and authenticated-but-unusable (a push/PR that
+# 403s only later — expired token, missing scope, SAML SSO, fine-grained PAT
+# without repo access). We prove usability with `gh api user`, never trusting
+# `gh auth status` alone.
+# ---------------------------------------------------------------------------
+gh_present() { # 0 if the gh CLI is available (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in missing) return 1 ;; *) return 0 ;; esac
+  fi
+  command -v gh >/dev/null 2>&1
+}
+
+gh_authed() { # 0 if gh auth status succeeds (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in missing|unauthed) return 1 ;; *) return 0 ;; esac
+  fi
+  gh auth status >/dev/null 2>&1
+}
+
+gh_usable() { # 0 if gh api user actually works — validates token + network + SSO
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GH_STATE" in ok) return 0 ;; *) return 1 ;; esac
+  fi
+  gh api user --jq .login >/dev/null 2>&1
+}
+
+gh_token_usable() { # 0 if the env GITHUB_TOKEN/GH_TOKEN actually authenticates
+  # An expired/revoked/underscoped token is the *exact* late failure this
+  # preflight exists to catch, so a non-empty token is not trusted blindly — we
+  # prove it works (gh api user, or a raw api.github.com/user probe when gh is
+  # absent). Honours the test hook so the smoke suite needs no network.
+  if [ "$TOKEN_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_TOKEN_STATE" in ok) return 0 ;; *) return 1 ;; esac
+  fi
+  _tok="${GITHUB_TOKEN:-${GH_TOKEN:-}}"
+  if gh_present; then
+    GITHUB_TOKEN="$_tok" GH_TOKEN="$_tok" gh api user --jq .login >/dev/null 2>&1
+  elif command -v curl >/dev/null 2>&1; then
+    # Pass the token via --config on stdin so it never lands in curl's argv
+    # (readable by other users via `ps` on a multi-user host).
+    printf 'header = "Authorization: Bearer %s"\n' "$_tok" | \
+      curl -fsS --connect-timeout 5 --max-time 10 --config - \
+        -H "User-Agent: nano-workforce-install" \
+        https://api.github.com/user >/dev/null 2>&1
+  else
+    # No gh and no curl to validate with — we cannot prove the token works,
+    # so warn explicitly rather than let an unvalidated token look "usable".
+    warn "cannot validate GITHUB_TOKEN/GH_TOKEN — neither gh nor curl is available on this host; proceeding on trust (an expired or under-scoped token will only fail later)."
+    return 0
+  fi
+}
+
+gh_scopes() { # print space-separated token scopes gh reports (honours the test hook)
+  if [ "$GH_STATE_OVERRIDE_SET" -eq 1 ]; then
+    printf '%s' "${NANO_INSTALL_GH_SCOPES:-}" | tr ',' ' '
+    return 0
+  fi
+  # gh auth status prints e.g.:  - Token scopes: 'gist', 'read:org', 'repo', 'workflow'
+  gh auth status 2>&1 | sed -n "s/.*Token scopes:[ ]*//p" | tr -d "'" | tr ',' ' '
+}
+
+git_present() { # 0 if git is available (honours the test hook)
+  if [ "$GIT_STATE_OVERRIDE_SET" -eq 1 ]; then
+    case "$NANO_INSTALL_GIT_STATE" in missing) return 1 ;; *) return 0 ;; esac
+  fi
+  command -v git >/dev/null 2>&1
+}
+
+# Platform-aware install + remediation hint. We print the command; we NEVER run
+# `gh auth login` for the user (it is an interactive device/OAuth flow that
+# should stay in their hands).
+gh_remediation_hint() {
+  note "GitHub access not detected. The workforce cannot review, push, or merge without it."
+  note ""
+  note "  macOS         brew install gh"
+  note "  Debian/Ubuntu sudo apt install gh"
+  note "  Fedora        sudo dnf install gh"
+  note "  Arch          sudo pacman -S gh"
+  note "  other         https://github.com/cli/cli#installation"
+  note ""
+  note "Then:  gh auth login          (or export GITHUB_TOKEN=…)"
+}
+
+# One probe pass. Sets GH_PROBE_MSG (human summary) and returns 0 when a usable
+# credential exists, 1 otherwise. Warns (non-fatal) when the workflow scope is
+# absent, since that only bites on workflow-file changes.
+probe_github() {
+  GH_PROBE_MSG=''
+  # 1. token in env → validate it (don't trust a non-empty value), skip gh
+  #    scope checks (a raw token exposes no scopes here) once it authenticates.
+  if [ -n "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then
+    if ! gh_token_usable; then
+      GH_PROBE_MSG="a GITHUB_TOKEN/GH_TOKEN is set but it failed validation (gh api user / api.github.com/user) — it is expired, revoked, or lacks access. Fix or unset it."
+      return 1
+    fi
+    if gh_present; then
+      GH_PROBE_MSG="GitHub token detected in the environment (GITHUB_TOKEN/GH_TOKEN); gh CLI also present."
+    else
+      GH_PROBE_MSG="GitHub token detected in the environment (GITHUB_TOKEN/GH_TOKEN)."
+      note "A token is set, so the nwf app is fine (NANO_PR_GITHUB_TRANSPORT=token)."
+      note "But gh is NOT installed on this host — harnesses that shell out to 'gh' still won't work. Install gh too."
+    fi
+    return 0
+  fi
+  # 2. otherwise the host CLI must be present, authenticated, and usable.
+  if ! gh_present; then
+    GH_PROBE_MSG="no gh CLI and no GITHUB_TOKEN/GH_TOKEN in the environment."
+    return 1
+  fi
+  if ! gh_authed; then
+    GH_PROBE_MSG="gh is installed but not authenticated (gh auth status failed)."
+    return 1
+  fi
+  # 3. prove it actually works — don't just trust status.
+  if ! gh_usable; then
+    GH_PROBE_MSG="gh reports authenticated but 'gh api user' failed — the credential is unusable (expired/revoked token, network, or SAML SSO not authorized for the target org)."
+    return 1
+  fi
+  # 4. authenticated + usable: the repo scope is required, workflow only warns.
+  _scopes=$(gh_scopes)
+  case " $_scopes " in
+    *" repo "*) : ;;
+    *)
+      GH_PROBE_MSG="gh is authenticated but the token is missing the 'repo' scope — pushes and PR creation will 403. Re-auth with:  gh auth refresh -s repo"
+      return 1 ;;
+  esac
+  case " $_scopes " in
+    *" workflow "*) : ;;
+    *) warn "gh token is missing the 'workflow' scope — harmless unless agents edit workflow files; add it with:  gh auth refresh -s workflow" ;;
+  esac
+  GH_PROBE_MSG="GitHub access OK via the host gh CLI."
+  return 0
+}
+
+# The full preflight: probe, remediate, and decide whether to continue. Records
+# a degraded state (repeated in the final summary) whenever we proceed without a
+# usable credential, so a degraded install never *looks* complete.
+add_degraded() { # accumulate a degraded reason so a later one never masks an earlier
+  if [ -n "$GITHUB_DEGRADED" ]; then
+    GITHUB_DEGRADED="${GITHUB_DEGRADED}; $1"
+  else
+    GITHUB_DEGRADED="$1"
+  fi
+}
+github_preflight() {
+  info "Checking GitHub access (this host only)"
+
+  # git is needed by every worker (clone/commit/push) — check it alongside gh.
+  if git_present; then
+    ok "git present"
+  else
+    warn "git not found on this host — agents cannot clone, commit, or push without it."
+    note "Install git from https://git-scm.com/downloads, then re-run."
+    add_degraded "git is not installed on this host"
+  fi
+
+  while : ; do
+    if probe_github; then
+      ok "$GH_PROBE_MSG"
+      note "This check covers THIS host only — remote worker hosts each need their own gh auth / token."
+      break
+    fi
+
+    warn "$GH_PROBE_MSG"
+    gh_remediation_hint
+    note "This check covers THIS host only — remote worker hosts each need their own gh auth / token."
+
+    # Non-interactive (--yes, no /dev/tty, or --dry-run): no prompt is possible.
+    if [ "$ASSUME_YES" -eq 1 ] || [ "$DRY_RUN" -eq 1 ] || [ -z "$TTY" ]; then
+      if [ "$ALLOW_NO_GITHUB" -eq 1 ]; then
+        warn "continuing without GitHub access (--allow-no-github) — the agents will not be able to do GitHub work."
+        add_degraded "$GH_PROBE_MSG"
+        break
+      fi
+      # Dry-run changes nothing, so never fail on it — just report what a real run would do.
+      if [ "$DRY_RUN" -eq 1 ]; then
+        note "dry-run: not blocking on GitHub access (a real run would fail here without --allow-no-github)."
+        break
+      fi
+      die "GitHub access not detected and running non-interactively — fix it (see above) and re-run, or pass --allow-no-github to proceed anyway."
+    fi
+
+    # Interactive: let the user fix it and re-check without re-running the whole
+    # script, else confirm-to-continue (default no).
+    if confirm "I've set up GitHub access (installed gh / ran gh auth login / exported a token). Re-check now?"; then
+      continue
+    fi
+    if confirm "Continue anyway? The agents won't be able to do GitHub work."; then
+      add_degraded "$GH_PROBE_MSG"
+      break
+    fi
+    die "aborted — set up GitHub access (see above) and re-run."
+  done
+}
+
 # ---------------------------------------------------------------------------
 # Step 1 — Preflight
 # ---------------------------------------------------------------------------
@@ -290,18 +514,10 @@ preflight() {
   fi
   ok "node $_nv (>= ${MIN_NODE}), npm present"
 
-  # Non-fatal: agents need GitHub access to do useful work.
-  if [ -z "${GITHUB_TOKEN:-}" ] && [ -z "${GH_TOKEN:-}" ]; then
-    if command -v gh >/dev/null 2>&1; then
-      if ! gh auth status >/dev/null 2>&1; then
-        warn "gh is installed but not authenticated, and no GITHUB_TOKEN/GH_TOKEN is set."
-        note "Agents need GitHub access — run 'gh auth login' or export GITHUB_TOKEN before they start pulling work."
-      fi
-    else
-      warn "no gh CLI and no GITHUB_TOKEN/GH_TOKEN in the environment."
-      note "Agents need GitHub access — install gh (https://cli.github.com) and 'gh auth login', or export GITHUB_TOKEN."
-    fi
-  fi
+  # GitHub access — a workforce with no usable credential can do nothing useful,
+  # so this is a real three-state check with remediation (nanobpm/nano-workforce#588),
+  # not a passing mention. Covers this host only; remote worker hosts need their own.
+  github_preflight
 }
 
 # ---------------------------------------------------------------------------
@@ -939,6 +1155,9 @@ confirm_app() {
   note "project           : ${PROJECT} (from template 'nano-workforce')"
   if [ -n "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then _ghkey='GITHUB_TOKEN'; else _ghkey='NANO_PR_GITHUB_TRANSPORT'; fi
   note "env keys written  : ${_ghkey}, NANOBPMN_BASE_URL, NANO_WORKFORCE_BASE_URL, PR_REVIEW_PORT (values not shown)"
+  if [ -z "${GITHUB_TOKEN:-${GH_TOKEN:-}}" ]; then
+    note "no token in env   : the app relies on the host gh CLI (NANO_PR_GITHUB_TRANSPORT=auto)."
+  fi
   note "app-view URL      : ${APPVIEW_BASE}/"
   if [ "$ASSUME_YES" -eq 1 ] || [ "$DRY_RUN" -eq 1 ]; then
     [ "$DRY_RUN" -eq 1 ] && note "dry-run: not asking for confirmation."
@@ -1147,6 +1366,11 @@ install_app() {
 # Partial-success report
 # ---------------------------------------------------------------------------
 report_and_exit() {
+  # A degraded GitHub-access install must never *look* complete — repeat the
+  # warning here and exit non-zero so the failure is visible, not deferred.
+  if [ -n "$GITHUB_DEGRADED" ] && [ "$DRY_RUN" -eq 0 ]; then
+    record_failure "GitHub/git preflight degraded (this host only): ${GITHUB_DEGRADED} — the workforce cannot review, push, or merge until it is fixed"
+  fi
   if [ -n "$FAILURES" ]; then
     warn "Completed with some steps skipped or failed:"
     printf '%s\n' "$FAILURES" | sed '/^$/d' | while IFS= read -r _f; do note "- $_f"; done

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.153.0",
+  "version": "0.155.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/test/install-smoke.sh

@@ -99,6 +99,115 @@ assert_contains "s5: later selection defaults to 1 instance" \
 assert_contains "s5: default model => bare adapter command, empty --model" \
   "--command 'claude-code-acp' --model ''" "$OUT"
 
+# ===========================================================================
+# GitHub credential preflight — three-state check (nano-workforce#588)
+# ===========================================================================
+# The probe is stubbed hermetically via NANO_INSTALL_GH_STATE / NANO_INSTALL_GH_SCOPES
+# / NANO_INSTALL_GIT_STATE so no real gh/git auth is needed. All run under
+# --dry-run (never blocks) unless a scenario specifically exercises the
+# non-interactive fail path.
+
+# --- Scenario G1: token in env is usable, gh absent → app-fine caveat -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_TOKEN_STATE="ok" GITHUB_TOKEN="fake-usable-token" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG1: token detected treated as usable" \
+  "GitHub token detected in the environment" "$OUT"
+assert_contains "sG1: token+no-gh caveat about harnesses shelling out to gh" \
+  "harnesses that shell out to 'gh' still won't work" "$OUT"
+
+# --- Scenario G1b: a set-but-invalid token FAILS validation (not trusted) ---
+# A non-empty token is not trusted blindly: an expired/revoked/underscoped
+# token is the exact late failure this preflight exists to surface early.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_TOKEN_STATE="bad" GITHUB_TOKEN="fake-invalid-token" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG1b: invalid token reported as failing validation" \
+  "failed validation" "$OUT"
+assert_contains "sG1b: invalid token names remediation (fix or unset)" \
+  "expired, revoked, or lacks access" "$OUT"
+
+# --- Scenario G2: gh missing, no token → not-detected + platform hint -------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG2: no gh + no token reported" \
+  "no gh CLI and no GITHUB_TOKEN/GH_TOKEN" "$OUT"
+assert_contains "sG2: not-detected headline" \
+  "GitHub access not detected" "$OUT"
+assert_contains "sG2: Debian/Ubuntu install hint" "sudo apt install gh" "$OUT"
+assert_contains "sG2: macOS install hint" "brew install gh" "$OUT"
+assert_contains "sG2: gh auth login remediation printed" "gh auth login" "$OUT"
+assert_contains "sG2: this-host-only caveat" "covers THIS host only" "$OUT"
+# The script must NEVER run gh auth login itself — only print it.
+assert_not_contains "sG2: never runs gh auth login (no 'Running' style exec)" \
+  "would run: gh auth login" "$OUT"
+
+# --- Scenario G3: gh present but unauthenticated ---------------------------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="unauthed" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG3: installed-but-unauthenticated state" \
+  "gh is installed but not authenticated" "$OUT"
+
+# --- Scenario G4: gh authenticated but unusable (gh api user fails) ---------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="unusable" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG4: authenticated-but-unusable state (gh api user failed)" \
+  "'gh api user' failed" "$OUT"
+assert_contains "sG4: names SAML SSO as a likely cause" "SAML SSO" "$OUT"
+
+# --- Scenario G5: authenticated + usable, missing repo scope FAILS ----------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="gist,read:org" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG5: missing repo scope fails the check" \
+  "missing the 'repo' scope" "$OUT"
+
+# --- Scenario G6: usable with repo but missing workflow scope only WARNS ----
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="repo,read:org" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG6: missing workflow scope warns (non-fatal)" \
+  "missing the 'workflow' scope" "$OUT"
+assert_contains "sG6: repo+ passes the check" "GitHub access OK via the host gh CLI" "$OUT"
+
+# --- Scenario G7: git absence is flagged -----------------------------------
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="ok" \
+  NANO_INSTALL_GH_SCOPES="repo,workflow" NANO_INSTALL_GIT_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
+assert_contains "sG7: git presence checked alongside gh" \
+  "git not found on this host" "$OUT"
+
+# --- Scenario G8: non-interactive (--yes) FAILS without --allow-no-github ----
+if NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+     sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes >/dev/null 2>&1; then
+  fail "sG8: non-interactive run with no GitHub access should exit non-zero"
+else
+  pass "sG8: non-interactive run with no GitHub access exits non-zero"
+fi
+
+# --- Scenario G9: --allow-no-github lets a non-interactive run proceed -------
+# Under --dry-run this exercises the --allow-no-github *continue* decision (the
+# preflight records GITHUB_DEGRADED and breaks instead of dying). The final
+# summary's degraded-failure line is intentionally NOT emitted here: dry-run
+# makes no changes, so report_and_exit() only records the degraded failure when
+# DRY_RUN=0 — that real-run summary path is a deliberate no-op under --dry-run.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --allow-no-github 2>&1)
+assert_contains "sG9: --allow-no-github continues" \
+  "continuing without GitHub access" "$OUT"
+
+# --- Scenario G9b: git-missing AND github-missing both surface (no masking) --
+# The GitHub-degraded reason must ACCUMULATE onto the earlier git-missing one,
+# not overwrite it — so a host lacking both never loses the git problem behind
+# the GitHub message. Both warnings must appear in the same run.
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" NANO_INSTALL_GH_STATE="missing" \
+  NANO_INSTALL_GIT_STATE="missing" \
+  sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run --allow-no-github 2>&1)
+assert_contains "sG9b: git-missing warning still shown alongside github" \
+  "git not found on this host" "$OUT"
+assert_contains "sG9b: github-missing continue also shown" \
+  "continuing without GitHub access" "$OUT"
+
 # ===========================================================================
 # Phase 2 — install & run the Nano Workforce app (nano-workforce#583)
 # ===========================================================================
@@ -157,10 +266,11 @@ assert_contains "s6b: project name in the run URL" \
   "POST http://localhost:8080/console/api/projects/Fleet/run" "$OUT"
 
 # --- Scenario 6c: GITHUB_TOKEN is redacted in dry-run, never printed --------
-OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" GITHUB_TOKEN="ghp_SHOULD_NOT_APPEAR" \
+OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" GITHUB_TOKEN="SHOULD-NOT-APPEAR-TOKEN" \
+  NANO_INSTALL_TOKEN_STATE="ok" \
   sh "$SCRIPT" --harness copilot:gpt-5.4:1 --yes --dry-run 2>&1)
 assert_contains "s6c: token key present, masked" '"GITHUB_TOKEN":"***"' "$OUT"
-assert_not_contains "s6c: token value never printed" "ghp_SHOULD_NOT_APPEAR" "$OUT"
+assert_not_contains "s6c: token value never printed" "SHOULD-NOT-APPEAR-TOKEN" "$OUT"
 
 # --- Scenario 7: --skip-app runs phase 1 only, emits no console calls -------
 OUT=$(NANO_INSTALL_HARNESSES_OVERRIDE="copilot" \
@@ -303,7 +413,7 @@ CJS
     # newline) must be rejected with a clear error before any JSON config body
     # is emitted, never producing invalid JSON that fails the console API
     # opaquely. The token flows through json_str() unredacted on the live PUT.
-    _ctrl_token="$(printf 'ghp_bad\ntoken')"
+    _ctrl_token="$(printf 'fake-bad\ntoken')"
     export GITHUB_TOKEN="$_ctrl_token"
     run_phase2 happy
     unset GITHUB_TOKEN