@bugmole/cli 0.4.0 → 0.6.0

package/src/runtime/local-registry-stub.ts

@@ -29,7 +29,8 @@ import { randomBytes } from "node:crypto";
 import { createObjectStore, type ObjectStoreConfig } from "../storage/create-object-store.js";
 import type { ObjectStore } from "../storage/object-store.js";
 import { normalizeTargets } from "./browser-matrix.js";
-import { MAX_TASK_ATTEMPTS, backoffUntil, isResumableTask, resumedTaskFields } from "../registry/task-scheduling.js";
+import { IN_REVIEW, MAX_TASK_ATTEMPTS, REVIEW_NOTE_MAX, approvalModeOf, backoffUntil, completionStatus, inReviewMessage, isResumableTask, resumedTaskFields, sentBackTaskFields, type ApprovalMode } from "../registry/task-scheduling.js";
+import { ROLE_DESCRIPTION_MAX, ROLE_EVIDENCE_MAX, normalizeRoleName, roleSourceOf, roleStatusOf, type RoleSource, type RoleStatus } from "../registry/roles.js";
 
 export type LocalRegistryStub = {
   origin: string;
@@ -39,6 +40,13 @@ export type LocalRegistryStub = {
 export type LocalRegistryStubOptions = {
   directory: string;
   port?: number;
+  /**
+   * The approval mode this stand-in plays for completion review. It approves
+   * every task on creation, as "extreme" does, and by default reviews none;
+   * pass (or set BUGMOLE_APPROVAL to) manual or auto to have finished tasks
+   * wait in review the way the real registry does.
+   */
+  reviewMode?: ApprovalMode;
 };
 
 type PlanDraft = {
@@ -112,6 +120,26 @@ type AgentTask = {
   requestedAt: string;
   startedAt?: string | null;
   completedAt?: string | null;
+  approvedAt?: string | null;
+  approvedBy?: string | null;
+  reviewedAt?: string | null;
+  reviewedBy?: string | null;
+  reviewNote?: string | null;
+};
+
+type Role = {
+  id: string;
+  projectId: string;
+  name: string;
+  description: string;
+  status: RoleStatus;
+  source: RoleSource;
+  evidence: string | null;
+  suggestedBy: string;
+  decidedBy: string | null;
+  decidedAt: string | null;
+  createdAt: string;
+  updatedAt: string;
 };
 
 type JourneyRevision = {
@@ -196,6 +224,7 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
     localDirectory: options.directory,
   } satisfies ObjectStoreConfig);
 
+  const reviewMode: ApprovalMode = options.reviewMode ?? approvalModeOf(process.env.BUGMOLE_APPROVAL?.trim()) ?? "extreme";
   const server = http.createServer(async (request, response) => {
     try {
       const url = new URL(request.url ?? "/", "http://127.0.0.1");
@@ -210,6 +239,58 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
         return;
       }
 
+      // Proposals: the stand-in has no people to review them, so each one is
+      // accepted on arrival (like "extreme" mode) and left for the proposing
+      // CLI or worker to apply to this project's own storage.
+      const proposalsMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/proposals$/);
+      if (proposalsMatch) {
+        const projectId = decodeURIComponent(proposalsMatch[1]);
+        const proposals = await loadCollection<Record<string, unknown>>(store, projectId, "proposals");
+        if (method === "GET") {
+          const unapplied = url.searchParams.get("unapplied") === "1";
+          writeJson(response, 200, { proposals: proposals.filter((item) => !unapplied || (item.status === "accepted" && !item.appliedAt)) });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request) ?? {};
+          if (!["add", "change", "retire"].includes(String(body.action)) || typeof body.caseSetId !== "string" || typeof body.caseId !== "string" || typeof body.summary !== "string" || !body.summary.trim()) {
+            writeJson(response, 422, { error: "caseSetId, caseId, action and summary are required" });
+            return;
+          }
+          const proposal = {
+            id: genId("prop"), projectId, kind: "test_case", caseSetId: body.caseSetId, caseId: body.caseId, action: body.action,
+            baseRevision: Number.isInteger(body.baseRevision) ? body.baseRevision : null, proposed: body.case ?? null,
+            summary: body.summary, source: body.source ?? "cli", proposedBy: "local-dev-bypass", status: "accepted",
+            decidedBy: "auto:local", decisionNote: null, appliedAt: null, appliedRevision: null, createdAt: new Date().toISOString(),
+          };
+          proposals.push(proposal);
+          await saveCollection(store, projectId, "proposals", proposals);
+          writeJson(response, 201, { proposal });
+          return;
+        }
+      }
+      const proposalAppliedMatch = url.pathname.match(/^\/api\/proposals\/([^/]+)\/applied$/);
+      if (proposalAppliedMatch && method === "POST") {
+        const proposalId = decodeURIComponent(proposalAppliedMatch[1]);
+        const projectIds = [...new Set((await store.list("projects/"))
+          .map((object) => object.key.match(/^projects\/([^/]+)\/local-registry\/proposals\.json$/)?.[1])
+          .filter((value): value is string => Boolean(value)))].map(decodeURIComponent);
+        for (const projectId of projectIds) {
+          const proposals = await loadCollection<Record<string, unknown>>(store, projectId, "proposals");
+          const index = proposals.findIndex((item) => item.id === proposalId);
+          if (index < 0) continue;
+          const body = await readJsonBody(request) ?? {};
+          proposals[index] = body.outcome === "outdated"
+            ? { ...proposals[index], status: "outdated", decisionNote: body.message ?? null }
+            : { ...proposals[index], appliedAt: new Date().toISOString(), appliedRevision: body.revision ?? null };
+          await saveCollection(store, projectId, "proposals", proposals);
+          writeJson(response, 200, { proposal: proposals[index] });
+          return;
+        }
+        writeJson(response, 404, { error: "Proposal not found" });
+        return;
+      }
+
       const plansMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/plans$/);
       if (plansMatch) {
         const projectId = decodeURIComponent(plansMatch[1]);
@@ -248,6 +329,111 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
         }
       }
 
+      // Roles: same contract as src/registry-worker/roles/routes.ts. The
+      // stand-in has one caller, the local developer, so a `source` of
+      // "person" (the dashboard's add form) confirms and anything else is a
+      // suggestion that waits for a decision.
+      const rolesMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/roles$/);
+      if (rolesMatch) {
+        const projectId = decodeURIComponent(rolesMatch[1]);
+        const roles = await loadCollection<Role>(store, projectId, "roles");
+        if (method === "GET") {
+          const status = roleStatusOf(url.searchParams.get("status"));
+          const order = { suggested: 0, confirmed: 1, rejected: 2 };
+          writeJson(response, 200, {
+            roles: roles.filter((role) => !status || role.status === status)
+              .sort((a, b) => order[a.status] - order[b.status] || a.name.localeCompare(b.name)),
+          });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const name = normalizeRoleName(body?.name);
+          if (!name) {
+            writeJson(response, 422, { error: "name is required: letters, numbers and underscores, up to 60 characters" });
+            return;
+          }
+          const source = roleSourceOf(body?.source) ?? "agent";
+          const status: RoleStatus = source === "person" ? "confirmed" : "suggested";
+          const description = typeof body?.description === "string" ? body.description.trim().slice(0, ROLE_DESCRIPTION_MAX) : "";
+          const evidence = typeof body?.evidence === "string" && body.evidence.trim() ? body.evidence.trim().slice(0, ROLE_EVIDENCE_MAX) : null;
+          if (status === "suggested" && !evidence) {
+            writeJson(response, 422, { error: "Say what points at this role in evidence (a sign-in wall, a gated route or menu, a spec entry)" });
+            return;
+          }
+          const now = new Date().toISOString();
+          const existing = roles.find((role) => role.name === name);
+          if (existing) {
+            if (existing.status === "suggested" && status === "suggested") {
+              existing.evidence = evidence;
+              existing.updatedAt = now;
+            } else if (existing.status !== "confirmed" && status === "confirmed") {
+              Object.assign(existing, { status: "confirmed", decidedBy: "local-dev-bypass", decidedAt: now, updatedAt: now });
+            }
+            await saveCollection(store, projectId, "roles", roles);
+            writeJson(response, 200, { role: existing, alreadyDecided: existing.status !== "suggested" && status === "suggested" });
+            return;
+          }
+          if (!description) {
+            writeJson(response, 422, { error: `description is required, up to ${ROLE_DESCRIPTION_MAX} characters` });
+            return;
+          }
+          const role: Role = {
+            id: genId("role"), projectId, name, description, status, source, evidence, suggestedBy: "local-dev-bypass",
+            decidedBy: status === "confirmed" ? "local-dev-bypass" : null, decidedAt: status === "confirmed" ? now : null,
+            createdAt: now, updatedAt: now,
+          };
+          roles.push(role);
+          await saveCollection(store, projectId, "roles", roles);
+          writeJson(response, 201, { role });
+          return;
+        }
+      }
+      const roleMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/roles\/([^/]+)$/);
+      if (roleMatch && (method === "PATCH" || method === "DELETE")) {
+        const projectId = decodeURIComponent(roleMatch[1]);
+        const roleId = decodeURIComponent(roleMatch[2]);
+        const roles = await loadCollection<Role>(store, projectId, "roles");
+        const index = roles.findIndex((role) => role.id === roleId);
+        if (index < 0) {
+          writeJson(response, 404, { error: "Not found" });
+          return;
+        }
+        if (method === "DELETE") {
+          roles.splice(index, 1);
+          await saveCollection(store, projectId, "roles", roles);
+          writeJson(response, 200, { deleted: true });
+          return;
+        }
+        const body = await readJsonBody(request);
+        const action = body?.action === "confirm" || body?.action === "reject" ? body.action : body?.action === undefined || body?.action === "edit" ? "edit" : null;
+        if (!action) {
+          writeJson(response, 422, { error: "action must be confirm, reject or edit" });
+          return;
+        }
+        const name = body?.name !== undefined ? normalizeRoleName(body.name) : roles[index].name;
+        if (!name) {
+          writeJson(response, 422, { error: "name must be letters, numbers and underscores, up to 60 characters" });
+          return;
+        }
+        if (roles.some((role, other) => other !== index && role.name === name)) {
+          writeJson(response, 409, { error: "A role with that name already exists" });
+          return;
+        }
+        const now = new Date().toISOString();
+        roles[index] = {
+          ...roles[index],
+          name,
+          description: typeof body?.description === "string" && body.description.trim() ? body.description.trim().slice(0, ROLE_DESCRIPTION_MAX) : roles[index].description,
+          status: action === "confirm" ? "confirmed" : action === "reject" ? "rejected" : roles[index].status,
+          ...(action !== "edit" ? { decidedBy: "local-dev-bypass", decidedAt: now } : {}),
+          updatedAt: now,
+        };
+        await saveCollection(store, projectId, "roles", roles);
+        writeJson(response, 200, { role: roles[index] });
+        return;
+      }
+
       const personasMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/personas$/);
       if (personasMatch) {
         const projectId = decodeURIComponent(personasMatch[1]);
@@ -522,6 +708,10 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
               requestedAt: new Date().toISOString(),
               startedAt: null,
               completedAt: null,
+              // The stand-in has no people to approve anything: every task
+              // it holds is approved on creation, as in "extreme" mode.
+              approvedAt: new Date().toISOString(),
+              approvedBy: "auto:local",
             };
             await saveCollection(store, projectId, "tasks", tasks);
             writeJson(response, 200, { task: tasks[existingIndex] });
@@ -543,6 +733,8 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
             attempts: 0,
             nextAttemptAt: null,
             requestedAt: new Date().toISOString(),
+            approvedAt: new Date().toISOString(),
+            approvedBy: "auto:local",
           };
           tasks.push(task);
           await saveCollection(store, projectId, "tasks", tasks);
@@ -641,7 +833,9 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
           writeJson(response, 409, {
             error: tasks[index].status === "completed"
               ? "Task is already finished"
-              : "Task is still held by a live worker",
+              : tasks[index].status === IN_REVIEW
+                ? "Task is waiting for review; accept it or send it back"
+                : "Task is still held by a live worker",
           });
           return;
         }
@@ -659,6 +853,45 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
         return;
       }
 
+      // Completion review, as in the registry's acceptAgentTask/sendBackAgentTask.
+      const taskReviewMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/(accept|send-back)$/);
+      if (taskReviewMatch && method === "POST") {
+        const found = await findTaskAnyProject(store, decodeURIComponent(taskReviewMatch[1]));
+        if (!found) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        const { projectId, tasks, index } = found;
+        if (tasks[index].status !== IN_REVIEW) {
+          writeJson(response, 409, { error: "Only a task in review can be accepted or sent back" });
+          return;
+        }
+        const body = await readJsonBody(request);
+        const note = typeof body?.note === "string" ? body.note.trim().slice(0, REVIEW_NOTE_MAX) : "";
+        const now = new Date().toISOString();
+        if (taskReviewMatch[2] === "accept") {
+          tasks[index] = { ...tasks[index], status: "completed", completedAt: now, reviewedAt: now, reviewedBy: "local-dev-bypass", reviewNote: note || null };
+          await saveCollection(store, projectId, "tasks", tasks);
+          writeJson(response, 200, { accepted: true, task: tasks[index] });
+          return;
+        }
+        if (!note) {
+          writeJson(response, 422, { error: "Say what needs to change in note" });
+          return;
+        }
+        tasks[index] = {
+          ...tasks[index],
+          ...sentBackTaskFields(note),
+          errorMessage: null,
+          completedAt: null,
+          reviewedAt: now,
+          reviewedBy: "local-dev-bypass",
+        };
+        await saveCollection(store, projectId, "tasks", tasks);
+        writeJson(response, 200, { sentBack: true, task: tasks[index] });
+        return;
+      }
+
       const taskUpdateMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)$/);
       if (taskUpdateMatch && method === "POST") {
         const taskId = decodeURIComponent(taskUpdateMatch[1]);
@@ -669,15 +902,26 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
         }
         const { projectId, tasks, index } = found;
         const body = await readJsonBody(request);
-        const status = typeof body?.status === "string" ? body.status : "running";
-        if (!["running", "blocked", "completed", "error"].includes(status)) {
+        const reported = typeof body?.status === "string" ? body.status : "running";
+        if (!["running", "blocked", "completed", "error"].includes(reported)) {
           writeJson(response, 422, { error: "Invalid task status" });
           return;
         }
-        if (status === "completed" && tasks[index].taskType === "ui" && (!body?.parityAuditId || typeof body?.parityMatchScore !== "number")) {
+        if (reported === "completed" && tasks[index].taskType === "ui" && (!body?.parityAuditId || typeof body?.parityMatchScore !== "number")) {
           writeJson(response, 422, { error: "UI tasks require parityAuditId and parityMatchScore before completion" });
           return;
         }
+        // See registry-worker's updateAgentTask: a task in review only
+        // answers a repeated "completed", and the mode decides review.
+        if (tasks[index].status === IN_REVIEW) {
+          if (reported !== "completed") {
+            writeJson(response, 409, { error: "Task is waiting for review" });
+            return;
+          }
+          writeJson(response, 200, { updated: false, inReview: true, message: "Task is already waiting for review.", task: tasks[index] });
+          return;
+        }
+        const status = reported === "completed" ? completionStatus(reviewMode, tasks[index].taskType) : reported;
         const terminal = ["completed", "error"].includes(status);
         tasks[index] = {
           ...tasks[index],
@@ -694,11 +938,15 @@ export async function startLocalRegistryStub(options: LocalRegistryStubOptions):
           nextAttemptAt: status === "blocked"
             ? backoffUntil(tasks[index].attempts ?? 0)
             : tasks[index].nextAttemptAt ?? null,
-          leaseExpiresAt: new Date(Date.now() + 60_000).toISOString(),
+          leaseExpiresAt: status === IN_REVIEW ? null : new Date(Date.now() + 60_000).toISOString(),
           completedAt: terminal ? new Date().toISOString() : tasks[index].completedAt,
         };
         await saveCollection(store, projectId, "tasks", tasks);
-        writeJson(response, 200, { updated: true, task: tasks[index] });
+        writeJson(response, 200, {
+          updated: true,
+          ...(status === IN_REVIEW ? { inReview: true, message: inReviewMessage(reviewMode) } : {}),
+          task: tasks[index],
+        });
         return;
       }
 

package/src/runtime/local-vault.ts

@@ -0,0 +1,65 @@
+// This machine's secure store for flow secrets: an encrypted vault file whose
+// one key is kept in the OS credential store (macOS Keychain, Windows
+// Credential Manager, Linux Secret Service). It is the open-source
+// @theaiinc/arcana-vault package, in Bugmole's own namespace, so nothing else
+// on the machine shares it. Where that package isn't installed (an
+// unsupported platform), secret-sources.ts falls back to the OS keychain.
+
+import os from "node:os";
+import path from "node:path";
+
+export type LocalVaultLike = {
+  get(name: string): string | null;
+  set(name: string, value: string): void;
+  delete(name: string): boolean;
+  has(name: string): boolean;
+  list(): string[];
+};
+
+/** The credential-store service holding Bugmole's vault key. */
+export const VAULT_SERVICE = "com.bugmole.cli";
+
+/** Where Bugmole keeps its data on this machine (BUGMOLE_DATA_DIR overrides it). */
+export function bugmoleDataDir(env: Record<string, string | undefined> = process.env, platform: string = process.platform): string {
+  if (env.BUGMOLE_DATA_DIR) return env.BUGMOLE_DATA_DIR;
+  const home = env.HOME ?? env.USERPROFILE ?? os.homedir();
+  if (platform === "darwin") return path.join(home, "Library", "Application Support", "Bugmole");
+  if (platform === "win32") return path.join(env.APPDATA ?? path.join(home, "AppData", "Roaming"), "Bugmole");
+  return path.join(env.XDG_DATA_HOME ?? path.join(home, ".local", "share"), "bugmole");
+}
+
+let opened: Promise<LocalVaultLike | null> | undefined;
+
+/**
+ * Opens Bugmole's vault, or null when the vault package isn't installed here.
+ * BUGMOLE_VAULT_MODULE points at another build of the package (development).
+ */
+export function openLocalVault(env: Record<string, string | undefined> = process.env): Promise<LocalVaultLike | null> {
+  opened ??= (async () => {
+    // A variable specifier: the package is optional, so it isn't resolved at build time.
+    const specifier = env.BUGMOLE_VAULT_MODULE || "@theaiinc/arcana-vault";
+    let module: { LocalVault?: { open(namespace: { service: string; dir: string }): LocalVaultLike } };
+    try {
+      module = await import(specifier);
+    } catch (error) {
+      const code = (error as NodeJS.ErrnoException).code;
+      if (code === "ERR_MODULE_NOT_FOUND" || code === "MODULE_NOT_FOUND" || /Cannot find (module|native binding)/i.test(String(error))) return null;
+      throw error;
+    }
+    const LocalVault = module.LocalVault ?? (module as { default?: { LocalVault?: typeof module.LocalVault } }).default?.LocalVault;
+    if (!LocalVault) return null;
+    try {
+      return LocalVault.open({ service: VAULT_SERVICE, dir: path.join(bugmoleDataDir(env), "vault") });
+    } catch {
+      // No credential store to keep the vault key in (a Linux machine with
+      // no Secret Service session, say): fall back as if it weren't installed.
+      return null;
+    }
+  })();
+  return opened;
+}
+
+/** For tests: forget the opened vault. */
+export function resetLocalVault(): void {
+  opened = undefined;
+}

package/src/runtime/pipeline.test.ts

@@ -64,6 +64,29 @@ test("an actor missing from roles.yaml is reconciled instead of dead-ending in t
   assert.match(state.next!.description, /user/);
 });
 
+test("a flow whose role is only suggested waits for a person instead of re-queueing the roles stage", () => {
+  const state = derivePipelineState(inputs({ knownActors: ["owner"], suggestedActors: ["user"] }));
+  assert.equal(state.status, "paused");
+  assert.equal(state.next, undefined);
+  assert.match(state.reason, /confirm or reject the suggested role user/);
+});
+
+test("the roles stage asks an agent to suggest, never to confirm", () => {
+  const state = derivePipelineState(inputs({ knownActors: ["owner"] }));
+  assert.match(state.next!.description, /bugmole_role_propose/);
+  assert.match(state.next!.description, /cannot confirm a role yourself/);
+});
+
+test("a task waiting for review pauses the pipeline until someone accepts or sends it back", () => {
+  const state = derivePipelineState(inputs({
+    tasks: [{ status: "in_review", title: "Fix the checkout button", idempotencyKey: "pipeline:bugmole:audit:flow:login" }],
+  }));
+  assert.equal(state.status, "paused");
+  assert.equal(state.next, undefined);
+  assert.match(state.reason, /waiting for your review/);
+  assert.match(state.reason, /Fix the checkout button/);
+});
+
 test("once cases exist the flow gets planned", () => {
   const state = derivePipelineState(inputs({
     auditedJourneyIds: ["flow:login"],

package/src/runtime/pipeline.ts

@@ -22,7 +22,10 @@ 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 { testCaseResultsKey } from "../storage/test-case-results.js";
+import { IN_REVIEW, MAX_TASK_ATTEMPTS } from "../registry/task-scheduling.js";
+import { suggestedRoleNames, usableRoleNames, type RoleRecord } from "../registry/roles.js";
+import { readSpecRoles } from "./project-roles.js";
 import { driverForPlatform } from "./planner.js";
 
 export type PipelineStage = "explore" | "roles" | "audit" | "testcases" | "plan" | "run";
@@ -50,8 +53,10 @@ export type PipelineTask = {
 export type PipelineInputs = {
   projectId: string;
   journeys: PipelineJourney[];
-  /** Actor names defined in roles.yaml. */
+  /** Confirmed roles: the only actors a flow may be planned for. */
   knownActors: string[];
+  /** Roles Bugmole suggested that still wait for a person to confirm or reject. */
+  suggestedActors?: string[];
   /** Journey ids that already have a written test-case set. */
   caseSetJourneyIds: string[];
   /** Journey ids that already have an App Audit artifact. */
@@ -168,7 +173,7 @@ function activeTask(tasks: PipelineTask[]): PipelineTask | undefined {
  */
 export function derivePipelineState(inputs: PipelineInputs): PipelineState {
   const {
-    projectId, journeys, knownActors, caseSetJourneyIds,
+    projectId, journeys, knownActors, suggestedActors = [], caseSetJourneyIds,
     plannedJourneyIds, tasks, hardStopCategories, recordedBlockerCategories,
   } = inputs;
 
@@ -237,8 +242,8 @@ export function derivePipelineState(inputs: PipelineInputs): PipelineState {
       stage: "roles",
       satisfied: missingActors.length === 0,
       detail: missingActors.length
-        ? `undefined actor${missingActors.length === 1 ? "" : "s"}: ${missingActors.join(", ")}`
-        : "every flow actor is defined",
+        ? `unconfirmed role${missingActors.length === 1 ? "" : "s"}: ${missingActors.join(", ")}`
+        : "every flow actor is a confirmed role",
     },
     {
       // The audit inventories each screen's controls and runs the component
@@ -331,6 +336,33 @@ export function derivePipelineState(inputs: PipelineInputs): PipelineState {
     };
   }
 
+  // Finished work waiting for a person is not in flight, but the next stage
+  // would build on it before anyone looked. Wait for the review instead.
+  const inReview = tasks.filter((task) => task.status === IN_REVIEW);
+  if (inReview.length) {
+    const first = inReview[0];
+    return {
+      status: "paused",
+      reason: `${inReview.length} task${inReview.length === 1 ? " is" : "s are"} waiting for your review — `
+        + `accept or send back "${first.title ?? first.idempotencyKey ?? "the task"}" on the Agent Tasks board.`,
+      stages,
+      orphanedArtifacts,
+    };
+  }
+
+  // A flow's actor that Bugmole suggested but nobody has confirmed yet is a
+  // question for a person, not work for an agent: queueing the roles stage
+  // again would only re-suggest it.
+  const awaitingDecision = missingActors.filter((actor) => suggestedActors.includes(actor));
+  if (awaitingDecision.length && awaitingDecision.length === missingActors.length) {
+    return {
+      status: "paused",
+      reason: `confirm or reject the suggested role${awaitingDecision.length === 1 ? "" : "s"} ${awaitingDecision.join(", ")} on the Roles page (Manage → Roles). Only confirmed roles are planned for.`,
+      stages,
+      orphanedArtifacts,
+    };
+  }
+
   // 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);
@@ -438,13 +470,14 @@ function buildNextTask(
     return {
       stage,
       taskType: "code",
-      title: "Define the actors the discovered flows use",
+      title: "Suggest the roles 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.",
+        `The discovered flows use actors that are not confirmed roles: ${context.missingActors.join(", ")}.`,
+        "Planning only uses roles a person confirmed, so the pipeline cannot proceed until this is reconciled.",
+        "Inspect the application's real roles (sign-in walls, role-gated routes and menus) and either suggest",
+        "the missing role with bugmole_role_propose (with the evidence that points at it) so a person can",
+        "confirm, rename or reject it, or update the flow to use a confirmed role that genuinely matches.",
+        "You cannot confirm a role yourself. Do not invent permissions to make the check pass.",
       ].join(" "),
       idempotencyKey: pipelineIdempotencyKey(projectId, stage),
     };
@@ -521,12 +554,14 @@ function readYaml(filePath: string): any {
   }
 }
 
-/** 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")
-    : [];
+/** Confirmed roles, which the planner validates against: roles.yaml, overridden by the registry's decisions. */
+export function knownActors(specDir: string, registryRoles: RoleRecord[] = []): string[] {
+  return usableRoleNames(readSpecRoles(specDir), registryRoles);
+}
+
+/** Roles still waiting for a person's decision. */
+export function suggestedActors(specDir: string, registryRoles: RoleRecord[] = []): string[] {
+  return suggestedRoleNames(readSpecRoles(specDir), registryRoles);
 }
 
 /**
@@ -569,7 +604,7 @@ async function listJourneyIdsWithVerdicts(cfg: any, projectId: string): Promise<
             ? 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 resultKey = testCaseResultsKey(projectId, caseSet.caseSetId);
           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
@@ -706,6 +741,8 @@ export async function loadPipelineInputs(
   registry?: {
     runs?: Array<{ journeyId?: string; status?: string }>;
     plans?: Array<{ planId: string; journeyId?: string }>;
+    /** The registry's role decisions, which override roles.yaml. */
+    roles?: RoleRecord[];
   },
 ): Promise<PipelineInputs> {
   const projectId = cfg.project?.id ?? "default";
@@ -727,7 +764,8 @@ export async function loadPipelineInputs(
   return {
     projectId,
     journeys,
-    knownActors: knownActors(specDir),
+    knownActors: knownActors(specDir, registry?.roles ?? []),
+    suggestedActors: suggestedActors(specDir, registry?.roles ?? []),
     caseSetJourneyIds,
     auditedJourneyIds,
     plannedJourneyIds: plannedJourneyIds(specDir, journeys.map((journey) => journey.id)),
@@ -758,6 +796,7 @@ type ReconcileClient = {
   }): Promise<unknown>;
   listRuns?(): Promise<{ runs: any[] }>;
   listPlans?(): Promise<{ plans: any[] }>;
+  listRoles?(): Promise<{ roles: Array<{ name: string; status: RoleRecord["status"] }> }>;
   createRun?(input: {
     planId: string;
     idempotencyKey: string;
@@ -799,14 +838,16 @@ export async function publishPipelineState(cfg: any, state: PipelineState): Prom
 }
 
 export async function reconcilePipeline(cfg: any, client: ReconcileClient): Promise<ReconcileResult> {
-  const [listed, runs, plans] = await Promise.all([
+  const [listed, runs, plans, roles] = await Promise.all([
     client.listTasks(),
     client.listRuns?.().catch(() => ({ runs: [] })) ?? Promise.resolve({ runs: [] }),
     client.listPlans?.().catch(() => ({ plans: [] })) ?? Promise.resolve({ plans: [] }),
+    client.listRoles?.().catch(() => ({ roles: [] })) ?? Promise.resolve({ roles: [] }),
   ]);
   const inputs = await loadPipelineInputs(cfg, listed.tasks ?? [], {
     runs: runs.runs ?? [],
     plans: plans.plans ?? [],
+    roles: (roles.roles ?? []).map((role) => ({ name: role.name, status: role.status })),
   });
   const state = derivePipelineState(inputs);
   // Published on every pass so the dashboard reflects the live position,

package/src/runtime/planner.test.ts

@@ -1,6 +1,7 @@
 import assert from "node:assert/strict";
 import test from "node:test";
-import { driverForPlatform } from "./planner.js";
+import { driverForPlatform, journeyFlow } from "./planner.js";
+import { parseMaestroStyleFlow } from "./flow-language.js";
 
 test("a web plan is never pinned to the mobile driver", () => {
   // bugmole.config defaults execution.driver to "maestro" while the plan
@@ -35,3 +36,25 @@ test("an unknown platform is treated as web rather than defaulting to mobile", (
   // first place: the driver that cannot run without a device file.
   assert.equal(driverForPlatform(undefined, "desktop"), "playwright");
 });
+
+test("a journey becomes a flow that opens its first screen and follows each transition", () => {
+  const flow = journeyFlow(
+    { id: "sign-up", name: "Sign up", startNodeId: "screen:/", nodeIds: ["screen:/", "screen:/signup", "screen:/projects/:id"], edgeIds: ["a", "b"] },
+    [
+      { id: "screen:/", route: "/" },
+      { id: "screen:/signup", route: "/signup" },
+      { id: "screen:/projects/:id", route: "/projects/:id" },
+    ],
+    [
+      { id: "a", from: "screen:/", to: "screen:/signup" },
+      { id: "b", from: "screen:/signup", to: "screen:/projects/:id", label: "Create account" },
+    ],
+  );
+  assert.ok(flow);
+  const parsed = parseMaestroStyleFlow(flow, "http://localhost:3000");
+  assert.deepEqual(parsed.steps.map((step) => step.type), ["launchApp", "assertLayout", "openLink", "assertLayout", "tapOn", "assertLayout"]);
+});
+
+test("a journey with no openable screen has no flow", () => {
+  assert.equal(journeyFlow({ id: "x", nodeIds: ["n"] }, [{ id: "n", route: "/projects/:id" }], []), null);
+});