codebyplan 1.10.2 → 1.11.0

package/templates/hooks/cbp-subagent-statusline.py

@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# @hook: NOT-A-HOOK (subagentStatusLine renderer, invoked via the cbp-subagent-statusline.sh dispatcher)
+# Claude Code Subagent Status Line — python renderer. Byte-identical output to the
+# bash renderer in cbp-subagent-statusline.sh and the node renderer in
+# cbp-subagent-statusline.mjs. Output protocol: one {"id":...,"content":...} JSON
+# line per task. See the .sh file for the full option/env/seam contract.
+# Never throws to stdout.
+
+import json
+import math
+import os
+import sys
+import time
+
+
+def main():
+    raw_input = sys.stdin.read()
+    try:
+        data = json.loads(raw_input)
+    except Exception:
+        data = {}
+    if not isinstance(data, dict):
+        data = {}
+
+    root = os.environ.get("CBP_STATUSLINE_ROOT") or (sys.argv[1] if len(sys.argv) > 1 else "")
+    if not root:
+        root = os.path.abspath(os.path.join(os.path.dirname(os.path.abspath(__file__)), "..", ".."))
+
+    try:
+        columns = math.trunc(float(data.get("columns") or 0))
+    except (TypeError, ValueError):
+        columns = 0
+    tasks = data.get("tasks")
+    if not isinstance(tasks, list):
+        tasks = []
+
+    # ---- Config: no_color from statusline.json -------------------------------
+    cfg_no_color = False
+    try:
+        with open(os.path.join(root, ".codebyplan", "statusline.json"), "r", encoding="utf-8") as fh:
+            parsed = json.load(fh)
+        if isinstance(parsed, dict) and isinstance(parsed.get("no_color"), bool):
+            cfg_no_color = parsed["no_color"]
+    except Exception:
+        pass
+
+    no_color = (
+        (os.environ.get("NO_COLOR") not in (None, ""))
+        or os.environ.get("CBP_SUBAGENT_STATUSLINE_NO_COLOR") == "1"
+        or cfg_no_color is True
+    )
+    if no_color:
+        RST = DIM = BOLD = GREEN = RED = BLUE = ""
+    else:
+        RST = "\x1b[0m"
+        DIM = "\x1b[2m"
+        BOLD = "\x1b[1m"
+        GREEN = "\x1b[32m"
+        RED = "\x1b[31m"
+        BLUE = "\x1b[34m"
+
+    def fmt_k(val):
+        v = float(val)
+        if v >= 1000000:
+            t = math.floor((v + 50000) / 100000)
+            return "%d.%dM" % (t // 10, t % 10)
+        elif v >= 1000:
+            t = math.floor((v + 50) / 100)
+            return "%d.%dK" % (t // 10, t % 10)
+        return str(int(v))
+
+    def cbp_now():
+        nv = os.environ.get("CBP_STATUSLINE_NOW")
+        if nv not in (None, ""):
+            return math.trunc(float(nv))
+        return math.floor(time.time())
+
+    def fmt_age_secs(start):
+        delta = cbp_now() - math.trunc(float(start))
+        if delta < 0:
+            delta = 0
+        if delta >= 3600:
+            return "%dh%dm" % (delta // 3600, (delta % 3600) // 60)
+        if delta >= 60:
+            return "%dm%ds" % (delta // 60, delta % 60)
+        return "%ds" % delta
+
+    def is_ascii_letter(b):
+        return (0x41 <= b <= 0x5A) or (0x61 <= b <= 0x7A)
+
+    def truncate(rendered):
+        # ANSI-aware byte-based truncation — mirrors the bash byte walk exactly.
+        if not (columns > 0):
+            return rendered
+        buf = rendered.encode("utf-8")
+        raw_len = len(buf)
+        target = columns - 3
+        if target < 0:
+            target = 0
+        vis = 0
+        i = 0
+        in_esc = False
+        while i < raw_len and vis < target:
+            b = buf[i]
+            if in_esc:
+                if is_ascii_letter(b):
+                    in_esc = False
+            elif b == 0x1B:
+                in_esc = True
+            else:
+                vis += 1
+            i += 1
+        while i < raw_len:
+            b = buf[i]
+            if in_esc:
+                if is_ascii_letter(b):
+                    in_esc = False
+                i += 1
+            elif b == 0x1B:
+                in_esc = True
+                i += 1
+            else:
+                break
+        if i < raw_len:
+            head = buf[:i]
+            tail = (RST + "...").encode("utf-8")
+            return (head + tail).decode("utf-8", errors="replace")
+        return rendered
+
+    out = []
+    for task in tasks:
+        if not isinstance(task, dict):
+            continue
+        t_id = "" if task.get("id") is None else str(task.get("id"))
+        if t_id == "":
+            continue
+        t_name = "" if task.get("name") is None else str(task.get("name"))
+        t_type = "" if task.get("type") is None else str(task.get("type"))
+        t_status = "" if task.get("status") is None else str(task.get("status"))
+        t_desc = "" if task.get("description") is None else str(task.get("description"))
+        try:
+            t_start = math.trunc(float(task.get("startTime") or 0))
+        except (TypeError, ValueError):
+            t_start = 0
+        try:
+            t_tokens = math.trunc(float(task.get("tokenCount") or 0))
+        except (TypeError, ValueError):
+            t_tokens = 0
+
+        if t_status == "running":
+            icon = "%s●%s" % (GREEN, RST)
+        elif t_status == "pending":
+            icon = "%s○%s" % (DIM, RST)
+        elif t_status == "completed":
+            icon = "%s✓%s" % (BLUE, RST)
+        elif t_status == "failed":
+            icon = "%s✗%s" % (RED, RST)
+        else:
+            icon = "%s•%s" % (DIM, RST)
+
+        row = "%s %s%s%s" % (icon, BOLD, t_name, RST)
+        if t_type:
+            row += " %s(%s)%s" % (DIM, t_type, RST)
+        if os.environ.get("CBP_SUBAGENT_STATUSLINE_HIDE_DESCRIPTION") != "1" and t_desc:
+            row += " %s—%s %s" % (DIM, RST, t_desc)
+        if os.environ.get("CBP_SUBAGENT_STATUSLINE_HIDE_TOKENS") != "1" and t_tokens > 0:
+            row += " %s·%s %stokens:%s%s" % (DIM, RST, DIM, RST, fmt_k(t_tokens))
+        if t_start > 0:
+            row += " %s·%s %sage:%s%s" % (DIM, RST, DIM, RST, fmt_age_secs(t_start))
+
+        rendered = truncate(row)
+        out.append(
+            '{"id":%s,"content":%s}'
+            % (json.dumps(t_id, ensure_ascii=False), json.dumps(rendered, ensure_ascii=False))
+        )
+
+    sys.stdout.write(("\n".join(out) + "\n") if out else "")
+
+
+try:
+    main()
+except Exception:
+    sys.exit(0)

package/templates/hooks/cbp-subagent-statusline.sh

@@ -1,22 +1,65 @@
 #!/bin/bash
 # Portability: bash 3.2+ (macOS default /bin/bash). UTF-8 multibyte chars in
 # user-controlled fields are byte-iterated under 3.2 (over-counts visible width
-# for non-ASCII content); acceptable safe-direction approximation.
-# @hook: NOT-A-HOOK (subagentStatusLine renderer, invoked by settings.json subagentStatusLine.command)
-# Claude Code Subagent Status Line — one JSON line per active subagent
-# Purpose: Renders one row per running subagent. Output protocol per upstream docs:
+# for non-ASCII content); acceptable safe-direction approximation — and the node
+# (.mjs) / python (.py) renderers iterate the SAME UTF-8 bytes so all three agree.
+# @hook: NOT-A-HOOK (subagentStatusLine renderer, invoked via settings.json subagentStatusLine.command)
+# Claude Code Subagent Status Line — multi-runtime dispatcher + bash renderer.
+# One JSON line per active subagent. Output protocol per upstream docs:
 #   {"id": "<task_id>", "content": "<rendered_body>"}
 #   - Omitted tasks keep their default Claude Code rendering
 #   - Empty content strings hide the row
 # NOT a PreToolUse/PostToolUse/Notification hook — do NOT register in hooks[].
 #
-# ENV-VAR TOGGLES — set to 1 to suppress a column / color
+# RENDERER SELECTION (per-device, gitignored .codebyplan/statusline.local.json):
+#   { "renderer": "bash" | "node" | "python" }  — default bash, falls back to bash
+#   when the chosen runtime is unavailable. Set via `codebyplan statusline …`.
+#
+# CONFIG: honours `no_color` from the committed .codebyplan/statusline.json. The six
+#   main-statusline line toggles do NOT apply to subagent rows.
+#
+# ENV-VAR OVERRIDES (env > config > default)
 #   CBP_SUBAGENT_STATUSLINE_HIDE_DESCRIPTION=1   omit DESCRIPTION segment
 #   CBP_SUBAGENT_STATUSLINE_HIDE_TOKENS=1        omit tokens:N segment
 #   CBP_SUBAGENT_STATUSLINE_NO_COLOR=1           strip all ANSI codes (also honoured by $NO_COLOR)
+#
+# TEST SEAMS (no effect in normal use)
+#   CBP_STATUSLINE_ROOT=<dir>   override the .codebyplan/ lookup root (default: repo root)
+#   CBP_STATUSLINE_NOW=<epoch>  override "now" for age rendering (determinism)
+
+# ============================================================
+# DISPATCHER — resolve root + renderer, delegate when possible
+# ============================================================
+CBP_HOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd 2>/dev/null)" || CBP_HOOK_DIR="."
+CBP_ROOT="${CBP_STATUSLINE_ROOT:-}"
+if [ -z "$CBP_ROOT" ]; then
+  CBP_ROOT="$(cd "$CBP_HOOK_DIR/../.." && pwd 2>/dev/null)" || CBP_ROOT="$PWD"
+fi
+
+CBP_RENDERER="bash"
+CBP_LOCAL_CFG="$CBP_ROOT/.codebyplan/statusline.local.json"
+if [ -f "$CBP_LOCAL_CFG" ] && command -v jq >/dev/null 2>&1; then
+  _r="$(jq -r '.renderer // empty' "$CBP_LOCAL_CFG" 2>/dev/null)"
+  case "$_r" in bash|node|python) CBP_RENDERER="$_r" ;; esac
+fi
+
+if [ "$CBP_RENDERER" = "node" ] && command -v node >/dev/null 2>&1 \
+   && [ -f "$CBP_HOOK_DIR/cbp-subagent-statusline.mjs" ]; then
+  CBP_STATUSLINE_ROOT="$CBP_ROOT" exec node "$CBP_HOOK_DIR/cbp-subagent-statusline.mjs"
+fi
+if [ "$CBP_RENDERER" = "python" ] && command -v python3 >/dev/null 2>&1 \
+   && [ -f "$CBP_HOOK_DIR/cbp-subagent-statusline.py" ]; then
+  CBP_STATUSLINE_ROOT="$CBP_ROOT" exec python3 "$CBP_HOOK_DIR/cbp-subagent-statusline.py"
+fi
+# Fall through → inline bash renderer (default + universal fallback).
 
 INPUT=$(cat)
 
+# Byte-deterministic string ops: force the C locale so the truncation walk below
+# counts UTF-8 BYTES (locale-independent), matching the .mjs/.py byte iteration.
+# Output bytes are unaffected (multibyte content passes through verbatim).
+export LC_ALL=C
+
 # One jq pass for base fields (cwd, session_id, columns)
 eval "$(echo "$INPUT" | jq -r '
   @sh "CWD=\(.cwd // "")",
@@ -24,9 +67,17 @@ eval "$(echo "$INPUT" | jq -r '
   @sh "COLUMNS=\(.columns // 0)"
 ')"
 
-# ---- Colour setup ----------------------------------------------------------
+# ---- Config: no_color from .codebyplan/statusline.json -----------------------
+CFG_NO_COLOR=false
+CBP_CFG="$CBP_ROOT/.codebyplan/statusline.json"
+if [ -f "$CBP_CFG" ] && command -v jq >/dev/null 2>&1; then
+  # `== true` (NOT jq `//`): only an explicit true enables no_color.
+  eval "$(jq -r '"CFG_NO_COLOR=\(.no_color == true)"' "$CBP_CFG" 2>/dev/null)"
+fi
+
+# ---- Colour setup (env > config) ---------------------------------------------
 # Only the colours referenced by the render block below are defined here.
-if [ -n "${NO_COLOR:-}" ] || [ "${CBP_SUBAGENT_STATUSLINE_NO_COLOR:-0}" = "1" ]; then
+if [ -n "${NO_COLOR:-}" ] || [ "${CBP_SUBAGENT_STATUSLINE_NO_COLOR:-0}" = "1" ] || [ "$CFG_NO_COLOR" = "true" ]; then
   RST=''; DIM=''; BOLD=''; GREEN=''; RED=''; BLUE=''
 else
   RST='\033[0m'
@@ -37,25 +88,29 @@ else
   BLUE='\033[34m'
 fi
 
-# ---- Token/size formatter K / M (verbatim from cbp-statusline.sh L96-105) ---
+# ---- Token/size formatter K / M — integer round-half-up (cross-runtime) ------
 fmt_k() {
   local val=$1
   if [ "$val" -ge 1000000 ] 2>/dev/null; then
-    printf "%.1fM" "$(echo "$val / 1000000" | bc -l)"
+    local t=$(( (val + 50000) / 100000 ))
+    printf "%d.%dM" $(( t / 10 )) $(( t % 10 ))
   elif [ "$val" -ge 1000 ] 2>/dev/null; then
-    printf "%.1fK" "$(echo "$val / 1000" | bc -l)"
+    local t=$(( (val + 50) / 100 ))
+    printf "%d.%dK" $(( t / 10 )) $(( t % 10 ))
   else
     printf "%d" "$val"
   fi
 }
 
-# ---- Age formatter: epoch seconds → "Xs" / "XmYs" / "XhYm" -----------------
-# NEW helper — cannot reuse fmt_dur (which divides by 1000 for ms input).
-# startTime is a Unix epoch in seconds, same as rate_limits.*.resets_at.
+# ---- "now" with test seam ----------------------------------------------------
+cbp_now() {
+  if [ -n "${CBP_STATUSLINE_NOW:-}" ]; then printf '%s' "$CBP_STATUSLINE_NOW"; else date +%s; fi
+}
+
+# ---- Age formatter: epoch seconds → "Xs" / "XmYs" / "XhYm" ------------------
 fmt_age_secs() {
   local start=$1
-  local now
-  now=$(date +%s)
+  local now; now=$(cbp_now)
   local delta=$(( now - start ))
   [ "$delta" -lt 0 ] && delta=0
   if [ "$delta" -ge 3600 ]; then
@@ -67,18 +122,16 @@ fmt_age_secs() {
   fi
 }
 
-# ---- Strip ANSI codes for visible-length measurement (column truncation) ----
-strip_ansi() {
-  printf '%s' "$1" | sed $'s/\033\\[[0-9;]*m//g'
-}
-
 # ---- JSON-string-escape a bash variable (embed in {"id":..., "content":...}) -
 json_escape() {
   printf '%s' "$1" | jq -Rs '.'
 }
 
-# ---- Per-task render: one jq TSV emission, looped in bash ------------------
-# Single jq pass for tasks[] (locked decision #3 — two jq calls total).
+# ---- Per-task render: one jq US-delimited emission, looped in bash ----------
+# Join with the Unit Separator (U+001F, non-whitespace) rather than @tsv: a tab is
+# IFS-whitespace, so `IFS=$'\t' read` collapses consecutive tabs and an EMPTY field
+# (e.g. blank description) would shift every later field. US is non-whitespace, so
+# empty fields are preserved — matching the .mjs/.py object iteration.
 echo "$INPUT" | jq -r '
   .tasks // [] | .[] | [
     .id // "",
@@ -88,8 +141,8 @@ echo "$INPUT" | jq -r '
     .description // "",
     (.startTime // 0 | tostring),
     (.tokenCount // 0 | tostring)
-  ] | @tsv
-' | while IFS=$'\t' read -r T_ID T_NAME T_TYPE T_STATUS T_DESC T_START T_TOKENS; do
+  ] | join("\u001f")
+' | while IFS=$'\037' read -r T_ID T_NAME T_TYPE T_STATUS T_DESC T_START T_TOKENS; do
   # Skip blank rows (empty tasks[] → no output)
   [ -z "$T_ID" ] && continue
 
@@ -123,14 +176,12 @@ echo "$INPUT" | jq -r '
   # Apply printf to interpret escape sequences, then truncate to $COLUMNS
   RENDERED=$(printf '%b' "$ROW")
   if [ "$COLUMNS" -gt 0 ] 2>/dev/null; then
-    # ANSI-aware iterative truncation: walk RENDERED char-by-char treating
-    # \033[...letter escape sequences as zero-width and ordinary chars as
+    # ANSI-aware iterative truncation: walk RENDERED byte-by-byte treating
+    # \033[...letter escape sequences as zero-width and ordinary bytes as
     # one-width. Stop when the visible counter reaches COLUMNS - 3, then
-    # append RST + ellipsis. Correct under any ANSI-density distribution,
-    # unlike a single OVERHEAD-add formula which assumes uniform spread.
-    # Pure bash (no awk/perl subprocess); byte-based slicing means non-ASCII
-    # multi-byte UTF-8 in user-controlled descriptions counts as multiple
-    # visible units — acceptable approximation for the ASCII-dominant case.
+    # append RST + ellipsis. Byte-based slicing means non-ASCII multi-byte
+    # UTF-8 counts as multiple visible units — the .mjs/.py renderers iterate
+    # the same UTF-8 bytes, so all three stay byte-identical.
     TARGET=$(( COLUMNS - 3 ))
     [ "$TARGET" -lt 0 ] && TARGET=0
     RAW_LEN=${#RENDERED}
@@ -150,12 +201,11 @@ echo "$INPUT" | jq -r '
       fi
       i=$(( i + 1 ))
     done
-    # Post-loop drain: every rendered row ends with a trailing ${RST} from the
-    # last segment. Without this drain, a row whose visible content fits within
-    # COLUMNS still has `i < RAW_LEN` (pointing inside the trailing reset),
-    # which would spuriously trigger truncation. Walk past any in-progress
-    # escape and any further escape sequences until we hit a real visible byte
-    # or end-of-string.
+    # Post-loop drain: every rendered row ends with a trailing ${RST}. Without
+    # this drain a row whose visible content fits within COLUMNS still has
+    # `i < RAW_LEN` (pointing inside the trailing reset), spuriously triggering
+    # truncation. Walk past any in-progress escape and any further escapes until
+    # a real visible byte or end-of-string.
     while [ $i -lt $RAW_LEN ]; do
       ch="${RENDERED:$i:1}"
       if [ "$in_esc" = "1" ]; then
@@ -171,8 +221,6 @@ echo "$INPUT" | jq -r '
       fi
     done
     if [ $i -lt $RAW_LEN ]; then
-      # printf '%b' converts the literal-text RST (`\033[0m`) into an actual
-      # ESC byte sequence, matching the byte semantics of RENDERED's prefix.
       RENDERED="${RENDERED:0:$i}$(printf '%b' "$RST")..."
     fi
   fi

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

@@ -12,7 +12,7 @@ Activate the session, open a fresh session log, and surface the previous log's p
 
 ## Instructions
 
-Do Steps 0–5 and Step 4.5 silently (no intermediate output). Step 1.4 may surface a one-line fast-forward note or warning, and Step 5.7 may surface an approval gate. Produce ONE output block at Step 6, then auto-trigger `/cbp-todo`.
+Run Steps 0 through 5.8 silently (no intermediate output) — except Step 1.4 may surface a one-line fast-forward note or warning, and Step 5.7 may surface an approval gate. (Step numbers are organizational labels; execution order is 0 → 1 → 1.4 → 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.
 
 ### Step 0: MCP Health Check
 
@@ -40,15 +40,19 @@ Read per-concern config files from the project root. Single load point for the s
 - `server_port`, `server_type`, `auto_push_enabled` — from `.codebyplan/server.json`
 - `git_branch` — from `.codebyplan/git.json`
 
-Resolve `worktree_id` at runtime (CHK-108: never read from `.codebyplan/repo.json`):
+Resolve `worktree_id` at runtime using the structured JSON form:
 
 ```bash
-WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+RESOLVE_JSON=$(npx codebyplan resolve-worktree --json)
+# → {"worktree_id":"<uuid>|null","error_kind":null|"<kind>"}
 ```
 
-Pass `WORKTREE_ID` to MCP tools that support it. Empty output means the (device, path, branch) tuple is unregistered — see fallback note below.
+Extract `worktree_id` and `error_kind` from the JSON output.
 
-**If `worktree_id` resolves to empty** (the (device, path, branch) tuple does not match any registered worktree row): the session continues, but downstream MCP calls treat this caller as untagged — every hard-lock pre-guard sees a NULL `caller_worktree_id` and may reject mutations on assigned rows. Surface a one-line note in the Step 6 output instructing the user to run `npx codebyplan setup` from this directory to register the worktree.
+- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed normally; downstream hard-lock pre-guards may reject mutations on assigned rows).
+- `error_kind` is `local_config_read_failed`, `local_config_write_failed`, `legacy_file_blocks_dir`, `api_failed`, `git_failed`, or `unhandled` → **broken local state**. Hold the `error_kind` for Step 6 to display as a distress warning. Session continues (non-blocking — unlike `/cbp-todo`, session-start does NOT hard-stop on a non-tuple-miss distress).
+
+Pass `WORKTREE_ID` to MCP tools that support it. Null `WORKTREE_ID` means the (device, path, branch) tuple is unregistered — note this for Step 6.
 
 ### Step 1.4: Home-Branch Fast-Forward
 
@@ -123,6 +127,7 @@ Probe the most-recent closed session log for a structured handoff payload (per `
      - `round_id` → `get_rounds({ task_id: handoff.context.task_id })` → find entry where `entry.id === handoff.context.round_id`
        Then compare `entry.updated_at > handoff.captured_at` → stale on any inequality.
    - Entity lookup fails OR the matching `id` is not present in the returned array → stale (referenced entity gone or moved out of reach).
+   - `handoff.context.checkpoint_id` resolves to a checkpoint whose `worktree_id` is non-null AND (caller `WORKTREE_ID` is `null` OR differs from `checkpoint.worktree_id`) → stale (a fresh handoff for another worktree's work — or for assigned work this caller cannot confirm ownership of — must not auto-resume here). Mirrors the cbp-todo Step 1.5 ownership rule.
 4. **On stale OR any defensive gate hit**: fall through silently to Step 7 (existing `/cbp-todo` trigger).
 5. **On fresh hit**: trigger `handoff.command` directly with `handoff.context` / `handoff.state` in the trigger arguments. The downstream skill self-loads its full context — do NOT duplicate `/cbp-todo` Step 2's context-loading matrix here. Skip Step 5.7, Step 6 output, and Step 7.
 
@@ -152,27 +157,50 @@ Clean the working tree of leftover infra before the session begins. Only commit
 
 Non-blocking — session start proceeds either way.
 
+### Step 5.8: Resolve Ownership
+
+Call MCP `get_checkpoints({ repo_id, status: 'active' })`. Partition results into:
+
+- `owned[]` — entries where `checkpoint.worktree_id === WORKTREE_ID`, OR both are `null`
+- `cross_worktree[]` — entries where `checkpoint.worktree_id` is non-null AND differs from `WORKTREE_ID` (includes the case where caller `WORKTREE_ID` is `null` but the target has a non-null `worktree_id`)
+
+Hold `owned_count = owned.length`, `total_count = owned.length + cross_worktree.length`, `owned_names` (CHK-NNN + title for each owned entry), and `cross_names` (CHK-NNN + name for each cross-worktree entry). These values are consumed by Step 6 and Step 7 — single MCP call, no duplicate round-trips.
+
 ### Step 6: Output
 
 ```
-Session active | Worktree: [worktree_id or "main"]
+Session active | Worktree: [worktree_id or "unregistered"]
+
+[⚠ resolve-worktree: <error_kind> — local state is broken; routing may be unreliable. Run `npx codebyplan setup` to repair. — only when error_kind is non-null and not tuple_miss]
 
 Previous session: [title or "none"]
   Pending: [pending items from previous log, or "—"]
 
+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]
 ```
 
-### Step 7: Auto-trigger Todo
+READ-ONLY — this block never proposes reassignment, release, or lock transfer of cross-worktree checkpoints.
+
+### Step 7: Auto-trigger
+
+Three-branch gate using `owned_count` and `total_count` from Step 5.8:
 
-Trigger `/cbp-todo` to determine what to work on.
+- **`owned_count >= 1`**: trigger `/cbp-todo` (owns active work — proceed as today).
+- **`total_count >= 1` AND `owned_count === 0`**: **STOP** — do NOT auto-trigger `/cbp-todo`. The Ownership block shown in Step 6 already communicates the situation; the user must switch to the owning worktree or start new work explicitly.
+- **`total_count === 0`** (no active checkpoints anywhere): trigger `/cbp-todo` (idle path — leads to checkpoint-create or session-end).
 
 ## Integration
 
 - **Triggered by**: user invocation, `/clear` recovery
-- **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` / `get_tasks` / `get_rounds` for freshness probe (Step 4.5)
+- **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
 - **Writes**: MCP `create_session_log` (new, possibly empty), MCP `update_session_state` (activate)
 - **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)
+- **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)
 - **Paired with**: `/cbp-session-end`
 - **Pairs with**: `.claude/rules/session-resume.md` (handoff payload shape + freshness gate contract)

package/templates/skills/cbp-session-start/qa-regression.md

@@ -0,0 +1,51 @@
+---
+scope: org-shared
+name: cbp-session-start-qa-regression
+description: Manual regression procedure for the cbp-session-start worktree-ownership awareness + resolve-worktree distress channel (CHK-137 TASK-3)
+---
+
+# cbp-session-start — Worktree-Ownership Regression
+
+Manual procedure verifying that `/cbp-session-start` correctly resolves the caller's worktree identity, gates Step 7 auto-trigger on ownership, and surfaces distress signals non-blocking. No automated harness exists for markdown skills; run these by hand (or exercise the MCP calls directly) whenever Step 1, Step 4.5, Step 5.8, Step 6, or Step 7 of `SKILL.md` changes.
+
+Repo under test: `2ff6d405-39c5-47b8-a6d1-59f998ac0537`.
+
+## Preconditions
+
+- Step 1 uses `resolve-worktree --json` (not the legacy `2>/dev/null` form) — confirm with `grep -n 'resolve-worktree' SKILL.md` → line contains `--json`.
+- Step 5.8 calls `get_checkpoints({ repo_id, status: 'active' })` — confirm no Step 7 auto-trigger bypasses this gate.
+- Step 6 Ownership block is READ-ONLY — confirm no "reassign", "release_assignment", or "transfer" language appears in SKILL.md: `grep -n 'reassign\|release_assignment\|transfer' SKILL.md` → no hits.
+- Step 4.5 freshness gate includes the cross-worktree stale bullet (checkpoint `worktree_id` non-null and differs from caller).
+
+## Scenario A — caller owns an active CHK → auto-trigger
+
+1. Run from a worktree whose `WORKTREE_ID` matches the active checkpoint's `worktree_id` (or both are `null`).
+2. `get_checkpoints({ repo_id, status: 'active' })` returns at least one entry whose `worktree_id === WORKTREE_ID` (or both null).
+3. **Expected**: Step 5.8 sets `owned_count >= 1`. Step 6 shows `Ownership: N active CHK(s), N owned by this worktree`. Step 7 first branch fires: `/cbp-todo` is auto-triggered.
+
+## Scenario B — active CHK(s) exist but none owned by caller → Ownership block + STOP
+
+Repro: caller worktree is `codebyplan-claude-2` (`38cd7dfa`). The only active checkpoint is CHK-136, assigned to `codebyplan-cli` (`016bd7f2`).
+
+1. `resolve-worktree --json` returns `{"worktree_id":"38cd7dfa-...","error_kind":null}`.
+2. `get_checkpoints({ repo_id, status: 'active' })` returns CHK-136 with `worktree_id = "016bd7f2-..."`.
+3. Step 5.8: `owned_count = 0`, `total_count = 1`, `cross_worktree = [CHK-136]`.
+4. **Expected**: Step 6 shows `Ownership: 1 active CHK(s), 0 owned by this worktree` and `[Cross-worktree: CHK-136 (…)]`. Step 7 second branch fires: Ownership block is displayed (already in Step 6) and skill **STOPS** — `/cbp-todo` is NOT auto-triggered. No reassignment language appears.
+
+## Scenario C — no active CHKs anywhere → idle /cbp-todo trigger
+
+1. `get_checkpoints({ repo_id, status: 'active' })` returns `[]`.
+2. Step 5.8: `owned_count = 0`, `total_count = 0`.
+3. **Expected**: Step 6 shows `Ownership: 0 active CHK(s), 0 owned by this worktree`. Step 7 third branch fires: `/cbp-todo` is auto-triggered (idle path → checkpoint-create or session-end suggestion).
+
+## Scenario D — cross-worktree handoff → Step 4.5 marks stale, falls through
+
+1. The most-recent closed session log contains a handoff payload whose `context.checkpoint_id` resolves to a checkpoint with `worktree_id = "016bd7f2-..."` (a different worktree).
+2. Caller `WORKTREE_ID = "38cd7dfa-..."`.
+3. **Expected**: Step 4.5 freshness gate hits the cross-worktree stale bullet (`checkpoint.worktree_id` non-null AND differs from caller) → marks stale → falls through silently to Step 7. The mismatched handoff is NOT auto-resumed. Ownership output from Step 5.8 / Step 6 / Step 7 proceeds normally.
+
+## Scenario E — resolver distress (non-tuple-miss) → warning line above Ownership block, session proceeds
+
+1. `resolve-worktree --json` returns `{"worktree_id":null,"error_kind":"local_config_read_failed"}` (or any other non-null, non-tuple-miss `error_kind`).
+2. **Expected**: Step 1 holds the `error_kind`; session continues (non-blocking). Step 6 surfaces `⚠ resolve-worktree: local_config_read_failed — local state is broken; routing may be unreliable. Run \`npx codebyplan setup\` to repair.` ABOVE the Ownership block. All subsequent steps still run (Steps 2–5.8). Step 7 proceeds per the `owned_count`/`total_count` values from Step 5.8 as normal — the skill does NOT hard-stop the way `/cbp-todo` does on the same distress kinds.
+3. **Compound case** (distress typically leaves `WORKTREE_ID` null): Step 5.8 then classifies every checkpoint with a non-null `worktree_id` as `cross_worktree[]` (only truly-null-`worktree_id` checkpoints land in `owned[]`). So if all active checkpoints are assigned, `owned_count = 0` and Step 7's second branch STOPS — the distress warning + Ownership block are the only output. The session log created in Step 5 records `worktree_id: null` (the resolver could not read local state); this is expected, not a failure.