@pickforge/picklab 0.1.0

package/dist/picklab.js

@@ -0,0 +1,3164 @@
+#!/usr/bin/env node
+import {
+  agentsDir,
+  back,
+  buildCreateAvdArgs,
+  captureToTarget,
+  clearLogcat,
+  click,
+  createAndroidSession,
+  createDesktopSession,
+  deepMerge,
+  desktopSessionLogDir,
+  destroyAndroidSession,
+  destroyDesktopSession,
+  detectAndroidEnvironment,
+  detectScreenshotTool,
+  detectVncBinary,
+  ensureDir,
+  findOnPath,
+  findOnPath2,
+  getAndroidSessionStatus,
+  getDesktopSessionStatus,
+  getSession,
+  getUiTree,
+  globalConfigPath,
+  home,
+  installApk,
+  isValidSystemImageId,
+  launchApp,
+  launchApp2,
+  listAvds,
+  listRuns,
+  listSessions,
+  loadConfig,
+  logcat,
+  missingSdkMessage,
+  picklabHome,
+  pressKey,
+  projectConfigPath,
+  readConfigFile,
+  redactSecrets,
+  requireDisplay,
+  resolveRunnableSession,
+  resolveScreenshotTarget,
+  resolvedDefaults,
+  runAdb,
+  runCommand,
+  runMcpServe,
+  runsDir,
+  saveGlobalConfig,
+  saveProjectConfig,
+  screenshot,
+  screenshot2,
+  sdkmanagerInstallCommand,
+  tap,
+  typeText,
+  typeText2,
+  waitForWindow
+} from "./chunk-SGSRIPSM.js";
+
+// src/program.ts
+import { createRequire } from "module";
+import { Command, Option } from "commander";
+
+// src/commands/android.ts
+import path2 from "path";
+import fs from "fs";
+
+// src/commands/shared.ts
+import path from "path";
+function resolveProjectDir(opts) {
+  return path.resolve(opts.projectDir ?? process.cwd());
+}
+function parseIntArg(value, label) {
+  if (!/^\d+$/.test(value)) {
+    throw new Error(
+      `Invalid ${label} "${value}": expected a non-negative integer`
+    );
+  }
+  return Number(value);
+}
+async function runReported(opts, fn) {
+  let result;
+  try {
+    result = await fn();
+  } catch (error) {
+    result = {
+      errors: [error instanceof Error ? error.message : String(error)]
+    };
+  }
+  const errors = result.errors ?? [];
+  const report = { ok: errors.length === 0 };
+  for (const [key, value] of Object.entries(result.data ?? {})) {
+    if (key !== "ok" && key !== "errors") {
+      report[key] = value;
+    }
+  }
+  report.errors = errors;
+  if (opts.json === true) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    for (const line of result.lines ?? []) {
+      console.log(line);
+    }
+    for (const error of errors) {
+      console.error(`error: ${error}`);
+    }
+  }
+  return errors.length === 0 ? 0 : 1;
+}
+async function resolveSessionRecord(type, opts, env = process.env) {
+  return resolveRunnableSession(type, opts.session, {
+    env,
+    projectDir: resolveProjectDir(opts),
+    consumerLabel: "command",
+    createHint: `create one with: picklab session create --type ${type}`,
+    selectHint: "pick one with --session <id>"
+  });
+}
+async function resolveScreenshotTarget2(opts, defaultSlug, sessionId) {
+  return resolveScreenshotTarget({
+    projectDir: resolveProjectDir(opts),
+    out: opts.out,
+    runSlug: opts.run,
+    defaultSlug,
+    sessionId,
+    conflictError: "use either --out or --run, not both"
+  });
+}
+
+// src/commands/android.ts
+async function resolveAndroidTarget(opts) {
+  if (opts.serial !== void 0 && opts.session !== void 0) {
+    throw new Error("Pass either --session or --serial, not both");
+  }
+  if (opts.serial !== void 0) {
+    return { serial: opts.serial };
+  }
+  const record = await resolveSessionRecord("android", opts);
+  const serial = record.android?.serial;
+  if (serial === void 0) {
+    throw new Error(`Session ${record.id} has no device serial recorded`);
+  }
+  return { serial, sessionId: record.id };
+}
+function targetData(target) {
+  const data = { serial: target.serial };
+  if (target.sessionId !== void 0) {
+    data.sessionId = target.sessionId;
+  }
+  return data;
+}
+async function runAndroidInstallApk(apk, opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    const apkPath = path2.resolve(apk);
+    await installApk({ serial: target.serial, apkPath });
+    return {
+      data: { ...targetData(target), apkPath },
+      lines: [`installed ${apkPath} on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidLaunchApp(packageName, opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    await launchApp({
+      serial: target.serial,
+      packageName,
+      activity: opts.activity
+    });
+    return {
+      data: { ...targetData(target), packageName },
+      lines: [`launched ${packageName} on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidScreenshot(opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    const destination = await resolveScreenshotTarget2(
+      opts,
+      "android",
+      target.sessionId
+    );
+    const data = await captureToTarget(destination, async () => {
+      await screenshot({ serial: target.serial, outPath: destination.outPath });
+    });
+    Object.assign(data, targetData(target));
+    const lines = [`screenshot saved to ${destination.outPath}`];
+    if (data.runId !== void 0) {
+      lines.push(`run: ${data.runId}`);
+    }
+    return { data, lines };
+  });
+}
+async function runAndroidTap(x, y, opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    const parsedX = parseIntArg(x, "x");
+    const parsedY = parseIntArg(y, "y");
+    await tap({ serial: target.serial, x: parsedX, y: parsedY });
+    return {
+      data: { ...targetData(target), x: parsedX, y: parsedY },
+      lines: [`tapped (${parsedX}, ${parsedY}) on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidType(text, opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    await typeText({ serial: target.serial, text });
+    return {
+      data: { ...targetData(target), length: text.length },
+      lines: [`typed ${text.length} character(s) on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidBack(opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    await back({ serial: target.serial });
+    return {
+      data: targetData(target),
+      lines: [`pressed back on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidHome(opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    await home({ serial: target.serial });
+    return {
+      data: targetData(target),
+      lines: [`pressed home on ${target.serial}`]
+    };
+  });
+}
+async function runAndroidUiTree(opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    const xml = redactSecrets(await getUiTree({ serial: target.serial }));
+    if (opts.out !== void 0) {
+      const outPath = path2.resolve(opts.out);
+      await fs.promises.mkdir(path2.dirname(outPath), { recursive: true });
+      await fs.promises.writeFile(outPath, `${xml}
+`, "utf8");
+      return {
+        data: { ...targetData(target), path: outPath },
+        lines: [`ui tree saved to ${outPath}`]
+      };
+    }
+    return { data: { ...targetData(target), xml }, lines: [xml] };
+  });
+}
+async function runAndroidLogcat(opts) {
+  return runReported(opts, async () => {
+    const target = await resolveAndroidTarget(opts);
+    if (opts.clear === true) {
+      await clearLogcat({ serial: target.serial });
+      return {
+        data: { ...targetData(target), cleared: true },
+        lines: [`cleared logcat buffer on ${target.serial}`]
+      };
+    }
+    const output = redactSecrets(
+      await logcat({
+        serial: target.serial,
+        lines: opts.lines === void 0 ? void 0 : parseIntArg(opts.lines, "--lines"),
+        filter: opts.filter
+      })
+    );
+    return {
+      data: { ...targetData(target), output },
+      lines: [output.replace(/\n$/, "")]
+    };
+  });
+}
+async function runAndroidAdb(args, opts) {
+  try {
+    let serial;
+    let sessionId;
+    if (opts.serial !== void 0 || opts.session !== void 0) {
+      ({ serial, sessionId } = await resolveAndroidTarget(opts));
+    } else {
+      const implicit = await resolveAndroidTarget(opts).then(
+        (target) => target,
+        async (error) => {
+          const message = error instanceof Error ? error.message : String(error);
+          if (!message.startsWith("No running android session")) {
+            throw error;
+          }
+          const running = (await listSessions()).filter(
+            (record) => record.type === "android" && record.status === "running"
+          );
+          if (running.length > 0) {
+            throw new Error(
+              "No running android session for this project, but other projects have running android sessions. Pass --session <id> or --serial <serial>, or run the command from the project that owns the session."
+            );
+          }
+          return void 0;
+        }
+      );
+      serial = implicit?.serial;
+      sessionId = implicit?.sessionId;
+    }
+    const result = await runAdb(
+      serial === void 0 ? { args } : { serial, args }
+    );
+    if (opts.json === true) {
+      const report = {
+        ok: result.ok,
+        code: result.code,
+        stdout: result.stdout,
+        stderr: result.stderr,
+        errors: result.ok ? [] : [`adb exited with code ${result.code}`]
+      };
+      if (serial !== void 0) report.serial = serial;
+      if (sessionId !== void 0) report.sessionId = sessionId;
+      console.log(JSON.stringify(report, null, 2));
+    } else {
+      if (result.stdout !== "") process.stdout.write(result.stdout);
+      if (result.stderr !== "") process.stderr.write(result.stderr);
+    }
+    return result.ok ? 0 : result.code ?? 1;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    if (opts.json === true) {
+      console.log(JSON.stringify({ ok: false, errors: [message] }, null, 2));
+    } else {
+      console.error(`error: ${message}`);
+    }
+    return 1;
+  }
+}
+
+// src/commands/artifacts.ts
+import { spawn } from "child_process";
+import path3 from "path";
+async function runArtifactsList(opts) {
+  return runReported(opts, async () => {
+    const projectDir = resolveProjectDir(opts);
+    const manifests = await listRuns(projectDir);
+    const runs = manifests.map((manifest) => ({
+      runId: manifest.runId,
+      slug: manifest.slug,
+      createdAt: manifest.createdAt,
+      status: manifest.status,
+      artifacts: manifest.artifacts.length
+    }));
+    return {
+      data: { projectDir, runs },
+      lines: runs.length === 0 ? [`no runs found under ${runsDir(projectDir)}`] : runs.map(
+        (run) => `${run.runId}  ${run.status}  ${run.artifacts} artifact(s)`
+      )
+    };
+  });
+}
+var RUN_ID_PATTERN = /^[A-Za-z0-9._-]+$/;
+function isSafeRunId(runId) {
+  return RUN_ID_PATTERN.test(runId) && runId !== "." && runId !== "..";
+}
+async function findRun(projectDir, runId) {
+  const manifests = (await listRuns(projectDir)).filter(
+    (candidate) => isSafeRunId(candidate.runId)
+  );
+  let manifest;
+  if (runId === void 0) {
+    manifest = manifests[0];
+    if (manifest === void 0) {
+      throw new Error(`No runs found under ${runsDir(projectDir)}`);
+    }
+  } else {
+    manifest = manifests.find((candidate) => candidate.runId === runId);
+    if (manifest === void 0) {
+      throw new Error(`Run not found: ${runId} (see: picklab artifacts list)`);
+    }
+  }
+  return { manifest, dir: path3.join(runsDir(projectDir), manifest.runId) };
+}
+async function runArtifactsOpen(runId, opts) {
+  return runReported(opts, async () => {
+    const projectDir = resolveProjectDir(opts);
+    const { manifest, dir } = await findRun(projectDir, runId);
+    let opened = false;
+    const display = process.env.DISPLAY;
+    if (opts.json !== true && display !== void 0 && display !== "") {
+      const xdgOpen = findOnPath2("xdg-open");
+      if (xdgOpen !== null) {
+        const child = spawn(xdgOpen, [dir], {
+          detached: true,
+          stdio: "ignore"
+        });
+        child.on("error", () => {
+        });
+        child.unref();
+        opened = true;
+      }
+    }
+    return {
+      data: { runId: manifest.runId, dir, opened },
+      lines: [dir]
+    };
+  });
+}
+function renderRunReport(manifest, dir) {
+  const lines = [
+    `# PickLab run ${manifest.runId}`,
+    "",
+    `- Slug: ${manifest.slug}`,
+    `- Status: ${manifest.status}`,
+    `- Created: ${manifest.createdAt}`
+  ];
+  if (manifest.sessionId !== void 0) {
+    lines.push(`- Session: ${manifest.sessionId}`);
+  }
+  lines.push(
+    `- Directory: ${dir}`,
+    "",
+    `## Artifacts (${manifest.artifacts.length})`,
+    ""
+  );
+  if (manifest.artifacts.length === 0) {
+    lines.push("(none)");
+  }
+  for (const artifact of manifest.artifacts) {
+    lines.push(
+      `- [${artifact.type}] ${artifact.name} \u2014 ${artifact.path} (${artifact.createdAt})`
+    );
+  }
+  return lines;
+}
+async function runArtifactsReport(runId, opts) {
+  return runReported(opts, async () => {
+    const projectDir = resolveProjectDir(opts);
+    const { manifest, dir } = await findRun(projectDir, runId);
+    return {
+      data: { runId: manifest.runId, dir, manifest },
+      lines: renderRunReport(manifest, dir)
+    };
+  });
+}
+
+// src/commands/agents.ts
+import fs10 from "fs";
+
+// ../agent-installers/dist/index.js
+import fs2 from "fs";
+import path4 from "path";
+import fs22 from "fs";
+import path22 from "path";
+import fs3 from "fs";
+import path32 from "path";
+import fs4 from "fs";
+import fs5 from "fs";
+import fs6 from "fs";
+import fs7 from "fs";
+import path42 from "path";
+import os from "os";
+import path5 from "path";
+import path6 from "path";
+import fs8 from "fs";
+import path7 from "path";
+import fs9 from "fs";
+import path8 from "path";
+var AGENT_KINDS = [
+  "codex",
+  "claude-code",
+  "cursor"
+];
+var tmpCounter = 0;
+async function writeFileAtomic(filePath, content) {
+  const dir = path4.dirname(filePath);
+  await fs2.promises.mkdir(dir, { recursive: true });
+  tmpCounter += 1;
+  const tmp = path4.join(
+    dir,
+    `.${path4.basename(filePath)}.tmp-${process.pid}-${tmpCounter}`
+  );
+  let mode;
+  try {
+    mode = (await fs2.promises.stat(filePath)).mode & 511;
+  } catch (error) {
+    const code = error.code;
+    if (code !== "ENOENT" && code !== "ENOTDIR") {
+      throw error;
+    }
+  }
+  try {
+    await fs2.promises.writeFile(tmp, content, { encoding: "utf8", mode });
+    if (mode !== void 0) {
+      await fs2.promises.chmod(tmp, mode);
+    }
+    await fs2.promises.rename(tmp, filePath);
+  } catch (error) {
+    await fs2.promises.rm(tmp, { force: true });
+    throw error;
+  }
+}
+function isPlainObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function agentsStatePath(env = process.env) {
+  return path22.join(agentsDir(env), "state.json");
+}
+async function readAgentsState(env = process.env) {
+  let raw;
+  try {
+    raw = await fs22.promises.readFile(agentsStatePath(env), "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { agents: {} };
+    }
+    throw error;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return { agents: {} };
+  }
+  if (!isPlainObject(parsed) || !isPlainObject(parsed.agents)) {
+    return { agents: {} };
+  }
+  const agents = {};
+  for (const [name, value] of Object.entries(parsed.agents)) {
+    if (isPlainObject(value) && typeof value.registered === "boolean" && typeof value.configPath === "string") {
+      agents[name] = {
+        registered: value.registered,
+        configPath: value.configPath,
+        updatedAt: typeof value.updatedAt === "string" ? value.updatedAt : ""
+      };
+    }
+  }
+  return { agents };
+}
+async function recordAgentState(name, entry, env = process.env, now = /* @__PURE__ */ new Date()) {
+  const state = await readAgentsState(env);
+  state.agents[name] = { ...entry, updatedAt: now.toISOString() };
+  await writeFileAtomic(
+    agentsStatePath(env),
+    `${JSON.stringify(state, null, 2)}
+`
+  );
+}
+var MCP_SERVER_NAME = "picklab";
+var SHARED_SNIPPET_BASENAMES = [
+  "picklab-mcp.json",
+  "picklab-mcp.toml"
+];
+function mcpServerEntry() {
+  return { command: "picklab", args: ["mcp", "serve"] };
+}
+function renderJsonSnippet(entry = mcpServerEntry()) {
+  const snippet = {
+    mcpServers: {
+      [MCP_SERVER_NAME]: { command: entry.command, args: entry.args }
+    }
+  };
+  return `${JSON.stringify(snippet, null, 2)}
+`;
+}
+function renderTomlSnippet(entry = mcpServerEntry()) {
+  const args = entry.args.map((arg) => JSON.stringify(arg)).join(", ");
+  return `[mcp_servers.${MCP_SERVER_NAME}]
+command = ${JSON.stringify(entry.command)}
+args = [${args}]
+`;
+}
+async function writeSharedSnippets(env = process.env) {
+  const dir = await ensureDir(agentsDir(env));
+  const jsonPath = path32.join(dir, SHARED_SNIPPET_BASENAMES[0]);
+  const tomlPath = path32.join(dir, SHARED_SNIPPET_BASENAMES[1]);
+  await fs3.promises.writeFile(jsonPath, renderJsonSnippet(), "utf8");
+  await fs3.promises.writeFile(tomlPath, renderTomlSnippet(), "utf8");
+  return { jsonPath, tomlPath };
+}
+var BACKUP_PATTERN = /\.picklab-backup-\d{8}-\d{6}(-\d+)?$/;
+function timestamp(now) {
+  const pad = (value) => String(value).padStart(2, "0");
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+function isBackupPath(filePath) {
+  return BACKUP_PATTERN.test(filePath);
+}
+async function backupFile(filePath, now = /* @__PURE__ */ new Date()) {
+  const base = `${filePath}.picklab-backup-${timestamp(now)}`;
+  let candidate = base;
+  for (let attempt = 2; ; attempt += 1) {
+    try {
+      await fs4.promises.copyFile(
+        filePath,
+        candidate,
+        fs4.constants.COPYFILE_EXCL
+      );
+      return candidate;
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        return void 0;
+      }
+      if (code !== "EEXIST") {
+        throw error;
+      }
+    }
+    candidate = `${base}-${attempt}`;
+  }
+}
+function isPlainObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function readTextIfExists(filePath) {
+  try {
+    return await fs5.promises.readFile(filePath, "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+async function readJsonObject(filePath) {
+  const raw = await readTextIfExists(filePath);
+  if (raw === void 0) {
+    return void 0;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (error) {
+    throw new Error(
+      `Refusing to edit ${filePath}: invalid JSON (${error.message}). Fix the file and retry.`
+    );
+  }
+  if (!isPlainObject2(parsed)) {
+    throw new Error(
+      `Refusing to edit ${filePath}: expected a top-level JSON object`
+    );
+  }
+  return parsed;
+}
+async function writeJsonObject(filePath, value) {
+  await writeFileAtomic(filePath, `${JSON.stringify(value, null, 2)}
+`);
+}
+function entryMatches(current, entry) {
+  if (!isPlainObject2(current)) {
+    return false;
+  }
+  return current.command === entry.command && JSON.stringify(current.args) === JSON.stringify(entry.args);
+}
+async function mergeMcpServerIntoJsonFile(filePath, opts) {
+  const entry = opts.entry ?? mcpServerEntry();
+  const existing = await readJsonObject(filePath);
+  if (existing === void 0 && !opts.createIfMissing) {
+    throw new Error(`Config file not found: ${filePath}`);
+  }
+  const config = existing ?? {};
+  const servers = isPlainObject2(config.mcpServers) ? config.mcpServers : {};
+  if (entryMatches(servers[MCP_SERVER_NAME], entry)) {
+    return { configPath: filePath, changed: false };
+  }
+  const backupPath = existing === void 0 ? void 0 : await backupFile(filePath);
+  const next = {
+    ...config,
+    mcpServers: {
+      ...servers,
+      [MCP_SERVER_NAME]: { command: entry.command, args: entry.args }
+    }
+  };
+  await writeJsonObject(filePath, next);
+  return { configPath: filePath, changed: true, backupPath };
+}
+async function removeMcpServerFromJsonFile(filePath) {
+  const existing = await readJsonObject(filePath);
+  if (existing === void 0 || !isPlainObject2(existing.mcpServers) || !(MCP_SERVER_NAME in existing.mcpServers)) {
+    return { configPath: filePath, changed: false };
+  }
+  const backupPath = await backupFile(filePath);
+  const servers = { ...existing.mcpServers };
+  delete servers[MCP_SERVER_NAME];
+  const next = { ...existing };
+  if (Object.keys(servers).length === 0) {
+    delete next.mcpServers;
+  } else {
+    next.mcpServers = servers;
+  }
+  await writeJsonObject(filePath, next);
+  return { configPath: filePath, changed: true, backupPath };
+}
+async function jsonFileMcpServerState(filePath) {
+  let config;
+  try {
+    config = await readJsonObject(filePath);
+  } catch {
+    return "unknown";
+  }
+  if (config === void 0 || !isPlainObject2(config.mcpServers)) {
+    return false;
+  }
+  return isPlainObject2(config.mcpServers[MCP_SERVER_NAME]);
+}
+var TOML_MARKER_BEGIN = "# >>> picklab >>>";
+var TOML_MARKER_END = "# <<< picklab <<<";
+var SECTION_PATTERN = /^[ \t]*\[mcp_servers\.(?:picklab|"picklab")(?:\.[^\]\r\n]*)?\][ \t]*\r?$/m;
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function findMarkerLine(content, marker) {
+  const pattern = new RegExp(`^${escapeRegExp(marker)}[ \\t]*\\r?$`, "m");
+  const match = pattern.exec(content);
+  if (match === null) {
+    return void 0;
+  }
+  return { start: match.index, end: match.index + match[0].length };
+}
+async function readTextIfExists2(filePath) {
+  try {
+    return await fs6.promises.readFile(filePath, "utf8");
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return void 0;
+    }
+    throw error;
+  }
+}
+function markerBlock(entry) {
+  return `${TOML_MARKER_BEGIN}
+${renderTomlSnippet(entry)}${TOML_MARKER_END}
+`;
+}
+function splitMarkers(content, filePath) {
+  const begin = findMarkerLine(content, TOML_MARKER_BEGIN);
+  const end = findMarkerLine(content, TOML_MARKER_END);
+  if (begin === void 0 && end === void 0) {
+    return { before: content, block: void 0, after: "" };
+  }
+  if (begin === void 0 || end === void 0 || end.start < begin.start) {
+    throw new Error(
+      `Refusing to edit ${filePath}: unbalanced picklab markers ("${TOML_MARKER_BEGIN}" / "${TOML_MARKER_END}"). Fix the file and retry.`
+    );
+  }
+  let blockEnd = end.end;
+  if (content[blockEnd] === "\n") {
+    blockEnd += 1;
+  }
+  return {
+    before: content.slice(0, begin.start),
+    block: content.slice(begin.start, blockEnd),
+    after: content.slice(blockEnd)
+  };
+}
+function assertNoForeignSection(split, filePath) {
+  if (SECTION_PATTERN.test(split.before) || SECTION_PATTERN.test(split.after)) {
+    throw new Error(
+      `Refusing to edit ${filePath}: an [mcp_servers.picklab] section exists outside the picklab markers. Remove it (or move it between "${TOML_MARKER_BEGIN}" and "${TOML_MARKER_END}") and retry.`
+    );
+  }
+}
+async function upsertTomlMarkerBlock(filePath, entry) {
+  const existing = await readTextIfExists2(filePath);
+  const content = existing ?? "";
+  const split = splitMarkers(content, filePath);
+  assertNoForeignSection(split, filePath);
+  const desired = markerBlock(entry);
+  if (split.block === desired) {
+    return { configPath: filePath, changed: false };
+  }
+  let next;
+  if (split.block === void 0) {
+    const separator = content === "" ? "" : content.endsWith("\n") ? "\n" : "\n\n";
+    next = `${content}${separator}${desired}`;
+  } else {
+    next = `${split.before}${desired}${split.after}`;
+  }
+  const backupPath = existing === void 0 ? void 0 : await backupFile(filePath);
+  await writeFileAtomic(filePath, next);
+  return { configPath: filePath, changed: true, backupPath };
+}
+async function removeTomlMarkerBlock(filePath) {
+  const existing = await readTextIfExists2(filePath);
+  if (existing === void 0) {
+    return { configPath: filePath, changed: false };
+  }
+  const split = splitMarkers(existing, filePath);
+  if (split.block === void 0) {
+    return { configPath: filePath, changed: false };
+  }
+  const backupPath = await backupFile(filePath);
+  await writeFileAtomic(filePath, `${split.before}${split.after}`);
+  return { configPath: filePath, changed: true, backupPath };
+}
+async function inspectTomlFile(filePath) {
+  const existing = await readTextIfExists2(filePath);
+  if (existing === void 0) {
+    return {
+      exists: false,
+      markersPresent: false,
+      markersHaveSection: false,
+      foreignSection: false
+    };
+  }
+  let split;
+  try {
+    split = splitMarkers(existing, filePath);
+  } catch {
+    return {
+      exists: true,
+      markersPresent: true,
+      markersHaveSection: false,
+      foreignSection: false
+    };
+  }
+  return {
+    exists: true,
+    markersPresent: split.block !== void 0,
+    markersHaveSection: split.block !== void 0 && SECTION_PATTERN.test(split.block),
+    foreignSection: SECTION_PATTERN.test(split.before) || SECTION_PATTERN.test(split.after)
+  };
+}
+async function tomlFileHasMcpServer(filePath) {
+  const inspection = await inspectTomlFile(filePath);
+  return inspection.markersHaveSection || inspection.foreignSection;
+}
+function homeDir(env) {
+  const fromEnv = env.HOME;
+  if (fromEnv !== void 0 && fromEnv !== "") {
+    return fromEnv;
+  }
+  return os.homedir();
+}
+var CLAUDE_CODE_MANUAL_COMMAND = "claude mcp add --scope user picklab -- picklab mcp serve";
+var DIRECT_EDIT_WARNING = "the claude binary was not found on PATH, so the config file was edited directly; close Claude Code while linking, or it may overwrite the change";
+function claudeCodeConfigPath(env = process.env) {
+  return path42.join(homeDir(env), ".claude.json");
+}
+function findClaudeBinary(env = process.env) {
+  for (const dir of (env.PATH ?? "").split(path42.delimiter)) {
+    if (dir === "") {
+      continue;
+    }
+    const candidate = path42.join(dir, "claude");
+    try {
+      fs7.accessSync(candidate, fs7.constants.X_OK);
+      if (fs7.statSync(candidate).isFile()) {
+        return candidate;
+      }
+    } catch {
+      continue;
+    }
+  }
+  return void 0;
+}
+function commandFailure(action, result) {
+  const output = result.stderr.trim() || result.stdout.trim();
+  return new Error(
+    `"claude mcp ${action}" failed (exit code ${result.code ?? "unknown"})` + (output === "" ? "" : `: ${output}`)
+  );
+}
+async function claudeCodeIsRegistered(configPath) {
+  return jsonFileMcpServerState(configPath);
+}
+async function linkClaudeCode(configPath, env = process.env) {
+  const claudeBin = findClaudeBinary(env);
+  if (claudeBin !== void 0) {
+    const result2 = await runCommand(
+      claudeBin,
+      [
+        "mcp",
+        "add",
+        "--scope",
+        "user",
+        "picklab",
+        "--",
+        "picklab",
+        "mcp",
+        "serve"
+      ],
+      { env: { ...env }, cleanEnv: true }
+    );
+    if (!result2.ok) {
+      throw commandFailure("add", result2);
+    }
+    return { configPath, changed: true };
+  }
+  let exists = false;
+  try {
+    await fs7.promises.access(configPath, fs7.constants.F_OK);
+    exists = true;
+  } catch {
+    exists = false;
+  }
+  if (!exists) {
+    return {
+      configPath,
+      changed: false,
+      instructions: `Claude Code config not found at ${configPath}; register manually with: ${CLAUDE_CODE_MANUAL_COMMAND}`
+    };
+  }
+  const result = await mergeMcpServerIntoJsonFile(configPath, {
+    createIfMissing: false
+  });
+  return result.changed ? { ...result, warning: DIRECT_EDIT_WARNING } : result;
+}
+async function unlinkClaudeCode(configPath, env = process.env) {
+  const claudeBin = findClaudeBinary(env);
+  if (claudeBin !== void 0) {
+    const result2 = await runCommand(
+      claudeBin,
+      ["mcp", "remove", "--scope", "user", "picklab"],
+      { env: { ...env }, cleanEnv: true }
+    );
+    if (result2.ok) {
+      return { configPath, changed: true };
+    }
+    const output = `${result2.stdout}
+${result2.stderr}`.toLowerCase();
+    if (output.includes("not found") || output.includes("no mcp server")) {
+      return { configPath, changed: false };
+    }
+    throw commandFailure("remove", result2);
+  }
+  const result = await removeMcpServerFromJsonFile(configPath);
+  return result.changed ? { ...result, warning: DIRECT_EDIT_WARNING } : result;
+}
+function codexConfigPath(env = process.env) {
+  const codexHome = env.CODEX_HOME;
+  if (codexHome !== void 0 && codexHome !== "") {
+    return path5.join(codexHome, "config.toml");
+  }
+  return path5.join(homeDir(env), ".codex", "config.toml");
+}
+async function codexIsRegistered(configPath) {
+  return tomlFileHasMcpServer(configPath);
+}
+async function linkCodex(configPath) {
+  return upsertTomlMarkerBlock(configPath);
+}
+async function unlinkCodex(configPath) {
+  return removeTomlMarkerBlock(configPath);
+}
+function cursorConfigPath(env = process.env) {
+  return path6.join(homeDir(env), ".cursor", "mcp.json");
+}
+async function cursorIsRegistered(configPath) {
+  return jsonFileMcpServerState(configPath);
+}
+async function linkCursor(configPath) {
+  return mergeMcpServerIntoJsonFile(configPath, { createIfMissing: true });
+}
+async function unlinkCursor(configPath) {
+  return removeMcpServerFromJsonFile(configPath);
+}
+var BUILTIN_AGENTS = {
+  codex: {
+    name: "codex",
+    defaultConfigPath: codexConfigPath,
+    isRegistered: codexIsRegistered,
+    link: linkCodex,
+    unlink: unlinkCodex
+  },
+  "claude-code": {
+    name: "claude-code",
+    defaultConfigPath: claudeCodeConfigPath,
+    isRegistered: claudeCodeIsRegistered,
+    link: linkClaudeCode,
+    unlink: unlinkClaudeCode
+  },
+  cursor: {
+    name: "cursor",
+    defaultConfigPath: cursorConfigPath,
+    isRegistered: cursorIsRegistered,
+    link: linkCursor,
+    unlink: unlinkCursor
+  }
+};
+function builtinAgent(name) {
+  return Object.prototype.hasOwnProperty.call(BUILTIN_AGENTS, name) ? BUILTIN_AGENTS[name] : void 0;
+}
+var NAME_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+var RESERVED_NAMES = /* @__PURE__ */ new Set([
+  ...AGENT_KINDS,
+  "state",
+  ...SHARED_SNIPPET_BASENAMES.map(
+    (basename) => basename.replace(/\.[^.]+$/, "")
+  )
+]);
+function validateCustomAgentName(name) {
+  if (!NAME_PATTERN.test(name)) {
+    throw new Error(
+      `Invalid agent name "${name}": use letters, digits, ".", "_", or "-" (must start with a letter or digit)`
+    );
+  }
+  if (RESERVED_NAMES.has(name)) {
+    throw new Error(`Agent name "${name}" is reserved`);
+  }
+  return name;
+}
+function parseMcpCommand(input) {
+  const parts = input.trim().split(/\s+/).filter((part) => part !== "");
+  const command = parts[0];
+  if (command === void 0) {
+    throw new Error("--mcp-command must not be empty");
+  }
+  return { command, args: parts.slice(1) };
+}
+function customAgentConfigPath(name, env = process.env) {
+  return path7.join(agentsDir(env), `${name}.json`);
+}
+async function addCustomAgent(opts, env = process.env) {
+  const name = validateCustomAgentName(opts.name);
+  const entry = parseMcpCommand(opts.mcpCommand);
+  await ensureDir(agentsDir(env));
+  const configPath = customAgentConfigPath(name, env);
+  if (opts.force !== true) {
+    let exists = false;
+    try {
+      await fs8.promises.access(configPath, fs8.constants.F_OK);
+      exists = true;
+    } catch {
+      exists = false;
+    }
+    if (exists) {
+      throw new Error(
+        `Custom agent "${name}" already exists at ${configPath} (re-run with --force to overwrite)`
+      );
+    }
+  }
+  await writeFileAtomic(configPath, renderJsonSnippet(entry));
+  return { name, configPath, entry };
+}
+function isPlainObject3(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function entryFromSnippet(raw) {
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return void 0;
+  }
+  if (!isPlainObject3(parsed) || !isPlainObject3(parsed.mcpServers)) {
+    return void 0;
+  }
+  const entry = parsed.mcpServers[MCP_SERVER_NAME];
+  if (!isPlainObject3(entry) || typeof entry.command !== "string") {
+    return void 0;
+  }
+  const args = Array.isArray(entry.args) ? entry.args.filter((arg) => typeof arg === "string") : [];
+  return { command: entry.command, args };
+}
+async function listCustomAgents(env = process.env) {
+  let entries;
+  try {
+    entries = await fs8.promises.readdir(agentsDir(env));
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return [];
+    }
+    throw error;
+  }
+  const sharedBasenames = new Set(SHARED_SNIPPET_BASENAMES);
+  const agents = [];
+  for (const basename of entries.sort()) {
+    if (!basename.endsWith(".json") || sharedBasenames.has(basename)) {
+      continue;
+    }
+    const configPath = path7.join(agentsDir(env), basename);
+    let raw;
+    try {
+      raw = await fs8.promises.readFile(configPath, "utf8");
+    } catch {
+      continue;
+    }
+    const entry = entryFromSnippet(raw);
+    if (entry === void 0) {
+      continue;
+    }
+    agents.push({ name: basename.slice(0, -".json".length), configPath, entry });
+  }
+  return agents;
+}
+async function removeCustomAgent(name, env = process.env) {
+  const configPath = customAgentConfigPath(validateCustomAgentName(name), env);
+  try {
+    await fs8.promises.unlink(configPath);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      return { configPath, changed: false };
+    }
+    throw error;
+  }
+  return { configPath, changed: true };
+}
+var BACKUP_CLUTTER_THRESHOLD = 3;
+async function checkAgentsDir(env, checks) {
+  const dir = agentsDir(env);
+  let entries;
+  try {
+    entries = await fs9.promises.readdir(dir);
+  } catch (error) {
+    const code = error.code;
+    if (code === "ENOENT" || code === "ENOTDIR") {
+      checks.push({
+        id: "agents-dir",
+        status: "ok",
+        detail: `${dir} does not exist yet (created on first link)`
+      });
+      return;
+    }
+    throw error;
+  }
+  const broken = [];
+  for (const basename of entries.sort()) {
+    const entryPath = path8.join(dir, basename);
+    let stat;
+    try {
+      stat = await fs9.promises.lstat(entryPath);
+    } catch (error) {
+      const code = error.code;
+      if (code === "ENOENT" || code === "ENOTDIR") {
+        continue;
+      }
+      throw error;
+    }
+    if (!stat.isSymbolicLink()) {
+      continue;
+    }
+    try {
+      await fs9.promises.stat(entryPath);
+    } catch {
+      broken.push(entryPath);
+    }
+  }
+  if (broken.length > 0) {
+    checks.push({
+      id: "agents-dir",
+      status: "problem",
+      detail: `broken symlink(s): ${broken.join(", ")}`
+    });
+    return;
+  }
+  checks.push({ id: "agents-dir", status: "ok", detail: dir });
+}
+async function countBackups(configPath) {
+  const dir = path8.dirname(configPath);
+  const base = path8.basename(configPath);
+  let entries;
+  try {
+    entries = await fs9.promises.readdir(dir);
+  } catch {
+    return 0;
+  }
+  return entries.filter(
+    (entry) => entry.startsWith(`${base}.picklab-backup-`) && isBackupPath(entry)
+  ).length;
+}
+async function fileExists(filePath) {
+  try {
+    await fs9.promises.access(filePath, fs9.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+function stateEntryForPath(stateEntry, configPath) {
+  if (stateEntry === void 0) {
+    return void 0;
+  }
+  return path8.resolve(stateEntry.configPath) === path8.resolve(configPath) ? stateEntry : void 0;
+}
+async function checkBuiltinAgent(name, configPath, checks, recordedEntry) {
+  const id = `agent-${name}`;
+  const stateEntry = stateEntryForPath(recordedEntry, configPath);
+  const exists = await fileExists(configPath);
+  const backups = await countBackups(configPath);
+  if (!exists) {
+    if (stateEntry?.registered === true) {
+      checks.push({
+        id,
+        status: "problem",
+        detail: `stale: PickLab linked ${configPath} but the file no longer exists (re-run: picklab agents link)`
+      });
+      return;
+    }
+    checks.push({
+      id,
+      status: "ok",
+      detail: `not registered (${configPath} does not exist)`
+    });
+    return;
+  }
+  if (name === "codex") {
+    const inspection = await inspectTomlFile(configPath);
+    if (inspection.markersPresent && !inspection.markersHaveSection) {
+      checks.push({
+        id,
+        status: "problem",
+        detail: `stale: ${configPath} has picklab markers without an [mcp_servers.picklab] section (re-run: picklab agents link codex)`
+      });
+      return;
+    }
+    if (inspection.foreignSection && !inspection.markersPresent) {
+      checks.push({
+        id,
+        status: "warn",
+        detail: `${configPath} has an [mcp_servers.picklab] section that PickLab does not manage`
+      });
+      return;
+    }
+    pushRegistrationCheck(
+      checks,
+      id,
+      configPath,
+      inspection.markersHaveSection,
+      backups,
+      stateEntry
+    );
+    return;
+  }
+  const registered = await jsonFileMcpServerState(configPath);
+  pushRegistrationCheck(checks, id, configPath, registered, backups, stateEntry);
+}
+function pushRegistrationCheck(checks, id, configPath, registered, backups, stateEntry) {
+  if (registered === "unknown") {
+    checks.push({
+      id,
+      status: "warn",
+      detail: `${configPath} exists but is not parseable as strict JSON (JSONC comments or trailing commas?); cannot tell whether picklab is registered`
+    });
+    return;
+  }
+  if (!registered && stateEntry?.registered === true) {
+    checks.push({
+      id,
+      status: "problem",
+      detail: `stale: PickLab linked ${configPath} but the picklab entry is gone (re-run: picklab agents link)`
+    });
+    return;
+  }
+  if (backups > BACKUP_CLUTTER_THRESHOLD) {
+    checks.push({
+      id,
+      status: "warn",
+      detail: `${backups} picklab backups next to ${configPath}; consider pruning`
+    });
+    return;
+  }
+  if (!registered && stateEntry === void 0 && backups > 0) {
+    checks.push({
+      id,
+      status: "warn",
+      detail: `${configPath} has ${backups} picklab backup(s) but no picklab entry; it may have been edited outside PickLab (re-link with: picklab agents link)`
+    });
+    return;
+  }
+  checks.push({
+    id,
+    status: "ok",
+    detail: registered ? `registered in ${configPath}` : stateEntry?.registered === false ? `not registered in ${configPath} (unlinked by picklab)` : `not registered in ${configPath}`
+  });
+}
+function checkPicklabOnPath(env, checks) {
+  const pathValue = env.PATH ?? "";
+  for (const dir of pathValue.split(path8.delimiter)) {
+    if (dir === "") {
+      continue;
+    }
+    const candidate = path8.join(dir, "picklab");
+    try {
+      fs9.accessSync(candidate, fs9.constants.X_OK);
+      if (fs9.statSync(candidate).isFile()) {
+        checks.push({ id: "picklab-bin", status: "ok", detail: candidate });
+        return;
+      }
+    } catch {
+      continue;
+    }
+  }
+  checks.push({
+    id: "picklab-bin",
+    status: "warn",
+    detail: "picklab is not on PATH; registered agents will fail to start the MCP server (install globally or adjust PATH)"
+  });
+}
+async function runAgentsDoctor(opts = {}) {
+  const env = opts.env ?? process.env;
+  const checks = [];
+  await checkAgentsDir(env, checks);
+  const state = await readAgentsState(env);
+  for (const agent of Object.values(BUILTIN_AGENTS)) {
+    const configPath = opts.configPaths?.[agent.name] ?? agent.defaultConfigPath(env);
+    await checkBuiltinAgent(
+      agent.name,
+      configPath,
+      checks,
+      state.agents[agent.name]
+    );
+  }
+  checkPicklabOnPath(env, checks);
+  return {
+    ok: !checks.some((check) => check.status === "problem"),
+    checks
+  };
+}
+
+// src/commands/agents.ts
+function parseConfigPathOverrides(values) {
+  const overrides = {};
+  for (const value of values ?? []) {
+    const separator = value.indexOf("=");
+    const agent = separator === -1 ? "" : value.slice(0, separator);
+    const configPath = separator === -1 ? "" : value.slice(separator + 1);
+    if (agent === "" || configPath === "") {
+      throw new Error(
+        `Invalid --config-path "${value}": expected <agent>=<path>`
+      );
+    }
+    if (!AGENT_KINDS.includes(agent)) {
+      throw new Error(
+        `Invalid --config-path agent "${agent}" (expected one of: ${AGENT_KINDS.join(", ")})`
+      );
+    }
+    overrides[agent] = configPath;
+  }
+  return overrides;
+}
+async function fileExists2(filePath) {
+  try {
+    await fs10.promises.access(filePath, fs10.constants.F_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function collectStatuses(env, overrides) {
+  const statuses = [];
+  for (const kind of AGENT_KINDS) {
+    const agent = builtinAgent(kind);
+    if (agent === void 0) continue;
+    const configPath = overrides[kind] ?? agent.defaultConfigPath(env);
+    statuses.push({
+      name: kind,
+      kind,
+      configPath,
+      configExists: await fileExists2(configPath),
+      registered: await agent.isRegistered(configPath)
+    });
+  }
+  for (const custom of await listCustomAgents(env)) {
+    statuses.push({
+      name: custom.name,
+      kind: "custom",
+      configPath: custom.configPath,
+      configExists: true,
+      registered: true
+    });
+  }
+  return statuses;
+}
+function registrationLabel(registered) {
+  if (registered === "unknown") {
+    return "unknown (config exists but is not parseable as strict JSON)";
+  }
+  return registered ? "registered" : "not registered";
+}
+async function runAgentsList(opts, env = process.env) {
+  return runReported(opts, async () => {
+    const overrides = parseConfigPathOverrides(opts.configPath);
+    const agents = await collectStatuses(env, overrides);
+    return {
+      data: { agents },
+      lines: agents.map(
+        (agent) => `${agent.name}  ${agent.kind === "custom" ? "custom" : "builtin"}  ${registrationLabel(agent.registered)}  ${agent.configPath}`
+      )
+    };
+  });
+}
+async function unknownAgentError(name, env) {
+  const customs = (await listCustomAgents(env)).map((agent) => agent.name);
+  const known = [...AGENT_KINDS, ...customs].join(", ");
+  return { errors: [`Unknown agent "${name}" (known agents: ${known})`] };
+}
+function changeLines(name, result, verb) {
+  const lines = [];
+  if (result.instructions !== void 0) {
+    lines.push(result.instructions);
+  } else if (result.changed) {
+    lines.push(
+      verb === "registered" ? `Registered the picklab MCP server for ${name} in ${result.configPath}` : `Removed the picklab MCP server entry for ${name} from ${result.configPath}`
+    );
+  } else {
+    lines.push(
+      verb === "registered" ? `${name} is already registered in ${result.configPath} (no changes made)` : `${name} has no picklab entry in ${result.configPath} (nothing to remove)`
+    );
+  }
+  if (result.backupPath !== void 0) {
+    lines.push(`Backed up the previous config to ${result.backupPath}`);
+  }
+  if (result.warning !== void 0) {
+    lines.push(`warning: ${result.warning}`);
+  }
+  return lines;
+}
+async function runAgentsLink(name, opts, env = process.env) {
+  return runReported(opts, async () => {
+    const agent = builtinAgent(name);
+    if (agent === void 0) {
+      const customs = await listCustomAgents(env);
+      const custom = customs.find((candidate) => candidate.name === name);
+      if (custom !== void 0) {
+        return {
+          errors: [
+            `"${name}" is a custom agent; its MCP config snippet lives at ${custom.configPath}. Point the agent at it manually.`
+          ]
+        };
+      }
+      return unknownAgentError(name, env);
+    }
+    const snippets = await writeSharedSnippets(env);
+    const configPath = opts.configPath ?? agent.defaultConfigPath(env);
+    const result = await agent.link(configPath, env);
+    const registered = await agent.isRegistered(configPath);
+    if (result.instructions === void 0) {
+      await recordAgentState(name, { registered: true, configPath }, env);
+    }
+    return {
+      data: {
+        agent: name,
+        configPath,
+        registered,
+        changed: result.changed,
+        backupPath: result.backupPath ?? null,
+        instructions: result.instructions ?? null,
+        warning: result.warning ?? null,
+        snippets
+      },
+      lines: changeLines(name, result, "registered")
+    };
+  });
+}
+async function runAgentsUnlink(name, opts, env = process.env) {
+  return runReported(opts, async () => {
+    const agent = builtinAgent(name);
+    if (agent === void 0) {
+      const customs = await listCustomAgents(env);
+      if (customs.some((candidate) => candidate.name === name)) {
+        const result2 = await removeCustomAgent(name, env);
+        return {
+          data: {
+            agent: name,
+            configPath: result2.configPath,
+            changed: result2.changed
+          },
+          lines: [`Removed custom agent "${name}" (${result2.configPath})`]
+        };
+      }
+      return unknownAgentError(name, env);
+    }
+    const configPath = opts.configPath ?? agent.defaultConfigPath(env);
+    const result = await agent.unlink(configPath, env);
+    await recordAgentState(name, { registered: false, configPath }, env);
+    return {
+      data: {
+        agent: name,
+        configPath,
+        changed: result.changed,
+        backupPath: result.backupPath ?? null,
+        warning: result.warning ?? null
+      },
+      lines: changeLines(name, result, "removed")
+    };
+  });
+}
+async function runAgentsDoctorCommand(opts, env = process.env) {
+  return runReported(opts, async () => {
+    const configPaths = parseConfigPathOverrides(opts.configPath);
+    const report = await runAgentsDoctor({ env, configPaths });
+    const errors = report.checks.filter((check) => check.status === "problem").map((check) => `${check.id}: ${check.detail}`);
+    return {
+      data: { checks: report.checks },
+      lines: report.checks.map(
+        (check) => `[${check.status}] ${check.id}: ${check.detail}`
+      ),
+      errors
+    };
+  });
+}
+async function runAgentsAdd(opts, env = process.env) {
+  return runReported(opts, async () => {
+    if (opts.name === void 0 || opts.name === "") {
+      return { errors: ["--name is required"] };
+    }
+    if (opts.mcpCommand === void 0) {
+      return { errors: ["--mcp-command is required"] };
+    }
+    const agent = await addCustomAgent(
+      { name: opts.name, mcpCommand: opts.mcpCommand, force: opts.force },
+      env
+    );
+    const snippets = await writeSharedSnippets(env);
+    return {
+      data: {
+        name: agent.name,
+        configPath: agent.configPath,
+        command: agent.entry.command,
+        args: agent.entry.args,
+        snippets
+      },
+      lines: [
+        `Added custom agent "${agent.name}" (${agent.configPath})`,
+        `Command: ${[agent.entry.command, ...agent.entry.args].join(" ")}`,
+        "Note: the command string is split on whitespace; quoting is not supported."
+      ]
+    };
+  });
+}
+
+// src/commands/desktop.ts
+async function resolveDesktop(opts) {
+  const record = await resolveSessionRecord("desktop", opts);
+  return { id: record.id, display: requireDisplay(record) };
+}
+async function runDesktopLaunch(command, args, opts) {
+  return runReported(opts, async () => {
+    const { id, display } = await resolveDesktop(opts);
+    const app = await launchApp2({
+      display,
+      command,
+      args,
+      logDir: desktopSessionLogDir(id),
+      cwd: opts.cwd
+    });
+    const data = {
+      sessionId: id,
+      display,
+      pid: app.pid,
+      logPath: app.logPath
+    };
+    const lines = [
+      `launched ${command} (pid ${app.pid}) on ${display}`,
+      `log: ${app.logPath}`
+    ];
+    if (opts.waitWindow !== void 0) {
+      const window = await waitForWindow(display, opts.waitWindow);
+      data.window = window;
+      lines.push(`window appeared: ${JSON.stringify(window.name)} (id ${window.id})`);
+    }
+    return { data, lines };
+  });
+}
+async function runDesktopScreenshot(opts) {
+  return runReported(opts, async () => {
+    const { id, display } = await resolveDesktop(opts);
+    const target = await resolveScreenshotTarget2(opts, "desktop", id);
+    let tool;
+    const data = await captureToTarget(target, async () => {
+      const result = await screenshot2({ display, outPath: target.outPath });
+      tool = result.tool;
+    });
+    data.sessionId = id;
+    data.display = display;
+    data.tool = tool;
+    const lines = [`screenshot saved to ${target.outPath}`];
+    if (data.runId !== void 0) {
+      lines.push(`run: ${data.runId}`);
+    }
+    return { data, lines };
+  });
+}
+async function runDesktopClick(x, y, opts) {
+  return runReported(opts, async () => {
+    const parsedX = parseIntArg(x, "x");
+    const parsedY = parseIntArg(y, "y");
+    const button = opts.button === void 0 ? void 0 : parseIntArg(opts.button, "--button");
+    if (button !== void 0 && (button < 1 || button > 9)) {
+      throw new Error(
+        `Invalid --button "${opts.button}": expected an integer between 1 and 9`
+      );
+    }
+    const { id, display } = await resolveDesktop(opts);
+    await click({ display, x: parsedX, y: parsedY, button });
+    return {
+      data: { sessionId: id, display, x: parsedX, y: parsedY, button: button ?? 1 },
+      lines: [`clicked (${parsedX}, ${parsedY}) on ${display}`]
+    };
+  });
+}
+async function runDesktopType(text, opts) {
+  return runReported(opts, async () => {
+    const { id, display } = await resolveDesktop(opts);
+    await typeText2({ display, text });
+    return {
+      data: { sessionId: id, display, length: text.length },
+      lines: [`typed ${text.length} character(s) on ${display}`]
+    };
+  });
+}
+async function runDesktopKey(key, opts) {
+  return runReported(opts, async () => {
+    const { id, display } = await resolveDesktop(opts);
+    await pressKey({ display, key });
+    return {
+      data: { sessionId: id, display, key },
+      lines: [`pressed ${key} on ${display}`]
+    };
+  });
+}
+
+// src/provision/planner.ts
+import path9 from "path";
+var RECOMMENDED_SYSTEM_IMAGE = "system-images;android-35;google_apis;x86_64";
+var NOLOGIN_SHELL = "/usr/sbin/nologin";
+var LAB_USER_NAME_PATTERN = /^[a-z_][a-z0-9_-]{0,31}$/;
+function planLabUser(input) {
+  if (!LAB_USER_NAME_PATTERN.test(input.name)) {
+    return {
+      ok: false,
+      error: `Invalid lab user name "${input.name}": expected a POSIX user name (lowercase letters, digits, underscores, hyphens; max 32 chars)`
+    };
+  }
+  if (!path9.isAbsolute(input.home) || input.home !== path9.normalize(input.home)) {
+    return {
+      ok: false,
+      error: `Invalid lab user home "${input.home}": expected a normalized absolute path`
+    };
+  }
+  const sudoArgs = (args) => input.nonInteractive === true ? ["-n", ...args] : args;
+  const privilegedSpecs = [];
+  if (!input.userExists) {
+    privilegedSpecs.push({
+      id: "useradd",
+      title: `Create locked service user ${input.name}`,
+      args: ["useradd", "-r", "-M", "-s", NOLOGIN_SHELL, input.name]
+    });
+  }
+  if (!input.homeExists) {
+    privilegedSpecs.push({
+      id: "mkdir-home",
+      title: `Create lab home ${input.home}`,
+      args: ["mkdir", "-p", input.home]
+    });
+  }
+  if (!input.userExists || !input.homeExists) {
+    privilegedSpecs.push(
+      {
+        id: "chown-home",
+        title: `Own lab home by ${input.name}`,
+        args: ["chown", `${input.name}:${input.name}`, input.home]
+      },
+      {
+        id: "chmod-home",
+        title: "Restrict lab home permissions to 750",
+        args: ["chmod", "750", input.home]
+      }
+    );
+  }
+  if (!input.userExists && input.kvmPresent) {
+    privilegedSpecs.push({
+      id: "kvm-group",
+      title: `Grant ${input.name} access to /dev/kvm`,
+      args: ["usermod", "-aG", "kvm", input.name]
+    });
+  }
+  const steps = [];
+  if (privilegedSpecs.length > 0) {
+    const sudoPath = input.sudoPath;
+    if (sudoPath === null) {
+      return {
+        ok: false,
+        error: `sudo not found on PATH; cannot provision lab user "${input.name}". Install sudo, or create the user manually as root: useradd -r -M -s ${NOLOGIN_SHELL} ${input.name}`
+      };
+    }
+    steps.push(
+      ...privilegedSpecs.map(
+        (spec) => ({
+          id: spec.id,
+          title: spec.title,
+          kind: "command",
+          privileged: true,
+          command: { cmd: sudoPath, args: sudoArgs(spec.args) }
+        })
+      )
+    );
+  }
+  steps.push({
+    id: "persist-lab-user",
+    title: "Persist lab user in global PickLab config",
+    kind: "write-global-config",
+    privileged: false,
+    config: { labUser: { name: input.name, home: input.home } }
+  });
+  return { ok: true, plan: { steps } };
+}
+var TAG_SCORES = {
+  google_apis: 3,
+  default: 2,
+  google_apis_playstore: 1
+};
+var ABI_SCORES = {
+  x86_64: 2,
+  x86: 1
+};
+function apiLevel(image) {
+  const match = /^android-(\d+)$/.exec(image.api);
+  return match === null ? -1 : Number(match[1]);
+}
+function chooseSystemImage(images) {
+  let best = null;
+  for (const image of images) {
+    if (best === null) {
+      best = image;
+      continue;
+    }
+    const tagDiff = (TAG_SCORES[image.tag] ?? 0) - (TAG_SCORES[best.tag] ?? 0);
+    if (tagDiff !== 0) {
+      if (tagDiff > 0) best = image;
+      continue;
+    }
+    const abiDiff = (ABI_SCORES[image.abi] ?? 0) - (ABI_SCORES[best.abi] ?? 0);
+    if (abiDiff !== 0) {
+      if (abiDiff > 0) best = image;
+      continue;
+    }
+    if (apiLevel(image) > apiLevel(best)) {
+      best = image;
+    }
+  }
+  return best;
+}
+function planCreateAvd(input) {
+  const persistStep = {
+    id: "persist-avd",
+    title: "Persist AVD name in global PickLab config",
+    kind: "write-global-config",
+    privileged: false,
+    config: { android: { avdName: input.avdName } }
+  };
+  if (input.existingAvds.includes(input.avdName)) {
+    return { ok: true, plan: { steps: [persistStep] } };
+  }
+  if (input.sdkRoot === null) {
+    return { ok: false, error: missingSdkMessage() };
+  }
+  let systemImage;
+  if (input.systemImage !== void 0) {
+    if (!isValidSystemImageId(input.systemImage)) {
+      return {
+        ok: false,
+        error: `Invalid system image "${input.systemImage}": expected the form "system-images;android-<api>;<tag>;<abi>"`
+      };
+    }
+    if (!input.installedImages.some(
+      (image) => image.packageId === input.systemImage
+    )) {
+      return {
+        ok: false,
+        error: `System image "${input.systemImage}" is not installed under ${input.sdkRoot}. Install it with: ` + sdkmanagerInstallCommand(input.systemImage)
+      };
+    }
+    systemImage = input.systemImage;
+  } else {
+    const chosen = chooseSystemImage(input.installedImages);
+    if (chosen === null) {
+      return {
+        ok: false,
+        error: `No Android system images installed under ${input.sdkRoot}. Install one with: ` + sdkmanagerInstallCommand(RECOMMENDED_SYSTEM_IMAGE)
+      };
+    }
+    systemImage = chosen.packageId;
+  }
+  if (input.avdmanagerPath === null) {
+    return {
+      ok: false,
+      error: `avdmanager not found under ${input.sdkRoot} or on PATH; install the Android command-line tools (https://developer.android.com/studio#command-line)`
+    };
+  }
+  let args;
+  try {
+    args = buildCreateAvdArgs({ name: input.avdName, systemImage });
+  } catch (error) {
+    return { ok: false, error: error.message };
+  }
+  return {
+    ok: true,
+    plan: {
+      steps: [
+        {
+          id: "create-avd",
+          title: `Create AVD ${input.avdName} (${systemImage})`,
+          kind: "command",
+          privileged: false,
+          command: {
+            cmd: input.avdmanagerPath,
+            args,
+            env: {
+              ANDROID_HOME: input.sdkRoot,
+              ANDROID_SDK_ROOT: input.sdkRoot
+            },
+            input: "no\n"
+          }
+        },
+        persistStep
+      ]
+    }
+  };
+}
+function planPicklabHome(input) {
+  if (input.exists) {
+    return { steps: [] };
+  }
+  return {
+    steps: [
+      {
+        id: "picklab-home",
+        title: `Create PickLab home ${input.path}`,
+        kind: "mkdir",
+        privileged: false,
+        dir: input.path
+      }
+    ]
+  };
+}
+
+// src/provision/checks.ts
+var BASE_CHECKS = ["picklab-home", "config"];
+var DESKTOP_CHECKS = [
+  "xvfb",
+  "xdotool",
+  "screenshot-tool",
+  "lab-user"
+];
+var ANDROID_CHECKS = [
+  "android-sdk",
+  "sdkmanager",
+  "avdmanager",
+  "emulator",
+  "adb",
+  "system-image",
+  "avd"
+];
+var PROFILE_REQUIRED_CHECKS = {
+  generic: [...BASE_CHECKS],
+  "flutter-desktop": [...BASE_CHECKS, ...DESKTOP_CHECKS],
+  android: [...BASE_CHECKS, ...ANDROID_CHECKS],
+  "desktop+android": [...BASE_CHECKS, ...DESKTOP_CHECKS, ...ANDROID_CHECKS]
+};
+function requiredChecksForProfile(profile) {
+  return PROFILE_REQUIRED_CHECKS[profile];
+}
+function pathCheck(id, title, found, hint, missingStatus = "missing") {
+  if (found !== null) {
+    return { id, title, status: "ok", detail: found };
+  }
+  return { id, title, status: missingStatus, detail: "not found", hint };
+}
+function evaluateChecks(s) {
+  const checks = [];
+  if (!s.picklabHome.exists) {
+    checks.push({
+      id: "picklab-home",
+      title: "PickLab home",
+      status: "missing",
+      detail: `${s.picklabHome.path} does not exist`,
+      hint: "run `picklab doctor --fix` or `picklab init` to create it"
+    });
+  } else if (!s.picklabHome.writable) {
+    checks.push({
+      id: "picklab-home",
+      title: "PickLab home",
+      status: "missing",
+      detail: `${s.picklabHome.path} is not writable`,
+      hint: `fix ownership/permissions of ${s.picklabHome.path}`
+    });
+  } else {
+    checks.push({
+      id: "picklab-home",
+      title: "PickLab home",
+      status: "ok",
+      detail: s.picklabHome.path
+    });
+  }
+  if (s.config.ok) {
+    checks.push({
+      id: "config",
+      title: "PickLab config",
+      status: "ok",
+      detail: s.config.profile === null ? "readable (no profile set)" : `readable (profile: ${s.config.profile})`
+    });
+  } else {
+    checks.push({
+      id: "config",
+      title: "PickLab config",
+      status: "missing",
+      detail: s.config.error ?? "unreadable",
+      hint: "fix or remove the broken config file"
+    });
+  }
+  checks.push(
+    pathCheck(
+      "xvfb",
+      "Xvfb (headless X server)",
+      s.desktop.xvfb,
+      "install Xvfb (e.g. xorg-server-xvfb / xvfb package)"
+    ),
+    pathCheck(
+      "xdotool",
+      "xdotool (input synthesis)",
+      s.desktop.xdotool,
+      "install xdotool"
+    ),
+    pathCheck(
+      "screenshot-tool",
+      "Screenshot tool",
+      s.desktop.screenshotTool,
+      "install ImageMagick (provides `import`) or scrot"
+    ),
+    pathCheck(
+      "x11vnc",
+      "x11vnc (optional live view)",
+      s.desktop.x11vnc,
+      "optional: install x11vnc to watch lab sessions live",
+      "warn"
+    ),
+    pathCheck(
+      "android-sdk",
+      "Android SDK",
+      s.android.sdkRoot,
+      missingSdkMessage()
+    ),
+    pathCheck(
+      "sdkmanager",
+      "sdkmanager",
+      s.android.tools.sdkmanager,
+      "install the Android command-line tools (cmdline-tools)"
+    ),
+    pathCheck(
+      "avdmanager",
+      "avdmanager",
+      s.android.tools.avdmanager,
+      "install the Android command-line tools (cmdline-tools)"
+    ),
+    pathCheck(
+      "emulator",
+      "Android emulator",
+      s.android.tools.emulator,
+      'install the emulator package: sdkmanager "emulator"'
+    ),
+    pathCheck(
+      "adb",
+      "adb",
+      s.android.tools.adb,
+      'install platform-tools: sdkmanager "platform-tools"'
+    )
+  );
+  if (s.android.systemImages.length > 0) {
+    checks.push({
+      id: "system-image",
+      title: "Android system images",
+      status: "ok",
+      detail: `${s.android.systemImages.length} installed`
+    });
+  } else {
+    checks.push({
+      id: "system-image",
+      title: "Android system images",
+      status: "missing",
+      detail: "no system images installed",
+      hint: `install one with: ${sdkmanagerInstallCommand(RECOMMENDED_SYSTEM_IMAGE)}`
+    });
+  }
+  if (s.android.kvm.supported) {
+    checks.push({
+      id: "kvm",
+      title: "KVM hardware acceleration",
+      status: "ok",
+      detail: "/dev/kvm is accessible"
+    });
+  } else if (s.android.kvm.exists) {
+    checks.push({
+      id: "kvm",
+      title: "KVM hardware acceleration",
+      status: "warn",
+      detail: "/dev/kvm exists but is not accessible",
+      hint: "add your user to the kvm group, then log in again"
+    });
+  } else {
+    checks.push({
+      id: "kvm",
+      title: "KVM hardware acceleration",
+      status: "warn",
+      detail: "/dev/kvm not found",
+      hint: "without KVM the Android emulator will be very slow"
+    });
+  }
+  if (s.android.avdExists) {
+    checks.push({
+      id: "avd",
+      title: "Dedicated PickLab AVD",
+      status: "ok",
+      detail: s.android.avdName
+    });
+  } else {
+    checks.push({
+      id: "avd",
+      title: "Dedicated PickLab AVD",
+      status: "missing",
+      detail: `AVD "${s.android.avdName}" not found`,
+      hint: `create it with: picklab setup android --create-avd --avd-name ${s.android.avdName}`
+    });
+  }
+  if (s.labUser.exists) {
+    checks.push({
+      id: "lab-user",
+      title: "Dedicated lab user",
+      status: "ok",
+      detail: s.labUser.name
+    });
+  } else {
+    checks.push({
+      id: "lab-user",
+      title: "Dedicated lab user",
+      status: "missing",
+      detail: `user "${s.labUser.name}" not found`,
+      hint: `create it with: picklab setup lab-user --name ${s.labUser.name}`
+    });
+  }
+  return checks;
+}
+function formatCheckLine(check) {
+  const status = `[${check.status}]`.padEnd(10);
+  const line = `${status}${check.id.padEnd(18)}${check.detail}`;
+  return check.hint === void 0 ? line : `${line}
+${" ".repeat(10)}hint: ${check.hint}`;
+}
+
+// src/provision/detect.ts
+import fs11 from "fs";
+function dirExists(dir) {
+  try {
+    return fs11.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+function isWritable(target) {
+  try {
+    fs11.accessSync(target, fs11.constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function labUserExists(name, env = process.env) {
+  try {
+    const result = await runCommand("getent", ["passwd", "--", name], {
+      env,
+      timeoutMs: 1e4
+    });
+    if (!result.ok) {
+      return false;
+    }
+    return result.stdout.split("\n").some((line) => line.split(":")[0] === name);
+  } catch {
+    return false;
+  }
+}
+async function collectSnapshot(opts = {}) {
+  const env = opts.env ?? process.env;
+  const projectDir = opts.projectDir ?? process.cwd();
+  let config = {
+    ok: true,
+    error: null,
+    profile: null
+  };
+  let loaded;
+  try {
+    loaded = await loadConfig(projectDir, env);
+    config = { ok: true, error: null, profile: loaded.profile ?? null };
+  } catch (error) {
+    loaded = { ...resolvedDefaults };
+    config = { ok: false, error: error.message, profile: null };
+  }
+  const avdName = opts.avdName ?? loaded.android?.avdName ?? resolvedDefaults.android.avdName;
+  const labUserName = opts.labUserName ?? loaded.labUser?.name ?? resolvedDefaults.labUser.name;
+  const labUserHome = opts.labUserHome ?? loaded.labUser?.home ?? resolvedDefaults.labUser.home;
+  const homePath = picklabHome(env);
+  const homeExists = dirExists(homePath);
+  const androidEnv = detectAndroidEnvironment({
+    env,
+    homeDir: env.HOME !== void 0 && env.HOME !== "" ? env.HOME : void 0,
+    kvmPath: env.PICKLAB_KVM_PATH !== void 0 && env.PICKLAB_KVM_PATH !== "" ? env.PICKLAB_KVM_PATH : void 0
+  });
+  const avds = await listAvds({ sdk: androidEnv.sdkRoot, env });
+  return {
+    picklabHome: {
+      path: homePath,
+      exists: homeExists,
+      writable: homeExists && isWritable(homePath)
+    },
+    config,
+    desktop: {
+      xvfb: findOnPath("Xvfb", env),
+      xdotool: findOnPath("xdotool", env),
+      screenshotTool: detectScreenshotTool(env),
+      x11vnc: detectVncBinary(env)
+    },
+    android: {
+      ...androidEnv,
+      avdName,
+      avds,
+      avdExists: avds.includes(avdName)
+    },
+    labUser: {
+      name: labUserName,
+      home: labUserHome,
+      exists: await labUserExists(labUserName, env),
+      homeExists: dirExists(labUserHome)
+    },
+    sudo: findOnPath("sudo", env)
+  };
+}
+
+// src/provision/executor.ts
+import fs12 from "fs";
+
+// src/provision/plan.ts
+function planHasCommandSteps(plan) {
+  return plan.steps.some((step) => step.kind === "command");
+}
+function formatStep(step) {
+  switch (step.kind) {
+    case "command":
+      return `$ ${step.command.cmd} ${step.command.args.join(" ")}`;
+    case "mkdir":
+      return `mkdir -p ${step.dir}`;
+    case "write-global-config":
+      return `update global config: ${JSON.stringify(step.config)}`;
+    case "write-project-config":
+      return `write project config: ${JSON.stringify(step.config)}`;
+  }
+}
+
+// src/provision/executor.ts
+var DEFAULT_STEP_TIMEOUT_MS = 18e4;
+async function patchGlobalConfig(patch, env = process.env) {
+  const existing = await readConfigFile(globalConfigPath(env));
+  await saveGlobalConfig(deepMerge(existing, patch), env);
+}
+async function patchProjectConfig(projectDir, patch) {
+  const existing = await readConfigFile(projectConfigPath(projectDir));
+  await saveProjectConfig(
+    projectDir,
+    deepMerge(existing, patch)
+  );
+}
+async function executeStep(step, opts) {
+  switch (step.kind) {
+    case "mkdir": {
+      await fs12.promises.mkdir(step.dir, { recursive: true });
+      return;
+    }
+    case "command": {
+      const command = step.command;
+      const result = await runCommand(command.cmd, command.args, {
+        env: { ...opts.env, ...command.env },
+        input: command.input,
+        timeoutMs: opts.timeoutMs ?? DEFAULT_STEP_TIMEOUT_MS
+      });
+      if (!result.ok) {
+        const detail = result.stderr.trim() || result.stdout.trim() || (result.timedOut ? "timed out" : `exit code ${result.code}`);
+        throw new Error(
+          `${command.cmd} ${command.args.join(" ")} failed: ${detail}`
+        );
+      }
+      return;
+    }
+    case "write-global-config": {
+      await patchGlobalConfig(step.config, opts.env);
+      return;
+    }
+    case "write-project-config": {
+      if (opts.projectDir === void 0) {
+        throw new Error("write-project-config step requires a project directory");
+      }
+      await patchProjectConfig(opts.projectDir, step.config);
+      return;
+    }
+  }
+}
+async function executePlan(plan, opts = {}) {
+  const log = opts.log ?? (() => {
+  });
+  const results = [];
+  for (const step of plan.steps) {
+    if (opts.dryRun === true) {
+      log(`[dry-run] ${step.title}: ${formatStep(step)}`);
+      results.push({ id: step.id, ok: true, detail: "dry-run" });
+      continue;
+    }
+    try {
+      await executeStep(step, opts);
+      log(`[done] ${step.title}`);
+      results.push({ id: step.id, ok: true, detail: formatStep(step) });
+    } catch (error) {
+      const message = `Step "${step.id}" failed: ${error.message}`;
+      log(`[failed] ${step.title}: ${error.message}`);
+      results.push({ id: step.id, ok: false, detail: message });
+      return { ok: false, results, error: message };
+    }
+  }
+  return { ok: true, results };
+}
+
+// src/provision/prompts.ts
+import readline from "readline/promises";
+async function confirm(question, opts = {}) {
+  if (opts.yes === true) {
+    return "yes";
+  }
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stderr;
+  if (input.isTTY !== true) {
+    return "non-interactive";
+  }
+  const rl = readline.createInterface({ input, output });
+  try {
+    const answer = await rl.question(`${question} [y/N] `);
+    return /^y(es)?$/i.test(answer.trim()) ? "yes" : "no";
+  } finally {
+    rl.close();
+  }
+}
+
+// src/commands/doctor.ts
+async function consentToRepair(question, opts) {
+  if (opts.dryRun === true) {
+    return true;
+  }
+  const answer = await confirm(question, { yes: opts.yes });
+  return answer === "yes";
+}
+async function buildFixPlan(snapshot, opts) {
+  const steps = [];
+  const skipped = [];
+  const consentHint = "skipped (requires consent; re-run with --yes or confirm interactively)";
+  steps.push(
+    ...planPicklabHome({
+      path: snapshot.picklabHome.path,
+      exists: snapshot.picklabHome.exists
+    }).steps
+  );
+  if (!snapshot.android.avdExists) {
+    const result = planCreateAvd({
+      avdName: snapshot.android.avdName,
+      sdkRoot: snapshot.android.sdkRoot,
+      avdmanagerPath: snapshot.android.tools.avdmanager,
+      installedImages: snapshot.android.systemImages,
+      existingAvds: snapshot.android.avds
+    });
+    if (!result.ok) {
+      skipped.push(`avd: ${result.error}`);
+    } else if (!planHasCommandSteps(result.plan) || await consentToRepair(
+      `Create AVD "${snapshot.android.avdName}" (runs avdmanager)?`,
+      opts
+    )) {
+      steps.push(...result.plan.steps);
+    } else {
+      skipped.push(`avd: ${consentHint}`);
+    }
+  }
+  if (!snapshot.labUser.exists) {
+    const result = planLabUser({
+      name: snapshot.labUser.name,
+      home: snapshot.labUser.home,
+      userExists: snapshot.labUser.exists,
+      homeExists: snapshot.labUser.homeExists,
+      kvmPresent: snapshot.android.kvm.exists,
+      sudoPath: snapshot.sudo,
+      nonInteractive: process.stdin.isTTY !== true
+    });
+    if (!result.ok) {
+      skipped.push(`lab-user: ${result.error}`);
+    } else if (!planHasCommandSteps(result.plan) || await consentToRepair(
+      `Create lab user "${snapshot.labUser.name}" (privileged, runs sudo)?`,
+      opts
+    )) {
+      steps.push(...result.plan.steps);
+    } else {
+      skipped.push(`lab-user: ${consentHint}`);
+    }
+  }
+  return { steps, skipped };
+}
+async function runDoctor(opts, env = process.env) {
+  const projectDir = opts.projectDir ?? process.cwd();
+  const snapshot = await collectSnapshot({ env, projectDir });
+  const checks = evaluateChecks(snapshot);
+  const report = {
+    ok: !checks.some((check) => check.status === "missing"),
+    checks,
+    errors: []
+  };
+  if (opts.json !== true) {
+    for (const check of checks) {
+      console.log(formatCheckLine(check));
+    }
+  }
+  let exitCode = 0;
+  if (opts.fix === true) {
+    const { steps, skipped } = await buildFixPlan(snapshot, opts);
+    const log = opts.json === true ? () => {
+    } : (line) => console.log(line);
+    const execution = await executePlan(
+      { steps },
+      { dryRun: opts.dryRun, env, projectDir, log }
+    );
+    report.fix = {
+      dryRun: opts.dryRun === true,
+      steps,
+      skipped,
+      results: execution.results
+    };
+    if (!execution.ok) {
+      report.errors.push(execution.error ?? "repairs failed");
+      exitCode = 1;
+    }
+  }
+  if (opts.json === true) {
+    console.log(JSON.stringify(report, null, 2));
+  } else {
+    if (report.fix !== void 0) {
+      for (const entry of report.fix.skipped) {
+        console.log(`[skipped] ${entry}`);
+      }
+    }
+    for (const error of report.errors) {
+      console.error(`error: ${error}`);
+    }
+  }
+  return exitCode;
+}
+
+// src/commands/init.ts
+import path10 from "path";
+async function consentTo(what, opts, remediation) {
+  if (opts.yes === true || opts.dryRun === true) {
+    return { granted: true };
+  }
+  const answer = await confirm(`Provision ${what}?`, {});
+  if (answer === "yes") {
+    return { granted: true };
+  }
+  if (answer === "no") {
+    return { granted: false, error: `Required ${what} was declined. ${remediation}` };
+  }
+  return {
+    granted: false,
+    error: `Refusing to provision ${what} without consent in a non-interactive session. ${remediation}`
+  };
+}
+async function planAvdProvisioning(snapshot, opts, steps, errors, handledCheckIds) {
+  const result = planCreateAvd({
+    avdName: snapshot.android.avdName,
+    sdkRoot: snapshot.android.sdkRoot,
+    avdmanagerPath: snapshot.android.tools.avdmanager,
+    installedImages: snapshot.android.systemImages,
+    existingAvds: snapshot.android.avds
+  });
+  if (!result.ok) {
+    errors.push(result.error);
+    return;
+  }
+  if (planHasCommandSteps(result.plan)) {
+    const consent = await consentTo(
+      `dedicated AVD "${snapshot.android.avdName}" (runs avdmanager)`,
+      opts,
+      "Re-run with --yes --create-avd or run: picklab setup android --create-avd"
+    );
+    if (!consent.granted) {
+      errors.push(consent.error ?? "AVD provisioning was not approved");
+      return;
+    }
+  }
+  steps.push(...result.plan.steps);
+  handledCheckIds.add("avd");
+}
+async function planLabUserProvisioning(snapshot, opts, steps, errors, handledCheckIds) {
+  const result = planLabUser({
+    name: snapshot.labUser.name,
+    home: snapshot.labUser.home,
+    userExists: snapshot.labUser.exists,
+    homeExists: snapshot.labUser.homeExists,
+    kvmPresent: snapshot.android.kvm.exists,
+    sudoPath: snapshot.sudo,
+    nonInteractive: process.stdin.isTTY !== true
+  });
+  if (!result.ok) {
+    errors.push(result.error);
+    return;
+  }
+  if (planHasCommandSteps(result.plan)) {
+    const consent = await consentTo(
+      `lab user "${snapshot.labUser.name}" (privileged, runs sudo)`,
+      opts,
+      "Re-run with --yes --create-lab-user or run: picklab setup lab-user"
+    );
+    if (!consent.granted) {
+      errors.push(consent.error ?? "Lab user provisioning was not approved");
+      return;
+    }
+  }
+  steps.push(...result.plan.steps);
+  handledCheckIds.add("lab-user");
+}
+async function runInit(opts, env = process.env) {
+  const profile = opts.profile ?? "generic";
+  const projectDir = path10.resolve(opts.projectDir ?? process.cwd());
+  const snapshot = await collectSnapshot({ env, projectDir });
+  const allChecks = evaluateChecks(snapshot);
+  const requiredIds = requiredChecksForProfile(profile);
+  const checks = allChecks.filter((check) => requiredIds.includes(check.id));
+  if (opts.json !== true) {
+    for (const check of checks) {
+      console.log(formatCheckLine(check));
+    }
+  }
+  const errors = [];
+  const handledCheckIds = /* @__PURE__ */ new Set();
+  const steps = [
+    {
+      id: "project-config",
+      title: `Write project config (profile: ${profile})`,
+      kind: "write-project-config",
+      privileged: false,
+      config: { profile }
+    }
+  ];
+  const homePlan = planPicklabHome({
+    path: snapshot.picklabHome.path,
+    exists: snapshot.picklabHome.exists
+  });
+  if (homePlan.steps.length > 0) {
+    steps.push(...homePlan.steps);
+    handledCheckIds.add("picklab-home");
+  }
+  const avdRequired = requiredIds.includes("avd");
+  const labUserRequired = requiredIds.includes("lab-user");
+  if (!snapshot.android.avdExists && (avdRequired || opts.createAvd === true)) {
+    await planAvdProvisioning(snapshot, opts, steps, errors, handledCheckIds);
+  }
+  if (!snapshot.labUser.exists && (labUserRequired || opts.createLabUser === true)) {
+    await planLabUserProvisioning(
+      snapshot,
+      opts,
+      steps,
+      errors,
+      handledCheckIds
+    );
+  }
+  for (const check of checks) {
+    if (check.status !== "missing") continue;
+    if (handledCheckIds.has(check.id)) continue;
+    errors.push(
+      `Required check "${check.id}" failed: ${check.detail}.` + (check.hint === void 0 ? "" : ` Hint: ${check.hint}`)
+    );
+  }
+  const report = {
+    ok: errors.length === 0,
+    profile,
+    projectDir,
+    dryRun: opts.dryRun === true,
+    checks,
+    plan: steps,
+    results: [],
+    errors
+  };
+  if (errors.length > 0) {
+    emit(report, opts);
+    return 1;
+  }
+  const log = opts.json === true ? () => {
+  } : (line) => console.log(line);
+  const execution = await executePlan(
+    { steps },
+    { dryRun: opts.dryRun, env, projectDir, log }
+  );
+  report.results = execution.results;
+  if (!execution.ok) {
+    report.ok = false;
+    report.errors.push(execution.error ?? "provisioning failed");
+  }
+  emit(report, opts);
+  return report.ok ? 0 : 1;
+}
+function emit(report, opts) {
+  if (opts.json === true) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const error of report.errors) {
+    console.error(`error: ${error}`);
+  }
+  if (report.ok) {
+    console.log(
+      report.dryRun ? `[dry-run] init complete for profile ${report.profile} (no changes made)` : `Initialized PickLab project (profile: ${report.profile}) in ${report.projectDir}`
+    );
+  }
+}
+
+// src/commands/session.ts
+async function createDesktopLeg(opts) {
+  const handle = await createDesktopSession({
+    projectDir: resolveProjectDir(opts),
+    width: opts.width === void 0 ? void 0 : parseIntArg(opts.width, "--width"),
+    height: opts.height === void 0 ? void 0 : parseIntArg(opts.height, "--height"),
+    vnc: opts.vnc
+  });
+  const summary = {
+    id: handle.id,
+    type: "desktop",
+    display: handle.display,
+    logDir: handle.logDir
+  };
+  if (handle.vncPort !== void 0) {
+    summary.vncPort = handle.vncPort;
+  }
+  return summary;
+}
+async function createAndroidLeg(opts) {
+  const projectDir = resolveProjectDir(opts);
+  const config = await loadConfig(projectDir);
+  const avdName = opts.avdName ?? config.android?.avdName;
+  const handle = await createAndroidSession(
+    avdName === void 0 ? { projectDir } : { projectDir, avdName }
+  );
+  return {
+    id: handle.id,
+    type: "android",
+    avdName: handle.avdName,
+    serial: handle.serial,
+    consolePort: handle.consolePort,
+    logDir: handle.logDir
+  };
+}
+function describeCreated(summary) {
+  if (summary.type === "desktop") {
+    const vnc = summary.vncPort === void 0 ? "" : `, vnc port ${summary.vncPort}`;
+    return `created desktop session ${summary.id} (display ${summary.display}${vnc})`;
+  }
+  return `created android session ${summary.id} (serial ${summary.serial})`;
+}
+async function runSessionCreate(opts) {
+  return runReported(opts, async () => {
+    const sessions = [];
+    if (opts.type === "desktop" || opts.type === "desktop+android") {
+      sessions.push(await createDesktopLeg(opts));
+    }
+    if (opts.type === "android" || opts.type === "desktop+android") {
+      try {
+        sessions.push(await createAndroidLeg(opts));
+      } catch (error) {
+        const desktop = sessions.find((session) => session.type === "desktop");
+        if (desktop !== void 0) {
+          await destroyDesktopSession(desktop.id).catch(() => {
+          });
+        }
+        throw error;
+      }
+    }
+    return { data: { sessions }, lines: sessions.map(describeCreated) };
+  });
+}
+async function sessionStatusEntry(record) {
+  const entry = {
+    id: record.id,
+    type: record.type,
+    status: record.status,
+    createdAt: record.createdAt,
+    projectDir: record.projectDir
+  };
+  if (record.type === "desktop") {
+    const status = await getDesktopSessionStatus(record.id);
+    entry.desktop = {
+      ...record.desktop,
+      xvfbAlive: status.xvfbAlive,
+      vncAlive: status.vncAlive,
+      displayAlive: status.displayAlive
+    };
+  } else if (record.type === "android") {
+    const status = await getAndroidSessionStatus(record.id);
+    entry.android = {
+      ...record.android,
+      emulatorAlive: status.emulatorAlive,
+      deviceState: status.deviceState
+    };
+  }
+  return entry;
+}
+function statusLine(entry) {
+  const parts = [`${entry.id}  ${entry.type}  ${entry.status}`];
+  const desktop = entry.desktop;
+  if (desktop !== void 0) {
+    parts.push(
+      `display=${desktop.display}`,
+      `xvfb=${desktop.xvfbAlive === true ? "alive" : "dead"}`
+    );
+    if (desktop.vncPort !== void 0) {
+      parts.push(`vnc=${desktop.vncAlive === true ? "alive" : "dead"}`);
+    }
+  }
+  const android = entry.android;
+  if (android !== void 0) {
+    parts.push(
+      `serial=${android.serial ?? "unknown"}`,
+      `emulator=${android.emulatorAlive === true ? "alive" : "dead"}`,
+      `device=${android.deviceState ?? "unknown"}`
+    );
+  }
+  return parts.join("  ");
+}
+async function runSessionStatus(id, opts) {
+  return runReported(opts, async () => {
+    let records;
+    if (id !== void 0) {
+      const record = await getSession(id);
+      if (record === void 0) {
+        throw new Error(`Session not found: ${id}`);
+      }
+      records = [record];
+    } else {
+      records = await listSessions();
+    }
+    const sessions = [];
+    for (const record of records) {
+      sessions.push(await sessionStatusEntry(record));
+    }
+    return {
+      data: { sessions },
+      lines: sessions.length === 0 ? ["no sessions"] : sessions.map(statusLine)
+    };
+  });
+}
+async function destroyRecord(record) {
+  if (record.type === "desktop") {
+    await destroyDesktopSession(record.id);
+  } else if (record.type === "android") {
+    await destroyAndroidSession(record.id);
+  } else {
+    throw new Error(
+      `Cannot destroy session ${record.id} of type "${record.type}"`
+    );
+  }
+}
+async function runSessionDestroy(id, opts) {
+  return runReported(opts, async () => {
+    if (id !== void 0 && opts.all === true) {
+      throw new Error("Pass either a session id or --all, not both");
+    }
+    if (id === void 0 && opts.all !== true) {
+      throw new Error("Pass a session id or --all");
+    }
+    const records = [];
+    if (id !== void 0) {
+      const record = await getSession(id);
+      if (record === void 0) {
+        throw new Error(`Session not found: ${id}`);
+      }
+      records.push(record);
+    } else {
+      records.push(...await listSessions());
+    }
+    const destroyed = [];
+    const errors = [];
+    for (const record of records) {
+      try {
+        await destroyRecord(record);
+        destroyed.push(record.id);
+      } catch (error) {
+        errors.push(
+          `${record.id}: ${error instanceof Error ? error.message : String(error)}`
+        );
+      }
+    }
+    return {
+      data: { destroyed },
+      lines: destroyed.length === 0 ? ["no sessions destroyed"] : destroyed.map((sessionId) => `destroyed session ${sessionId}`),
+      errors
+    };
+  });
+}
+
+// src/commands/setup-android.ts
+function describe(report) {
+  const lines = [
+    `Android SDK:    ${report.sdkRoot ?? "not found"}`,
+    `sdkmanager:     ${report.tools.sdkmanager ?? "not found"}`,
+    `avdmanager:     ${report.tools.avdmanager ?? "not found"}`,
+    `emulator:       ${report.tools.emulator ?? "not found"}`,
+    `adb:            ${report.tools.adb ?? "not found"}`,
+    `system images:  ${report.systemImages.length > 0 ? report.systemImages.join(", ") : "none installed"}`,
+    `KVM:            ${report.kvm.supported ? "available" : "unavailable"}`,
+    `AVDs:           ${report.avds.length > 0 ? report.avds.join(", ") : "none"}`
+  ];
+  if (report.systemImages.length === 0) {
+    lines.push(
+      `hint: install a system image with: ` + sdkmanagerInstallCommand(RECOMMENDED_SYSTEM_IMAGE)
+    );
+  }
+  return lines;
+}
+function emit2(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const line of describe(report)) {
+    console.log(line);
+  }
+  for (const error of report.errors) {
+    console.error(`error: ${error}`);
+  }
+}
+async function runSetupAndroid(opts, env = process.env) {
+  const snapshot = await collectSnapshot({ env, avdName: opts.avdName });
+  const android = snapshot.android;
+  const report = {
+    ok: true,
+    sdkRoot: android.sdkRoot,
+    tools: android.tools,
+    systemImages: android.systemImages.map((image) => image.packageId),
+    kvm: android.kvm,
+    avdName: android.avdName,
+    avds: android.avds,
+    avdExists: android.avdExists,
+    dryRun: opts.dryRun === true,
+    plan: [],
+    results: [],
+    errors: []
+  };
+  if (opts.createAvd !== true) {
+    emit2(report, opts.json === true);
+    return 0;
+  }
+  const result = planCreateAvd({
+    avdName: android.avdName,
+    systemImage: opts.systemImage,
+    sdkRoot: android.sdkRoot,
+    avdmanagerPath: android.tools.avdmanager,
+    installedImages: android.systemImages,
+    existingAvds: android.avds
+  });
+  if (!result.ok) {
+    report.ok = false;
+    report.errors.push(result.error);
+    emit2(report, opts.json === true);
+    return 1;
+  }
+  report.plan = result.plan.steps;
+  if (planHasCommandSteps(result.plan) && opts.dryRun !== true) {
+    const answer = await confirm(`Create AVD "${android.avdName}"?`, {
+      yes: opts.yes
+    });
+    if (answer === "non-interactive") {
+      report.ok = false;
+      report.errors.push(
+        "Refusing to create the AVD without consent in a non-interactive session. Re-run with --yes."
+      );
+      emit2(report, opts.json === true);
+      return 1;
+    }
+    if (answer === "no") {
+      report.ok = false;
+      report.errors.push("Aborted: AVD creation was declined.");
+      emit2(report, opts.json === true);
+      return 1;
+    }
+  }
+  const log = opts.json === true ? () => {
+  } : (line) => console.log(line);
+  if (opts.json !== true && android.avdExists) {
+    console.log(`AVD "${android.avdName}" already exists.`);
+  }
+  const execution = await executePlan(result.plan, {
+    dryRun: opts.dryRun,
+    env,
+    log
+  });
+  report.results = execution.results;
+  report.ok = execution.ok;
+  if (!execution.ok) {
+    report.errors.push(execution.error ?? "provisioning failed");
+  }
+  emit2(report, opts.json === true);
+  return execution.ok ? 0 : 1;
+}
+
+// src/commands/setup-lab-user.ts
+function emit3(report, json) {
+  if (json) {
+    console.log(JSON.stringify(report, null, 2));
+    return;
+  }
+  for (const error of report.errors) {
+    console.error(`error: ${error}`);
+  }
+}
+async function runSetupLabUser(opts, env = process.env) {
+  const snapshot = await collectSnapshot({
+    env,
+    labUserName: opts.name,
+    labUserHome: opts.home
+  });
+  const report = {
+    ok: false,
+    name: snapshot.labUser.name,
+    home: snapshot.labUser.home,
+    userExists: snapshot.labUser.exists,
+    dryRun: opts.dryRun === true,
+    plan: [],
+    results: [],
+    errors: []
+  };
+  const result = planLabUser({
+    name: snapshot.labUser.name,
+    home: snapshot.labUser.home,
+    userExists: snapshot.labUser.exists,
+    homeExists: snapshot.labUser.homeExists,
+    kvmPresent: snapshot.android.kvm.exists,
+    sudoPath: snapshot.sudo,
+    nonInteractive: process.stdin.isTTY !== true
+  });
+  if (!result.ok) {
+    report.errors.push(result.error);
+    emit3(report, opts.json === true);
+    return 1;
+  }
+  report.plan = result.plan.steps;
+  if (planHasCommandSteps(result.plan) && opts.dryRun !== true) {
+    const answer = await confirm(
+      `Create system user "${snapshot.labUser.name}" with home ${snapshot.labUser.home} (privileged, runs sudo)?`,
+      { yes: opts.yes }
+    );
+    if (answer === "non-interactive") {
+      report.errors.push(
+        "Refusing to provision the lab user without consent in a non-interactive session. Re-run with --yes."
+      );
+      emit3(report, opts.json === true);
+      return 1;
+    }
+    if (answer === "no") {
+      report.errors.push("Aborted: lab user provisioning was declined.");
+      emit3(report, opts.json === true);
+      return 1;
+    }
+  }
+  const log = opts.json === true ? () => {
+  } : (line) => console.log(line);
+  if (opts.json !== true && snapshot.labUser.exists) {
+    console.log(`User "${snapshot.labUser.name}" already exists.`);
+  }
+  const execution = await executePlan(result.plan, {
+    dryRun: opts.dryRun,
+    env,
+    log
+  });
+  report.results = execution.results;
+  report.ok = execution.ok;
+  if (!execution.ok) {
+    report.errors.push(execution.error ?? "provisioning failed");
+  }
+  emit3(report, opts.json === true);
+  if (opts.json !== true && execution.ok && opts.dryRun !== true) {
+    console.log(
+      `Lab user "${report.name}" is ready (home: ${report.home}).`
+    );
+  }
+  return execution.ok ? 0 : 1;
+}
+
+// src/program.ts
+var require2 = createRequire(import.meta.url);
+var { version } = require2("../package.json");
+var PROFILES = [
+  "flutter-desktop",
+  "android",
+  "desktop+android",
+  "generic"
+];
+var SESSION_TYPES = ["desktop", "android", "desktop+android"];
+function withJson(command) {
+  return command.option("--json", "machine-readable output");
+}
+function withProjectDir(command) {
+  return command.option(
+    "--project-dir <dir>",
+    "project directory (defaults to cwd)"
+  );
+}
+function withDesktopSession(command) {
+  return withProjectDir(
+    command.option("--session <id>", "desktop session id")
+  );
+}
+function withAndroidTarget(command) {
+  return withProjectDir(
+    command.option("--session <id>", "android session id").option("--serial <serial>", "adb device serial")
+  );
+}
+function buildProgram() {
+  const program = new Command().name("picklab").description(
+    "Native app and Android emulator automation for AI coding agents"
+  ).version(version);
+  program.command("doctor").description("Check dependencies and dedicated lab resources").option("--json", "machine-readable output").option("--fix", "apply repairs (privileged ones need --yes or a prompt)").option("--yes", "consent to privileged repairs without prompting").option("--dry-run", "print planned repairs without executing them").option("--project-dir <dir>", "project directory for config resolution").action(async (opts) => {
+    process.exitCode = await runDoctor(opts);
+  });
+  program.command("init").description("Initialize a PickLab project and provision lab resources").addOption(
+    new Option("--profile <profile>", "project profile").choices(PROFILES)
+  ).option("--yes", "non-interactive mode; fails closed when provisioning is impossible").option("--create-lab-user", "provision the dedicated lab user").option("--create-avd", "provision the dedicated Android AVD").option("--dry-run", "print the provisioning plan without executing it").option("--json", "machine-readable output").option("--project-dir <dir>", "project directory (defaults to cwd)").action(async (opts) => {
+    process.exitCode = await runInit(opts);
+  });
+  const setup = program.command("setup").description("Provision dedicated PickLab lab resources");
+  setup.command("lab-user").description("Create the dedicated locked lab user (uses sudo)").option("--name <name>", "lab user name").option("--home <dir>", "lab user home directory").option("--yes", "do not prompt for confirmation").option("--dry-run", "print the provisioning plan without executing it").option("--json", "machine-readable output").action(async (opts) => {
+    process.exitCode = await runSetupLabUser(opts);
+  });
+  setup.command("android").description("Detect the Android toolchain and create the dedicated AVD").option("--create-avd", "create the dedicated AVD").option("--avd-name <name>", "AVD name").option("--system-image <id>", 'system image id, e.g. "system-images;android-35;google_apis;x86_64"').option("--yes", "do not prompt for confirmation").option("--dry-run", "print the provisioning plan without executing it").option("--json", "machine-readable output").action(async (opts) => {
+    process.exitCode = await runSetupAndroid(opts);
+  });
+  const session = program.command("session").description("Manage desktop and Android lab sessions");
+  withJson(
+    withProjectDir(
+      session.command("create").description("Create a desktop (Xvfb) and/or Android emulator session").addOption(
+        new Option("--type <type>", "session type").choices(SESSION_TYPES).makeOptionMandatory()
+      ).option("--width <pixels>", "desktop display width").option("--height <pixels>", "desktop display height").option("--vnc", "expose the desktop display over VNC").option("--avd-name <name>", "Android AVD name")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runSessionCreate(opts);
+  });
+  withJson(
+    session.command("status").description("Show liveness for one or all sessions").argument("[id]", "session id")
+  ).action(async (id, opts) => {
+    process.exitCode = await runSessionStatus(id, opts);
+  });
+  withJson(
+    session.command("destroy").description("Destroy a session and stop its processes").argument("[id]", "session id").option("--all", "destroy all sessions")
+  ).action(async (id, opts) => {
+    process.exitCode = await runSessionDestroy(id, opts);
+  });
+  const desktop = program.command("desktop").description("Drive the desktop (X11) lab session");
+  withJson(
+    withDesktopSession(
+      desktop.command("launch").description("Launch an app inside the desktop session").argument("<command>", "executable to launch").argument("[args...]", "arguments for the executable (use -- before flags)").option("--cwd <dir>", "working directory for the app").option(
+        "--wait-window <pattern>",
+        "wait for a window whose name contains the pattern"
+      )
+    )
+  ).action(async (command, args, opts) => {
+    process.exitCode = await runDesktopLaunch(command, args, opts);
+  });
+  withJson(
+    withDesktopSession(
+      desktop.command("screenshot").description("Capture the desktop display into a run (or --out path)").option("--out <path>", "write to an explicit path instead of a run").option("--run <slug>", "run slug (default: desktop)")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runDesktopScreenshot(opts);
+  });
+  withJson(
+    withDesktopSession(
+      desktop.command("click").description("Click at the given coordinates").argument("<x>", "x coordinate").argument("<y>", "y coordinate").option("--button <n>", "mouse button (1-9, default 1)")
+    )
+  ).action(async (x, y, opts) => {
+    process.exitCode = await runDesktopClick(x, y, opts);
+  });
+  withJson(
+    withDesktopSession(
+      desktop.command("type").description("Type text into the focused window").argument("<text>", "text to type")
+    )
+  ).action(async (text, opts) => {
+    process.exitCode = await runDesktopType(text, opts);
+  });
+  withJson(
+    withDesktopSession(
+      desktop.command("key").description('Press a key or chord (e.g. "Return", "ctrl+s")').argument("<keys>", "key or chord to press")
+    )
+  ).action(async (keys, opts) => {
+    process.exitCode = await runDesktopKey(keys, opts);
+  });
+  const android = program.command("android").description("Drive the Android emulator lab session");
+  withJson(
+    withProjectDir(
+      android.command("start").description("Start an Android emulator session (alias for session create)").option("--avd-name <name>", "Android AVD name")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runSessionCreate({ ...opts, type: "android" });
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("install-apk").description("Install an APK on the device").argument("<apk>", "path to the APK")
+    )
+  ).action(async (apk, opts) => {
+    process.exitCode = await runAndroidInstallApk(apk, opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("launch-app").description("Launch an app by package name").argument("<package>", "application package name").option("--activity <activity>", 'activity to start (e.g. ".MainActivity")')
+    )
+  ).action(async (packageName, opts) => {
+    process.exitCode = await runAndroidLaunchApp(packageName, opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("screenshot").description("Capture the device screen into a run (or --out path)").option("--out <path>", "write to an explicit path instead of a run").option("--run <slug>", "run slug (default: android)")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAndroidScreenshot(opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("tap").description("Tap at the given coordinates").argument("<x>", "x coordinate").argument("<y>", "y coordinate")
+    )
+  ).action(async (x, y, opts) => {
+    process.exitCode = await runAndroidTap(x, y, opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("type").description("Type text into the focused field").argument("<text>", "text to type")
+    )
+  ).action(async (text, opts) => {
+    process.exitCode = await runAndroidType(text, opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("back").description("Press the back button")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAndroidBack(opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("home").description("Press the home button")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAndroidHome(opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("ui-tree").description("Dump the UI hierarchy as XML").option("--out <path>", "write the XML to a file instead of stdout")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAndroidUiTree(opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("logcat").description("Dump (or --clear) the device log with secrets redacted").option("--lines <n>", "number of recent lines (default 500)").option("--filter <spec>", 'logcat filter spec, e.g. "ActivityManager:I *:S"').option("--clear", "clear the log buffer instead of dumping it")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAndroidLogcat(opts);
+  });
+  withJson(
+    withAndroidTarget(
+      android.command("adb").description(
+        "Run a raw adb command (put adb flags after --); output is not redacted"
+      ).argument("[args...]", "adb arguments")
+    )
+  ).action(async (args, opts) => {
+    process.exitCode = await runAndroidAdb(args, opts);
+  });
+  const artifacts = program.command("artifacts").description("Inspect run artifacts recorded under .picklab/runs");
+  withJson(
+    withProjectDir(
+      artifacts.command("list").description("List recorded runs")
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runArtifactsList(opts);
+  });
+  withJson(
+    withProjectDir(
+      artifacts.command("open").description("Print (and open, when a display is available) a run directory").argument("<runId>", "run id")
+    )
+  ).action(async (runId, opts) => {
+    process.exitCode = await runArtifactsOpen(runId, opts);
+  });
+  withJson(
+    withProjectDir(
+      artifacts.command("report").description("Render a report for a run (default: latest)").argument("[runId]", "run id")
+    )
+  ).action(async (runId, opts) => {
+    process.exitCode = await runArtifactsReport(runId, opts);
+  });
+  const agents = program.command("agents").description("Register the PickLab MCP server with coding agents");
+  const collectConfigPath = (value, previous) => [
+    ...previous,
+    value
+  ];
+  withJson(
+    agents.command("list").description("List known agents and their registration status").option(
+      "--config-path <agent>=<path>",
+      "agent config file override, repeatable (e.g. cursor=/tmp/mcp.json)",
+      collectConfigPath,
+      []
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAgentsList(opts);
+  });
+  for (const [verb, description] of [
+    ["install", "Register the picklab MCP server with an agent"],
+    ["link", "Register the picklab MCP server with an agent (alias of install)"]
+  ]) {
+    withJson(
+      agents.command(verb).description(description).argument("<agent>", "agent name (codex, claude-code, cursor)").option(
+        "--config-path <path>",
+        "agent config file (overrides the default location)"
+      )
+    ).action(async (agent, opts) => {
+      process.exitCode = await runAgentsLink(agent, opts);
+    });
+  }
+  withJson(
+    agents.command("unlink").description("Remove the picklab MCP server entry from an agent config").argument("<agent>", "agent name (codex, claude-code, cursor, or custom)").option(
+      "--config-path <path>",
+      "agent config file (overrides the default location)"
+    )
+  ).action(async (agent, opts) => {
+    process.exitCode = await runAgentsUnlink(agent, opts);
+  });
+  withJson(
+    agents.command("doctor").description(
+      "Check agent registrations for broken symlinks and stale config"
+    ).option(
+      "--config-path <agent>=<path>",
+      "agent config file override, repeatable (e.g. cursor=/tmp/mcp.json)",
+      collectConfigPath,
+      []
+    )
+  ).action(async (opts) => {
+    process.exitCode = await runAgentsDoctorCommand(opts);
+  });
+  withJson(
+    agents.command("add").description("Store a custom agent MCP config snippet under ~/.picklab/agents").requiredOption("--name <name>", "custom agent name").requiredOption(
+      "--mcp-command <command>",
+      'MCP server command, split on whitespace (e.g. "picklab mcp serve")'
+    ).option("--force", "overwrite an existing custom agent with the same name")
+  ).action(async (opts) => {
+    process.exitCode = await runAgentsAdd(opts);
+  });
+  const mcp = program.command("mcp").description("Model Context Protocol server");
+  mcp.command("serve").description("Serve PickLab tools over MCP (stdio)").action(async () => {
+    process.exitCode = await runMcpServe();
+  });
+  return program;
+}
+
+// src/picklab.ts
+try {
+  await buildProgram().parseAsync();
+} catch (error) {
+  console.error(`error: ${error.message}`);
+  process.exitCode = 1;
+}