@bugmole/cli 0.5.0 → 0.6.0

package/src/runtime/journey-editor.ts

@@ -82,6 +82,15 @@ function idPart(value: string): string {
   return value.trim().replace(/[^a-zA-Z0-9._:-]+/g, "-").replace(/^-+|-+$/g, "");
 }
 
+/**
+ * Step and transition IDs keep the route in them (screen:/settings,
+ * screen:/->screen:/settings:dom-3), as exploration writes them; rewriting
+ * the slashes made the agent's next call name a step that didn't exist.
+ */
+function graphIdPart(value: string): string {
+  return value.trim().replace(/[^a-zA-Z0-9._:/>\[\]-]+/g, "-").replace(/^-+|-+$/g, "");
+}
+
 function requireJourney(graph: JourneyGraph, journeyId: string): UserJourney {
   const journey = graph.journeys.find((item) => item.id === journeyId);
   if (!journey) throw new Error(`Journey not found: ${journeyId}`);
@@ -191,7 +200,7 @@ export async function addJourneyStep(
 ) {
   const graph = readJourneyGraph(cfg);
   const journey = requireJourney(graph, input.journeyId);
-  const nodeId = idPart(input.node.id || `step-${Date.now()}`);
+  const nodeId = graphIdPart(input.node.id || `step-${Date.now()}`);
   if (!nodeId || graph.nodes.some((node) => node.id === nodeId)) throw new Error(`Node already exists: ${nodeId}`);
   const node = { ...input.node, id: nodeId } as JourneyNode;
   graph.nodes.push(node);
@@ -241,7 +250,7 @@ export async function addJourneyTransition(
   if (!graph.nodes.some((node) => node.id === input.from) || !graph.nodes.some((node) => node.id === input.to)) {
     throw new Error("Transition endpoints must reference existing nodes");
   }
-  const edgeId = idPart(input.edge?.id || `${input.from}->${input.to}:${Date.now()}`);
+  const edgeId = graphIdPart(input.edge?.id || `${input.from}->${input.to}:${Date.now()}`);
   if (graph.edges.some((edge) => edge.id === edgeId)) throw new Error(`Edge already exists: ${edgeId}`);
   const edge: JourneyEdge = { ...input.edge, id: edgeId, from: input.from, to: input.to };
   graph.edges.push(edge);
@@ -301,6 +310,34 @@ export async function removeJourneyItem(
 export function nextJourneyTask(cfg: JourneyConfig, journeyId: string): JourneyNextTask {
   const graph = readJourneyGraph(cfg);
   const journey = requireJourney(graph, journeyId);
+  // An empty journey, or steps nothing connects, is not finished: there is
+  // nothing to plan from yet.
+  if (!journey.nodeIds.length) {
+    return {
+      status: "actionable",
+      journeyId,
+      reason: "The journey has no steps yet.",
+      action: "Add the screen the journey starts on",
+      nextSteps: [
+        "Open the app where this journey starts and record that screen with bugmole_journey_add_step",
+        "Call bugmole_journey_next again after recording it",
+      ],
+    };
+  }
+  if (journey.nodeIds.length > 1 && !journey.edgeIds.length) {
+    return {
+      status: "actionable",
+      journeyId,
+      reason: "The journey's steps aren't connected: no transition says how a person gets from one to the next.",
+      nodeId: journey.nodeIds[0],
+      route: graph.nodes.find((node) => node.id === journey.nodeIds[0])?.route,
+      action: `Connect ${journey.nodeIds[0]} to the next step`,
+      nextSteps: [
+        "Perform the action that leads from each step to the next and record it with bugmole_journey_add_transition",
+        "Call bugmole_journey_next again after recording it",
+      ],
+    };
+  }
   const included = new Set(journey.nodeIds);
   const includedEdges = new Set(journey.edgeIds);
   const coveredTransitions = new Set(

package/src/runtime/journey-graph.test.ts

@@ -297,3 +297,21 @@ test("a passing run promotes the explored draft it proved, from the stored graph
     fs.rmSync(root, { recursive: true, force: true });
   }
 });
+
+test("route-style step IDs are kept, and an empty or unconnected journey is not exhausted", async () => {
+  const root = await fs.promises.mkdtemp(path.join(os.tmpdir(), "bugmole-flow-ids-"));
+  const cfg = {
+    project: { id: "demo" },
+    runtime: { spec_dir: path.join(root, "spec"), artifacts_dir: path.join(root, "artifacts") },
+    storage: { provider: "local", localDirectory: path.join(root, "artifacts") },
+  };
+  await createJourney(cfg, { id: "sign-up", name: "Sign up", actor: "guest" });
+  assert.equal(nextJourneyTask(cfg, "sign-up").status, "actionable");
+  const home = await addJourneyStep(cfg, { journeyId: "sign-up", node: { id: "screen:/", title: "Home", kind: "screen", route: "/" } });
+  const signup = await addJourneyStep(cfg, { journeyId: "sign-up", node: { id: "screen:/signup", title: "Sign up", kind: "screen", route: "/signup" } });
+  assert.deepEqual(signup.journey.nodeIds, ["screen:/", "screen:/signup"]);
+  assert.ok(home);
+  assert.match(nextJourneyTask(cfg, "sign-up").reason, /aren't connected/);
+  await addJourneyTransition(cfg, { journeyId: "sign-up", from: "screen:/", to: "screen:/signup" });
+  assert.match(readJourneyGraph(cfg).edges[0].id, /^screen:\/->screen:\/signup:/);
+});

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

@@ -323,3 +323,67 @@ test("personas: adding, renaming, and removing, with at least one always kept",
     assert.equal(removeLast.status, 409, "the last persona in a project can't be removed");
   });
 });
+
+test("completion review mirrors the registry: in review, then accepted or sent back with a note", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-local-registry-"));
+  const stub = await startLocalRegistryStub({ directory, reviewMode: "auto" });
+  const origin = stub.origin;
+  try {
+    const create = async (taskType: string, key: string) => {
+      const created = await postJson(origin, "/api/projects/lumis/tasks", { title: "t", description: "d", taskType, idempotencyKey: key });
+      const id = (created.body as { task: { id: string } }).task.id;
+      await postJson(origin, `/api/tasks/${id}/claim`, { workerId: "w" });
+      return id;
+    };
+    const investigation = await create("investigation", "a");
+    const done = await postJson(origin, `/api/tasks/${investigation}`, { workerId: "w", status: "completed" });
+    assert.equal((done.body as { task: { status: string } }).task.status, "completed", "auto doesn't review an investigation");
+
+    const code = await create("code", "b");
+    const review = await postJson(origin, `/api/tasks/${code}`, { workerId: "w", status: "completed" });
+    const reviewed = review.body as { inReview: boolean; message: string; task: { status: string } };
+    assert.equal(reviewed.task.status, "in_review");
+    assert.equal(reviewed.inReview, true);
+    assert.equal((await postJson(origin, `/api/tasks/${code}`, { workerId: "w", status: "running" })).status, 409);
+    assert.equal((await postJson(origin, `/api/tasks/${code}/resume`, {})).status, 409);
+
+    assert.equal((await postJson(origin, `/api/tasks/${code}/send-back`, {})).status, 422, "sending back needs a note");
+    const sent = await postJson(origin, `/api/tasks/${code}/send-back`, { note: "Also cover the empty cart" });
+    const sentTask = (sent.body as { task: { status: string; reviewNote: string; attempts: number } }).task;
+    assert.equal(sentTask.status, "queued");
+    assert.equal(sentTask.reviewNote, "Also cover the empty cart");
+    assert.equal(sentTask.attempts, 0);
+
+    await postJson(origin, `/api/tasks/${code}/claim`, { workerId: "w" });
+    await postJson(origin, `/api/tasks/${code}`, { workerId: "w", status: "completed" });
+    const accepted = await postJson(origin, `/api/tasks/${code}/accept`, {});
+    assert.equal((accepted.body as { task: { status: string; reviewedBy: string } }).task.status, "completed");
+    assert.equal((await postJson(origin, `/api/tasks/${code}/accept`, {})).status, 409);
+  } finally {
+    await stub.close();
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("roles: suggestions wait for a decision; the dashboard's add form confirms", async () => {
+  await withStub(async (origin) => {
+    const suggested = await postJson(origin, "/api/projects/lumis/roles", { name: "Admin", description: "Admin area.", source: "role_gated_route", evidence: "route /admin" });
+    assert.equal(suggested.status, 201);
+    const role = (suggested.body as { role: { id: string; name: string; status: string } }).role;
+    assert.equal(role.name, "admin");
+    assert.equal(role.status, "suggested");
+    assert.equal((await postJson(origin, "/api/projects/lumis/roles", { name: "x", description: "x" })).status, 422, "a suggestion needs evidence");
+
+    const rejected = await fetch(`${origin}/api/projects/lumis/roles/${role.id}`, {
+      method: "PATCH", headers: { "content-type": "application/json" }, body: JSON.stringify({ action: "reject" }),
+    });
+    assert.equal(((await rejected.json()) as { role: { status: string } }).role.status, "rejected");
+    const again = await postJson(origin, "/api/projects/lumis/roles", { name: "admin", description: "Admin area.", source: "role_gated_menu", evidence: "menu Admin" });
+    assert.equal((again.body as { role: { status: string } }).role.status, "rejected", "a rejected role stays rejected");
+
+    const added = await postJson(origin, "/api/projects/lumis/roles", { name: "guest", description: "Not signed in.", source: "person" });
+    assert.equal((added.body as { role: { status: string } }).role.status, "confirmed");
+    const listed = await (await fetch(`${origin}/api/projects/lumis/roles?status=confirmed`)).json() as { roles: Array<{ name: string }> };
+    assert.deepEqual(listed.roles.map((item) => item.name), ["guest"]);
+  });
+});

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"],