@bugmole/cli 0.4.0

package/src/runtime/pipeline.ts

@@ -0,0 +1,833 @@
+/**
+ * Autonomous QA pipeline.
+ *
+ * Pulling "Explore this app" is meant to start the platform working on its
+ * own — explore, then assume flows, then assume test cases, then plan —
+ * and keep going until it is done or something says stop. Previously the
+ * worker ran exactly one task and stopped: nothing enqueued follow-on
+ * work, and the agent guidance only ever said "do this one task and
+ * report". A real run finished exploration and then sat idle forever.
+ *
+ * The agent may enqueue its own next stage, but progress cannot depend on
+ * that: the agent demonstrably died mid-pipeline (its CLI was killed by a
+ * timeout) and nothing recovered. So the worker also reconciles. Stage
+ * state is DERIVED from real artifacts on every pass rather than stored as
+ * a separate state machine, which means the two paths converge instead of
+ * fighting, and a half-finished pipeline repairs itself rather than
+ * drifting out of sync with what is actually on disk.
+ */
+
+import fs from "node:fs";
+import path from "node:path";
+import YAML from "yaml";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { MAX_TASK_ATTEMPTS } from "../registry/task-scheduling.js";
+import { driverForPlatform } from "./planner.js";
+
+export type PipelineStage = "explore" | "roles" | "audit" | "testcases" | "plan" | "run";
+
+export type PipelineStatus = "running" | "paused" | "stopped" | "complete";
+
+export type PipelineJourney = {
+  id: string;
+  actor?: string;
+  revision?: number;
+  nodeIds?: string[];
+  stability?: string;
+  linkedToGraph?: boolean;
+};
+
+export type PipelineTask = {
+  status: string;
+  idempotencyKey?: string;
+  completionSummary?: string | null;
+  title?: string;
+  attempts?: number;
+  errorMessage?: string | null;
+};
+
+export type PipelineInputs = {
+  projectId: string;
+  journeys: PipelineJourney[];
+  /** Actor names defined in roles.yaml. */
+  knownActors: string[];
+  /** Journey ids that already have a written test-case set. */
+  caseSetJourneyIds: string[];
+  /** Journey ids that already have an App Audit artifact. */
+  auditedJourneyIds?: string[];
+  /** Journey ids that already have a published plan. */
+  plannedJourneyIds: string[];
+  /** Journey ids that already have a run (of any status). */
+  ranJourneyIds?: string[];
+  /**
+   * Every recorded run with its status.
+   *
+   * Needed because "has a run" is not enough to decide what to do next: a run
+   * still in flight must not be duplicated, while a run that already finished
+   * must not block a fresh attempt. Keyed only on ids, those two cases look
+   * identical — which is how a finished run ended up being handed back
+   * forever under a stable idempotency key.
+   */
+  runs?: Array<{ journeyId?: string; status?: string }>;
+  /**
+   * Journey ids where every written test case carries a recorded verdict.
+   *
+   * A run artifact only proves a run happened. This proves the run actually
+   * judged the cases it was supposed to, which is the difference between
+   * "executed" and "covered".
+   */
+  verdictJourneyIds?: string[];
+  /** Published plans, used to start a run for a planned journey. */
+  publishedPlans?: Array<{ planId: string; journeyId?: string }>;
+  /** Environment to run against, when one is configured. */
+  environmentId?: string;
+  /** Current agent tasks for the project. */
+  tasks: PipelineTask[];
+  /** Blocker categories declared hard_stop in spec/blockers.yaml. */
+  hardStopCategories: string[];
+  /** Blocker categories actually encountered and recorded. */
+  recordedBlockerCategories: string[];
+  /** Set when a stage is waiting on a human answer. */
+  pendingClarification?: string;
+};
+
+export type PipelineNextTask = {
+  stage: PipelineStage;
+  journeyId?: string;
+  title: string;
+  description: string;
+  taskType: "code" | "ui" | "investigation";
+  idempotencyKey: string;
+};
+
+/**
+ * The run stage produces a run, not an agent task: executing a published
+ * plan is the worker's own job (processRun), and it is what turns a test
+ * case assumption into evidence. Without this the pipeline stopped at
+ * "planned" and every case stayed unproven.
+ */
+export type PipelineNextRun = {
+  stage: "run";
+  journeyId: string;
+  planId: string;
+  idempotencyKey: string;
+  environmentId?: string;
+};
+
+export type PipelineState = {
+  status: PipelineStatus;
+  reason: string;
+  next?: PipelineNextTask;
+  nextRun?: PipelineNextRun;
+  stages: Array<{ stage: PipelineStage; satisfied: boolean; detail: string }>;
+  /**
+   * Artifacts written against flows that no longer exist. Surfaced rather
+   * than quietly ignored: they are the visible trace of the graph having
+   * been regenerated, and they are why a stage can look further along than
+   * it is.
+   */
+  orphanedArtifacts: Array<{ kind: string; journeyId: string }>;
+  /** Stages that gave up and need a human answer before work can continue. */
+  blockedTasks?: Array<{ title: string; idempotencyKey?: string; attempts: number; reason?: string }>;
+};
+
+export const PIPELINE_KEY_PREFIX = "pipeline";
+
+/** Deterministic per-stage key, so the agent's own enqueue and the
+ *  reconciler's converge on one task instead of creating duplicates. */
+export function pipelineIdempotencyKey(
+  projectId: string,
+  stage: PipelineStage,
+  journeyId?: string,
+): string {
+  return journeyId
+    ? `${PIPELINE_KEY_PREFIX}:${projectId}:${stage}:${journeyId}`
+    : `${PIPELINE_KEY_PREFIX}:${projectId}:${stage}`;
+}
+
+export function isPipelineTask(task: PipelineTask): boolean {
+  return typeof task.idempotencyKey === "string"
+    && task.idempotencyKey.startsWith(`${PIPELINE_KEY_PREFIX}:`);
+}
+
+/** A journey the graph considers real enough to build on. */
+function isCanonical(journey: PipelineJourney): boolean {
+  return journey.stability === "stable" && journey.linkedToGraph === true;
+}
+
+function activeTask(tasks: PipelineTask[]): PipelineTask | undefined {
+  return tasks.find((task) => task.status === "queued" || task.status === "running");
+}
+
+/**
+ * Decide what the pipeline should do next.
+ *
+ * Pure on purpose: every stop rule is a branch here, so each can be proven
+ * in isolation rather than only observable by running a live agent.
+ */
+export function derivePipelineState(inputs: PipelineInputs): PipelineState {
+  const {
+    projectId, journeys, knownActors, caseSetJourneyIds,
+    plannedJourneyIds, tasks, hardStopCategories, recordedBlockerCategories,
+  } = inputs;
+
+  const withNodes = journeys.filter((journey) => (journey.nodeIds?.length ?? 0) > 0);
+  const canonical = withNodes.filter(isCanonical);
+  // Artifacts outlive the flows they describe: regenerating the graph
+  // gives journeys new ids, orphaning every case set, audit and plan
+  // written against the old ones. Counting those raw made the pipeline
+  // report "4/7 flows have test cases" when none of the live flows had
+  // any, and mark planning satisfied while nothing was planned — so it
+  // would have skipped the stage entirely. Only artifacts belonging to a
+  // flow that still exists count.
+  const canonicalIds = new Set(canonical.map((journey) => journey.id));
+  const belongsToLiveFlow = (id: string) => canonicalIds.has(id);
+  const caseSets = new Set(caseSetJourneyIds.filter(belongsToLiveFlow));
+  const planned = new Set(plannedJourneyIds.filter(belongsToLiveFlow));
+  const orphanedArtifacts = [
+    ...caseSetJourneyIds.filter((id) => !belongsToLiveFlow(id)).map((id) => ({ kind: "test cases", journeyId: id })),
+    ...(inputs.auditedJourneyIds ?? []).filter((id) => !belongsToLiveFlow(id)).map((id) => ({ kind: "audit", journeyId: id })),
+    ...plannedJourneyIds.filter((id) => !belongsToLiveFlow(id)).map((id) => ({ kind: "plan", journeyId: id })),
+  ];
+  const missingActors = [...new Set(
+    canonical
+      .map((journey) => journey.actor)
+      .filter((actor): actor is string => Boolean(actor) && !knownActors.includes(actor!)),
+  )];
+  const audited = new Set((inputs.auditedJourneyIds ?? []).filter(belongsToLiveFlow));
+  const needsAudit = canonical.filter((journey) => !audited.has(journey.id));
+  const needsCases = canonical.filter((journey) => !caseSets.has(journey.id));
+  const needsPlan = canonical.filter((journey) => caseSets.has(journey.id) && !planned.has(journey.id));
+  const ran = new Set((inputs.ranJourneyIds ?? []).filter(belongsToLiveFlow));
+  const judged = new Set((inputs.verdictJourneyIds ?? []).filter(belongsToLiveFlow));
+  const ranButUnjudged = [...ran].filter((id) => !judged.has(id));
+  // The run stage is about planned flows, so only verdicts for flows that
+  // are currently planned count toward it. Without the intersection a flow
+  // judged under a plan that has since been discarded still counted, and the
+  // stage read "20/2 planned flows judged" — more judged than exist.
+  const judgedAndPlanned = [...judged].filter((id) => planned.has(id));
+  // Runs still in flight, and how many have already finished per flow. A
+  // finished run must not satisfy a fresh attempt, and an in-flight one must
+  // not be duplicated.
+  const TERMINAL_RUN = ["success", "partial", "error", "cancelled"];
+  const runsInFlight = new Set(
+    (inputs.runs ?? [])
+      .filter((run) => run.journeyId && !TERMINAL_RUN.includes(run.status ?? ""))
+      .map((run) => run.journeyId!),
+  );
+  const finishedRunCounts = new Map<string, number>();
+  for (const run of inputs.runs ?? []) {
+    if (!run.journeyId || !TERMINAL_RUN.includes(run.status ?? "")) continue;
+    finishedRunCounts.set(run.journeyId, (finishedRunCounts.get(run.journeyId) ?? 0) + 1);
+  }
+  // A flow that ran but recorded no verdicts still needs running: the run
+  // produced artifacts without judging anything, so re-running it is the only
+  // way the cases get a status. Keyed off judged rather than ran so the
+  // pipeline cannot declare itself finished over unjudged cases.
+  const needsRun = canonical.filter((journey) => planned.has(journey.id) && !judged.has(journey.id));
+
+  const stages: PipelineState["stages"] = [
+    {
+      stage: "explore",
+      satisfied: withNodes.length > 0,
+      detail: `${withNodes.length} discovered flow${withNodes.length === 1 ? "" : "s"}`,
+    },
+    {
+      stage: "roles",
+      satisfied: missingActors.length === 0,
+      detail: missingActors.length
+        ? `undefined actor${missingActors.length === 1 ? "" : "s"}: ${missingActors.join(", ")}`
+        : "every flow actor is defined",
+    },
+    {
+      // The audit inventories each screen's controls and runs the component
+      // scan that populates the library, so it comes before test cases:
+      // knowing what a screen is built from is what lets a case be written
+      // against something real.
+      stage: "audit",
+      satisfied: canonical.length > 0 && needsAudit.length === 0,
+      detail: `${audited.size}/${canonical.length} flows audited`,
+    },
+    {
+      stage: "testcases",
+      satisfied: canonical.length > 0 && needsCases.length === 0,
+      detail: `${caseSets.size}/${canonical.length} flows have test case assumptions`,
+    },
+    {
+      stage: "plan",
+      satisfied: canonical.length > 0 && planned.size === canonical.length,
+      detail: `${planned.size}/${canonical.length} flows planned`,
+    },
+    {
+      // Until a plan actually runs, every test case assumption is still
+      // just an assumption — this is the stage that produces evidence.
+      //
+      // "Executed" is not the bar. A run artifact only proves a run happened;
+      // this stage is satisfied when the run recorded a verdict for every
+      // case it was meant to judge. Counting runs alone reported 20/20 here
+      // while all 118 cases still had no status, which is exactly the kind of
+      // green that hides an untested app.
+      stage: "run",
+      satisfied: canonical.length > 0 && planned.size > 0 && judgedAndPlanned.length === planned.size,
+      // Counted as a set difference, not ran minus judged: a flow can be
+      // judged without a registry run record, which made that subtraction
+      // report a negative number of flows.
+      detail: ranButUnjudged.length === 0
+        ? `${judgedAndPlanned.length}/${planned.size} planned flows executed and judged`
+        : `${judgedAndPlanned.length}/${planned.size} planned flows judged `
+          + `(${ranButUnjudged.length} ran but recorded no verdicts)`,
+    },
+  ];
+
+  const stopped = (reason: string): PipelineState => ({ status: "stopped", reason, stages, orphanedArtifacts });
+
+  // Cancelling is the user's kill switch, so it must halt the whole
+  // pipeline, not just the one task — otherwise the reconciler would
+  // cheerfully queue the next stage a few seconds later. Re-triggering
+  // recycles that task back to queued, which clears the stop.
+  const cancelled = tasks.find((task) =>
+    isPipelineTask(task) && task.status === "error" && task.completionSummary === "Cancelled");
+  if (cancelled) {
+    return stopped("A pipeline task was cancelled. Re-run the stage to resume.");
+  }
+
+  const hitHardStop = recordedBlockerCategories.find((category) => hardStopCategories.includes(category));
+  if (hitHardStop) {
+    return stopped(`Hard stop: the "${hitHardStop}" blocker halts the run by policy.`);
+  }
+
+  if (inputs.pendingClarification) {
+    // Paused, not stopped: the work is fine, it just needs an answer that
+    // the agent must not invent.
+    return { status: "paused", reason: inputs.pendingClarification, stages, orphanedArtifacts };
+  }
+
+  // A pipeline task that has burned its attempts is not going to succeed
+  // on its own. It is neither in flight nor terminal, so the reconciler
+  // would keep "enqueueing" it — getting the same blocked task back every
+  // few seconds, making no progress and saying nothing. Surface it as
+  // needing an answer instead, which is the one thing that can unblock it.
+  const exhausted = tasks.filter((task) =>
+    isPipelineTask(task)
+    && task.status === "blocked"
+    && (task.attempts ?? 0) >= MAX_TASK_ATTEMPTS);
+  if (exhausted.length) {
+    const first = exhausted[0];
+    const detail = first.errorMessage?.trim() || first.completionSummary?.trim();
+    return {
+      status: "paused",
+      reason: `${exhausted.length} stage${exhausted.length === 1 ? "" : "s"} need your input — `
+        + `"${first.title ?? first.idempotencyKey}" stopped after ${MAX_TASK_ATTEMPTS} attempts`
+        + (detail ? `: ${detail}` : "."),
+      stages,
+      orphanedArtifacts,
+      blockedTasks: exhausted.map((task) => ({
+        title: task.title ?? task.idempotencyKey ?? "pipeline task",
+        idempotencyKey: task.idempotencyKey,
+        attempts: task.attempts ?? 0,
+        reason: task.errorMessage?.trim() || task.completionSummary?.trim(),
+      })),
+    };
+  }
+
+  // Only one stage runs at a time; the worker already serialises task
+  // execution, and queueing ahead would just create work that races.
+  const inFlight = activeTask(tasks);
+  if (inFlight) {
+    return { status: "running", reason: "A task is already in flight.", stages, orphanedArtifacts };
+  }
+
+  const nextStage = stages.find((stage) => !stage.satisfied);
+  if (!nextStage) {
+    return { status: "complete", reason: "Every stage is satisfied.", stages, orphanedArtifacts };
+  }
+
+  if (nextStage.stage === "run") {
+    const journey = needsRun[0];
+    if (journey && runsInFlight.has(journey.id)) {
+      // Its run is already executing. Starting another would either duplicate
+      // the work or, under a stable idempotency key, hand back the same run
+      // and look like progress that is not happening.
+      return {
+        status: "running",
+        reason: `A run of "${journey.id}" is already in flight.`,
+        stages,
+        orphanedArtifacts,
+      };
+    }
+    // A flow that has burned this many finished runs and still has no
+    // verdicts is not going to get them by being run again. Stop and say so,
+    // rather than starting run number four and calling it progress.
+    const attempts = journey ? finishedRunCounts.get(journey.id) ?? 0 : 0;
+    if (journey && attempts >= MAX_TASK_ATTEMPTS) {
+      return {
+        status: "paused",
+        reason: `Flow "${journey.id}" ran ${attempts} times without recording any verdict — it needs your input.`,
+        stages,
+        orphanedArtifacts,
+      };
+    }
+    const plan = (inputs.publishedPlans ?? []).find((candidate) => candidate.journeyId === journey?.id);
+    if (!journey || !plan) {
+      // A plan exists on disk but was never published to the registry, so
+      // there is nothing runnable yet. Say so instead of silently idling.
+      return {
+        status: "paused",
+        reason: `Flow "${journey?.id ?? "unknown"}" is planned but has no published plan to run.`,
+        stages,
+        orphanedArtifacts,
+      };
+    }
+    return {
+      status: "running",
+      reason: "Next stage: run",
+      nextRun: {
+        stage: "run",
+        journeyId: journey.id,
+        planId: plan.planId,
+        // Discriminated by how many runs of this flow have already finished.
+        // The key has to stay stable while a run is in flight, so repeated
+        // reconciles do not duplicate it — but it must change once that run
+        // finishes, or the registry keeps handing back the completed run and
+        // the flow can never be run again. That is exactly what happened: a
+        // finished run from hours earlier was returned on every poll, so the
+        // pipeline announced "started run" forever and nothing executed.
+        idempotencyKey: `${pipelineIdempotencyKey(projectId, "run", journey.id)}:${attempts}`,
+        environmentId: inputs.environmentId,
+      },
+      stages,
+      orphanedArtifacts,
+    };
+  }
+
+  const next = buildNextTask(projectId, nextStage.stage, {
+    missingActors,
+    needsAudit,
+    needsCases,
+    needsPlan,
+  });
+  return { status: "running", reason: `Next stage: ${nextStage.stage}`, next, stages, orphanedArtifacts };
+}
+
+function buildNextTask(
+  projectId: string,
+  stage: PipelineStage,
+  context: {
+    missingActors: string[];
+    needsAudit: PipelineJourney[];
+    needsCases: PipelineJourney[];
+    needsPlan: PipelineJourney[];
+  },
+): PipelineNextTask {
+  if (stage === "explore") {
+    return {
+      stage,
+      taskType: "investigation",
+      title: "Explore the app and build the journey graph",
+      description: [
+        "Read bugmole://guidance/agent-testing and follow it end to end.",
+        "Run bugmole_explore against the configured environment, then record what you actually",
+        "observe with bugmole_record_discovery. After every exploration call bugmole_journey_next",
+        "and perform the returned task until the flow is exhausted or explicitly blocked.",
+      ].join(" "),
+      idempotencyKey: pipelineIdempotencyKey(projectId, stage),
+    };
+  }
+  if (stage === "roles") {
+    return {
+      stage,
+      taskType: "code",
+      title: "Define the actors the discovered flows use",
+      description: [
+        `The discovered flows use actors that roles.yaml does not define: ${context.missingActors.join(", ")}.`,
+        "Planning refuses an undefined actor, so the pipeline cannot proceed until this is reconciled.",
+        "Inspect the application's real roles and either add the missing actor to spec/roles.yaml with",
+        "accurate permissions, or update the flow to use an existing role that genuinely matches.",
+        "Do not invent permissions to make the check pass.",
+      ].join(" "),
+      idempotencyKey: pipelineIdempotencyKey(projectId, stage),
+    };
+  }
+  if (stage === "audit") {
+    const journey = context.needsAudit[0];
+    return {
+      stage,
+      journeyId: journey?.id,
+      taskType: "investigation",
+      title: `Audit the controls and components of ${journey?.id ?? "the discovered flow"}`,
+      description: [
+        "Read bugmole://guidance/app-ui-audit and follow it for this flow.",
+        "",
+        "First populate the component library, because nothing else does:",
+        "call bugmole_ui_re_start with kind \"existing_app\" and the app's base URL, then",
+        "bugmole_ui_re_stage with stage \"atoms\". That runs the Storybook/CSF source scan and",
+        "records the catalogue the dashboard's component library reads. If the project has no",
+        "Storybook, the scan reports that as a blocked reason — report it as-is rather than",
+        "inventing components.",
+        "",
+        `Then audit "${journey?.id}": inventory every interactive control on each screen with its`,
+        "handler and evidence, and call bugmole_write_ui_audit with the completed object.",
+      ].join("\n"),
+      idempotencyKey: pipelineIdempotencyKey(projectId, stage, journey?.id),
+    };
+  }
+  if (stage === "testcases") {
+    const journey = context.needsCases[0];
+    return {
+      stage,
+      journeyId: journey?.id,
+      taskType: "investigation",
+      title: `Write test case assumptions for ${journey?.id ?? "the discovered flow"}`,
+      description: [
+        `Read bugmole://spec/test-cases.schema.json and write the test case assumptions for "${journey?.id}".`,
+        "Every case must name a real nodeId from that flow, say what it is trying to prove, and list",
+        "observable expectations. Cite what each assumption rests on in `basis`; a case you cannot ground",
+        "must be confidence \"low\" rather than a confident guess. Then call bugmole_write_test_cases.",
+      ].join(" "),
+      idempotencyKey: pipelineIdempotencyKey(projectId, stage, journey?.id),
+    };
+  }
+  const journey = context.needsPlan[0];
+  return {
+    stage: "plan",
+    journeyId: journey?.id,
+    taskType: "investigation",
+    title: `Plan ${journey?.id ?? "the discovered flow"}`,
+    description: [
+      `Call bugmole_plan for "${journey?.id}" using the actor defined for that flow.`,
+      "Planning is blocked while the flow still has an actionable exploration task, so check",
+      "bugmole_journey_next first and finish any remaining verification before planning.",
+    ].join(" "),
+    idempotencyKey: pipelineIdempotencyKey(projectId, "plan", journey?.id),
+  };
+}
+
+// --- Loading real state -----------------------------------------------------
+//
+// Everything below reads the same artifacts the dashboard reads, so the
+// pipeline's view of "what is done" is the same view a human gets rather
+// than a private ledger that can disagree with reality.
+
+function store(cfg: any) {
+  return createProjectObjectStore(cfg);
+}
+
+function readYaml(filePath: string): any {
+  try {
+    return YAML.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+/** Actor names defined in roles.yaml, which the planner validates against. */
+export function knownActors(specDir: string): string[] {
+  const roles = readYaml(path.join(specDir, "roles.yaml"));
+  return Array.isArray(roles?.roles)
+    ? roles.roles.map((role: any) => role?.name).filter((name: unknown): name is string => typeof name === "string")
+    : [];
+}
+
+/**
+ * Blocker categories that halt the run by policy.
+ *
+ * spec/blockers.yaml has declared these since it was written, but nothing
+ * in the runtime ever read them — they were documentation the agent might
+ * choose to honour. The pipeline enforces them.
+ */
+export function hardStopCategories(specDir: string): string[] {
+  const doc = readYaml(path.join(specDir, "blockers.yaml"));
+  const fromBlockers = Array.isArray(doc?.blockers)
+    ? doc.blockers.filter((entry: any) => entry?.hard_stop === true).map((entry: any) => entry?.name)
+    : [];
+  const fromHardStops = Array.isArray(doc?.hard_stops)
+    ? doc.hard_stops.map((entry: any) => entry?.name)
+    : [];
+  return [...new Set([...fromBlockers, ...fromHardStops])]
+    .filter((name: unknown): name is string => typeof name === "string");
+}
+
+/**
+ * Journeys whose every written case carries a recorded verdict.
+ *
+ * Partial credit would defeat the purpose: a flow with one judged case and
+ * six unjudged ones has not been covered, and counting it would put the
+ * pipeline back to reporting green over an untested app. A "blocked" verdict
+ * still counts — the run looked and said why it could not check.
+ */
+async function listJourneyIdsWithVerdicts(cfg: any, projectId: string): Promise<string[]> {
+  try {
+    const objects = await store(cfg).list(`${projectPrefix(projectId)}/test-cases/`);
+    const ids = await Promise.all(objects
+      .filter((object) => object.key.endsWith(".json"))
+      .map(async (object) => {
+        try {
+          const caseSet = JSON.parse(await store(cfg).getText(object.key));
+          const journeyId = typeof caseSet?.journeyId === "string" ? caseSet.journeyId : null;
+          const caseIds = Array.isArray(caseSet?.cases)
+            ? caseSet.cases.map((item: any) => item?.caseId).filter((id: unknown) => typeof id === "string")
+            : [];
+          if (!journeyId || caseIds.length === 0) return null;
+          const resultKey = `${projectPrefix(projectId)}/test-case-results/${caseSet.caseSetId}.json`;
+          const results = JSON.parse(await store(cfg).getText(resultKey));
+          // A verdict recorded against a superseded revision is not evidence
+          // about the cases as they stand now, matching how the dashboard
+          // discards it rather than showing it as proof.
+          if (Number.isInteger(results?.journeyRevision)
+            && Number.isInteger(caseSet?.journeyRevision)
+            && results.journeyRevision !== caseSet.journeyRevision) {
+            return null;
+          }
+          const judged = new Set(
+            (Array.isArray(results?.results) ? results.results : [])
+              .map((item: any) => item?.caseId)
+              .filter((id: unknown) => typeof id === "string"),
+          );
+          return caseIds.every((id: string) => judged.has(id)) ? journeyId : null;
+        } catch {
+          // No results file for this case set, or it is unreadable: not judged.
+          return null;
+        }
+      }));
+    return ids.filter((id): id is string => Boolean(id));
+  } catch {
+    return [];
+  }
+}
+
+async function listJourneyIdsWithCaseSets(cfg: any, projectId: string): Promise<string[]> {
+  try {
+    const objects = await store(cfg).list(`${projectPrefix(projectId)}/test-cases/`);
+    const ids = await Promise.all(objects
+      .filter((object) => object.key.endsWith(".json"))
+      .map(async (object) => {
+        try {
+          const parsed = JSON.parse(await store(cfg).getText(object.key));
+          return typeof parsed?.journeyId === "string" ? parsed.journeyId : null;
+        } catch {
+          return null;
+        }
+      }));
+    return ids.filter((id): id is string => Boolean(id));
+  } catch {
+    return [];
+  }
+}
+
+async function listAuditedJourneyIds(cfg: any, projectId: string): Promise<string[]> {
+  try {
+    const objects = await store(cfg).list(`${projectPrefix(projectId)}/ui-audits/`);
+    const ids = await Promise.all(objects
+      .filter((object) => object.key.endsWith(".json"))
+      .map(async (object) => {
+        try {
+          const parsed = JSON.parse(await store(cfg).getText(object.key));
+          return typeof parsed?.journeyId === "string" ? parsed.journeyId : null;
+        } catch {
+          return null;
+        }
+      }));
+    return [...new Set(ids.filter((id): id is string => Boolean(id)))];
+  } catch {
+    return [];
+  }
+}
+
+async function listRecordedBlockerCategories(cfg: any, projectId: string): Promise<string[]> {
+  try {
+    const objects = await store(cfg).list(`${projectPrefix(projectId)}/blocker-resolutions/`);
+    const categories = await Promise.all(objects
+      .filter((object) => object.key.endsWith(".json"))
+      .map(async (object) => {
+        try {
+          const parsed = JSON.parse(await store(cfg).getText(object.key));
+          return typeof parsed?.category === "string" ? parsed.category : null;
+        } catch {
+          return null;
+        }
+      }));
+    return [...new Set(categories.filter((category): category is string => Boolean(category)))];
+  } catch {
+    return [];
+  }
+}
+
+/** Journey ids that already have a published plan on disk. */
+/**
+ * Whether a written plan could actually execute.
+ *
+ * Only the driver/platform pairing is checked, because that is the one that
+ * fails silently: the run starts, the driver rejects the plan outright, and
+ * every case it was meant to prove is recorded blocked without anything
+ * being tested. A plan unreadable for any other reason is left alone rather
+ * than quietly discarded.
+ */
+function isRunnablePlan(planPath: string): boolean {
+  let plan: any;
+  try {
+    plan = YAML.parse(fs.readFileSync(planPath, "utf8"));
+  } catch {
+    return true;
+  }
+  const driver = typeof plan?.driver === "string" ? plan.driver : undefined;
+  const platform = typeof plan?.platform === "string" ? plan.platform : "web";
+  if (!driver) return true;
+  return driverForPlatform(driver, platform) === driver;
+}
+
+export function plannedJourneyIds(specDir: string, journeyIds: string[]): string[] {
+  const plansDir = path.join(specDir, "plans");
+  let files: string[];
+  try {
+    files = fs.readdirSync(plansDir);
+  } catch {
+    return [];
+  }
+  // The planner writes <journeyId sanitised>.flow.yaml, so match by that
+  // same transform rather than guessing from the file's contents.
+  //
+  // A plan whose driver cannot drive its own platform does not count as
+  // planned. Eighteen web plans were written pinned to maestro, a mobile
+  // runner, and every run of them failed identically without checking
+  // anything. Treating those as planned left the pipeline satisfied with
+  // work that could never succeed; treating them as missing makes it
+  // re-plan them with a driver that can actually run.
+  const planIds = new Set(files
+    .filter((file) => file.endsWith(".flow.yaml"))
+    .filter((file) => isRunnablePlan(path.join(plansDir, file)))
+    .map((file) => file.replace(/\.flow\.yaml$/, "")));
+  return journeyIds.filter((id) => planIds.has(id.replace(/[^a-z0-9._-]/gi, "_").toLowerCase()));
+}
+
+export async function loadPipelineInputs(
+  cfg: any,
+  tasks: PipelineTask[],
+  registry?: {
+    runs?: Array<{ journeyId?: string; status?: string }>;
+    plans?: Array<{ planId: string; journeyId?: string }>;
+  },
+): Promise<PipelineInputs> {
+  const projectId = cfg.project?.id ?? "default";
+  const specDir = cfg.runtime?.spec_dir || "./spec";
+  const graphPath = path.join(specDir, "journeys.graph.json");
+  let journeys: PipelineJourney[] = [];
+  try {
+    const graph = JSON.parse(fs.readFileSync(graphPath, "utf8"));
+    journeys = Array.isArray(graph?.journeys) ? graph.journeys : [];
+  } catch {
+    journeys = [];
+  }
+  const [caseSetJourneyIds, recordedBlockerCategories, auditedJourneyIds, verdictJourneyIds] = await Promise.all([
+    listJourneyIdsWithCaseSets(cfg, projectId),
+    listRecordedBlockerCategories(cfg, projectId),
+    listAuditedJourneyIds(cfg, projectId),
+    listJourneyIdsWithVerdicts(cfg, projectId),
+  ]);
+  return {
+    projectId,
+    journeys,
+    knownActors: knownActors(specDir),
+    caseSetJourneyIds,
+    auditedJourneyIds,
+    plannedJourneyIds: plannedJourneyIds(specDir, journeys.map((journey) => journey.id)),
+    tasks,
+    hardStopCategories: hardStopCategories(specDir),
+    recordedBlockerCategories,
+    ranJourneyIds: [...new Set(
+      (registry?.runs ?? [])
+        .map((run) => run.journeyId)
+        .filter((id): id is string => Boolean(id)),
+    )],
+    verdictJourneyIds,
+    runs: (registry?.runs ?? []).map((run: any) => ({ journeyId: run.journeyId, status: run.status })),
+    publishedPlans: registry?.plans ?? [],
+    environmentId: cfg.project?.environment_id ?? cfg.project?.environmentId ?? cfg.runtime?.environment,
+  };
+}
+
+type ReconcileClient = {
+  listTasks(): Promise<{ tasks: any[] }>;
+  createTask(input: {
+    title: string;
+    description: string;
+    taskType?: "code" | "ui" | "investigation";
+    priority?: number;
+    idempotencyKey: string;
+    journeyId?: string;
+  }): Promise<unknown>;
+  listRuns?(): Promise<{ runs: any[] }>;
+  listPlans?(): Promise<{ plans: any[] }>;
+  createRun?(input: {
+    planId: string;
+    idempotencyKey: string;
+    environmentId?: string;
+  }): Promise<unknown>;
+};
+
+export type ReconcileResult = {
+  state: PipelineState;
+  enqueued?: PipelineNextTask;
+  startedRun?: PipelineNextRun;
+};
+
+/**
+ * Advance the pipeline by at most one stage.
+ *
+ * Safe to call on every worker poll: the stage is derived from artifacts
+ * and the task carries a deterministic idempotency key, so repeating this
+ * on an unchanged project is a no-op rather than a queue of duplicates.
+ */
+export function pipelineStateKey(projectId: string): string {
+  return `${projectPrefix(projectId)}/pipeline/state.json`;
+}
+
+/**
+ * Publish what the pipeline is doing, so it is visible in the dashboard.
+ *
+ * The pipeline was already advancing on its own, but the only way to see
+ * where a project had got to was to run a script against the artifact
+ * store — which is not a usable answer to "where do we go from here".
+ */
+export async function publishPipelineState(cfg: any, state: PipelineState): Promise<void> {
+  const projectId = cfg.project?.id ?? "default";
+  await store(cfg).put(
+    pipelineStateKey(projectId),
+    JSON.stringify({ ...state, projectId, updatedAt: new Date().toISOString() }, null, 2) + "\n",
+    "application/json",
+  );
+}
+
+export async function reconcilePipeline(cfg: any, client: ReconcileClient): Promise<ReconcileResult> {
+  const [listed, runs, plans] = await Promise.all([
+    client.listTasks(),
+    client.listRuns?.().catch(() => ({ runs: [] })) ?? Promise.resolve({ runs: [] }),
+    client.listPlans?.().catch(() => ({ plans: [] })) ?? Promise.resolve({ plans: [] }),
+  ]);
+  const inputs = await loadPipelineInputs(cfg, listed.tasks ?? [], {
+    runs: runs.runs ?? [],
+    plans: plans.plans ?? [],
+  });
+  const state = derivePipelineState(inputs);
+  // Published on every pass so the dashboard reflects the live position,
+  // including when nothing is queued.
+  await publishPipelineState(cfg, state).catch(() => undefined);
+
+  if (state.nextRun && client.createRun) {
+    await client.createRun({
+      planId: state.nextRun.planId,
+      idempotencyKey: state.nextRun.idempotencyKey,
+      environmentId: state.nextRun.environmentId,
+    });
+    return { state, startedRun: state.nextRun };
+  }
+  if (!state.next) return { state };
+  await client.createTask({
+    title: state.next.title,
+    description: state.next.description,
+    taskType: state.next.taskType,
+    idempotencyKey: state.next.idempotencyKey,
+    journeyId: state.next.journeyId,
+  });
+  return { state, enqueued: state.next };
+}