@bugmole/cli 0.4.0

package/src/runtime/discovery-task.ts

@@ -0,0 +1,284 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import YAML from "yaml";
+import type { ControlPlaneClient, RegistryTask } from "../registry/control-plane-client.js";
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+import { readJourneyGraph, writeJourneyGraph } from "./journey-editor.js";
+import type { JourneyEdge, JourneyNode, UserJourney } from "./journey-graph.js";
+import { discoverSite, type DiscoveryResult } from "./site-discovery.js";
+import { explorationPrompt, parseExploration, type ExplorationPersona } from "./ai-exploration.js";
+import { modelCaller } from "./platform-ai.js";
+
+/** Discovery tasks queued as "Explore with AI …" also have a model write multi-page journeys. */
+export function discoveryUsesAi(task: Pick<RegistryTask, "title">): boolean {
+  return /^Explore with AI\b/i.test(task.title ?? "");
+}
+
+const PERSONA_MARKER = /<!-- persona:([A-Za-z0-9+/=]+) -->/;
+
+/**
+ * base64 via TextEncoder/btoa rather than Buffer, so the exact same scheme
+ * works in the worker runtime and in the dashboard's browser bundle (which
+ * constructs this same marker before the task is even created — see
+ * apps/qa/src/lib/discovery-persona.ts).
+ */
+function toBase64(text: string): string {
+  return btoa(String.fromCharCode(...new TextEncoder().encode(text)));
+}
+function fromBase64(encoded: string): string {
+  return new TextDecoder().decode(Uint8Array.from(atob(encoded), (char) => char.charCodeAt(0)));
+}
+
+/** Packs the chosen persona into the task description, base64'd so its text can't break the marker. */
+export function withPersonaMarker(description: string, persona: ExplorationPersona | null | undefined): string {
+  if (!persona) return description;
+  return `${description}\n\n<!-- persona:${toBase64(JSON.stringify(persona))} -->`;
+}
+
+/** The persona a discovery task was queued with, if any. */
+export function discoveryPersona(task: Pick<RegistryTask, "description">): ExplorationPersona | null {
+  const match = PERSONA_MARKER.exec(task.description ?? "");
+  if (!match) return null;
+  try {
+    const parsed = JSON.parse(fromBase64(match[1])) as Partial<ExplorationPersona>;
+    return typeof parsed.name === "string" && typeof parsed.description === "string" ? { name: parsed.name, description: parsed.description } : null;
+  } catch {
+    return null;
+  }
+}
+
+export const DISCOVERY_TASK_TYPE = "discovery";
+
+/** The URL a discovery task was queued for: the first http(s) URL in its description. */
+export function discoveryUrl(task: Pick<RegistryTask, "description">): string | null {
+  const match = /https?:\/\/[^\s"'<>]+/.exec(task.description ?? "");
+  if (!match) return null;
+  try {
+    const url = new URL(match[0]);
+    return /^https?:$/.test(url.protocol) ? url.toString() : null;
+  } catch {
+    return null;
+  }
+}
+
+/** What the dashboard shows while discovery runs; sent in full on every update. */
+export type DiscoveryProgress = {
+  kind: "discovery";
+  url: string;
+  events: DiscoveryResult["events"];
+  pages: Array<{ route: string; title: string; heading?: string; forms: number }>;
+  flows: Array<{ id: string; name: string; kind: "page" | "form" | "journey"; route: string; steps: string[]; planId?: string }>;
+};
+
+export function progressOf(url: string, result: DiscoveryResult, planIds: Record<string, string> = {}): DiscoveryProgress {
+  return {
+    kind: "discovery",
+    url,
+    // The last 40 events are plenty for a live log and keep updates small.
+    events: result.events.slice(-40),
+    pages: result.pages.map((page) => ({ route: page.route, title: page.title, ...(page.heading ? { heading: page.heading } : {}), forms: page.forms.length })),
+    flows: result.flows.map((flow) => ({ id: flow.id, name: flow.name, kind: flow.kind, route: flow.route, steps: flow.steps, ...(planIds[flow.id] ? { planId: planIds[flow.id] } : {}) })),
+  };
+}
+
+type WorkerConfig = { project?: { id?: string }; runtime?: { spec_dir?: string; artifacts_dir?: string }; storage?: unknown };
+
+/**
+ * Saves what discovery found as the project's own flows and plans, publishes
+ * the plans so the dashboard can run them, and adds the pages and clicks to
+ * the journey graph. Returns the plan id published for each flow.
+ */
+export async function saveDiscovery(cfg: WorkerConfig, client: Pick<ControlPlaneClient, "publishPlan">, result: DiscoveryResult): Promise<Record<string, string>> {
+  const projectId = cfg.project?.id ?? "default";
+  const specDir = cfg.runtime?.spec_dir || "./spec";
+  const store = createProjectObjectStore(cfg as never);
+  const planIds: Record<string, string> = {};
+
+  for (const flow of result.flows) {
+    const flowFile = path.join(specDir, flow.file);
+    await fs.mkdir(path.dirname(flowFile), { recursive: true });
+    await fs.writeFile(flowFile, flow.content, "utf8");
+    await store.put(`${projectPrefix(projectId)}/spec/${flow.file}`, flow.content, "text/yaml");
+
+    const planId = flow.id;
+    const plan = YAML.stringify({
+      suites: [{
+        journeys: [{
+          id: flow.id,
+          name: flow.name,
+          driver: "playwright",
+          platform: "web",
+          flow: flow.file,
+          steps: flow.steps.map((label, index) => ({ node_id: `step-${index + 1}`, action: label })),
+        }],
+      }],
+    });
+    const planFile = path.join(specDir, "plans", `${planId}.yaml`);
+    await fs.mkdir(path.dirname(planFile), { recursive: true });
+    await fs.writeFile(planFile, plan, "utf8");
+    const objectKey = `${projectPrefix(projectId)}/plans/${planId}.flow.yaml`;
+    await store.put(objectKey, plan, "text/yaml");
+    await client.publishPlan({ planId, journeyId: flow.id, objectKey });
+    planIds[flow.id] = planId;
+  }
+
+  const graph = readJourneyGraph(cfg as never);
+  const nodeId = (route: string) => `screen:${route}`;
+  const nodes = new Map(graph.nodes.map((node) => [node.id, node]));
+  for (const page of result.pages) {
+    const existing = nodes.get(nodeId(page.route));
+    nodes.set(nodeId(page.route), {
+      ...(existing ?? { kind: "screen" as const }),
+      id: nodeId(page.route),
+      title: existing?.title ?? (page.heading || page.title || page.route),
+      kind: existing?.kind ?? "screen",
+      route: page.route,
+      metadata: { ...(existing?.metadata ?? {}), discoveredBy: "site-discovery", forms: page.forms.map((form) => form.name) },
+    } as JourneyNode);
+  }
+  const edges = new Map(graph.edges.map((edge) => [edge.id, edge]));
+  for (const page of result.pages) {
+    for (const link of page.links) {
+      if (!result.pages.some((other) => other.route === link.route)) continue;
+      const id = `${nodeId(page.route)}->${nodeId(link.route)}:click`;
+      edges.set(id, { ...(edges.get(id) ?? {}), id, from: nodeId(page.route), to: nodeId(link.route), label: link.label } as JourneyEdge);
+    }
+  }
+  const journeys = new Map(graph.journeys.map((journey) => [journey.id, journey]));
+  for (const flow of result.flows) {
+    const page = result.pages.find((candidate) => candidate.route === flow.route);
+    if (!page) continue;
+    // The pages a visitor passes through: home, then each click on the path.
+    let current = result.pages.find((candidate) => candidate.path.length === 0);
+    const routes = current ? [current.route] : [];
+    for (const label of page.path) {
+      const link = current?.links.find((candidate) => candidate.label === label);
+      if (!link) break;
+      routes.push(link.route);
+      current = result.pages.find((candidate) => candidate.route === link.route);
+    }
+    const nodeIds = [...new Set(routes.map((route) => nodeId(route)))].filter((id) => nodes.has(id));
+    const edgeIds = nodeIds.slice(1).map((id, index) => `${nodeIds[index]}->${id}:click`).filter((id) => edges.has(id));
+    const previous = journeys.get(flow.id);
+    journeys.set(flow.id, {
+      id: flow.id,
+      name: flow.name,
+      actor: "visitor",
+      startNodeId: nodeIds[0],
+      nodeIds,
+      edgeIds,
+      revision: (previous?.revision ?? 0) + 1,
+      status: "draft",
+      sourceOfTruth: "canonical_flow",
+      stability: "discovered",
+      linkedToGraph: false,
+      metadata: { generatedBy: "site-discovery", flow: flow.file, planId: planIds[flow.id], kind: flow.kind },
+    } as UserJourney);
+  }
+  await writeJourneyGraph(cfg as never, {
+    ...graph,
+    nodes: [...nodes.values()],
+    edges: [...edges.values()],
+    journeys: [...journeys.values()],
+  });
+  return planIds;
+}
+
+/**
+ * Runs one queued discovery task end to end. Progress is streamed to the
+ * registry on every event, so the dashboard shows the exploration live.
+ */
+export async function runDiscoveryTask(
+  cfg: WorkerConfig,
+  client: Pick<ControlPlaneClient, "claimTask" | "updateTask" | "publishPlan">,
+  task: RegistryTask,
+  workerId: string,
+  discover: typeof discoverSite = discoverSite,
+  options: {
+    /** A cloud runner's task was already claimed by the dispatcher. */
+    claimed?: boolean;
+    /** Called once if the registry answers an update with `stop`. */
+    onStop?: (signal: { reason: string; message: string }) => void;
+  } = {},
+): Promise<void> {
+  const url = discoveryUrl(task);
+  if (!options.claimed) {
+    try {
+      await client.claimTask(task.id, workerId);
+    } catch {
+      return;
+    }
+  }
+  let stopped = false;
+  const watchStop = (reply: unknown) => {
+    const body = reply as { stop?: unknown; reason?: unknown; message?: unknown } | null;
+    if (!body || body.stop !== true || stopped) return;
+    stopped = true;
+    options.onStop?.({
+      reason: typeof body.reason === "string" ? body.reason : "stopped",
+      message: typeof body.message === "string" ? body.message : "The registry stopped this task.",
+    });
+  };
+  if (!url) {
+    await client.updateTask(task.id, { workerId, status: "error", errorMessage: "No http(s) URL to explore in this task." });
+    return;
+  }
+  let latest: DiscoveryProgress = progressOf(url, { baseUrl: url, pages: [], flows: [], events: [] });
+  let sending: Promise<unknown> = Promise.resolve();
+  const send = (status: string, extra: Record<string, unknown> = {}) => {
+    const snapshot = latest;
+    const lastEvent = snapshot.events[snapshot.events.length - 1];
+    sending = sending.then(() => client.updateTask(task.id, {
+      workerId,
+      status,
+      progressMessage: lastEvent?.text ?? "Starting the browser…",
+      continuation: snapshot,
+      ...extra,
+    }).then(watchStop).catch(() => undefined));
+    return sending;
+  };
+  const heartbeat = setInterval(() => void send("running"), 20_000);
+  heartbeat.unref?.();
+  try {
+    await send("running");
+    const result = await discover(url, {
+      onEvent: async (_event, snapshot) => {
+        latest = progressOf(url, snapshot);
+        await send("running");
+      },
+    });
+    if (discoveryUsesAi(task)) {
+      const caller = modelCaller(cfg, { projectId: cfg.project?.id ?? "default", requestId: task.id });
+      const note = (text: string, kind: "flows" | "error") => {
+        result.events.push({ at: new Date().toISOString(), kind, text });
+        latest = progressOf(url, result);
+        return send("running");
+      };
+      if (!caller) {
+        await note("AI exploration needs a model: connect a model key or Bugmole AI.", "error");
+      } else {
+        const persona = discoveryPersona(task);
+        await note(persona ? `Asking AI for multi-page journeys as ${persona.name}…` : "Asking AI for multi-page journeys…", "flows");
+        try {
+          const reply = await caller(explorationPrompt(result, persona ?? undefined), "exploration");
+          const journeys = parseExploration(reply.text, result.baseUrl, result.flows);
+          result.flows.push(...journeys);
+          await note(`AI wrote ${journeys.length} journey${journeys.length === 1 ? "" : "s"}`, "flows");
+        } catch (error) {
+          await note(`AI exploration failed: ${error instanceof Error ? error.message : String(error)}`, "error");
+        }
+      }
+    }
+    const planIds = await saveDiscovery(cfg, client, result);
+    latest = progressOf(url, result, planIds);
+    await send("completed", {
+      completionSummary: `Explored ${result.pages.length} page(s) of ${url} and discovered ${result.flows.length} flow(s).`,
+    });
+  } catch (error) {
+    await send("error", { errorMessage: error instanceof Error ? error.message : String(error) });
+  } finally {
+    clearInterval(heartbeat);
+    await sending;
+  }
+}

package/src/runtime/driver-recovery.ts

@@ -0,0 +1,69 @@
+import { llmStructured } from "./llm.js";
+import type { AppDriver, DriverContext, DriverResult } from "./driver.js";
+
+export type RecoveryPolicy = {
+  enabled?: boolean;
+  maxAttempts?: number;
+  timeoutMs?: number;
+};
+
+export type RecoveryResult = {
+  result: DriverResult;
+  attempts: number;
+  explanation?: string;
+};
+
+type RecoveryDecision = {
+  retry?: boolean;
+  reason?: string;
+};
+
+function parseDecision(text: string): RecoveryDecision {
+  try {
+    const parsed = JSON.parse(text) as RecoveryDecision;
+    return { retry: parsed.retry === true, reason: parsed.reason };
+  } catch {
+    return { retry: false, reason: "LLM recovery response was not valid JSON." };
+  }
+}
+
+export async function recoverDriverFailure(
+  driver: AppDriver,
+  context: DriverContext,
+  initial: DriverResult,
+  policy: RecoveryPolicy = {},
+): Promise<RecoveryResult> {
+  if (!policy.enabled || !initial.recoverable) return { result: initial, attempts: 0 };
+  const maxAttempts = Math.max(0, Math.min(policy.maxAttempts ?? 1, 3));
+  let result = initial;
+  let attempts = 0;
+  let explanation: string | undefined;
+
+  while (attempts < maxAttempts && result.status !== "passed") {
+    attempts++;
+    try {
+      const response = await llmStructured(
+        [
+          "Classify whether this application E2E failure is safe to retry once.",
+          "Return JSON only: {\"retry\": boolean, \"reason\": string}.",
+          "Only retry transient UI/driver blockers. Never retry destructive or invariant failures.",
+          `Driver: ${driver.id}`,
+          `Platform: ${context.platform}`,
+          `Failure code: ${result.failureCode || "unknown"}`,
+          `Failure message: ${result.message}`,
+          `stderr: ${(result.stderr || "").slice(0, 4000)}`,
+        ].join("\n"),
+        { timeout: policy.timeoutMs ?? 30_000 },
+      );
+      const decision = parseDecision(response.text);
+      explanation = decision.reason;
+      if (!decision.retry) break;
+      result = await driver.run(context);
+    } catch (error) {
+      explanation = error instanceof Error ? error.message : "LLM recovery failed";
+      break;
+    }
+  }
+
+  return { result, attempts, explanation };
+}

package/src/runtime/driver.ts

@@ -0,0 +1,79 @@
+import type { RunTarget } from "./browser-matrix.js";
+
+export type DriverPlatform = "web" | "android" | "ios";
+
+export type DriverTarget = {
+  baseUrl?: string;
+  appId?: string;
+  deviceId?: string;
+  serial?: string;
+};
+
+export type DriverContext = {
+  runId: string;
+  projectId: string;
+  journeyId: string;
+  flowPath: string;
+  platform: DriverPlatform;
+  target: DriverTarget;
+  timeoutMs: number;
+  artifactsDir: string;
+  environment?: Record<string, string>;
+  /**
+   * Browser session state (cookies and local storage) shared across the flows
+   * of one suite, so a multi-flow journey can stay signed in the way a person
+   * would. Drivers that cannot carry session state ignore it.
+   */
+  sessionStatePath?: string;
+  /** Browser/device to run a web flow on. Drivers without a browser matrix ignore it. */
+  runTarget?: RunTarget;
+  /**
+   * When true, an absolute URL in the flow is moved onto target.baseUrl's
+   * origin (path kept), so a flow authored against one host runs against the
+   * selected environment.
+   */
+  rebaseOrigin?: boolean;
+};
+
+export type DriverArtifact = {
+  path: string;
+  contentType?: string;
+  name?: string;
+};
+
+/**
+ * Real, independently-observed outcome for a single flow step. Optional:
+ * drivers that cannot attribute pass/fail to individual steps simply omit
+ * `steps`, and callers must not fabricate one from the aggregate result.
+ */
+export type DriverStepResult = {
+  sequenceNumber: number;
+  status: "passed" | "failed" | "blocked";
+  /** What the step does, in words a person reads in a trace. Typed text is masked. */
+  label?: string;
+  message?: string;
+  durationMs?: number;
+  timestamp?: string;
+  screenshotPath?: string;
+};
+
+export type DriverResult = {
+  status: "passed" | "failed" | "blocked";
+  exitCode?: number;
+  message: string;
+  stdout?: string;
+  stderr?: string;
+  artifacts: DriverArtifact[];
+  recoverable?: boolean;
+  failureCode?: string;
+  /** Per-step outcomes, when the driver can observe them independently. */
+  steps?: DriverStepResult[];
+  /** Wall-clock time the driver spent on the flow. */
+  durationMs?: number;
+};
+
+export interface AppDriver {
+  readonly id: string;
+  supports(platform: DriverPlatform): boolean;
+  run(context: DriverContext): Promise<DriverResult>;
+}

package/src/runtime/environment.test.ts

@@ -0,0 +1,104 @@
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import test from "node:test";
+import { getEnvironmentContract, setEnvironmentContract } from "./environment.js";
+
+test("environment contracts persist runnable access metadata without credentials", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-environment-"));
+  try {
+    const cfg = {
+      project: { id: "qa-framework" },
+      runtime: { artifacts_dir: directory },
+      storage: { provider: "local", localDirectory: directory },
+    };
+    const saved = await setEnvironmentContract(cfg, {
+      environmentId: "android-local",
+      name: "Lumis Nokia",
+      platform: "android",
+      baseUrl: "http://127.0.0.1:8083",
+      mockUrl: "https://gcore.otlrs.com/lumis-consumer/",
+      status: "active",
+      access: {
+        transport: "adb",
+        deviceLabel: "Nokia",
+        serialHint: "DRGGAM58B1004777",
+        appPackage: "com.lumis.consumer",
+        startCommand: "adb -s DRGGAM58B1004777 shell monkey -p com.lumis.consumer 1",
+      },
+    });
+    const loaded = await getEnvironmentContract(cfg, "android-local");
+    assert.equal(loaded?.environmentId, saved.environmentId);
+    // Regression: setEnvironmentContract's type declared platform/driver/
+    // flowPath but the setter silently dropped them before persisting.
+    assert.equal(loaded?.platform, "android");
+    assert.equal(loaded?.mockUrl, saved.mockUrl);
+    assert.equal(loaded?.access.startCommand, saved.access.startCommand);
+    assert.equal("apiKey" in saved, false);
+    assert.equal("secret" in saved, false);
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("re-registering the same base URL under a different id reuses the original environment", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-environment-dedupe-"));
+  try {
+    const cfg = {
+      project: { id: "bugmole" },
+      runtime: { artifacts_dir: directory },
+      storage: { provider: "local", localDirectory: directory },
+    };
+    // Exactly the real failure: each exploration run invented a new
+    // synonym for the same localhost target, leaving four identical records.
+    const first = await setEnvironmentContract(cfg, {
+      environmentId: "local",
+      name: "Local QA Dashboard",
+      baseUrl: "http://localhost:3020",
+      access: { transport: "browser" },
+    });
+    for (const alias of ["local-dev", "browser-local", "local-browser"]) {
+      const again = await setEnvironmentContract(cfg, {
+        environmentId: alias,
+        name: "Local QA Dashboard",
+        baseUrl: "http://localhost:3020",
+        access: { transport: "browser" },
+      });
+      assert.equal(again.environmentId, first.environmentId, `${alias} must fold into the canonical id`);
+    }
+
+    const files = await fs.readdir(path.join(directory, "projects", "bugmole", "environments"));
+    assert.deepEqual(files, ["local.json"], "only one environment record should exist");
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});
+
+test("a genuinely different target still registers as its own environment", async () => {
+  const directory = await fs.mkdtemp(path.join(os.tmpdir(), "bugmole-environment-distinct-"));
+  try {
+    const cfg = {
+      project: { id: "bugmole" },
+      runtime: { artifacts_dir: directory },
+      storage: { provider: "local", localDirectory: directory },
+    };
+    await setEnvironmentContract(cfg, {
+      environmentId: "local",
+      name: "Local",
+      baseUrl: "http://localhost:3020",
+      access: { transport: "browser" },
+    });
+    const staging = await setEnvironmentContract(cfg, {
+      environmentId: "staging",
+      name: "Staging",
+      baseUrl: "https://staging.example.com",
+      access: { transport: "browser" },
+    });
+    assert.equal(staging.environmentId, "staging");
+    const files = await fs.readdir(path.join(directory, "projects", "bugmole", "environments"));
+    assert.equal(files.length, 2);
+  } finally {
+    await fs.rm(directory, { recursive: true, force: true });
+  }
+});

package/src/runtime/environment.ts

@@ -0,0 +1,137 @@
+import { createProjectObjectStore } from "../storage/create-object-store.js";
+import { projectPrefix } from "../storage/keys.js";
+
+export type EnvironmentAccessContract = {
+  environmentId: string;
+  name: string;
+  platform?: "web" | "android" | "ios";
+  driver?: string;
+  flowPath?: string;
+  baseUrl?: string;
+  mockUrl?: string;
+  status: "active" | "blocked" | "planned";
+  access: {
+    transport: "adb" | "browser" | "manual" | "unknown";
+    deviceLabel?: string;
+    serialHint?: string;
+    appPackage?: string;
+    appId?: string;
+    baseUrl?: string;
+    startCommand?: string;
+    notes?: string;
+  };
+  lastVerifiedAt?: string;
+  blockedReason?: string;
+};
+
+function key(cfg: any, environmentId: string): string {
+  return `${projectPrefix(cfg.project?.id ?? "default")}/environments/${encodeURIComponent(environmentId)}.json`;
+}
+
+function environmentsPrefix(cfg: any): string {
+  return `${projectPrefix(cfg.project?.id ?? "default")}/environments/`;
+}
+
+/**
+ * What actually makes two environment records the same environment: the
+ * thing they point at, not the id someone chose for them.
+ */
+function environmentTarget(contract: Partial<EnvironmentAccessContract>): string | null {
+  const transport = contract.access?.transport ?? "unknown";
+  if (transport === "adb") {
+    const device = contract.access?.serialHint ?? contract.access?.deviceLabel;
+    return device ? `adb:${device}` : null;
+  }
+  const baseUrl = (contract.baseUrl ?? contract.access?.baseUrl)?.trim().replace(/\/+$/, "");
+  return baseUrl ? `url:${baseUrl.toLowerCase()}` : null;
+}
+
+/**
+ * Find an already-registered environment pointing at the same target.
+ *
+ * The environment id is agent-chosen, and an LLM picks a different
+ * plausible synonym on each run — this project accumulated four identical
+ * records (`local`, `local-dev`, `browser-local`, `local-browser`), all
+ * http://localhost:3020, one per exploration attempt. Resolving by target
+ * keeps re-registration idempotent so a repeating pipeline can't multiply
+ * them further.
+ */
+export async function findEnvironmentByTarget(
+  cfg: any,
+  contract: Partial<EnvironmentAccessContract>,
+): Promise<EnvironmentAccessContract | null> {
+  const target = environmentTarget(contract);
+  if (!target) return null;
+  const store = createProjectObjectStore(cfg);
+  let entries: Array<{ key: string }>;
+  try {
+    entries = await store.list(environmentsPrefix(cfg));
+  } catch {
+    return null;
+  }
+  const matches: EnvironmentAccessContract[] = [];
+  for (const entry of entries) {
+    if (!entry.key.endsWith(".json")) continue;
+    try {
+      const existing = JSON.parse(await store.getText(entry.key)) as EnvironmentAccessContract;
+      if (environmentTarget(existing) === target) matches.push(existing);
+    } catch {
+      // A malformed record must not block registration.
+    }
+  }
+  if (matches.length === 0) return null;
+  // Oldest wins, so the canonical id stays stable once chosen.
+  matches.sort((a, b) => (a.lastVerifiedAt ?? "").localeCompare(b.lastVerifiedAt ?? ""));
+  return matches[0];
+}
+
+export async function getEnvironmentContract(
+  cfg: any,
+  environmentId: string,
+): Promise<EnvironmentAccessContract | null> {
+  const store = createProjectObjectStore(cfg);
+  try {
+    return JSON.parse(await store.getText(key(cfg, environmentId))) as EnvironmentAccessContract;
+  } catch {
+    return null;
+  }
+}
+
+export async function setEnvironmentContract(
+  cfg: any,
+  input: Partial<EnvironmentAccessContract> & { environmentId: string },
+): Promise<EnvironmentAccessContract> {
+  if (!input.environmentId.trim()) throw new Error("environmentId is required");
+  if (!input.name?.trim()) throw new Error("name is required");
+  if (input.baseUrl && !/^https?:\/\//.test(input.baseUrl)) throw new Error("baseUrl must be an HTTP(S) URL");
+  if (input.mockUrl && !/^https?:\/\//.test(input.mockUrl)) throw new Error("mockUrl must be an HTTP(S) URL");
+  // Re-registering the same target updates the record that already exists
+  // rather than minting a second one under a new synonym for its id.
+  const existing = await findEnvironmentByTarget(cfg, input);
+  const canonicalId = existing && existing.environmentId !== input.environmentId.trim()
+    ? existing.environmentId
+    : input.environmentId.trim();
+  const contract: EnvironmentAccessContract = {
+    environmentId: canonicalId,
+    name: input.name.trim(),
+    platform: input.platform,
+    driver: input.driver,
+    flowPath: input.flowPath,
+    baseUrl: input.baseUrl?.trim(),
+    mockUrl: input.mockUrl?.trim(),
+    status: input.status ?? "planned",
+    access: {
+      transport: input.access?.transport ?? "unknown",
+      deviceLabel: input.access?.deviceLabel,
+      serialHint: input.access?.serialHint,
+      appPackage: input.access?.appPackage,
+      startCommand: input.access?.startCommand,
+      notes: input.access?.notes,
+    },
+    lastVerifiedAt: input.lastVerifiedAt ?? new Date().toISOString(),
+    blockedReason: input.blockedReason,
+  };
+  const store = createProjectObjectStore(cfg);
+  await store.put(key(cfg, contract.environmentId), JSON.stringify(contract, null, 2) + "\n", "application/json");
+  return contract;
+}