@nanobpm/nano-workforce 0.78.0 → 0.80.0

package/app/agentic/transcript-fork.ts

@@ -0,0 +1,151 @@
+// nano-workforce — replay-by-reseed / fork of a transcript log (ADR 0056, #251).
+//
+// The H3 read path (#222) can RESUME the same stream from an offset (reattach parity), but it cannot
+// FORK: seed a NEW stream from an existing log so an exited agent's session can be branched or re-run
+// from a chosen point ("what-if" a different continuation). dsh gets this for free because a session IS
+// its append-only log, so forking is just re-seeding a new session from an existing log up to offset N.
+// This module gives the transcript store the same capability WITHOUT touching the store package: it
+// reads the source log and re-records it into a fresh stream through the store's own idempotent,
+// offset-keyed {@link TranscriptStore.record} — so the fork is itself append-only and offset-parity
+// with its source, and replays through the SAME resume-from-offset read path a native stream uses.
+//
+// Invariants preserved (ADR 0056): app-tier only, append-only (we only ever `record`, never mutate),
+// advisory (a fork is a new advisory transcript — it gates no BPMN flow), and offset/resume wire-shape
+// parity (the fork keeps the source offsets, so a reattach behaves identically on the branch).
+
+import type { TranscriptChunk, TranscriptLifecycle, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
+
+/** Raised when a fork/reseed cannot proceed — the source is missing, or the target already exists. */
+export class TranscriptForkError extends Error {
+  readonly source: string;
+  readonly target: string;
+  constructor(source: string, target: string, message: string) {
+    super(message);
+    this.name = "TranscriptForkError";
+    this.source = source;
+    this.target = target;
+  }
+}
+
+/** Options controlling how a source log is reseeded into a new stream. */
+export interface ForkTranscriptOptions {
+  /**
+   * Seed only chunks with `offset <= throughOffset` (inclusive) — the point the branch diverges from.
+   * Omit to fork the WHOLE source log (every retained chunk). A `throughOffset` below the source's
+   * oldest retained offset yields an empty fork (a valid, if trivial, branch point).
+   */
+  readonly throughOffset?: number;
+  /**
+   * The forked stream's retention lifecycle. Defaults to `ephemeral` — a fork is a captured branch,
+   * retained-whole then swept like any completed session, not a growing live stream.
+   */
+  readonly lifecycle?: TranscriptLifecycle;
+  /**
+   * Allow reseeding into a target that already exists. Off by default: forking onto a populated stream
+   * would interleave two logs' bytes and defeat offset-parity, so we refuse rather than clobber. When
+   * on, seeding is still idempotent (offset-keyed), so re-running the SAME fork is a safe no-op — but
+   * the existing target must already hold exactly this seed prefix (same offsets, same chunk bytes,
+   * same lifecycle); a target that diverges from the prefix throws rather than silently interleaving.
+   */
+  readonly allowExisting?: boolean;
+}
+
+/** The outcome of a {@link forkTranscript}: the new stream, how many chunks it seeded, and its window. */
+export interface ForkResult {
+  /** The forked stream id (the `target` argument). */
+  readonly stream: string;
+  /** The source stream the fork was seeded from. */
+  readonly source: string;
+  /** Number of chunks newly persisted into the fork. */
+  readonly seeded: number;
+  /** The highest source offset included in the fork (undefined when the fork is empty). */
+  readonly throughOffset?: number;
+  /** The forked stream's metadata after seeding. */
+  readonly meta: TranscriptStream;
+}
+
+/**
+ * Fork a transcript: seed a NEW stream (`target`) from an existing log (`source`) up to a chosen offset,
+ * so an exited session can be branched and replayed independently.
+ *
+ * The fork keeps the SOURCE offsets (offset-parity), so it resumes through the identical
+ * resume-from-offset read path a native stream uses. It reads the source's retained window
+ * (`store.read`), takes the prefix at or below `throughOffset` (default: the whole log), and re-records
+ * it into `target` via the store's idempotent offset-keyed `record` — so the operation is append-only
+ * and safe to re-run. The branch is fully independent of its source thereafter: appending to either
+ * stream never affects the other.
+ *
+ * Throws {@link TranscriptForkError} when the source has no transcript, when the target already
+ * exists and `allowExisting` is not set, or when `allowExisting` is set but the existing target does
+ * not already match the reseed prefix exactly (divergent chunk bytes/offsets or a different lifecycle).
+ */
+export function forkTranscript(
+  store: TranscriptStore,
+  source: string,
+  target: string,
+  options: ForkTranscriptOptions = {},
+): ForkResult {
+  if (source === target) {
+    throw new TranscriptForkError(source, target, "cannot fork a stream onto itself");
+  }
+  if (store.get(source) === undefined) {
+    throw new TranscriptForkError(source, target, `source stream "${source}" has no transcript to fork`);
+  }
+  const existing = store.get(target);
+  if (existing !== undefined && !options.allowExisting) {
+    throw new TranscriptForkError(source, target, `target stream "${target}" already exists (pass allowExisting to reseed it)`);
+  }
+
+  const lifecycle: TranscriptLifecycle = options.lifecycle ?? "ephemeral";
+  const through = options.throughOffset;
+  const chunks: TranscriptChunk[] = store
+    .read(source)
+    .filter((c) => through === undefined || c.offset <= through);
+
+  // Reseeding onto an EXISTING target (allowExisting) is only safe when that target already holds
+  // exactly the prefix we are about to seed. `record()` is offset-keyed and idempotent, so it silently
+  // no-ops any offset already present — if the existing chunk at that offset differs (or the target
+  // carries offsets outside this prefix, or a different lifecycle), the reseed would leave a stream
+  // that is a MIXTURE of the prior data and the seed, breaking the documented offset-parity invariant.
+  // Validate the overlap before writing and refuse rather than clobber/interleave.
+  if (existing !== undefined) {
+    if (existing.lifecycle !== lifecycle) {
+      throw new TranscriptForkError(
+        source,
+        target,
+        `target stream "${target}" already exists with lifecycle "${existing.lifecycle}", cannot reseed as "${lifecycle}"`,
+      );
+    }
+    const seedByOffset = new Map(chunks.map((c) => [c.offset, c.chunk]));
+    for (const c of store.read(target)) {
+      const expected = seedByOffset.get(c.offset);
+      if (expected === undefined || expected !== c.chunk) {
+        throw new TranscriptForkError(
+          source,
+          target,
+          `target stream "${target}" already contains data that does not match the reseed prefix at offset ${c.offset}; refusing to interleave`,
+        );
+      }
+    }
+  }
+
+  // Open the fork explicitly so an empty fork (throughOffset predating the log) is still a real,
+  // listed stream under its own lifecycle rather than a phantom — mirrors the store's open-then-record.
+  store.open(target, lifecycle);
+  const seeded = chunks.length > 0 ? store.record(target, chunks, lifecycle) : 0;
+
+  const meta = store.get(target);
+  if (meta === undefined) {
+    // Defensive: open() above guarantees a row, so this only fires on a store contract breach.
+    throw new TranscriptForkError(source, target, `fork of "${source}" into "${target}" did not persist a stream`);
+  }
+
+  const result: ForkResult = {
+    stream: target,
+    source,
+    seeded,
+    meta,
+  };
+  const last = chunks.at(-1);
+  return last !== undefined ? { ...result, throughOffset: last.offset } : result;
+}

package/app/agentic/transcript-read.ts

@@ -17,11 +17,12 @@
 import type { TranscriptChunk, TranscriptStore, TranscriptStream } from "@nanobpm/agentic/transcript";
 import type { AgenticTranscript, AgenticTranscriptData } from "../../nano-generated/api-io.d.ts";
 import { type CorrelationRegistry, jobKeyOfStream } from "./correlation.ts";
+import { utf8ByteLength } from "./transcript-events.ts";
 
 /** Total captured bytes across a set of retained chunks (UTF-8, the on-the-wire terminal encoding). */
 export function byteLengthOf(chunks: readonly TranscriptChunk[]): number {
   let total = 0;
-  for (const c of chunks) total += Buffer.byteLength(c.chunk, "utf8");
+  for (const c of chunks) total += utf8ByteLength(c.chunk);
   return total;
 }
 

package/app/delivery.test.ts

@@ -6,7 +6,8 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import type { DataLayer } from "@nanobpm/urban";
-import { deriveDelivery, pollDelivery, TERMINAL_STATUSES } from "./service.ts";
+import { deriveDelivery, TERMINAL_STATUSES } from "./delivery.ts";
+import { pollDelivery } from "./service.ts";
 
 // A tiny in-memory record gateway (all/find/update/insert), mirroring the fake-app style used
 // across the app tests (see app/taskDelta.test.ts), enough to exercise the `pollDelivery` projection.

package/app/delivery.ts

@@ -0,0 +1,76 @@
+// Canonical PR-terminal / epic-delivery derivation, extracted from `service.ts` so that the
+// lineage read-projection (`app/lineage.ts`) can reuse `deriveDelivery`/`TERMINAL_STATUSES`
+// without importing `service.ts` — which imports `pollLineage` back from `lineage.ts` and would
+// otherwise form a `service.ts` ↔ `lineage.ts` module cycle (fragile in ESM). This is the single
+// source of truth for both; `service.ts` re-uses it and remains free to import `pollLineage`.
+
+/** 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 };
+}

package/app/instance-tracking.test.ts

@@ -7,7 +7,8 @@
 import { test } from "node:test";
 import { assert, assertEquals } from "#test-assert";
 import { readFileSync } from "node:fs";
-import { PR_ACTIVE_STATUSES, PLAN_ACTIVE_STATUSES, FEATURE_ACTIVE_STATUSES, TERMINAL_STATUSES } from "./service.ts";
+import { PR_ACTIVE_STATUSES, PLAN_ACTIVE_STATUSES, FEATURE_ACTIVE_STATUSES } from "./service.ts";
+import { TERMINAL_STATUSES } from "./delivery.ts";
 import { PLAN_TERMINAL_STATUSES } from "./plan.ts";
 import { FEATURE_TERMINAL_STATUSES } from "./feature.ts";
 

package/app/lineage.test.ts

@@ -0,0 +1,300 @@
+// Read-model derivation test for the lineage projection (issue #245). `deriveLineage` is the single
+// source of truth for the denormalised `lineage_threads` rows the poller projects: it must stitch a
+// request → implementation → PR(s) → convergence → merge → outcome arc into one thread, expose the
+// active frontier plus whether the arc has settled, roll epic fan-out up across N slice PRs, and
+// tolerate a human/webhook PR with no originating request (self-rooted, kind `pr`).
+import { test } from "node:test";
+import { assert, assertEquals } from "#test-assert";
+import type { DataLayer } from "@nanobpm/urban";
+import {
+  deriveLineage,
+  type LineagePr,
+  type LineageThreadRow,
+  listLineage,
+  pollLineage,
+} from "./lineage.ts";
+
+function pr(overrides: Partial<LineagePr> & { prKey: string; status: string }): LineagePr {
+  return {
+    title: overrides.title ?? `title ${overrides.prKey}`,
+    url: overrides.url ?? `https://github.com/${overrides.prKey.replace("#", "/pull/")}`,
+    round: overrides.round ?? 1,
+    processKey: overrides.processKey ?? "p1",
+    outcome: overrides.outcome ?? null,
+    ...overrides,
+  };
+}
+
+// ── feature arc ──────────────────────────────────────────────────────────────────────────────
+
+test("feature: implementing before any PR is handed off", () => {
+  const t = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "Add X", issueUrl: "u", status: "running", processKey: "f1" },
+    [],
+  );
+  assertEquals(t.kind, "feature");
+  assertEquals(t.stage, "implementing");
+  assertEquals(t.stageLabel, "Implementing");
+  assert(t.active, "an implementing run is active");
+  assertEquals(t.processKey, "f1");
+  assertEquals(t.prCount, 0);
+});
+
+test("feature: converging hands the narrative to the PR frontier", () => {
+  const t = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "Add X", issueUrl: "u", status: "converging", processKey: "f1" },
+    [pr({ prKey: "o/r#2", status: "converging", round: 3, processKey: "c9" })],
+  );
+  assertEquals(t.stage, "converging");
+  assertEquals(t.stageLabel, "Converging (round 3)");
+  assertEquals(t.processKey, "c9", "frontier prefers the active PR's instance");
+  assert(t.active);
+  assertEquals(t.prKeys, ["o/r#2"]);
+});
+
+test("feature: a merged PR settles the arc (history)", () => {
+  const t = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "Add X", issueUrl: "u", status: "merged", processKey: "f1" },
+    [pr({ prKey: "o/r#2", status: "merged" })],
+  );
+  assertEquals(t.stage, "merged");
+  assertEquals(t.stageLabel, "Merged");
+  assert(!t.active, "a merged arc has no active frontier");
+});
+
+test("feature: an escalated run surfaces the escalation stage", () => {
+  const t = deriveLineage(
+    { kind: "feature", key: "o/r#1", title: "X", issueUrl: "u", status: "escalated", processKey: "f1" },
+    [],
+  );
+  assertEquals(t.stage, "escalated");
+  assert(t.active);
+});
+
+// ── epic fan-out ─────────────────────────────────────────────────────────────────────────────
+
+test("epic: rolls up N slice PRs and stays active while any is in flight", () => {
+  const t = deriveLineage(
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    [
+      pr({ prKey: "o/r#10", status: "merged" }),
+      pr({ prKey: "o/r#11", status: "converging", processKey: "c11" }),
+      pr({ prKey: "o/r#12", status: "abandoned" }),
+    ],
+  );
+  assertEquals(t.kind, "epic");
+  assertEquals(t.stage, "converging");
+  assertEquals(t.stageLabel, "1/3 slices merged, 1 converging");
+  assertEquals(t.processKey, "c11");
+  assertEquals(t.prCount, 3);
+  assert(t.active);
+});
+
+test("epic: all slices merged settles as merged", () => {
+  const t = deriveLineage(
+    { kind: "epic", key: "o/r#9", title: "Big epic", issueUrl: "u", status: "done", processKey: "e1" },
+    [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "merged" })],
+  );
+  assertEquals(t.stage, "merged");
+  assertEquals(t.stageLabel, "2/2 slices merged");
+  assert(!t.active);
+});
+
+test("epic: mixed terminal (none in flight, not all merged) is resolved, not landed", () => {
+  const t = deriveLineage(
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "done", processKey: "e1" },
+    [pr({ prKey: "o/r#10", status: "merged" }), pr({ prKey: "o/r#11", status: "abandoned" })],
+  );
+  assertEquals(t.stage, "resolved");
+  assert(!t.active);
+});
+
+test("epic: planning with no PRs yet", () => {
+  const t = deriveLineage(
+    { kind: "epic", key: "o/r#9", title: "E", issueUrl: "u", status: "planning", processKey: "e1" },
+    [],
+  );
+  assertEquals(t.stage, "planning");
+  assert(t.active);
+});
+
+// ── self-rooted (human/webhook) PR ───────────────────────────────────────────────────────────
+
+test("pr: a human/webhook PR with no origin is its own root", () => {
+  const t = deriveLineage({ kind: "pr", key: "o/r#5" }, [
+    pr({ prKey: "o/r#5", status: "waiting_review", round: 2, title: "Fix bug" }),
+  ]);
+  assertEquals(t.kind, "pr");
+  assertEquals(t.rootRequestKey, "o/r#5");
+  assertEquals(t.stage, "reviewing");
+  assertEquals(t.stageLabel, "Awaiting review (round 2)");
+  assertEquals(t.title, "Fix bug", "a self-rooted PR takes its title from the PR");
+  assertEquals(t.issueUrl, null);
+  assert(t.active);
+});
+
+// ── poller projection ────────────────────────────────────────────────────────────────────────
+
+function memData(): { data: DataLayer; stores: Record<string, any[]> } {
+  const stores: Record<string, any[]> = {};
+  function tbl(name: string, pk = "id") {
+    const rows = (stores[name] ??= [] as any[]);
+    const match = (r: any, where: any) => Object.entries(where).every(([k, v]) => r[k] === v);
+    return {
+      async all() {
+        return rows.slice();
+      },
+      async get(id: any) {
+        return rows.find((r) => r[pk] === id);
+      },
+      async find(where: any = {}) {
+        return rows.filter((r) => match(r, where));
+      },
+      async insert(row: any) {
+        rows.push({ ...row });
+        return row[pk];
+      },
+      async update(id: any, patch: any) {
+        const r = rows.find((row) => row[pk] === id);
+        if (r) Object.assign(r, patch);
+      },
+      async delete(id: any) {
+        const i = rows.findIndex((r) => r[pk] === id);
+        if (i >= 0) rows.splice(i, 1);
+      },
+    };
+  }
+  const data = { table: (n: string, pk?: string) => tbl(n, pk) } as any as DataLayer;
+  return { data, stores };
+}
+
+test("pollLineage: projects feature, epic, and self-rooted threads onto lineage_threads", async () => {
+  const { data, stores } = memData();
+  stores.feature_runs = [
+    { feature_key: "o/r#1", title: "Feature", issue_url: "u1", status: "converging", process_key: "f1", pr_key: "o/r#100" },
+  ];
+  stores.plans = [
+    { plan_key: "o/r#2", title: "Epic", issue_url: "u2", status: "done", process_key: "e1" },
+  ];
+  stores.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" },
+  ];
+  stores.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" },
+    // Human/webhook PR — no root_request_key.
+    { pr_key: "o/r#300", title: "Human PR", url: "x", status: "merged", current_round: 1, process_key: "c4", outcome: null, root_request_key: null },
+  ];
+
+  await pollLineage(data);
+
+  const threads: LineageThreadRow[] = stores.lineage_threads;
+  assertEquals(threads.length, 3, "one feature, one epic, one self-rooted PR");
+
+  const feat = threads.find((t) => t.root_request_key === "o/r#1");
+  assert(feat, "feature thread present");
+  assertEquals(feat?.kind, "feature");
+  assertEquals(feat?.stage, "converging");
+  assertEquals(feat?.stage_label, "Converging (round 2)");
+  assertEquals(feat?.active, 1);
+  assertEquals(JSON.parse(feat?.pr_keys ?? "[]"), ["o/r#100"]);
+
+  const epic = threads.find((t) => t.root_request_key === "o/r#2");
+  assertEquals(epic?.kind, "epic");
+  assertEquals(epic?.stage, "converging");
+  assertEquals(epic?.pr_count, 2);
+  assertEquals(epic?.active, 1);
+
+  const human = threads.find((t) => t.root_request_key === "o/r#300");
+  assertEquals(human?.kind, "pr");
+  assertEquals(human?.stage, "merged");
+  assertEquals(human?.active, 0);
+
+  // Idempotent: a second pass with no state change writes nothing new (same row count, same ts).
+  const before = stores.lineage_threads.map((r: LineageThreadRow) => r.updated_at);
+  await pollLineage(data);
+  const after = stores.lineage_threads.map((r: LineageThreadRow) => r.updated_at);
+  assertEquals(after, before, "steady-state pass is a no-op");
+});
+
+test("pollLineage: a self-rooted PR row (root_request_key === pr_key) projects exactly one thread keyed on its pr_key", async () => {
+  // Regression (#245): submitPr now self-roots a human/webhook PR on its own `pr_key` (rather than
+  // NULL) so the Lineage page's `lineage_threads.root_request_key → pull_requests.root_request_key`
+  // drill-down join is non-empty. Guard that this row shape still projects a single self-rooted
+  // thread keyed on the `pr_key` — not double-counted, and not grouped under a phantom origin.
+  const { data, stores } = memData();
+  stores.feature_runs = [];
+  stores.plans = [];
+  stores.plan_tasks = [];
+  stores.pull_requests = [
+    { pr_key: "o/r#42", title: "Human PR", url: "x", status: "converging", current_round: 1, process_key: "c9", outcome: null, root_request_key: "o/r#42" },
+  ];
+
+  await pollLineage(data);
+
+  const threads: LineageThreadRow[] = stores.lineage_threads;
+  assertEquals(threads.length, 1, "one self-rooted thread");
+  assertEquals(threads[0].root_request_key, "o/r#42", "thread key equals the PR row's root_request_key so the page join drills down");
+  assertEquals(threads[0].kind, "pr");
+  assertEquals(JSON.parse(threads[0].pr_keys ?? "[]"), ["o/r#42"]);
+  assertEquals(threads[0].pr_count, 1);
+});
+
+test("pollLineage: an orphaned non-null root (origin row gone) keys the thread on the stored root, not pr_key", async () => {
+  // Regression (#245 review): a PR whose `root_request_key` points at a feature/epic origin row that
+  // no longer survives is unclaimed by any feature/epic thread. Keying its self-rooted thread on
+  // `pr_key` would leave `lineage_threads.root_request_key` (= pr_key) ≠ `pull_requests.root_request_key`
+  // (= the orphaned root), so the page's drill-down join renders an empty PR list. The thread MUST be
+  // keyed on the stored `root_request_key`. Two PRs sharing one orphaned root belong to one thread.
+  const { data, stores } = memData();
+  stores.feature_runs = [];
+  stores.plans = [];
+  stores.plan_tasks = [];
+  stores.pull_requests = [
+    { pr_key: "o/r#71", title: "Orphan A", url: "x", status: "converging", current_round: 1, process_key: "c1", outcome: null, root_request_key: "o/r#7" },
+    { pr_key: "o/r#72", title: "Orphan B", url: "x", status: "merged", current_round: 1, process_key: "c2", outcome: null, root_request_key: "o/r#7" },
+  ];
+
+  await pollLineage(data);
+
+  const threads: LineageThreadRow[] = stores.lineage_threads;
+  assertEquals(threads.length, 1, "both orphaned PRs group into one thread under their shared root");
+  assertEquals(
+    threads[0].root_request_key,
+    "o/r#7",
+    "thread key equals the stored root_request_key so the page join drills down, not the pr_key",
+  );
+  assertEquals(threads[0].kind, "pr");
+  assertEquals(JSON.parse(threads[0].pr_keys ?? "[]").sort(), ["o/r#71", "o/r#72"]);
+  assertEquals(threads[0].pr_count, 2);
+});
+
+test("listLineage: unknown root returns nothing; known roots stitched", async () => {
+  const { data } = memData();
+  const threads = await listLineage(data);
+  assertEquals(threads.length, 0);
+});
+
+test("listLineage: deterministic order — active frontier first, then by rootRequestKey", async () => {
+  // Guard the tie-break (#245 review): equal-`active` threads have no per-thread timestamp to sort
+  // on, so ordering must fall back to `rootRequestKey` for a stable, deterministic response instead
+  // of jittering across passes. Insert settled roots out of order plus one active root.
+  const { data, stores } = memData();
+  stores.feature_runs = [];
+  stores.plans = [];
+  stores.plan_tasks = [];
+  stores.pull_requests = [
+    { pr_key: "o/r#3", title: "c", url: "x", status: "merged", current_round: 1, process_key: null, outcome: null, root_request_key: "o/r#3" },
+    { pr_key: "o/r#1", title: "a", url: "x", status: "merged", current_round: 1, process_key: null, outcome: null, root_request_key: "o/r#1" },
+    { pr_key: "o/r#2", title: "b", url: "x", status: "converging", current_round: 1, process_key: "c9", outcome: null, root_request_key: "o/r#2" },
+  ];
+
+  const threads = await listLineage(data);
+  assertEquals(
+    threads.map((t) => t.rootRequestKey),
+    ["o/r#2", "o/r#1", "o/r#3"],
+    "active first, then inactive sorted by rootRequestKey",
+  );
+});