codebyplan 1.13.14 → 1.13.16

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.14";
+    VERSION = "1.13.16";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -697,7 +697,7 @@ function isRetryable(err) {
   return false;
 }
 function delay(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 async function request(method, path8, options) {
   const url = buildUrl(path8, options?.params);
@@ -1055,7 +1055,7 @@ var init_device_flow = __esm({
         this.name = "OAuthInvalidClientError";
       }
     };
-    defaultSleep = (ms) => new Promise((resolve7) => setTimeout(resolve7, ms));
+    defaultSleep = (ms) => new Promise((resolve8) => setTimeout(resolve8, ms));
   }
 });
 
@@ -1880,9 +1880,9 @@ async function writeMcpConfig(scope) {
   return configPath;
 }
 async function fetchRepos(auth) {
-  const baseUrl2 = (process.env.CODEBYPLAN_API_URL ?? "https://www.codebyplan.com").replace(/\/$/, "");
+  const baseUrl3 = (process.env.CODEBYPLAN_API_URL ?? "https://www.codebyplan.com").replace(/\/$/, "");
   const headers = auth.kind === "oauth" ? { Authorization: `Bearer ${await getAccessToken()}` } : { "x-api-key": auth.apiKey };
-  const res = await fetch(`${baseUrl2}/api/repos`, {
+  const res = await fetch(`${baseUrl3}/api/repos`, {
     headers,
     signal: AbortSignal.timeout(1e4)
   });
@@ -1987,6 +1987,11 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
     JSON.stringify({}, null, 2) + "\n",
     "utf-8"
   );
+  await writeFile6(
+    join9(codebyplanDir, "cmux.json"),
+    JSON.stringify({}, null, 2) + "\n",
+    "utf-8"
+  );
   const statuslinePath = join9(codebyplanDir, "statusline.json");
   let statuslineExists = false;
   try {
@@ -2004,7 +2009,7 @@ async function writeCodebyplanDirectory(projectPath, selectedRepo, deviceId) {
   await writeLocalConfig(projectPath, { device_id: deviceId });
   console.log(`  Created ${codebyplanDir}/`);
   console.log(
-    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, statusline.json`
+    `    repo.json, server.json, git.json, shipment.json, vendor.json, e2e.json, eslint.json, cmux.json, statusline.json`
   );
   console.log(`    device.local.json (gitignored)`);
   const gitignoreAction = await ensureManagedGitignoreBlock(projectPath);
@@ -2081,8 +2086,8 @@ async function runSetup() {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync8 } = await import("node:child_process");
-      branch = execSync8("git symbolic-ref --short HEAD", {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -3720,9 +3725,9 @@ async function eslintInit(repoId, projectPath) {
   Install ${missingPkgs.length} missing packages? [Y/n] `
     );
     if (confirmed) {
-      const { execSync: execSync8 } = await import("node:child_process");
+      const { execSync: execSync11 } = await import("node:child_process");
       try {
-        execSync8(installCmd, { cwd: projectPath, stdio: "inherit" });
+        execSync11(installCmd, { cwd: projectPath, stdio: "inherit" });
         console.log("  Packages installed.\n");
       } catch (err) {
         console.error(
@@ -4157,7 +4162,7 @@ function setRetryDelayMs(ms) {
   RETRY_DELAY_MS = ms;
 }
 function sleep(ms) {
-  return new Promise((resolve7) => setTimeout(resolve7, ms));
+  return new Promise((resolve8) => setTimeout(resolve8, ms));
 }
 function isTransientMcpError(err) {
   if (!(err instanceof McpError)) return false;
@@ -6374,32 +6379,318 @@ var init_version_status = __esm({
   }
 });
 
+// src/cli/upload-e2e-images.ts
+var upload_e2e_images_exports = {};
+__export(upload_e2e_images_exports, {
+  runUploadE2eImagesCommand: () => runUploadE2eImagesCommand
+});
+import { readFile as readFile15 } from "node:fs/promises";
+import { join as join21, basename, resolve as resolve5 } from "node:path";
+import { execSync as execSync7 } from "node:child_process";
+function baseUrl2() {
+  return (process.env.CODEBYPLAN_API_URL ?? "https://www.codebyplan.com").replace(/\/$/, "");
+}
+function parseArgs(args) {
+  const flags = {};
+  const booleans = /* @__PURE__ */ new Set();
+  const positionals = [];
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const next = args[i + 1];
+      if (next !== void 0 && !next.startsWith("--")) {
+        flags[key] = next;
+        i++;
+      } else {
+        booleans.add(key);
+      }
+    } else {
+      positionals.push(arg);
+    }
+  }
+  return {
+    checkpointId: positionals[0],
+    repoId: flags["repo-id"],
+    baseBranch: flags["base-branch"] ?? "main",
+    json: booleans.has("json"),
+    dryRun: booleans.has("dry-run")
+  };
+}
+async function readE2eConfig(projectPath) {
+  try {
+    const raw = await readFile15(
+      join21(projectPath, ".codebyplan", "e2e.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return {};
+  }
+}
+function collectPngsFromGitDiff(projectPath, frameworkName, frameworkConfig, baseBranch) {
+  const pathspec = frameworkConfig.test_dir ?? frameworkConfig.app;
+  if (!pathspec) {
+    return [];
+  }
+  let stdout7;
+  try {
+    stdout7 = execSync7(
+      `git diff --name-status --diff-filter=AM "${baseBranch}...HEAD" -- "${pathspec}"`,
+      { cwd: projectPath, encoding: "utf-8" }
+    );
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("unknown revision") || msg.includes("ambiguous argument") || msg.includes("not a git repository")) {
+      return [];
+    }
+    process.stderr.write(`upload-e2e-images: git diff failed: ${msg}
+`);
+    return [];
+  }
+  const results = [];
+  for (const line of stdout7.split("\n")) {
+    const trimmed = line.trim();
+    if (!trimmed) continue;
+    const tab = trimmed.indexOf("	");
+    if (tab === -1) continue;
+    const status = trimmed.slice(0, tab).trim();
+    const filePath = trimmed.slice(tab + 1).trim();
+    if (!filePath.endsWith(".png")) continue;
+    if (frameworkName === "playwright" && !filePath.includes(".spec.ts-snapshots/"))
+      continue;
+    const isNew = status === "A";
+    results.push({
+      absolutePath: join21(projectPath, filePath),
+      filename: basename(filePath),
+      framework: frameworkName,
+      is_new: isNew
+    });
+  }
+  return results;
+}
+function deriveTestName(absolutePath) {
+  const segments = absolutePath.replace(/\\/g, "/").split("/");
+  for (let i = segments.length - 2; i >= 0; i--) {
+    const seg = segments[i];
+    if (seg && seg.endsWith(".spec.ts-snapshots")) {
+      return seg.replace(".spec.ts-snapshots", "");
+    }
+  }
+  return basename(absolutePath, ".png");
+}
+function buildManifestItem(png) {
+  const testName = deriveTestName(png.absolutePath);
+  const pageOrScreen = basename(png.absolutePath, ".png");
+  return {
+    filename: png.filename,
+    test_name: testName,
+    page_or_screen: pageOrScreen,
+    framework: png.framework,
+    is_new: png.is_new,
+    baseline_diff_pct: null
+  };
+}
+async function runUploadE2eImagesCommand(args) {
+  const parsed = parseArgs(args);
+  if (!parsed.checkpointId) {
+    process.stderr.write(
+      "upload-e2e-images: missing required argument <checkpointId>\n\nUsage: codebyplan upload-e2e-images <checkpointId> [--repo-id <uuid>]\n       [--base-branch <name>] [--json] [--dry-run]\n\nExample: codebyplan upload-e2e-images chk-abc-123 --base-branch main\n"
+    );
+    process.exit(1);
+  }
+  const checkpointId = parsed.checkpointId;
+  const projectPath = resolve5(process.cwd());
+  let repoId = parsed.repoId;
+  if (!repoId) {
+    const found = await findCodebyplanConfig(projectPath);
+    repoId = found?.contents.repo_id;
+  }
+  if (!repoId) {
+    process.stderr.write(
+      "upload-e2e-images: could not determine repo_id.\nPass --repo-id <uuid> or ensure .codebyplan/repo.json exists.\n"
+    );
+    process.exit(1);
+  }
+  const e2eConfig = await readE2eConfig(projectPath);
+  const frameworks = e2eConfig.frameworks ?? {};
+  const allPngs = [];
+  for (const [name, cfg] of Object.entries(frameworks)) {
+    if (!cfg.enabled || !cfg.auto_run) continue;
+    const pngs = collectPngsFromGitDiff(
+      projectPath,
+      name,
+      cfg,
+      parsed.baseBranch
+    );
+    allPngs.push(...pngs);
+  }
+  if (allPngs.length === 0) {
+    process.stdout.write(
+      `No new/changed e2e screenshots found for ${checkpointId}
+`
+    );
+    process.exit(0);
+  }
+  const manifest = allPngs.map(buildManifestItem);
+  if (parsed.dryRun) {
+    if (parsed.json) {
+      process.stdout.write(JSON.stringify(manifest, null, 2) + "\n");
+    } else {
+      process.stdout.write(
+        `[dry-run] Would upload ${manifest.length} screenshot(s) for checkpoint ${checkpointId}:
+`
+      );
+      for (const item of manifest) {
+        const label = item.is_new ? "NEW" : "CHANGED";
+        process.stdout.write(
+          `  [${label}] ${item.filename} (${item.framework}, test: ${item.test_name})
+`
+        );
+      }
+    }
+    process.exit(0);
+  }
+  const formData = new FormData();
+  formData.append("checkpointId", checkpointId);
+  formData.append("repoId", repoId);
+  formData.append("manifest", JSON.stringify(manifest));
+  for (const png of allPngs) {
+    let bytes;
+    try {
+      bytes = await readFile15(png.absolutePath);
+    } catch {
+      process.stderr.write(
+        `upload-e2e-images: could not read file: ${png.absolutePath}
+`
+      );
+      process.exit(1);
+    }
+    const blob = new Blob([bytes], { type: "image/png" });
+    formData.append("files", blob, png.filename);
+  }
+  const auth = await getAuthHeaders();
+  const url = `${baseUrl2()}/api/checkpoint-images`;
+  let res;
+  try {
+    res = await fetch(url, {
+      method: "POST",
+      headers: auth.headers,
+      body: formData
+    });
+  } catch (err) {
+    process.stderr.write(
+      `upload-e2e-images: network error: ${err instanceof Error ? err.message : String(err)}
+`
+    );
+    process.exit(1);
+  }
+  if (!res.ok) {
+    let bodyText = "";
+    try {
+      bodyText = await res.text();
+    } catch {
+    }
+    process.stderr.write(
+      `upload-e2e-images: API returned ${res.status}: ${bodyText}
+`
+    );
+    process.exit(1);
+  }
+  let result;
+  try {
+    result = await res.json();
+  } catch {
+    process.stderr.write(
+      "upload-e2e-images: failed to parse API response as JSON\n"
+    );
+    process.exit(1);
+  }
+  if (parsed.json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + "\n");
+    return;
+  }
+  process.stdout.write(
+    `Uploaded ${manifest.length} screenshot(s) for checkpoint ${checkpointId}
+`
+  );
+  const paths = result.data.stored_paths ?? [];
+  for (const p of paths) {
+    process.stdout.write(`  ${p}
+`);
+  }
+}
+var init_upload_e2e_images = __esm({
+  "src/cli/upload-e2e-images.ts"() {
+    "use strict";
+    init_api();
+    init_flags();
+  }
+});
+
+// src/lib/cmux.ts
+import { readFileSync as readFileSync6 } from "node:fs";
+import { join as join22 } from "node:path";
+function insideCmux() {
+  return !!process.env.CMUX_WORKSPACE_ID;
+}
+function resolveCmuxBin() {
+  return process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
+}
+function readCmuxConfig(projectRoot) {
+  let raw = {};
+  try {
+    const text = readFileSync6(
+      join22(projectRoot, ".codebyplan", "cmux.json"),
+      "utf-8"
+    );
+    raw = JSON.parse(text);
+  } catch {
+    raw = {};
+  }
+  if (typeof raw !== "object" || raw === null || Array.isArray(raw)) {
+    raw = {};
+  }
+  const config = raw;
+  return {
+    ...config,
+    auto_status: config.auto_status ?? true,
+    auto_dev_server: config.auto_dev_server ?? true
+  };
+}
+var init_cmux = __esm({
+  "src/lib/cmux.ts"() {
+    "use strict";
+  }
+});
+
 // src/cli/cmux-sync.ts
 var cmux_sync_exports = {};
 __export(cmux_sync_exports, {
   runCmuxSync: () => runCmuxSync
 });
-import { execSync as execSync7, execFileSync as execFileSync2 } from "node:child_process";
-import { basename } from "node:path";
+import { execSync as execSync8, execFileSync as execFileSync2 } from "node:child_process";
+import { basename as basename2 } from "node:path";
 async function runCmuxSync() {
   try {
-    if (!process.env.CMUX_WORKSPACE_ID) {
+    if (!insideCmux()) {
       process.exit(0);
     }
-    const bin = process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
+    const bin = resolveCmuxBin();
     let branch = "";
     try {
-      branch = execSync7("git rev-parse --abbrev-ref HEAD", {
+      branch = execSync8("git rev-parse --abbrev-ref HEAD", {
         encoding: "utf8"
       }).trim();
     } catch {
     }
     let folder = "";
+    let toplevel = "";
     try {
-      const toplevel = execSync7("git rev-parse --show-toplevel", {
+      toplevel = execSync8("git rev-parse --show-toplevel", {
         encoding: "utf8"
       }).trim();
-      folder = basename(toplevel);
+      folder = basename2(toplevel);
     } catch {
     }
     if (branch) {
@@ -6426,6 +6717,26 @@ async function runCmuxSync() {
       } catch {
       }
     }
+    try {
+      const cmuxCfg = readCmuxConfig(toplevel || process.cwd());
+      if (typeof cmuxCfg.workspace_color === "string" && cmuxCfg.workspace_color !== "") {
+        try {
+          execFileSync2(bin, [
+            "workspace-action",
+            "--action",
+            "set-color",
+            "--color",
+            cmuxCfg.workspace_color
+          ]);
+        } catch {
+        }
+      } else {
+        process.stdout.write(
+          "cmux: no workspace color set \u2014 run /cbp-setup-cmux\n"
+        );
+      }
+    } catch {
+    }
     process.exit(0);
   } catch (err) {
     if (err instanceof ProcessExitSignal) throw err;
@@ -6436,23 +6747,346 @@ var init_cmux_sync = __esm({
   "src/cli/cmux-sync.ts"() {
     "use strict";
     init_process_exit_signal();
+    init_cmux();
+  }
+});
+
+// src/cli/cmux-status.ts
+var cmux_status_exports = {};
+__export(cmux_status_exports, {
+  normalizeProgress: () => normalizeProgress,
+  runCmuxStatus: () => runCmuxStatus
+});
+import { execSync as execSync9, execFileSync as execFileSync3 } from "node:child_process";
+function normalizeProgress(raw) {
+  if (raw.includes("/")) {
+    const [numStr, denStr] = raw.split("/", 2);
+    const num = parseInt(numStr ?? "", 10);
+    const den = parseInt(denStr ?? "", 10);
+    if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return "0";
+    const ratio = num / den;
+    const clamped2 = Math.max(0, Math.min(1, ratio));
+    return String(clamped2);
+  }
+  const f = parseFloat(raw);
+  if (!Number.isFinite(f)) return null;
+  const clamped = Math.max(0, Math.min(1, f));
+  return String(clamped);
+}
+async function runCmuxStatus(args) {
+  try {
+    if (!insideCmux()) {
+      process.exit(0);
+    }
+    let toplevel = "";
+    try {
+      toplevel = execSync9("git rev-parse --show-toplevel", {
+        encoding: "utf8"
+      }).trim();
+    } catch {
+      toplevel = process.cwd();
+    }
+    const cfg = readCmuxConfig(toplevel);
+    if (cfg.auto_status === false) {
+      process.exit(0);
+    }
+    let checkpoint;
+    let task;
+    let qa;
+    let progress;
+    let clear = false;
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--checkpoint" && i + 1 < args.length) {
+        checkpoint = args[++i];
+      } else if (flag === "--task" && i + 1 < args.length) {
+        task = args[++i];
+      } else if (flag === "--qa" && i + 1 < args.length) {
+        qa = args[++i];
+      } else if (flag === "--progress" && i + 1 < args.length) {
+        progress = args[++i];
+      } else if (flag === "--clear") {
+        clear = true;
+      }
+    }
+    const bin = resolveCmuxBin();
+    if (clear) {
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-checkpoint"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-task"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-status", "cbp-qa"]);
+      } catch {
+      }
+      try {
+        execFileSync3(bin, ["clear-progress"]);
+      } catch {
+      }
+    } else {
+      if (checkpoint !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-checkpoint", checkpoint]);
+        } catch {
+        }
+      }
+      if (task !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-task", task]);
+        } catch {
+        }
+      }
+      if (qa !== void 0) {
+        try {
+          execFileSync3(bin, ["set-status", "cbp-qa", qa]);
+        } catch {
+        }
+      }
+      if (progress !== void 0) {
+        const decimalStr = normalizeProgress(progress);
+        if (decimalStr !== null) {
+          try {
+            execFileSync3(bin, ["set-progress", decimalStr]);
+          } catch {
+          }
+        }
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.exit(0);
+  }
+}
+var init_cmux_status = __esm({
+  "src/cli/cmux-status.ts"() {
+    "use strict";
+    init_process_exit_signal();
+    init_cmux();
+  }
+});
+
+// src/cli/cmux-serve.ts
+var cmux_serve_exports = {};
+__export(cmux_serve_exports, {
+  probePort: () => probePort,
+  runCmuxServe: () => runCmuxServe
+});
+import { execSync as execSync10, execFileSync as execFileSync4 } from "node:child_process";
+import { readFileSync as readFileSync7 } from "node:fs";
+import * as net from "node:net";
+import { join as join23 } from "node:path";
+function resolveAppDir(allocation, toplevel) {
+  if (allocation.command !== null && allocation.working_dir !== null) {
+    const wd = allocation.working_dir;
+    const dir = wd.startsWith(toplevel + "/") ? wd.slice(toplevel.length + 1) : wd;
+    return { appDir: dir, devCommand: allocation.command };
+  }
+  const label = allocation.label ?? "";
+  if (label === "E2E Tests") return { skip: "skip-e2e" };
+  if (label.includes("Web Dev") && !label.toLowerCase().includes("desktop")) {
+    return { appDir: "apps/web", devCommand: null };
+  }
+  if (label.toLowerCase().includes("desktop")) {
+    return { appDir: "apps/desktop", devCommand: null };
+  }
+  const appDir = LABEL_APP_MAP[label];
+  if (appDir !== void 0) {
+    return { appDir, devCommand: null };
+  }
+  return { skip: "no-match" };
+}
+function probePort(port) {
+  return new Promise((resolve8) => {
+    const socket = new net.Socket();
+    let settled = false;
+    const settle = (result) => {
+      if (!settled) {
+        settled = true;
+        socket.destroy();
+        resolve8(result);
+      }
+    };
+    socket.setTimeout(500);
+    socket.on("connect", () => settle(true));
+    socket.on("error", () => settle(false));
+    socket.on("timeout", () => settle(false));
+    socket.connect({ port, host: "127.0.0.1" });
+  });
+}
+async function runCmuxServe(args) {
+  try {
+    if (!insideCmux()) {
+      process.exit(0);
+    }
+    let toplevel = "";
+    try {
+      toplevel = execSync10("git rev-parse --show-toplevel", {
+        encoding: "utf8"
+      }).trim();
+    } catch {
+      toplevel = process.cwd();
+    }
+    const cfg = readCmuxConfig(toplevel);
+    if (cfg.auto_dev_server === false) {
+      process.exit(0);
+    }
+    let filesArg;
+    let appArg;
+    for (let i = 0; i < args.length; i++) {
+      const flag = args[i];
+      if (flag === "--files" && i + 1 < args.length) {
+        filesArg = args[++i];
+      } else if (flag === "--app" && i + 1 < args.length) {
+        appArg = args[++i];
+      }
+    }
+    const changedFiles = filesArg !== void 0 ? filesArg.split(",").map((f) => f.trim()).filter(Boolean) : [];
+    let serverConfig = null;
+    try {
+      const raw = readFileSync7(
+        join23(toplevel, ".codebyplan", "server.json"),
+        "utf-8"
+      );
+      serverConfig = JSON.parse(raw);
+    } catch {
+      process.exit(0);
+    }
+    const allocations = serverConfig?.port_allocations ?? [];
+    if (allocations.length === 0) {
+      process.exit(0);
+    }
+    const bin = resolveCmuxBin();
+    for (const allocation of allocations) {
+      try {
+        const resolved = resolveAppDir(allocation, toplevel);
+        if ("skip" in resolved) {
+          if (resolved.skip === "no-match") {
+            process.stdout.write(
+              `cmux-serve: no app mapping for allocation "${allocation.label ?? ""}" \u2014 skipped
+`
+            );
+          }
+          continue;
+        }
+        const { appDir, devCommand } = resolved;
+        const appDirWithSlash = appDir + "/";
+        const intersects = appArg !== void 0 && (appArg === appDir || appArg.startsWith(appDirWithSlash)) || changedFiles.some(
+          (f) => f === appDir || f.startsWith(appDirWithSlash)
+        );
+        if (!intersects) {
+          continue;
+        }
+        const port = allocation.port;
+        const listening = await probePort(port);
+        if (!listening) {
+          let shellCommand = null;
+          if (devCommand !== null) {
+            shellCommand = `cd "${join23(toplevel, appDir)}" && ${devCommand}`;
+          } else {
+            let hasDev = false;
+            try {
+              const pkgRaw = readFileSync7(
+                join23(toplevel, appDir, "package.json"),
+                "utf-8"
+              );
+              const pkg = JSON.parse(pkgRaw);
+              hasDev = typeof pkg.scripts?.dev === "string";
+            } catch {
+            }
+            if (!hasDev) {
+              process.stdout.write(
+                `cmux-serve: no "dev" script in ${appDir}/package.json \u2014 skipped
+`
+              );
+              continue;
+            }
+            shellCommand = `cd "${join23(toplevel, appDir)}" && pnpm run dev`;
+          }
+          let splitSurfaceRef = null;
+          try {
+            const splitOut = execFileSync4(
+              bin,
+              ["new-split", "down", "--json"],
+              {
+                encoding: "utf8"
+              }
+            );
+            const parsed = JSON.parse(splitOut);
+            if (typeof parsed.surface_ref === "string" && parsed.surface_ref) {
+              splitSurfaceRef = parsed.surface_ref;
+            }
+          } catch {
+          }
+          if (splitSurfaceRef !== null) {
+            try {
+              execFileSync4(bin, [
+                "send",
+                "--surface",
+                splitSurfaceRef,
+                `${shellCommand}
+`
+              ]);
+            } catch {
+            }
+          } else {
+            process.stdout.write(
+              `cmux-serve: could not resolve new split surface for ${appDir} \u2014 dev server not auto-started (open it manually)
+`
+            );
+          }
+        }
+        try {
+          execFileSync4(bin, [
+            "new-pane",
+            "--type",
+            "browser",
+            "--url",
+            `http://localhost:${port}`
+          ]);
+        } catch {
+        }
+      } catch {
+      }
+    }
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.exit(0);
+  }
+}
+var LABEL_APP_MAP;
+var init_cmux_serve = __esm({
+  "src/cli/cmux-serve.ts"() {
+    "use strict";
+    init_process_exit_signal();
+    init_cmux();
+    LABEL_APP_MAP = {
+      "Backend Dev": "apps/backend",
+      "MCP Dev": "apps/mcp",
+      "Docs Ingest": "apps/docs-ingest"
+    };
   }
 });
 
 // src/lib/migrate-local-config.ts
-import { mkdir as mkdir6, readFile as readFile15, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join21 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile16, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
+import { join as join24 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join21(projectPath, ".codebyplan.json");
+  return join24(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join21(projectPath, ".codebyplan.local.json");
+  return join24(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join21(projectPath, ".codebyplan");
+  return join24(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join21(projectPath, ".codebyplan", "repo.json");
+  return join24(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -6491,7 +7125,7 @@ async function runLocalMigration(projectPath) {
   }
   let legacyRaw;
   try {
-    legacyRaw = await readFile15(legacySharedPath(projectPath), "utf-8");
+    legacyRaw = await readFile16(legacySharedPath(projectPath), "utf-8");
   } catch {
     return {
       migrated: true,
@@ -6518,7 +7152,7 @@ async function runLocalMigration(projectPath) {
   let deviceId;
   let deviceWrittenByHelper = false;
   try {
-    const localRaw = await readFile15(legacyLocalPath(projectPath), "utf-8");
+    const localRaw = await readFile16(legacyLocalPath(projectPath), "utf-8");
     const localParsed = JSON.parse(localRaw);
     if (typeof localParsed.device_id === "string") {
       deviceId = localParsed.device_id;
@@ -6546,7 +7180,7 @@ async function runLocalMigration(projectPath) {
   if ("organization_id" in cfg) repoJson.organization_id = cfg.organization_id;
   if ("project_id" in cfg) repoJson.project_id = cfg.project_id;
   await writeFile12(
-    join21(projectPath, ".codebyplan", "repo.json"),
+    join24(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6559,7 +7193,7 @@ async function runLocalMigration(projectPath) {
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
   await writeFile12(
-    join21(projectPath, ".codebyplan", "server.json"),
+    join24(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6568,7 +7202,7 @@ async function runLocalMigration(projectPath) {
   if ("git_branch" in cfg) gitJson.git_branch = cfg.git_branch;
   if ("branch_config" in cfg) gitJson.branch_config = cfg.branch_config;
   await writeFile12(
-    join21(projectPath, ".codebyplan", "git.json"),
+    join24(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6576,35 +7210,35 @@ async function runLocalMigration(projectPath) {
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
   await writeFile12(
-    join21(projectPath, ".codebyplan", "shipment.json"),
+    join24(projectPath, ".codebyplan", "shipment.json"),
     JSON.stringify(shipmentJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/shipment.json");
   const vendorJson = {};
   await writeFile12(
-    join21(projectPath, ".codebyplan", "vendor.json"),
+    join24(projectPath, ".codebyplan", "vendor.json"),
     JSON.stringify(vendorJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/vendor.json");
   const e2eJson = {};
   await writeFile12(
-    join21(projectPath, ".codebyplan", "e2e.json"),
+    join24(projectPath, ".codebyplan", "e2e.json"),
     JSON.stringify(e2eJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/e2e.json");
   const eslintJson = {};
   await writeFile12(
-    join21(projectPath, ".codebyplan", "eslint.json"),
+    join24(projectPath, ".codebyplan", "eslint.json"),
     JSON.stringify(eslintJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/eslint.json");
   if (!deviceWrittenByHelper) {
     await writeFile12(
-      join21(projectPath, ".codebyplan", "device.local.json"),
+      join24(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -6616,9 +7250,9 @@ async function runLocalMigration(projectPath) {
       "Migration write incomplete: .codebyplan/repo.json was not persisted. Re-run migration to retry from a clean state."
     );
   }
-  const gitignorePath = join21(projectPath, ".gitignore");
+  const gitignorePath = join24(projectPath, ".gitignore");
   try {
-    const gitignoreContent = await readFile15(gitignorePath, "utf-8");
+    const gitignoreContent = await readFile16(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
     const newLine = ".codebyplan/device.local.json";
     const hasLegacy = gitignoreContent.split("\n").some((l) => l.trimEnd() === legacyLine);
@@ -6669,7 +7303,7 @@ var init_migrate_local_config = __esm({
 // src/cli/config.ts
 var config_exports = {};
 __export(config_exports, {
-  readE2eConfig: () => readE2eConfig,
+  readE2eConfig: () => readE2eConfig2,
   readGitConfig: () => readGitConfig,
   readRepoConfig: () => readRepoConfig,
   readServerConfig: () => readServerConfig,
@@ -6677,8 +7311,8 @@ __export(config_exports, {
   readVendorConfig: () => readVendorConfig,
   runConfig: () => runConfig
 });
-import { mkdir as mkdir7, readFile as readFile16, writeFile as writeFile13 } from "node:fs/promises";
-import { join as join22 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile17, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join25 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -6711,14 +7345,14 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join22(projectPath, ".codebyplan");
+  const codebyplanDir = join25(projectPath, ".codebyplan");
   let resolvedWorktreeId;
   try {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync8 } = await import("node:child_process");
-      branch = execSync8("git symbolic-ref --short HEAD", {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -6838,6 +7472,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   const vendorPayload = {};
   const e2ePayload = {};
   const eslintPayload = {};
+  const cmuxPayload = {};
   if (dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
@@ -6850,15 +7485,16 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     { name: "shipment.json", payload: shipmentPayload },
     { name: "vendor.json", payload: vendorPayload },
     { name: "e2e.json", payload: e2ePayload, createOnly: true },
-    { name: "eslint.json", payload: eslintPayload, createOnly: true }
+    { name: "eslint.json", payload: eslintPayload, createOnly: true },
+    { name: "cmux.json", payload: cmuxPayload, createOnly: true }
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
-    const filePath = join22(codebyplanDir, name);
+    const filePath = join25(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
-      currentJson = await readFile16(filePath, "utf-8");
+      currentJson = await readFile17(filePath, "utf-8");
     } catch {
     }
     if (createOnly && currentJson !== "") continue;
@@ -6873,8 +7509,8 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 }
 async function readRepoConfig(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "repo.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6884,8 +7520,8 @@ async function readRepoConfig(projectPath) {
 }
 async function readServerConfig(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "server.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6895,8 +7531,8 @@ async function readServerConfig(projectPath) {
 }
 async function readGitConfig(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "git.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6906,8 +7542,8 @@ async function readGitConfig(projectPath) {
 }
 async function readShipmentConfig(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "shipment.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6917,8 +7553,8 @@ async function readShipmentConfig(projectPath) {
 }
 async function readVendorConfig(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "vendor.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6926,10 +7562,10 @@ async function readVendorConfig(projectPath) {
     return null;
   }
 }
-async function readE2eConfig(projectPath) {
+async function readE2eConfig2(projectPath) {
   try {
-    const raw = await readFile16(
-      join22(projectPath, ".codebyplan", "e2e.json"),
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "e2e.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6985,14 +7621,14 @@ var init_server_detect = __esm({
 });
 
 // src/lib/port-verify.ts
-import { readFile as readFile17 } from "node:fs/promises";
+import { readFile as readFile18 } from "node:fs/promises";
 async function verifyPorts(projectPath, portAllocations) {
   const mismatches = [];
   const allocatedPorts = new Set(portAllocations.map((a) => a.port));
   const packageJsonPaths = await findPackageJsonFiles(projectPath, projectPath);
   for (const pkgPath of packageJsonPaths) {
     try {
-      const raw = await readFile17(pkgPath, "utf-8");
+      const raw = await readFile18(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       const scriptPort = detectPortFromScripts(pkg);
       if (scriptPort !== null && !allocatedPorts.has(scriptPort)) {
@@ -7055,7 +7691,7 @@ async function findUnallocatedApps(projectPath, portAllocations) {
     }
     let pkg;
     try {
-      const raw = await readFile17(`${app.absPath}/package.json`, "utf-8");
+      const raw = await readFile18(`${app.absPath}/package.json`, "utf-8");
       pkg = JSON.parse(raw);
     } catch {
       continue;
@@ -7263,10 +7899,10 @@ async function runTechStack() {
         );
       }
       try {
-        const { execSync: execSync8 } = await import("node:child_process");
+        const { execSync: execSync11 } = await import("node:child_process");
         let branch = "main";
         try {
-          branch = execSync8("git symbolic-ref --short HEAD", {
+          branch = execSync11("git symbolic-ref --short HEAD", {
             cwd: projectPath,
             encoding: "utf-8"
           }).trim();
@@ -7429,11 +8065,11 @@ async function ask(q, opts) {
   try {
     while (true) {
       const choices = q.choices.map((c) => `[${c.key}] ${c.label}`).join("  ");
-      const answer = await new Promise((resolve7) => {
+      const answer = await new Promise((resolve8) => {
         rl.question(`${q.message}
   ${choices}
 > `, (input) => {
-          resolve7(input.trim().toLowerCase());
+          resolve8(input.trim().toLowerCase());
         });
       });
       const match = q.choices.find(
@@ -8065,13 +8701,13 @@ var init_uninstall = __esm({
 
 // src/index.ts
 init_version();
-import { readFileSync as readFileSync8 } from "node:fs";
-import { resolve as resolve6 } from "node:path";
+import { readFileSync as readFileSync10 } from "node:fs";
+import { resolve as resolve7 } from "node:path";
 void (async () => {
   if (!process.env.CODEBYPLAN_API_KEY) {
     try {
-      const envPath = resolve6(process.cwd(), ".env.local");
-      const content = readFileSync8(envPath, "utf-8");
+      const envPath = resolve7(process.cwd(), ".env.local");
+      const content = readFileSync10(envPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#")) continue;
@@ -8203,11 +8839,29 @@ void (async () => {
     await runVersionStatus2();
     process.exit(0);
   }
+  if (arg === "upload-e2e-images") {
+    const { runUploadE2eImagesCommand: runUploadE2eImagesCommand2 } = await Promise.resolve().then(() => (init_upload_e2e_images(), upload_e2e_images_exports));
+    const rest = process.argv.slice(3);
+    await runUploadE2eImagesCommand2(rest);
+    process.exit(0);
+  }
   if (arg === "cmux-sync") {
     const { runCmuxSync: runCmuxSync2 } = await Promise.resolve().then(() => (init_cmux_sync(), cmux_sync_exports));
     await runCmuxSync2();
     process.exit(0);
   }
+  if (arg === "cmux-status") {
+    const { runCmuxStatus: runCmuxStatus2 } = await Promise.resolve().then(() => (init_cmux_status(), cmux_status_exports));
+    const rest = process.argv.slice(3);
+    await runCmuxStatus2(rest);
+    process.exit(0);
+  }
+  if (arg === "cmux-serve") {
+    const { runCmuxServe: runCmuxServe2 } = await Promise.resolve().then(() => (init_cmux_serve(), cmux_serve_exports));
+    const rest = process.argv.slice(3);
+    await runCmuxServe2(rest);
+    process.exit(0);
+  }
   if (arg === "config") {
     const { runConfig: runConfig2 } = await Promise.resolve().then(() => (init_config(), config_exports));
     await runConfig2();
@@ -8304,6 +8958,7 @@ void (async () => {
     codebyplan round sync-approvals  Sync git diff and approvals with round/task state
     codebyplan bump                  Detect changed packages and patch-bump versions
     codebyplan ship                  Ship current feat branch to production via PR
+    codebyplan upload-e2e-images     Upload new/changed committed e2e PNGs for a checkpoint
     codebyplan scaffold-publish-workflow   Write the publish-on-main GitHub workflow into ./.github/workflows/
     codebyplan branch migrate        Rewrite branch_config from 3-branch to 2-tier model
     codebyplan claude                Claude asset management (install/update/uninstall)
@@ -8311,6 +8966,8 @@ void (async () => {
     codebyplan resolve-worktree      Resolve active worktree UUID from device+path+branch tuple
     codebyplan version-status        Report installed vs latest version + update guard (JSON)
     codebyplan cmux-sync             Sync cmux workspace title/description to current git branch and repo folder
+    codebyplan cmux-status           Push checkpoint/task/QA + progress to the cmux workspace sidebar
+    codebyplan cmux-serve            Auto-start dev server + browser pane for the round's app files (cmux)
     codebyplan help                  Show this help message
     codebyplan --version             Print version