codebyplan 1.13.8 → 1.13.10

package/package.json

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

package/templates/hooks/cbp-mcp-round-sync.sh

@@ -12,6 +12,14 @@
 #   - Web-UI flag (app_file_approval_by_user) consumption + reset
 #   - Writes both PATCH /api/rounds/${ROUND_ID} and PATCH /api/tasks/${TASK_ID}
 #
+# Caller worktree identity:
+#   The CLI auto-resolves caller_worktree_id (override flag → cache →
+#   in-process tuple API) and hard-fails with exit 1 if it cannot resolve
+#   on the write path. This hook resolves the worktree id before invoking the
+#   CLI and passes it via --caller-worktree-id so the server can honor the
+#   feat-worktree lock. The hook itself stays non-fatal (exits 0) and surfaces
+#   the CLI's stderr output to the user.
+#
 # Flags:
 #   --dry-run  Pass through to CLI (prints merged payload, no API writes).
 #              Used by fixture-based smoke tests.
@@ -67,11 +75,19 @@ if [ -z "$TASK_ID" ]; then
   exit 0
 fi
 
+# Resolve worktree id before invoking the CLI so the server can honor the
+# feat-worktree lock. On miss (unregistered worktree) the CLI falls back to
+# its in-process resolve and hard-fails with guidance if still unresolved.
+WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+
 # Delegate to the codebyplan CLI (single source of truth for merge semantics)
 CMD_ARGS=("round" "sync-approvals" "--round-id" "$ROUND_ID" "--task-id" "$TASK_ID")
+if [ -n "$WORKTREE_ID" ]; then
+  CMD_ARGS+=("--caller-worktree-id" "$WORKTREE_ID")
+fi
 [ "$DRY_RUN" = "true" ] && CMD_ARGS+=("--dry-run")
 
-if npx codebyplan "${CMD_ARGS[@]}" 2>&1; then
+if npx codebyplan "${CMD_ARGS[@]}"; then
   echo "cbp-mcp-round-sync: synced via CLI for round ${ROUND_ID}" >&2
 else
   echo "cbp-mcp-round-sync: CLI sync failed for round ${ROUND_ID} (non-fatal)" >&2

package/templates/settings.project.base.json

@@ -181,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-git-worktree-create/SKILL.md

@@ -196,7 +196,7 @@ echo '{}' > "$WORKTREE_PATH/.codebyplan/shipment.json"
 echo '{}' > "$WORKTREE_PATH/.codebyplan/vendor.json"
 ```
 
-The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never persisted in any of these files — it is resolved at runtime via `npx codebyplan resolve-worktree` based on the device_id, filesystem path, and current git branch.
+The `.codebyplan/device.local.json` file is created by `npx codebyplan setup` on the device (gitignored). The `worktree_id` is never COMMITTED; it may be cached per-device in the gitignored `.codebyplan/worktree.local.json` (branch-keyed, re-derivable via `codebyplan resolve-worktree --cache`), otherwise resolved at runtime from the `(device_id, repo path, branch)` tuple via `npx codebyplan resolve-worktree`.
 
 No need to mark as `skip-worktree` — the committed files are merge-safe per CHK-108 and CHK-120.
 

package/templates/skills/cbp-round-update/SKILL.md

@@ -69,7 +69,20 @@ Run:
 npx codebyplan round sync-approvals --round-id <round_id> --task-id <task_id>
 ```
 
-The CLI auto-resolves the worktree id, parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task.
+The CLI auto-resolves the caller worktree id with the following precedence:
+1. `--caller-worktree-id <uuid>` override (if passed — skips all resolution)
+2. Per-device branch-keyed cache (`.codebyplan/worktree.local.json`)
+3. In-process tuple API call: `POST /worktrees/resolve` using `(device_id, repo_path, branch)`
+
+On the write path (non `--dry-run`), if the worktree id cannot be resolved the CLI **hard-fails with exit 1** and prints an actionable message. To pre-populate the cache:
+
+```
+npx codebyplan resolve-worktree --cache
+```
+
+If this worktree is not yet registered, run `npx codebyplan setup` first, then re-run `/cbp-round-update`.
+
+The CLI parses `git status --short`, merges drift + staging + web-UI flag, and writes both round and task (forwarding `caller_worktree_id` on both writes so the server honors the feat-worktree lock).
 
 Read the stdout JSON: `{ added, stale_marked, reactivated, total_files }`.
 

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)