codebyplan 1.13.8 → 1.13.10

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.8";
+    VERSION = "1.13.10";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -148,6 +148,7 @@ var init_gitignore_block = __esm({
       ".claude/scheduled_tasks.lock",
       ".codebyplan/device.local.json",
       ".codebyplan/statusline.local.json",
+      ".codebyplan/worktree.local.json",
       ".codebyplan.local.json"
     ];
     GITIGNORE_BLOCK_START = "# >>> codebyplan (managed) >>>";
@@ -1443,8 +1444,8 @@ async function runSetup() {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync7 } = await import("node:child_process");
-      branch = execSync7("git symbolic-ref --short HEAD", {
+      const { execSync: execSync8 } = await import("node:child_process");
+      branch = execSync8("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -3064,9 +3065,9 @@ async function eslintInit(repoId, projectPath) {
   Install ${missingPkgs.length} missing packages? [Y/n] `
     );
     if (confirmed) {
-      const { execSync: execSync7 } = await import("node:child_process");
+      const { execSync: execSync8 } = await import("node:child_process");
       try {
-        execSync7(installCmd, { cwd: projectPath, stdio: "inherit" });
+        execSync8(installCmd, { cwd: projectPath, stdio: "inherit" });
         console.log("  Packages installed.\n");
       } catch (err) {
         console.error(
@@ -3409,6 +3410,81 @@ var init_sync_approvals = __esm({
   }
 });
 
+// src/lib/worktree-cache.ts
+import { mkdir as mkdir5, readFile as readFile11, writeFile as writeFile9 } from "node:fs/promises";
+import { dirname as dirname4, join as join11 } from "node:path";
+function worktreeCachePath(repoRoot) {
+  return join11(repoRoot, ".codebyplan", "worktree.local.json");
+}
+async function readCachedWorktreeId(repoRoot, currentBranch) {
+  const cachePath = worktreeCachePath(repoRoot);
+  let raw;
+  try {
+    raw = await readFile11(cachePath, "utf-8");
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      return null;
+    }
+    console.warn(
+      `worktree-cache: read failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return null;
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    console.warn(
+      "worktree-cache: JSON parse failed (non-fatal): cache entry will be ignored"
+    );
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed) || typeof parsed.worktree_id !== "string" || typeof parsed.branch !== "string" || typeof parsed.device_id !== "string" || typeof parsed.resolved_at !== "string") {
+    return null;
+  }
+  const data = parsed;
+  if (!data.branch || data.branch !== currentBranch) {
+    return null;
+  }
+  return data.worktree_id;
+}
+async function writeWorktreeCache(repoRoot, data) {
+  if (!data.branch) {
+    console.warn(
+      "worktree-cache: skipping write for empty branch (detached HEAD or non-repo)"
+    );
+    return false;
+  }
+  const cachePath = worktreeCachePath(repoRoot);
+  const dirPath = dirname4(cachePath);
+  const payload = {
+    worktree_id: data.worktree_id,
+    branch: data.branch,
+    device_id: data.device_id,
+    resolved_at: (/* @__PURE__ */ new Date()).toISOString()
+  };
+  try {
+    await mkdir5(dirPath, { recursive: true });
+    await writeFile9(
+      cachePath,
+      JSON.stringify(payload, null, 2) + "\n",
+      "utf-8"
+    );
+    return true;
+  } catch (err) {
+    console.warn(
+      `worktree-cache: write failed (non-fatal): ${err instanceof Error ? err.message : String(err)}`
+    );
+    return false;
+  }
+}
+var init_worktree_cache = __esm({
+  "src/lib/worktree-cache.ts"() {
+    "use strict";
+  }
+});
+
 // src/cli/round.ts
 var round_exports = {};
 __export(round_exports, {
@@ -3420,7 +3496,7 @@ __export(round_exports, {
   setRetryDelayMs: () => setRetryDelayMs
 });
 import { access as access3 } from "node:fs/promises";
-import { join as join11 } from "node:path";
+import { join as join12 } from "node:path";
 import { execSync as execSync2 } from "node:child_process";
 function setRetryDelayMs(ms) {
   RETRY_DELAY_MS = ms;
@@ -3480,6 +3556,34 @@ function printRoundHelp() {
     "\n  codebyplan round <subcommand>\n\n  Subcommands:\n    sync-approvals   Sync git diff and approvals with round/task state\n\n  sync-approvals flags:\n    --round-id <uuid>     Round UUID (required)\n    --task-id <uuid>      Task UUID (required)\n    --dry-run             Print merged payload to stdout without writing\n\n"
   );
 }
+async function resolveCallerWorktreeId(repoRoot, currentBranch, repoId, overrideId) {
+  if (overrideId) {
+    return overrideId;
+  }
+  const cached = await readCachedWorktreeId(repoRoot, currentBranch);
+  if (cached) {
+    return cached;
+  }
+  if (!repoId || !currentBranch) {
+    return null;
+  }
+  const deviceId = await getOrCreateDeviceId(repoRoot);
+  const wid = await resolveWorktreeId({
+    repoId,
+    repoPath: repoRoot,
+    branch: currentBranch,
+    deviceId
+  });
+  if (wid) {
+    await writeWorktreeCache(repoRoot, {
+      worktree_id: wid,
+      branch: currentBranch,
+      device_id: deviceId
+    });
+    return wid;
+  }
+  return null;
+}
 function parseFlagsFromArgs(args) {
   const flags = {};
   const booleans = /* @__PURE__ */ new Set();
@@ -3503,6 +3607,7 @@ async function runRoundSyncApprovals(args) {
   const roundId = flags["round-id"];
   const taskId = flags["task-id"];
   const dryRun = booleans.has("dry-run");
+  const overrideWorktreeId = flags["caller-worktree-id"];
   if (!roundId) {
     process.stderr.write(
       "sync-approvals: --round-id is required\nUsage: codebyplan round sync-approvals --round-id <uuid> --task-id <uuid>\n"
@@ -3523,6 +3628,14 @@ async function runRoundSyncApprovals(args) {
       // Walk up to the directory containing .codebyplan/ or .codebyplan.json
       found.path.replace(/\/.codebyplan(\.json|\/repo\.json)$/, "")
     ) : process.cwd();
+    let currentBranch = "";
+    try {
+      currentBranch = execSync2("git symbolic-ref --short HEAD", {
+        cwd: repoRoot,
+        encoding: "utf-8"
+      }).trim();
+    } catch {
+    }
     let rounds;
     try {
       rounds = await fetchRoundsWithRetry(taskId);
@@ -3542,6 +3655,17 @@ async function runRoundSyncApprovals(args) {
       }
       const taskResponse = await apiGet(`/tasks/${taskId}`);
       const currentTask = taskResponse.data;
+      const callerWorktreeId = await resolveCallerWorktreeId(
+        repoRoot,
+        currentBranch,
+        found?.contents.repo_id,
+        overrideWorktreeId
+      );
+      if (!dryRun && !callerWorktreeId) {
+        throw new Error(
+          "could not resolve caller_worktree_id for this worktree.\n  Run: codebyplan resolve-worktree --cache\n  If this worktree is not registered, run: npx codebyplan setup\n  Then re-run /cbp-round-update (sync-approvals)."
+        );
+      }
       let gitStatusOutput = "";
       try {
         gitStatusOutput = execSync2("git status --short --porcelain -z", {
@@ -3553,7 +3677,7 @@ async function runRoundSyncApprovals(args) {
           "sync-approvals: git status failed; proceeding with empty diff\n"
         );
       }
-      const hookPath = join11(
+      const hookPath = join12(
         repoRoot,
         ".claude",
         "hooks",
@@ -3586,12 +3710,14 @@ async function runRoundSyncApprovals(args) {
       } else {
         await mcpCall("update_round", {
           round_id: roundId,
-          files_changed: result.merged_files_changed
+          files_changed: result.merged_files_changed,
+          caller_worktree_id: callerWorktreeId
         });
         await mcpCall("update_task", {
           task_id: taskId,
           files_changed: result.merged_files_changed,
-          app_file_approval_by_user: false
+          app_file_approval_by_user: false,
+          caller_worktree_id: callerWorktreeId
         });
         stdoutPayload = JSON.stringify(
           {
@@ -3634,13 +3760,16 @@ var init_round = __esm({
     init_mcp_client();
     init_flags();
     init_sync_approvals();
+    init_worktree_cache();
+    init_resolve_worktree();
+    init_local_config();
     RETRY_DELAY_MS = 1e3;
   }
 });
 
 // src/lib/migrate-branch-model.ts
-import { readFile as readFile11, writeFile as writeFile9 } from "node:fs/promises";
-import { join as join12 } from "node:path";
+import { readFile as readFile12, writeFile as writeFile10 } from "node:fs/promises";
+import { join as join13 } from "node:path";
 import { execSync as execSync3 } from "node:child_process";
 function assertValidBranchName(branch) {
   if (!/^[a-zA-Z0-9/_.-]+$/.test(branch)) {
@@ -3650,7 +3779,7 @@ function assertValidBranchName(branch) {
   }
 }
 async function readJsonFile(filePath) {
-  const raw = await readFile11(filePath, "utf-8");
+  const raw = await readFile12(filePath, "utf-8");
   const parsed = JSON.parse(raw);
   if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
     throw new Error(`${filePath} does not contain a JSON object`);
@@ -3719,12 +3848,12 @@ async function runBranchMigration(opts) {
   if (found) {
     if (found.path.endsWith("/repo.json")) {
       const dir = found.path.slice(0, found.path.lastIndexOf("/"));
-      configPath = join12(dir, "git.json");
+      configPath = join13(dir, "git.json");
     } else {
       configPath = found.path;
     }
   } else {
-    configPath = join12(cwd, ".codebyplan", "git.json");
+    configPath = join13(cwd, ".codebyplan", "git.json");
   }
   let fileRaw;
   let fileParsed;
@@ -3798,7 +3927,7 @@ async function runBranchMigration(opts) {
     const updatedParsed = { ...fileParsed, branch_config: after };
     const newJson = JSON.stringify(updatedParsed, null, 2) + "\n";
     if (newJson !== fileRaw) {
-      await writeFile9(configPath, newJson, "utf-8");
+      await writeFile10(configPath, newJson, "utf-8");
     }
   }
   return {
@@ -3904,8 +4033,8 @@ var init_branch = __esm({
 });
 
 // src/lib/git-utils.ts
-import { readFile as readFile12 } from "node:fs/promises";
-import { join as join13 } from "node:path";
+import { readFile as readFile13 } from "node:fs/promises";
+import { join as join14 } from "node:path";
 import { spawnSync as spawnSync2 } from "node:child_process";
 async function readBaseBranch(cwd) {
   const found = await findCodebyplanConfig(cwd);
@@ -3913,15 +4042,15 @@ async function readBaseBranch(cwd) {
   if (found) {
     if (found.path.endsWith("/repo.json")) {
       const dir = found.path.slice(0, found.path.lastIndexOf("/"));
-      gitJsonPath = join13(dir, "git.json");
+      gitJsonPath = join14(dir, "git.json");
     } else {
       gitJsonPath = found.path;
     }
   } else {
-    gitJsonPath = join13(cwd, ".codebyplan", "git.json");
+    gitJsonPath = join14(cwd, ".codebyplan", "git.json");
   }
   try {
-    const raw = await readFile12(gitJsonPath, "utf-8");
+    const raw = await readFile13(gitJsonPath, "utf-8");
     const parsed = JSON.parse(raw);
     if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
       return "main";
@@ -3959,8 +4088,8 @@ var init_git_utils = __esm({
 });
 
 // src/lib/bump.ts
-import { readFile as readFile13, writeFile as writeFile10, access as access4, readdir as readdir3 } from "node:fs/promises";
-import { join as join14, relative as relative3, resolve as resolve2 } from "node:path";
+import { readFile as readFile14, writeFile as writeFile11, access as access4, readdir as readdir3 } from "node:fs/promises";
+import { join as join15, relative as relative3, resolve as resolve2 } from "node:path";
 import { spawnSync as spawnSync3 } from "node:child_process";
 function parsePnpmWorkspaceGlobs(raw) {
   const lines = raw.split("\n");
@@ -3990,18 +4119,18 @@ async function expandGlob(cwd, glob) {
   if (parts.length !== 2 || parts[1] !== "*") {
     return [];
   }
-  const parentDir = join14(cwd, parts[0]);
+  const parentDir = join15(cwd, parts[0]);
   let dirs;
   try {
     const entries = await readdir3(parentDir, { withFileTypes: true });
-    dirs = entries.filter((e) => e.isDirectory()).map((e) => join14(parentDir, e.name));
+    dirs = entries.filter((e) => e.isDirectory()).map((e) => join15(parentDir, e.name));
   } catch {
     return [];
   }
   const results = [];
   for (const dir of dirs) {
     try {
-      await access4(join14(dir, "package.json"));
+      await access4(join15(dir, "package.json"));
       results.push(dir);
     } catch {
     }
@@ -4012,7 +4141,7 @@ async function buildPackageMap(cwd) {
   const map = /* @__PURE__ */ new Map();
   let globs = [];
   try {
-    const raw = await readFile13(join14(cwd, "pnpm-workspace.yaml"), "utf-8");
+    const raw = await readFile14(join15(cwd, "pnpm-workspace.yaml"), "utf-8");
     globs = parsePnpmWorkspaceGlobs(raw);
   } catch {
   }
@@ -4020,7 +4149,7 @@ async function buildPackageMap(cwd) {
     const dirs = await expandGlob(cwd, glob);
     for (const dir of dirs) {
       try {
-        const pkgRaw = await readFile13(join14(dir, "package.json"), "utf-8");
+        const pkgRaw = await readFile14(join15(dir, "package.json"), "utf-8");
         const pkg = JSON.parse(pkgRaw);
         const name = pkg.name ?? relative3(cwd, dir);
         map.set(dir, { name, dir });
@@ -4110,7 +4239,7 @@ function injectVersion(raw, nextVersion, filePath) {
 async function prependChangelog(changelogPath, packageName, nextVersion, now, dryRun) {
   let existing;
   try {
-    existing = await readFile13(changelogPath, "utf-8");
+    existing = await readFile14(changelogPath, "utf-8");
   } catch {
     return false;
   }
@@ -4123,7 +4252,7 @@ async function prependChangelog(changelogPath, packageName, nextVersion, now, dr
 `;
   const updated = entry + existing;
   if (!dryRun) {
-    await writeFile10(changelogPath, updated, "utf-8");
+    await writeFile11(changelogPath, updated, "utf-8");
   }
   return true;
 }
@@ -4149,7 +4278,7 @@ async function runBump(opts) {
   const changedFiles = (diffResult.stdout ?? "").trim().split("\n").filter(Boolean).map((f) => resolve2(cwd, f));
   const packageMap = await buildPackageMap(cwd);
   const packageDirs = Array.from(packageMap.keys());
-  const rootPkgPath = join14(cwd, "package.json");
+  const rootPkgPath = join15(cwd, "package.json");
   const changedPackageDirs = /* @__PURE__ */ new Set();
   for (const absFile of changedFiles) {
     const owner = findOwningPackage(absFile, packageDirs);
@@ -4160,19 +4289,19 @@ async function runBump(opts) {
   const entries = [];
   for (const pkgDir of changedPackageDirs) {
     const pkgInfo = packageMap.get(pkgDir);
-    const pkgJsonPath = join14(pkgDir, "package.json");
+    const pkgJsonPath = join15(pkgDir, "package.json");
     if (pkgJsonPath === rootPkgPath) continue;
     const versionFileCandidates = [
       { abs: pkgJsonPath, rel: relative3(cwd, pkgJsonPath).replace(/\\/g, "/") }
     ];
-    const tauriConfPath = join14(pkgDir, "src-tauri", "tauri.conf.json");
+    const tauriConfPath = join15(pkgDir, "src-tauri", "tauri.conf.json");
     const tauriRelPath = relative3(cwd, tauriConfPath).replace(/\\/g, "/");
     try {
       await access4(tauriConfPath);
       versionFileCandidates.push({ abs: tauriConfPath, rel: tauriRelPath });
     } catch {
     }
-    const appJsonPath = join14(pkgDir, "app.json");
+    const appJsonPath = join15(pkgDir, "app.json");
     const appJsonRelPath = relative3(cwd, appJsonPath).replace(/\\/g, "/");
     try {
       await access4(appJsonPath);
@@ -4181,7 +4310,7 @@ async function runBump(opts) {
     }
     let currentPkgJsonRaw;
     try {
-      currentPkgJsonRaw = await readFile13(pkgJsonPath, "utf-8");
+      currentPkgJsonRaw = await readFile14(pkgJsonPath, "utf-8");
     } catch (err) {
       console.warn(
         `runBump: could not read ${pkgJsonPath}: ${err instanceof Error ? err.message : String(err)}`
@@ -4226,7 +4355,7 @@ async function runBump(opts) {
     for (const { abs, rel } of versionFileCandidates) {
       let raw;
       try {
-        raw = await readFile13(abs, "utf-8");
+        raw = await readFile14(abs, "utf-8");
       } catch {
         continue;
       }
@@ -4240,11 +4369,11 @@ async function runBump(opts) {
       }
       const updated = injectVersion(raw, nextVersion, abs);
       if (!dryRun) {
-        await writeFile10(abs, updated, "utf-8");
+        await writeFile11(abs, updated, "utf-8");
       }
       updatedVersionFiles.push(rel);
     }
-    const changelogPath = join14(pkgDir, "CHANGELOG.md");
+    const changelogPath = join15(pkgDir, "CHANGELOG.md");
     const changelogUpdated = await prependChangelog(
       changelogPath,
       pkgInfo.name,
@@ -5612,6 +5741,7 @@ function distress(kind, message, jsonMode) {
 }
 async function runResolveWorktree() {
   const jsonMode = hasFlag("json", 3);
+  const cacheMode = hasFlag("cache", 3);
   let errorContext = null;
   const migrationNoticeCallback = (legacyPath, primaryPath) => {
     if (!jsonMode) {
@@ -5625,7 +5755,7 @@ async function runResolveWorktree() {
     const projectPath = process.cwd();
     const found = await findCodebyplanConfig(projectPath);
     if (!found?.contents.repo_id) {
-      emitAndExit(null, null, jsonMode);
+      emitAndExit(null, null, jsonMode, cacheMode ? false : void 0);
     }
     const repoId = found.contents.repo_id;
     try {
@@ -5656,7 +5786,7 @@ async function runResolveWorktree() {
           message: deviceErr instanceof Error ? deviceErr.message : String(deviceErr)
         };
       }
-      emitAndExit(null, errorContext, jsonMode);
+      emitAndExit(null, errorContext, jsonMode, cacheMode ? false : void 0);
     }
     let branch = "";
     try {
@@ -5685,7 +5815,12 @@ async function runResolveWorktree() {
       onError: onResolverError
     });
     if (worktreeId) {
-      emitAndExit(worktreeId, errorContext, jsonMode);
+      const cacheWritten = cacheMode ? await writeWorktreeCache(projectPath, {
+        worktree_id: worktreeId,
+        branch,
+        device_id: deviceId
+      }) : void 0;
+      emitAndExit(worktreeId, errorContext, jsonMode, cacheWritten);
     }
     const useFallback = hasFlag("fallback-from-branch", 3);
     if (useFallback) {
@@ -5696,23 +5831,33 @@ async function runResolveWorktree() {
         onError: onResolverError
       });
       if (fallbackId) {
-        emitAndExit(fallbackId, errorContext, jsonMode);
+        const cacheWritten = cacheMode ? await writeWorktreeCache(projectPath, {
+          worktree_id: fallbackId,
+          branch,
+          device_id: deviceId
+        }) : void 0;
+        emitAndExit(fallbackId, errorContext, jsonMode, cacheWritten);
       }
     }
-    emitAndExit(null, errorContext, jsonMode);
+    emitAndExit(null, errorContext, jsonMode, cacheMode ? false : void 0);
   } catch (err) {
     if (err instanceof ProcessExitSignal) throw err;
     const msg = err instanceof Error ? err.message : String(err);
     errorContext = { kind: "unhandled", message: msg };
-    emitAndExit(null, errorContext, jsonMode);
+    emitAndExit(null, errorContext, jsonMode, cacheMode ? false : void 0);
   }
 }
-function emitAndExit(worktreeId, errorContext, jsonMode) {
+function emitAndExit(worktreeId, errorContext, jsonMode, cacheWritten) {
   if (jsonMode) {
     const errorKind = errorContext?.kind ?? (worktreeId === null ? "tuple_miss" : null);
-    process.stdout.write(
-      JSON.stringify({ worktree_id: worktreeId, error_kind: errorKind }) + "\n"
-    );
+    const payload = {
+      worktree_id: worktreeId,
+      error_kind: errorKind
+    };
+    if (cacheWritten !== void 0) {
+      payload.cache_written = cacheWritten;
+    }
+    process.stdout.write(JSON.stringify(payload) + "\n");
   } else {
     if (worktreeId !== null) {
       process.stdout.write(worktreeId);
@@ -5731,7 +5876,177 @@ var init_resolve_worktree2 = __esm({
     init_flags();
     init_local_config();
     init_resolve_worktree();
+    init_worktree_cache();
+    init_process_exit_signal();
+  }
+});
+
+// src/cli/version-status.ts
+var version_status_exports = {};
+__export(version_status_exports, {
+  runVersionStatus: () => runVersionStatus
+});
+import { execFileSync, execSync as execSync6 } from "node:child_process";
+import { existsSync as existsSync4, readFileSync as readFileSync5 } from "node:fs";
+import { dirname as dirname8, join as join20 } from "node:path";
+function fetchLatestVersion() {
+  try {
+    return execFileSync("npm", ["view", "codebyplan", "version"], {
+      encoding: "utf-8",
+      stdio: ["pipe", "pipe", "pipe"]
+    }).trim() || null;
+  } catch {
+    return null;
+  }
+}
+function resolveGitRoot() {
+  try {
+    return execSync6("git rev-parse --show-toplevel", {
+      encoding: "utf-8"
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+function resolveCurrentBranch() {
+  try {
+    return execSync6("git symbolic-ref --short HEAD", {
+      encoding: "utf-8"
+    }).trim();
+  } catch {
+    try {
+      return execSync6("git rev-parse --abbrev-ref HEAD", {
+        encoding: "utf-8"
+      }).trim();
+    } catch {
+      return "";
+    }
+  }
+}
+function detectPackageManager2(gitRoot) {
+  let dir = process.cwd();
+  const stopAt = gitRoot ?? null;
+  while (true) {
+    if (existsSync4(join20(dir, "pnpm-lock.yaml"))) return "pnpm";
+    if (existsSync4(join20(dir, "yarn.lock"))) return "yarn";
+    if (existsSync4(join20(dir, "package-lock.json"))) return "npm";
+    if (stopAt !== null && dir === stopAt) break;
+    const parent = dirname8(dir);
+    if (parent === dir) break;
+    dir = parent;
+  }
+  return "npm";
+}
+function buildInstallCommand2(pm) {
+  switch (pm) {
+    case "pnpm":
+      return "pnpm add codebyplan@latest";
+    case "yarn":
+      return "yarn add codebyplan@latest";
+    case "npm":
+      return "npm install codebyplan@latest";
+  }
+}
+async function resolveGuard(gitRoot, currentBranch) {
+  if (gitRoot !== null) {
+    const canonicalPkgPath = join20(
+      gitRoot,
+      "packages",
+      "codebyplan-package",
+      "package.json"
+    );
+    try {
+      if (existsSync4(canonicalPkgPath)) {
+        const raw = readFileSync5(canonicalPkgPath, "utf-8");
+        const parsed = JSON.parse(raw);
+        if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && parsed["name"] === "codebyplan") {
+          return { guarded: true, guardReason: "canonical_source" };
+        }
+      }
+    } catch {
+    }
+  }
+  let protectedBranches = [];
+  try {
+    const found = await findCodebyplanConfig(process.cwd());
+    if (found) {
+      let gitJsonPath;
+      if (found.path.endsWith("/repo.json")) {
+        const dir = found.path.slice(0, found.path.lastIndexOf("/"));
+        gitJsonPath = join20(dir, "git.json");
+      } else {
+        const legacyDir = found.path.slice(0, found.path.lastIndexOf("/"));
+        gitJsonPath = join20(legacyDir, ".codebyplan", "git.json");
+      }
+      const raw = readFileSync5(gitJsonPath, "utf-8");
+      const parsed = JSON.parse(raw);
+      if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)) {
+        const bc = parsed["branch_config"];
+        if (typeof bc === "object" && bc !== null && !Array.isArray(bc)) {
+          const protectedField = bc["protected"];
+          if (Array.isArray(protectedField)) {
+            protectedBranches = protectedField.filter(
+              (v) => typeof v === "string"
+            );
+          }
+        }
+      }
+    }
+  } catch {
+    protectedBranches = [];
+  }
+  const isProtected = currentBranch === "main" || currentBranch !== "" && protectedBranches.includes(currentBranch);
+  if (isProtected) {
+    return { guarded: true, guardReason: "protected_branch" };
+  }
+  return { guarded: false, guardReason: null };
+}
+async function runVersionStatus() {
+  try {
+    const installed = VERSION;
+    const latest = fetchLatestVersion();
+    const newer = latest !== null && compareSemver(latest, installed) > 0;
+    const gitRoot = resolveGitRoot();
+    const pm = detectPackageManager2(gitRoot);
+    const installCommand = buildInstallCommand2(pm);
+    const currentBranch = resolveCurrentBranch();
+    const { guarded, guardReason } = await resolveGuard(gitRoot, currentBranch);
+    const result = {
+      installed,
+      latest,
+      newer,
+      packageManager: pm,
+      installCommand,
+      guarded,
+      guardReason
+    };
+    process.stdout.write(JSON.stringify(result) + "\n");
+    process.exit(0);
+  } catch (err) {
+    if (err instanceof ProcessExitSignal) throw err;
+    process.stdout.write(JSON.stringify(FAIL_SAFE) + "\n");
+    process.exit(0);
+  }
+}
+var FAIL_SAFE;
+var init_version_status = __esm({
+  "src/cli/version-status.ts"() {
+    "use strict";
+    init_version();
+    init_bump();
+    init_flags();
     init_process_exit_signal();
+    FAIL_SAFE = {
+      installed: VERSION,
+      latest: null,
+      newer: false,
+      packageManager: "npm",
+      installCommand: "npm install codebyplan@latest",
+      guarded: true,
+      // Detection failed entirely — guard conservatively with an explicit reason
+      // so consumers never see guarded:true paired with a null reason.
+      guardReason: "unknown"
+    };
   }
 });
 
@@ -5740,7 +6055,7 @@ var cmux_sync_exports = {};
 __export(cmux_sync_exports, {
   runCmuxSync: () => runCmuxSync
 });
-import { execSync as execSync6, execFileSync } from "node:child_process";
+import { execSync as execSync7, execFileSync as execFileSync2 } from "node:child_process";
 import { basename } from "node:path";
 async function runCmuxSync() {
   try {
@@ -5750,14 +6065,14 @@ async function runCmuxSync() {
     const bin = process.env.CMUX_BUNDLED_CLI_PATH || process.env.CMUX_CLAUDE_HOOK_CMUX_BIN || "cmux";
     let branch = "";
     try {
-      branch = execSync6("git rev-parse --abbrev-ref HEAD", {
+      branch = execSync7("git rev-parse --abbrev-ref HEAD", {
         encoding: "utf8"
       }).trim();
     } catch {
     }
     let folder = "";
     try {
-      const toplevel = execSync6("git rev-parse --show-toplevel", {
+      const toplevel = execSync7("git rev-parse --show-toplevel", {
         encoding: "utf8"
       }).trim();
       folder = basename(toplevel);
@@ -5765,7 +6080,7 @@ async function runCmuxSync() {
     }
     if (branch) {
       try {
-        execFileSync(bin, [
+        execFileSync2(bin, [
           "workspace-action",
           "--action",
           "rename",
@@ -5777,7 +6092,7 @@ async function runCmuxSync() {
     }
     if (folder) {
       try {
-        execFileSync(bin, [
+        execFileSync2(bin, [
           "workspace-action",
           "--action",
           "set-description",
@@ -5801,19 +6116,19 @@ var init_cmux_sync = __esm({
 });
 
 // src/lib/migrate-local-config.ts
-import { mkdir as mkdir5, readFile as readFile14, unlink as unlink2, writeFile as writeFile11 } from "node:fs/promises";
-import { join as join19 } from "node:path";
+import { mkdir as mkdir6, readFile as readFile15, unlink as unlink2, writeFile as writeFile12 } from "node:fs/promises";
+import { join as join21 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join19(projectPath, ".codebyplan.json");
+  return join21(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join19(projectPath, ".codebyplan.local.json");
+  return join21(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join19(projectPath, ".codebyplan");
+  return join21(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join19(projectPath, ".codebyplan", "repo.json");
+  return join21(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -5852,7 +6167,7 @@ async function runLocalMigration(projectPath) {
   }
   let legacyRaw;
   try {
-    legacyRaw = await readFile14(legacySharedPath(projectPath), "utf-8");
+    legacyRaw = await readFile15(legacySharedPath(projectPath), "utf-8");
   } catch {
     return {
       migrated: true,
@@ -5879,7 +6194,7 @@ async function runLocalMigration(projectPath) {
   let deviceId;
   let deviceWrittenByHelper = false;
   try {
-    const localRaw = await readFile14(legacyLocalPath(projectPath), "utf-8");
+    const localRaw = await readFile15(legacyLocalPath(projectPath), "utf-8");
     const localParsed = JSON.parse(localRaw);
     if (typeof localParsed.device_id === "string") {
       deviceId = localParsed.device_id;
@@ -5887,7 +6202,7 @@ async function runLocalMigration(projectPath) {
   } catch {
   }
   try {
-    await mkdir5(newDirPath(projectPath), { recursive: true });
+    await mkdir6(newDirPath(projectPath), { recursive: true });
   } catch (err) {
     const code = err.code;
     if (code === "ENOTDIR" || code === "EEXIST") {
@@ -5906,8 +6221,8 @@ async function runLocalMigration(projectPath) {
   if ("repo_id" in cfg) repoJson.repo_id = cfg.repo_id;
   if ("organization_id" in cfg) repoJson.organization_id = cfg.organization_id;
   if ("project_id" in cfg) repoJson.project_id = cfg.project_id;
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "repo.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -5919,8 +6234,8 @@ async function runLocalMigration(projectPath) {
     serverJson.auto_push_enabled = cfg.auto_push_enabled;
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "server.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -5928,44 +6243,44 @@ async function runLocalMigration(projectPath) {
   const gitJson = {};
   if ("git_branch" in cfg) gitJson.git_branch = cfg.git_branch;
   if ("branch_config" in cfg) gitJson.branch_config = cfg.branch_config;
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "git.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/git.json");
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "shipment.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "shipment.json"),
     JSON.stringify(shipmentJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/shipment.json");
   const vendorJson = {};
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "vendor.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "vendor.json"),
     JSON.stringify(vendorJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/vendor.json");
   const e2eJson = {};
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "e2e.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "e2e.json"),
     JSON.stringify(e2eJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/e2e.json");
   const eslintJson = {};
-  await writeFile11(
-    join19(projectPath, ".codebyplan", "eslint.json"),
+  await writeFile12(
+    join21(projectPath, ".codebyplan", "eslint.json"),
     JSON.stringify(eslintJson, null, 2) + "\n",
     "utf-8"
   );
   filesChanged.push(".codebyplan/eslint.json");
   if (!deviceWrittenByHelper) {
-    await writeFile11(
-      join19(projectPath, ".codebyplan", "device.local.json"),
+    await writeFile12(
+      join21(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -5977,9 +6292,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 = join19(projectPath, ".gitignore");
+  const gitignorePath = join21(projectPath, ".gitignore");
   try {
-    const gitignoreContent = await readFile14(gitignorePath, "utf-8");
+    const gitignoreContent = await readFile15(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
     const newLine = ".codebyplan/device.local.json";
     const hasLegacy = gitignoreContent.split("\n").some((l) => l.trimEnd() === legacyLine);
@@ -5998,7 +6313,7 @@ async function runLocalMigration(projectPath) {
       updated = gitignoreContent;
     }
     if (updated !== gitignoreContent) {
-      await writeFile11(gitignorePath, updated, "utf-8");
+      await writeFile12(gitignorePath, updated, "utf-8");
       filesChanged.push(".gitignore");
     }
   } catch {
@@ -6038,8 +6353,8 @@ __export(config_exports, {
   readVendorConfig: () => readVendorConfig,
   runConfig: () => runConfig
 });
-import { mkdir as mkdir6, readFile as readFile15, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join20 } from "node:path";
+import { mkdir as mkdir7, readFile as readFile16, writeFile as writeFile13 } from "node:fs/promises";
+import { join as join22 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -6072,14 +6387,14 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join20(projectPath, ".codebyplan");
+  const codebyplanDir = join22(projectPath, ".codebyplan");
   let resolvedWorktreeId;
   try {
     const deviceId = await getOrCreateDeviceId(projectPath);
     let branch = "main";
     try {
-      const { execSync: execSync7 } = await import("node:child_process");
-      branch = execSync7("git symbolic-ref --short HEAD", {
+      const { execSync: execSync8 } = await import("node:child_process");
+      branch = execSync8("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
@@ -6203,7 +6518,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
     console.log("  Config would be updated (dry-run).");
     return;
   }
-  await mkdir6(codebyplanDir, { recursive: true });
+  await mkdir7(codebyplanDir, { recursive: true });
   const files = [
     { name: "repo.json", payload: repoPayload },
     { name: "server.json", payload: serverPayload },
@@ -6215,16 +6530,16 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
-    const filePath = join20(codebyplanDir, name);
+    const filePath = join22(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
-      currentJson = await readFile15(filePath, "utf-8");
+      currentJson = await readFile16(filePath, "utf-8");
     } catch {
     }
     if (createOnly && currentJson !== "") continue;
     if (currentJson === newJson) continue;
-    await writeFile12(filePath, newJson, "utf-8");
+    await writeFile13(filePath, newJson, "utf-8");
     console.log(`  Updated .codebyplan/${name}`);
     anyUpdated = true;
   }
@@ -6234,8 +6549,8 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 }
 async function readRepoConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "repo.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6245,8 +6560,8 @@ async function readRepoConfig(projectPath) {
 }
 async function readServerConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "server.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6256,8 +6571,8 @@ async function readServerConfig(projectPath) {
 }
 async function readGitConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "git.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6267,8 +6582,8 @@ async function readGitConfig(projectPath) {
 }
 async function readShipmentConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "shipment.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6278,8 +6593,8 @@ async function readShipmentConfig(projectPath) {
 }
 async function readVendorConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "vendor.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6289,8 +6604,8 @@ async function readVendorConfig(projectPath) {
 }
 async function readE2eConfig(projectPath) {
   try {
-    const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "e2e.json"),
+    const raw = await readFile16(
+      join22(projectPath, ".codebyplan", "e2e.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6346,14 +6661,14 @@ var init_server_detect = __esm({
 });
 
 // src/lib/port-verify.ts
-import { readFile as readFile16 } from "node:fs/promises";
+import { readFile as readFile17 } 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 readFile16(pkgPath, "utf-8");
+      const raw = await readFile17(pkgPath, "utf-8");
       const pkg = JSON.parse(raw);
       const scriptPort = detectPortFromScripts(pkg);
       if (scriptPort !== null && !allocatedPorts.has(scriptPort)) {
@@ -6416,7 +6731,7 @@ async function findUnallocatedApps(projectPath, portAllocations) {
     }
     let pkg;
     try {
-      const raw = await readFile16(`${app.absPath}/package.json`, "utf-8");
+      const raw = await readFile17(`${app.absPath}/package.json`, "utf-8");
       pkg = JSON.parse(raw);
     } catch {
       continue;
@@ -6562,7 +6877,7 @@ __export(tech_stack_exports, {
   runFullTechStack: () => runFullTechStack,
   runTechStack: () => runTechStack
 });
-import { existsSync as existsSync4 } from "node:fs";
+import { existsSync as existsSync5 } from "node:fs";
 async function runTechStack() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -6624,10 +6939,10 @@ async function runTechStack() {
         );
       }
       try {
-        const { execSync: execSync7 } = await import("node:child_process");
+        const { execSync: execSync8 } = await import("node:child_process");
         let branch = "main";
         try {
-          branch = execSync7("git symbolic-ref --short HEAD", {
+          branch = execSync8("git symbolic-ref --short HEAD", {
             cwd: projectPath,
             encoding: "utf-8"
           }).trim();
@@ -6735,7 +7050,7 @@ async function runFullTechStack(dryRun) {
       continue;
     }
     const localWorktrees = worktrees.filter(
-      (wt) => wt.path ? existsSync4(wt.path) : false
+      (wt) => wt.path ? existsSync5(wt.path) : false
     );
     if (localWorktrees.length === 0) {
       console.log(`  skipping ${repo.name} \u2014 no local worktree on this device`);
@@ -7418,13 +7733,13 @@ var init_uninstall = __esm({
 
 // src/index.ts
 init_version();
-import { readFileSync as readFileSync7 } from "node:fs";
+import { readFileSync as readFileSync8 } from "node:fs";
 import { resolve as resolve6 } from "node:path";
 void (async () => {
   if (!process.env.CODEBYPLAN_API_KEY) {
     try {
       const envPath = resolve6(process.cwd(), ".env.local");
-      const content = readFileSync7(envPath, "utf-8");
+      const content = readFileSync8(envPath, "utf-8");
       for (const line of content.split("\n")) {
         const trimmed = line.trim();
         if (!trimmed || trimmed.startsWith("#")) continue;
@@ -7536,6 +7851,11 @@ void (async () => {
     await runResolveWorktree2();
     process.exit(0);
   }
+  if (arg === "version-status") {
+    const { runVersionStatus: runVersionStatus2 } = await Promise.resolve().then(() => (init_version_status(), version_status_exports));
+    await runVersionStatus2();
+    process.exit(0);
+  }
   if (arg === "cmux-sync") {
     const { runCmuxSync: runCmuxSync2 } = await Promise.resolve().then(() => (init_cmux_sync(), cmux_sync_exports));
     await runCmuxSync2();
@@ -7639,6 +7959,7 @@ void (async () => {
     codebyplan claude                Claude asset management (install/update/uninstall)
     codebyplan statusline            Show or set the statusline renderer (bash/node/python)
     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 help                  Show this help message
     codebyplan --version             Print version
@@ -7677,6 +7998,11 @@ void (async () => {
       --node                  Set statusline renderer to node after install/update
       --python                Set statusline renderer to python after install/update
 
+  Resolve-worktree options:
+    --json                  Structured JSON output instead of bare UUID
+    --fallback-from-branch  Fallback resolver: filter by (device_id, branch) client-side
+    --cache                 Resolve and write worktree id to .codebyplan/worktree.local.json
+
   MCP Server:
     Claude Code connects to CodeByPlan via remote MCP:
       URL: https://mcp.codebyplan.com/mcp