@nanobpm/nano-workforce 0.78.0 → 0.80.0

package/app/service.test.ts

@@ -7,7 +7,7 @@
 // GitHub transport forced off so it is hermetic.
 import { test } from "node:test";
 import { assertEquals } from "#test-assert";
-import { parsePr, pollIncidentsImpl, repoEnvelopeVars, submitPr } from "./service.ts";
+import { parsePr, pollIncidentsImpl, repoEnvelopeVars, startMerge, submitPr } from "./service.ts";
 
 function memTable(rows: any[], key: string) {
   return {
@@ -331,6 +331,109 @@ test("submitPr defaults convergeOnly to false so the global auto-merge default g
   });
 });
 
+// Lineage threading (issue #245): `submitPr` persists the origin `root_request_key` on the PR row
+// and carries it onto the convergence instance; `startMerge` reads it back off the row onto the
+// merge instance. A human/webhook submit that supplies no root self-roots on the `pr_key` (its own
+// root), and a resubmit that omits the root must not clobber a root already learned.
+function captureRoot() {
+  const stores: Record<string, { rows: unknown[]; key: string }> = {
+    pull_requests: { rows: [], key: "pr_key" },
+    escalations: { rows: [], key: "id" },
+    pr_dependencies: { rows: [], key: "pr_key" },
+  };
+  const data = {
+    table: (name: string, key: string) => memTable(stores[name]?.rows ?? [], stores[name]?.key ?? key),
+  } as any;
+  let captured: unknown;
+  const engine = {
+    createInstance: (req: { variables?: Record<string, unknown> }) => {
+      captured = req.variables?.rootRequestKey;
+      return Promise.resolve({ processInstanceKey: "PI-1" });
+    },
+  } as any;
+  return { data, engine, stores, get: () => captured };
+}
+
+test("submitPr persists root_request_key and threads it onto the convergence instance", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 8, url: "https://github.com/owner/repo/pull/8", prKey: "owner/repo#8" },
+      [],
+      20,
+      false,
+      "owner/repo#1",
+    );
+    assertEquals(get(), "owner/repo#1");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#1");
+  });
+});
+
+test("submitPr self-roots root_request_key on the pr_key for a human/webhook submit (its own root)", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 9,
+      url: "https://github.com/owner/repo/pull/9",
+      prKey: "owner/repo#9",
+    });
+    assertEquals(get(), "owner/repo#9");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#9");
+  });
+});
+
+test("submitPr resubmit does not clobber an already-learned root when omitted", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, stores, get } = captureRoot();
+    (stores.pull_requests.rows as unknown[]).push({
+      pr_key: "owner/repo#8",
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      status: "abandoned", // terminal -> re-open path
+      current_round: 3,
+      root_request_key: "owner/repo#1",
+    });
+    await submitPr(data, engine, {
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      prKey: "owner/repo#8",
+    });
+    assertEquals(get(), "owner/repo#1", "resubmit re-threads the learned root");
+    const pr = stores.pull_requests.rows[0] as Record<string, unknown>;
+    assertEquals(pr.root_request_key, "owner/repo#1");
+  });
+});
+
+test("startMerge reads root_request_key off the PR row onto the merge instance", async () => {
+  await withGithubOff(async () => {
+    const { data, engine, get } = captureRoot();
+    await submitPr(
+      data,
+      engine,
+      { repo: "owner/repo", number: 8, url: "https://github.com/owner/repo/pull/8", prKey: "owner/repo#8" },
+      [],
+      20,
+      false,
+      "owner/repo#1",
+    );
+    await startMerge(data, engine, {
+      repo: "owner/repo",
+      number: 8,
+      url: "https://github.com/owner/repo/pull/8",
+      prKey: "owner/repo#8",
+      round: 2,
+    });
+    assertEquals(get(), "owner/repo#1");
+  });
+});
+
 // The repository envelope drives the c8ctl harness's isolated workspace provisioning: it is
 // emitted under the reserved `io.nanobpm.agentTask` namespace with the PR head branch as the
 // checkout ref, and omitted entirely when the head branch couldn't be resolved (so the harness

package/app/service.ts

@@ -11,6 +11,7 @@ import { readFileSync } from "node:fs";
 import type { DataLayer, EngineClient } from "@nanobpm/urban";
 import { abandonUrl, mintAbandonToken, renderAbandonBrief } from "./abandon.ts";
 import { agentSlaTimeout } from "./agentSla.ts";
+import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
 import { deriveFeatureBlockedPatch, deriveFeatureDelivery, deriveFeatureEscalationPatch, FEATURE_BLOCKED_ELEMENT, FEATURE_ESCALATION_ELEMENT, FEATURE_RUN_STATUSES, type FeatureRun, type FeatureRunStatus, featureRuns } from "./feature.ts";
 import {
   classifyMergeability,
@@ -26,6 +27,7 @@ import {
   type PrState,
   requestCopilotReview,
 } from "./github.ts";
+import { pollLineage } from "./lineage.ts";
 import { mergeLanes, readExclusions } from "./mergeExclusion.ts";
 import { freshHeadRunAction, headRunPresenceCount, loadMergeProtocol } from "./mergeProtocol.ts";
 import { type PrLaneDecision, planPrLane, taskDependencyDepths } from "./mergeTrain.ts";
@@ -122,77 +124,6 @@ export const MERGE_ADMIN = ["1", "true", "on", "yes"].includes(
 
 const now = () => new Date().toISOString();
 
-/** A PR is "done" in exactly these states; everything else (converging, waiting_review,
- * escalated, and the merge-stage waiting_deps/waiting_merge/waiting_lane/queued) is in flight. `converged`
- * is terminal only in review-only mode (AUTO_MERGE off); with auto-merge on, a converged PR
- * transitions into the merge stage and lands as `merged`. The status endpoint and the cancel
- * guard both key off this set. */
-export const TERMINAL_STATUSES: readonly string[] = ["converged", "merged", "abandoned"];
-
-/** The derived epic delivery signal (issue #171). Distinct from `plan.status`: `status = done`
- * means "the fan-out finished and ≥1 slice opened a PR, dispatched to convergence" (record-results
- * sets it as soon as one PR opened — other slices may be blocked/skipped), which conflates hand-off
- * with landing. `delivery` reports whether those slice PRs have actually MERGED. */
-export type Delivery = "converging" | "landed";
-
-/** Rollup of a plan's slice-PR landing state, derived by joining `plan_tasks.pr_key` →
- * `pull_requests.status`. Pure and read-only — the single source of truth for the denormalised
- * `plans.delivery` / `plans.delivery_label` columns the poller projects. */
-export interface DeliveryRollup {
-  delivery: Delivery | null;
-  label: string | null;
-  prsOpened: number;
-  prsMerged: number;
-  prsInFlight: number;
-}
-
-/** Derive the delivery signal for one plan from its status and the statuses of its slice PRs.
- *
- * - `converging` — the plan is `done` but ≥1 slice PR is still non-terminal (in flight).
- * - `landed` — every slice PR merged: `prsInFlight == 0 && prsMerged == prsOpened && prsOpened > 0`.
- * - `null` — no positive signal yet: the plan isn't `done`, it opened no PRs, or every PR is
- *   terminal but not all merged (some `abandoned`/`converged` — resolved-not-landed, per the issue).
- *
- * A slice's PR status is "in flight" iff it is NOT in `TERMINAL_STATUSES`; `abandoned`/`converged`
- * count as resolved-not-landed (terminal but not merged), so they never make an epic `landed`. */
-export function deriveDelivery(
-  planStatus: string,
-  prStatuses: readonly string[],
-): DeliveryRollup {
-  const prsOpened = prStatuses.length;
-  let prsMerged = 0;
-  let prsInFlight = 0;
-  for (const s of prStatuses) {
-    if (s === "merged") prsMerged++;
-    else if (!TERMINAL_STATUSES.includes(s)) prsInFlight++;
-  }
-  // `delivery` is only meaningful once the fan-out has been dispatched (`status = done`) and at
-  // least one slice PR exists; otherwise there is nothing to have landed yet.
-  if (planStatus !== "done" || prsOpened === 0) {
-    return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
-  }
-  if (prsInFlight > 0) {
-    return {
-      delivery: "converging",
-      label: `${prsMerged}/${prsOpened} slices merged, ${prsInFlight} converging`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  if (prsMerged === prsOpened) {
-    return {
-      delivery: "landed",
-      label: `${prsOpened}/${prsOpened} slices merged`,
-      prsOpened,
-      prsMerged,
-      prsInFlight,
-    };
-  }
-  // Every slice PR is terminal but not all merged (some abandoned/converged): resolved, not landed.
-  return { delivery: null, label: null, prsOpened, prsMerged, prsInFlight };
-}
-
 interface PullRequest {
   pr_key: string;
   repo: string;
@@ -233,6 +164,13 @@ interface PullRequest {
   // workflow stage.
   incident_key: string | null;
   incident_message: string | null;
+  // Lineage projection (037_lineage.sql, issue #245): the stable ORIGIN identity (the issue =
+  // feature_key / plan_key) threaded onto this PR by `submitPr`, and passed as a `createInstance`
+  // variable onto the convergence + merge instances so every descendant carries the root. For a
+  // human-opened / webhook PR with no originating request, `submitPr` self-roots it to its own
+  // `pr_key` so the Lineage UI join resolves; a legacy NULL is tolerated the same way by the
+  // lineage read projection (`pollLineage`), which self-roots on `pr_key`.
+  root_request_key: string | null;
 }
 
 interface PrDependency {
@@ -413,6 +351,7 @@ export async function submitPr(
   dependsOn: string[] = [],
   maxRounds: number = MAX_ROUNDS,
   convergeOnly = false,
+  rootRequestKey: string | null = null,
 ) {
   const table = prs(data);
   const existing = await table.get(parsed.prKey);
@@ -447,6 +386,15 @@ export async function submitPr(
   // Cooperative abandon check (#76): reuse the PR's existing capability token across re-runs (and
   // the later merge instance), or mint one for a first submission.
   const abandonToken = existing?.abandon_token ?? mintAbandonToken();
+  // Lineage (issue #245): the origin identity threaded onto this PR + its convergence/merge
+  // instances. A caller (feature/epic hand-off) supplies it on the first submit; a resubmit that
+  // omits it must not clobber a root already learned, so coalesce onto the existing row's value. A
+  // human/webhook submit supplies none → the PR is its OWN root, so self-root on its `pr_key`
+  // (never NULL): the Lineage page drills into a thread's member PRs by joining
+  // `lineage_threads.root_request_key` → `pull_requests.root_request_key`, and a self-rooted
+  // thread's key IS the `pr_key`, so leaving the PR row NULL would render an empty PR list for it.
+  // Persisting `pr_key` keeps that join honest (the projection self-roots the same key either way).
+  const effectiveRoot = rootRequestKey ?? existing?.root_request_key ?? parsed.prKey;
   if (existing) {
     // A prior run (cancelled, converged, or otherwise superseded) may have left an OPEN
     // escalation row. A fresh convergence run must not inherit that stale answer — the
@@ -474,6 +422,7 @@ export async function submitPr(
       converged_at: null,
       merged_at: null,
       abandon_token: abandonToken,
+      root_request_key: effectiveRoot,
       updated_at: ts,
     });
   } else {
@@ -488,6 +437,7 @@ export async function submitPr(
       status: "converging",
       current_round: 1,
       abandon_token: abandonToken,
+      root_request_key: effectiveRoot,
       created_at: ts,
       updated_at: ts,
     });
@@ -503,6 +453,10 @@ export async function submitPr(
       round: 1,
       maxRounds: clampRounds(maxRounds, MAX_ROUNDS),
       reviewWaitTimeout: REVIEW_WAIT_TIMEOUT,
+      // Lineage (issue #245): carry the origin identity onto the convergence instance so every
+      // descendant (and any message it correlates) is stitched back to the originating request.
+      // A human/webhook PR that is its own root carries its own `pr_key` (never NULL — see above).
+      rootRequestKey: effectiveRoot,
       // Per-request review-only override: carried on the instance so `pr.finalize` can stop at
       // `converged` for this PR without handing off to the merge-loop, independent of the global
       // NANO_PR_AUTO_MERGE default. Only ever narrows (never forces merge on when auto-merge is off).
@@ -539,6 +493,11 @@ export async function startMerge(
   if (!existing?.abandon_token) {
     await prs(data).update(pr.prKey, { abandon_token: abandonToken, updated_at: now() });
   }
+  // Lineage (issue #245): the origin identity was persisted on the PR row at submit; carry it onto
+  // the merge instance too so the merge stage stays stitched to the originating request. A
+  // self-rooted PR carries its own `pr_key`; `?? null` only tolerates a legacy row predating the
+  // column.
+  const rootRequestKey = existing?.root_request_key ?? null;
   const abUrl = abandonUrl(abandonToken);
   // Resolve the PR head branch so the merge agents (fix-ci, rebase) get an isolated clone checked
   // out on it (same host-git provisioning path as review-round). Best-effort: an unresolved head
@@ -566,6 +525,8 @@ export async function startMerge(
       rebaseRound: 0,
       rebaseMax: MAX_REBASE_ROUNDS,
       agentSlaTimeout: AGENT_SLA_TIMEOUT,
+      // Lineage (issue #245): thread the origin identity onto the merge instance (see startMerge).
+      rootRequestKey,
       abandonUrl: abUrl,
       abandonBrief: renderAbandonBrief(abUrl),
       // Host-git provisioning (c8ctl): same repository envelope as the convergence loop, so the
@@ -1610,6 +1571,7 @@ export async function pollOnce(
   await pollWaveGates(data, engine, token);
   await pollDelivery(data);
   await pollFeatureDelivery(data);
+  await pollLineage(data);
   await pollFeatureEscalations(data, engine);
   await pollFeatureBlocked(data, engine);
   await pollUserTasks(data, engine);

package/db/migrations/037_lineage.sql

@@ -0,0 +1,69 @@
+-- Lineage projection (issue #245): thread user intent → progress as one arc.
+--
+-- The lineage already exists in the data layer (feature_runs.pr_key ↔ pull_requests.pr_key,
+-- plan_tasks.pr_key ↔ pull_requests.pr_key, and message correlation by prKey/planKey) but is not
+-- projected as a single narrative. This migration adds the two pieces the read model needs:
+--
+--   1. `pull_requests.root_request_key` — the stable ORIGIN identity (the issue = feature_key /
+--      plan_key) threaded onto every PR a request spawns. `submitPr` persists it and passes it as a
+--      `createInstance` variable onto the convergence + merge instances; `startMerge` reads it back
+--      off the row. A human-opened / webhook PR with no originating request is self-rooted by
+--      `submitPr` (`root_request_key = pr_key`); a legacy pre-migration NULL is backfilled below to
+--      the SAME root submitPr would persist (feature/epic origin key, else self-rooted pr_key), and
+--      the projection tolerates any residual NULL by self-rooting on `pr_key`.
+--
+--   2. `lineage_threads` — a DERIVED read table, one row per `root_request_key` (or a self-rooted
+--      PR's own key), recomputed idempotently each poll pass by `pollLineage` (app/lineage.ts) from
+--      the existing gateway joins. It stitches `request → implementation run → PR(s) → convergence →
+--      merge → outcome` into one ordered thread, exposing the active frontier (`stage`/`stage_label`/
+--      `process_key`) plus whether the whole arc has settled (`active`). Urban's datasource cannot
+--      read a SQL VIEW (gateway.ts schema() whitelists only type='table'), so — following the
+--      codebase convention for read-model projections (`plans.delivery`, `feature_runs.delivery_label`)
+--      — this is a denormalised flat table the schema-driven pages read directly.
+--
+-- Forward-only, additive (expand): a nullable column with no default, a new table/indexes, and an
+-- origin-aware backfill of the new column. Numbered after the current highest prefix (036). The
+-- runner wraps each file in its own transaction, so this file must NOT contain BEGIN/COMMIT.
+ALTER TABLE pull_requests ADD COLUMN root_request_key TEXT;
+CREATE INDEX IF NOT EXISTS idx_pr_root ON pull_requests(root_request_key);
+
+-- Backfill: every pre-migration PR row has root_request_key = NULL, which breaks the Lineage page's
+-- `lineage_threads.root_request_key → pull_requests.root_request_key` drill-down join (a NULL never
+-- matches a thread key), rendering an empty PR list. Backfill each row with the SAME root `submitPr`
+-- persists going forward, so the join resolves for already-tracked PRs at deploy time too:
+--   1. a PR spawned by a feature run roots on its origin `feature_runs.feature_key` (submitPr passes
+--      `featureKey` — workers/converge-feature);
+--   2. a PR spawned by an epic slice roots on its origin `plan_tasks.plan_key` (submitPr passes
+--      `planKey` — workers/record-wave);
+--   3. any remaining origin-less PR (human/webhook, or an origin row that no longer survives) is
+--      self-rooted on its own `pr_key`, exactly as `submitPr` self-roots a human/webhook PR.
+-- Origin-aware steps run first so a tracked PR keeps its true origin key rather than being self-rooted
+-- (which would orphan it from its feature/epic thread in the drill-down). All idempotent.
+UPDATE pull_requests SET root_request_key = (
+    SELECT fr.feature_key FROM feature_runs fr WHERE fr.pr_key = pull_requests.pr_key
+  )
+  WHERE root_request_key IS NULL
+    AND EXISTS (SELECT 1 FROM feature_runs fr WHERE fr.pr_key = pull_requests.pr_key);
+UPDATE pull_requests SET root_request_key = (
+    SELECT pt.plan_key FROM plan_tasks pt WHERE pt.pr_key = pull_requests.pr_key
+  )
+  WHERE root_request_key IS NULL
+    AND EXISTS (SELECT 1 FROM plan_tasks pt WHERE pt.pr_key = pull_requests.pr_key);
+UPDATE pull_requests SET root_request_key = pr_key WHERE root_request_key IS NULL;
+
+CREATE TABLE IF NOT EXISTS lineage_threads (
+  root_request_key TEXT PRIMARY KEY,        -- origin issue key (feature_key/plan_key), or a self-rooted pr_key
+  kind             TEXT NOT NULL,            -- feature | epic | pr
+  title            TEXT,                     -- best-effort origin/PR title
+  issue_url        TEXT,                     -- origin issue URL (NULL for self-rooted PRs)
+  stage            TEXT NOT NULL,            -- active-frontier machine label (implementing|converging|merged|…)
+  stage_label      TEXT,                     -- human narrative rollup for the timeline
+  process_key      TEXT,                     -- active-frontier process instance (for the processExplorer link)
+  pr_keys          TEXT,                     -- JSON array of the member PR keys (fan-out for epics)
+  pr_count         INTEGER NOT NULL DEFAULT 0,
+  active           INTEGER NOT NULL DEFAULT 1, -- 1 while the arc has an active frontier, 0 once settled
+  created_at       TEXT NOT NULL,
+  updated_at       TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_lineage_active ON lineage_threads(active);

package/openapi.yaml

@@ -99,6 +99,99 @@ components:
           type: array
           items:
             $ref: "#/components/schemas/ActivePr"
+    LineagePrView:
+      type: object
+      description: A member PR of a lineage thread (issue #245).
+      additionalProperties: false
+      required:
+        - prKey
+        - title
+        - url
+        - status
+        - round
+        - processKey
+        - outcome
+      properties:
+        prKey:
+          type: string
+        title:
+          type: string
+          nullable: true
+        url:
+          type: string
+        status:
+          type: string
+        round:
+          type: integer
+        processKey:
+          type: string
+          nullable: true
+        outcome:
+          type: string
+          nullable: true
+    LineageThreadView:
+      type: object
+      description: One stitched intent → progress arc, keyed by its origin request (issue #245).
+      additionalProperties: false
+      required:
+        - rootRequestKey
+        - kind
+        - title
+        - issueUrl
+        - stage
+        - stageLabel
+        - processKey
+        - prKeys
+        - prCount
+        - active
+        - prs
+      properties:
+        rootRequestKey:
+          type: string
+          description: The origin issue key (feature_key/plan_key), or a self-rooted pr_key.
+        kind:
+          type: string
+          enum: [feature, epic, pr]
+        title:
+          type: string
+          nullable: true
+        issueUrl:
+          type: string
+          nullable: true
+        stage:
+          type: string
+          description: The active-frontier stage (implementing|converging|merged|…).
+        stageLabel:
+          type: string
+        processKey:
+          type: string
+          nullable: true
+          description: The active-frontier process instance key (for the processExplorer link).
+        prKeys:
+          type: array
+          items:
+            type: string
+        prCount:
+          type: integer
+        active:
+          type: boolean
+          description: True while the arc has an active frontier; false once every stage has settled.
+        prs:
+          type: array
+          items:
+            $ref: "#/components/schemas/LineagePrView"
+    LineageList:
+      type: object
+      required:
+        - count
+        - threads
+      properties:
+        count:
+          type: integer
+        threads:
+          type: array
+          items:
+            $ref: "#/components/schemas/LineageThreadView"
     AgenticSupplyWorker:
       type: object
       description: One connected worker in the supply mirror (H5 cockpit; sourced from the H1 presence registry).
@@ -936,6 +1029,33 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/ErrorBody"
+  /lineage:
+    get:
+      operationId: getLineage
+      summary: "Intent to progress lineage projection (issue #245): every request stitched into one arc (request, implementation, PRs, convergence, merge, outcome), active frontier first. Pass root to fetch a single origin's thread."
+      security:
+        - hookSecret: []
+        - {}
+      parameters:
+        - name: root
+          in: query
+          required: false
+          schema:
+            type: string
+          description: "An origin request key (feature_key/plan_key) or a self-rooted pr_key. When set, the response contains just that thread (empty if unknown)."
+      responses:
+        "200":
+          description: The stitched lineage threads.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/LineageList"
+        "401":
+          description: Missing/invalid shared secret (only when NANO_PR_WEBHOOK_SECRET is set).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ErrorBody"
   /agentic/supply:
     get:
       operationId: getAgenticSupply

package/operations/getLineage.test.ts

@@ -0,0 +1,105 @@
+// Tests for GET /app/api/lineage → operation `getLineage` (issue #245). Covers the stitched list
+// projection, the `root` narrowing, an unknown root (empty), and the optional shared-secret guard.
+// A minimal in-memory DataLayer backs the derivation (it reads the feature_runs / plans / plan_tasks
+// / pull_requests tables via `.all()` / `.find()`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { AppApi } from "@nanobpm/urban";
+import { noopLog } from "../test/log.ts";
+import handler from "./getLineage.ts";
+
+function memApp(stores: Record<string, any[]>): AppApi {
+  const table = (name: string) => {
+    const rows = stores[name] ?? [];
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async find(where: Record<string, unknown> = {}) {
+        return rows.filter((r) => Object.entries(where).every(([k, v]) => r[k] === v));
+      },
+    };
+  };
+  return { data: { table }, log: noopLog() } as any as AppApi;
+}
+
+function input(query: Record<string, string> = {}, headers: Record<string, string> = {}) {
+  return {
+    req: {
+      method: "GET",
+      path: "/app/api/lineage",
+      query: new URLSearchParams(query),
+      headers: new Headers(headers),
+      text: async () => "",
+    } as any,
+    params: {},
+    query,
+    body: undefined,
+  };
+}
+
+function fixture(): Record<string, any[]> {
+  return {
+    feature_runs: [
+      { feature_key: "o/r#1", title: "Feature", issue_url: "u1", status: "converging", process_key: "f1", pr_key: "o/r#100" },
+    ],
+    plans: [
+      { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1" },
+    ],
+    plan_tasks: [
+      { id: 1, plan_key: "o/r#2", pr_key: "o/r#200" },
+      { id: 2, plan_key: "o/r#2", pr_key: "o/r#201" },
+    ],
+    pull_requests: [
+      { pr_key: "o/r#100", title: "Feat PR", url: "x", status: "converging", current_round: 2, process_key: "c1", outcome: null, root_request_key: "o/r#1" },
+      { pr_key: "o/r#200", title: "S1", url: "x", status: "merged", current_round: 1, process_key: "c2", outcome: null, root_request_key: "o/r#2" },
+      { pr_key: "o/r#201", title: "S2", url: "x", status: "converging", current_round: 1, process_key: "c3", outcome: null, root_request_key: "o/r#2" },
+      { pr_key: "o/r#300", title: "Human PR", url: "x", status: "merged", current_round: 1, process_key: "c4", outcome: null, root_request_key: null },
+    ],
+  };
+}
+
+test("lists every stitched thread, active frontier first", async () => {
+  const res = (await handler(input(), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 3);
+  // Active threads (feature + epic) sort ahead of the settled human PR.
+  assert(res.body.threads[res.body.threads.length - 1].active === false);
+  const kinds = res.body.threads.map((t: any) => t.kind).sort();
+  assertEquals(kinds, ["epic", "feature", "pr"]);
+});
+
+test("narrows to a single origin thread via ?root=", async () => {
+  const res = (await handler(input({ root: "o/r#2" }), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 1);
+  const t = res.body.threads[0];
+  assertEquals(t.kind, "epic");
+  assertEquals(t.rootRequestKey, "o/r#2");
+  assertEquals(t.prCount, 2);
+});
+
+test("unknown root returns an empty thread list", async () => {
+  const res = (await handler(input({ root: "o/r#999" }), memApp(fixture()))) as any;
+  assertEquals(res.status, 200);
+  assertEquals(res.body.count, 0);
+  assertEquals(res.body.threads, []);
+});
+
+test("shared-secret guard rejects a missing secret when configured", async () => {
+  const prev = process.env["NANO_PR_WEBHOOK_SECRET"];
+  process.env["NANO_PR_WEBHOOK_SECRET"] = "s3cr3t";
+  try {
+    const mod = await import(`./getLineage.ts?guard=${Date.now()}`);
+    const guarded = mod.default as typeof handler;
+    const app = memApp(fixture());
+    const bad = (await guarded(input(), app)) as any;
+    assertEquals(bad.status, 401);
+    const ok = (await guarded(input({}, { "x-hook-secret": "s3cr3t" }), app)) as any;
+    assertEquals(ok.status, 200);
+    assert("count" in ok.body);
+  } finally {
+    if (prev === undefined) delete process.env["NANO_PR_WEBHOOK_SECRET"];
+    else process.env["NANO_PR_WEBHOOK_SECRET"] = prev;
+  }
+});

package/operations/getLineage.ts

@@ -0,0 +1,32 @@
+// GET /app/api/lineage → operationId `getLineage` (issue #245). Project user intent → progress as
+// one lineage arc per origin request, so an operator or an external harness can see, in one place,
+// that "issue #123 → implementation → PR #45 → converging (round 2) → merged" is a single thread of
+// their intent — without opening the DB or joining the tables by hand. Read-only projection over the
+// existing record-gateway joins (the same derivation the `lineage_threads` read table is built from).
+//
+// Optional `root` query param narrows to a single origin's thread (feature_key/plan_key, or a
+// self-rooted pr_key for a human/webhook PR). Absent → every thread, active frontier first.
+//
+// The optional shared-secret guard stays HERE (the runtime does not enforce OpenAPI `security`):
+// when NANO_PR_WEBHOOK_SECRET is set, callers must present it via the x-hook-secret header.
+import { getLineage, listLineage } from "../app/lineage.ts";
+import { envVar } from "../app/version.ts";
+import { defineOperation } from "../nano-generated/operations.ts";
+
+const SECRET = envVar("NANO_PR_WEBHOOK_SECRET") ?? "";
+
+export default defineOperation("getLineage", async ({ query, req }, app) => {
+  if (SECRET && req.headers.get("x-hook-secret") !== SECRET) {
+    app.log.warn("getLineage rejected: missing/invalid shared secret");
+    return { status: 401, body: { error: "unauthorized" } };
+  }
+  const rawRoot = query.root;
+  const root = typeof rawRoot === "string" ? rawRoot.trim() : "";
+  if (root) {
+    const thread = await getLineage(app.data, root);
+    const threads = thread ? [thread] : [];
+    return { status: 200, body: { count: threads.length, threads } };
+  }
+  const threads = await listLineage(app.data);
+  return { status: 200, body: { count: threads.length, threads } };
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nanobpm/nano-workforce",
-  "version": "0.78.0",
+  "version": "0.80.0",
   "description": "Nano Workforce — an Agent Graph Orchestration application for Agentic SDLC: durable BPMN processes that coordinate a graph of AI agents across the software delivery lifecycle.",
   "type": "module",
   "main": "main.ts",

package/pages/cockpit.page.json

@@ -10,6 +10,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },

package/pages/epic-detail.page.json

@@ -11,6 +11,7 @@
         "title": "Nano Workforce",
         "items": [
           { "label": "Overview", "page": "overview" },
+          { "label": "Lineage", "page": "lineage" },
           { "label": "Convergence", "page": "home" },
           { "label": "Epics", "page": "epic" },
           { "label": "Feature", "page": "feature" },