@bugmole/cli 0.4.0

package/src/registry-worker/index.ts

@@ -0,0 +1,2077 @@
+import { MAX_TASK_ATTEMPTS, backoffUntil, isResumableTask, resumedTaskFields } from "../registry/task-scheduling.js";
+import { getProjectArtifact, isRunManifestKey, listProjectArtifacts } from "./artifacts.js";
+import {
+  type Env,
+  type Principal,
+  jsonHeaders,
+  response,
+  bearer,
+  sha256,
+  subscriptionPrincipal,
+  apiPrincipal,
+  constantTimeEqual,
+  can,
+  projectAllowed,
+  memberOfProject,
+  memberOfWorkspace,
+  randomToken,
+  base64,
+  fromBase64,
+  encryptForSecret,
+  decryptForSecret,
+} from "./core.js";
+
+export type { Env } from "./core.js";
+import { detachedContext, handleExtendedRoutes, handlePublicRoutes } from "./routes/index.js";
+import { runScheduledJobs } from "./jobs/index.js";
+import { actorOf, auditProject, recordAudit } from "./org/audit.js";
+import { checkCloudRun, checkProjectLimit, executionModeOf, historyCutoffFor } from "./billing/enforcement.js";
+import { workspaceOfProject } from "./billing/entitlements.js";
+import { heartbeatChecks, registryDispatch, runChangedHooks, runQueuedHooks, runService, taskChangedHooks, taskQueuedHooks, type InternalRunFields } from "./hooks.js";
+import { appendRunEvent, broadcastProjectEvent } from "./run-events.js";
+import { runnerMayCall } from "./runner/tokens.js";
+import { cloudStorageError } from "./runner/policy.js";
+import { deviceTargetsError } from "./devices/policy.js";
+import { requireVerifiedDomainForCloud } from "./domains/routes.js";
+import { cloudTargetId, parseCloudDevice } from "../runtime/device-clouds/targets.js";
+import type { CloudDevice } from "../runtime/device-clouds/types.js";
+import { cloudAccountError, freeWorkspaceLimit } from "./signup/policy.js";
+import { applyOrgMembership, isDeprovisioned } from "./sso/membership.js";
+import "./features.js";
+
+function deviceCode(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(2));
+  return String(((bytes[0] << 8) | bytes[1]) % 10_000).padStart(4, "0");
+}
+
+async function createDeviceAuthorization(request: Request, env: Env): Promise<Response> {
+  const body = await request.json().catch(() => null) as {
+    projectId?: string;
+    projectName?: string;
+    environment?: string;
+    storageProvider?: string;
+  } | null;
+  if (!body?.projectId || !body.projectName || !body.environment || !body.storageProvider) {
+    return response({ error: "projectId, projectName, environment, and storageProvider are required" }, 422);
+  }
+  const sourceIp = request.headers.get("CF-Connecting-IP") ?? "unknown";
+  const recent = await env.DB.prepare(`
+    SELECT COUNT(*) AS count FROM device_authorizations
+    WHERE source_ip = ? AND created_at > datetime('now', '-10 minutes')
+  `).bind(sourceIp).first<{ count: number }>();
+  if ((recent?.count ?? 0) >= 10) return response({ error: "Too many device registration attempts" }, 429);
+  const attemptId = `dev_${randomToken(18)}`;
+  const code = deviceCode();
+  const pollSecret = randomToken(32);
+  const expiresAt = new Date(Date.now() + 5 * 60 * 1000).toISOString();
+  await env.DB.prepare(`
+    INSERT INTO device_authorizations
+      (attempt_id, code_hash, poll_secret_hash, project_id, project_name, environment, storage_provider, source_ip, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    attemptId,
+    await sha256(code),
+    await sha256(pollSecret),
+    body.projectId,
+    body.projectName,
+    body.environment,
+    currentStorageProvider(body.storageProvider),
+    sourceIp,
+    expiresAt,
+  ).run();
+  return response({ attemptId, code, pollSecret, expiresAt }, 201);
+}
+
+/**
+ * A friendly default from the email's domain: ada@northwind.io -> "Northwind".
+ * Empty for the big free providers, where the domain says nothing about the
+ * person. Mirrors apps/qa/src/lib/signup-intent.ts's workspaceNameFromEmail —
+ * duplicated rather than imported, since the dashboard and the registry
+ * worker build separately and don't share a module graph.
+ */
+function workspaceNameFromEmail(email: string | null | undefined): string {
+  const domain = email?.split("@")[1]?.split(".")[0] ?? "";
+  if (!domain || ["gmail", "outlook", "hotmail", "yahoo", "icloud", "proton", "protonmail"].includes(domain)) return "";
+  return domain.charAt(0).toUpperCase() + domain.slice(1);
+}
+
+async function claimDeviceAuthorization(request: Request, env: Env, principal: Principal): Promise<Response> {
+  const body = await request.json().catch(() => null) as {
+    attemptId?: string;
+    code?: string;
+    deviceId?: string;
+    email?: string;
+  } | null;
+  if (!body?.attemptId || !body.code || !/^\d{4}$/.test(body.code)) {
+    return response({ error: "attemptId and a four-digit code are required" }, 422);
+  }
+  const attempt = await env.DB.prepare(`
+    SELECT attempt_id AS attemptId, code_hash AS codeHash, project_id AS projectId,
+           project_name AS projectName, environment, storage_provider AS storageProvider,
+           status, failed_attempts AS failedAttempts, expires_at AS expiresAt
+    FROM device_authorizations WHERE attempt_id = ?
+  `).bind(body.attemptId).first<{
+    attemptId: string;
+    codeHash: string;
+    projectId: string;
+    projectName: string;
+    environment: string;
+    storageProvider: string;
+    status: string;
+    failedAttempts: number;
+    expiresAt: string;
+  }>();
+  if (!attempt || attempt.status !== "pending" || Date.parse(attempt.expiresAt) <= Date.now()) {
+    return response({ error: "Device authorization expired or already completed" }, 410);
+  }
+  if (attempt.failedAttempts >= 5) return response({ error: "Too many code attempts" }, 429);
+  if (!constantTimeEqual(await sha256(body.code), attempt.codeHash)) {
+    await env.DB.prepare("UPDATE device_authorizations SET failed_attempts = failed_attempts + 1 WHERE attempt_id = ?")
+      .bind(body.attemptId).run();
+    return response({ error: "Incorrect authorization code" }, 401);
+  }
+  if (body.deviceId !== attempt.projectId) {
+    return response({ error: "Device binding does not match the Bugmole project" }, 403);
+  }
+
+  const claimResult = await env.DB.prepare(`
+    UPDATE device_authorizations SET status = 'claimed', aegis_id = ?, aegis_email = ?, claimed_at = CURRENT_TIMESTAMP
+    WHERE attempt_id = ? AND status = 'pending'
+  `).bind(principal.aegisId, body.email?.trim() || null, body.attemptId).run() as { meta?: { changes?: number } };
+  if (claimResult.meta?.changes !== 1) {
+    return response({ error: "Device authorization was claimed by another session" }, 409);
+  }
+
+  const existingKeys = await env.DB.prepare(`
+    SELECT id, project_ids_json AS projectIds
+    FROM api_keys WHERE aegis_id = ? AND revoked_at IS NULL
+  `).bind(principal.aegisId).all<{ id: string; projectIds: string }>();
+  const existingKey = existingKeys.results.find((key) => {
+    try {
+      const projectIds = JSON.parse(key.projectIds) as unknown;
+      return Array.isArray(projectIds) && projectIds.includes(attempt.projectId);
+    } catch {
+      return false;
+    }
+  });
+  const now = new Date().toISOString();
+  const workspaceId = `workspace_${principal.aegisId}`;
+  const workspaceName = workspaceNameFromEmail(body.email) || (attempt.projectName ? `${attempt.projectName} workspace` : "My workspace");
+  const environmentId = attempt.environment.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "") || "default";
+  if (existingKey) {
+    try {
+      await env.DB.batch([
+        env.DB.prepare("INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING").bind(principal.aegisId),
+        env.DB.prepare(`
+          INSERT INTO workspaces (id, name, created_by)
+          VALUES (?, ?, ?)
+          ON CONFLICT(id) DO NOTHING
+        `).bind(workspaceId, workspaceName, principal.aegisId),
+        env.DB.prepare(`
+          INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status)
+          VALUES (?, ?, 'owner', 'active')
+          ON CONFLICT(workspace_id, aegis_id) DO UPDATE SET status = 'active'
+        `).bind(workspaceId, principal.aegisId),
+        env.DB.prepare(`
+          INSERT INTO projects (id, workspace_id, tenant_id, name, environment, storage_provider, created_at)
+          VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+          ON CONFLICT(id) DO UPDATE SET name = excluded.name, environment = excluded.environment,
+            storage_provider = excluded.storage_provider, workspace_id = excluded.workspace_id
+        `).bind(attempt.projectId, workspaceId, workspaceId, attempt.projectName, attempt.environment, currentStorageProvider(attempt.storageProvider)),
+        env.DB.prepare(`
+          INSERT INTO project_apps (id, project_id, name, type, is_default)
+          VALUES ('default', ?, ?, 'web', 1)
+          ON CONFLICT(project_id, id) DO UPDATE SET name = excluded.name
+        `).bind(attempt.projectId, attempt.projectName),
+        env.DB.prepare(`
+          INSERT INTO project_environments (id, project_id, app_id, name, base_url, status, is_default)
+          VALUES (?, ?, 'default', ?, '', 'active', 1)
+          ON CONFLICT(project_id, id) DO UPDATE SET app_id = excluded.app_id, name = excluded.name, is_default = 1
+        `).bind(environmentId, attempt.projectId, attempt.environment),
+        env.DB.prepare(`
+          INSERT INTO project_memberships (project_id, aegis_id, role, status)
+          VALUES (?, ?, 'owner', 'active')
+          ON CONFLICT(project_id, aegis_id) DO UPDATE SET status = 'active'
+        `).bind(attempt.projectId, principal.aegisId),
+        env.DB.prepare(`
+          UPDATE device_authorizations SET status = 'completed', aegis_id = ?, api_key_id = ?, completed_at = ?
+          WHERE attempt_id = ? AND status = 'claimed'
+        `).bind(principal.aegisId, existingKey.id, now, body.attemptId),
+      ]);
+    } catch (error) {
+      await releaseClaimedDeviceAuthorization(env, body.attemptId);
+      throw error;
+    }
+    return response({ claimed: true, alreadyInitialized: true }, 200);
+  }
+
+  const id = `key_${randomToken(12)}`;
+  const token = `bm_live_${id}_${randomToken()}`;
+  const encrypted = await encryptForSecret(token, await pollSecretForAttempt(env, body.attemptId));
+  try {
+    await env.DB.batch([
+      env.DB.prepare("INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING").bind(principal.aegisId),
+      env.DB.prepare(`
+        INSERT INTO workspaces (id, name, created_by)
+        VALUES (?, ? ,?)
+        ON CONFLICT(id) DO NOTHING
+      `).bind(workspaceId, workspaceName, principal.aegisId),
+      env.DB.prepare(`
+        INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status)
+        VALUES (?, ?, 'owner', 'active')
+        ON CONFLICT(workspace_id, aegis_id) DO UPDATE SET status = 'active'
+      `).bind(workspaceId, principal.aegisId),
+      env.DB.prepare(`
+        INSERT INTO projects (id, workspace_id, tenant_id, name, environment, storage_provider, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+        ON CONFLICT(id) DO UPDATE SET name = excluded.name, environment = excluded.environment,
+          storage_provider = excluded.storage_provider, workspace_id = excluded.workspace_id
+      `).bind(attempt.projectId, workspaceId, workspaceId, attempt.projectName, attempt.environment, currentStorageProvider(attempt.storageProvider)),
+      env.DB.prepare(`
+        INSERT INTO project_apps (id, project_id, name, type, is_default)
+        VALUES ('default', ?, ?, 'web', 1)
+        ON CONFLICT(project_id, id) DO UPDATE SET name = excluded.name
+      `).bind(attempt.projectId, attempt.projectName),
+      env.DB.prepare(`
+        INSERT INTO project_environments (id, project_id, app_id, name, base_url, status, is_default)
+        VALUES (?, ?, 'default', ?, '', 'active', 1)
+        ON CONFLICT(project_id, id) DO UPDATE SET app_id = excluded.app_id, name = excluded.name, is_default = 1
+      `).bind(environmentId, attempt.projectId, attempt.environment),
+      env.DB.prepare(`
+        INSERT INTO project_memberships (project_id, aegis_id, role, status)
+        VALUES (?, ?, 'owner', 'active')
+        ON CONFLICT(project_id, aegis_id) DO UPDATE SET status = 'active'
+      `).bind(attempt.projectId, principal.aegisId),
+      env.DB.prepare(`
+        INSERT INTO api_keys (id, aegis_id, name, token_hash, scopes_json, project_ids_json, expires_at)
+        VALUES (?, ?, ?, ?, ?, ?, NULL)
+      `).bind(id, principal.aegisId, `${attempt.projectName} CLI`, await sha256(token),
+        JSON.stringify(["projects:read", "projects:write", "runs:write", "artifacts:write"]), JSON.stringify([attempt.projectId])),
+      env.DB.prepare(`
+        UPDATE device_authorizations
+        SET status = 'completed', aegis_id = ?, api_key_id = ?, encrypted_token = ?, token_iv = ?, completed_at = ?
+        WHERE attempt_id = ? AND status = 'claimed'
+      `).bind(principal.aegisId, id, encrypted.ciphertext, encrypted.iv, now, body.attemptId),
+    ]);
+  } catch (error) {
+    await releaseClaimedDeviceAuthorization(env, body.attemptId);
+    throw error;
+  }
+  return response({ claimed: true, alreadyInitialized: false }, 200);
+}
+
+async function releaseClaimedDeviceAuthorization(env: Env, attemptId: string): Promise<void> {
+  await env.DB.prepare(`
+    UPDATE device_authorizations
+    SET status = 'pending', aegis_id = NULL, aegis_email = NULL, claimed_at = NULL
+    WHERE attempt_id = ? AND status = 'claimed' AND api_key_id IS NULL
+  `).bind(attemptId).run();
+}
+
+async function pollSecretForAttempt(env: Env, attemptId: string): Promise<string> {
+  // The poll secret is never stored in plaintext. The token encryption key is
+  // derived from the poll secret supplied on the poll request and re-encrypted
+  // during claim through the short-lived claim handoff below.
+  const row = await env.DB.prepare("SELECT poll_secret_hash AS pollSecretHash FROM device_authorizations WHERE attempt_id = ?")
+    .bind(attemptId).first<{ pollSecretHash: string }>();
+  if (!row) throw new Error("Device authorization not found");
+  return row.pollSecretHash;
+}
+
+async function pollDeviceAuthorization(request: Request, env: Env): Promise<Response> {
+  const body = await request.json().catch(() => null) as { attemptId?: string; pollSecret?: string } | null;
+  if (!body?.attemptId || !body.pollSecret) return response({ error: "attemptId and pollSecret are required" }, 422);
+  const attempt = await env.DB.prepare(`
+    SELECT status, expires_at AS expiresAt, encrypted_token AS encryptedToken, token_iv AS tokenIv,
+           poll_secret_hash AS pollSecretHash, aegis_email AS aegisEmail
+    FROM device_authorizations WHERE attempt_id = ?
+  `).bind(body.attemptId).first<{
+    status: string;
+    expiresAt: string;
+    encryptedToken: string | null;
+    tokenIv: string | null;
+    pollSecretHash: string;
+    aegisEmail: string | null;
+  }>();
+  if (!attempt || !constantTimeEqual(await sha256(body.pollSecret), attempt.pollSecretHash)) {
+    return response({ error: "Device authorization not found" }, 404);
+  }
+  if (Date.parse(attempt.expiresAt) <= Date.now() && attempt.status === "pending") {
+    await env.DB.prepare("UPDATE device_authorizations SET status = 'expired' WHERE attempt_id = ?")
+      .bind(body.attemptId).run();
+    return response({ status: "expired" }, 410);
+  }
+  if (attempt.status === "pending") return response({ status: "pending" }, 202);
+  if (!attempt.encryptedToken || !attempt.tokenIv) return response({ status: "completed", alreadyInitialized: true }, 200);
+  const result = await env.DB.prepare(`
+    UPDATE device_authorizations SET encrypted_token = NULL, token_iv = NULL
+    WHERE attempt_id = ? AND status = 'completed' AND encrypted_token = ?
+  `).bind(body.attemptId, attempt.encryptedToken).run() as { meta?: { changes?: number } };
+  if (result.meta?.changes !== 1) return response({ status: "completed", alreadyInitialized: true }, 200);
+  const token = await decryptForSecret(
+    attempt.encryptedToken,
+    attempt.tokenIv,
+    await sha256(body.pollSecret),
+  );
+  return response({ status: "completed", alreadyInitialized: false, token, email: attempt.aegisEmail }, 200);
+}
+
+async function registerProject(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "projects:write")) return response({ error: "Project registration is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as {
+    id?: string;
+    name?: string;
+    appId?: string;
+    appName?: string;
+    workspaceId?: string;
+    workspaceName?: string;
+    tenantId?: string;
+    environment?: string;
+    storageProvider?: string;
+  } | null;
+  if (!body?.id || !body.name || !body.environment || !body.storageProvider) {
+    return response({ error: "id, name, environment, and storageProvider are required" }, 422);
+  }
+  if (!projectAllowed(principal, body.id)) return response({ error: "Project scope is not allowed" }, 403);
+  const workspaceId = body.workspaceId ?? body.tenantId ?? `workspace_${principal.aegisId}`;
+  const tenantId = body.tenantId ?? workspaceId;
+  const existingWorkspace = await env.DB.prepare(
+    "SELECT id FROM workspaces WHERE id = ?",
+  ).bind(workspaceId).first<{ id: string }>();
+  if (existingWorkspace && !(await memberOfWorkspace(env, principal, workspaceId, "workspace.write"))) {
+    return response({ error: "Workspace scope is not allowed" }, 403);
+  }
+  // Re-registering a project is how the CLI refreshes it, but only for people
+  // who may manage it; otherwise an id could be used to move someone else's
+  // project into another workspace.
+  const existingProject = await env.DB.prepare("SELECT workspace_id AS workspaceId FROM projects WHERE id = ?")
+    .bind(body.id).first<{ workspaceId: string }>();
+  if (existingProject && !(await memberOfProject(env, principal, body.id, "project.manage"))) {
+    return response({ error: "A project with this id already exists" }, 409);
+  }
+  if (existingProject && existingProject.workspaceId !== workspaceId) {
+    return response({ error: "This project belongs to another workspace" }, 409);
+  }
+  const joinedAt = new Date().toISOString();
+  await env.DB.batch([
+    env.DB.prepare(`
+      INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING
+    `).bind(principal.aegisId),
+    env.DB.prepare(`
+      INSERT INTO workspaces (id, name, created_by)
+      VALUES (?, ?, ?)
+      ON CONFLICT(id) DO NOTHING
+    `).bind(workspaceId, body.workspaceName ?? workspaceId, principal.aegisId),
+    // Only the creator of a brand-new workspace becomes its owner; an existing
+    // membership (including a removed one) is left alone.
+    env.DB.prepare(`
+      INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status, created_at)
+      SELECT ?, ?, 'owner', 'active', ?
+      WHERE NOT EXISTS (SELECT 1 FROM workspace_memberships WHERE workspace_id = ?)
+    `).bind(workspaceId, principal.aegisId, joinedAt, workspaceId),
+    env.DB.prepare(`
+      INSERT INTO project_apps (id, project_id, name, type, is_default)
+      VALUES (?, ?, ?, 'web', 1)
+      ON CONFLICT(project_id, id) DO NOTHING
+    `).bind(body.appId?.trim() || "default", body.id, body.appName?.trim() || body.name),
+    env.DB.prepare(`
+      INSERT INTO projects (id, workspace_id, tenant_id, name, environment, storage_provider, created_at)
+      VALUES (?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+      ON CONFLICT(id) DO UPDATE SET name = excluded.name, environment = excluded.environment,
+        storage_provider = excluded.storage_provider, workspace_id = excluded.workspace_id
+    `).bind(body.id, workspaceId, tenantId, body.name, body.environment, currentStorageProvider(body.storageProvider)),
+    env.DB.prepare(`
+      INSERT INTO project_memberships (project_id, aegis_id, role, status)
+      VALUES (?, ?, 'owner', 'active')
+      ON CONFLICT(project_id, aegis_id) DO NOTHING
+    `).bind(body.id, principal.aegisId),
+  ]);
+  await auditProject(env, principal, body.id, { action: "project.registered", targetType: "project", targetId: body.id, data: { environment: body.environment } }, request);
+  return response({ registered: true, projectId: body.id, workspaceId, tenantId }, 201);
+}
+
+async function listWorkspaces(env: Env, principal: Principal): Promise<Response> {
+  const rows = await env.DB.prepare(`
+    SELECT w.id, w.name, w.created_at AS createdAt, wm.role
+    FROM workspaces w
+    JOIN workspace_memberships wm ON wm.workspace_id = w.id
+    WHERE wm.aegis_id = ? AND wm.status = 'active'
+    ORDER BY w.created_at ASC
+  `).bind(principal.aegisId).all();
+  const workspaces = await Promise.all(rows.results.map(async (workspace) => {
+    const projects = await env.DB.prepare(`
+      SELECT p.id, p.name, p.environment, p.storage_provider AS storageProvider
+      FROM projects p
+      WHERE p.workspace_id = ? AND p.deleted_at IS NULL
+      ORDER BY p.created_at ASC
+    `).bind(workspace.id).all();
+    return { ...workspace, projects: projects.results };
+  }));
+  return response({ workspaces });
+}
+
+async function createWorkspace(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) {
+    return response({ error: "Workspace creation is not allowed" }, 403);
+  }
+  const body = await request.json().catch(() => null) as { id?: string; name?: string } | null;
+  const workspaceId = body?.id?.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+  const name = body?.name?.trim();
+  if (!workspaceId || !name) return response({ error: "id and name are required" }, 422);
+  const freeLimit = await freeWorkspaceLimit(env, principal);
+  if (freeLimit) return freeLimit;
+  try {
+    await env.DB.batch([
+      env.DB.prepare("INSERT INTO aegis_users (id) VALUES (?) ON CONFLICT(id) DO NOTHING").bind(principal.aegisId),
+      env.DB.prepare("INSERT INTO workspaces (id, name, created_by) VALUES (?, ?, ?)").bind(workspaceId, name, principal.aegisId),
+      env.DB.prepare(`
+        INSERT INTO workspace_memberships (workspace_id, aegis_id, role, status)
+        VALUES (?, ?, 'owner', 'active')
+      `).bind(workspaceId, principal.aegisId),
+    ]);
+  } catch {
+    return response({ error: "A workspace with this id already exists" }, 409);
+  }
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "workspace.created", targetType: "workspace", targetId: workspaceId }, request);
+  return response({ workspace: { id: workspaceId, name, projects: [] } }, 201);
+}
+
+async function updateWorkspace(request: Request, env: Env, principal: Principal, workspaceId: string): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "Workspace editing is not allowed" }, 403);
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.manage"))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as { name?: string } | null;
+  const name = body?.name?.trim();
+  if (!name) return response({ error: "name is required" }, 422);
+  await env.DB.prepare("UPDATE workspaces SET name = ? WHERE id = ?").bind(name, workspaceId).run();
+  await recordAudit(env, actorOf(principal), { workspaceId, action: "workspace.renamed", targetType: "workspace", targetId: workspaceId, data: { name } }, request);
+  return response({ workspace: { id: workspaceId, name } });
+}
+
+/** Bugmole storage was called "valkyrie" before the rename; 0.3.x CLIs still send that. */
+export function currentStorageProvider(provider: string): string {
+  return provider.trim() === "valkyrie" ? "bugmole" : provider.trim();
+}
+
+/** "bugmole" storage lives in Bugmole's bucket; anything else is the customer's own. */
+function storageModeOf(provider: string): "managed" | "byo" {
+  return currentStorageProvider(provider) === "bugmole" ? "managed" : "byo";
+}
+
+async function createManagedProject(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "Project creation is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as {
+    id?: string; name?: string; workspaceId?: string; environment?: string; storageProvider?: string;
+  } | null;
+  const projectId = body?.id?.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+  const name = body?.name?.trim();
+  const workspaceId = body?.workspaceId?.trim();
+  if (!projectId || !name || !workspaceId || !body?.environment?.trim() || !body.storageProvider?.trim()) {
+    return response({ error: "id, name, workspaceId, environment, and storageProvider are required" }, 422);
+  }
+  if (!(await memberOfWorkspace(env, principal, workspaceId, "workspace.write"))) return response({ error: "Workspace scope is not allowed" }, 403);
+  const projectLimit = await checkProjectLimit(env, workspaceId);
+  if (projectLimit) return projectLimit;
+  try {
+    await env.DB.batch([
+      env.DB.prepare(`
+        INSERT INTO projects (id, workspace_id, tenant_id, name, environment, storage_provider, storage_mode, created_at)
+        VALUES (?, ?, ?, ?, ?, ?, ?, CURRENT_TIMESTAMP)
+      `).bind(projectId, workspaceId, workspaceId, name, body.environment.trim(), currentStorageProvider(body.storageProvider), storageModeOf(body.storageProvider)),
+      env.DB.prepare("INSERT INTO project_memberships (project_id, aegis_id, role, status) VALUES (?, ?, 'owner', 'active')")
+        .bind(projectId, principal.aegisId),
+      env.DB.prepare("INSERT INTO project_apps (id, project_id, name, type, is_default) VALUES ('default', ?, ?, 'web', 1)")
+        .bind(projectId, name),
+    ]);
+  } catch {
+    return response({ error: "A project with this id already exists" }, 409);
+  }
+  await auditProject(env, principal, projectId, { action: "project.created", targetType: "project", targetId: projectId }, request);
+  return response({ project: { id: projectId, name, workspaceId, environment: body.environment.trim(), storageProvider: body.storageProvider.trim() } }, 201);
+}
+
+async function updateProject(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "Project editing is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as { name?: string; environment?: string; storageProvider?: string } | null;
+  const name = body?.name?.trim();
+  if (!name || !body?.environment?.trim() || !body.storageProvider?.trim()) {
+    return response({ error: "name, environment, and storageProvider are required" }, 422);
+  }
+  await env.DB.prepare(`
+    UPDATE projects SET name = ?, environment = ?, storage_provider = ?, storage_mode = ? WHERE id = ?
+  `).bind(name, body.environment.trim(), currentStorageProvider(body.storageProvider), storageModeOf(body.storageProvider), projectId).run();
+  await auditProject(env, principal, projectId, { action: "project.updated", targetType: "project", targetId: projectId }, request);
+  return response({ project: { id: projectId, name, environment: body.environment.trim(), storageProvider: body.storageProvider.trim() } });
+}
+
+async function createApiKey(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "keys:write") && !can(principal, "*")) {
+    return response({ error: "API key creation is not allowed" }, 403);
+  }
+  const body = await request.json().catch(() => null) as {
+    name?: string;
+    scopes?: string[];
+    projectIds?: string[];
+    expiresAt?: string | null;
+  } | null;
+  if (!body?.name?.trim()) return response({ error: "name is required" }, 422);
+  const projectIds = body.projectIds ?? [];
+  for (const projectId of projectIds) {
+    if (!(await memberOfProject(env, principal, projectId))) {
+      return response({ error: "Project scope is not allowed" }, 403);
+    }
+  }
+  const id = `key_${randomToken(12)}`;
+  const token = `bm_live_${id}_${randomToken()}`;
+  await env.DB.prepare(`
+    INSERT INTO api_keys (id, aegis_id, name, token_hash, scopes_json, project_ids_json, expires_at)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    id,
+    principal.aegisId,
+    body.name.trim(),
+    await sha256(token),
+    JSON.stringify(body.scopes ?? ["projects:read", "projects:write", "runs:write", "artifacts:write"]),
+    JSON.stringify(projectIds),
+    body.expiresAt ?? null,
+  ).run();
+  for (const projectId of projectIds) await auditProject(env, principal, projectId, { action: "api_key.created", targetType: "api_key", targetId: id }, request);
+  return response({
+    id,
+    name: body.name.trim(),
+    scopes: body.scopes ?? ["projects:read", "projects:write", "runs:write", "artifacts:write"],
+    projectIds,
+    expiresAt: body.expiresAt ?? null,
+    token,
+    warning: "Store this token securely. It will not be shown again.",
+  }, 201);
+}
+
+async function listApiKeys(env: Env, principal: Principal): Promise<Response> {
+  const rows = await env.DB.prepare(`
+    SELECT id, name, scopes_json AS scopes, project_ids_json AS projectIds,
+           expires_at AS expiresAt, created_at AS createdAt, revoked_at AS revokedAt
+    FROM api_keys
+    WHERE aegis_id = ? AND revoked_at IS NULL
+    ORDER BY created_at DESC
+  `).bind(principal.aegisId).all<{
+    id: string;
+    name: string;
+    scopes: string;
+    projectIds: string;
+    expiresAt: string | null;
+    createdAt: string;
+    revokedAt: string | null;
+  }>();
+  return response({
+    keys: rows.results.map((key) => ({
+      id: key.id,
+      name: key.name,
+      scopes: JSON.parse(key.scopes || "[]"),
+      projectIds: JSON.parse(key.projectIds || "[]"),
+      expiresAt: key.expiresAt,
+      createdAt: key.createdAt,
+      revokedAt: key.revokedAt,
+    })),
+  });
+}
+
+async function listProjects(env: Env, principal: Principal): Promise<Response> {
+  const rows = await env.DB.prepare(`
+    SELECT p.id, p.workspace_id AS workspaceId,
+           CASE
+             WHEN w.name LIKE 'tenant_%' OR w.name LIKE 'workspace_%'
+             THEN 'Bugmole workspace'
+             ELSE w.name
+           END AS workspaceName,
+           p.tenant_id AS tenantId, p.name, p.environment,
+           p.storage_provider AS storageProvider, p.storage_mode AS storageMode,
+           p.default_execution_mode AS defaultExecutionMode, p.locked_at AS lockedAt, p.created_at AS createdAt
+    FROM projects p
+    JOIN workspace_memberships wm ON wm.workspace_id = p.workspace_id
+    JOIN workspaces w ON w.id = p.workspace_id
+    WHERE wm.aegis_id = ? AND wm.status = 'active' AND p.deleted_at IS NULL
+    ORDER BY p.created_at DESC
+  `).bind(principal.aegisId).all();
+  const visible = rows.results.filter((project) => projectAllowed(principal, String(project.id)));
+  const projects = await Promise.all(visible.map(async (project) => {
+    const apps = await env.DB.prepare(`
+      SELECT id, name, type, location, is_default AS isDefault
+      FROM project_apps
+      WHERE project_id = ?
+      ORDER BY created_at ASC
+    `).bind(project.id).all<{
+      id: string;
+      name: string;
+      type: string;
+      location: string | null;
+      isDefault: number;
+    }>();
+    const environments = await env.DB.prepare(`
+      SELECT id, app_id AS appId, name, base_url AS baseUrl, api_url AS apiUrl,
+             status, is_default AS isDefault
+      FROM project_environments
+      WHERE project_id = ?
+      ORDER BY is_default DESC, created_at ASC
+    `).bind(project.id).all<{
+      id: string;
+      appId: string;
+      name: string;
+      baseUrl: string;
+      apiUrl: string | null;
+      status: string;
+      isDefault: number;
+    }>();
+    return {
+      ...project,
+      apps: apps.results.map((app) => ({
+        ...app,
+        location: app.location ?? undefined,
+        isDefault: Boolean(app.isDefault),
+      })),
+      environments: environments.results.map((environment) => ({
+        ...environment,
+        apiUrl: environment.apiUrl ?? undefined,
+        isDefault: Boolean(environment.isDefault),
+      })),
+    };
+  }));
+  return response({ projects });
+}
+
+async function createApp(
+  request: Request,
+  env: Env,
+  principal: Principal,
+  projectId: string,
+): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) {
+    return response({ error: "App creation is not allowed" }, 403);
+  }
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) {
+    return response({ error: "Project scope is not allowed" }, 403);
+  }
+  const body = await request.json().catch(() => null) as {
+    id?: string;
+    name?: string;
+    type?: string;
+    location?: string;
+  } | null;
+  const id = body?.id?.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+  if (!id || !body?.name?.trim()) return response({ error: "id and name are required" }, 422);
+  const count = await env.DB.prepare(
+    "SELECT COUNT(*) AS count FROM project_apps WHERE project_id = ?",
+  ).bind(projectId).first<{ count: number }>();
+  try {
+    await env.DB.prepare(`
+      INSERT INTO project_apps (id, project_id, name, type, location, is_default)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).bind(
+      id,
+      projectId,
+      body.name.trim(),
+      body.type?.trim() || "web",
+      body.location?.trim() || null,
+      (count?.count ?? 0) === 0 ? 1 : 0,
+    ).run();
+  } catch {
+    return response({ error: "An app with this id already exists" }, 409);
+  }
+  await auditProject(env, principal, projectId, { action: "app.created", targetType: "app" }, request);
+  return response({
+    app: {
+      id,
+      name: body.name.trim(),
+      type: body.type?.trim() || "web",
+      location: body.location?.trim() || undefined,
+      isDefault: (count?.count ?? 0) === 0,
+    },
+  }, 201);
+}
+
+async function createEnvironment(
+  request: Request,
+  env: Env,
+  principal: Principal,
+  projectId: string,
+): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) {
+    return response({ error: "Environment creation is not allowed" }, 403);
+  }
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) {
+    return response({ error: "Project scope is not allowed" }, 403);
+  }
+  const body = await request.json().catch(() => null) as {
+    id?: string;
+    appId?: string;
+    name?: string;
+    baseUrl?: string;
+    apiUrl?: string;
+  } | null;
+  const id = body?.id?.trim().toLowerCase().replace(/[^a-z0-9-]+/g, "-").replace(/^-|-$/g, "");
+  if (!id || !body?.name?.trim() || !body.baseUrl?.trim()) {
+    return response({ error: "id, name, and baseUrl are required" }, 422);
+  }
+  const appId = body?.appId?.trim() || "default";
+  const app = await env.DB.prepare(
+    "SELECT id FROM project_apps WHERE project_id = ? AND id = ?",
+  ).bind(projectId, appId).first<{ id: string }>();
+  if (!app) return response({ error: "App does not belong to this project" }, 422);
+  try {
+    await env.DB.prepare(`
+      INSERT INTO project_environments (id, project_id, app_id, name, base_url, api_url)
+      VALUES (?, ?, ?, ?, ?, ?)
+    `).bind(id, projectId, appId, body.name.trim(), body.baseUrl.trim(), body.apiUrl?.trim() || null).run();
+  } catch {
+    return response({ error: "An environment with this id already exists" }, 409);
+  }
+  await auditProject(env, principal, projectId, { action: "environment.created", targetType: "environment" }, request);
+  return response({
+    environment: {
+      id,
+      appId,
+      name: body.name.trim(),
+      baseUrl: body.baseUrl.trim(),
+      apiUrl: body.apiUrl?.trim() || undefined,
+      status: "active",
+      isDefault: false,
+    },
+  }, 201);
+}
+
+async function updateApp(request: Request, env: Env, principal: Principal, projectId: string, appId: string): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "App editing is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as { name?: string; type?: string; location?: string } | null ?? {};
+  const name = body?.name?.trim();
+  if (!name) return response({ error: "name is required" }, 422);
+  const result = await env.DB.prepare(`
+    UPDATE project_apps SET name = ?, type = ?, location = ? WHERE project_id = ? AND id = ?
+  `).bind(name, body.type?.trim() || "web", body.location?.trim() || null, projectId, appId).run() as { meta?: { changes?: number } };
+  if (result.meta?.changes !== 1) return response({ error: "App not found" }, 404);
+  await auditProject(env, principal, projectId, { action: "app.updated", targetType: "app", targetId: appId }, request);
+  return response({ app: { id: appId, name, type: body.type?.trim() || "web", location: body.location?.trim() || undefined } });
+}
+
+async function updateEnvironment(
+  request: Request,
+  env: Env,
+  principal: Principal,
+  projectId: string,
+  environmentId: string,
+): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "Environment editing is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await request.json().catch(() => null) as {
+    appId?: string; name?: string; baseUrl?: string; apiUrl?: string; status?: string; isDefault?: boolean;
+  } | null ?? {};
+  const name = body?.name?.trim();
+  const baseUrl = body?.baseUrl?.trim();
+  if (!name || !baseUrl) return response({ error: "name and baseUrl are required" }, 422);
+  if (body.appId?.trim()) {
+    const app = await env.DB.prepare("SELECT id FROM project_apps WHERE project_id = ? AND id = ?")
+      .bind(projectId, body.appId.trim()).first<{ id: string }>();
+    if (!app) return response({ error: "App does not belong to this project" }, 422);
+  }
+  const result = await env.DB.prepare(`
+    UPDATE project_environments
+    SET app_id = COALESCE(?, app_id), name = ?, base_url = ?, api_url = ?, status = COALESCE(?, status),
+        is_default = CASE WHEN ? = 1 THEN 1 ELSE is_default END
+    WHERE project_id = ? AND id = ?
+  `).bind(
+    body.appId?.trim() || null,
+    name,
+    baseUrl,
+    body.apiUrl?.trim() || null,
+    body.status?.trim() || null,
+    body.isDefault === true ? 1 : 0,
+    projectId,
+    environmentId,
+  ).run() as { meta?: { changes?: number } };
+  if (result.meta?.changes !== 1) return response({ error: "Environment not found" }, 404);
+  await auditProject(env, principal, projectId, { action: "environment.updated", targetType: "environment", targetId: environmentId }, request);
+  return response({ environment: { id: environmentId, appId: body.appId, name, baseUrl, apiUrl: body.apiUrl?.trim() || undefined, status: body.status || "active", isDefault: body.isDefault === true } });
+}
+
+async function revokeApiKey(request: Request, env: Env, principal: Principal, keyId: string): Promise<Response> {
+  if (!can(principal, "keys:write") && !can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  const revokedKey = await env.DB.prepare("SELECT project_ids_json AS projectIds FROM api_keys WHERE id = ? AND aegis_id = ?")
+    .bind(keyId, principal.aegisId).first<{ projectIds: string }>();
+  const revokedProjectIds: string[] = revokedKey ? JSON.parse(revokedKey.projectIds || "[]") : [];
+  await env.DB.prepare(`
+    UPDATE api_keys SET revoked_at = CURRENT_TIMESTAMP
+    WHERE id = ? AND aegis_id = ? AND revoked_at IS NULL
+  `).bind(keyId, principal.aegisId).run();
+  for (const projectId of revokedProjectIds) await auditProject(env, principal, projectId, { action: "api_key.revoked", targetType: "api_key", targetId: keyId }, request);
+  return response({ revoked: true, id: keyId });
+}
+
+async function requestJson(request: Request): Promise<Record<string, unknown> | null> {
+  return await request.json().catch(() => null) as Record<string, unknown> | null;
+}
+
+function id(prefix: string): string {
+  return `${prefix}_${randomToken(12)}`;
+}
+
+async function listPlanDrafts(env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, plan_id AS planId, journey_id AS journeyId,
+           object_key AS objectKey, status, created_by AS createdBy,
+           created_at AS createdAt, updated_at AS updatedAt
+    FROM plan_drafts WHERE project_id = ? ORDER BY updated_at DESC
+  `).bind(projectId).all();
+  return response({ plans: rows.results });
+}
+
+async function publishPlanDraft(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Plan publication is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(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) return response({ error: "planId, journeyId, and objectKey are required" }, 422);
+  const project = await env.DB.prepare("SELECT tenant_id AS tenantId FROM projects WHERE id = ?")
+    .bind(projectId).first<{ tenantId: string }>();
+  if (!project) return response({ error: "Project not found" }, 404);
+  const draftId = id("plan");
+  await env.DB.prepare(`
+    INSERT INTO plan_drafts (id, project_id, tenant_id, plan_id, journey_id, object_key, created_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(project_id, plan_id) DO UPDATE SET journey_id = excluded.journey_id,
+      object_key = excluded.object_key, status = 'draft', updated_at = CURRENT_TIMESTAMP
+  `).bind(draftId, projectId, project.tenantId, planId, journeyId, objectKey, principal.aegisId).run();
+  const plan = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, plan_id AS planId, journey_id AS journeyId,
+           object_key AS objectKey, status, created_by AS createdBy,
+           created_at AS createdAt, updated_at AS updatedAt
+    FROM plan_drafts WHERE project_id = ? AND plan_id = ?
+  `).bind(projectId, planId).first();
+  return response({ plan }, 201);
+}
+
+// Mirrors src/runtime/browser-matrix.ts. The Worker can't import Playwright,
+// so device names are only shape-checked here; the runtime validates them
+// against Playwright's device list and reports an unknown one as a run error.
+const RUN_BROWSERS = new Set(["chromium", "firefox", "webkit", "msedge"]);
+const MAX_RUN_TARGETS = 12;
+const MAX_TARGET_RESULTS_BYTES = 64 * 1024;
+const TERMINAL_RUN_STATUSES = new Set(["success", "partial", "error", "cancelled"]);
+
+type BrowserRunTarget = { browser: string; device?: string };
+type RunTargetRecord = BrowserRunTarget | ({ kind: "device" } & CloudDevice);
+
+function validateRunTargets(input: unknown): { targets: RunTargetRecord[] } | { error: string } {
+  if (input === undefined || input === null) return { targets: [] };
+  if (!Array.isArray(input)) return { error: "targets must be an array of { browser, device? } or device-cloud targets" };
+  const seen = new Set<string>();
+  const targets: RunTargetRecord[] = [];
+  for (const raw of input as Array<Record<string, unknown>>) {
+    if (raw?.kind === "device") {
+      let cloud: CloudDevice;
+      try {
+        cloud = parseCloudDevice(raw);
+      } catch (error) {
+        return { error: error instanceof Error ? error.message : "Invalid device target" };
+      }
+      const key = cloudTargetId(cloud);
+      if (seen.has(key)) continue;
+      seen.add(key);
+      targets.push({ kind: "device", ...cloud });
+      continue;
+    }
+    const browser = raw?.browser;
+    if (typeof browser !== "string" || !RUN_BROWSERS.has(browser)) {
+      return { error: `Unsupported browser "${String(browser)}". Use one of: ${[...RUN_BROWSERS].join(", ")}.` };
+    }
+    const device = raw.device;
+    if (device !== undefined && device !== null && device !== "") {
+      if (typeof device !== "string" || !/^[A-Za-z0-9 ()+.,-]{1,48}$/.test(device)) {
+        return { error: `Invalid device "${String(device)}".` };
+      }
+    }
+    const key = `${browser}|${device || ""}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    targets.push(typeof device === "string" && device ? { browser, device } : { browser });
+  }
+  if (targets.length > MAX_RUN_TARGETS) return { error: `A run can target at most ${MAX_RUN_TARGETS} browser/device combinations.` };
+  return { targets };
+}
+
+function parseJsonColumn(value: unknown): unknown {
+  if (typeof value !== "string" || !value) return null;
+  try {
+    return JSON.parse(value);
+  } catch {
+    return null;
+  }
+}
+
+function hydrateRun<T extends Record<string, unknown>>(row: T) {
+  const { targetsJson, targetResultsJson, fixFromJson, ...rest } = row as Record<string, unknown>;
+  const started = typeof rest.startedAt === "string" ? Date.parse(`${rest.startedAt.replace(" ", "T")}Z`) : NaN;
+  const completed = typeof rest.completedAt === "string" ? Date.parse(`${rest.completedAt.replace(" ", "T")}Z`) : NaN;
+  return {
+    ...rest,
+    targets: parseJsonColumn(targetsJson),
+    targetResults: parseJsonColumn(targetResultsJson),
+    fixFrom: parseJsonColumn(fixFromJson),
+    durationMs: Number.isFinite(started) && Number.isFinite(completed) ? Math.max(0, completed - started) : null,
+  };
+}
+
+async function listRuns(env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const cutoff = await historyCutoffFor(env, await workspaceOfProject(env, projectId));
+  const rows = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, plan_id AS planId, journey_id AS journeyId,
+           environment_id AS environmentId, status, worker_id AS workerId,
+           journey_revision AS journeyRevision,
+           current_step AS currentStep, steps_executed AS stepsExecuted,
+           steps_passed AS stepsPassed, steps_failed AS stepsFailed,
+           driver, platform, recovery_attempts AS recoveryAttempts,
+           failure_code AS failureCode, artifact_summary_json AS artifactSummaryJson,
+           error_code AS errorCode, error_message AS errorMessage,
+           manifest_key AS manifestKey, requested_at AS requestedAt,
+           started_at AS startedAt, completed_at AS completedAt,
+           targets_json AS targetsJson, environment_base_url AS environmentBaseUrl,
+           target_results_json AS targetResultsJson, fix_from_json AS fixFromJson,
+           execution_mode AS executionMode, blocked_reason AS blockedReason, billed_minutes AS billedMinutes,
+           trigger_source AS triggerSource, repo_full_name AS repoFullName, commit_sha AS commitSha, pr_number AS prNumber,
+           gitlab_binding_id AS gitlabBindingId
+    FROM runs
+    WHERE project_id = ? AND (? IS NULL OR COALESCE(completed_at, requested_at) >= ? OR status NOT IN ('success', 'partial', 'error', 'cancelled'))
+    ORDER BY requested_at DESC LIMIT 100
+  `).bind(projectId, cutoff, cutoff).all<Record<string, unknown>>();
+  return response({ runs: rows.results.map(hydrateRun) });
+}
+
+async function createRun(request: Request, env: Env, principal: Principal, projectId: string, ctx: ExecutionContext, internal: InternalRunFields = {}): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Run creation is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request);
+  const planId = typeof body?.planId === "string" ? body.planId.trim() : "";
+  const idempotencyKey = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+  if (!planId || !idempotencyKey) return response({ error: "planId and idempotencyKey are required" }, 422);
+  const draft = await env.DB.prepare(`
+    SELECT journey_id AS journeyId FROM plan_drafts WHERE project_id = ? AND plan_id = ?
+  `).bind(projectId, planId).first<{ journeyId: string }>();
+  if (!draft) return response({ error: "Plan draft not found" }, 404);
+  const existing = await env.DB.prepare(`
+    SELECT id, status FROM runs WHERE project_id = ? AND idempotency_key = ?
+  `).bind(projectId, idempotencyKey).first();
+  if (existing) return response({ run: existing }, 200);
+  const matrix = validateRunTargets(body?.targets);
+  if ("error" in matrix) return response({ error: matrix.error }, 422);
+  const deviceTargets = matrix.targets.filter((target): target is { kind: "device" } & CloudDevice => "kind" in target);
+  const executionMode = executionModeOf(body?.executionMode);
+  if (!executionMode) return response({ error: "executionMode must be self or cloud" }, 422);
+  const runWorkspaceId = await workspaceOfProject(env, projectId);
+  if (executionMode === "cloud") {
+    if (!runWorkspaceId) return response({ error: "This project isn't in a workspace" }, 422);
+    const storageProblem = await cloudStorageError(env, projectId);
+    if (storageProblem) return storageProblem;
+    const accountProblem = await cloudAccountError(env, principal, runWorkspaceId);
+    if (accountProblem) return accountProblem;
+    const blocked = await checkCloudRun(env, runWorkspaceId);
+    if (blocked) return blocked;
+  }
+  if (deviceTargets.length) {
+    const deviceProblem = await deviceTargetsError(env, projectId, runWorkspaceId, deviceTargets, executionMode);
+    if (deviceProblem) return deviceProblem;
+  }
+  const environmentId = typeof body?.environmentId === "string" && body.environmentId.trim() ? body.environmentId.trim() : null;
+  let environmentBaseUrl: string | null = null;
+  if (environmentId) {
+    const environment = await env.DB.prepare(`
+      SELECT base_url AS baseUrl FROM project_environments WHERE project_id = ? AND id = ?
+    `).bind(projectId, environmentId).first<{ baseUrl: string | null }>();
+    if (!environment) return response({ error: "Environment not found in this project" }, 422);
+    environmentBaseUrl = internal.environmentBaseUrl ?? (environment.baseUrl?.trim() || null);
+    if (!environmentBaseUrl) {
+      return response({ error: "Environment has no base URL — set one in Manage → Environments", code: "environment_base_url_missing" }, 422);
+    }
+    // Only when the environment's own URL is what's being used: a person
+    // chose it. internal.environmentBaseUrl (GitHub PR preview runs) comes
+    // from a repo binding an admin already configured, so it isn't gated
+    // again here.
+    if (executionMode === "cloud" && runWorkspaceId && !internal.environmentBaseUrl) {
+      const domainProblem = await requireVerifiedDomainForCloud(env, runWorkspaceId, environmentBaseUrl);
+      if (domainProblem) return domainProblem;
+    }
+  }
+  let fixFrom: { runId: string; targetId: string; mode?: "ai" } | null = null;
+  if (body?.fixFrom !== undefined && body?.fixFrom !== null) {
+    const source = body.fixFrom as Record<string, unknown>;
+    const sourceRunId = typeof source.runId === "string" ? source.runId : "";
+    const targetId = typeof source.targetId === "string" ? source.targetId : "";
+    if (!/^[a-z0-9-]{1,60}$/.test(targetId)) return response({ error: "fixFrom.targetId is invalid" }, 422);
+    const sourceRun = await env.DB.prepare("SELECT plan_id AS planId FROM runs WHERE id = ? AND project_id = ?")
+      .bind(sourceRunId, projectId).first<{ planId: string }>();
+    if (!sourceRun) return response({ error: "The run to take the fix from was not found in this project" }, 422);
+    if (sourceRun.planId !== planId) return response({ error: "A fix can only be applied to the plan it was suggested for" }, 422);
+    if (source.mode !== undefined && source.mode !== "suggested" && source.mode !== "ai") {
+      return response({ error: "fixFrom.mode must be suggested or ai" }, 422);
+    }
+    fixFrom = { runId: sourceRunId, targetId, ...(source.mode === "ai" ? { mode: "ai" as const } : {}) };
+  }
+  const project = await env.DB.prepare("SELECT tenant_id AS tenantId FROM projects WHERE id = ?")
+    .bind(projectId).first<{ tenantId: string }>();
+  if (!environmentId && internal.environmentBaseUrl) environmentBaseUrl = internal.environmentBaseUrl;
+  const runId = id("run");
+  const targets = matrix.targets.length > 0 ? matrix.targets : null;
+  await env.DB.prepare(`
+    INSERT INTO runs (id, project_id, tenant_id, plan_id, journey_id, journey_revision, environment_id, requested_by, idempotency_key, driver, platform, targets_json, environment_base_url, fix_from_json, execution_mode, workspace_id,
+      trigger_source, repo_full_name, commit_sha, pr_number, github_installation_id, gitlab_binding_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    runId, projectId, project?.tenantId ?? `tenant_${principal.aegisId}`, planId, draft.journeyId,
+    Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+    environmentId, principal.aegisId, idempotencyKey,
+    typeof body?.driver === "string" ? body.driver : "maestro",
+    typeof body?.platform === "string" ? body.platform : null,
+    targets ? JSON.stringify(targets) : null,
+    environmentBaseUrl,
+    fixFrom ? JSON.stringify(fixFrom) : null,
+    executionMode,
+    runWorkspaceId,
+    internal.triggerSource ?? null,
+    internal.repoFullName ?? null,
+    internal.commitSha ?? null,
+    internal.prNumber ?? null,
+    internal.githubInstallationId ?? null,
+    internal.gitlabBindingId ?? null,
+  ).run();
+  await appendRunEvent(env, runId, "queued", { status: "queued", targets, environmentBaseUrl, executionMode });
+  await broadcastProjectEvent(env, projectId, { type: "job_queued", runId, projectId, planId, executionMode });
+  for (const hook of runQueuedHooks) ctx.waitUntil(hook(env, { runId, projectId, workspaceId: runWorkspaceId, executionMode }));
+  await auditProject(env, principal, projectId, { action: "run.created", targetType: "run", targetId: runId, data: { planId } }, request);
+  return response({
+    run: {
+      id: runId, projectId, planId, journeyId: draft.journeyId, status: "queued", executionMode,
+      environmentId, environmentBaseUrl, targets, targetResults: null, durationMs: null, fixFrom,
+    },
+  }, 201);
+}
+
+async function getRun(env: Env, principal: Principal, runId: string): Promise<Response> {
+  const run = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, plan_id AS planId, journey_id AS journeyId,
+           environment_id AS environmentId, status, worker_id AS workerId,
+           current_step AS currentStep, steps_executed AS stepsExecuted,
+           steps_passed AS stepsPassed, steps_failed AS stepsFailed,
+           driver, platform, recovery_attempts AS recoveryAttempts,
+           failure_code AS failureCode, artifact_summary_json AS artifactSummaryJson,
+           error_code AS errorCode, error_message AS errorMessage,
+           manifest_key AS manifestKey, requested_at AS requestedAt,
+           started_at AS startedAt, completed_at AS completedAt,
+           targets_json AS targetsJson, environment_base_url AS environmentBaseUrl,
+           target_results_json AS targetResultsJson, fix_from_json AS fixFromJson,
+           execution_mode AS executionMode, blocked_reason AS blockedReason, billed_minutes AS billedMinutes
+    FROM runs WHERE id = ?
+  `).bind(runId).first<{ projectId: string } & Record<string, unknown>>();
+  if (!run || !(await memberOfProject(env, principal, run.projectId))) return response({ error: "Run not found" }, 404);
+  const events = await env.DB.prepare(`
+    SELECT sequence, type, payload_json AS payload, created_at AS createdAt
+    FROM run_events WHERE run_id = ? ORDER BY sequence ASC
+  `).bind(runId).all<{ sequence: number; type: string; payload: string; createdAt: string }>();
+  return response({ run: hydrateRun(run), events: events.results.map((event) => ({ ...event, payload: JSON.parse(event.payload) })) });
+}
+
+async function claimRun(request: Request, env: Env, principal: Principal, runId: string, ctx: ExecutionContext): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Run claim is not allowed" }, 403);
+  const body = await requestJson(request);
+  const workerId = typeof body?.workerId === "string" ? body.workerId.trim() : "";
+  if (!workerId) return response({ error: "workerId is required" }, 422);
+  const run = await env.DB.prepare(`
+    SELECT project_id AS projectId, targets_json AS targetsJson, environment_base_url AS environmentBaseUrl,
+           fix_from_json AS fixFromJson, execution_mode AS executionMode, workspace_id AS workspaceId, status
+    FROM runs WHERE id = ?
+  `).bind(runId).first<{ projectId: string; targetsJson: string | null; environmentBaseUrl: string | null; fixFromJson: string | null; executionMode: string; workspaceId: string | null; status: string }>();
+  if (!run || !(await memberOfProject(env, principal, run.projectId, "project.write"))) return response({ error: "Run not found" }, 404);
+  // Bugmole Cloud runs are billed; only Bugmole's own runners may take them.
+  if (run.executionMode === "cloud") return response({ error: "This run is queued for Bugmole Cloud" }, 409);
+  const lease = new Date(Date.now() + 60_000).toISOString();
+  const claimed = await env.DB.prepare(`
+    UPDATE runs SET status = 'running', worker_id = ?, lease_expires_at = ?,
+      heartbeat_at = CURRENT_TIMESTAMP, started_at = COALESCE(started_at, CURRENT_TIMESTAMP)
+    WHERE id = ? AND (status = 'queued' OR (status = 'running' AND lease_expires_at < strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))
+  `).bind(workerId, lease, runId).run() as { meta?: { changes?: number } };
+  if (claimed.meta?.changes !== 1) return response({ error: "Run is already claimed or complete" }, 409);
+  await appendRunEvent(env, runId, "running", { status: "running", workerId });
+  await broadcastProjectEvent(env, run.projectId, { type: "run_event", runId, eventType: "running", status: "running" });
+  if (run.status !== "running") {
+    const event = {
+      runId, projectId: run.projectId, workspaceId: run.workspaceId, executionMode: run.executionMode,
+      status: "running", previousStatus: run.status, terminal: false,
+    };
+    for (const hook of runChangedHooks) ctx.waitUntil(hook(env, event));
+  }
+  return response({
+    claimed: true,
+    leaseExpiresAt: lease,
+    environmentBaseUrl: run.environmentBaseUrl,
+    targets: parseJsonColumn(run.targetsJson),
+    fixFrom: parseJsonColumn(run.fixFromJson),
+  });
+}
+
+async function updateRun(request: Request, env: Env, principal: Principal, runId: string, ctx: ExecutionContext): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Run update is not allowed" }, 403);
+  const body = await requestJson(request);
+  const run = await env.DB.prepare(`
+    SELECT project_id AS projectId, worker_id AS workerId, status, execution_mode AS executionMode, workspace_id AS workspaceId
+    FROM runs WHERE id = ?
+  `).bind(runId).first<{ projectId: string; workerId: string | null; status: string; executionMode: string; workspaceId: string | null }>();
+  if (!run || !(await memberOfProject(env, principal, run.projectId, "project.write"))) return response({ error: "Run not found" }, 404);
+  if (run.workerId && body?.workerId !== run.workerId) return response({ error: "Worker lease does not match" }, 409);
+  const status = typeof body?.status === "string" ? body.status : "running";
+  // A late progress tick or heartbeat (a browser lane still reporting after
+  // the run was finalized) must not turn a finished run back into a running one.
+  if (TERMINAL_RUN_STATUSES.has(run.status) && !TERMINAL_RUN_STATUSES.has(status)) {
+    return response({ error: "Run already finished" }, 409);
+  }
+  const manifestKey = body?.manifestKey;
+  let targetResultsJson: string | null = null;
+  if (Array.isArray(body?.targetResults)) {
+    const serialized = JSON.stringify(body.targetResults);
+    if (serialized.length <= MAX_TARGET_RESULTS_BYTES) targetResultsJson = serialized;
+  }
+  await env.DB.prepare(`
+    UPDATE runs SET status = ?, heartbeat_at = CURRENT_TIMESTAMP,
+      lease_expires_at = ?, current_step = ?, steps_executed = ?, steps_passed = ?,
+      steps_failed = ?, error_code = ?, error_message = ?,
+      driver = COALESCE(?, driver), platform = COALESCE(?, platform),
+      recovery_attempts = COALESCE(?, recovery_attempts),
+      failure_code = COALESCE(?, failure_code), artifact_summary_json = COALESCE(?, artifact_summary_json),
+      manifest_key = COALESCE(?, manifest_key),
+      target_results_json = COALESCE(?, target_results_json),
+      completed_at = CASE WHEN ? IN ('success', 'partial', 'error', 'cancelled') THEN CURRENT_TIMESTAMP ELSE completed_at END
+    WHERE id = ?
+  `).bind(
+    status, new Date(Date.now() + 60_000).toISOString(),
+    typeof body?.currentStep === "string" ? body.currentStep : null,
+    Number(body?.stepsExecuted ?? 0), Number(body?.stepsPassed ?? 0), Number(body?.stepsFailed ?? 0),
+    typeof body?.errorCode === "string" ? body.errorCode : null,
+    typeof body?.errorMessage === "string" ? body.errorMessage : null,
+    typeof body?.driver === "string" ? body.driver : null,
+    typeof body?.platform === "string" ? body.platform : null,
+    Number.isFinite(Number(body?.recoveryAttempts)) ? Number(body?.recoveryAttempts) : null,
+    typeof body?.failureCode === "string" ? body.failureCode : null,
+    typeof body?.artifactSummaryJson === "string" ? body.artifactSummaryJson : null,
+    isRunManifestKey(run.projectId, runId, manifestKey) ? manifestKey : null,
+    targetResultsJson,
+    status, runId,
+  ).run();
+  await appendRunEvent(env, runId, typeof body?.eventType === "string" ? body.eventType : status, body);
+  await broadcastProjectEvent(env, run.projectId, {
+    type: "run_event",
+    runId,
+    eventType: typeof body?.eventType === "string" ? body.eventType : status,
+    ...body,
+  });
+  if (status !== run.status) {
+    const event = {
+      runId, projectId: run.projectId, workspaceId: run.workspaceId, executionMode: run.executionMode,
+      status, previousStatus: run.status, terminal: TERMINAL_RUN_STATUSES.has(status),
+    };
+    for (const hook of runChangedHooks) ctx.waitUntil(hook(env, event));
+  }
+  if (!TERMINAL_RUN_STATUSES.has(status)) {
+    for (const check of heartbeatChecks) {
+      const stop = await check(env, { kind: "run", id: runId, projectId: run.projectId, workspaceId: run.workspaceId, executionMode: run.executionMode });
+      if (stop) return response({ updated: true, stop: true, reason: stop.reason, message: stop.message });
+    }
+  }
+  return response({ updated: true });
+}
+
+const taskSelect = `
+  SELECT id, project_id AS projectId, title, description, task_type AS taskType,
+         priority, status, requested_by AS requestedBy, worker_id AS workerId,
+         lease_expires_at AS leaseExpiresAt, heartbeat_at AS heartbeatAt,
+         progress_message AS progressMessage, continuation_json AS continuation,
+         baseline_match_score AS baselineMatchScore, parity_match_score AS parityMatchScore,
+         parity_audit_id AS parityAuditId, completion_summary AS completionSummary,
+         changed_files_json AS changedFiles, error_message AS errorMessage,
+         journey_id AS journeyId, journey_revision AS journeyRevision, step_id AS stepId,
+         idempotency_key AS idempotencyKey, requested_at AS requestedAt,
+         started_at AS startedAt, completed_at AS completedAt, device_session_id AS deviceSessionId,
+         attempts, next_attempt_at AS nextAttemptAt,
+         execution_mode AS executionMode, billed_minutes AS billedMinutes
+  FROM agent_tasks
+`;
+
+
+async function listAgentTasks(env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`${taskSelect} WHERE project_id = ? ORDER BY priority DESC, requested_at ASC LIMIT 100`)
+    .bind(projectId).all();
+  return response({ tasks: rows.results });
+}
+
+function extractDiscoveryUrl(description: string): string | null {
+  const match = /https?:\/\/[^\s"'<>]+/.exec(description);
+  if (!match) return null;
+  try {
+    return /^https?:$/.test(new URL(match[0]).protocol) ? match[0] : null;
+  } catch {
+    return null;
+  }
+}
+
+function validDiscoveryUrl(description: string): boolean {
+  return extractDiscoveryUrl(description) !== null;
+}
+
+/**
+ * A project's default environment can sit with no base_url at all — created
+ * empty by the CLI's device-pairing flow (migration 0003 / index.ts's
+ * claim-device inserts), or not created at all by createManagedProject — and
+ * nothing has ever filled it in since. A discovery run against a project
+ * with no configured URL yet is the one moment we know what that URL should
+ * be, so use it: fill an empty default environment, or create one if the
+ * project doesn't have one yet. Either way, only into the gap — an
+ * environment a human already pointed somewhere (including at something
+ * else) is never touched.
+ */
+async function fillDiscoveredEnvironmentUrl(env: Env, projectId: string, description: string | null): Promise<void> {
+  const discovered = description && extractDiscoveryUrl(description);
+  if (!discovered) return;
+  const origin = new URL(discovered).origin;
+  const existing = await env.DB.prepare(
+    "SELECT id, base_url AS baseUrl FROM project_environments WHERE project_id = ? AND is_default = 1",
+  ).bind(projectId).first<{ id: string; baseUrl: string }>();
+  if (existing) {
+    if (existing.baseUrl) return;
+    await env.DB.prepare("UPDATE project_environments SET base_url = ? WHERE project_id = ? AND id = ?")
+      .bind(origin, projectId, existing.id).run();
+    return;
+  }
+  const app = await env.DB.prepare("SELECT id FROM project_apps WHERE project_id = ? AND is_default = 1")
+    .bind(projectId).first<{ id: string }>();
+  if (!app) return;
+  await env.DB.prepare(`
+    INSERT INTO project_environments (id, project_id, app_id, name, base_url, status, is_default)
+    VALUES ('default', ?, ?, 'Production', ?, 'active', 1)
+  `).bind(projectId, app.id, origin).run();
+}
+
+async function createAgentTask(request: Request, env: Env, principal: Principal, projectId: string, ctx: ExecutionContext): Promise<Response> {
+  if (!can(principal, "tasks:write") && !can(principal, "projects:write") && !can(principal, "*")) {
+    return response({ error: "Task creation is not allowed" }, 403);
+  }
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request) as {
+    title?: string; description?: string; taskType?: string; idempotencyKey?: string; priority?: number;
+    journeyId?: string; journeyRevision?: number; deviceSessionId?: string; stepId?: string;
+  } | null;
+  const title = typeof body?.title === "string" ? body.title.trim() : "";
+  const description = typeof body?.description === "string" ? body.description.trim() : "";
+  const taskType = body?.taskType && ["code", "ui", "investigation", "discovery"].includes(body.taskType) ? body.taskType : "code";
+  const idempotencyKey = typeof body?.idempotencyKey === "string" ? body.idempotencyKey.trim() : "";
+  if (!title || !description || !idempotencyKey) return response({ error: "title, description, and idempotencyKey are required" }, 422);
+  // A worker opens this URL in a browser, so only a real http(s) address is accepted.
+  if (taskType === "discovery" && !validDiscoveryUrl(description)) {
+    return response({ error: "Discovery needs an http(s) URL to explore" }, 422);
+  }
+  const executionMode = executionModeOf((body as { executionMode?: unknown } | null)?.executionMode);
+  if (!executionMode) return response({ error: "executionMode must be self or cloud" }, 422);
+  const taskWorkspaceId = await workspaceOfProject(env, projectId);
+  if (executionMode === "cloud") {
+    // Coding-agent tasks need the customer's own agent; only discovery runs in the cloud.
+    if (taskType !== "discovery") return response({ error: "Only discovery can run on Bugmole Cloud" }, 422);
+    if (!taskWorkspaceId) return response({ error: "This project isn't in a workspace" }, 422);
+    const storageProblem = await cloudStorageError(env, projectId);
+    if (storageProblem) return storageProblem;
+    const accountProblem = await cloudAccountError(env, principal, taskWorkspaceId);
+    if (accountProblem) return accountProblem;
+    const blocked = await checkCloudRun(env, taskWorkspaceId);
+    if (blocked) return blocked;
+    const discoveryUrl = extractDiscoveryUrl(description);
+    if (discoveryUrl) {
+      const domainProblem = await requireVerifiedDomainForCloud(env, taskWorkspaceId, discoveryUrl);
+      if (domainProblem) return domainProblem;
+    }
+  }
+  const queued = (taskId: string) => {
+    for (const hook of taskQueuedHooks) ctx.waitUntil(hook(env, { taskId, projectId, workspaceId: taskWorkspaceId, executionMode }));
+  };
+  const existing = await env.DB.prepare(`${taskSelect} WHERE project_id = ? AND idempotency_key = ?`)
+    .bind(projectId, idempotencyKey).first<{ id: string; status: string }>();
+  if (existing && !["completed", "error"].includes(existing.status)) return response({ task: existing }, 200);
+  if (existing) {
+    // The UNIQUE(project_id, idempotency_key) constraint means a finished
+    // (completed/error, including a manually cancelled) task can't simply
+    // be superseded by a new INSERT under the same key — without this, a
+    // cancelled task would keep being returned as "the" task forever,
+    // making retry impossible. Recycle the row into a fresh attempt instead.
+    await env.DB.prepare(`
+      UPDATE agent_tasks SET title = ?, description = ?, task_type = ?, priority = ?, status = 'queued',
+        worker_id = NULL, lease_expires_at = NULL, heartbeat_at = NULL, progress_message = NULL,
+        continuation_json = NULL, completion_summary = NULL, changed_files_json = NULL, error_message = NULL,
+        journey_id = ?, journey_revision = ?, device_session_id = ?, step_id = ?,
+        attempts = 0, next_attempt_at = NULL,
+        execution_mode = ?, workspace_id = ?, claimed_at = NULL, billed_at = NULL, billed_minutes = NULL,
+        blocked_reason = NULL, dispatch_attempts = 0, next_dispatch_at = NULL,
+        requested_at = CURRENT_TIMESTAMP, started_at = NULL, completed_at = NULL
+      WHERE id = ?
+    `).bind(
+      title, description, taskType,
+      Number.isFinite(Number(body?.priority)) ? Number(body?.priority) : 0,
+      body?.journeyId ?? null, Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+      typeof body?.deviceSessionId === "string" ? body.deviceSessionId : null,
+      typeof body?.stepId === "string" ? body.stepId : null,
+      executionMode, taskWorkspaceId,
+      existing.id,
+    ).run();
+    await broadcastProjectEvent(env, projectId, { type: "task_event", taskId: existing.id, projectId, status: "queued" });
+    queued(existing.id);
+    return response({ task: await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(existing.id).first() }, 200);
+  }
+  const project = await env.DB.prepare("SELECT tenant_id AS tenantId FROM projects WHERE id = ?")
+    .bind(projectId).first<{ tenantId: string }>();
+  const taskId = id("task");
+  await env.DB.prepare(`
+    INSERT INTO agent_tasks
+      (id, project_id, tenant_id, title, description, task_type, priority, requested_by, idempotency_key, journey_id, journey_revision, device_session_id, step_id, execution_mode, workspace_id)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    taskId, projectId, project?.tenantId ?? `tenant_${principal.aegisId}`, title, description, taskType,
+    Number.isFinite(Number(body?.priority)) ? Number(body?.priority) : 0, principal.aegisId, idempotencyKey,
+    body?.journeyId ?? null, Number.isFinite(Number(body?.journeyRevision)) ? Number(body?.journeyRevision) : null,
+    typeof body?.deviceSessionId === "string" ? body.deviceSessionId : null,
+    typeof body?.stepId === "string" ? body.stepId : null,
+    executionMode, taskWorkspaceId,
+  ).run();
+  await broadcastProjectEvent(env, projectId, { type: "task_event", taskId, projectId, status: "queued" });
+  queued(taskId);
+  const task = await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(taskId).first();
+  return response({ task }, 201);
+}
+
+async function claimAgentTask(request: Request, env: Env, principal: Principal, taskId: string): Promise<Response> {
+  if (!can(principal, "tasks:write") && !can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Task claim is not allowed" }, 403);
+  const body = await requestJson(request);
+  const workerId = typeof body?.workerId === "string" ? body.workerId.trim() : "";
+  if (!workerId) return response({ error: "workerId is required" }, 422);
+  const task = await env.DB.prepare("SELECT project_id AS projectId, execution_mode AS executionMode FROM agent_tasks WHERE id = ?")
+    .bind(taskId).first<{ projectId: string; executionMode: string }>();
+  if (!task || !(await memberOfProject(env, principal, task.projectId, "project.write"))) return response({ error: "Task not found" }, 404);
+  if (task.executionMode === "cloud") return response({ error: "This task is queued for Bugmole Cloud" }, 409);
+  const lease = new Date(Date.now() + 60_000).toISOString();
+  const deviceSessionId = typeof body?.deviceSessionId === "string" ? body.deviceSessionId : null;
+  // Claiming is what counts as an attempt: it's the only point both the
+  // worker and an agent-driven claim pass through, so the cap can't be
+  // sidestepped by whichever path picks the task up.
+  const claimed = await env.DB.prepare(`
+    UPDATE agent_tasks SET status = 'running', worker_id = ?, lease_expires_at = ?,
+      heartbeat_at = CURRENT_TIMESTAMP, started_at = COALESCE(started_at, CURRENT_TIMESTAMP),
+      device_session_id = COALESCE(device_session_id, ?),
+      attempts = attempts + 1
+    WHERE id = ? AND attempts < ${MAX_TASK_ATTEMPTS}
+      AND (next_attempt_at IS NULL OR next_attempt_at <= strftime('%Y-%m-%dT%H:%M:%fZ', 'now'))
+      AND (status = 'queued' OR status = 'blocked' OR (status = 'running' AND lease_expires_at < strftime('%Y-%m-%dT%H:%M:%fZ', 'now')))
+  `).bind(workerId, lease, deviceSessionId, taskId).run() as { meta?: { changes?: number } };
+  if (claimed.meta?.changes !== 1) {
+    return response({ error: "Task is already claimed, complete, or has exhausted its attempts" }, 409);
+  }
+  await broadcastProjectEvent(env, task.projectId, { type: "task_event", taskId, projectId: task.projectId, status: "running", workerId });
+  return response({ claimed: true, leaseExpiresAt: lease, task: await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(taskId).first() });
+}
+
+async function updateAgentTask(request: Request, env: Env, principal: Principal, taskId: string, ctx: ExecutionContext): Promise<Response> {
+  if (!can(principal, "tasks:write") && !can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Task update is not allowed" }, 403);
+  const body = await requestJson(request);
+  const task = await env.DB.prepare(`
+    SELECT project_id AS projectId, worker_id AS workerId, task_type AS taskType, attempts, status,
+           execution_mode AS executionMode, workspace_id AS workspaceId, description
+    FROM agent_tasks WHERE id = ?
+  `).bind(taskId).first<{ projectId: string; workerId: string | null; taskType: string; attempts: number; status: string; executionMode: string; workspaceId: string | null; description: string | null }>();
+  if (!task || !(await memberOfProject(env, principal, task.projectId, "project.write"))) return response({ error: "Task not found" }, 404);
+  if (task.workerId && body?.workerId !== task.workerId) return response({ error: "Worker lease does not match" }, 409);
+  const status = typeof body?.status === "string" ? body.status : "running";
+  if (!["running", "blocked", "completed", "error"].includes(status)) return response({ error: "Invalid task status" }, 422);
+  if (status === "completed" && task.taskType === "ui" && (!body?.parityAuditId || typeof body?.parityMatchScore !== "number")) {
+    return response({ error: "UI tasks require parityAuditId and parityMatchScore before completion" }, 422);
+  }
+  // Falling back to blocked schedules the next attempt rather than making
+  // the task immediately eligible again on the worker's next 5s poll.
+  const nextAttemptAt = status === "blocked" ? backoffUntil(task.attempts ?? 0) : null;
+  await env.DB.prepare(`
+    UPDATE agent_tasks SET status = ?, heartbeat_at = CURRENT_TIMESTAMP, lease_expires_at = ?,
+      progress_message = ?, continuation_json = ?, parity_match_score = ?, parity_audit_id = ?,
+      completion_summary = ?, changed_files_json = ?, error_message = ?,
+      next_attempt_at = ?,
+      completed_at = CASE WHEN ? IN ('completed', 'error') THEN CURRENT_TIMESTAMP ELSE completed_at END
+    WHERE id = ?
+  `).bind(
+    status, new Date(Date.now() + 60_000).toISOString(),
+    typeof body?.progressMessage === "string" ? body.progressMessage : null,
+    body?.continuation ? JSON.stringify(body.continuation) : null,
+    typeof body?.parityMatchScore === "number" ? body.parityMatchScore : null,
+    typeof body?.parityAuditId === "string" ? body.parityAuditId : null,
+    typeof body?.completionSummary === "string" ? body.completionSummary : null,
+    Array.isArray(body?.changedFiles) ? JSON.stringify(body.changedFiles) : null,
+    typeof body?.errorMessage === "string" ? body.errorMessage : null,
+    nextAttemptAt, status, taskId,
+  ).run();
+  if (status === "completed" && task.taskType === "discovery") {
+    await fillDiscoveredEnvironmentUrl(env, task.projectId, task.description);
+  }
+  await broadcastProjectEvent(env, task.projectId, { type: "task_event", taskId, projectId: task.projectId, status, ...body });
+  const terminal = status === "completed" || status === "error";
+  if (status !== task.status) {
+    const event = {
+      taskId, projectId: task.projectId, workspaceId: task.workspaceId, executionMode: task.executionMode,
+      status, previousStatus: task.status, terminal,
+    };
+    for (const hook of taskChangedHooks) ctx.waitUntil(hook(env, event));
+  }
+  let stop: { reason: string; message: string } | null = null;
+  if (!terminal) {
+    for (const check of heartbeatChecks) {
+      stop = await check(env, { kind: "task", id: taskId, projectId: task.projectId, workspaceId: task.workspaceId, executionMode: task.executionMode });
+      if (stop) break;
+    }
+  }
+  return response({
+    updated: true,
+    task: await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(taskId).first(),
+    ...(stop ? { stop: true, reason: stop.reason, message: stop.message } : {}),
+  });
+}
+
+// The counterpart to cancelling: a human answering what a parked task asked
+// for and putting it back in the queue. Same trust boundary as cancel (no
+// worker-lease check — the worker that gave up is exactly who we are
+// overriding), and the attempt cap is deliberately not consulted, since
+// being over it is the normal reason to be here.
+async function resumeAgentTask(request: Request, env: Env, principal: Principal, taskId: string): Promise<Response> {
+  if (!can(principal, "tasks:write") && !can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Task resume is not allowed" }, 403);
+  const task = await env.DB.prepare("SELECT project_id AS projectId, status, lease_expires_at AS leaseExpiresAt FROM agent_tasks WHERE id = ?")
+    .bind(taskId).first<{ projectId: string; status: string; leaseExpiresAt: string | null }>();
+  if (!task || !(await memberOfProject(env, principal, task.projectId, "project.write"))) return response({ error: "Task not found" }, 404);
+  if (!isResumableTask(task)) {
+    return response({ error: task.status === "completed" ? "Task is already finished" : "Task is still held by a live worker" }, 409);
+  }
+  const body = await requestJson(request);
+  const note = typeof body?.note === "string" && body.note.trim() ? body.note.trim() : "Resumed by user";
+  const fields = resumedTaskFields();
+  await env.DB.prepare(`
+    UPDATE agent_tasks SET status = ?, attempts = ?, next_attempt_at = NULL, lease_expires_at = NULL,
+      worker_id = NULL, error_message = NULL, completed_at = NULL,
+      progress_message = ?, heartbeat_at = CURRENT_TIMESTAMP
+    WHERE id = ?
+  `).bind(fields.status, fields.attempts, note, taskId).run();
+  await broadcastProjectEvent(env, task.projectId, { type: "task_event", taskId, projectId: task.projectId, status: fields.status, progressMessage: note });
+  return response({ resumed: true, task: await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(taskId).first() });
+}
+
+// A human closing a task from the dashboard is a different trust boundary
+// than a worker self-reporting its own status — updateAgentTask's worker-
+// lease check (`body.workerId` must match `worker_id`) deliberately doesn't
+// apply here, since the whole point is overriding a task that's stuck
+// (claimed by a worker that died, or never should have been claimed).
+async function cancelAgentTask(request: Request, env: Env, principal: Principal, taskId: string): Promise<Response> {
+  if (!can(principal, "tasks:write") && !can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Task cancellation is not allowed" }, 403);
+  const task = await env.DB.prepare("SELECT project_id AS projectId, status FROM agent_tasks WHERE id = ?")
+    .bind(taskId).first<{ projectId: string; status: string }>();
+  if (!task || !(await memberOfProject(env, principal, task.projectId, "project.write"))) return response({ error: "Task not found" }, 404);
+  if (["completed", "error"].includes(task.status)) return response({ error: "Task is already finished" }, 409);
+  const body = await requestJson(request);
+  const reason = typeof body?.reason === "string" && body.reason.trim() ? body.reason.trim() : "Cancelled by user";
+  await env.DB.prepare(`
+    UPDATE agent_tasks SET status = 'error', error_message = ?, completion_summary = 'Cancelled',
+      heartbeat_at = CURRENT_TIMESTAMP, completed_at = CURRENT_TIMESTAMP
+    WHERE id = ?
+  `).bind(reason, taskId).run();
+  await broadcastProjectEvent(env, task.projectId, { type: "task_event", taskId, projectId: task.projectId, status: "error", errorMessage: reason });
+  return response({ cancelled: true, task: await env.DB.prepare(`${taskSelect} WHERE id = ?`).bind(taskId).first() });
+}
+
+// device_sessions is append-oriented historical infrastructure data, not a
+// cache of current Realm state — rows are retained even after the underlying
+// Realm resource is destroyed upstream. It carries no project reference:
+// project attribution is derived transitively through agent_tasks below,
+// since a session can legitimately be used by tasks from more than one
+// project (hence `projects: [{id, taskCount}]`, never a singular projectId).
+//
+// Tenant isolation happens once, at the apps/qa edge (dashboardIdentity()'s
+// tenantIds checked against REGISTRY_REALM_OWNER_TENANT_ID before this route
+// is ever called) — these routes don't re-check tenant membership themselves,
+// they trust the authenticated service-to-service caller like every other
+// apps/qa -> registry-worker proxy already does, and just tag/filter rows by
+// the fixed owner-tenant configuration value.
+type DeviceSessionRow = {
+  id: string;
+  deviceId: string;
+  provider: string;
+  deviceType: string;
+  nativeSessionId: string;
+  state: string;
+  startedAt: string;
+  stoppedAt: string | null;
+};
+
+async function listDeviceSessions(env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "*") && !can(principal, "tasks:read")) return response({ error: "Not allowed" }, 403);
+  const ownerTenantId = env.REGISTRY_REALM_OWNER_TENANT_ID;
+  if (!ownerTenantId) return response({ sessions: [] });
+  const sessions = await env.DB.prepare(`
+    SELECT id, device_id AS deviceId, provider, device_type AS deviceType, native_session_id AS nativeSessionId,
+           state, started_at AS startedAt, stopped_at AS stoppedAt
+    FROM device_sessions WHERE tenant_id = ? ORDER BY started_at DESC LIMIT 200
+  `).bind(ownerTenantId).all<DeviceSessionRow>();
+  const rows = sessions.results;
+  const sessionIds = rows.map((row) => row.id);
+  const tasksBySession = new Map<string, Array<{ id: string; title: string; projectId: string }>>();
+  if (sessionIds.length > 0) {
+    const placeholders = sessionIds.map(() => "?").join(",");
+    const taskRows = await env.DB.prepare(`
+      SELECT id, title, project_id AS projectId, device_session_id AS deviceSessionId
+      FROM agent_tasks WHERE device_session_id IN (${placeholders})
+    `).bind(...sessionIds).all<{ id: string; title: string; projectId: string; deviceSessionId: string }>();
+    for (const task of taskRows.results) {
+      const list = tasksBySession.get(task.deviceSessionId) ?? [];
+      list.push({ id: task.id, title: task.title, projectId: task.projectId });
+      tasksBySession.set(task.deviceSessionId, list);
+    }
+  }
+  const result = rows.map((row) => {
+    const tasks = tasksBySession.get(row.id) ?? [];
+    const projectCounts = new Map<string, number>();
+    for (const task of tasks) projectCounts.set(task.projectId, (projectCounts.get(task.projectId) ?? 0) + 1);
+    return {
+      id: row.id, deviceId: row.deviceId, provider: row.provider, deviceType: row.deviceType,
+      nativeSessionId: row.nativeSessionId, state: row.state, startedAt: row.startedAt, stoppedAt: row.stoppedAt,
+      tasks: tasks.map(({ id: taskId, title }) => ({ id: taskId, title })),
+      projects: [...projectCounts.entries()].map(([projectId, taskCount]) => ({ id: projectId, taskCount })),
+    };
+  });
+  return response({ sessions: result });
+}
+
+// Trusted internal route: reachable only via apps/qa's server-side proxy
+// (AEGIS_CLIENT_SECRET-authenticated), never directly by a dashboard user.
+// Idempotent at the whole-request level by construction — upsert on the
+// (provider, native_session_id) unique key plus set-stopped_at-only-from-NULL
+// means calling it once or a hundred times with the same observed state (or
+// concurrently, from multiple tabs) produces identical DB state. Absence of a
+// session from the observed list is never treated as evidence it stopped —
+// only sessions actually present in this request's payload are touched.
+async function reconcileDeviceSessions(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  const ownerTenantId = env.REGISTRY_REALM_OWNER_TENANT_ID;
+  if (!ownerTenantId) return response({ error: "REGISTRY_REALM_OWNER_TENANT_ID is not configured" }, 500);
+  const body = await requestJson(request) as {
+    devices?: Array<{
+      id?: string; provider?: string; deviceType?: string;
+      session?: { id?: string; state?: string; startedAt?: string };
+    }>;
+  } | null;
+  const devices = Array.isArray(body?.devices) ? body.devices : [];
+  let reconciled = 0;
+  for (const device of devices) {
+    if (!device.session?.id || !device.id || !device.provider || !device.deviceType || !device.session.state || !device.session.startedAt) continue;
+    await env.DB.prepare(`
+      INSERT INTO device_sessions (id, device_id, provider, device_type, native_session_id, tenant_id, state, started_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+      ON CONFLICT(provider, native_session_id) DO UPDATE SET
+        state = CASE WHEN device_sessions.state IN ('stopped', 'failed') THEN device_sessions.state ELSE excluded.state END,
+        stopped_at = CASE WHEN device_sessions.stopped_at IS NULL AND excluded.state IN ('stopped', 'failed') THEN CURRENT_TIMESTAMP ELSE device_sessions.stopped_at END,
+        updated_at = CURRENT_TIMESTAMP
+    `).bind(
+      id("dsess"), device.id, device.provider, device.deviceType, device.session.id,
+      ownerTenantId, device.session.state, device.session.startedAt,
+    ).run();
+    reconciled += 1;
+  }
+  return response({ reconciled });
+}
+
+async function listJourneyRevisions(env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, journey_id AS journeyId, revision, object_key AS objectKey,
+           app_id AS appId, environment_id AS environmentId, status,
+           source_of_truth AS sourceOfTruth, stability, linked_to_graph AS linkedToGraph,
+           verification_run_id AS verificationRunId, created_by AS createdBy,
+           created_at AS createdAt
+    FROM journey_revisions WHERE project_id = ? ORDER BY journey_id, revision DESC
+  `).bind(projectId).all();
+  return response({ revisions: rows.results });
+}
+
+async function saveJourneyRevision(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "tasks:write") && !can(principal, "*")) {
+    return response({ error: "Journey editing is not allowed" }, 403);
+  }
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request) as {
+    journeyId?: string; objectKey?: string; expectedRevision?: number; appId?: string; environmentId?: string; status?: string;
+    sourceOfTruth?: string; stability?: string; linkedToGraph?: boolean; verificationRunId?: string;
+  } | null;
+  if (!body) return response({ error: "Request body is required" }, 422);
+  const journeyId = body?.journeyId?.trim() ?? "";
+  const objectKey = body?.objectKey?.trim() ?? "";
+  if (!journeyId || !objectKey) return response({ error: "journeyId and objectKey are required" }, 422);
+  const latest = await env.DB.prepare(`
+    SELECT revision FROM journey_revisions WHERE project_id = ? AND journey_id = ?
+    ORDER BY revision DESC LIMIT 1
+  `).bind(projectId, journeyId).first<{ revision: number }>();
+  const currentRevision = latest?.revision ?? 0;
+  if (body?.expectedRevision !== undefined && body.expectedRevision !== currentRevision) {
+    return response({ error: "Journey revision conflict", currentRevision }, 409);
+  }
+  const project = await env.DB.prepare("SELECT tenant_id AS tenantId FROM projects WHERE id = ?")
+    .bind(projectId).first<{ tenantId: string }>();
+  const revision = currentRevision + 1;
+  const idValue = id("journey");
+  await env.DB.prepare(`
+    INSERT INTO journey_revisions
+      (id, project_id, tenant_id, journey_id, revision, object_key, app_id, environment_id, status,
+       source_of_truth, stability, linked_to_graph, verification_run_id, created_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).bind(
+    idValue, projectId, project?.tenantId ?? `tenant_${principal.aegisId}`, journeyId, revision,
+    objectKey, body.appId ?? null, body.environmentId ?? null, body.status === "published" ? "published" : "draft",
+    body.sourceOfTruth === "canonical_flow" ? "canonical_flow" : "canonical_flow",
+    body.stability === "stable" ? "stable" : body.stability === "stabilizing" ? "stabilizing" : "discovered",
+    body.linkedToGraph === true ? 1 : 0,
+    body.verificationRunId ?? null,
+    principal.aegisId,
+  ).run();
+  await broadcastProjectEvent(env, projectId, { type: "journey_event", journeyId, projectId, revision, status: body.status ?? "draft" });
+  return response({
+    revision: {
+      id: idValue, projectId, journeyId, revision, objectKey, appId: body.appId ?? null,
+      environmentId: body.environmentId ?? null, status: body.status === "published" ? "published" : "draft",
+      sourceOfTruth: "canonical_flow",
+      stability: body.stability ?? "discovered",
+      linkedToGraph: body.linkedToGraph === true,
+      verificationRunId: body.verificationRunId ?? null,
+    },
+  }, 201);
+}
+
+async function resetProject(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Project reset is not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request);
+  if (body?.confirmation !== `RESET ${projectId}`) return response({ error: "Explicit reset confirmation is required" }, 422);
+  await env.DB.batch([
+    env.DB.prepare("DELETE FROM plan_drafts WHERE project_id = ?").bind(projectId),
+    env.DB.prepare("DELETE FROM runs WHERE project_id = ?").bind(projectId),
+    env.DB.prepare("DELETE FROM agent_tasks WHERE project_id = ?").bind(projectId),
+    env.DB.prepare("DELETE FROM journey_revisions WHERE project_id = ?").bind(projectId),
+  ]);
+  await auditProject(env, principal, projectId, { action: "project.reset", targetType: "project", targetId: projectId }, request);
+  return response({ reset: true, projectId });
+}
+
+async function upsertGithubInstallation(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "projects:write") && !can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.manage"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request);
+  const installationId = Number(body?.installationId);
+  const accountLogin = typeof body?.accountLogin === "string" ? body.accountLogin.trim() : "";
+  const accountType = typeof body?.accountType === "string" ? body.accountType.trim() : "";
+  const repositorySelection = typeof body?.repositorySelection === "string" ? body.repositorySelection.trim() : "";
+  if (!Number.isFinite(installationId) || !accountLogin || !accountType || !repositorySelection) {
+    return response({ error: "installationId, accountLogin, accountType, and repositorySelection are required" }, 422);
+  }
+  const repositories = Array.isArray(body?.repositories) ? body.repositories : [];
+  const installationRowId = id("ghinst");
+  await env.DB.prepare(`
+    INSERT INTO github_installations
+      (id, project_id, installation_id, account_login, account_type, repository_selection, repositories_json, connected_by)
+    VALUES (?, ?, ?, ?, ?, ?, ?, ?)
+    ON CONFLICT(project_id, installation_id) DO UPDATE SET
+      account_login = excluded.account_login, account_type = excluded.account_type,
+      repository_selection = excluded.repository_selection, repositories_json = excluded.repositories_json,
+      revoked_at = NULL
+  `).bind(
+    installationRowId, projectId, installationId, accountLogin, accountType,
+    repositorySelection, JSON.stringify(repositories), principal.aegisId,
+  ).run();
+  const installation = await env.DB.prepare(`
+    SELECT id, installation_id AS installationId, account_login AS accountLogin, account_type AS accountType,
+           repository_selection AS repositorySelection, repositories_json AS repositoriesJson,
+           connected_by AS connectedBy, connected_at AS connectedAt, revoked_at AS revokedAt
+    FROM github_installations WHERE project_id = ? AND installation_id = ?
+  `).bind(projectId, installationId).first();
+  await auditProject(env, principal, projectId, { action: "integration.github_connected", targetType: "github_installation", targetId: String(installationId) }, request);
+  return response({ installation }, 201);
+}
+
+async function listGithubInstallations(env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT id, installation_id AS installationId, account_login AS accountLogin, account_type AS accountType,
+           repository_selection AS repositorySelection, repositories_json AS repositoriesJson,
+           connected_by AS connectedBy, connected_at AS connectedAt, revoked_at AS revokedAt
+    FROM github_installations WHERE project_id = ? AND revoked_at IS NULL ORDER BY connected_at DESC
+  `).bind(projectId).all();
+  return response({ installations: rows.results });
+}
+
+async function getGithubInstallationsByInstallationId(env: Env, principal: Principal, installationId: string): Promise<Response> {
+  if (!can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  const rows = await env.DB.prepare(`
+    SELECT project_id AS projectId FROM github_installations
+    WHERE installation_id = ? AND revoked_at IS NULL
+  `).bind(Number(installationId)).all<{ projectId: string }>();
+  return response({ installations: rows.results });
+}
+
+async function markGithubInstallationRevoked(env: Env, principal: Principal, installationId: string): Promise<Response> {
+  if (!can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  await env.DB.prepare(`
+    UPDATE github_installations SET revoked_at = CURRENT_TIMESTAMP
+    WHERE installation_id = ? AND revoked_at IS NULL
+  `).bind(Number(installationId)).run();
+  return response({ revoked: true, installationId: Number(installationId) });
+}
+
+async function updateGithubInstallationRepositories(request: Request, env: Env, principal: Principal, installationId: string): Promise<Response> {
+  if (!can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  const body = await requestJson(request);
+  const repositories = Array.isArray(body?.repositories) ? body.repositories : [];
+  await env.DB.prepare(`
+    UPDATE github_installations SET repositories_json = ? WHERE installation_id = ? AND revoked_at IS NULL
+  `).bind(JSON.stringify(repositories), Number(installationId)).run();
+  return response({ updated: true, installationId: Number(installationId) });
+}
+
+async function createIssueTrackerLink(request: Request, env: Env, principal: Principal, projectId: string): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const body = await requestJson(request);
+  const owner = typeof body?.owner === "string" ? body.owner.trim() : "";
+  const repo = typeof body?.repo === "string" ? body.repo.trim() : "";
+  const issueNumber = Number(body?.issueNumber);
+  const url = typeof body?.url === "string" ? body.url.trim() : "";
+  const title = typeof body?.title === "string" ? body.title.trim() : "";
+  const state = typeof body?.state === "string" ? body.state.trim() : "unknown";
+  const findingKind = typeof body?.findingKind === "string" ? body.findingKind.trim() : "";
+  const findingKey = typeof body?.findingKey === "string" ? body.findingKey.trim() : "";
+  if (!owner || !repo || !Number.isFinite(issueNumber) || !url || !title || !findingKind || !findingKey) {
+    return response({ error: "owner, repo, issueNumber, url, title, findingKind, and findingKey are required" }, 422);
+  }
+  const existing = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, provider, installation_id AS installationId, owner, repo,
+           issue_number AS issueNumber, issue_node_id AS issueNodeId, url, title, state,
+           finding_kind AS findingKind, finding_key AS findingKey, created_by AS createdBy,
+           created_at AS createdAt, updated_at AS updatedAt, last_sync_source AS lastSyncSource
+    FROM issue_tracker_links WHERE project_id = ? AND provider = 'github' AND finding_kind = ? AND finding_key = ?
+  `).bind(projectId, findingKind, findingKey).first();
+  if (existing) return response({ error: "This finding is already linked", link: existing }, 409);
+  const linkId = id("ghlink");
+  await env.DB.prepare(`
+    INSERT INTO issue_tracker_links
+      (id, project_id, provider, installation_id, owner, repo, issue_number, issue_node_id, url, title, state,
+       finding_kind, finding_key, created_by, last_sync_source)
+    VALUES (?, ?, 'github', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 'create')
+  `).bind(
+    linkId, projectId, Number.isFinite(Number(body?.installationId)) ? Number(body?.installationId) : null,
+    owner, repo, issueNumber, typeof body?.nodeId === "string" ? body.nodeId : null, url, title, state,
+    findingKind, findingKey, principal.aegisId,
+  ).run();
+  const link = await env.DB.prepare(`
+    SELECT id, project_id AS projectId, provider, installation_id AS installationId, owner, repo,
+           issue_number AS issueNumber, issue_node_id AS issueNodeId, url, title, state,
+           finding_kind AS findingKind, finding_key AS findingKey, created_by AS createdBy,
+           created_at AS createdAt, updated_at AS updatedAt, last_sync_source AS lastSyncSource
+    FROM issue_tracker_links WHERE id = ?
+  `).bind(linkId).first();
+  return response({ link }, 201);
+}
+
+async function listIssueTrackerLinks(env: Env, principal: Principal, projectId: string, findingKey?: string): Promise<Response> {
+  if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+  const rows = findingKey
+    ? await env.DB.prepare(`
+        SELECT id, project_id AS projectId, provider, installation_id AS installationId, owner, repo,
+               issue_number AS issueNumber, issue_node_id AS issueNodeId, url, title, state,
+               finding_kind AS findingKind, finding_key AS findingKey, created_by AS createdBy,
+               created_at AS createdAt, updated_at AS updatedAt, last_sync_source AS lastSyncSource
+        FROM issue_tracker_links WHERE project_id = ? AND finding_key = ? ORDER BY updated_at DESC
+      `).bind(projectId, findingKey).all()
+    : await env.DB.prepare(`
+        SELECT id, project_id AS projectId, provider, installation_id AS installationId, owner, repo,
+               issue_number AS issueNumber, issue_node_id AS issueNodeId, url, title, state,
+               finding_kind AS findingKind, finding_key AS findingKey, created_by AS createdBy,
+               created_at AS createdAt, updated_at AS updatedAt, last_sync_source AS lastSyncSource
+        FROM issue_tracker_links WHERE project_id = ? ORDER BY updated_at DESC
+      `).bind(projectId).all();
+  return response({ links: rows.results });
+}
+
+async function deleteIssueTrackerLink(env: Env, principal: Principal, projectId: string, linkId: string): Promise<Response> {
+  if (!can(principal, "runs:write") && !can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  if (!(await memberOfProject(env, principal, projectId, "project.write"))) return response({ error: "Project scope is not allowed" }, 403);
+  const result = await env.DB.prepare(`
+    DELETE FROM issue_tracker_links WHERE id = ? AND project_id = ?
+  `).bind(linkId, projectId).run() as { meta?: { changes?: number } };
+  if (result.meta?.changes !== 1) return response({ error: "Link not found" }, 404);
+  return response({ deleted: true, id: linkId });
+}
+
+/**
+ * Service-only: called by the GitHub webhook handler, which knows only
+ * owner/repo/issue_number (never our finding_key or project id). Updates
+ * every matching link across every project in one idempotent SET — webhook
+ * delivery isn't ordered and can be redelivered, so this must stay a plain
+ * last-write-wins update rather than any increment/toggle logic.
+ */
+async function updateIssueTrackerLinksByExternalIssue(request: Request, env: Env, principal: Principal): Promise<Response> {
+  if (!can(principal, "*")) return response({ error: "Not allowed" }, 403);
+  const body = await requestJson(request);
+  const owner = typeof body?.owner === "string" ? body.owner.trim() : "";
+  const repo = typeof body?.repo === "string" ? body.repo.trim() : "";
+  const issueNumber = Number(body?.issueNumber);
+  const state = typeof body?.state === "string" ? body.state.trim() : "";
+  const title = typeof body?.title === "string" ? body.title.trim() : "";
+  if (!owner || !repo || !Number.isFinite(issueNumber) || !state) {
+    return response({ error: "owner, repo, issueNumber, and state are required" }, 422);
+  }
+  const result = await env.DB.prepare(`
+    UPDATE issue_tracker_links
+    SET state = ?, title = COALESCE(NULLIF(?, ''), title), updated_at = CURRENT_TIMESTAMP, last_sync_source = 'webhook'
+    WHERE provider = 'github' AND owner = ? AND repo = ? AND issue_number = ?
+  `).bind(state, title, owner, repo, issueNumber).run() as { meta?: { changes?: number } };
+  return response({ updated: result.meta?.changes ?? 0 });
+}
+
+async function rememberEmail(env: Env, aegisId: string, email: string, verified: boolean): Promise<void> {
+  await env.DB.prepare(`
+    INSERT INTO aegis_users (id, email, email_verified) VALUES (?, ?, ?)
+    ON CONFLICT(id) DO UPDATE SET email = excluded.email, email_verified = excluded.email_verified
+    WHERE aegis_users.email IS NOT excluded.email OR aegis_users.email_verified IS NOT excluded.email_verified
+  `).bind(aegisId, email, verified ? 1 : 0).run();
+}
+
+runService.create = createRun;
+
+export class RunsCoordinator {
+  private readonly sockets = new Set<WebSocket>();
+
+  constructor(private readonly state: DurableObjectState) {}
+
+  async fetch(request: Request): Promise<Response> {
+    if (request.method === "POST" && new URL(request.url).pathname === "/broadcast") {
+      const event = await request.text();
+      for (const socket of this.sockets) {
+        try {
+          socket.send(event);
+        } catch {
+          this.sockets.delete(socket);
+        }
+      }
+      return new Response("ok");
+    }
+    if (request.headers.get("Upgrade")?.toLowerCase() !== "websocket") {
+      return new Response("WebSocket upgrade required", { status: 426 });
+    }
+    const pair = new WebSocketPair();
+    const client = pair[0];
+    const server = pair[1];
+    server.accept();
+    this.sockets.add(server);
+    server.addEventListener("close", () => this.sockets.delete(server));
+    server.addEventListener("error", () => this.sockets.delete(server));
+    server.addEventListener("message", (event) => {
+      if (typeof event.data === "string") {
+        try {
+          server.send(JSON.stringify({ type: "ack", message: JSON.parse(event.data) }));
+        } catch {
+          server.send(JSON.stringify({ type: "error", error: "Invalid message" }));
+        }
+      }
+    });
+    return new Response(null, { status: 101, webSocket: client });
+  }
+}
+
+const registryWorker = {
+  async scheduled(controller: ScheduledController, env: Env, ctx: ExecutionContext): Promise<void> {
+    await runScheduledJobs(controller, env, ctx);
+  },
+
+  async fetch(request: Request, env: Env, ctx?: ExecutionContext): Promise<Response> {
+    const url = new URL(request.url);
+    const context = ctx ?? detachedContext();
+    if (request.method === "GET" && url.pathname === "/health") return response({ ok: true, service: "valkyrie-registry" });
+    const publicResponse = await handlePublicRoutes(request, env, url, context);
+    if (publicResponse) return publicResponse;
+    if (request.method === "POST" && url.pathname === "/api/device-authorizations") {
+      return createDeviceAuthorization(request, env);
+    }
+    if (request.method === "POST" && url.pathname === "/api/device-authorizations/poll") {
+      return pollDeviceAuthorization(request, env);
+    }
+    const websocketMatch = url.pathname.match(/^\/api\/ws\/projects\/([^/]+)$/);
+    const principal = websocketMatch
+      ? ((await apiPrincipal(request, env)) ?? (await subscriptionPrincipal(request, env)))
+      : await apiPrincipal(request, env);
+    if (!principal) return response({ error: "Authentication required" }, 401);
+    if (principal.runner && !runnerMayCall(principal.runner, request.method, url)) {
+      return response({ error: "Runner tokens can't call this route" }, 403);
+    }
+    if (principal.org) {
+      // People the IdP removed stay out, even with a dashboard session left over.
+      if (await isDeprovisioned(env, principal.aegisId)) {
+        return response({ error: "Your access was removed by your organization", code: "account_deprovisioned" }, 401);
+      }
+      // Groups arrive with the sign-in; later changes come from SCIM events.
+      if (principal.org.groups) {
+        await applyOrgMembership(env, { aegisId: principal.aegisId, email: principal.email }, { id: principal.org.id, groups: principal.org.groups });
+      }
+    }
+    if (principal.email) context.waitUntil(rememberEmail(env, principal.aegisId, principal.email, principal.emailVerified === true));
+    if (websocketMatch && request.headers.get("Upgrade")?.toLowerCase() === "websocket") {
+      if (!(await memberOfProject(env, principal, decodeURIComponent(websocketMatch[1])))) {
+        return response({ error: "Project scope is not allowed" }, 403);
+      }
+      if (!env.RUNS_COORDINATOR) return response({ error: "WebSocket coordinator is unavailable" }, 503);
+      const stub = env.RUNS_COORDINATOR.get(
+        env.RUNS_COORDINATOR.idFromName(decodeURIComponent(websocketMatch[1])),
+      );
+      return stub.fetch(request);
+    }
+    if (request.method === "POST" && url.pathname === "/api/device-authorizations/claim") {
+      return claimDeviceAuthorization(request, env, principal);
+    }
+    if (request.method === "GET" && url.pathname === "/api/projects") {
+      return can(principal, "projects:read") ? listProjects(env, principal) : response({ error: "Not allowed" }, 403);
+    }
+    if (request.method === "GET" && url.pathname === "/api/workspaces") {
+      return can(principal, "projects:read") ? listWorkspaces(env, principal) : response({ error: "Not allowed" }, 403);
+    }
+    if (request.method === "POST" && url.pathname === "/api/workspaces") return createWorkspace(request, env, principal);
+    const workspaceMatch = url.pathname.match(/^\/api\/workspaces\/([^/]+)$/);
+    if (workspaceMatch && request.method === "PATCH") {
+      return updateWorkspace(request, env, principal, decodeURIComponent(workspaceMatch[1]));
+    }
+    if (request.method === "POST" && url.pathname === "/api/projects/register") return createManagedProject(request, env, principal);
+    const projectEditMatch = url.pathname.match(/^\/api\/projects\/([^/]+)$/);
+    if (projectEditMatch && request.method === "PATCH") {
+      return updateProject(request, env, principal, decodeURIComponent(projectEditMatch[1]));
+    }
+    const appEditMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/apps\/([^/]+)$/);
+    if (appEditMatch && request.method === "PATCH") {
+      return updateApp(request, env, principal, decodeURIComponent(appEditMatch[1]), decodeURIComponent(appEditMatch[2]));
+    }
+    const appMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/apps$/);
+    if (request.method === "POST" && appMatch) {
+      return createApp(request, env, principal, decodeURIComponent(appMatch[1]));
+    }
+    const environmentMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/environments$/);
+    if (request.method === "POST" && environmentMatch) {
+      return createEnvironment(request, env, principal, decodeURIComponent(environmentMatch[1]));
+    }
+    const environmentEditMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/environments\/([^/]+)$/);
+    if (environmentEditMatch && request.method === "PATCH") {
+      return updateEnvironment(
+        request,
+        env,
+        principal,
+        decodeURIComponent(environmentEditMatch[1]),
+        decodeURIComponent(environmentEditMatch[2]),
+      );
+    }
+    if (request.method === "GET" && url.pathname === "/api/api-keys") {
+      return can(principal, "keys:read") || can(principal, "keys:write") || can(principal, "*")
+        ? listApiKeys(env, principal)
+        : response({ error: "Not allowed" }, 403);
+    }
+    if (request.method === "POST" && url.pathname === "/api/api-keys") return createApiKey(request, env, principal);
+    const revokeMatch = url.pathname.match(/^\/api\/api-keys\/([^/]+)$/);
+    if (request.method === "DELETE" && revokeMatch) return revokeApiKey(request, env, principal, revokeMatch[1]);
+    const plansMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/plans$/);
+    if (plansMatch && request.method === "GET") {
+      return listPlanDrafts(env, principal, decodeURIComponent(plansMatch[1]));
+    }
+    if (plansMatch && request.method === "POST") {
+      return publishPlanDraft(request, env, principal, decodeURIComponent(plansMatch[1]));
+    }
+    const runsMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/runs$/);
+    if (runsMatch && request.method === "GET") return listRuns(env, principal, decodeURIComponent(runsMatch[1]));
+    if (runsMatch && request.method === "POST") return createRun(request, env, principal, decodeURIComponent(runsMatch[1]), context);
+    const artifactsMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/artifacts(\/object)?$/);
+    if (artifactsMatch && request.method === "GET") {
+      const projectId = decodeURIComponent(artifactsMatch[1]);
+      if (!(await memberOfProject(env, principal, projectId))) return response({ error: "Project scope is not allowed" }, 403);
+      return artifactsMatch[2]
+        ? getProjectArtifact(env.ARTIFACTS, projectId, url)
+        : listProjectArtifacts(env.ARTIFACTS, projectId, url);
+    }
+    const runMatch = url.pathname.match(/^\/api\/runs\/([^/]+)$/);
+    if (runMatch && request.method === "GET") return getRun(env, principal, decodeURIComponent(runMatch[1]));
+    if (runMatch && request.method === "POST") return updateRun(request, env, principal, decodeURIComponent(runMatch[1]), context);
+    const claimMatch = url.pathname.match(/^\/api\/runs\/([^/]+)\/claim$/);
+    if (claimMatch && request.method === "POST") return claimRun(request, env, principal, decodeURIComponent(claimMatch[1]), context);
+    const tasksMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/tasks$/);
+    if (tasksMatch && request.method === "GET") return listAgentTasks(env, principal, decodeURIComponent(tasksMatch[1]));
+    if (tasksMatch && request.method === "POST") return createAgentTask(request, env, principal, decodeURIComponent(tasksMatch[1]), context);
+    const taskClaimMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/claim$/);
+    if (taskClaimMatch && request.method === "POST") return claimAgentTask(request, env, principal, decodeURIComponent(taskClaimMatch[1]));
+    const taskCancelMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/cancel$/);
+    if (taskCancelMatch && request.method === "POST") return cancelAgentTask(request, env, principal, decodeURIComponent(taskCancelMatch[1]));
+    const taskResumeMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)\/resume$/);
+    if (taskResumeMatch && request.method === "POST") return resumeAgentTask(request, env, principal, decodeURIComponent(taskResumeMatch[1]));
+    const taskMatch = url.pathname.match(/^\/api\/tasks\/([^/]+)$/);
+    if (taskMatch && request.method === "POST") return updateAgentTask(request, env, principal, decodeURIComponent(taskMatch[1]), context);
+    if (request.method === "GET" && url.pathname === "/api/device-sessions") return listDeviceSessions(env, principal);
+    if (request.method === "POST" && url.pathname === "/api/device-sessions/reconcile") return reconcileDeviceSessions(request, env, principal);
+    const journeysMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/journeys$/);
+    if (journeysMatch && request.method === "GET") return listJourneyRevisions(env, principal, decodeURIComponent(journeysMatch[1]));
+    if (journeysMatch && request.method === "POST") return saveJourneyRevision(request, env, principal, decodeURIComponent(journeysMatch[1]));
+    const resetMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/reset$/);
+    if (resetMatch && request.method === "POST") return resetProject(request, env, principal, decodeURIComponent(resetMatch[1]));
+    const githubInstallationsMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/github-installations$/);
+    if (githubInstallationsMatch && request.method === "GET") {
+      return listGithubInstallations(env, principal, decodeURIComponent(githubInstallationsMatch[1]));
+    }
+    if (githubInstallationsMatch && request.method === "POST") {
+      return upsertGithubInstallation(request, env, principal, decodeURIComponent(githubInstallationsMatch[1]));
+    }
+    const githubInstallationByIdMatch = url.pathname.match(/^\/api\/github-installations\/by-installation-id\/([^/]+)$/);
+    if (githubInstallationByIdMatch && request.method === "GET") {
+      return getGithubInstallationsByInstallationId(env, principal, decodeURIComponent(githubInstallationByIdMatch[1]));
+    }
+    const githubInstallationRevokeMatch = url.pathname.match(/^\/api\/github-installations\/by-installation-id\/([^/]+)\/revoke$/);
+    if (githubInstallationRevokeMatch && request.method === "POST") {
+      return markGithubInstallationRevoked(env, principal, decodeURIComponent(githubInstallationRevokeMatch[1]));
+    }
+    const githubInstallationReposMatch = url.pathname.match(/^\/api\/github-installations\/by-installation-id\/([^/]+)\/repositories$/);
+    if (githubInstallationReposMatch && request.method === "POST") {
+      return updateGithubInstallationRepositories(request, env, principal, decodeURIComponent(githubInstallationReposMatch[1]));
+    }
+    const githubLinksMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/github-links$/);
+    if (githubLinksMatch && request.method === "GET") {
+      return listIssueTrackerLinks(env, principal, decodeURIComponent(githubLinksMatch[1]), url.searchParams.get("finding") ?? undefined);
+    }
+    if (githubLinksMatch && request.method === "POST") {
+      return createIssueTrackerLink(request, env, principal, decodeURIComponent(githubLinksMatch[1]));
+    }
+    const githubLinkDeleteMatch = url.pathname.match(/^\/api\/projects\/([^/]+)\/github-links\/([^/]+)$/);
+    if (githubLinkDeleteMatch && request.method === "DELETE") {
+      return deleteIssueTrackerLink(env, principal, decodeURIComponent(githubLinkDeleteMatch[1]), decodeURIComponent(githubLinkDeleteMatch[2]));
+    }
+    if (request.method === "PATCH" && url.pathname === "/api/github-links/by-issue") {
+      return updateIssueTrackerLinksByExternalIssue(request, env, principal);
+    }
+    const extended = await handleExtendedRoutes(request, env, principal, url, context);
+    if (extended) return extended;
+    return response({ error: "Not found" }, 404);
+  },
+};
+
+registryDispatch.fetch = (request, env, ctx) => registryWorker.fetch(request, env, ctx);
+
+export default registryWorker;