codebyplan 1.13.15 → 1.13.17

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.15";
+    VERSION = "1.13.17";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -663,10 +663,8 @@ function noAuthHint() {
 Or, for the legacy 30-day shim:
   export CODEBYPLAN_API_KEY=<key>   # from https://codebyplan.com/settings/api-keys/`;
 }
-function validateApiKey() {
-  if (!legacyApiKey()) {
-    throw new Error(noAuthHint());
-  }
+async function validateAuth() {
+  await getAuthHeaders();
 }
 async function getAuthHeaders() {
   try {
@@ -1987,6 +1985,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 +2007,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 +2084,8 @@ async function runSetup() {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync9 } = await import("node:child_process");
-      branch = execSync9("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 +3723,9 @@ async function eslintInit(repoId, projectPath) {
   Install ${missingPkgs.length} missing packages? [Y/n] `
     );
     if (confirmed) {
-      const { execSync: execSync9 } = await import("node:child_process");
+      const { execSync: execSync11 } = await import("node:child_process");
       try {
-        execSync9(installCmd, { cwd: projectPath, stdio: "inherit" });
+        execSync11(installCmd, { cwd: projectPath, stdio: "inherit" });
         console.log("  Packages installed.\n");
       } catch (err) {
         console.error(
@@ -3792,7 +3795,7 @@ async function eslintInit(repoId, projectPath) {
 async function runEslint() {
   const subcommand = process.argv[3];
   const flags = parseFlags(4);
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   switch (subcommand) {
@@ -6623,6 +6626,42 @@ var init_upload_e2e_images = __esm({
   }
 });
 
+// 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, {
@@ -6632,10 +6671,10 @@ import { execSync as execSync8, execFileSync as execFileSync2 } from "node:child
 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 = execSync8("git rev-parse --abbrev-ref HEAD", {
@@ -6644,8 +6683,9 @@ async function runCmuxSync() {
     } catch {
     }
     let folder = "";
+    let toplevel = "";
     try {
-      const toplevel = execSync8("git rev-parse --show-toplevel", {
+      toplevel = execSync8("git rev-parse --show-toplevel", {
         encoding: "utf8"
       }).trim();
       folder = basename2(toplevel);
@@ -6675,6 +6715,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;
@@ -6685,23 +6745,434 @@ 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/worktree-port-resolver.ts
+async function resolveWorktreePortAllocations(repoId, projectPath) {
+  let resolvedWorktreeId;
+  try {
+    const deviceId = await getOrCreateDeviceId(projectPath);
+    let branch = "main";
+    try {
+      const { execSync: execSync11 } = await import("node:child_process");
+      branch = execSync11("git symbolic-ref --short HEAD", {
+        cwd: projectPath,
+        encoding: "utf-8"
+      }).trim();
+    } catch {
+    }
+    const tupleId = await resolveWorktreeId({
+      repoId,
+      repoPath: projectPath,
+      branch,
+      deviceId
+    });
+    if (tupleId) {
+      resolvedWorktreeId = tupleId;
+    } else {
+      resolvedWorktreeId = await resolveAndCacheWorktreeId(repoId, projectPath) ?? void 0;
+    }
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    console.warn(
+      `  Warning: failed to cache worktree_id (self-heal skipped): ${msg}`
+    );
+  }
+  let portAllocations = [];
+  try {
+    const portsRes = await apiGet(
+      `/port-allocations`,
+      resolvedWorktreeId ? {
+        repo_id: repoId,
+        worktree_id: resolvedWorktreeId,
+        limit: PORT_ALLOCATIONS_UNFILTERED_LIMIT
+      } : {
+        repo_id: repoId,
+        worktree_id: "null",
+        limit: PORT_ALLOCATIONS_UNFILTERED_LIMIT
+      }
+    );
+    const allAllocations = portsRes.data ?? [];
+    const filtered = resolvedWorktreeId ? allAllocations.filter((a) => a.worktree_id === resolvedWorktreeId) : allAllocations.filter((a) => !a.worktree_id);
+    portAllocations = filtered.map((a) => {
+      const clean = {};
+      for (const key of ALLOWED_FIELDS) {
+        if (key in a) clean[key] = a[key];
+      }
+      return clean;
+    });
+  } catch (err) {
+    console.warn(
+      `  Warning: failed to fetch port allocations: ${err instanceof Error ? err.message : String(err)}`
+    );
+  }
+  const matchingAlloc = portAllocations[0];
+  return { resolvedWorktreeId, portAllocations, matchingAlloc };
+}
+var PORT_ALLOCATIONS_UNFILTERED_LIMIT, ALLOWED_FIELDS;
+var init_worktree_port_resolver = __esm({
+  "src/lib/worktree-port-resolver.ts"() {
+    "use strict";
+    init_api();
+    init_resolve_worktree();
+    init_local_config();
+    PORT_ALLOCATIONS_UNFILTERED_LIMIT = "500";
+    ALLOWED_FIELDS = [
+      "id",
+      "repo_id",
+      "port",
+      "label",
+      "server_type",
+      "auto_start",
+      "command",
+      "working_dir",
+      "env_vars",
+      "external_refs",
+      "worktree_id",
+      "created_at",
+      "updated_at"
+    ];
   }
 });
 
 // src/lib/migrate-local-config.ts
 import { mkdir as mkdir6, readFile as readFile16, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join22 } from "node:path";
+import { join as join24 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join22(projectPath, ".codebyplan.json");
+  return join24(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join22(projectPath, ".codebyplan.local.json");
+  return join24(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join22(projectPath, ".codebyplan");
+  return join24(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join22(projectPath, ".codebyplan", "repo.json");
+  return join24(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -6795,7 +7266,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(
-    join22(projectPath, ".codebyplan", "repo.json"),
+    join24(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6808,7 +7279,7 @@ async function runLocalMigration(projectPath) {
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
   await writeFile12(
-    join22(projectPath, ".codebyplan", "server.json"),
+    join24(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6817,7 +7288,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(
-    join22(projectPath, ".codebyplan", "git.json"),
+    join24(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
@@ -6825,35 +7296,35 @@ async function runLocalMigration(projectPath) {
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
   await writeFile12(
-    join22(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(
-    join22(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(
-    join22(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(
-    join22(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(
-      join22(projectPath, ".codebyplan", "device.local.json"),
+      join24(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -6865,7 +7336,7 @@ async function runLocalMigration(projectPath) {
       "Migration write incomplete: .codebyplan/repo.json was not persisted. Re-run migration to retry from a clean state."
     );
   }
-  const gitignorePath = join22(projectPath, ".gitignore");
+  const gitignorePath = join24(projectPath, ".gitignore");
   try {
     const gitignoreContent = await readFile16(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
@@ -6922,16 +7393,17 @@ __export(config_exports, {
   readGitConfig: () => readGitConfig,
   readRepoConfig: () => readRepoConfig,
   readServerConfig: () => readServerConfig,
+  readServerLocalConfig: () => readServerLocalConfig,
   readShipmentConfig: () => readShipmentConfig,
   readVendorConfig: () => readVendorConfig,
   runConfig: () => runConfig
 });
 import { mkdir as mkdir7, readFile as readFile17, writeFile as writeFile13 } from "node:fs/promises";
-import { join as join23 } from "node:path";
+import { join as join25 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   console.log(`
@@ -6960,36 +7432,13 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join23(projectPath, ".codebyplan");
-  let resolvedWorktreeId;
-  try {
-    const deviceId = await getOrCreateDeviceId(projectPath);
-    let branch = "main";
-    try {
-      const { execSync: execSync9 } = await import("node:child_process");
-      branch = execSync9("git symbolic-ref --short HEAD", {
-        cwd: projectPath,
-        encoding: "utf-8"
-      }).trim();
-    } catch {
-    }
-    const tupleId = await resolveWorktreeId({
-      repoId,
-      repoPath: projectPath,
-      branch,
-      deviceId
-    });
-    if (tupleId) {
-      resolvedWorktreeId = tupleId;
-    } else {
-      resolvedWorktreeId = await resolveAndCacheWorktreeId(repoId, projectPath) ?? void 0;
-    }
-  } catch (err) {
-    const msg = err instanceof Error ? err.message : String(err);
-    console.warn(
-      `  Warning: failed to cache worktree_id (self-heal skipped): ${msg}`
-    );
-  }
+  const codebyplanDir = join25(projectPath, ".codebyplan");
+  const {
+    resolvedWorktreeId,
+    portAllocations,
+    matchingAlloc: matchingAllocRaw
+  } = await resolveWorktreePortAllocations(repoId, projectPath);
+  const matchingAlloc = matchingAllocRaw;
   let repoRes;
   try {
     repoRes = await apiGet(`/repos/${repoId}`);
@@ -7012,42 +7461,6 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     process.exit(1);
   }
   const repo = repoRes.data;
-  let portAllocations = [];
-  try {
-    const portsRes = await apiGet(
-      `/port-allocations`,
-      { repo_id: repoId }
-    );
-    const allAllocations = portsRes.data ?? [];
-    const filtered = resolvedWorktreeId ? allAllocations.filter((a) => a.worktree_id === resolvedWorktreeId) : allAllocations.filter((a) => !a.worktree_id);
-    const ALLOWED_FIELDS = [
-      "id",
-      "repo_id",
-      "port",
-      "label",
-      "server_type",
-      "auto_start",
-      "command",
-      "working_dir",
-      "env_vars",
-      "external_refs",
-      "worktree_id",
-      "created_at",
-      "updated_at"
-    ];
-    portAllocations = filtered.map((a) => {
-      const clean = {};
-      for (const key of ALLOWED_FIELDS) {
-        if (key in a) clean[key] = a[key];
-      }
-      return clean;
-    });
-  } catch (err) {
-    console.warn(
-      `  Warning: failed to fetch port allocations: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-  const matchingAlloc = portAllocations[0];
   const defaultBranchConfig = {
     protected: ["main"],
     integration: null,
@@ -7087,6 +7500,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;
@@ -7099,11 +7513,12 @@ 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 = join23(codebyplanDir, name);
+    const filePath = join25(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
@@ -7123,7 +7538,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 async function readRepoConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "repo.json"),
+      join25(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7134,7 +7549,7 @@ async function readRepoConfig(projectPath) {
 async function readServerConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "server.json"),
+      join25(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7145,7 +7560,7 @@ async function readServerConfig(projectPath) {
 async function readGitConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "git.json"),
+      join25(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7156,7 +7571,7 @@ async function readGitConfig(projectPath) {
 async function readShipmentConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "shipment.json"),
+      join25(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7167,7 +7582,7 @@ async function readShipmentConfig(projectPath) {
 async function readVendorConfig(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "vendor.json"),
+      join25(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7178,7 +7593,18 @@ async function readVendorConfig(projectPath) {
 async function readE2eConfig2(projectPath) {
   try {
     const raw = await readFile17(
-      join23(projectPath, ".codebyplan", "e2e.json"),
+      join25(projectPath, ".codebyplan", "e2e.json"),
+      "utf-8"
+    );
+    return JSON.parse(raw);
+  } catch {
+    return null;
+  }
+}
+async function readServerLocalConfig(projectPath) {
+  try {
+    const raw = await readFile17(
+      join25(projectPath, ".codebyplan", "server.local.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -7192,8 +7618,7 @@ var init_config = __esm({
     "use strict";
     init_flags();
     init_api();
-    init_resolve_worktree();
-    init_local_config();
+    init_worktree_port_resolver();
     init_migrate_local_config();
     legacyBranchConfigWarned = false;
   }
@@ -7351,22 +7776,48 @@ var init_port_verify = __esm({
 // src/cli/ports.ts
 var ports_exports = {};
 __export(ports_exports, {
+  parseEnvFile: () => parseEnvFile,
   runPorts: () => runPorts
 });
+import { mkdir as mkdir8, readFile as readFile19, writeFile as writeFile14 } from "node:fs/promises";
+import { join as join26 } from "node:path";
 async function runPorts() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
   const fix = hasFlag("fix", 3);
-  validateApiKey();
-  const config = await resolveConfig(flags);
-  const { repoId, projectPath } = config;
+  const writeLocal = hasFlag("write-local", 3);
+  const provisionE2e = hasFlag("provision-e2e", 3);
+  if (flags["path"]?.startsWith("--")) {
+    console.warn(
+      `  Warning: --path value "${flags["path"]}" looks like a flag. Pass --path <dir> BEFORE boolean flags (e.g. --path . --provision-e2e).`
+    );
+  }
+  const provisionE2eOnly = provisionE2e && !writeLocal;
+  let repoId = "";
+  let projectPath;
+  if (provisionE2eOnly) {
+    projectPath = flags["path"] ?? process.cwd();
+  } else {
+    await validateAuth();
+    const config = await resolveConfig(flags);
+    repoId = config.repoId;
+    projectPath = config.projectPath;
+  }
   console.log(`
   CodeByPlan Ports`);
-  console.log(`  Repo: ${repoId}`);
+  if (repoId) console.log(`  Repo: ${repoId}`);
   console.log(`  Path: ${projectPath}`);
   if (dryRun) console.log(`  Mode: dry-run`);
   if (fix) console.log(`  Mode: fix`);
+  if (writeLocal) console.log(`  Mode: write-local`);
+  if (provisionE2e) console.log(`  Mode: provision-e2e`);
   console.log();
+  if (writeLocal || provisionE2e) {
+    if (writeLocal) await writeServerLocalConfig(repoId, projectPath, dryRun);
+    if (provisionE2e) await provisionE2eEnv(projectPath, dryRun);
+    console.log("\n  Ports complete.\n");
+    return;
+  }
   try {
     const portsRes = await apiGet(
       `/port-allocations`,
@@ -7435,12 +7886,135 @@ async function runPorts() {
   }
   console.log("\n  Ports complete.\n");
 }
+async function writeServerLocalConfig(repoId, projectPath, dryRun) {
+  const { resolvedWorktreeId, portAllocations, matchingAlloc } = await resolveWorktreePortAllocations(repoId, projectPath);
+  if (portAllocations.length === 0) {
+    console.warn(
+      "  Skipped .codebyplan/server.local.json \u2014 no worktree port allocations resolved (API failure or none assigned)."
+    );
+    return;
+  }
+  const payload = {
+    server_port: matchingAlloc?.port ?? null,
+    server_type: matchingAlloc?.server_type ?? null,
+    // No cast needed: resolveWorktreePortAllocations returns Partial<PortAllocation>[]
+    // and ServerLocalConfig.port_allocations is typed the same — honest end-to-end.
+    port_allocations: portAllocations
+  };
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "server.local.json");
+  const newJson = JSON.stringify(payload, null, 2) + "\n";
+  let currentJson = "";
+  try {
+    currentJson = await readFile19(filePath, "utf-8");
+  } catch {
+  }
+  if (currentJson === newJson) {
+    console.log("  server.local.json up to date.");
+    return;
+  }
+  if (dryRun) {
+    console.log("  Would update .codebyplan/server.local.json (dry-run).");
+    return;
+  }
+  await mkdir8(codebyplanDir, { recursive: true });
+  await writeFile14(filePath, newJson, "utf-8");
+  console.log(
+    `  Updated .codebyplan/server.local.json (worktree ${resolvedWorktreeId ?? "\u2014"}, ${portAllocations.length} allocation${portAllocations.length === 1 ? "" : "s"}).`
+  );
+}
+async function provisionE2eEnv(projectPath, dryRun) {
+  const relSource = join26("apps", "web", ".env.local");
+  const sourcePath = join26(projectPath, relSource);
+  let sourceRaw;
+  try {
+    sourceRaw = await readFile19(sourcePath, "utf-8");
+  } catch {
+    console.warn(
+      `  Skipped .codebyplan/e2e.env \u2014 source ${relSource} not found.`
+    );
+    return;
+  }
+  const sourceVars = parseEnvFile(sourceRaw);
+  const lines = [];
+  const missing = [];
+  for (const key of E2E_ENV_VARS) {
+    const val = sourceVars[key];
+    if (val === void 0) {
+      missing.push(key);
+      continue;
+    }
+    lines.push(`${key}=${val}`);
+  }
+  if (missing.length > 0) {
+    console.warn(
+      `  Warning: ${missing.length} E2E var(s) missing from ${relSource}: ${missing.join(", ")}`
+    );
+  }
+  if (lines.length === 0) {
+    console.warn(
+      "  Skipped .codebyplan/e2e.env \u2014 none of the expected E2E vars were found."
+    );
+    return;
+  }
+  const codebyplanDir = join26(projectPath, ".codebyplan");
+  const filePath = join26(codebyplanDir, "e2e.env");
+  const newContent = lines.join("\n") + "\n";
+  let currentContent = "";
+  try {
+    currentContent = await readFile19(filePath, "utf-8");
+  } catch {
+  }
+  if (currentContent === newContent) {
+    console.log("  e2e.env up to date.");
+    return;
+  }
+  if (dryRun) {
+    console.log("  Would provision .codebyplan/e2e.env (dry-run).");
+    return;
+  }
+  await mkdir8(codebyplanDir, { recursive: true });
+  await writeFile14(filePath, newContent, "utf-8");
+  console.log(
+    `  Provisioned .codebyplan/e2e.env (${lines.length} var${lines.length === 1 ? "" : "s"}).`
+  );
+}
+function parseEnvFile(raw) {
+  const out = {};
+  for (const line of raw.split("\n")) {
+    const trimmed = line.trim();
+    if (trimmed === "" || trimmed.startsWith("#")) continue;
+    const eq = trimmed.indexOf("=");
+    if (eq === -1) continue;
+    const key = trimmed.slice(0, eq).trim();
+    if (key === "") continue;
+    let value = trimmed.slice(eq + 1).trim();
+    const quoted = value.length >= 2 && (value.startsWith('"') && value.endsWith('"') || value.startsWith("'") && value.endsWith("'"));
+    if (quoted) {
+      value = value.slice(1, -1);
+    } else {
+      const commentIdx = value.indexOf(" #");
+      if (commentIdx !== -1) value = value.slice(0, commentIdx).trimEnd();
+    }
+    out[key] = value;
+  }
+  return out;
+}
+var E2E_ENV_VARS;
 var init_ports = __esm({
   "src/cli/ports.ts"() {
     "use strict";
     init_flags();
     init_api();
     init_port_verify();
+    init_worktree_port_resolver();
+    E2E_ENV_VARS = [
+      "E2E_USER_EMAIL",
+      "E2E_USER_PASSWORD",
+      "NEXT_PUBLIC_SUPABASE_URL",
+      "NEXT_PUBLIC_SUPABASE_PUBLISHABLE_KEY",
+      "SUPABASE_SECRET_KEY"
+    ];
   }
 });
 
@@ -7458,7 +8032,7 @@ async function runTechStack() {
     await runFullTechStack(dryRun);
     return;
   }
-  validateApiKey();
+  await validateAuth();
   const config = await resolveConfig(flags);
   const { repoId, projectPath } = config;
   console.log(`
@@ -7512,10 +8086,10 @@ async function runTechStack() {
         );
       }
       try {
-        const { execSync: execSync9 } = await import("node:child_process");
+        const { execSync: execSync11 } = await import("node:child_process");
         let branch = "main";
         try {
-          branch = execSync9("git symbolic-ref --short HEAD", {
+          branch = execSync11("git symbolic-ref --short HEAD", {
             cwd: projectPath,
             encoding: "utf-8"
           }).trim();
@@ -7593,7 +8167,7 @@ async function syncTechStackForPath(repoId, projectPath, dryRun) {
   }
 }
 async function runFullTechStack(dryRun) {
-  validateApiKey();
+  await validateAuth();
   const localConfig = await readLocalConfig(process.cwd());
   if (!localConfig?.device_id) {
     console.error(
@@ -8314,13 +8888,13 @@ var init_uninstall = __esm({
 
 // src/index.ts
 init_version();
-import { readFileSync as readFileSync8 } from "node:fs";
+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 = resolve7(process.cwd(), ".env.local");
-      const content = readFileSync8(envPath, "utf-8");
+      const content = readFileSync10(envPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#")) continue;
@@ -8463,6 +9037,18 @@ void (async () => {
     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();
@@ -8567,6 +9153,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
 
@@ -8580,6 +9168,11 @@ void (async () => {
     --repo-id <uuid>        Repository ID (or set via .codebyplan/repo.json)
     --dry-run               Preview changes without writing
     --fix                   Auto-create missing port allocations
+    --write-local           Write this worktree's port allocations to the
+                            gitignored .codebyplan/server.local.json overlay
+                            (never the committed server.json)
+    --provision-e2e         Copy E2E credentials from apps/web/.env.local into
+                            the gitignored .codebyplan/e2e.env (local, no API)
 
   Tech stack options:
     --path <dir>            Project root directory (default: cwd)