@bugmole/cli 0.4.0

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

@@ -0,0 +1,803 @@
+/**
+ * A local, loopback-only stand-in for the real Bugmole registry (the
+ * deployed Cloudflare Worker at BUGMOLE_REGISTRY_URL). It implements the
+ * same REST contract (`src/registry-worker/index.ts`'s plans/runs/tasks/
+ * journeys endpoints, as consumed by `ControlPlaneClient` and the
+ * dashboard's `apps/qa/src/app/api/**` proxy routes) but persists to a
+ * local JSON file per collection instead of the real D1 database, and
+ * accepts any caller without checking `x-aegis-id`/Bearer credentials.
+ *
+ * This exists so a project that has no real registered access (no
+ * BUGMOLE_API_KEY scoped to it, no real Aegis membership) can still
+ * exercise the full write path locally — queue a task, have `bugmole serve`'s
+ * worker claim and run it, publish a plan, start a run — without the real
+ * registry rejecting every write with "Project scope is not allowed" and
+ * without repeatedly clicking through the real Aegis login. It is never
+ * reachable from a browser directly (the dashboard's own Next.js server
+ * proxies to it, same as it would the real registry); binding to
+ * 127.0.0.1 only is the trust boundary, matching other local-only dev
+ * servers in this codebase (e.g. the local artifact bridge).
+ *
+ * Deliberately out of scope: workspaces, apps, environments, api-keys,
+ * device authorizations, and `GET /api/projects` (project listing stays
+ * "no real membership" so the dashboard's local-dev-bypass project
+ * synthesis — see `apps/qa/src/app/dashboard-route.tsx` — keeps doing
+ * exactly what it already does for reads).
+ */
+import http from "node:http";
+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";
+
+export type LocalRegistryStub = {
+  origin: string;
+  close(): Promise<void>;
+};
+
+export type LocalRegistryStubOptions = {
+  directory: string;
+  port?: number;
+};
+
+type PlanDraft = {
+  id: string;
+  projectId: string;
+  planId: string;
+  journeyId: string;
+  objectKey: string;
+  status: "draft";
+  createdBy: string;
+  createdAt: string;
+  updatedAt: string;
+};
+
+type Run = {
+  id: string;
+  projectId: string;
+  planId: string;
+  journeyId?: string;
+  journeyRevision?: number | null;
+  environmentId?: string | null;
+  environmentBaseUrl?: string | null;
+  targets?: Array<{ browser: string; device?: string }> | null;
+  targetResults?: unknown[] | null;
+  durationMs?: number | null;
+  fixFrom?: { runId: string; targetId: string } | null;
+  status: string;
+  workerId?: string | null;
+  currentStep?: string | null;
+  stepsExecuted: number;
+  stepsPassed: number;
+  stepsFailed: number;
+  driver?: string | null;
+  platform?: string | null;
+  recoveryAttempts?: number | null;
+  failureCode?: string | null;
+  artifactSummaryJson?: string | null;
+  errorCode?: string | null;
+  errorMessage?: string | null;
+  manifestKey?: string | null;
+  idempotencyKey: string;
+  requestedAt: string;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};
+
+type AgentTask = {
+  id: string;
+  projectId: string;
+  title: string;
+  description: string;
+  taskType: "code" | "ui" | "investigation" | "discovery";
+  priority: number;
+  status: string;
+  requestedBy: string;
+  workerId?: string | null;
+  progressMessage?: string | null;
+  continuation?: unknown;
+  parityMatchScore?: number | null;
+  parityAuditId?: string | null;
+  completionSummary?: string | null;
+  changedFiles?: unknown;
+  errorMessage?: string | null;
+  journeyId?: string | null;
+  journeyRevision?: number | null;
+  stepId?: string | null;
+  attempts?: number;
+  nextAttemptAt?: string | null;
+  leaseExpiresAt?: string | null;
+  idempotencyKey: string;
+  requestedAt: string;
+  startedAt?: string | null;
+  completedAt?: string | null;
+};
+
+type JourneyRevision = {
+  id: string;
+  projectId: string;
+  journeyId: string;
+  revision: number;
+  objectKey: string;
+  appId?: string | null;
+  environmentId?: string | null;
+  status: "draft" | "published";
+  sourceOfTruth: "canonical_flow";
+  stability: "discovered" | "stabilizing" | "stable";
+  linkedToGraph: boolean;
+  verificationRunId?: string | null;
+  createdBy: string;
+  createdAt: string;
+};
+
+type Persona = {
+  id: string;
+  projectId: string;
+  name: string;
+  description: string;
+  isDefault: boolean;
+  createdBy: string;
+  createdAt: string;
+};
+
+/**
+ * Same default text as src/registry-worker/personas/routes.ts's
+ * DEFAULT_PERSONA — duplicated, not imported: this stub and the registry
+ * worker are separately deployable units, so it can't reach across into
+ * registry-worker's own module graph.
+ */
+const DEFAULT_PERSONA = {
+  name: "Curious",
+  description:
+    "Explore like a curious first-time visitor. Click into anything unfamiliar, wander into secondary sections " +
+    "instead of only the shortest path to a goal, and open things out of order the way someone browsing for the " +
+    "first time would. Prefer journeys that reveal more of the app over the single fastest way through it.",
+};
+
+function genId(prefix: string): string {
+  return `${prefix}_${randomBytes(9).toString("base64url")}`;
+}
+
+function writeJson(response: http.ServerResponse, status: number, body: unknown): void {
+  response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+  response.end(JSON.stringify(body));
+}
+
+async function readJsonBody(request: http.IncomingMessage): Promise<Record<string, unknown> | null> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of request) chunks.push(Buffer.from(chunk));
+  if (chunks.length === 0) return null;
+  try {
+    return JSON.parse(Buffer.concat(chunks).toString("utf8")) as Record<string, unknown>;
+  } catch {
+    return null;
+  }
+}
+
+async function loadCollection<T>(store: ObjectStore, projectId: string, name: string): Promise<T[]> {
+  const key = `projects/${encodeURIComponent(projectId)}/local-registry/${name}.json`;
+  if (!(await store.has(key))) return [];
+  try {
+    return JSON.parse(await store.getText(key)) as T[];
+  } catch {
+    return [];
+  }
+}
+
+async function saveCollection<T>(store: ObjectStore, projectId: string, name: string, items: T[]): Promise<void> {
+  const key = `projects/${encodeURIComponent(projectId)}/local-registry/${name}.json`;
+  await store.put(key, JSON.stringify(items, null, 2), "application/json");
+}
+
+export async function startLocalRegistryStub(options: LocalRegistryStubOptions): Promise<LocalRegistryStub> {
+  const store = createObjectStore({
+    provider: "local",
+    localDirectory: options.directory,
+  } satisfies ObjectStoreConfig);
+
+  const server = http.createServer(async (request, response) => {
+    try {
+      const url = new URL(request.url ?? "/", "http://127.0.0.1");
+      const method = request.method ?? "GET";
+
+      if (method === "GET" && url.pathname === "/health") {
+        writeJson(response, 200, { ok: true, service: "bugmole-local-registry-stub" });
+        return;
+      }
+      if (method === "GET" && url.pathname === "/api/projects") {
+        writeJson(response, 200, { projects: [] });
+        return;
+      }
+
+      const plansMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/plans$/);
+      if (plansMatch) {
+        const projectId = decodeURIComponent(plansMatch[1]);
+        if (method === "GET") {
+          const plans = await loadCollection<PlanDraft>(store, projectId, "plans");
+          writeJson(response, 200, { plans: [...plans].sort((a, b) => b.updatedAt.localeCompare(a.updatedAt)) });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const planId = typeof body?.planId === "string" ? body.planId.trim() : "";
+          const journeyId = typeof body?.journeyId === "string" ? body.journeyId.trim() : "";
+          const objectKey = typeof body?.objectKey === "string" ? body.objectKey.trim() : "";
+          if (!planId || !journeyId || !objectKey) {
+            writeJson(response, 422, { error: "planId, journeyId, and objectKey are required" });
+            return;
+          }
+          const plans = await loadCollection<PlanDraft>(store, projectId, "plans");
+          const now = new Date().toISOString();
+          const existingIndex = plans.findIndex((plan) => plan.planId === planId);
+          const plan: PlanDraft = {
+            id: existingIndex >= 0 ? plans[existingIndex].id : genId("plan"),
+            projectId,
+            planId,
+            journeyId,
+            objectKey,
+            status: "draft",
+            createdBy: existingIndex >= 0 ? plans[existingIndex].createdBy : "local-dev-bypass",
+            createdAt: existingIndex >= 0 ? plans[existingIndex].createdAt : now,
+            updatedAt: now,
+          };
+          if (existingIndex >= 0) plans[existingIndex] = plan; else plans.push(plan);
+          await saveCollection(store, projectId, "plans", plans);
+          writeJson(response, 201, { plan });
+          return;
+        }
+      }
+
+      const personasMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/personas$/);
+      if (personasMatch) {
+        const projectId = decodeURIComponent(personasMatch[1]);
+        if (method === "GET") {
+          let personas = await loadCollection<Persona>(store, projectId, "personas");
+          if (personas.length === 0) {
+            personas = [{
+              id: genId("persona"), projectId, name: DEFAULT_PERSONA.name, description: DEFAULT_PERSONA.description,
+              isDefault: true, createdBy: "local-dev-bypass", createdAt: new Date().toISOString(),
+            }];
+            await saveCollection(store, projectId, "personas", personas);
+          }
+          writeJson(response, 200, { personas });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const name = typeof body?.name === "string" ? body.name.trim() : "";
+          const description = typeof body?.description === "string" ? body.description.trim() : "";
+          if (!name || name.length > 60 || !description || description.length > 1000) {
+            writeJson(response, 422, { error: "name and description are required (name up to 60 characters, description up to 1000)" });
+            return;
+          }
+          const personas = await loadCollection<Persona>(store, projectId, "personas");
+          if (personas.some((persona) => persona.name === name)) {
+            writeJson(response, 409, { error: "A persona with that name already exists" });
+            return;
+          }
+          const persona: Persona = { id: genId("persona"), projectId, name, description, isDefault: false, createdBy: "local-dev-bypass", createdAt: new Date().toISOString() };
+          personas.push(persona);
+          await saveCollection(store, projectId, "personas", personas);
+          writeJson(response, 201, { persona });
+          return;
+        }
+      }
+
+      const personaMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/personas\/([^/]+)$/);
+      if (personaMatch) {
+        const projectId = decodeURIComponent(personaMatch[1]);
+        const personaId = decodeURIComponent(personaMatch[2]);
+        const personas = await loadCollection<Persona>(store, projectId, "personas");
+        const index = personas.findIndex((persona) => persona.id === personaId);
+        if (index < 0) {
+          writeJson(response, 404, { error: "Not found" });
+          return;
+        }
+        if (method === "DELETE") {
+          if (personas.length <= 1) {
+            writeJson(response, 409, { error: "A project needs at least one persona; add another before removing this one" });
+            return;
+          }
+          personas.splice(index, 1);
+          await saveCollection(store, projectId, "personas", personas);
+          writeJson(response, 200, { deleted: true });
+          return;
+        }
+        if (method === "PATCH") {
+          const body = await readJsonBody(request);
+          const name = typeof body?.name === "string" ? body.name.trim() : "";
+          const description = typeof body?.description === "string" ? body.description.trim() : "";
+          if (!name || name.length > 60 || !description || description.length > 1000) {
+            writeJson(response, 422, { error: "name and description are required (name up to 60 characters, description up to 1000)" });
+            return;
+          }
+          if (personas.some((persona) => persona.name === name && persona.id !== personaId)) {
+            writeJson(response, 409, { error: "A persona with that name already exists" });
+            return;
+          }
+          personas[index] = { ...personas[index], name, description };
+          await saveCollection(store, projectId, "personas", personas);
+          writeJson(response, 200, { persona: personas[index] });
+          return;
+        }
+      }
+
+      const runsMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/runs$/);
+      if (runsMatch) {
+        const projectId = decodeURIComponent(runsMatch[1]);
+        if (method === "GET") {
+          const runs = await loadCollection<Run>(store, projectId, "runs");
+          writeJson(response, 200, { runs: [...runs].sort((a, b) => b.requestedAt.localeCompare(a.requestedAt)).slice(0, 100) });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const planId = typeof body?.planId === "string" ? body.planId.trim() : "";
+          const idempotencyKey = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+          if (!planId || !idempotencyKey) {
+            writeJson(response, 422, { error: "planId and idempotencyKey are required" });
+            return;
+          }
+          const plans = await loadCollection<PlanDraft>(store, projectId, "plans");
+          const draft = plans.find((plan) => plan.planId === planId);
+          if (!draft) {
+            writeJson(response, 404, { error: "Plan draft not found" });
+            return;
+          }
+          const runs = await loadCollection<Run>(store, projectId, "runs");
+          const existing = runs.find((run) => run.idempotencyKey === idempotencyKey);
+          if (existing) {
+            writeJson(response, 200, { run: existing });
+            return;
+          }
+          let targets: Array<{ browser: string; device?: string }> = [];
+          try {
+            targets = normalizeTargets(body?.targets).map(({ browser, device }) => (device ? { browser, device } : { browser }));
+          } catch (error) {
+            writeJson(response, 422, { error: error instanceof Error ? error.message : String(error) });
+            return;
+          }
+          const now = new Date().toISOString();
+          const run: Run = {
+            id: genId("run"),
+            projectId,
+            planId,
+            journeyId: draft.journeyId,
+            journeyRevision: Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+            environmentId: typeof body?.environmentId === "string" ? body.environmentId : null,
+            // The stub has no environments table, so a caller passes the URL directly.
+            environmentBaseUrl: typeof body?.environmentBaseUrl === "string" && body.environmentBaseUrl ? body.environmentBaseUrl : null,
+            targets: targets.length > 0 ? targets : null,
+            targetResults: null,
+            durationMs: null,
+            fixFrom: body?.fixFrom && typeof (body.fixFrom as { runId?: unknown }).runId === "string"
+              ? { runId: String((body.fixFrom as { runId: string }).runId), targetId: String((body.fixFrom as { targetId?: string }).targetId ?? "") }
+              : null,
+            status: "queued",
+            stepsExecuted: 0,
+            stepsPassed: 0,
+            stepsFailed: 0,
+            driver: typeof body?.driver === "string" ? body.driver : "maestro",
+            platform: typeof body?.platform === "string" ? body.platform : null,
+            idempotencyKey,
+            requestedAt: now,
+          };
+          runs.push(run);
+          await saveCollection(store, projectId, "runs", runs);
+          writeJson(response, 201, { run });
+          return;
+        }
+      }
+
+      const runClaimMatch = url.pathname.match(/^\/api\/runs\/([^/]+)\/claim$/);
+      if (runClaimMatch && method === "POST") {
+        const runId = decodeURIComponent(runClaimMatch[1]);
+        const body = await readJsonBody(request);
+        const workerId = typeof body?.workerId === "string" ? body.workerId.trim() : "";
+        if (!workerId) {
+          writeJson(response, 422, { error: "workerId is required" });
+          return;
+        }
+        const found = await findRunAnyProject(store, runId);
+        if (!found) {
+          writeJson(response, 404, { error: "Run not found" });
+          return;
+        }
+        const { projectId, runs, index } = found;
+        if (runs[index].status !== "queued") {
+          writeJson(response, 409, { error: "Run is already claimed or complete" });
+          return;
+        }
+        const leaseExpiresAt = new Date(Date.now() + 60_000).toISOString();
+        runs[index] = { ...runs[index], status: "running", workerId, startedAt: runs[index].startedAt ?? new Date().toISOString() };
+        await saveCollection(store, projectId, "runs", runs);
+        writeJson(response, 200, {
+          claimed: true,
+          leaseExpiresAt,
+          environmentBaseUrl: runs[index].environmentBaseUrl ?? null,
+          targets: runs[index].targets ?? null,
+          fixFrom: runs[index].fixFrom ?? null,
+        });
+        return;
+      }
+
+      const runUpdateMatch = url.pathname.match(/^\/api\/runs\/([^/]+)$/);
+      if (runUpdateMatch) {
+        const runId = decodeURIComponent(runUpdateMatch[1]);
+        const found = await findRunAnyProject(store, runId);
+        if (!found) {
+          writeJson(response, 404, { error: "Run not found" });
+          return;
+        }
+        const { projectId, runs, index } = found;
+        if (method === "GET") {
+          writeJson(response, 200, { run: runs[index], events: [] });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const status = typeof body?.status === "string" ? body.status : "running";
+          const terminal = ["success", "partial", "error", "cancelled"].includes(status);
+          // Mirrors the registry: a late update can't reopen a finished run.
+          if (!terminal && ["success", "partial", "error", "cancelled"].includes(runs[index].status)) {
+            writeJson(response, 409, { error: "Run already finished" });
+            return;
+          }
+          runs[index] = {
+            ...runs[index],
+            status,
+            currentStep: typeof body?.currentStep === "string" ? body.currentStep : runs[index].currentStep,
+            stepsExecuted: Number(body?.stepsExecuted ?? runs[index].stepsExecuted),
+            stepsPassed: Number(body?.stepsPassed ?? runs[index].stepsPassed),
+            stepsFailed: Number(body?.stepsFailed ?? runs[index].stepsFailed),
+            errorCode: typeof body?.errorCode === "string" ? body.errorCode : runs[index].errorCode,
+            errorMessage: typeof body?.errorMessage === "string" ? body.errorMessage : runs[index].errorMessage,
+            driver: typeof body?.driver === "string" ? body.driver : runs[index].driver,
+            platform: typeof body?.platform === "string" ? body.platform : runs[index].platform,
+            recoveryAttempts: Number.isFinite(Number(body?.recoveryAttempts)) ? Number(body?.recoveryAttempts) : runs[index].recoveryAttempts,
+            failureCode: typeof body?.failureCode === "string" ? body.failureCode : runs[index].failureCode,
+            artifactSummaryJson: typeof body?.artifactSummaryJson === "string" ? body.artifactSummaryJson : runs[index].artifactSummaryJson,
+            targetResults: Array.isArray(body?.targetResults) ? body.targetResults : runs[index].targetResults,
+            completedAt: terminal ? new Date().toISOString() : runs[index].completedAt,
+          };
+          const { startedAt, completedAt } = runs[index];
+          if (startedAt && completedAt) runs[index].durationMs = Math.max(0, Date.parse(completedAt) - Date.parse(startedAt));
+          await saveCollection(store, projectId, "runs", runs);
+          writeJson(response, 200, { updated: true });
+          return;
+        }
+      }
+
+      const tasksMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/tasks$/);
+      if (tasksMatch) {
+        const projectId = decodeURIComponent(tasksMatch[1]);
+        if (method === "GET") {
+          const tasks = await loadCollection<AgentTask>(store, projectId, "tasks");
+          const sorted = [...tasks].sort((a, b) => b.priority - a.priority || a.requestedAt.localeCompare(b.requestedAt));
+          writeJson(response, 200, { tasks: sorted.slice(0, 100) });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const title = typeof body?.title === "string" ? body.title.trim() : "";
+          const description = typeof body?.description === "string" ? body.description.trim() : "";
+          const idempotencyKey = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+          const taskType = body?.taskType && ["code", "ui", "investigation", "discovery"].includes(body.taskType as string)
+            ? body.taskType as AgentTask["taskType"] : "code";
+          if (!title || !description || !idempotencyKey) {
+            writeJson(response, 422, { error: "title, description, and idempotencyKey are required" });
+            return;
+          }
+          const tasks = await loadCollection<AgentTask>(store, projectId, "tasks");
+          const existingIndex = tasks.findIndex((task) => task.idempotencyKey === idempotencyKey);
+          const existing = existingIndex >= 0 ? tasks[existingIndex] : undefined;
+          if (existing && !["completed", "error"].includes(existing.status)) {
+            writeJson(response, 200, { task: existing });
+            return;
+          }
+          if (existing) {
+            // See registry-worker's createAgentTask: a finished task can't
+            // just be superseded by a new row under the same idempotency
+            // key, or a cancelled task would be returned forever, making
+            // retry impossible. Recycle the row into a fresh attempt.
+            tasks[existingIndex] = {
+              ...existing,
+              title,
+              description,
+              taskType,
+              priority: Number.isFinite(Number(body?.priority)) ? Number(body?.priority) : 0,
+              status: "queued",
+              workerId: null,
+              progressMessage: null,
+              continuation: undefined,
+              completionSummary: null,
+              changedFiles: undefined,
+              errorMessage: null,
+              journeyId: typeof body?.journeyId === "string" ? body.journeyId : null,
+              journeyRevision: Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+              stepId: typeof body?.stepId === "string" ? body.stepId : null,
+              attempts: 0,
+              nextAttemptAt: null,
+              requestedAt: new Date().toISOString(),
+              startedAt: null,
+              completedAt: null,
+            };
+            await saveCollection(store, projectId, "tasks", tasks);
+            writeJson(response, 200, { task: tasks[existingIndex] });
+            return;
+          }
+          const task: AgentTask = {
+            id: genId("task"),
+            projectId,
+            title,
+            description,
+            taskType,
+            priority: Number.isFinite(Number(body?.priority)) ? Number(body?.priority) : 0,
+            status: "queued",
+            requestedBy: "local-dev-bypass",
+            idempotencyKey,
+            journeyId: typeof body?.journeyId === "string" ? body.journeyId : null,
+            journeyRevision: Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+            stepId: typeof body?.stepId === "string" ? body.stepId : null,
+            attempts: 0,
+            nextAttemptAt: null,
+            requestedAt: new Date().toISOString(),
+          };
+          tasks.push(task);
+          await saveCollection(store, projectId, "tasks", tasks);
+          writeJson(response, 201, { task });
+          return;
+        }
+      }
+
+      const taskClaimMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/claim$/);
+      if (taskClaimMatch && method === "POST") {
+        const taskId = decodeURIComponent(taskClaimMatch[1]);
+        const body = await readJsonBody(request);
+        const workerId = typeof body?.workerId === "string" ? body.workerId.trim() : "";
+        if (!workerId) {
+          writeJson(response, 422, { error: "workerId is required" });
+          return;
+        }
+        const found = await findTaskAnyProject(store, taskId);
+        if (!found) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        const { projectId, tasks, index } = found;
+        // Mirrors registry-worker: a running task whose lease has lapsed is
+        // reclaimable, otherwise a worker that died mid-task would wedge
+        // the queue permanently. Without this the client-side selector and
+        // the claim handler disagreed — the selector offered a stale task
+        // and the claim rejected it, aborting every poll.
+        const lease = tasks[index].leaseExpiresAt;
+        const reclaimable = tasks[index].status === "running"
+          && Boolean(lease)
+          && Date.parse(lease!) <= Date.now();
+        if (!["queued", "blocked"].includes(tasks[index].status) && !reclaimable) {
+          writeJson(response, 409, { error: "Task is already claimed or complete" });
+          return;
+        }
+        // Mirrors registry-worker's claim guard: claiming counts as an
+        // attempt, and an exhausted or backed-off task is not claimable.
+        const attempts = tasks[index].attempts ?? 0;
+        const nextAttemptAt = tasks[index].nextAttemptAt;
+        if (attempts >= MAX_TASK_ATTEMPTS || (nextAttemptAt && Date.parse(nextAttemptAt) > Date.now())) {
+          writeJson(response, 409, { error: "Task is already claimed, complete, or has exhausted its attempts" });
+          return;
+        }
+        const leaseExpiresAt = new Date(Date.now() + 60_000).toISOString();
+        tasks[index] = {
+          ...tasks[index],
+          status: "running",
+          workerId,
+          attempts: attempts + 1,
+          leaseExpiresAt,
+          startedAt: tasks[index].startedAt ?? new Date().toISOString(),
+        };
+        await saveCollection(store, projectId, "tasks", tasks);
+        writeJson(response, 200, { claimed: true, leaseExpiresAt, task: tasks[index] });
+        return;
+      }
+
+      const taskCancelMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/cancel$/);
+      if (taskCancelMatch && method === "POST") {
+        const taskId = decodeURIComponent(taskCancelMatch[1]);
+        const found = await findTaskAnyProject(store, taskId);
+        if (!found) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        const { projectId, tasks, index } = found;
+        if (["completed", "error"].includes(tasks[index].status)) {
+          writeJson(response, 409, { error: "Task is already finished" });
+          return;
+        }
+        const body = await readJsonBody(request);
+        const reason = typeof body?.reason === "string" && body.reason.trim() ? body.reason.trim() : "Cancelled by user";
+        tasks[index] = {
+          ...tasks[index],
+          status: "error",
+          errorMessage: reason,
+          completionSummary: "Cancelled",
+          completedAt: new Date().toISOString(),
+        };
+        await saveCollection(store, projectId, "tasks", tasks);
+        writeJson(response, 200, { cancelled: true, task: tasks[index] });
+        return;
+      }
+
+      const taskResumeMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/resume$/);
+      if (taskResumeMatch && method === "POST") {
+        const taskId = decodeURIComponent(taskResumeMatch[1]);
+        const found = await findTaskAnyProject(store, taskId);
+        if (!found) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        const { projectId, tasks, index } = found;
+        if (!isResumableTask(tasks[index])) {
+          writeJson(response, 409, {
+            error: tasks[index].status === "completed"
+              ? "Task is already finished"
+              : "Task is still held by a live worker",
+          });
+          return;
+        }
+        const body = await readJsonBody(request);
+        const note = typeof body?.note === "string" && body.note.trim() ? body.note.trim() : "Resumed by user";
+        tasks[index] = {
+          ...tasks[index],
+          ...resumedTaskFields(),
+          progressMessage: note,
+          errorMessage: null,
+          completedAt: null,
+        };
+        await saveCollection(store, projectId, "tasks", tasks);
+        writeJson(response, 200, { resumed: true, task: tasks[index] });
+        return;
+      }
+
+      const taskUpdateMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)$/);
+      if (taskUpdateMatch && method === "POST") {
+        const taskId = decodeURIComponent(taskUpdateMatch[1]);
+        const found = await findTaskAnyProject(store, taskId);
+        if (!found) {
+          writeJson(response, 404, { error: "Task not found" });
+          return;
+        }
+        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)) {
+          writeJson(response, 422, { error: "Invalid task status" });
+          return;
+        }
+        if (status === "completed" && tasks[index].taskType === "ui" && (!body?.parityAuditId || typeof body?.parityMatchScore !== "number")) {
+          writeJson(response, 422, { error: "UI tasks require parityAuditId and parityMatchScore before completion" });
+          return;
+        }
+        const terminal = ["completed", "error"].includes(status);
+        tasks[index] = {
+          ...tasks[index],
+          status,
+          progressMessage: typeof body?.progressMessage === "string" ? body.progressMessage : tasks[index].progressMessage,
+          continuation: body?.continuation ?? tasks[index].continuation,
+          parityMatchScore: typeof body?.parityMatchScore === "number" ? body.parityMatchScore : tasks[index].parityMatchScore,
+          parityAuditId: typeof body?.parityAuditId === "string" ? body.parityAuditId : tasks[index].parityAuditId,
+          completionSummary: typeof body?.completionSummary === "string" ? body.completionSummary : tasks[index].completionSummary,
+          changedFiles: Array.isArray(body?.changedFiles) ? body.changedFiles : tasks[index].changedFiles,
+          errorMessage: typeof body?.errorMessage === "string" ? body.errorMessage : tasks[index].errorMessage,
+          // See registry-worker's updateAgentTask: falling back to blocked
+          // schedules the retry instead of making it instantly claimable.
+          nextAttemptAt: status === "blocked"
+            ? backoffUntil(tasks[index].attempts ?? 0)
+            : tasks[index].nextAttemptAt ?? null,
+          leaseExpiresAt: 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] });
+        return;
+      }
+
+      const journeysMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/journeys$/);
+      if (journeysMatch) {
+        const projectId = decodeURIComponent(journeysMatch[1]);
+        if (method === "GET") {
+          const revisions = await loadCollection<JourneyRevision>(store, projectId, "journeys");
+          writeJson(response, 200, { revisions });
+          return;
+        }
+        if (method === "POST") {
+          const body = await readJsonBody(request);
+          const journeyId = typeof body?.journeyId === "string" ? body.journeyId.trim() : "";
+          const objectKey = typeof body?.objectKey === "string" ? body.objectKey.trim() : "";
+          if (!journeyId || !objectKey) {
+            writeJson(response, 422, { error: "journeyId and objectKey are required" });
+            return;
+          }
+          const revisions = await loadCollection<JourneyRevision>(store, projectId, "journeys");
+          const currentRevision = revisions
+            .filter((rev) => rev.journeyId === journeyId)
+            .reduce((max, rev) => Math.max(max, rev.revision), 0);
+          if (body?.expectedRevision !== undefined && Number(body.expectedRevision) !== currentRevision) {
+            writeJson(response, 409, { error: "Journey revision conflict", currentRevision });
+            return;
+          }
+          const revision: JourneyRevision = {
+            id: genId("journey"),
+            projectId,
+            journeyId,
+            revision: currentRevision + 1,
+            objectKey,
+            appId: typeof body?.appId === "string" ? body.appId : null,
+            environmentId: typeof body?.environmentId === "string" ? body.environmentId : null,
+            status: body?.status === "published" ? "published" : "draft",
+            sourceOfTruth: "canonical_flow",
+            stability: body?.stability === "stable" ? "stable" : body?.stability === "stabilizing" ? "stabilizing" : "discovered",
+            linkedToGraph: body?.linkedToGraph === true,
+            verificationRunId: typeof body?.verificationRunId === "string" ? body.verificationRunId : null,
+            createdBy: "local-dev-bypass",
+            createdAt: new Date().toISOString(),
+          };
+          revisions.push(revision);
+          await saveCollection(store, projectId, "journeys", revisions);
+          writeJson(response, 201, { revision });
+          return;
+        }
+      }
+
+      writeJson(response, 404, { error: "Not found" });
+    } catch (error) {
+      writeJson(response, 500, { error: error instanceof Error ? error.message : "Local registry stub error" });
+    }
+  });
+
+  await new Promise<void>((resolve) => server.listen(options.port ?? 0, "127.0.0.1", resolve));
+  const address = server.address();
+  const port = typeof address === "object" && address ? address.port : options.port ?? 0;
+  const origin = `http://127.0.0.1:${port}`;
+
+  return {
+    origin,
+    async close() {
+      await new Promise<void>((resolve) => server.close(() => resolve()));
+    },
+  };
+
+  async function findRunAnyProject(objectStore: ObjectStore, runId: string) {
+    const prefix = "projects/";
+    const objects = await objectStore.list(prefix);
+    const projectIds = [...new Set(
+      objects
+        .map((object) => object.key.match(/^projects\/([^/]+)\/local-registry\/runs\.json$/)?.[1])
+        .filter((value): value is string => Boolean(value)),
+    )];
+    for (const encodedProjectId of projectIds) {
+      const projectId = decodeURIComponent(encodedProjectId);
+      const runs = await loadCollection<Run>(objectStore, projectId, "runs");
+      const index = runs.findIndex((run) => run.id === runId);
+      if (index >= 0) return { projectId, runs, index };
+    }
+    return null;
+  }
+
+  async function findTaskAnyProject(objectStore: ObjectStore, taskId: string) {
+    const prefix = "projects/";
+    const objects = await objectStore.list(prefix);
+    const projectIds = [...new Set(
+      objects
+        .map((object) => object.key.match(/^projects\/([^/]+)\/local-registry\/tasks\.json$/)?.[1])
+        .filter((value): value is string => Boolean(value)),
+    )];
+    for (const encodedProjectId of projectIds) {
+      const projectId = decodeURIComponent(encodedProjectId);
+      const tasks = await loadCollection<AgentTask>(objectStore, projectId, "tasks");
+      const index = tasks.findIndex((task) => task.id === taskId);
+      if (index >= 0) return { projectId, tasks, index };
+    }
+    return null;
+  }
+}