codebyplan 1.13.7 → 1.13.9

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.7";
+    VERSION = "1.13.9";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -1443,8 +1443,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 +3064,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(
@@ -5735,12 +5735,181 @@ var init_resolve_worktree2 = __esm({
   }
 });
 
+// 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 dirname7, join as join19 } 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(join19(dir, "pnpm-lock.yaml"))) return "pnpm";
+    if (existsSync4(join19(dir, "yarn.lock"))) return "yarn";
+    if (existsSync4(join19(dir, "package-lock.json"))) return "npm";
+    if (stopAt !== null && dir === stopAt) break;
+    const parent = dirname7(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 = join19(
+      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 = join19(dir, "git.json");
+      } else {
+        const legacyDir = found.path.slice(0, found.path.lastIndexOf("/"));
+        gitJsonPath = join19(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"
+    };
+  }
+});
+
 // src/cli/cmux-sync.ts
 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 +5919,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 +5934,7 @@ async function runCmuxSync() {
     }
     if (branch) {
       try {
-        execFileSync(bin, [
+        execFileSync2(bin, [
           "workspace-action",
           "--action",
           "rename",
@@ -5777,7 +5946,7 @@ async function runCmuxSync() {
     }
     if (folder) {
       try {
-        execFileSync(bin, [
+        execFileSync2(bin, [
           "workspace-action",
           "--action",
           "set-description",
@@ -5802,18 +5971,18 @@ 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 { join as join20 } from "node:path";
 function legacySharedPath(projectPath) {
-  return join19(projectPath, ".codebyplan.json");
+  return join20(projectPath, ".codebyplan.json");
 }
 function legacyLocalPath(projectPath) {
-  return join19(projectPath, ".codebyplan.local.json");
+  return join20(projectPath, ".codebyplan.local.json");
 }
 function newDirPath(projectPath) {
-  return join19(projectPath, ".codebyplan");
+  return join20(projectPath, ".codebyplan");
 }
 function sentinelPath(projectPath) {
-  return join19(projectPath, ".codebyplan", "repo.json");
+  return join20(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
   const { stat: stat2 } = await import("node:fs/promises");
@@ -5907,7 +6076,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 writeFile11(
-    join19(projectPath, ".codebyplan", "repo.json"),
+    join20(projectPath, ".codebyplan", "repo.json"),
     JSON.stringify(repoJson, null, 2) + "\n",
     "utf-8"
   );
@@ -5920,7 +6089,7 @@ async function runLocalMigration(projectPath) {
   if ("port_allocations" in cfg)
     serverJson.port_allocations = cfg.port_allocations;
   await writeFile11(
-    join19(projectPath, ".codebyplan", "server.json"),
+    join20(projectPath, ".codebyplan", "server.json"),
     JSON.stringify(serverJson, null, 2) + "\n",
     "utf-8"
   );
@@ -5929,7 +6098,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 writeFile11(
-    join19(projectPath, ".codebyplan", "git.json"),
+    join20(projectPath, ".codebyplan", "git.json"),
     JSON.stringify(gitJson, null, 2) + "\n",
     "utf-8"
   );
@@ -5937,35 +6106,35 @@ async function runLocalMigration(projectPath) {
   const shipmentJson = {};
   if ("shipment" in cfg) shipmentJson.shipment = cfg.shipment;
   await writeFile11(
-    join19(projectPath, ".codebyplan", "shipment.json"),
+    join20(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"),
+    join20(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"),
+    join20(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"),
+    join20(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"),
+      join20(projectPath, ".codebyplan", "device.local.json"),
       JSON.stringify({ device_id: deviceId }, null, 2) + "\n",
       "utf-8"
     );
@@ -5977,7 +6146,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 = join19(projectPath, ".gitignore");
+  const gitignorePath = join20(projectPath, ".gitignore");
   try {
     const gitignoreContent = await readFile14(gitignorePath, "utf-8");
     const legacyLine = ".codebyplan.local.json";
@@ -6039,7 +6208,7 @@ __export(config_exports, {
   runConfig: () => runConfig
 });
 import { mkdir as mkdir6, readFile as readFile15, writeFile as writeFile12 } from "node:fs/promises";
-import { join as join20 } from "node:path";
+import { join as join21 } from "node:path";
 async function runConfig() {
   const flags = parseFlags(3);
   const dryRun = hasFlag("dry-run", 3);
@@ -6072,14 +6241,14 @@ async function runConfig() {
   console.log("\n  Config complete.\n");
 }
 async function syncConfigToFile(repoId, projectPath, dryRun) {
-  const codebyplanDir = join20(projectPath, ".codebyplan");
+  const codebyplanDir = join21(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();
@@ -6215,7 +6384,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
   ];
   let anyUpdated = false;
   for (const { name, payload, createOnly } of files) {
-    const filePath = join20(codebyplanDir, name);
+    const filePath = join21(codebyplanDir, name);
     const newJson = JSON.stringify(payload, null, 2) + "\n";
     let currentJson = "";
     try {
@@ -6235,7 +6404,7 @@ async function syncConfigToFile(repoId, projectPath, dryRun) {
 async function readRepoConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "repo.json"),
+      join21(projectPath, ".codebyplan", "repo.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6246,7 +6415,7 @@ async function readRepoConfig(projectPath) {
 async function readServerConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "server.json"),
+      join21(projectPath, ".codebyplan", "server.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6257,7 +6426,7 @@ async function readServerConfig(projectPath) {
 async function readGitConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "git.json"),
+      join21(projectPath, ".codebyplan", "git.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6268,7 +6437,7 @@ async function readGitConfig(projectPath) {
 async function readShipmentConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "shipment.json"),
+      join21(projectPath, ".codebyplan", "shipment.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6279,7 +6448,7 @@ async function readShipmentConfig(projectPath) {
 async function readVendorConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "vendor.json"),
+      join21(projectPath, ".codebyplan", "vendor.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6290,7 +6459,7 @@ async function readVendorConfig(projectPath) {
 async function readE2eConfig(projectPath) {
   try {
     const raw = await readFile15(
-      join20(projectPath, ".codebyplan", "e2e.json"),
+      join21(projectPath, ".codebyplan", "e2e.json"),
       "utf-8"
     );
     return JSON.parse(raw);
@@ -6562,7 +6731,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 +6793,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 +6904,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 +7587,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 +7705,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 +7813,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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codebyplan",
-  "version": "1.13.7",
+  "version": "1.13.9",
   "description": "CLI for CodeByPlan — AI-powered development planning and tracking",
   "type": "module",
   "bin": {

package/templates/settings.project.base.json

@@ -149,6 +149,7 @@
       "mcp__codebyplan__get_worktrees",
       "mcp__codebyplan__list_tech_stack_sync_sessions",
       "mcp__codebyplan__get_chunk",
+      "mcp__codebyplan__get_library_toc",
       "mcp__codebyplan__list_migrations",
       "mcp__codebyplan__lookup_symbol",
       "mcp__codebyplan__resolve_library_id",
@@ -180,6 +181,8 @@
       "Bash(npx codebyplan resolve-worktree:*)",
       "Bash(codebyplan cmux-sync:*)",
       "Bash(npx codebyplan cmux-sync:*)",
+      "Bash(codebyplan version-status:*)",
+      "Bash(npx codebyplan version-status:*)",
       "Bash(codebyplan statusline:*)",
       "Bash(npx codebyplan statusline:*)",
       "Bash(codebyplan ports:*)",

package/templates/skills/cbp-session-end/SKILL.md

@@ -25,7 +25,7 @@ Always write a session log for this session — **even if empty**. `/cbp-session
 
 ### Step 1.3: Capture Handoff Snapshot
 
-Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can auto-resume. Per `.claude/rules/session-resume.md` write-path contract.
+Snapshot the current next-action so the next `/cbp-session-start` (Step 4.5) can auto-resume. The handoff write-path + payload shape are specified inline here and in `/cbp-session-start` Step 4.5 (freshness gate).
 
 1. Call MCP `get_next_action({ repo_id, worktree_id })`.
 2. If the returned `command` is non-empty (active work in flight):
@@ -60,7 +60,8 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
    - Collect `files[]` from those rounds → `task_files` set
    - If no active task exists, `task_files` is empty
 3. `infra_files = changed_files − task_files`
-4. If `infra_files` is empty → skip. Otherwise present once:
+4. Re-run `git status --porcelain` immediately before showing the commit-prompt (after Steps 1–1.3 have completed their MCP round-trips). Recompute `infra_files` from the fresh listing — eliminates the race where files appear in the index only after the network round-trips complete.
+5. If `infra_files` is empty → skip. Otherwise present once:
 
    ```
    Commit these non-task files before ending session?
@@ -69,7 +70,7 @@ Same rule as `/cbp-session-start` Step 5.7 — only commit files that are **not*
    Reply: yes | no | select
    ```
 
-5. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit`.
+6. On `yes`: `git add` the listed files, then trigger `/cbp-git-commit`.
    On `no`: skip. On `select`: ask which subset.
 
 Non-blocking — session end proceeds either way.
@@ -78,7 +79,7 @@ Non-blocking — session end proceeds either way.
 
 Keep this worktree's **home branch** rooted at the freshest production tip — no prompt, fully non-blocking. Home branches are the folder-named placeholder branches each worktree rests on (e.g. `codebyplan-web`); `feat/*` branches are deliberately skipped — they integrate via `/cbp-merge-main` with QA, never an auto fast-forward.
 
-Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the asset-update CLIs operate on the freshest tree.
+Runs after Step 1.5 so any infra commits land first, and before Step 1.7 so the freshness gate's asset update operates on the freshest tree.
 
 Resolve the production branch: read `.codebyplan/git.json` and take `branch_config.production` (fall back to `main` if the file or field is absent). Call this `$PRODUCTION`. Then compare the current branch against the worktree's folder name:
 
@@ -99,83 +100,35 @@ CURRENT="$(git rev-parse --abbrev-ref HEAD)"
 
 Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is a signal to reconcile manually, not to overwrite.
 
-### Step 1.7: Auto-Update CodeByPlan Assets
+### Step 1.7: Package Freshness Gate
 
-Run the latest published CLIs to pull any asset or config changes. Sub-block A runs first, then Sub-block B. A failure in A does **not** skip B — each sub-block has its own retry-and-warn lane.
+Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch, then run the local install + asset update. Runs after the Step 1.6 home-branch fast-forward (so any update lands on the freshest tree) and before Step 2. Fully non-blocking — the guard and skip branches proceed silently; any failure in the install/update commands warns once and continues to Step 2. session-end never halts.
 
-**a) `codebyplan claude` (asset subcommand group)**
-
-Run the latest published CLI's asset-update verb to pull any skill / agent / hook changes:
-
-```
-npx codebyplan@latest claude update
-```
-
-Always run — do not skip, even when the current repo is the canonical-owner monorepo source.
-
-The command may pause for interactive prompts when:
-
-- a tracked file has been hand-edited locally (overwrite / skip / diff)
-- a new file is being shipped for the first time (opt-in / skip)
-- a file has been removed from the package (remove / keep)
-
-Respond to each prompt in the terminal as it appears. The commit prompt below runs only after all per-file prompts are resolved.
-
-Failure handling:
-
-- On non-zero exit: wait ~5 s, retry once.
-- If retry also fails: print a warning and continue — this step is non-blocking.
-
-After the command exits (success):
-
-1. Run `git status --porcelain -- .claude/` to detect any file changes.
-2. If non-empty, present once (same pattern as Step 1.5):
-
-   ```
-   .claude/ was updated. Commit these changes?
-   [list of changed paths under .claude/]
-
-   Reply: yes | no | select
-   ```
-
-   On `yes`: `git add` the listed paths only (not the whole `.claude/` directory), then trigger `/cbp-git-commit`.
-   On `no`: skip. On `select`: ask which subset.
-
-3. Print the final stdout line from the update command as a one-line session summary (e.g. `codebyplan claude update: 47 files tracked.`). Silent when the command produces no stdout.
-
-Non-blocking — session end proceeds regardless of outcome.
-
-**b) `codebyplan` (project CLI)**
-
-Fetch the latest published version of the project CLI. The `codebyplan` CLI has no `update` verb (subcommands are `setup`, `sync`, `eslint`); the freshness idiom is to invoke a fast read-only flag with `@latest` so npx fetches and caches the newest published version:
-
-```
-npx codebyplan@latest --version
+```bash
+VERSION_JSON=$(npx codebyplan version-status 2>/dev/null)
 ```
 
-Do **not** run `sync`, `setup`, or any other state-changing subcommand — this step updates the cached binary only.
-
-Failure handling:
-
-- On non-zero exit: wait ~5 s, retry once.
-- If retry also fails: print a warning and continue — this step is non-blocking.
-
-After the command exits (success):
+Parse `$VERSION_JSON` as JSON and branch on the result:
 
-1. Run `git status --porcelain -- .codebyplan/` to detect any file changes.
-2. If non-empty, present once (same pattern as Step 1.5):
+- **Probe failed / unparseable** — the command errored, produced no output, or the output cannot be parsed as JSON carrying the required keys (`newer`, `guarded`, `installCommand`). This includes an installed `codebyplan` too old to have the `version-status` subcommand (which prints `Unknown command`). → **FAIL-SAFE SKIP**: proceed silently to Step 2. A best-effort freshness probe must never disrupt session-end.
+- **`guarded: true`** (protected/main branch OR the canonical `codebyplan` source monorepo — any `guardReason`) → skip silently, proceed to Step 2. Gate on the `guarded` boolean only; never branch on the specific `guardReason` string. This is the guard that prevents clobbering the canonical monorepo's ahead-of-published `.claude/` and blocks any update or commit on a protected branch.
+- **`newer: false`** (already up to date) → skip silently, proceed to Step 2.
+- **`newer: true` AND `guarded: false`** → run the update path:
+  1. Run the JSON's `installCommand` (e.g. `pnpm add codebyplan@latest`) to LOCALLY install `codebyplan@latest` via the repo's package manager. Never a global `-g` install.
+  2. Run `npx codebyplan claude update` to refresh the worktree's `.claude/` assets on the current branch. If `installCommand` (step 1) or this command exits non-zero, warn once and skip to Step 2 — this path is non-blocking.
+  3. Detect changes across BOTH asset directories in one pass: `git status --porcelain -- .claude/ .codebyplan/`. If non-empty, present a single combined offer (same pattern as Step 1.5):
 
-   ```
-   .codebyplan/ was updated. Commit these changes?
-   [list of changed paths under .codebyplan/]
+     ```
+     codebyplan updated. Commit these changes before ending the session?
+     [list of changed paths under .claude/ and .codebyplan/]
 
-   Reply: yes | no | select
-   ```
+     Reply: yes | no | select
+     ```
 
-   On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`.
-   On `no`: skip. On `select`: ask which subset.
+     On `yes`: `git add` the listed paths only (not the whole directories), then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
+  4. Continue to Step 2 — session-end does NOT halt. The update lands in the current worktree on its current branch; main/protected branches and the canonical source repo are already excluded by the `guarded` check above.
 
-3. Print the command's stdout (the version line) as a one-line session summary (e.g. `codebyplan 1.4.2`). Silent when the command produces no stdout.
+**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so `version-status` returns `guarded:false` there and this gate runs the update exactly as on a feat branch — landing it on whichever branch the worktree currently rests on (the deliberate "update the branch they're on, except main/canonical" behavior).
 
 Non-blocking — session end proceeds regardless of outcome.
 
@@ -204,9 +157,9 @@ You can close this window.
 ## Integration
 
 - **Triggered by**: user invocation (prompted by `/cbp-todo` when no work remains)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward), MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot)
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.6 home-branch fast-forward), MCP `get_session_logs` (resolve current log), MCP `get_current_task`, MCP `get_rounds`, MCP `get_next_action` (Step 1.3 handoff snapshot); `npx codebyplan version-status` (Step 1.7 package-freshness gate)
 - **Writes**: MCP `update_session_log` (with `ended_at` + `handoff` per TASK-2 alias surface; or `create_session_log` fallback), MCP `update_session_state` (deactivate)
 - **Spawns**: none
-- **Triggers**: none at the skill-contract level. Steps 1.5 and 1.7 may invoke `/cbp-git-commit` inline on user approval.
+- **Triggers**: none at the skill-contract level. Step 1.5 may invoke `/cbp-git-commit` inline on user approval; Step 1.7 may invoke `/cbp-git-commit` on the `newer:true AND guarded:false` update path (committing changed `.claude/` and `.codebyplan/` paths).
 - **Paired with**: `/cbp-session-start`
-- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + write-path contract)
+- **Pairs with**: `/cbp-session-start` Step 4.5 (handoff payload shape + freshness-gate contract; specified inline — no separate rule file)

package/templates/skills/cbp-session-start/SKILL.md

@@ -12,32 +12,29 @@ Activate the session, open a fresh session log, and surface the previous log's p
 
 ## Instructions
 
-Run Steps 0 through 5.8 silently (no intermediate output) — except Step 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 2 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
+Run Steps 0 through 5.8 silently (no intermediate output) — except Step 0 aborts the session on MCP failure, Step 1.4 may surface a one-line fast-forward note or warning, Step 1.5 may surface a one-line infra-drift nudge, Step 1.6 may run an install-and-halt path, Step 4.5 may auto-resume a handoff and exit session-start entirely (no Step 6 output), and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 1.5 → 1.6 → 3 → 4 → 4.5 → 5 → 5.7 → 5.8 → 6 → 7.) Produce ONE output block at Step 6, then auto-trigger or stop per Step 7.
 
-### Step 0: MCP Health Check
+### Step 0: MCP Health Gate
 
-Call MCP `health_check` tool.
+Call MCP `health_check` tool. **The MCP connection is vital — this is a hard gate.**
 
-- **If succeeds**: Continue silently
-- **If fails**: Show warning:
+- **If succeeds**: Continue silently to Step 1.
+- **If fails**: Print the error below and **STOP the entire session-start**. Do NOT continue to Step 1 or any later step — no config load, no `update_session_state(activate)`, no `create_session_log`, no `/cbp-todo` trigger:
 
   ```
-  ⚠ MCP connection failed. Check:
+  ✖ MCP connection failed — session-start aborted. Check:
   1. Network connectivity
   2. API key validity (CODEBYPLAN_API_KEY env var)
   3. codebyplan.com availability
 
-  Session continues but MCP-dependent features will be unavailable.
+  Fix the connection, then run /cbp-session-start again.
   ```
 
-  Continue to Step 1 (non-blocking).
-
 ### Step 1: Load Config
 
 Read per-concern config files from the project root. Single load point for the session:
 
 - `repo_id` (UUID) — from `.codebyplan/repo.json`, required for all MCP operations
-- `server_port`, `server_type`, `auto_push_enabled` — from `.codebyplan/server.json`
 - `git_branch` — from `.codebyplan/git.json`
 
 Resolve `worktree_id` at runtime using the structured JSON form:
@@ -79,7 +76,7 @@ Never rebase, reset, force-push, or stash. A non-fast-forwardable home branch is
 
 ### Step 1.5: Infra Drift Check
 
-Surface — never block — when this worktree's CBP tooling has fallen behind. Runs after Step 1.4 and may add one line to the Step 6 output. Two mutually-exclusive concepts, keyed on repo type (`$PRODUCTION` is the branch resolved in Step 1.4):
+Surface — never block — when this worktree's source-monorepo `.claude/` infra has fallen behind. Runs after Step 1.4 and may add one line to the Step 6 output (`$PRODUCTION` is the branch resolved in Step 1.4). Consumer-repo package-version freshness is handled by Step 1.6 (the freshness gate), not here:
 
 - **Monorepo (concept A)** — both `packages/codebyplan-package/templates/` and `scripts/infra-drift.mjs` exist. Step 1.4 skips the fetch on a feat branch, so refresh `origin/$PRODUCTION` best-effort first, then run the reporter:
 
@@ -90,26 +87,46 @@ Surface — never block — when this worktree's CBP tooling has fallen behind.
 
   The script self-guards (feat branch + behind > 0) and emits at most one `⚠ .claude/ infra is N behind — run /cbp-refresh-infra` line. Hold any output for Step 6.
 
-- **Consumer (concept B)** — no `templates/`, but an install manifest exists (`.claude/.cbp.manifest.json`, falling back to `.cbp-claude.manifest.json` then `.codebyplan-claude.manifest.json`). Compare its `version` to the latest published `codebyplan`, offline-safe:
+- **Neither** → skip silently.
 
-  ```bash
-  LATEST="$(npm view codebyplan version 2>/dev/null)"
-  ```
+Fully non-blocking; every failure path falls through with no output.
 
-  When `$LATEST` is non-empty and newer than the manifest `version`, hold one line for Step 6: `⚠ codebyplan {installed} → {LATEST} — run npx codebyplan@latest claude update`. Any failure (offline, npm absent) → silent.
+### Step 1.6: Package Freshness Gate
 
-- **Neither** → skip silently.
+Check whether a newer `codebyplan` is published and safe to auto-install on this worktree's current branch. Runs AFTER the infra-drift check (Step 1.5) and BEFORE session activation (Step 3).
+
+```bash
+VERSION_JSON=$(npx codebyplan version-status 2>/dev/null)
+```
+
+Parse `$VERSION_JSON` as JSON and branch on the result:
+
+- **Probe failed / unparseable** — the command errored, produced no output, or the output cannot be parsed as JSON carrying the required keys (`newer`, `guarded`, `installCommand`). This includes an installed `codebyplan` too old to have the `version-status` subcommand (which prints `Unknown command`). → **FAIL-SAFE SKIP**: proceed silently to Step 3. Never disrupt a session over a best-effort freshness probe — the MCP gate (Step 0) is the only vital gate.
+- **`guarded: true`** (protected/main branch OR the canonical `codebyplan` source monorepo — any `guardReason`) → skip silently, proceed to Step 3. Gate on the `guarded` boolean only; never branch on the specific `guardReason` string.
+- **`newer: false`** (already up to date) → skip silently, proceed to Step 3.
+- **`newer: true` AND `guarded: false`** → run the update path:
+  1. Run the JSON's `installCommand` (e.g. `pnpm add codebyplan@latest`) to LOCALLY install `codebyplan@latest` via the repo's package manager. Never a global `-g` install.
+  2. Run `npx codebyplan claude update` to refresh the worktree's `.claude/` assets on the current branch.
+  3. Detect changes across BOTH asset directories in one pass: `git status --porcelain -- .claude/ .codebyplan/`. If non-empty, offer the same commit gate as Step 5.7:
+
+     ```
+     codebyplan updated. Commit the resulting .claude/ and .codebyplan/ changes before exiting?
+     [list of changed paths under .claude/ and .codebyplan/]
+
+     Reply: yes | no | select
+     ```
 
-Concept B never fires in the monorepo — the `templates/` guard routes the source repo to concept A only (its manifest `version` is intentionally stale). Fully non-blocking; every failure path falls through with no output.
+     On `yes`: `git add` the listed paths only, then trigger `/cbp-git-commit`. On `no`: skip. On `select`: ask which subset.
+  4. **HALT** — do NOT proceed to Step 3. Print:
 
-### Step 2: Check Dev Server
+     ```
+     ✓ codebyplan updated to {latest}. Start a FRESH Claude Code session
+     (run /clear or open a new window) so the updated .claude/ takes effect.
+     ```
 
-**Skip if `server_type` is `"none"`.**
+     On this update-and-halt path the session is NOT continued: `update_session_state(activate)` is NOT called, `create_session_log` is NOT called, and `/cbp-todo` is NOT triggered.
 
-1. Get `server_port` from `.codebyplan/server.json`
-2. Check if running: `lsof -ti:{PORT} 2>/dev/null`
-3. If running, verify health: `curl -s -o /dev/null -w "%{http_code}" http://localhost:{PORT}/ --max-time 2`
-4. If NOT running, note in output that user should start via desktop app
+**Home branches are intentionally not guarded.** A worktree's folder-named home branch (e.g. `codebyplan-web`) is neither protected/main nor the canonical source, so `version-status` returns `guarded:false` there and this gate fires exactly as on a feat branch. That is deliberate — the update lands on whatever branch the worktree is currently resting on (the "update the branch they're on, except main/canonical" decision), not an accidental halt.
 
 ### Step 3: Update Session State
 
@@ -136,7 +153,7 @@ Hold the new log's ID in context so `/cbp-session-end` can update the same recor
 
 ### Step 4.5: Handoff Auto-Resume Probe
 
-Probe the most-recent closed session log for a structured handoff payload (per `.claude/rules/session-resume.md`) and auto-resume directly into the captured command when fresh. Additive — placed BEFORE the existing `/cbp-todo` auto-trigger; ALL failure paths fall through silently to Step 7.
+Probe the most-recent closed session log for a structured handoff payload (the handoff freshness-gate contract is specified inline in this step) and auto-resume directly into the captured command when fresh. Additive — placed BEFORE the existing `/cbp-todo` auto-trigger; ALL failure paths fall through silently to Step 7.
 
 1. Reuse the row held from Step 4 (same `get_session_logs({ repo_id, worktree_id, limit: 1 })` call shape — no extra MCP round-trip).
 2. **Defensive gates** (any failure → silent fall-through to Step 7):
@@ -205,7 +222,6 @@ Ownership: [total_count] active CHK(s), [owned_count] owned by this worktree
 [Owned: CHK-NNN (title), … — only when owned_count > 0]
 [Cross-worktree: CHK-ZZZ (name), … — only when total_count > owned_count]
 
-[⚠ Dev server not running — start via desktop app — only if applicable]
 [⚠ Worktree unregistered — run `npx codebyplan setup` to register — only when WORKTREE_ID is null and no resolver distress was already shown]
 ```
 
@@ -223,9 +239,9 @@ Three-branch gate using `owned_count` and `total_count` from Step 5.8:
 
 - **Triggered by**: user invocation, `/clear` recovery
 - **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal; non-tuple-miss distress is non-blocking at session-start)
-- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check`, MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift) or the install manifest + `npm view codebyplan version` (Step 1.5 consumer drift)
-- **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
+- **Reads**: `.codebyplan/repo.json`, `.codebyplan/git.json` (`branch_config.production` for the Step 1.4 home-branch fast-forward), MCP `get_session_logs` (worktree-filtered, limit 1 — single call shared by Step 4 and Step 4.5), MCP `health_check` (Step 0 hard gate), MCP `get_current_task`, MCP `get_rounds`, MCP `get_checkpoints` (two calls: `{ repo_id, status: 'active' }` for the Step 5.8 ownership partition; `{ repo_id }` unfiltered for the Step 4.5 freshness probe, which may resolve a non-active checkpoint), MCP `get_tasks` / `get_rounds` for the Step 4.5 freshness probe; `scripts/infra-drift.mjs` + a best-effort `git fetch` (Step 1.5 monorepo drift); `npx codebyplan version-status` (Step 1.6 package-freshness gate). Reads at Step 3 and later (session-state, session logs, checkpoints, tasks/rounds) do NOT fire on a Step 0 MCP hard-fail or the Step 1.6 update-and-halt path
+- **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate) — both SKIPPED on a Step 0 MCP hard-fail and on the Step 1.6 update-and-halt path
 - **Spawns**: none
-- **Triggers**: `/cbp-git-commit` (conditional, on user approval), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through when owned_count >= 1 or total_count === 0; STOPS with no trigger when total_count >= 1 AND owned_count === 0)
+- **Triggers**: `/cbp-git-commit` (conditional, on user approval at Step 5.7 or the Step 1.6 update path), `handoff.command` (on fresh handoff hit at Step 4.5), `/cbp-todo` (auto fall-through when owned_count >= 1 or total_count === 0; STOPS with no trigger when total_count >= 1 AND owned_count === 0; NOT triggered on a Step 0 hard-fail or the Step 1.6 update-and-halt path)
 - **Paired with**: `/cbp-session-end`
-- **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + freshness gate contract)
+- **Pairs with**: `/cbp-session-end` Step 1.3 (handoff write-path; the freshness-gate contract is specified inline in Step 4.5 above)