proof-artifacts 0.1.0-preview.0

package/bin/proof-artifacts.js

@@ -0,0 +1,2049 @@
+#!/usr/bin/env node
+import { execFileSync, spawnSync } from "node:child_process";
+import {
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  realpathSync,
+  readFileSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from "node:fs";
+import { homedir } from "node:os";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const rootDir = path.resolve(__dirname, "..");
+const defaultImage = "proof-artifacts/desktop:0.1.0";
+const defaultName = "default";
+const defaultWidth = "1280";
+const defaultHeight = "800";
+
+const args = process.argv.slice(2);
+const command = args[0] ?? "help";
+
+function printHelp() {
+  console.log(`proof-artifacts
+
+Proof artifacts for coding agents using isolated Linux desktops.
+
+Usage:
+  proof-artifacts doctor [--url URL] [--name NAME] [--deep] [--project PATH] [--keep] [--rebuild] [--allow-unsafe-url]
+  proof-artifacts detect [--project PATH] [--json]
+  proof-artifacts smoke [--name NAME] [--project PATH] [--url URL] [--keep] [--rebuild]
+  proof-artifacts start [--name NAME] [--project PATH] [--url URL] [--fullscreen] [--width 1280] [--height 800] [--novnc-port auto] [--network bridge|host] [--replace] [--image IMAGE] [--pull] [--no-build] [--rebuild]
+  proof-artifacts launch [--name NAME] [--window-match TEXT] [--wait-ms 10000] [--no-wait] -- <command...>
+  proof-artifacts open <url> [--name NAME] [--fullscreen] [--no-fullscreen] [--allow-unsafe-url]
+  proof-artifacts screenshot [--name NAME] [--label LABEL]
+  proof-artifacts record start [--name NAME] [--label LABEL]
+  proof-artifacts record stop [--name NAME]
+  proof-artifacts report [--name NAME]
+  proof-artifacts list [--json]
+  proof-artifacts status [--name NAME] [--json]
+  proof-artifacts artifacts [--name NAME]
+  proof-artifacts cleanup [--max-age-hours 24] [--all] [--dry-run] [--delete-artifacts]
+  proof-artifacts exec [--name NAME] [--stdin] -- <command...>
+  proof-artifacts stop [--name NAME] [--all]
+  proof-artifacts install-skill
+
+Aliases:
+  proof is the same CLI.
+`);
+}
+
+function parseOptions(input) {
+  const opts = {};
+  const rest = [];
+  for (let i = 0; i < input.length; i += 1) {
+    const arg = input[i];
+    if (arg === "--") {
+      rest.push(...input.slice(i + 1));
+      break;
+    }
+    if (arg.startsWith("--")) {
+      const [rawKey, inlineValue] = arg.slice(2).split("=", 2);
+      if (inlineValue !== undefined) {
+        opts[rawKey] = inlineValue;
+        continue;
+      }
+      const next = input[i + 1];
+      if (!next || next.startsWith("--")) {
+        opts[rawKey] = "true";
+      } else {
+        opts[rawKey] = next;
+        i += 1;
+      }
+      continue;
+    }
+    rest.push(arg);
+  }
+  return { opts, rest };
+}
+
+function isTruthy(value) {
+  return value === true || value === "true" || value === "1" || value === "yes";
+}
+
+function safeName(name) {
+  const normalized = String(name || defaultName)
+    .toLowerCase()
+    .replace(/[^a-z0-9_.-]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    || defaultName;
+  return normalized === "." || normalized === ".." ? defaultName : normalized;
+}
+
+function containerName(name) {
+  return `proof-artifacts-${safeName(name)}`;
+}
+
+function localSessionDir(name) {
+  return path.resolve(process.cwd(), ".proof-artifacts", "sessions", safeName(name));
+}
+
+function globalStateDir() {
+  return path.join(homedir(), ".proof-artifacts", "sessions");
+}
+
+function sessionIndexPath(name) {
+  return path.join(globalStateDir(), `${safeName(name)}.json`);
+}
+
+function sessionDir(name) {
+  const local = localSessionDir(name);
+  if (existsSync(path.join(local, "manifest.json")) || existsSync(path.join(local, "session.json"))) {
+    return local;
+  }
+  const index = readJsonFile(sessionIndexPath(name));
+  if (index?.artifacts) return path.resolve(index.artifacts);
+  return local;
+}
+
+function manifestPath(name) {
+  return path.join(sessionDir(name), "manifest.json");
+}
+
+function legacySessionPath(name) {
+  return path.join(sessionDir(name), "session.json");
+}
+
+function ensureDocker() {
+  const result = spawnSync("docker", ["version"], { stdio: "ignore" });
+  if (result.status !== 0) {
+    throw new Error("Docker is required. Install Docker Engine on the VPS and make sure this user can run `docker`.");
+  }
+}
+
+function run(commandName, commandArgs, options = {}) {
+  return execFileSync(commandName, commandArgs, {
+    stdio: options.stdio ?? "inherit",
+    encoding: options.encoding ?? "utf8",
+    ...options,
+  });
+}
+
+function docker(argsForDocker, options = {}) {
+  ensureDocker();
+  return run("docker", argsForDocker, options);
+}
+
+function dockerTry(argsForDocker, options = {}) {
+  ensureDocker();
+  return spawnSync("docker", argsForDocker, {
+    encoding: "utf8",
+    stdio: options.stdio ?? "pipe",
+    ...options,
+  });
+}
+
+function containerExists(name) {
+  const output = docker(["ps", "-a", "--filter", `name=^/${containerName(name)}$`, "--format", "{{.Names}}"], {
+    stdio: "pipe",
+  }).trim();
+  return output === containerName(name);
+}
+
+function containerRunning(name) {
+  const output = docker(["ps", "--filter", `name=^/${containerName(name)}$`, "--format", "{{.Names}}"], {
+    stdio: "pipe",
+  }).trim();
+  return output === containerName(name);
+}
+
+function managedContainerExists(name) {
+  if (!containerExists(name)) return false;
+  const result = dockerTry([
+    "inspect",
+    "--format",
+    "{{ index .Config.Labels \"proof-artifacts.managed\" }}",
+    containerName(name),
+  ]);
+  return result.status === 0 && result.stdout.trim() === "true";
+}
+
+function managedContainerArtifactDir(name) {
+  const result = dockerTry([
+    "inspect",
+    "--format",
+    "{{ index .Config.Labels \"proof-artifacts.artifacts\" }}",
+    containerName(name),
+  ]);
+  return result.status === 0 && result.stdout.trim() ? path.resolve(result.stdout.trim()) : null;
+}
+
+function sameResolvedPath(left, right) {
+  return canonicalPath(left) === canonicalPath(right);
+}
+
+function imageExists(image) {
+  return dockerTry(["image", "inspect", image], { stdio: "ignore" }).status === 0;
+}
+
+function buildImage(image) {
+  docker(["build", "-t", image, path.join(rootDir, "runtime")]);
+}
+
+function ensureRuntimeImage(opts = {}) {
+  const requestedImage = opts.image ?? process.env.PROOF_ARTIFACTS_IMAGE ?? defaultImage;
+  if (isTruthy(opts.rebuild)) {
+    buildImage(requestedImage);
+    return { image: requestedImage, requestedImage, imageSource: "rebuilt" };
+  }
+
+  if (imageExists(requestedImage)) {
+    return { image: requestedImage, requestedImage, imageSource: "local" };
+  }
+
+  if (requestedImage !== defaultImage && !isTruthy(opts.pull)) {
+    throw new Error(`Runtime image ${requestedImage} is not available locally. Build it locally first or pass --pull to pull a remote image explicitly.`);
+  }
+
+  const shouldPull = isTruthy(opts.pull);
+  if (shouldPull) {
+    console.log(`Runtime image not found locally. Pulling ${requestedImage}...`);
+    const pull = dockerTry(["pull", requestedImage], { stdio: "inherit" });
+    if (pull.status === 0) {
+      return { image: requestedImage, requestedImage, imageSource: "pulled" };
+    }
+    if (isTruthy(opts["no-build"])) {
+      throw new Error(`Could not pull runtime image ${requestedImage}, and --no-build was set.`);
+    }
+    console.log(`Pull failed; building local runtime image ${defaultImage} instead.`);
+  }
+
+  if (isTruthy(opts["no-build"])) {
+    throw new Error(`Runtime image ${requestedImage} is not available locally, and --no-build was set.`);
+  }
+
+  buildImage(defaultImage);
+  return {
+    image: defaultImage,
+    requestedImage,
+    imageSource: requestedImage === defaultImage ? "built" : "built-fallback",
+  };
+}
+
+function readJsonFile(file) {
+  if (!existsSync(file)) return undefined;
+  return JSON.parse(readFileSync(file, "utf8"));
+}
+
+function readPackageJson(project) {
+  return readJsonFile(path.join(project, "package.json")) ?? {};
+}
+
+function dependencyNames(pkg) {
+  return new Set(Object.keys({
+    ...(pkg.dependencies ?? {}),
+    ...(pkg.devDependencies ?? {}),
+    ...(pkg.optionalDependencies ?? {}),
+  }));
+}
+
+function scriptsMatching(pkg, patterns) {
+  const scripts = pkg.scripts ?? {};
+  return Object.entries(scripts)
+    .filter(([, script]) => patterns.some((pattern) => pattern.test(script)))
+    .map(([name]) => `npm run ${name}`);
+}
+
+function likelyDevServerScripts(pkg) {
+  const scripts = pkg.scripts ?? {};
+  const preferredNames = ["dev", "start", "serve"];
+  const excludedNames = /(test|coverage|lint|format|release|build|typecheck)/i;
+  const devServerCommand = /\b(vite|next|react-scripts|astro|svelte-kit|remix|webpack(?:-dev-server)?|webpack\s+serve)\b/i;
+  const matches = [];
+  for (const [name, script] of Object.entries(scripts)) {
+    if (excludedNames.test(name)) continue;
+    if (devServerCommand.test(script)) {
+      matches.push(`npm run ${name}`);
+    }
+  }
+  return [...new Set(matches)].sort((a, b) => {
+    const aName = a.replace(/^npm run /, "");
+    const bName = b.replace(/^npm run /, "");
+    const aRank = preferredNames.includes(aName) ? preferredNames.indexOf(aName) : preferredNames.length;
+    const bRank = preferredNames.includes(bName) ? preferredNames.indexOf(bName) : preferredNames.length;
+    return aRank - bRank || aName.localeCompare(bName);
+  });
+}
+
+function fileExists(project, relativePath) {
+  return existsSync(path.join(project, relativePath));
+}
+
+function findFiles(project, matcher, maxDepth = 3) {
+  const matches = [];
+  const skip = new Set([".git", "node_modules", ".proof-artifacts", "dist", "build", ".next"]);
+  function walk(dir, depth) {
+    if (depth > maxDepth || matches.length > 20) return;
+    for (const entry of readdirSync(dir)) {
+      if (skip.has(entry)) continue;
+      const full = path.join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(full);
+      } catch {
+        continue;
+      }
+      if (stat.isDirectory()) {
+        walk(full, depth + 1);
+      } else if (matcher(path.relative(project, full))) {
+        matches.push(path.relative(project, full));
+      }
+    }
+  }
+  if (existsSync(project)) walk(project, 0);
+  return matches.sort();
+}
+
+function findDirs(project, matcher, maxDepth = 3) {
+  const matches = [];
+  const skip = new Set([".git", "node_modules", ".proof-artifacts", "dist", "build", ".next"]);
+  function walk(dir, depth) {
+    if (depth > maxDepth || matches.length > 20) return;
+    for (const entry of readdirSync(dir)) {
+      if (skip.has(entry)) continue;
+      const full = path.join(dir, entry);
+      let stat;
+      try {
+        stat = statSync(full);
+      } catch {
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+      const relative = path.relative(project, full);
+      if (matcher(relative)) matches.push(relative);
+      walk(full, depth + 1);
+    }
+  }
+  if (existsSync(project)) walk(project, 0);
+  return matches.sort();
+}
+
+function detectProject(project) {
+  const resolved = path.resolve(project);
+  if (!existsSync(resolved)) throw new Error(`Project path does not exist: ${resolved}`);
+
+  const pkg = readPackageJson(resolved);
+  const deps = dependencyNames(pkg);
+  const scripts = pkg.scripts ?? {};
+  const findings = [];
+
+  const electronScripts = scriptsMatching(pkg, [/electron/i]);
+  const otherDesktopScripts = scriptsMatching(pkg, [/tauri/i, /neutralino/i, /nw(\s|$)/i]);
+  const desktopScripts = [...new Set([...electronScripts, ...otherDesktopScripts])];
+  const webScripts = likelyDevServerScripts(pkg);
+
+  if (deps.has("electron") || electronScripts.length > 0) {
+    findings.push({
+      kind: "linux-desktop",
+      confidence: "high",
+      canRunHere: true,
+      reason: "Electron project detected. If Linux dependencies install cleanly, it can run inside the proof-artifacts desktop.",
+      commands: desktopScripts.length > 0 ? desktopScripts : ["npm start"],
+      next: "Start a session, then use `proof-artifacts launch --name <task> --window-match <app-name> -- <command>`.",
+    });
+  }
+
+  if (deps.has("@tauri-apps/cli") || deps.has("@tauri-apps/api") || fileExists(resolved, "src-tauri/tauri.conf.json")) {
+    findings.push({
+      kind: "linux-desktop",
+      confidence: "medium",
+      canRunHere: true,
+      reason: "Tauri project detected. It may run on Linux, but the desktop container may need extra system libraries/Rust tooling.",
+      commands: desktopScripts.length > 0 ? desktopScripts : ["npm run tauri dev"],
+      next: "Try launching after dependencies are installed; if system libraries are missing, this runtime image may need project-specific packages.",
+    });
+  }
+
+  if (webScripts.length > 0 || deps.has("next") || deps.has("vite") || deps.has("@sveltejs/kit")) {
+    findings.push({
+      kind: "web",
+      confidence: webScripts.length > 0 ? "high" : "medium",
+      canRunHere: true,
+      reason: "Web dev server scripts/dependencies detected.",
+      commands: webScripts.length > 0 ? webScripts : ["npm run dev", "npm start"],
+      next: "Run the dev server on the VPS host, then start with `proof-artifacts start --url http://127.0.0.1:<port>` and open that URL.",
+    });
+  }
+
+  const xcodeDirs = findDirs(resolved, (file) => file.endsWith(".xcodeproj") || file.endsWith(".xcworkspace"), 2);
+  if (xcodeDirs.length > 0 || fileExists(resolved, "Podfile")) {
+    findings.push({
+      kind: "apple",
+      confidence: "high",
+      canRunHere: false,
+      reason: "Xcode/macOS/iOS project markers detected. The current runtime is Linux Docker/Xvfb, not macOS.",
+      commands: [],
+      next: "Use a macOS runner for macOS apps or iOS Simulator testing.",
+    });
+  }
+
+  const windowsFiles = findFiles(resolved, (file) => file.endsWith(".sln") || file.endsWith(".vcxproj") || file.endsWith(".wixproj"), 3);
+  if (windowsFiles.length > 0) {
+    findings.push({
+      kind: "windows",
+      confidence: "medium",
+      canRunHere: false,
+      reason: "Windows project markers detected. The current runtime is Linux Docker/Xvfb.",
+      commands: [],
+      next: "Use a Windows runner for native Windows desktop testing. Wine/VM support is intentionally out of scope for v0.",
+    });
+  }
+
+  if (fileExists(resolved, "android/build.gradle") || fileExists(resolved, "android/app/build.gradle") || fileExists(resolved, "gradlew")) {
+    findings.push({
+      kind: "android",
+      confidence: "medium",
+      canRunHere: false,
+      reason: "Android/Gradle project markers detected. The current runtime does not include an Android emulator.",
+      commands: [],
+      next: "Use an Android-capable runner/emulator backend later; do not try to force it through the desktop container.",
+    });
+  }
+
+  if (findings.length === 0) {
+    findings.push({
+      kind: "unknown",
+      confidence: "low",
+      canRunHere: false,
+      reason: "No known web, Linux desktop, mobile, macOS, or Windows project markers were detected.",
+      commands: [],
+      next: "Inspect project docs/package scripts manually before attempting visual testing.",
+    });
+  }
+
+  return { project: resolved, findings };
+}
+
+function readSessionMeta(name) {
+  return readJsonFile(manifestPath(name)) ?? readJsonFile(legacySessionPath(name)) ?? {};
+}
+
+function writeSessionMeta(name, meta) {
+  const dir = meta.artifacts ? path.resolve(meta.artifacts) : sessionDir(name);
+  writeSessionMetaInDir(name, dir, meta);
+}
+
+function writeSessionMetaInDir(name, dir, meta) {
+  mkdirSync(dir, { recursive: true });
+  const normalized = {
+    schemaVersion: 1,
+    events: [],
+    screenshots: [],
+    recordings: [],
+    ...meta,
+  };
+  const persisted = redactSensitive(normalized);
+  const payload = `${JSON.stringify(persisted, null, 2)}\n`;
+  writeFileSync(path.join(dir, "manifest.json"), payload);
+  writeFileSync(path.join(dir, "session.json"), payload);
+  mkdirSync(globalStateDir(), { recursive: true });
+  writeFileSync(sessionIndexPath(name), `${JSON.stringify({
+    name: safeName(name),
+    artifacts: dir,
+    project: persisted.project,
+    container: persisted.container,
+    updatedAt: new Date().toISOString(),
+  }, null, 2)}\n`);
+}
+
+function updateSessionMeta(name, updater) {
+  const current = readSessionMeta(name);
+  const next = updater({
+    schemaVersion: 1,
+    events: [],
+    screenshots: [],
+    recordings: [],
+    ...current,
+  });
+  writeSessionMeta(name, next);
+  return next;
+}
+
+function updateSessionMetaInDir(name, dir, updater) {
+  const current = readJsonFile(path.join(dir, "manifest.json")) ?? readJsonFile(path.join(dir, "session.json")) ?? {};
+  const next = updater({
+    schemaVersion: 1,
+    events: [],
+    screenshots: [],
+    recordings: [],
+    ...current,
+  });
+  writeSessionMetaInDir(name, dir, next);
+  return next;
+}
+
+function addEvent(name, type, details = {}) {
+  updateSessionMeta(name, (meta) => ({
+    ...meta,
+    events: [
+      ...(meta.events ?? []),
+      {
+        type,
+        at: new Date().toISOString(),
+        ...details,
+      },
+    ],
+  }));
+}
+
+function requireRunning(name) {
+  const status = containerStatus(name, sessionDir(name));
+  if (status.state === "conflict") {
+    throw new Error(`Session "${safeName(name)}" has a same-name container for different artifacts: ${status.containerArtifacts}. Use a unique --name or run from the matching project.`);
+  }
+  if (status.state !== "running") {
+    throw new Error(`Session "${safeName(name)}" is not running. Start it with: proof-artifacts start --name ${safeName(name)}`);
+  }
+}
+
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-");
+}
+
+function validateDimension(value, label) {
+  const text = String(value);
+  if (!/^[1-9][0-9]{1,4}$/.test(text)) {
+    throw new Error(`${label} must be a positive integer.`);
+  }
+  return text;
+}
+
+function parsePort(value) {
+  const port = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(port) || port < 1 || port > 65535) {
+    throw new Error(`Invalid noVNC port: ${value}`);
+  }
+  return port;
+}
+
+function parseNetworkMode(value) {
+  const mode = value ?? "bridge";
+  if (mode !== "bridge" && mode !== "host") {
+    throw new Error("--network must be either bridge or host.");
+  }
+  return mode;
+}
+
+function isLocalhostUrl(value) {
+  if (!value) return false;
+  try {
+    const parsed = new URL(String(value));
+    return ["127.0.0.1", "localhost", "[::1]", "::1", "0.0.0.0"].includes(parsed.hostname);
+  } catch {
+    return false;
+  }
+}
+
+function isBlockedMetadataUrl(value) {
+  if (!value) return false;
+  try {
+    const hostname = new URL(String(value)).hostname
+      .toLowerCase()
+      .replace(/^\[|\]$/g, "")
+      .replace(/\.$/, "");
+    return hostname.startsWith("169.254.")
+      || hostname.startsWith("::ffff:a9fe:")
+      || hostname === "fd00:ec2::254"
+      || hostname === "fe80::a9fe:a9fe"
+      || hostname === "metadata.google.internal"
+      || hostname === "metadata";
+  } catch {
+    return false;
+  }
+}
+
+function assertUrlAllowed(value, opts = {}) {
+  if (isBlockedMetadataUrl(value) && !isTruthy(opts["allow-unsafe-url"])) {
+    throw new Error(`Refusing to access cloud metadata URL: ${value}. Pass --allow-unsafe-url if you intentionally need this.`);
+  }
+}
+
+function tcpPortAvailable(port) {
+  const script = `
+const net = require("node:net");
+const port = Number(process.argv[1]);
+const server = net.createServer();
+server.once("error", () => process.exit(1));
+server.listen(port, "127.0.0.1", () => server.close(() => process.exit(0)));
+`;
+  return spawnSync(process.execPath, ["-e", script, String(port)], { stdio: "ignore" }).status === 0;
+}
+
+function findAvailablePort(startPort) {
+  const start = parsePort(startPort);
+  for (let port = start; port < start + 100; port += 1) {
+    if (tcpPortAvailable(port)) return port;
+  }
+  throw new Error(`Could not find an available localhost port starting at ${start}.`);
+}
+
+function findAvailableVncPorts() {
+  for (let noVncPort = 6080; noVncPort < 6180; noVncPort += 1) {
+    const vncPort = noVncPort - 180;
+    if (tcpPortAvailable(noVncPort) && tcpPortAvailable(vncPort)) {
+      return { noVncPort, vncPort };
+    }
+  }
+  throw new Error("Could not find available localhost ports for noVNC/VNC host-network mode.");
+}
+
+function mappedNoVncPort(name) {
+  const output = docker(["port", containerName(name), "6080/tcp"], { stdio: "pipe" }).trim();
+  const match = output.match(/127\.0\.0\.1:(\d+)/) ?? output.match(/0\.0\.0\.0:(\d+)/) ?? output.match(/:(\d+)$/);
+  if (!match) {
+    throw new Error(`Could not determine noVNC host port for session "${safeName(name)}".`);
+  }
+  return Number.parseInt(match[1], 10);
+}
+
+function dockerImageId(image) {
+  const result = dockerTry(["image", "inspect", image, "--format", "{{.Id}}"]);
+  return result.status === 0 ? result.stdout.trim() : null;
+}
+
+function hostUserSpec() {
+  if (typeof process.getuid !== "function" || typeof process.getgid !== "function") {
+    return null;
+  }
+  return `${process.getuid()}:${process.getgid()}`;
+}
+
+function wait(ms) {
+  run(process.execPath, ["-e", `setTimeout(() => {}, ${Number(ms) || 0})`], { stdio: "ignore" });
+}
+
+function waitForHttp(url, timeoutMs = 10000) {
+  const script = `
+const http = require("node:http");
+const https = require("node:https");
+const { URL } = require("node:url");
+const target = new URL(process.argv[1]);
+const client = target.protocol === "https:" ? https : http;
+const deadline = Date.now() + Number(process.argv[2]);
+function attempt() {
+  const req = client.get(target, (res) => {
+    res.resume();
+    if (res.statusCode >= 200 && res.statusCode < 500) process.exit(0);
+    retry();
+  });
+  req.on("error", retry);
+  req.setTimeout(1000, () => {
+    req.destroy();
+    retry();
+  });
+}
+function retry() {
+  if (Date.now() > deadline) process.exit(1);
+  setTimeout(attempt, 250);
+}
+attempt();
+`;
+  const result = spawnSync(process.execPath, ["-e", script, url, String(timeoutMs)], { stdio: "ignore" });
+  return result.status === 0;
+}
+
+function assertFileMinSize(file, minBytes, label) {
+  if (!existsSync(file)) {
+    throw new Error(`${label} was not created: ${file}`);
+  }
+  const size = statSync(file).size;
+  if (size < minBytes) {
+    throw new Error(`${label} is too small (${size} bytes): ${file}`);
+  }
+}
+
+function escapeHtml(value) {
+  return String(value)
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function redactSensitive(value) {
+  const sensitiveKey = /(token|secret|key|password|passwd|auth|cookie|credential|session)/i;
+  if (Array.isArray(value)) return value.map((item) => redactSensitive(item));
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.entries(value).map(([key, entry]) => [
+      key,
+      sensitiveKey.test(key) ? "[redacted]" : redactSensitive(entry),
+    ]));
+  }
+  if (typeof value === "string") {
+    return value
+      .replace(/([a-z][a-z0-9+.-]*:\/\/)([^:@/\s]+):([^@/\s]+)@/gi, "$1[redacted-user]:[redacted-password]@")
+      .replace(/([?&][^?&=\s]*(?:token|key|auth|signature|password|secret|credential|cookie)[^?&=\s]*=)[^&\s]+/gi, "$1[redacted]")
+      .replace(/\b([A-Z0-9_]*(?:TOKEN|SECRET|KEY|PASSWORD|PASSWD|AUTH|COOKIE|CREDENTIAL|SESSION)[A-Z0-9_]*=)(?:"[^"]*"|'[^']*'|[^\s]+)/gi, "$1[redacted]")
+      .replace(/(^|\s)(--?(?:token|secret|key|password|passwd|auth|cookie|credential|session)(?:=|\s+))(?:"[^"]*"|'[^']*'|[^\s]+)/gi, "$1$2[redacted]")
+      .replace(/\b(?:Bearer|Basic)\s+[A-Za-z0-9._~+/=-]+/gi, "[redacted-auth]")
+      .replace(/\bgh[pousr]_[A-Za-z0-9_]{20,}\b/g, "[redacted-github-token]")
+      .replace(/\bnpm_[A-Za-z0-9]{20,}\b/g, "[redacted-npm-token]")
+      .replace(/\bsk-[A-Za-z0-9_-]{20,}\b/g, "[redacted-openai-token]")
+      .replace(/\beyJ[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\.[A-Za-z0-9_-]{10,}\b/g, "[redacted-jwt]");
+  }
+  return value;
+}
+
+function listFiles(dir) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => statSync(path.join(dir, file)).isFile())
+    .sort();
+}
+
+function fileInfo(root, folder, file) {
+  const absolute = path.join(root, folder, file);
+  const stat = statSync(absolute);
+  const size = stat.size;
+  const info = {
+    file,
+    relativePath: path.join(folder, file),
+    size,
+    sizeLabel: formatBytes(size),
+    mtimeMs: stat.mtimeMs,
+    modifiedAt: stat.mtime.toISOString(),
+  };
+  if (file.endsWith(".mp4")) {
+    const durationSeconds = mediaDurationSeconds(absolute);
+    if (durationSeconds !== null) {
+      info.durationSeconds = durationSeconds;
+      info.durationLabel = formatDuration(durationSeconds * 1000);
+    }
+  }
+  return info;
+}
+
+function formatBytes(bytes) {
+  if (bytes < 1024) return `${bytes} B`;
+  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)} KB`;
+  return `${(bytes / (1024 * 1024)).toFixed(1)} MB`;
+}
+
+function durationMs(start, end) {
+  const started = Date.parse(start ?? "");
+  const ended = Date.parse(end ?? "");
+  if (!Number.isFinite(started) || !Number.isFinite(ended) || ended < started) return null;
+  return ended - started;
+}
+
+function formatDuration(ms) {
+  if (ms === null || ms === undefined) return "unknown";
+  if (ms < 1000) return `${ms} ms`;
+  const seconds = Math.round(ms / 100) / 10;
+  if (seconds < 60) return `${seconds.toFixed(seconds % 1 === 0 ? 0 : 1)} s`;
+  const minutes = Math.floor(seconds / 60);
+  const remainder = Math.round(seconds % 60);
+  return `${minutes} min ${remainder} s`;
+}
+
+function mediaDurationSeconds(file) {
+  const result = spawnSync("ffprobe", [
+    "-v", "error",
+    "-show_entries", "format=duration",
+    "-of", "default=noprint_wrappers=1:nokey=1",
+    file,
+  ], { encoding: "utf8", stdio: "pipe" });
+  if (result.status !== 0) return null;
+  const duration = Number.parseFloat(result.stdout.trim());
+  return Number.isFinite(duration) ? duration : null;
+}
+
+function artifactCounts(dir) {
+  return {
+    screenshots: listFiles(path.join(dir, "screenshots")).filter((file) => file.endsWith(".png")).length,
+    recordings: listFiles(path.join(dir, "recordings")).filter((file) => file.endsWith(".mp4")).length,
+    logs: listFiles(path.join(dir, "recordings")).filter((file) => file.endsWith(".log")).length
+      + listFiles(path.join(dir, "logs")).filter((file) => file.endsWith(".log")).length,
+  };
+}
+
+function reachableFromContainer(name, url) {
+  const result = dockerTry([
+    "exec",
+    containerName(name),
+    "curl",
+    "-sS",
+    "-o",
+    "/dev/null",
+    "-w",
+    "%{http_code}",
+    "--max-time",
+    "3",
+    url,
+  ]);
+  const statusCode = Number.parseInt(result.stdout.trim(), 10);
+  return {
+    ok: result.status === 0 && statusCode >= 200 && statusCode < 500,
+    statusCode: Number.isFinite(statusCode) ? statusCode : null,
+    stderr: result.stderr?.trim(),
+  };
+}
+
+function hostGatewayCandidate(url) {
+  const parsed = new URL(url);
+  if (!isLocalhostUrl(url)) return null;
+  parsed.hostname = "host.docker.internal";
+  return parsed.toString();
+}
+
+function diagnoseUrlAccess(name, url, opts = {}) {
+  let parsed;
+  try {
+    parsed = new URL(url);
+  } catch {
+    throw new Error(`Invalid --url value: ${url}`);
+  }
+  assertUrlAllowed(parsed.toString(), opts);
+
+  console.log(`Host URL check: ${url}`);
+  if (waitForHttp(url, 3000)) {
+    console.log("Host can reach URL.");
+  } else {
+    console.log("Host could not reach URL within 3s.");
+  }
+
+  if (opts.dockerAvailable === false) {
+    console.log("Docker is unavailable, so container reachability was not checked.");
+    return;
+  }
+
+  if (!containerRunning(name)) {
+    console.log(`Session "${safeName(name)}" is not running, so container reachability was not checked.`);
+    console.log(`Start one with: proof-artifacts start --name ${safeName(name)} --project . --url ${url}`);
+    return;
+  }
+
+  const meta = readSessionMeta(name);
+  const candidates = [url];
+  const gateway = hostGatewayCandidate(url);
+  if (gateway && meta.network !== "host" && !candidates.includes(gateway)) candidates.push(gateway);
+
+  console.log(`Container URL checks for session "${safeName(name)}" (${meta.network ?? "unknown"} network):`);
+  let anyWorked = false;
+  for (const candidate of candidates) {
+    const result = reachableFromContainer(name, candidate);
+    anyWorked = anyWorked || result.ok;
+    const statusLabel = result.statusCode ? ` (${result.statusCode})` : "";
+    console.log(`- ${candidate}: ${result.ok ? "ok" : "failed"}${statusLabel}`);
+    if (!result.ok && result.stderr) {
+      console.log(`  ${result.stderr.split("\n").slice(-1)[0]}`);
+    }
+  }
+
+  if (!anyWorked && isLocalhostUrl(url)) {
+    if (meta.network === "host") {
+      console.log("Host-network session could not reach the host URL. Check whether the app is still running and bound to localhost.");
+    } else {
+      console.log("Bridge networking could not reach this host-local app.");
+      console.log(`Recommended VPS fallback: proof-artifacts stop --name ${safeName(name)}`);
+      console.log(`Then start: proof-artifacts start --name ${safeName(name)} --project ${meta.project ?? "."} --url ${url}`);
+      console.log(`Then open: proof-artifacts open ${url} --name ${safeName(name)}`);
+    }
+  }
+}
+
+function hasSessionManifest(dir, name) {
+  const meta = readJsonFile(path.join(dir, "manifest.json")) ?? readJsonFile(path.join(dir, "session.json"));
+  return meta?.name === safeName(name);
+}
+
+function safeArtifactDeleteDir(dir, name) {
+  const resolved = path.resolve(dir);
+  const expectedSuffix = path.join(".proof-artifacts", "sessions", safeName(name));
+  return hasSessionManifest(resolved, name) && resolved.endsWith(expectedSuffix);
+}
+
+function collectSessions() {
+  const sessions = new Map();
+  const addSession = (name, dir, source) => {
+    const safe = safeName(name);
+    const resolved = path.resolve(dir);
+    const key = `${safe}:${resolved}`;
+    const existing = sessions.get(key);
+    sessions.set(key, {
+      name: safe,
+      dir: resolved,
+      source: existing ? `${existing.source}+${source}` : source,
+    });
+  };
+  const localRoot = path.resolve(process.cwd(), ".proof-artifacts", "sessions");
+  if (existsSync(localRoot)) {
+    for (const entry of readdirSync(localRoot)) {
+      const dir = path.join(localRoot, entry);
+      if (statSync(dir).isDirectory()) {
+        addSession(entry, dir, "local");
+      }
+    }
+  }
+  if (existsSync(globalStateDir())) {
+    for (const entry of readdirSync(globalStateDir())) {
+      if (!entry.endsWith(".json")) continue;
+      const name = safeName(entry.slice(0, -5));
+      const index = readJsonFile(path.join(globalStateDir(), entry));
+      if (index?.artifacts) {
+        addSession(name, index.artifacts, "global");
+      }
+    }
+  }
+  return [...sessions.values()].sort((a, b) => a.name.localeCompare(b.name) || a.source.localeCompare(b.source));
+}
+
+function containerStatus(name, expectedArtifacts = null) {
+  try {
+    if (!containerExists(name)) return { state: "missing", managed: false };
+    const managed = managedContainerExists(name);
+    const containerArtifacts = managedContainerArtifactDir(name);
+    if (expectedArtifacts && containerArtifacts && !sameResolvedPath(containerArtifacts, expectedArtifacts)) {
+      return {
+        state: "conflict",
+        managed,
+        containerArtifacts,
+        expectedArtifacts: path.resolve(expectedArtifacts),
+      };
+    }
+    const result = dockerTry(["inspect", "--format", "{{.State.Status}}", containerName(name)]);
+    return {
+      state: result.status === 0 ? result.stdout.trim() : "unknown",
+      managed,
+      containerArtifacts,
+    };
+  } catch (error) {
+    return { state: "unknown", managed: false, error: error.message };
+  }
+}
+
+function sessionStatusSummary(name, dir = sessionDir(name)) {
+  const meta = readJsonFile(path.join(dir, "manifest.json")) ?? readJsonFile(path.join(dir, "session.json")) ?? {};
+  const status = containerStatus(name, dir);
+  const state = lifecycleState(meta, status.state);
+  const counts = existsSync(dir) ? artifactCounts(dir) : { screenshots: 0, recordings: 0, logs: 0 };
+  const noVncReachable = state === "running" && meta.noVncUrl
+    ? waitForHttp(meta.noVncUrl, 1000)
+    : false;
+  return {
+    name: safeName(meta.name ?? name),
+    state,
+    managed: status.managed,
+    dockerError: status.error,
+    artifacts: dir,
+    artifactsExist: existsSync(dir),
+    project: meta.project ?? null,
+    noVncUrl: meta.noVncUrl ?? null,
+    noVncReachable,
+    network: meta.network ?? null,
+    targetUrl: meta.targetUrl ?? null,
+    browserFullscreen: meta.browserFullscreen ?? false,
+    startedAt: meta.startedAt ?? null,
+    stoppedAt: meta.stoppedAt ?? null,
+    durationMs: durationMs(meta.startedAt, meta.stoppedAt ?? (state === "running" ? new Date().toISOString() : null)),
+    activeRecording: meta.activeRecording ?? null,
+    counts,
+    events: meta.events ?? [],
+  };
+}
+
+function canonicalPath(file) {
+  return existsSync(file) ? realpathSync(file) : path.resolve(file);
+}
+
+function latestArtifact(items) {
+  if (items.length === 0) return null;
+  return [...items].sort((a, b) => {
+    const timeDiff = (a.mtimeMs ?? 0) - (b.mtimeMs ?? 0);
+    return timeDiff || a.file.localeCompare(b.file);
+  }).at(-1);
+}
+
+function lifecycleState(meta, dockerState) {
+  if (meta.stoppedAt) return "stopped";
+  if (dockerState === "running") return "running";
+  if (meta.name && dockerState === "missing") return "stale";
+  return dockerState ?? "unknown";
+}
+
+function buildReportSummary(meta, artifacts, state = null) {
+  const events = meta.events ?? [];
+  const failures = events.filter((event) => event.failedAt || (typeof event.status === "number" && event.status !== 0));
+  const eventCounts = events.reduce((counts, event) => {
+    const type = event.type ?? "event";
+    counts[type] = (counts[type] ?? 0) + 1;
+    return counts;
+  }, {});
+  const endedAt = meta.stoppedAt ?? (meta.activeRecording ? null : meta.updatedAt);
+  const elapsedMs = durationMs(meta.startedAt, meta.stoppedAt ?? new Date().toISOString());
+  return {
+    status: state ?? (meta.stoppedAt ? "stopped" : "active-or-stale"),
+    startedAt: meta.startedAt ?? null,
+    stoppedAt: meta.stoppedAt ?? null,
+    elapsedMs,
+    elapsedLabel: formatDuration(elapsedMs),
+    targetUrl: meta.targetUrl ?? null,
+    network: meta.network ?? null,
+    noVncUrl: meta.noVncUrl ?? null,
+    project: meta.project ?? null,
+    browserFullscreen: meta.browserFullscreen ?? false,
+    counts: {
+      screenshots: artifacts.screenshots.length,
+      recordings: artifacts.recordings.length,
+      logs: artifacts.logs.length,
+      events: events.length,
+      failures: failures.length,
+    },
+    latest: {
+      screenshot: latestArtifact(artifacts.screenshots),
+      recording: latestArtifact(artifacts.recordings),
+    },
+    activeRecording: meta.activeRecording ?? null,
+    lastEvent: events.at(-1) ?? null,
+    failures,
+    eventCounts,
+    endedAt,
+  };
+}
+
+function generateReport(name) {
+  const safe = safeName(name);
+  const dir = sessionDir(safe);
+  const meta = readSessionMeta(safe);
+  if (!meta.name) {
+    throw new Error(`Session "${safe}" was not found.`);
+  }
+  if (safeName(meta.name) !== safe) {
+    throw new Error(`Session manifest mismatch: expected "${safe}", found "${meta.name}".`);
+  }
+  if (meta.artifacts && canonicalPath(meta.artifacts) !== canonicalPath(dir)) {
+    throw new Error(`Session artifact path mismatch for "${safe}". Refusing to generate a report from stale metadata.`);
+  }
+  const redactedMeta = redactSensitive(meta);
+  const screenshots = listFiles(path.join(dir, "screenshots")).map((file) => fileInfo(dir, "screenshots", file));
+  const recordings = listFiles(path.join(dir, "recordings"))
+    .filter((file) => file.endsWith(".mp4"))
+    .map((file) => fileInfo(dir, "recordings", file));
+  const logs = [
+    ...listFiles(path.join(dir, "recordings"))
+      .filter((file) => file.endsWith(".log"))
+      .map((file) => fileInfo(dir, "recordings", file)),
+    ...listFiles(path.join(dir, "logs"))
+      .filter((file) => file.endsWith(".log"))
+      .map((file) => fileInfo(dir, "logs", file)),
+  ];
+  const status = containerStatus(safe, dir);
+  const summary = buildReportSummary(redactedMeta, { screenshots, recordings, logs }, lifecycleState(meta, status.state));
+  const report = {
+    generatedAt: new Date().toISOString(),
+    summary,
+    session: redactedMeta,
+    artifacts: {
+      root: dir,
+      screenshots,
+      recordings,
+      logs,
+    },
+  };
+  mkdirSync(dir, { recursive: true });
+  writeFileSync(path.join(dir, "report.json"), `${JSON.stringify(report, null, 2)}\n`);
+
+  const html = `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Proof Artifacts Report - ${escapeHtml(safe)}</title>
+  <style>
+    body { font-family: ui-sans-serif, system-ui, sans-serif; margin: 32px; color: #18181b; background: #fafaf9; }
+    main { max-width: 960px; margin: 0 auto; }
+    h1 { font-size: 32px; margin-bottom: 4px; }
+    h2 { margin-top: 32px; border-top: 1px solid #d6d3d1; padding-top: 20px; }
+    code, pre { background: #f5f5f4; border: 1px solid #e7e5e4; border-radius: 8px; }
+    code { padding: 2px 5px; }
+    pre { padding: 14px; overflow: auto; }
+    img { max-width: 100%; border: 1px solid #d6d3d1; border-radius: 12px; background: white; }
+    video { width: 100%; border: 1px solid #d6d3d1; border-radius: 12px; background: #18181b; }
+    .grid { display: grid; gap: 16px; grid-template-columns: repeat(auto-fit, minmax(240px, 1fr)); }
+    .card { background: white; border: 1px solid #e7e5e4; border-radius: 14px; padding: 16px; }
+    .metric { font-size: 28px; font-weight: 750; margin: 4px 0; }
+    .muted { color: #57534e; }
+    .fail { color: #991b1b; }
+    .timeline { list-style: none; padding: 0; }
+    .timeline li { padding: 10px 0; border-bottom: 1px solid #e7e5e4; }
+  </style>
+</head>
+<body>
+<main>
+  <p class="muted">Generated ${escapeHtml(report.generatedAt)}</p>
+  <h1>${escapeHtml(safe)}</h1>
+  <p><strong>Project:</strong> <code>${escapeHtml(redactedMeta.project ?? "unknown")}</code></p>
+  <p><strong>noVNC:</strong> <code>${escapeHtml(redactedMeta.noVncUrl ?? "unknown")}</code></p>
+  <p><strong>Artifacts:</strong> <code>${escapeHtml(dir)}</code></p>
+
+  <h2>Summary</h2>
+  <div class="grid">
+    <div class="card"><p class="muted">Status</p><p class="metric">${escapeHtml(summary.status)}</p><p>${escapeHtml(summary.elapsedLabel)}</p></div>
+    <div class="card"><p class="muted">Screenshots</p><p class="metric">${summary.counts.screenshots}</p><p>${summary.latest.screenshot ? escapeHtml(summary.latest.screenshot.file) : "none"}</p></div>
+    <div class="card"><p class="muted">Recordings</p><p class="metric">${summary.counts.recordings}</p><p>${summary.latest.recording ? `${escapeHtml(summary.latest.recording.file)} · ${escapeHtml(summary.latest.recording.durationLabel ?? summary.latest.recording.sizeLabel)}` : "none"}</p></div>
+    <div class="card"><p class="muted">Failures</p><p class="metric ${summary.counts.failures > 0 ? "fail" : ""}">${summary.counts.failures}</p><p>${summary.lastEvent ? `Last event: ${escapeHtml(summary.lastEvent.type ?? "event")}` : "No events"}</p></div>
+  </div>
+
+  ${summary.failures.length === 0 ? "" : `
+  <h2>Failure Context</h2>
+  <ol class="timeline">
+    ${summary.failures.map((event) => `<li><strong>${escapeHtml(event.type ?? "event")}</strong> <span class="muted">${escapeHtml(event.failedAt ?? event.at ?? "")}</span><br><code>${escapeHtml(JSON.stringify(event))}</code></li>`).join("")}
+  </ol>`}
+
+  <h2>Screenshots</h2>
+  <div class="grid">
+    ${screenshots.length === 0 ? "<p>No screenshots captured.</p>" : screenshots.map((item) => `
+      <figure class="card">
+        <img src="screenshots/${encodeURIComponent(item.file)}" alt="${escapeHtml(item.file)}">
+        <figcaption>${escapeHtml(item.file)} · ${escapeHtml(item.sizeLabel)}</figcaption>
+      </figure>`).join("")}
+  </div>
+
+  <h2>Recordings</h2>
+  <div class="grid">
+    ${recordings.length === 0 ? "<p>No recordings captured.</p>" : recordings.map((item) => `
+      <div class="card">
+        <video controls src="recordings/${encodeURIComponent(item.file)}"></video>
+        <p><a href="recordings/${encodeURIComponent(item.file)}">${escapeHtml(item.file)}</a> · ${escapeHtml(item.sizeLabel)}</p>
+      </div>`).join("")}
+  </div>
+
+  <h2>Timeline</h2>
+  ${(redactedMeta.events ?? []).length === 0 ? "<p>No events recorded.</p>" : `
+    <ol class="timeline">
+      ${(redactedMeta.events ?? []).map((event) => `
+        <li><strong>${escapeHtml(event.type ?? "event")}</strong> <span class="muted">${escapeHtml(event.at ?? "")}</span><br><code>${escapeHtml(JSON.stringify(event))}</code></li>`).join("")}
+    </ol>`}
+
+  <h2>Logs</h2>
+  ${logs.length === 0 ? "<p>No logs captured.</p>" : `
+    <ul>${logs.map((item) => `<li><a href="${escapeHtml(item.relativePath.split(path.sep).map(encodeURIComponent).join("/"))}">${escapeHtml(item.relativePath)}</a> · ${escapeHtml(item.sizeLabel)}</li>`).join("")}</ul>`}
+
+  <h2>Manifest</h2>
+  <pre>${escapeHtml(JSON.stringify(redactedMeta, null, 2))}</pre>
+</main>
+</body>
+</html>
+`;
+  writeFileSync(path.join(dir, "report.html"), html);
+  return {
+    reportJson: path.join(dir, "report.json"),
+    reportHtml: path.join(dir, "report.html"),
+  };
+}
+
+function cmdDoctor(input = []) {
+  const { opts } = parseOptions(input);
+  const checks = [];
+  const addCheck = (status, label, detail = "") => checks.push({ status, label, detail });
+  const nodeMajor = Number.parseInt(process.versions.node.split(".")[0], 10);
+
+  addCheck(nodeMajor >= 18 ? "pass" : "fail", "Node.js >= 18", process.version);
+  addCheck(process.platform === "linux" ? "pass" : "warn", "Host OS", `${process.platform}/${process.arch}; Linux VPS is the supported v0 target`);
+  addCheck(existsSync(path.join(rootDir, "runtime", "Dockerfile")) ? "pass" : "fail", "Runtime Dockerfile", path.join(rootDir, "runtime", "Dockerfile"));
+  addCheck(existsSync(path.join(rootDir, "runtime", "entrypoint.sh")) ? "pass" : "fail", "Runtime entrypoint", path.join(rootDir, "runtime", "entrypoint.sh"));
+
+  const dockerCli = spawnSync("docker", ["version"], { encoding: "utf8", stdio: "pipe" });
+  const dockerAvailable = dockerCli.status === 0;
+  addCheck(dockerAvailable ? "pass" : "fail", "Docker CLI", dockerAvailable ? "available" : "docker version failed");
+  if (dockerAvailable) {
+    const dockerDaemon = spawnSync("docker", ["info"], { encoding: "utf8", stdio: "pipe" });
+    addCheck(dockerDaemon.status === 0 ? "pass" : "fail", "Docker daemon", dockerDaemon.status === 0 ? "reachable" : dockerDaemon.stderr.trim());
+    addCheck(imageExists(defaultImage) ? "pass" : "warn", "Default runtime image", imageExists(defaultImage) ? defaultImage : "not built yet; first start/smoke can build it");
+  }
+
+  try {
+    const ports = findAvailableVncPorts();
+    addCheck("pass", "Host-network noVNC/VNC ports", `${ports.noVncPort}/${ports.vncPort} available`);
+  } catch (error) {
+    addCheck("warn", "Host-network noVNC/VNC ports", error.message);
+  }
+
+  const name = safeName(opts.name);
+  if (dockerAvailable && opts.name) {
+    const dir = sessionDir(name);
+    const status = containerStatus(name, dir);
+    addCheck(status.state === "running" ? "pass" : "warn", `Session "${name}"`, `container ${status.state}${status.managed ? ", managed" : ""}`);
+    if (status.state === "running") {
+      const runtime = dockerTry([
+        "exec",
+        "-e", "DISPLAY=:99",
+        containerName(name),
+        "sh",
+        "-lc",
+        "for bin in curl chromium ffmpeg wmctrl xdotool xdpyinfo x11vnc websockify; do command -v $bin >/dev/null || { echo missing $bin >&2; exit 10; }; done; xdpyinfo -display :99 >/dev/null; pgrep Xvfb >/dev/null; pgrep websockify >/dev/null; pgrep x11vnc >/dev/null",
+      ]);
+      addCheck(runtime.status === 0 ? "pass" : "fail", "Runtime desktop tools", runtime.status === 0 ? "available" : (runtime.stderr.trim() || `exit ${runtime.status}`));
+      const meta = readSessionMeta(name);
+      if (meta.noVncUrl) {
+        addCheck(waitForHttp(meta.noVncUrl, 3000) ? "pass" : "warn", "Session noVNC", meta.noVncUrl);
+      }
+    }
+  }
+
+  console.log("Proof Artifacts doctor");
+  console.log("This Linux-first v0 uses Docker, Xvfb, Chromium, noVNC, and ffmpeg inside the desktop container.");
+  for (const check of checks) {
+    const icon = check.status === "pass" ? "PASS" : check.status === "warn" ? "WARN" : "FAIL";
+    console.log(`[${icon}] ${check.label}${check.detail ? ` - ${check.detail}` : ""}`);
+  }
+
+  if (opts.url) {
+    console.log("");
+    diagnoseUrlAccess(name, String(opts.url), { ...opts, dockerAvailable });
+  }
+
+  if (isTruthy(opts.deep)) {
+    console.log("");
+    console.log("Deep doctor: running disposable smoke test.");
+    const deepName = safeName(opts.name ? `${opts.name}-doctor-${timestamp()}` : `doctor-${timestamp()}`);
+    const smokeArgs = ["--name", deepName, "--project", String(opts.project ?? process.cwd())];
+    if (opts.url) smokeArgs.push("--url", String(opts.url));
+    if (opts.keep) smokeArgs.push("--keep");
+    if (opts.rebuild) smokeArgs.push("--rebuild");
+    cmdSmoke(smokeArgs);
+  }
+
+  if (checks.some((check) => check.status === "fail")) {
+    process.exitCode = 1;
+  }
+}
+
+function cmdDetect(input) {
+  const { opts } = parseOptions(input);
+  const result = detectProject(opts.project ?? process.cwd());
+  if (isTruthy(opts.json)) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(`Project: ${result.project}`);
+  for (const finding of result.findings) {
+    console.log("");
+    console.log(`${finding.kind} (${finding.confidence})`);
+    console.log(`Can run in Linux desktop runtime: ${finding.canRunHere ? "yes" : "no"}`);
+    console.log(`Reason: ${finding.reason}`);
+    if (finding.commands.length > 0) {
+      console.log("Likely commands:");
+      for (const commandText of finding.commands) {
+        console.log(`- ${commandText}`);
+      }
+    }
+    console.log(`Next: ${finding.next}`);
+  }
+}
+
+function cmdStart(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name);
+  const width = validateDimension(opts.width ?? defaultWidth, "width");
+  const height = validateDimension(opts.height ?? defaultHeight, "height");
+  const project = path.resolve(opts.project ?? process.cwd());
+  const artifacts = localSessionDir(name);
+  const inferredNetwork = opts.network ?? (isLocalhostUrl(opts.url) ? "host" : "bridge");
+  const networkMode = parseNetworkMode(inferredNetwork);
+  const requestedPort = opts["novnc-port"] ?? "auto";
+  const autoHostPorts = networkMode === "host" && requestedPort === "auto" && !opts["vnc-port"]
+    ? findAvailableVncPorts()
+    : null;
+  const hostNoVncPort = networkMode === "host"
+    ? (autoHostPorts?.noVncPort ?? (requestedPort === "auto" ? findAvailablePort(6080) : parsePort(requestedPort)))
+    : null;
+  const hostVncPort = networkMode === "host"
+    ? (autoHostPorts?.vncPort ?? parsePort(opts["vnc-port"] ?? String(hostNoVncPort - 180)))
+    : null;
+  const portMapping = networkMode === "bridge"
+    ? (requestedPort === "auto" ? "127.0.0.1::6080" : `127.0.0.1:${parsePort(requestedPort)}:6080`)
+    : null;
+
+  if (networkMode === "host" && !autoHostPorts) {
+    if (!tcpPortAvailable(hostNoVncPort)) {
+      throw new Error(`Host noVNC port ${hostNoVncPort} is already in use. Choose another --novnc-port.`);
+    }
+    if (!tcpPortAvailable(hostVncPort)) {
+      throw new Error(`Host VNC port ${hostVncPort} is already in use. Choose another --vnc-port.`);
+    }
+  }
+
+  if (!existsSync(project)) {
+    throw new Error(`Project path does not exist: ${project}`);
+  }
+
+  if (containerRunning(name) && !isTruthy(opts.replace)) {
+    throw new Error(`Session "${name}" is already running. Use a unique --name, stop it first, or pass --replace to remove it.`);
+  }
+
+  if (containerExists(name)) {
+    if (!managedContainerExists(name)) {
+      throw new Error(`Container ${containerName(name)} exists but is not managed by proof-artifacts. Rename or remove it manually before starting this session.`);
+    }
+    const containerArtifacts = managedContainerArtifactDir(name);
+    if (containerArtifacts && !sameResolvedPath(containerArtifacts, artifacts)) {
+      throw new Error(`Container ${containerName(name)} belongs to different artifacts: ${containerArtifacts}. Use a unique --name or stop it from the matching project.`);
+    }
+    docker(["rm", "-f", containerName(name)]);
+  }
+
+  const imageInfo = ensureRuntimeImage(opts);
+
+  mkdirSync(artifacts, { recursive: true });
+
+  const userSpec = hostUserSpec();
+  const dockerRunArgs = [
+    "run",
+    "-d",
+    "--name", containerName(name),
+    "--label", "proof-artifacts.managed=true",
+    "--label", `proof-artifacts.session=${name}`,
+    "--label", `proof-artifacts.project=${project}`,
+    "--label", `proof-artifacts.artifacts=${artifacts}`,
+    "-e", `WIDTH=${width}`,
+    "-e", `HEIGHT=${height}`,
+    "-e", "DISPLAY=:99",
+    "-e", `NOVNC_PORT=${networkMode === "host" ? hostNoVncPort : 6080}`,
+    "-e", `NOVNC_LISTEN=${networkMode === "host" ? "127.0.0.1" : "0.0.0.0"}`,
+    "-e", `VNC_PORT=${networkMode === "host" ? hostVncPort : 5900}`,
+    "--mount", `type=bind,src=${project},dst=/workspace`,
+    "--mount", `type=bind,src=${artifacts},dst=/artifacts`,
+    imageInfo.image,
+  ];
+  if (networkMode === "host") {
+    dockerRunArgs.splice(6, 0, "--network", "host");
+  } else {
+    dockerRunArgs.splice(6, 0, "--add-host", "host.docker.internal:host-gateway", "-p", portMapping);
+  }
+  if (userSpec) {
+    dockerRunArgs.splice(6, 0, "--user", userSpec);
+  }
+
+  const result = dockerTry(dockerRunArgs);
+
+  if (result.status !== 0) {
+    if (containerExists(name)) {
+      docker(["rm", "-f", containerName(name)], { stdio: "ignore" });
+    }
+    const stderr = result.stderr?.trim();
+    throw new Error(stderr || "Failed to start desktop container.");
+  }
+
+  const selectedPort = networkMode === "host" ? hostNoVncPort : mappedNoVncPort(name);
+  const meta = {
+    schemaVersion: 1,
+    name,
+    width,
+    height,
+    project,
+    artifacts,
+    noVncUrl: `http://127.0.0.1:${selectedPort}/vnc.html`,
+    noVncPort: selectedPort,
+    noVncListen: networkMode === "host" ? "127.0.0.1" : "docker-published-127.0.0.1",
+    network: networkMode,
+    targetUrl: opts.url ?? null,
+    networkInferredFromUrl: opts.network ? false : isLocalhostUrl(opts.url),
+    browserFullscreen: isTruthy(opts.fullscreen),
+    vncPort: networkMode === "host" ? hostVncPort : 5900,
+    container: containerName(name),
+    containerUser: userSpec ?? "default",
+    image: imageInfo.image,
+    imageId: dockerImageId(imageInfo.image),
+    requestedImage: imageInfo.requestedImage,
+    imageSource: imageInfo.imageSource,
+    startedAt: new Date().toISOString(),
+    stoppedAt: null,
+    events: [],
+    screenshots: [],
+    recordings: [],
+  };
+  writeSessionMeta(name, meta);
+  addEvent(name, "start", {
+    container: containerName(name),
+    image: imageInfo.image,
+    imageSource: imageInfo.imageSource,
+    noVncPort: selectedPort,
+  });
+  if (waitForHttp(meta.noVncUrl, 15000)) {
+    addEvent(name, "novnc-ready", { url: meta.noVncUrl });
+  } else {
+    addEvent(name, "novnc-not-ready", { url: meta.noVncUrl, warning: "noVNC did not respond within 15s" });
+    console.log("Warning: noVNC did not respond within 15s. The container may still be starting.");
+  }
+
+  console.log(`Started desktop session "${name}".`);
+  console.log(`noVNC: http://127.0.0.1:${selectedPort}/vnc.html`);
+  if (opts.url) {
+    console.log(`Target URL: ${opts.url}`);
+    console.log(`Open it with: proof-artifacts open ${opts.url} --name ${name}${isTruthy(opts.fullscreen) ? " --fullscreen" : ""}`);
+  }
+  console.log(`Artifacts: ${artifacts}`);
+}
+
+function cmdLaunch(input) {
+  const { opts, rest } = parseOptions(input);
+  const name = safeName(opts.name);
+  const commandToRun = rest;
+  if (commandToRun.length === 0) {
+    throw new Error("Missing command. Usage: proof-artifacts launch [--name NAME] [--window-match TEXT] -- <command...>");
+  }
+  requireRunning(name);
+
+  const label = safeName(opts.label ?? `launch-${timestamp()}`);
+  const logFile = `/artifacts/logs/${label}.launch.log`;
+  const result = dockerTry([
+    "exec",
+    "-d",
+    "-e", "DISPLAY=:99",
+    "-e", "HOME=/tmp",
+    "-e", "XDG_CONFIG_HOME=/tmp/app-config",
+    "-e", "XDG_CACHE_HOME=/tmp/app-cache",
+    "-w", "/workspace",
+    containerName(name),
+    "sh",
+    "-lc",
+    `mkdir -p /tmp/app-config /tmp/app-cache /artifacts/logs && exec "$@" >${logFile} 2>&1`,
+    "proof-artifacts-launch",
+    ...commandToRun,
+  ]);
+  if (result.status !== 0) {
+    addEvent(name, "launch", {
+      command: commandToRun.join(" "),
+      status: result.status,
+      signal: result.signal,
+      failedAt: new Date().toISOString(),
+    });
+    throw new Error(`Launch failed in session "${name}": ${commandToRun.join(" ")}`);
+  }
+
+  const windowMatch = opts["window-match"] ?? path.basename(commandToRun[0]);
+  const waitMs = Number.parseInt(String(opts["wait-ms"] ?? "10000"), 10);
+  let windowFound = false;
+  if (!isTruthy(opts["no-wait"]) && windowMatch) {
+    const waitResult = dockerTry([
+      "exec",
+      "-e", "DISPLAY=:99",
+      "-e", `WINDOW_MATCH=${windowMatch}`,
+      "-e", `WAIT_MS=${Number.isFinite(waitMs) ? waitMs : 10000}`,
+      containerName(name),
+      "sh",
+      "-lc",
+      "deadline=$(( $(date +%s%3N) + WAIT_MS )); while [ $(date +%s%3N) -lt $deadline ]; do wid=$(xdotool search --onlyvisible --name \"$WINDOW_MATCH\" 2>/dev/null | tail -n 1 || true); if [ -n \"$wid\" ]; then xdotool windowactivate \"$wid\" windowraise \"$wid\" >/dev/null 2>&1 || true; exit 0; fi; sleep 0.2; done; exit 1",
+    ], { stdio: "pipe" });
+    windowFound = waitResult.status === 0;
+  }
+
+  addEvent(name, "launch", {
+    command: commandToRun.join(" "),
+    label,
+    logFile: path.join(sessionDir(name), "logs", `${label}.launch.log`),
+    windowMatch,
+    windowFound,
+    status: 0,
+  });
+  if (!isTruthy(opts["no-wait"]) && !windowFound) {
+    addEvent(name, "launch-window-missing", {
+      command: commandToRun.join(" "),
+      label,
+      logFile: path.join(sessionDir(name), "logs", `${label}.launch.log`),
+      windowMatch,
+      waitMs: Number.isFinite(waitMs) ? waitMs : 10000,
+      failedAt: new Date().toISOString(),
+    });
+    throw new Error(`Launch command started, but no visible window matched "${windowMatch}". Use --window-match with the app title or --no-wait.`);
+  }
+  console.log(`Launched in session "${name}": ${commandToRun.join(" ")}`);
+  console.log(path.join(sessionDir(name), "logs", `${label}.launch.log`));
+}
+
+function cmdOpen(input) {
+  const { opts, rest } = parseOptions(input);
+  const name = safeName(opts.name);
+  const url = rest[0];
+  if (!url) throw new Error("Missing URL. Usage: proof-artifacts open <url>");
+  assertUrlAllowed(url, opts);
+  requireRunning(name);
+  const meta = readSessionMeta(name);
+  const fullscreen = isTruthy(opts.fullscreen) || (meta.browserFullscreen && !isTruthy(opts["no-fullscreen"]));
+  const forceWindowed = isTruthy(opts["no-fullscreen"]);
+  const result = dockerTry([
+    "exec",
+    "-e", "DISPLAY=:99",
+    "-e", `TARGET_URL=${url}`,
+    "-e", `BROWSER_FULLSCREEN=${fullscreen ? "true" : "false"}`,
+    "-e", `BROWSER_FORCE_WINDOWED=${forceWindowed ? "true" : "false"}`,
+    "-e", `SCREEN_WIDTH=${validateDimension(meta.width ?? defaultWidth, "width")}`,
+    "-e", `SCREEN_HEIGHT=${validateDimension(meta.height ?? defaultHeight, "height")}`,
+    "-e", "HOME=/tmp",
+    "-e", "XDG_CONFIG_HOME=/tmp/chromium-config",
+    "-e", "XDG_CACHE_HOME=/tmp/chromium-cache",
+    containerName(name),
+    "sh",
+    "-lc",
+    `mkdir -p /tmp/chromium-profile /tmp/chromium-config /tmp/chromium-cache
+if [ "$BROWSER_FULLSCREEN" = "true" ] || [ "$BROWSER_FORCE_WINDOWED" = "true" ]; then
+  pkill -TERM chromium >/dev/null 2>&1 || true
+  sleep 0.4
+fi
+if [ "$BROWSER_FULLSCREEN" = "true" ]; then
+  chromium --test-type --no-sandbox --disable-dev-shm-usage --disable-crash-reporter --disable-breakpad --user-data-dir=/tmp/chromium-profile --new-window --window-position=0,0 --window-size="\${SCREEN_WIDTH},\${SCREEN_HEIGHT}" "$TARGET_URL" >/tmp/chromium.log 2>&1 &
+else
+  chromium --test-type --no-sandbox --disable-dev-shm-usage --disable-crash-reporter --disable-breakpad --user-data-dir=/tmp/chromium-profile --new-window "$TARGET_URL" >/tmp/chromium.log 2>&1 &
+fi
+for i in $(seq 1 100); do
+  wid=$(xdotool search --onlyvisible --class Chromium 2>/dev/null | tail -n 1 || true)
+  if [ -z "$wid" ]; then
+    wid=$(xdotool search --onlyvisible --name Chromium 2>/dev/null | tail -n 1 || true)
+  fi
+  if [ -n "$wid" ]; then
+    xdotool windowactivate "$wid" windowraise "$wid" >/dev/null 2>&1 || true
+    if [ "$BROWSER_FULLSCREEN" = "true" ]; then
+      if command -v wmctrl >/dev/null 2>&1; then
+        wmctrl -i -r "$wid" -b add,fullscreen >/dev/null 2>&1 || true
+        wmctrl -i -r "$wid" -b add,maximized_vert,maximized_horz >/dev/null 2>&1 || true
+      fi
+      xdotool windowmove "$wid" 0 0 >/dev/null 2>&1 || true
+      xdotool windowsize "$wid" "$SCREEN_WIDTH" "$SCREEN_HEIGHT" >/dev/null 2>&1 || true
+    else
+      if command -v wmctrl >/dev/null 2>&1; then
+        wmctrl -i -r "$wid" -b remove,fullscreen >/dev/null 2>&1 || true
+      fi
+    fi
+    exit 0
+  fi
+  sleep 0.1
+done
+cat /tmp/chromium.log >&2
+exit 1`,
+  ]);
+  if (result.status !== 0) {
+    addEvent(name, "open", {
+      url,
+      fullscreen,
+      status: result.status,
+      signal: result.signal,
+      stderr: result.stderr?.trim(),
+      failedAt: new Date().toISOString(),
+    });
+    throw new Error(`Failed to open ${url} in session "${name}".`);
+  }
+  addEvent(name, "open", { url, fullscreen });
+  console.log(`Opened ${url} in session "${name}"${fullscreen ? " (fullscreen)" : ""}.`);
+}
+
+function cmdScreenshot(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name);
+  const label = safeName(opts.label ?? `screenshot-${timestamp()}`);
+  const meta = readSessionMeta(name);
+  const width = validateDimension(meta.width ?? defaultWidth, "width");
+  const height = validateDimension(meta.height ?? defaultHeight, "height");
+  const target = `/artifacts/screenshots/${label}.png`;
+  requireRunning(name);
+  docker([
+    "exec",
+    "-e", "DISPLAY=:99",
+    containerName(name),
+    "sh",
+    "-lc",
+    `mkdir -p /artifacts/screenshots && ffmpeg -y -f x11grab -video_size ${width}x${height} -i :99.0 -frames:v 1 ${target} >/tmp/screenshot.log 2>&1`,
+  ]);
+  const file = path.join(sessionDir(name), "screenshots", `${label}.png`);
+  updateSessionMeta(name, (current) => ({
+    ...current,
+    screenshots: [
+      ...(current.screenshots ?? []),
+      { label, file, capturedAt: new Date().toISOString() },
+    ],
+    events: [
+      ...(current.events ?? []),
+      { type: "screenshot", at: new Date().toISOString(), label, file },
+    ],
+  }));
+  console.log(file);
+}
+
+function cmdRecord(input) {
+  const subcommand = input[0];
+  const { opts } = parseOptions(input.slice(1));
+  const name = safeName(opts.name);
+  requireRunning(name);
+
+  if (subcommand === "start") {
+    const label = safeName(opts.label ?? `recording-${timestamp()}`);
+    const meta = readSessionMeta(name);
+    const width = validateDimension(meta.width ?? defaultWidth, "width");
+    const height = validateDimension(meta.height ?? defaultHeight, "height");
+    docker([
+      "exec",
+      "-e", "DISPLAY=:99",
+      "-e", `RECORDING_LABEL=${label}`,
+      "-e", `VIDEO_SIZE=${width}x${height}`,
+      containerName(name),
+      "sh",
+      "-lc",
+      "test ! -f /tmp/proof-artifacts-recording.pid || { echo recording already running >&2; exit 2; }; mkdir -p /artifacts/recordings; nohup ffmpeg -y -f x11grab -framerate 30 -video_size \"$VIDEO_SIZE\" -i :99.0 -c:v libx264 -preset ultrafast -crf 23 -pix_fmt yuv420p \"/artifacts/recordings/$RECORDING_LABEL.mp4\" >/artifacts/recordings/$RECORDING_LABEL.log 2>&1 & echo $! >/tmp/proof-artifacts-recording.pid; echo \"$RECORDING_LABEL\" >/tmp/proof-artifacts-recording.label",
+    ]);
+    const file = path.join(sessionDir(name), "recordings", `${label}.mp4`);
+    updateSessionMeta(name, (current) => ({
+      ...current,
+      activeRecording: { label, file, startedAt: new Date().toISOString() },
+      events: [
+        ...(current.events ?? []),
+        { type: "record-start", at: new Date().toISOString(), label, file },
+      ],
+    }));
+    console.log(`Recording started: ${file}`);
+    return;
+  }
+
+  if (subcommand === "stop") {
+    const meta = readSessionMeta(name);
+    const active = meta.activeRecording;
+    docker([
+      "exec",
+      containerName(name),
+      "sh",
+      "-lc",
+      "test -f /tmp/proof-artifacts-recording.pid || { echo no recording running >&2; exit 2; }; kill -INT \"$(cat /tmp/proof-artifacts-recording.pid)\"; sleep 1; rm -f /tmp/proof-artifacts-recording.pid; cat /tmp/proof-artifacts-recording.label; rm -f /tmp/proof-artifacts-recording.label",
+    ]);
+    updateSessionMeta(name, (current) => {
+      const stoppedAt = new Date().toISOString();
+      const recording = current.activeRecording
+        ? { ...current.activeRecording, stoppedAt, durationMs: durationMs(current.activeRecording.startedAt, stoppedAt) }
+        : { label: "unknown", stoppedAt };
+      const { activeRecording, ...rest } = current;
+      return {
+        ...rest,
+        recordings: [...(current.recordings ?? []), recording],
+        events: [
+          ...(current.events ?? []),
+          { type: "record-stop", at: stoppedAt, label: active?.label ?? "unknown", file: active?.file },
+        ],
+      };
+    });
+    console.log(`Recording stopped. Artifacts: ${path.join(sessionDir(name), "recordings")}`);
+    return;
+  }
+
+  throw new Error("Usage: proof-artifacts record start|stop");
+}
+
+function cmdReport(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name);
+  const report = generateReport(name);
+  console.log(report.reportHtml);
+  console.log(report.reportJson);
+}
+
+function cmdExec(input) {
+  const { opts, rest } = parseOptions(input);
+  const name = safeName(opts.name);
+  const useStdin = isTruthy(opts.stdin);
+  const commandToRun = rest;
+  if (commandToRun.length === 0) throw new Error("Missing command. Usage: proof-artifacts exec [--stdin] -- <command...>");
+  requireRunning(name);
+  const result = dockerTry([
+    "exec",
+    ...(useStdin ? ["-i"] : []),
+    "-e", "DISPLAY=:99",
+    "-w", "/workspace",
+    containerName(name),
+    ...commandToRun,
+  ], { stdio: "inherit" });
+  if (result.status !== 0) {
+    addEvent(name, "exec", {
+      command: commandToRun.join(" "),
+      stdin: useStdin,
+      status: result.status,
+      signal: result.signal,
+      failedAt: new Date().toISOString(),
+    });
+    throw new Error(`Command failed in session "${name}": ${commandToRun.join(" ")}`);
+  }
+  addEvent(name, "exec", { command: commandToRun.join(" "), stdin: useStdin, status: 0 });
+}
+
+function cmdArtifacts(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name);
+  console.log(sessionDir(name));
+}
+
+function cmdList(input) {
+  const { opts } = parseOptions(input);
+  const sessions = collectSessions().map((session) => {
+    const summary = sessionStatusSummary(session.name, session.dir);
+    return redactSensitive({
+      source: session.source,
+      ...summary,
+      events: undefined,
+    });
+  });
+  if (isTruthy(opts.json)) {
+    console.log(JSON.stringify(sessions, null, 2));
+    return;
+  }
+  if (sessions.length === 0) {
+    console.log("No proof-artifacts sessions found.");
+    return;
+  }
+  for (const session of sessions) {
+    const counts = session.counts ?? { screenshots: 0, recordings: 0, logs: 0 };
+    console.log(`${session.name} [${session.state}] ${session.source}`);
+    console.log(`  artifacts: ${session.artifacts}${session.artifactsExist ? "" : " (missing)"}`);
+    console.log(`  project: ${session.project ?? "unknown"}`);
+    console.log(`  noVNC: ${session.noVncUrl ?? "unknown"}${session.noVncReachable ? " (reachable)" : ""}`);
+    console.log(`  captured: ${counts.screenshots} screenshot(s), ${counts.recordings} recording(s), ${counts.logs} log(s)`);
+    if (session.startedAt) console.log(`  started: ${session.startedAt}`);
+    if (session.stoppedAt) console.log(`  stopped: ${session.stoppedAt}`);
+  }
+}
+
+function cmdStatus(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name);
+  const dir = sessionDir(name);
+  const meta = readJsonFile(path.join(dir, "manifest.json")) ?? readJsonFile(path.join(dir, "session.json"));
+  const status = sessionStatusSummary(name, dir);
+  if (!meta?.name && (status.state === "missing" || status.state === "unknown")) {
+    throw new Error(`Session "${name}" was not found.`);
+  }
+  const output = redactSensitive(status);
+  if (isTruthy(opts.json)) {
+    console.log(JSON.stringify(output, null, 2));
+    return;
+  }
+  console.log(`${output.name} [${output.state}]${output.managed ? " managed" : ""}`);
+  console.log(`Artifacts: ${output.artifacts}${output.artifactsExist ? "" : " (missing)"}`);
+  console.log(`Project: ${output.project ?? "unknown"}`);
+  console.log(`Network: ${output.network ?? "unknown"}`);
+  console.log(`Target URL: ${output.targetUrl ?? "none"}`);
+  console.log(`noVNC: ${output.noVncUrl ?? "unknown"}${output.noVncReachable ? " (reachable)" : ""}`);
+  console.log(`Started: ${output.startedAt ?? "unknown"}`);
+  console.log(`Stopped: ${output.stoppedAt ?? "not recorded"}`);
+  console.log(`Elapsed: ${formatDuration(output.durationMs)}`);
+  console.log(`Artifacts captured: ${output.counts.screenshots} screenshot(s), ${output.counts.recordings} recording(s), ${output.counts.logs} log(s)`);
+  if (output.activeRecording) {
+    console.log(`Active recording: ${output.activeRecording.label ?? "unknown"}`);
+  }
+  const recentEvents = (output.events ?? []).slice(-5);
+  if (recentEvents.length > 0) {
+    console.log("Recent events:");
+    for (const event of recentEvents) {
+      console.log(`- ${event.at ?? ""} ${event.type ?? "event"}`);
+    }
+  }
+}
+
+function managedContainerNames() {
+  const result = dockerTry(["ps", "-a", "--filter", "label=proof-artifacts.managed=true", "--format", "{{.Names}}"]);
+  if (result.status !== 0) throw new Error(result.stderr.trim() || "Could not list managed proof-artifacts containers.");
+  return result.stdout.split("\n").map((line) => line.trim()).filter(Boolean);
+}
+
+function managedSessionNameForContainer(name) {
+  const result = dockerTry([
+    "inspect",
+    "--format",
+    "{{ index .Config.Labels \"proof-artifacts.session\" }}",
+    name,
+  ]);
+  return result.status === 0 && result.stdout.trim() ? safeName(result.stdout.trim()) : safeName(name.replace(/^proof-artifacts-/, ""));
+}
+
+function cmdStop(input) {
+  const { opts } = parseOptions(input);
+  if (isTruthy(opts.all)) {
+    const containers = managedContainerNames();
+    if (containers.length === 0) {
+      console.log("No managed proof-artifacts containers are running or stopped.");
+      return;
+    }
+    for (const name of containers) {
+      const sessionName = managedSessionNameForContainer(name);
+      const artifactDir = managedContainerArtifactDir(sessionName);
+      docker(["rm", "-f", name]);
+      const updateMeta = artifactDir && existsSync(artifactDir)
+        ? (updater) => updateSessionMetaInDir(sessionName, artifactDir, updater)
+        : (updater) => updateSessionMeta(sessionName, updater);
+      updateMeta((current) => ({
+        ...current,
+        stoppedAt: new Date().toISOString(),
+        events: [
+          ...(current.events ?? []),
+          { type: "stop", at: new Date().toISOString(), container: name, all: true },
+        ],
+      }));
+      console.log(`Stopped managed desktop session "${sessionName}" (${name}).`);
+    }
+    console.log("Artifacts were kept.");
+    return;
+  }
+
+  const name = safeName(opts.name);
+  const status = containerStatus(name, sessionDir(name));
+  if (status.state === "conflict") {
+    throw new Error(`Session "${name}" has a same-name container for different artifacts: ${status.containerArtifacts}. Refusing to remove it from this project.`);
+  }
+  if (status.state !== "missing" && status.state !== "unknown") {
+    if (!status.managed) {
+      throw new Error(`Container ${containerName(name)} exists but is not managed by proof-artifacts. Refusing to remove it.`);
+    }
+    docker(["rm", "-f", containerName(name)]);
+    updateSessionMeta(name, (current) => ({
+      ...current,
+      stoppedAt: new Date().toISOString(),
+      events: [
+        ...(current.events ?? []),
+        { type: "stop", at: new Date().toISOString(), container: containerName(name) },
+      ],
+    }));
+    console.log(`Stopped desktop session "${name}".`);
+  } else {
+    const meta = readSessionMeta(name);
+    if (meta.name) {
+      updateSessionMeta(name, (current) => ({
+        ...current,
+        stoppedAt: new Date().toISOString(),
+        events: [
+          ...(current.events ?? []),
+          { type: "stop", at: new Date().toISOString(), container: containerName(name), alreadyMissing: true },
+        ],
+      }));
+    }
+    console.log(`Session "${name}" is not running.`);
+  }
+}
+
+function cmdCleanup(input) {
+  const { opts } = parseOptions(input);
+  const dryRun = isTruthy(opts["dry-run"]);
+  const removeAll = isTruthy(opts.all);
+  const deleteArtifacts = isTruthy(opts["delete-artifacts"]);
+  const maxAgeHours = Number.parseFloat(opts["max-age-hours"] ?? "24");
+  if (!removeAll && (!Number.isFinite(maxAgeHours) || maxAgeHours < 0)) {
+    throw new Error("--max-age-hours must be a non-negative number.");
+  }
+  const cutoff = Date.now() - maxAgeHours * 60 * 60 * 1000;
+  let removed = 0;
+  for (const session of collectSessions()) {
+    const { name, dir, source } = session;
+    if (!existsSync(dir)) continue;
+    const meta = readJsonFile(path.join(dir, "manifest.json")) ?? readJsonFile(path.join(dir, "session.json")) ?? {};
+    const status = containerStatus(name, dir);
+    if (!removeAll && (status.state === "running" || status.state === "unknown" || status.state === "conflict" || meta.activeRecording)) continue;
+    const referenceTime = Date.parse(meta.stoppedAt ?? meta.startedAt ?? statSync(dir).mtime.toISOString());
+    const expired = removeAll || referenceTime < cutoff;
+    if (!expired) continue;
+
+    const action = dryRun ? "Would clean" : "Cleaning";
+    console.log(`${action} ${source} session "${name}" (${dir})`);
+    if (!dryRun) {
+      if (source.includes("global") && managedContainerExists(name)) {
+        docker(["rm", "-f", containerName(name)], { stdio: "ignore" });
+      }
+      if (deleteArtifacts) {
+        if (!safeArtifactDeleteDir(dir, name)) {
+          throw new Error(`Refusing to delete artifacts for "${name}" because ${dir} is not a verified session artifact directory.`);
+        }
+        rmSync(dir, { recursive: true, force: true });
+        if (source.includes("global")) {
+          rmSync(sessionIndexPath(name), { force: true });
+        }
+      }
+    }
+    removed += 1;
+  }
+  const artifactNote = deleteArtifacts ? "containers and artifacts" : "containers only; artifacts kept";
+  console.log(`${dryRun ? "Matched" : "Cleaned"} ${removed} session(s) (${artifactNote}).`);
+}
+
+function cmdSmoke(input) {
+  const { opts } = parseOptions(input);
+  const name = safeName(opts.name ?? `smoke-${timestamp()}`);
+  const defaultSmokePage = "<!doctype html><title>Proof Artifacts Smoke</title><style>body{font:32px system-ui;margin:48px;background:#f7f0df;color:#18130a}button{font:inherit;padding:16px 22px}</style><h1>Proof Artifacts Smoke</h1><p id=status>ready</p><button onclick=\"status.textContent='clicked '+new Date().toISOString()\">Click me</button>";
+  const url = opts.url ?? `data:text/html,${encodeURIComponent(defaultSmokePage)}`;
+  const project = path.resolve(opts.project ?? process.cwd());
+  const keep = isTruthy(opts.keep);
+  const startArgs = [
+    "--name", name,
+    "--project", project,
+    "--width", String(opts.width ?? defaultWidth),
+    "--height", String(opts.height ?? defaultHeight),
+  ];
+  if (opts["novnc-port"]) startArgs.push("--novnc-port", String(opts["novnc-port"]));
+  if (opts.url) startArgs.push("--url", String(opts.url));
+  if (opts.network) startArgs.push("--network", String(opts.network));
+  if (opts["vnc-port"]) startArgs.push("--vnc-port", String(opts["vnc-port"]));
+  if (opts.image) startArgs.push("--image", String(opts.image));
+  if (opts.pull) startArgs.push("--pull");
+  if (opts["no-build"]) startArgs.push("--no-build");
+  if (opts.rebuild) startArgs.push("--rebuild");
+
+  let smokePhase = "init";
+  try {
+    smokePhase = "doctor";
+    console.log("Smoke: checking Docker...");
+    cmdDoctor();
+    smokePhase = "start";
+    console.log("Smoke: starting desktop...");
+    cmdStart(startArgs);
+    smokePhase = "novnc";
+    const meta = readSessionMeta(name);
+    if (meta.noVncUrl && waitForHttp(meta.noVncUrl, 15000)) {
+      addEvent(name, "smoke-novnc-ready", { url: meta.noVncUrl });
+      console.log(`Smoke: noVNC responded at ${meta.noVncUrl}`);
+    } else {
+      throw new Error(`noVNC did not respond at ${meta.noVncUrl}`);
+    }
+    smokePhase = "open";
+    console.log("Smoke: opening browser...");
+    cmdOpen([url, "--name", name]);
+    wait(1000);
+    smokePhase = "screenshot";
+    console.log("Smoke: taking screenshot...");
+    cmdScreenshot(["--name", name, "--label", "smoke-page"]);
+    smokePhase = "record";
+    console.log("Smoke: recording a short interaction...");
+    cmdRecord(["start", "--name", name, "--label", "smoke-recording"]);
+    smokePhase = "interaction";
+    docker([
+      "exec",
+      "-e", "DISPLAY=:99",
+      containerName(name),
+      "sh",
+      "-lc",
+      "xdotool mousemove 120 120 click 1 mousemove 420 260 key Tab key Tab >/tmp/smoke-interaction.log 2>&1",
+    ]);
+    wait(1500);
+    smokePhase = "record-stop";
+    cmdRecord(["stop", "--name", name]);
+    const artifactRoot = sessionDir(name);
+    smokePhase = "validate-artifacts";
+    assertFileMinSize(path.join(artifactRoot, "screenshots", "smoke-page.png"), 1000, "Smoke screenshot");
+    assertFileMinSize(path.join(artifactRoot, "recordings", "smoke-recording.mp4"), 1000, "Smoke recording");
+    addEvent(name, "smoke-pass");
+    const report = generateReport(name);
+    console.log("Smoke passed.");
+    console.log(report.reportHtml);
+  } catch (error) {
+    if (existsSync(manifestPath(name))) {
+      try {
+        addEvent(name, "smoke-fail", {
+          phase: smokePhase,
+          error: error.message,
+          status: 1,
+          failedAt: new Date().toISOString(),
+        });
+      } catch {
+        // Preserve the original smoke failure; failure logging is best-effort.
+      }
+    }
+    throw error;
+  } finally {
+    if (!keep && containerExists(name)) {
+      cmdStop(["--name", name]);
+    }
+    if (existsSync(manifestPath(name))) {
+      generateReport(name);
+    }
+  }
+}
+
+function cmdInstallSkill() {
+  const source = path.join(rootDir, "skills", "proof-artifacts");
+  const target = path.join(homedir(), ".codex", "skills", "proof-artifacts");
+  rmSync(target, { recursive: true, force: true });
+  mkdirSync(path.dirname(target), { recursive: true });
+  cpSync(source, target, { recursive: true });
+  console.log(`Installed Codex skill: ${target}`);
+}
+
+try {
+  switch (command) {
+    case "help":
+    case "--help":
+    case "-h":
+      printHelp();
+      break;
+    case "doctor":
+      cmdDoctor(args.slice(1));
+      break;
+    case "detect":
+      cmdDetect(args.slice(1));
+      break;
+    case "smoke":
+      cmdSmoke(args.slice(1));
+      break;
+    case "start":
+      cmdStart(args.slice(1));
+      break;
+    case "launch":
+      cmdLaunch(args.slice(1));
+      break;
+    case "open":
+      cmdOpen(args.slice(1));
+      break;
+    case "screenshot":
+      cmdScreenshot(args.slice(1));
+      break;
+    case "record":
+      cmdRecord(args.slice(1));
+      break;
+    case "report":
+      cmdReport(args.slice(1));
+      break;
+    case "list":
+      cmdList(args.slice(1));
+      break;
+    case "status":
+      cmdStatus(args.slice(1));
+      break;
+    case "exec":
+      cmdExec(args.slice(1));
+      break;
+    case "artifacts":
+      cmdArtifacts(args.slice(1));
+      break;
+    case "cleanup":
+      cmdCleanup(args.slice(1));
+      break;
+    case "stop":
+      cmdStop(args.slice(1));
+      break;
+    case "install-skill":
+    case "install-codex-skill":
+      cmdInstallSkill();
+      break;
+    default:
+      printHelp();
+      process.exitCode = 1;
+  }
+} catch (error) {
+  console.error(error.message);
+  process.exitCode = 1;
+}