@bugmole/cli 0.4.0 → 0.6.0

package/src/mcp/server.ts

@@ -1,13 +1,19 @@
 import http from "node:http";
+import { activeRevision, caseProblem, isObsolete, revisionOf } from "../registry/test-case-revisions.js";
+import { SCENARIO_CATEGORIES, SCENARIO_MEANING, isScenarioCategory, normalizeScenarioExclusions, scenarioMatrix } from "../runtime/scenario-matrix.js";
+import { applyAcceptedProposals } from "../runtime/apply-proposals.js";
 import fs from "node:fs";
 import path from "node:path";
 import { URL } from "node:url";
 import * as readline from "node:readline";
 import { createProjectObjectStore } from "../storage/create-object-store.js";
 import { json, type ObjectStore } from "../storage/object-store.js";
-import { projectPrefix } from "../storage/keys.js";
-import { ControlPlaneClient, isClaimableTask } from "../registry/control-plane-client.js";
+import { projectPrefix, runKey } from "../storage/keys.js";
+import { putTestCaseResults } from "../storage/test-case-results.js";
+import { ControlPlaneClient, isClaimableTask, workerApprovalMode } from "../registry/control-plane-client.js";
 import { getEnvironmentContract, setEnvironmentContract } from "../runtime/environment.js";
+import { collectRoleSuggestions, holdAgentRoleWrites, projectActorProblem, projectRoles, proposeRoleSuggestions, rolesClient } from "../runtime/project-roles.js";
+import { ROLE_SOURCES, normalizeRoleName } from "../registry/roles.js";
 import {
   completeCoordinatorJob,
   extractAtomicCandidates,
@@ -103,9 +109,9 @@ interface Prompt {
 function taskClient(cfg: any): ControlPlaneClient {
   const registryUrl = process.env.BUGMOLE_REGISTRY_URL ?? cfg.registry?.url ?? "https://api.bugmole.com";
   const apiKey = process.env.BUGMOLE_API_KEY ?? cfg.registry?.api_key;
-  if (!apiKey) throw new Error("BUGMOLE_API_KEY is required for agent task queue operations");
+  if (!apiKey) throw new Error("This needs your Bugmole account: set BUGMOLE_API_KEY in .bugmole.env (create a key on the dashboard's API keys page).");
   const projectId = cfg.project?.id;
-  if (!projectId) throw new Error("A project id is required for agent task queue operations");
+  if (!projectId) throw new Error("This needs a project ID: set project.id in .bugmole/config.yaml.");
   return new ControlPlaneClient({ registryUrl, apiKey, projectId });
 }
 
@@ -959,7 +965,7 @@ export function getTools(cfg: any): Tool[] {
     {
       name: "bugmole_write_test_cases",
       description:
-        "Validate and write test case assumptions for a discovered journey. Every case must reference a node (and optionally an edge) that exists in that journey at that revision — assumptions are grounded in the real graph, never invented.",
+        "Validate and write test case assumptions for a discovered journey. Every case must reference a node (and optionally an edge) that exists in that journey at that revision — assumptions are grounded in the real graph, never invented. Give each case a category (happy_path, validation, error_state, permission, edge_case): every step needs a happy_path case, and each other category needs a case somewhere in the journey or a scenarioExclusions entry with the reason it doesn't apply. The result lists what is still missing.",
       inputSchema: {
         type: "object",
         properties: {
@@ -971,10 +977,26 @@ export function getTools(cfg: any): Tool[] {
         required: ["caseSet"],
       },
     },
+    {
+      name: "bugmole_propose_test_case",
+      description:
+        "Propose adding, changing or retiring one test case. A change never edits a case in place: once accepted it becomes a new revision and the old one is marked obsolete. The project's approval mode decides whether a manager must accept it (manual, auto) or it's accepted on arrival (extreme). Say why in summary.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          caseSetId: { type: "string" },
+          caseId: { type: "string" },
+          action: { type: "string", enum: ["add", "change", "retire"] },
+          case: { type: "object", description: "The full case for add/change (title, nodeId, intent, steps, expected, confidence, basis), as in bugmole://spec/test-cases.schema.json" },
+          summary: { type: "string", description: "Why this change: what the app or the understanding of it changed" },
+        },
+        required: ["caseSetId", "caseId", "action", "summary"],
+      },
+    },
     {
       name: "bugmole_write_test_case_results",
       description:
-        "Record what a run observed for test cases already written by bugmole_write_test_cases. Every result must name a caseId that exists in that case set at that revision. This is the only thing that moves a case off \"planned\" — assumptions never count as evidence.",
+        "Record what a run observed for test cases already written by bugmole_write_test_cases. Every result must name a caseId that exists in that case set at that revision. This is the only thing that moves a case off \"planned\" — assumptions never count as evidence. Each write replaces the latest results and keeps its own copy in the case's history, so pass runId when there is one.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1103,9 +1125,50 @@ export function getTools(cfg: any): Tool[] {
         required: ["title", "description", "idempotencyKey"],
       },
     },
+    {
+      name: "bugmole_secrets_status",
+      description:
+        "List the secrets the project's flows type as {{secret.NAME}} (passwords, tokens), where each one comes from (Google Secret Manager, AWS Secrets Manager, this machine's secure store or keychain, or an environment variable) and whether this machine can supply it. Never returns a value. Never ask a person to paste a password into the chat: when one is missing, tell them to run `bugmole secrets set NAME` in their own terminal, or to map NAME to their vault under secrets: in the Bugmole config.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "bugmole_sign_in",
+      description:
+        "Sign in to the app by running a sign-in flow that types {{secret.NAME}} values, on this machine, and save the signed-in browser session (cookies and local storage). Returns the session file to explore or test as a signed-in user (Playwright storageState; bugmole --mode discover --sign-in uses the same flow). Secrets are read from the project's vault and never reach you.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          flow: { type: "string", description: "Path of the sign-in flow, relative to the workspace (e.g. spec/flows/sign-in.yaml)" },
+          baseUrl: { type: "string", description: "The app's address; the flow's own URL is moved onto it" },
+        },
+        required: ["flow"],
+      },
+    },
+    {
+      name: "bugmole_roles_list",
+      description:
+        "List the project's roles (who a journey is run as: guest, member, admin…) with their status. Only confirmed roles may be used as a plan's actor or a test case set's actor; suggested ones wait for a person, rejected ones are never used.",
+      inputSchema: { type: "object", properties: {} },
+    },
+    {
+      name: "bugmole_role_propose",
+      description:
+        "Suggest a role for a person to confirm, rename or reject on the dashboard's Roles page. You cannot confirm a role yourself. Give the evidence that points at it (a sign-in wall, a role-gated route or menu, a spec entry). With fromEvidence: true, Bugmole derives suggestions from the journey graph, blockers and roles.yaml instead. Suggesting a role a person already decided on changes nothing.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          name: { type: "string", description: "Role name, used as the actor id (e.g. member, admin)" },
+          description: { type: "string", description: "Who this is and what they can do" },
+          source: { type: "string", enum: ROLE_SOURCES.filter((source) => source !== "person") },
+          evidence: { type: "string", description: "What points at this role, e.g. \"sign-in screen at /login\" or \"route /admin\"" },
+          fromEvidence: { type: "boolean", description: "Derive and suggest roles from the project's graph, blockers and roles.yaml" },
+        },
+      },
+    },
     {
       name: "bugmole_task_update",
-      description: "Report progress, continuation steps, parity evidence, or a blocked/completed status for the claimed task.",
+      description:
+        "Report progress, continuation steps, parity evidence, or a blocked/completed status for the claimed task. Depending on the project's approval mode, a task you report completed may go to review (status in_review) instead: a person then accepts it or sends it back with a note. The response says so with inReview: true; do not treat the work as accepted.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1126,7 +1189,7 @@ export function getTools(cfg: any): Tool[] {
     {
       name: "bugmole_commit_response",
       description:
-        "Finalize a Cursor task by committing structured response payload. This is the mandatory final step for all CURSOR_DRIVER tasks. Use the SIMPLEST possible JSON - only status and summary are required. Everything else is optional.",
+        "Finish a task Bugmole handed to this agent by committing its structured response. It is the required last step of every such task. Keep the JSON simple: only status and summary are required.",
       inputSchema: {
         type: "object",
         properties: {
@@ -1496,7 +1559,7 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
 
     case "bugmole_explore": {
       const { explore } = await import("../runtime/explorer.js");
-      return await explore(cfg, {
+      const explored = await explore(cfg, {
         baseUrl: args.baseUrl,
         maxDepth: args.maxDepth,
         projectId: args.projectId,
@@ -1506,6 +1569,128 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         journeyId: args.journeyId,
         actor: args.actor,
       });
+      // Discovery is where roles show up (a sign-in wall, an /admin route),
+      // so suggest them now for a person to decide on. Best effort: a
+      // project without a registry key still gets the suggestions listed.
+      if (explored.status !== "success") return explored;
+      const suggestions = collectRoleSuggestions(cfg);
+      if (!suggestions.length) return explored;
+      const client = rolesClient(cfg);
+      const roles = await projectRoles(cfg, client);
+      const pending = suggestions.filter((suggestion) => !roles.usable.includes(suggestion.name));
+      if (!pending.length) return explored;
+      const proposed = client ? await proposeRoleSuggestions(pending, client, roles.usable) : [];
+      return {
+        ...explored,
+        roleSuggestions: client ? proposed : pending.map((item) => ({ name: item.name, source: item.source, status: "suggested", evidence: item.evidence })),
+        nextSteps: [
+          ...((explored as { nextSteps?: string[] }).nextSteps ?? []),
+          client
+            ? `Bugmole suggested roles (${pending.map((item) => item.name).join(", ")}). A person confirms, renames or rejects them on the Roles page; only confirmed roles are used for test cases and runs.`
+            : `Roles this exploration points at: ${pending.map((item) => item.name).join(", ")}. Suggest them with bugmole_role_propose (needs BUGMOLE_API_KEY) or add them to roles.yaml with status: suggested for a person to confirm.`,
+        ],
+      };
+    }
+
+    case "bugmole_secrets_status": {
+      const { projectSecretStatuses } = await import("../runtime/secrets-cli.js");
+      const { statuses, problems } = await projectSecretStatuses(cfg, process.cwd());
+      const missing = statuses.filter((status) => !status.ready);
+      return {
+        secrets: statuses,
+        problems,
+        nextSteps: missing.length
+          ? [`Ask the person to supply ${missing.map((status) => status.name).join(", ")} themselves: \`bugmole secrets set NAME\` in their own terminal, or a vault reference under secrets: in the config. Don't ask for the value in chat.`]
+          : [],
+      };
+    }
+    case "bugmole_sign_in": {
+      if (typeof args.flow !== "string" || !args.flow.trim()) throw new Error("flow is required");
+      const flowPath = path.resolve(process.cwd(), args.flow);
+      if (!flowPath.startsWith(path.resolve(process.cwd()) + path.sep)) throw new Error("flow must be inside the workspace");
+      if (!fs.existsSync(flowPath)) throw new Error(`No flow at ${args.flow}`);
+      const projectId = cfg.project?.id ?? "default";
+      const { secretMap } = await import("../runtime/secret-sources.js");
+      const { withFlowSecrets } = await import("../runtime/secret-driver.js");
+      const { PlaywrightDriver } = await import("../runtime/playwright-driver.js");
+      const runId = `sign-in-${Date.now()}`;
+      const directory = path.resolve(cfg.runtime?.artifacts_dir || "./artifacts", projectId, "sessions", runId);
+      // Session files hold the app's cookies: only this user may read them.
+      fs.mkdirSync(directory, { recursive: true, mode: 0o700 });
+      fs.chmodSync(path.dirname(directory), 0o700);
+      const sessionStatePath = path.join(directory, "session-state.json");
+      const driver = withFlowSecrets(new PlaywrightDriver({ headless: true }), { map: secretMap(cfg).map, projectId });
+      const result = await driver.run({
+        runId,
+        projectId,
+        journeyId: "sign-in",
+        flowPath,
+        platform: "web",
+        target: typeof args.baseUrl === "string" && args.baseUrl ? { baseUrl: args.baseUrl } : {},
+        rebaseOrigin: typeof args.baseUrl === "string" && Boolean(args.baseUrl),
+        timeoutMs: 60_000,
+        artifactsDir: path.join(directory, "artifacts"),
+        sessionStatePath,
+      });
+      if (result.status !== "passed") {
+        return {
+          status: result.status,
+          message: result.message,
+          nextSteps: result.failureCode === "secret_unavailable"
+            ? ["Call bugmole_secrets_status, then ask the person to supply the missing secret in their own terminal (bugmole secrets set NAME) or in their vault."]
+            : ["Check the sign-in flow against the app, then try again."],
+        };
+      }
+      return {
+        status: "passed",
+        sessionStatePath,
+        message: "Signed in. The session file holds cookies for the app: use it as Playwright storageState, and don't paste its contents anywhere.",
+      };
+    }
+    case "bugmole_roles_list": {
+      const client = rolesClient(cfg);
+      const roles = await projectRoles(cfg, client);
+      const registry = client && roles.registryRead ? (await client.listRoles().catch(() => ({ roles: [] }))).roles : [];
+      return {
+        confirmed: roles.usable,
+        suggested: roles.suggested,
+        roles: registry.length ? registry : roles.spec,
+        source: registry.length ? "registry" : "spec/roles.yaml",
+        ...(client && !roles.registryRead ? { warning: "Bugmole couldn't reach the account, so only spec/roles.yaml was read." } : {}),
+        nextSteps: roles.suggested.length
+          ? [`Ask a person to confirm or reject the suggested roles on the dashboard's Roles page: ${roles.suggested.join(", ")}`]
+          : [],
+      };
+    }
+
+    case "bugmole_role_propose": {
+      const client = rolesClient(cfg);
+      if (!client) throw new Error("BUGMOLE_API_KEY and a project id are required to suggest roles; or add the role to roles.yaml with status: suggested");
+      if (args.fromEvidence === true) {
+        const roles = await projectRoles(cfg, client);
+        const proposed = await proposeRoleSuggestions(collectRoleSuggestions(cfg), client, roles.usable);
+        return {
+          proposed,
+          message: proposed.length
+            ? "Suggested. A person confirms, renames or rejects each one on the Roles page; only confirmed roles are used."
+            : "Nothing new to suggest: the evidence points at no role that isn't already confirmed.",
+        };
+      }
+      const name = normalizeRoleName(args.name);
+      if (!name) throw new Error("name is required: letters, numbers and underscores, up to 60 characters");
+      if (typeof args.evidence !== "string" || !args.evidence.trim()) throw new Error("Say what points at this role in evidence");
+      const source = ROLE_SOURCES.includes(args.source) && args.source !== "person" ? args.source : "agent";
+      const { role, alreadyDecided } = await client.proposeRole({
+        name, description: typeof args.description === "string" ? args.description : "", source, evidence: args.evidence,
+      });
+      return {
+        role,
+        message: alreadyDecided
+          ? `A person already ${role.status} "${role.name}"; suggesting it again changes nothing.`
+          : role.status === "confirmed"
+            ? `"${role.name}" is already a confirmed role.`
+            : `Suggested "${role.name}". It is used for test cases and runs only after a person confirms it on the Roles page.`,
+      };
     }
 
     case "bugmole_journey_list": {
@@ -1597,6 +1782,26 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
     }
 
     case "bugmole_journey_stabilize": {
+      // "Stable" means a run proved the journey: check that run exists,
+      // passed, and ran this journey, instead of trusting any ID.
+      const runId = String(args.verificationRunId ?? "").trim();
+      const store = createProjectObjectStore(cfg, cfg.runtime.artifacts_dir || "./artifacts");
+      const manifestKey = runKey(cfg.project?.id ?? "default", runId, "manifest.json");
+      let manifest: { status?: string; journeyId?: string } | null = null;
+      try {
+        manifest = runId ? JSON.parse(await store.getText(manifestKey)) : null;
+      } catch {
+        manifest = null;
+      }
+      if (!manifest) {
+        return { status: "error", error: `No run ${runId || "(empty)"} in this project. Run the journey with bugmole_run, then pass that run's ID.` };
+      }
+      if (manifest.status !== "success") {
+        return { status: "error", error: `Run ${runId} did not pass (${manifest.status}). Fix the journey and run it again before marking it stable.` };
+      }
+      if (manifest.journeyId && manifest.journeyId !== args.journeyId) {
+        return { status: "error", error: `Run ${runId} ran journey ${manifest.journeyId}, not ${args.journeyId}.` };
+      }
       const result = await stabilizeJourney(cfg, {
         journeyId: args.journeyId,
         verificationRunId: args.verificationRunId,
@@ -1781,6 +1986,7 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
     }
 
     case "bugmole_plan": {
+      // The planner accepts only confirmed roles as the actor (src/registry/roles.ts).
       const { plan } = await import("../runtime/planner.js");
       return await plan(cfg, {
         journeyId: args.journeyId,
@@ -1852,6 +2058,13 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
           `caseSet.journeyRevision must match the selected journey revision (${journey.revision})`,
         );
       }
+      // Test cases are planned for confirmed roles only: a case set that
+      // names its actor must name one a person confirmed.
+      if (caseSet.actor !== undefined) {
+        if (typeof caseSet.actor !== "string" || !caseSet.actor.trim()) throw new Error("caseSet.actor must be a role name");
+        const actorIssue = projectActorProblem(await projectRoles(cfg), caseSet.actor.trim());
+        if (actorIssue) throw new Error(actorIssue);
+      }
       const allowedNodes = new Set(journey.nodeIds);
       const allowedEdges = new Set(journey.edgeIds);
       const seenCaseIds = new Set<string>();
@@ -1865,8 +2078,16 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         if (!/^[a-zA-Z0-9._-]+$/.test(testCase.caseId)) {
           throw new Error(`case ${testCase.caseId}: caseId may contain only letters, numbers, ., _, and -`);
         }
-        if (seenCaseIds.has(testCase.caseId)) throw new Error(`duplicate caseId: ${testCase.caseId}`);
-        seenCaseIds.add(testCase.caseId);
+        // A set keeps every revision of a case; only one may be current.
+        const revisionKey = `${testCase.caseId}@${revisionOf(testCase)}`;
+        if (seenCaseIds.has(revisionKey)) throw new Error(`duplicate caseId: ${testCase.caseId} (revision ${revisionOf(testCase)})`);
+        seenCaseIds.add(revisionKey);
+        if (!isObsolete(testCase)) {
+          if (seenCaseIds.has(`${testCase.caseId}@active`)) throw new Error(`case ${testCase.caseId} has more than one current revision`);
+          seenCaseIds.add(`${testCase.caseId}@active`);
+        }
+        // An obsolete revision may name steps the journey no longer has.
+        if (isObsolete(testCase)) continue;
         if (!allowedNodes.has(testCase.nodeId)) {
           throw new Error(
             `case ${testCase.caseId}: nodeId "${testCase.nodeId}" is not a step of journey ${caseSet.journeyId}`,
@@ -1895,7 +2116,30 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
             `case ${testCase.caseId}: a case with no basis must be confidence "low"`,
           );
         }
+        if (testCase.category !== undefined && !isScenarioCategory(testCase.category)) {
+          throw new Error(`case ${testCase.caseId}: category must be one of ${SCENARIO_CATEGORIES.join(", ")}`);
+        }
       }
+      if (caseSet.scenarioExclusions !== undefined) {
+        if (!Array.isArray(caseSet.scenarioExclusions)) throw new Error("caseSet.scenarioExclusions must be an array");
+        for (const exclusion of caseSet.scenarioExclusions) {
+          if (!exclusion || typeof exclusion !== "object" || !isScenarioCategory(exclusion.category)) {
+            throw new Error(`each scenario exclusion needs a category: one of ${SCENARIO_CATEGORIES.join(", ")}`);
+          }
+          // Saying a scenario doesn't apply is a claim like any other: it needs its reason.
+          if (typeof exclusion.reason !== "string" || !exclusion.reason.trim()) {
+            throw new Error(`scenario exclusion ${exclusion.category}: reason is required`);
+          }
+          if (exclusion.nodeId !== undefined && !allowedNodes.has(exclusion.nodeId)) {
+            throw new Error(`scenario exclusion ${exclusion.category}: nodeId "${exclusion.nodeId}" is not a step of journey ${caseSet.journeyId}`);
+          }
+        }
+      }
+      const matrix = scenarioMatrix(
+        journey.nodeIds,
+        caseSet.cases.filter((testCase: any) => !isObsolete(testCase)),
+        normalizeScenarioExclusions(caseSet.scenarioExclusions),
+      );
       const artifactsDir = cfg.runtime.artifacts_dir || "./artifacts";
       const store: ObjectStore = createProjectObjectStore(cfg, artifactsDir);
       const projectId = cfg.project?.id ?? "default";
@@ -1912,12 +2156,63 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         journeyId: caseSet.journeyId,
         caseCount: caseSet.cases.length,
         objectKey,
+        scenarios: {
+          missing: matrix.missing,
+          uncategorized: matrix.uncategorized,
+        },
         nextSteps: [
+          ...matrix.missing.map((gap) => gap.nodeId
+            ? `Step ${gap.nodeId} has no ${gap.category} case: add one (${SCENARIO_MEANING[gap.category]})`
+            : `No step covers ${gap.category}: add a case where it belongs (${SCENARIO_MEANING[gap.category]}), or a scenarioExclusions entry saying why it doesn't apply`),
+          ...(matrix.uncategorized.length
+            ? [`Give these cases a category so the scenario matrix can place them: ${matrix.uncategorized.join(", ")}`]
+            : []),
           `Plan the journey with bugmole_plan for "${caseSet.journeyId}" so these cases can be executed`,
         ],
       };
     }
 
+    case "bugmole_propose_test_case": {
+      const action = args.action;
+      if (!["add", "change", "retire"].includes(action)) throw new Error("action must be add, change or retire");
+      const projectId = cfg.project?.id ?? "default";
+      const store: ObjectStore = createProjectObjectStore(cfg, cfg.runtime.artifacts_dir || "./artifacts");
+      const key = `${projectPrefix(projectId)}/test-cases/${args.caseSetId}.json`;
+      if (!(await store.has(key))) throw new Error(`No case set ${args.caseSetId}; write it with bugmole_write_test_cases first`);
+      const caseSet = JSON.parse(await store.getText(key));
+      const current = activeRevision(caseSet, args.caseId);
+      if (action !== "add" && !current) throw new Error(`${args.caseId} has no current revision in ${args.caseSetId}`);
+      if (action === "add" && current) throw new Error(`${args.caseId} already exists at revision ${revisionOf(current)}; propose a change instead`);
+      if (action !== "retire") {
+        const problem = caseProblem({ ...(args.case ?? {}), caseId: args.caseId });
+        if (problem) throw new Error(`case ${args.caseId}: ${problem}`);
+        // Grounded like bugmole_write_test_cases: the step must exist in the journey.
+        const journey = readJourneyGraph(cfg).journeys.find((item) => item.id === caseSet.journeyId);
+        if (journey && !journey.nodeIds.includes(args.case.nodeId)) {
+          throw new Error(`case ${args.caseId}: nodeId "${args.case.nodeId}" is not a step of journey ${caseSet.journeyId}`);
+        }
+      }
+      const client = taskClient(cfg);
+      const { proposal } = await client.proposeTestCaseChange({
+        caseSetId: args.caseSetId,
+        caseId: args.caseId,
+        action,
+        ...(current ? { baseRevision: revisionOf(current) } : {}),
+        ...(action !== "retire" ? { case: args.case } : {}),
+        summary: args.summary,
+        source: "mcp",
+      });
+      // Accepted on arrival (extreme mode) and this project keeps its own files: apply it now.
+      const applied = proposal.status === "accepted" && !proposal.appliedAt ? await applyAcceptedProposals(cfg, client) : [];
+      return {
+        status: "success",
+        proposal: applied.length ? { ...proposal, applied: applied.find((item) => item.id === proposal.id) } : proposal,
+        nextSteps: proposal.status === "pending"
+          ? ["A project manager reviews this proposal on the Tests page; it becomes a new revision once accepted"]
+          : [],
+      };
+    }
+
     case "bugmole_write_test_case_results": {
       const resultSet = args.resultSet;
       if (!resultSet || typeof resultSet !== "object" || Array.isArray(resultSet)) {
@@ -1955,7 +2250,11 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
           + `(${storedCaseSet.journeyRevision}) — re-run against the current assumptions`,
         );
       }
-      const knownCaseIds = new Set((storedCaseSet.cases ?? []).map((item: any) => item.caseId));
+      // Only the current revision of a case can be judged; an obsolete one
+      // was replaced before this run. Each verdict records which revision it
+      // judged, so a later revision starts untested.
+      const activeCases = new Map<string, any>((storedCaseSet.cases ?? []).filter((item: any) => !isObsolete(item)).map((item: any) => [item.caseId, item]));
+      const knownCaseIds = new Set(activeCases.keys());
       const allowedStatuses = ["passed", "failed", "blocked", "needs_setup"];
       const seen = new Set<string>();
       for (const result of resultSet.results) {
@@ -1973,6 +2272,7 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         if (typeof result.detail !== "string" || !result.detail.trim()) {
           throw new Error(`result ${result.caseId}: detail is required — say what was observed`);
         }
+        result.caseRevision = revisionOf(activeCases.get(result.caseId));
       }
       const record = {
         ...resultSet,
@@ -1981,8 +2281,9 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         journeyRevision: storedCaseSet.journeyRevision,
         recordedAt: resultSet.recordedAt ?? new Date().toISOString(),
       };
-      const objectKey = `${projectPrefix(projectId)}/test-case-results/${resultSet.caseSetId}.json`;
-      await store.put(objectKey, JSON.stringify(record, null, 2) + "\n", "application/json");
+      // Latest verdicts plus one history entry per write, so earlier runs'
+      // verdicts survive for the case's pass/fail trail.
+      const { objectKey, historyKey } = await putTestCaseResults(store, projectId, record);
       const counts = resultSet.results.reduce((acc: Record<string, number>, item: any) => {
         acc[item.status] = (acc[item.status] ?? 0) + 1;
         return acc;
@@ -1995,6 +2296,7 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
         of: knownCaseIds.size,
         counts,
         objectKey,
+        historyKey,
       };
     }
 
@@ -2273,9 +2575,14 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
     case "bugmole_task_next": {
       const client = taskClient(cfg);
       const listed = await client.listTasks();
-      const next = listed.tasks.find((task) => isClaimableTask(task));
+      const next = listed.tasks.find((task) => isClaimableTask(task, Date.now(), workerApprovalMode()));
       if (!next) return { task: null, message: "No queued agent tasks are available." };
-      return client.claimTask(next.id, args.workerId);
+      const claimed = await client.claimTask(next.id, args.workerId);
+      // A task a person sent back from review carries what they want changed.
+      if (claimed.task?.reviewNote && next.reviewNote) {
+        return { ...claimed, message: `A reviewer sent this task back: ${claimed.task.reviewNote}. Address it before completing again.` };
+      }
+      return claimed;
     }
 
     case "bugmole_task_create": {
@@ -2297,7 +2604,20 @@ export async function callToolInternal(name: string, args: any, cfg: any): Promi
       const client = taskClient(cfg);
       const update = { ...args };
       delete update.taskId;
-      return client.updateTask(args.taskId, update);
+      const result = await client.updateTask(args.taskId, update) as { task: { status: string }; inReview?: boolean; message?: string };
+      // The project's approval mode may hold a completed task for a person.
+      if (result.inReview || result.task?.status === "in_review") {
+        return {
+          ...result,
+          inReview: true,
+          message: result.message ?? "This task is now in review: a person accepts it or sends it back with a note.",
+          nextSteps: [
+            "Do not treat this work as accepted yet; a person reviews it on the Agent Tasks board.",
+            "If it comes back, bugmole_task_next returns it with the reviewer's note in reviewNote.",
+          ],
+        };
+      }
+      return result;
     }
 
     case "bugmole_commit_response": {
@@ -2552,13 +2872,14 @@ export async function readResource(params: any, cfg: any): Promise<any> {
             "3. Call `bugmole_environment_get` for the selected environment. If it is missing or incomplete, call `bugmole_environment_set` with the safe base URL, mock/reference URL, device transport, device label, and reproducible start command before exploring.",
             "4. For an ADB environment, verify the named device is reachable and follow the recorded start command; do not guess a generic browser URL. For Lumis android-local, the expected transport is Nokia via ADB and the mock/reference URL is `https://gcore.otlrs.com/lumis-consumer/`.",
             "5. Call `bugmole_explore` with the environment ID; omit baseUrl when the environment contract provides it.",
+            "5a. If the app needs sign-in, never ask the person for a password in chat. Call `bugmole_secrets_status` to see which secrets the flows type and where each comes from; if one is missing, ask the person to run `bugmole secrets set NAME` in their own terminal or map it to their vault (Google Secret Manager, AWS Secrets Manager) under secrets: in the Bugmole config. Then call `bugmole_sign_in` with the sign-in flow to get a signed-in session to explore with.",
             "6. If an authenticated browser or device session is available, explore one concrete task and call `bugmole_record_discovery` with screens, transitions, proof tokens, `verifiedControlIds` for every button/link/action checked, and `completedNodeIds` after the terminal action actually succeeds.",
             "7. After every exploration or discovery result, call `bugmole_journey_get` and `bugmole_journey_next` for the selected flow.",
             "8. Perform the returned nextTask, add/edit the flow with `bugmole_journey_add_step` or `bugmole_journey_add_transition`, then call `bugmole_journey_next` again.",
             "9. If the chart returns blocked, inspect its clarification question and check the remembered resolution. Ask the user when it is missing or stale; record their answer with `bugmole_resolve_blocker`, then retry the chart.",
             "10. Continue this chart-check loop until every transition is runtime-verified, the terminal goal is completed, and `bugmole_journey_next` returns exhausted or an explicit blocked reason that cannot be resolved.",
-            "11. Once the flow is exhausted, write its test case assumptions: read `bugmole://spec/test-cases.schema.json` and call `bugmole_write_test_cases` with one case per step worth proving. Each case must name a real `nodeId` from that journey, state what it is trying to prove, and list observable expectations. Cite what each assumption is based on in `basis`; a case with nothing behind it must be `confidence: \"low\"` rather than a confident guess.",
-            "12. Confirm the selected actor exists in `roles.yaml`, then call `bugmole_plan` only after the flow is exhausted or documented as blocked.",
+            "11. Once the flow is exhausted, write its test case assumptions: read `bugmole://spec/test-cases.schema.json` and call `bugmole_write_test_cases` with one case per step worth proving. Each case must name a real `nodeId` from that journey, state what it is trying to prove, and list observable expectations. Cite what each assumption is based on in `basis`; a case with nothing behind it must be `confidence: \"low\"` rather than a confident guess. Give every case a `category`: each step needs a `happy_path` case, and the journey needs `validation`, `error_state`, `permission` and `edge_case` cases on the steps they belong to. When one truly doesn't apply (no input to validate, a single role), add a `scenarioExclusions` entry with the reason instead of leaving a silent gap. Follow the returned `nextSteps` until nothing is missing.",
+            "12. Confirm the selected actor is a confirmed role (`bugmole_roles_list`), then call `bugmole_plan` only after the flow is exhausted or documented as blocked. Bugmole suggests roles and a person decides: if the flow needs a role that isn't confirmed, suggest it with `bugmole_role_propose` (with its evidence) and stop there — you cannot confirm a role yourself, and a suggested or rejected role is never planned for.",
             "13. After a run actually exercises those cases, record what it observed: read `bugmole://spec/test-case-results.schema.json` and call `bugmole_write_test_case_results` with one result per case you checked. This is the only thing that moves a case off \"planned\" — writing assumptions never counts as proof, so a flow whose cases were verified but never recorded reads as 0% covered. Say what you saw in `detail` (status code, element present or missing, assertion that failed), use \"failed\" when a check ran and the expectation did not hold, and \"blocked\" only when it could not be run at all. Do not record a result for a case you did not actually exercise.",
             "14. Commit progress/results with `bugmole_commit_response`, always including the returned `nextSteps` until the workflow is complete.",
             "",
@@ -2674,8 +2995,9 @@ export async function readResource(params: any, cfg: any): Promise<any> {
           "For taskType ui, read the parity guidance and schema, rerun affected flows, generate a fresh parity artifact, and include parityAuditId and parityMatchScore.",
           "A UI task cannot be completed without fresh parity evidence. If parity is blocked, leave the task blocked with concrete next steps.",
           "When finished, call bugmole_task_update with status completed, completionSummary, changedFiles, and required parity evidence.",
+          "Depending on the project's approval mode the task then goes to review (inReview: true, status in_review) instead of completed: manual reviews every task, auto reviews code and ui tasks, extreme none. A person accepts it or sends it back; a task sent back returns through bugmole_task_next with the reviewer's note in reviewNote — address that note before completing again.",
           "",
-          "Finishing a task is not the end of the work. This queue drives an autonomous pipeline: explore, then define any missing actors in roles.yaml, then write test case assumptions with bugmole_write_test_cases, then bugmole_plan. If your task leaves an obvious next stage undone, queue it with bugmole_task_create before you complete, using a stable idempotencyKey of the form `pipeline:<projectId>:<stage>:<journeyId>` so it cannot duplicate an existing one.",
+          "Finishing a task is not the end of the work. This queue drives an autonomous pipeline: explore, then suggest any missing roles with bugmole_role_propose (a person confirms them), then write test case assumptions with bugmole_write_test_cases, then bugmole_plan. If your task leaves an obvious next stage undone, queue it with bugmole_task_create before you complete, using a stable idempotencyKey of the form `pipeline:<projectId>:<stage>:<journeyId>` so it cannot duplicate an existing one.",
           "The worker independently reconciles the same pipeline from the artifacts on disk, so a follow-up you skip is still picked up. Never invent a stage that the evidence does not support just to keep the pipeline moving, and never mark work completed that you did not actually finish — a blocked task with concrete next steps is more useful than a false completion.",
         ].join("\n"),
       }],
@@ -2728,7 +3050,7 @@ export async function getPrompt(params: any, cfg: any): Promise<any> {
                 "Use bugmole_explore for source/application discovery when a runnable base URL exists. If you have an authenticated browser session, inspect the owner dashboard there and persist concrete observations with bugmole_record_discovery.",
                 "After every meaningful phase, call bugmole_report_progress, read the current journey chart, and call bugmole_journey_next.",
                 "Perform the returned flow task, record its concrete screen/transition evidence, and repeat the chart check until it returns exhausted or blocked.",
-                "Before bugmole_plan, verify that the journey graph has real nodes/actions, no actionable next task remains, and the actor exists in roles.yaml.",
+                "Before bugmole_plan, verify that the journey graph has real nodes/actions, no actionable next task remains, and the actor is a confirmed role (bugmole_roles_list). Suggest missing roles with bugmole_role_propose; only a person confirms them.",
                 "If discovery is incomplete, return a blocked status with concrete next_steps instead of creating a generic login-only plan.",
                 "After planning, read the generated plan resource, validate its steps against the discovered evidence, and only then hand it to the dashboard for execution.",
               ].join("\n"),
@@ -2812,7 +3134,7 @@ export async function getPrompt(params: any, cfg: any): Promise<any> {
               "You are continuing a dashboard-created Bugmole agent task.",
               "Read bugmole://guidance/agent-task-queue, then call bugmole_task_next with a stable workerId.",
               "Implement the claimed task and report progress. For UI tasks, rerun parity after the fix and do not complete without a fresh parity audit id and match score.",
-              "Call bugmole_task_update with completed or blocked status and concrete evidence.",
+              "Call bugmole_task_update with completed or blocked status and concrete evidence. If the response says inReview, a person reviews the work before it counts as completed.",
             ].join("\n"),
           },
         }],
@@ -3053,6 +3375,16 @@ export function writeSpecFile(filePath: string, content: string, cfg: any): any
   const dir = path.dirname(fullPath);
   fs.mkdirSync(dir, { recursive: true });
 
+  // An agent can suggest roles in roles.yaml but not confirm them: new or
+  // promoted roles are written `status: suggested` for a person to decide.
+  let heldBack: string[] = [];
+  if (path.normalize(filePath) === "roles.yaml") {
+    const previous = fs.existsSync(fullPath) ? fs.readFileSync(fullPath, "utf-8") : null;
+    const held = holdAgentRoleWrites(previous, content);
+    content = held.content;
+    heldBack = held.heldBack;
+  }
+
   // Write file
   fs.writeFileSync(fullPath, content, "utf-8");
 
@@ -3060,5 +3392,9 @@ export function writeSpecFile(filePath: string, content: string, cfg: any): any
     success: true,
     path: filePath,
     size: content.length,
+    ...(heldBack.length ? {
+      suggestedRoles: heldBack,
+      message: `Written as suggestions: ${heldBack.join(", ")}. A person confirms or rejects them on the Roles page before they are used for test cases or runs.`,
+    } : {}),
   };
 }