codebyplan 1.10.2 → 1.10.3

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.10.2";
+    VERSION = "1.10.3";
     PACKAGE_NAME = "codebyplan";
   }
 });
@@ -22,13 +22,16 @@ var init_version = __esm({
 // src/lib/local-config.ts
 import { execSync } from "node:child_process";
 import { createHash } from "node:crypto";
-import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { mkdir, readFile, stat, writeFile } from "node:fs/promises";
 import { hostname } from "node:os";
 import { dirname, join } from "node:path";
 function localConfigPath(projectPath) {
   return join(projectPath, ".codebyplan", "device.local.json");
 }
-async function readLocalConfig(projectPath) {
+function legacyLocalConfigPath(projectPath) {
+  return join(projectPath, ".codebyplan.local.json");
+}
+async function readLocalConfig(projectPath, onMigrationNotice) {
   try {
     const raw = await readFile(localConfigPath(projectPath), "utf-8");
     const parsed = JSON.parse(raw);
@@ -38,22 +41,81 @@ async function readLocalConfig(projectPath) {
     console.error("Failed to read local config: invalid shape");
     return null;
   } catch (err) {
-    console.error(
-      `Failed to read local config: ${err instanceof Error ? err.message : String(err)}`
-    );
+    const code = err.code;
+    if (code === "ENOENT") {
+    } else if (code === "ENOTDIR") {
+      try {
+        const dirPath = dirname(localConfigPath(projectPath));
+        const st = await stat(dirPath);
+        if (!st.isDirectory()) {
+          throw Object.assign(
+            new Error(`${dirPath} is a file, expected directory`),
+            { code: "LEGACY_FILE_BLOCKS_DIR" }
+          );
+        }
+      } catch (statErr) {
+        if (statErr.code === "LEGACY_FILE_BLOCKS_DIR")
+          throw statErr;
+      }
+      throw err;
+    } else if (typeof code === "string") {
+      throw err;
+    } else {
+      console.error(
+        `Failed to read local config: ${err instanceof Error ? err.message : String(err)}`
+      );
+      return null;
+    }
+  }
+  try {
+    const raw = await readFile(legacyLocalConfigPath(projectPath), "utf-8");
+    const parsed = JSON.parse(raw);
+    if (typeof parsed === "object" && parsed !== null && !Array.isArray(parsed) && typeof parsed.device_id === "string") {
+      onMigrationNotice?.(
+        legacyLocalConfigPath(projectPath),
+        localConfigPath(projectPath)
+      );
+      return parsed;
+    }
     return null;
+  } catch (err) {
+    const code = err.code;
+    if (code === "ENOENT") {
+      return null;
+    }
+    throw err;
   }
 }
 async function writeLocalConfig(projectPath, config) {
   const content = { device_id: config.device_id };
   const path6 = localConfigPath(projectPath);
+  const dirPath = dirname(path6);
+  let phase = "stat config directory";
   try {
-    await mkdir(dirname(path6), { recursive: true });
+    try {
+      const st = await stat(dirPath);
+      if (!st.isDirectory()) {
+        const err = Object.assign(
+          new Error(`${dirPath} is a file, expected directory`),
+          { code: "LEGACY_FILE_BLOCKS_DIR" }
+        );
+        throw err;
+      }
+    } catch (statErr) {
+      const code = statErr.code;
+      if (code === "LEGACY_FILE_BLOCKS_DIR") throw statErr;
+      if (code !== "ENOENT") throw statErr;
+    }
+    phase = "create config directory";
+    await mkdir(dirPath, { recursive: true });
+    phase = "write local config";
     await writeFile(path6, JSON.stringify(content, null, 2) + "\n", "utf-8");
   } catch (err) {
-    console.error(
-      `Failed to write local config: ${err instanceof Error ? err.message : String(err)}`
-    );
+    const code = err.code;
+    if (code === "LEGACY_FILE_BLOCKS_DIR") {
+      throw err;
+    }
+    console.error(`Failed to ${phase}: ${err.message}`);
     throw err;
   }
 }
@@ -73,8 +135,8 @@ async function resolveMachineSeed() {
   }
   return hostname();
 }
-async function getOrCreateDeviceId(projectPath) {
-  const existing = await readLocalConfig(projectPath);
+async function getOrCreateDeviceId(projectPath, onMigrationNotice) {
+  const existing = await readLocalConfig(projectPath, onMigrationNotice);
   if (existing?.device_id) {
     return existing.device_id;
   }
@@ -561,7 +623,8 @@ async function resolveAndCacheWorktreeId(repoId, projectPath, options) {
 async function resolveWorktreeByBranch({
   repoId,
   deviceId,
-  branch
+  branch,
+  onError
 }) {
   if (!deviceId || !branch) {
     return null;
@@ -588,6 +651,10 @@ async function resolveWorktreeByBranch({
     console.warn(
       `Worktree self-heal skipped (non-fatal): branch worktree resolve failed: ${err instanceof Error ? err.message : String(err)}. Continuing.`
     );
+    onError?.(
+      "api_failed",
+      err instanceof Error ? err : new Error(String(err))
+    );
     return null;
   }
 }
@@ -595,7 +662,8 @@ async function resolveWorktreeId({
   repoId,
   repoPath,
   branch,
-  deviceId
+  deviceId,
+  onError
 }) {
   try {
     const res = await apiPost(
@@ -607,6 +675,10 @@ async function resolveWorktreeId({
     console.warn(
       `Worktree self-heal skipped (non-fatal): ${err instanceof Error ? err.message : String(err)}. Continuing \u2014 run \`codebyplan config\` again later to retry.`
     );
+    onError?.(
+      "api_failed",
+      err instanceof Error ? err : new Error(String(err))
+    );
     return null;
   }
 }
@@ -3806,63 +3878,145 @@ var init_ship2 = __esm({
 // src/cli/resolve-worktree.ts
 var resolve_worktree_exports = {};
 __export(resolve_worktree_exports, {
+  ProcessExitSignal: () => ProcessExitSignal,
   runResolveWorktree: () => runResolveWorktree
 });
 import { execSync as execSync5 } from "node:child_process";
+function distress(kind, message, jsonMode) {
+  if (jsonMode) return;
+  process.stderr.write(`resolve-worktree: ${kind}: ${message}
+`);
+}
 async function runResolveWorktree() {
+  const jsonMode = hasFlag("json", 3);
+  let errorContext = null;
+  const migrationNoticeCallback = (legacyPath, primaryPath) => {
+    if (!jsonMode) {
+      process.stderr.write(
+        `resolve-worktree: local_config_migration: ${legacyPath} is the legacy flat config; move device_id to ${primaryPath}
+`
+      );
+    }
+  };
   try {
     const projectPath = process.cwd();
     const found = await findCodebyplanConfig(projectPath);
     if (!found?.contents.repo_id) {
-      process.exit(0);
+      emitAndExit(null, null, jsonMode);
     }
     const repoId = found.contents.repo_id;
-    const deviceId = await getOrCreateDeviceId(projectPath);
+    try {
+      await readLocalConfig(projectPath);
+    } catch (readErr) {
+      const readErrCode = readErr.code;
+      errorContext = {
+        kind: readErrCode === "LEGACY_FILE_BLOCKS_DIR" ? "legacy_file_blocks_dir" : "local_config_read_failed",
+        message: readErr instanceof Error ? readErr.message : String(readErr)
+      };
+    }
+    let deviceId;
+    try {
+      deviceId = await getOrCreateDeviceId(
+        projectPath,
+        migrationNoticeCallback
+      );
+    } catch (deviceErr) {
+      const code = deviceErr.code;
+      if (code === "LEGACY_FILE_BLOCKS_DIR") {
+        errorContext = {
+          kind: "legacy_file_blocks_dir",
+          message: deviceErr instanceof Error ? deviceErr.message : String(deviceErr)
+        };
+      } else if (errorContext === null || errorContext.kind !== "local_config_read_failed" && errorContext.kind !== "legacy_file_blocks_dir") {
+        errorContext = {
+          kind: "local_config_write_failed",
+          message: deviceErr instanceof Error ? deviceErr.message : String(deviceErr)
+        };
+      }
+      emitAndExit(null, errorContext, jsonMode);
+    }
     let branch = "";
     try {
       branch = execSync5("git symbolic-ref --short HEAD", {
         cwd: projectPath,
         encoding: "utf-8"
       }).trim();
-    } catch {
+    } catch (gitErr) {
+      if (errorContext === null) {
+        errorContext = {
+          kind: "git_failed",
+          message: gitErr instanceof Error ? gitErr.message : String(gitErr)
+        };
+      }
     }
+    const onResolverError = (kind, err) => {
+      if (errorContext === null) {
+        errorContext = { kind, message: err.message };
+      }
+    };
     const worktreeId = await resolveWorktreeId({
       repoId,
       repoPath: projectPath,
       branch,
-      deviceId
+      deviceId,
+      onError: onResolverError
     });
     if (worktreeId) {
-      process.stdout.write(worktreeId);
-      process.exit(0);
+      emitAndExit(worktreeId, errorContext, jsonMode);
     }
     const useFallback = hasFlag("fallback-from-branch", 3);
     if (useFallback) {
       const fallbackId = await resolveWorktreeByBranch({
         repoId,
         deviceId,
-        branch
+        branch,
+        onError: onResolverError
       });
       if (fallbackId) {
-        process.stdout.write(fallbackId);
+        emitAndExit(fallbackId, errorContext, jsonMode);
       }
     }
-    process.exit(0);
+    emitAndExit(null, errorContext, jsonMode);
   } catch (err) {
-    if (process.env.CODEBYPLAN_DEBUG === "1") {
-      const msg = err instanceof Error ? err.message : String(err);
-      process.stderr.write(`resolve-worktree: ${msg}
-`);
+    if (err instanceof ProcessExitSignal) throw err;
+    const msg = err instanceof Error ? err.message : String(err);
+    errorContext = { kind: "unhandled", message: msg };
+    emitAndExit(null, errorContext, jsonMode);
+  }
+}
+function emitAndExit(worktreeId, errorContext, jsonMode) {
+  if (jsonMode) {
+    const errorKind = errorContext?.kind ?? (worktreeId === null ? "tuple_miss" : null);
+    process.stdout.write(
+      JSON.stringify({ worktree_id: worktreeId, error_kind: errorKind }) + "\n"
+    );
+  } else {
+    if (worktreeId !== null) {
+      process.stdout.write(worktreeId);
+    }
+    if (errorContext !== null) {
+      if (errorContext.kind !== "unhandled" || process.env.CODEBYPLAN_DEBUG === "1") {
+        distress(errorContext.kind, errorContext.message, jsonMode);
+      }
     }
-    process.exit(0);
   }
+  process.exit(0);
 }
+var ProcessExitSignal;
 var init_resolve_worktree2 = __esm({
   "src/cli/resolve-worktree.ts"() {
     "use strict";
     init_flags();
     init_local_config();
     init_resolve_worktree();
+    ProcessExitSignal = class extends Error {
+      code;
+      constructor(code) {
+        super(`process.exit(${code})`);
+        this.name = "ProcessExitSignal";
+        this.code = code;
+      }
+    };
   }
 });
 
@@ -3882,9 +4036,9 @@ function sentinelPath(projectPath) {
   return join12(projectPath, ".codebyplan", "repo.json");
 }
 async function statSafe(p) {
-  const { stat } = await import("node:fs/promises");
+  const { stat: stat2 } = await import("node:fs/promises");
   try {
-    return await stat(p);
+    return await stat2(p);
   } catch {
     return null;
   }
@@ -6010,8 +6164,8 @@ function pruneEmptyManagedDirs(projectDir) {
 }
 function pruneLeafFirst(dir) {
   if (!fs5.existsSync(dir)) return;
-  const stat = fs5.statSync(dir);
-  if (!stat.isDirectory()) return;
+  const stat2 = fs5.statSync(dir);
+  if (!stat2.isDirectory()) return;
   for (const entry of fs5.readdirSync(dir, { withFileTypes: true })) {
     if (entry.isDirectory()) {
       pruneLeafFirst(path5.join(dir, entry.name));

package/package.json

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

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.

package/templates/skills/cbp-todo/SKILL.md

@@ -7,47 +7,95 @@ effort: low
 
 # Todo Command
 
-Single MCP call to determine next action, then load appropriate context before triggering the command. This is the **sole entry point** after `/clear` — it ensures Claude always has full context before any command runs.
+Single entry point after `/clear`: read the pure-read todo queue, gate on worktree ownership + checkpoint planning, load context, then trigger the next command. It ensures Claude always has full context — and never auto-routes into work locked to another worktree — before any command runs.
 
 ## Instructions
 
-### Step 0: Resolve Caller Worktree
+### Step 0: Resolve Caller Identity (worktree + user)
 
-Before any MCP call, derive the caller's `worktree_id` at runtime via `npx codebyplan resolve-worktree` so downstream calls can identify this worktree for hard-lock enforcement (CHK-104 TASK-2). The CLI resolves the tuple (device_id, repo path, current branch) against the worktrees table; CHK-108 removed the legacy `worktree_id` field from `.codebyplan/repo.json`.
+Before any MCP call, resolve who and where the caller is.
+
+**Worktree** — derive the caller `worktree_id` and any distress signal in one structured read:
 
 ```bash
-WORKTREE_ID=$(npx codebyplan resolve-worktree 2>/dev/null)
+npx codebyplan resolve-worktree --json   # → {"worktree_id":"<uuid>|null","error_kind":null|"<kind>"}
+```
+
+- `error_kind` is `null` or `"tuple_miss"` → healthy. `WORKTREE_ID` = `worktree_id` (may be `null`: a legitimate main-repo or unregistered-worktree case — proceed to read the queue, but downstream hard-locks 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**. Surface the distress line and STOP (skip Steps 1–4) — routing is unreliable when the resolver cannot read local state:
+
+```
+⚠ resolve-worktree: <error_kind> — local state is broken; routing is unreliable.
+Run `npx codebyplan setup` from this directory to register/repair, then re-run /cbp-todo.
 ```
 
-- **`WORKTREE_ID` non-empty** → forward as `worktree_id` to the `get_next_action` call in Step 1.
-- **`WORKTREE_ID` empty** → the current repo path + branch did not match any worktree row. The MCP server's hard-lock will reject mutations on assigned rows; surface a one-line note to the user that the worktree may need registration via `npx codebyplan setup` from this directory.
+**User** — `get_todos` (Step 1) requires a `user_id`:
+
+```bash
+npx codebyplan whoami --json   # → {"user_id":"<uuid>","email":"…"} or null
+```
+
+- A `user_id` is returned → use it in Step 1.
+- `null` (CLI keychain empty — common in OAuth-MCP-only environments) → the queue cannot be scoped by user; skip Step 1 and use the Step 3 fallback. The Step 1.5 ownership gate still applies.
+
+### Step 1: Read the Todo Queue (pure-read)
+
+With `USER_ID` resolved, call MCP `get_todos({ repo_id, user_id, worktree_id })` (omit `worktree_id` when `WORKTREE_ID` is `null` or unresolved — that returns only unscoped rows). Take **`rows[0]`** as the queue head (ordered by `sort_order`).
 
-### Step 1: Get Next Action
+- The head carries `command`, `instructions`, `state`, `metadata`, `worktree_id`, `checkpoint_id`, `task_id`.
+- The routing context (checkpoint/task) lives in **`rows[0].metadata`**.
+- `get_todos` is **pure-read** — `apps/todo-worker` is the sole regen authority. NEVER call `get_next_action` or `regenerate_todos_for_repo`.
+- Empty array, or `USER_ID` unavailable → go to Step 3 (empty-queue fallback).
 
-Use MCP `get_next_action` with `repo_id` and `worktree_id` (if present from Step 0).
+Queue `command` values may use the `/codebyplan:<name>` plugin-namespace form (e.g. `/codebyplan:round-start`); treat each as the matching `/cbp-<name>` skill for the Step 2 matrix.
 
-### Step 1.5: Checkpoint Planning Gate
+### Step 1.5: Resolve Target + Worktree-Ownership Gate
 
-Before honoring the command from Step 1, gate on the resolved active/next checkpoint's planning + activation state. This keeps work from starting on a half-baked or un-activated checkpoint. Resolve the checkpoint from the `get_next_action` response context (or MCP `get_current_task`), then load its `plan` + `status` via MCP `get_checkpoints` and its task count via MCP `get_tasks(checkpoint_id)`.
+Resolve the routing target's checkpoint and gate on ownership BEFORE any auto-trigger — including the Step 1.6 planning hand-offs. Refuse to route into, plan, or start work locked to a different worktree.
 
-Evaluate two rules in order (Rule A wins if both could match):
+Resolve the checkpoint from `rows[0].metadata` (or MCP `get_current_task`), then load its `worktree_id` + `plan` + `status` via MCP `get_checkpoints` and its task count via MCP `get_tasks(checkpoint_id)`. This single load is reused by the Step 1.6 planning gate. Skip this gate when the routing target has no checkpoint (idle — see Step 3) or the command is `/cbp-session-start`.
 
-- **RULE A — unplanned**: empty `plan.steps[]` **AND** zero tasks → the checkpoint has not been planned. Suppress the Step-1 command; surface `Now planning CHK-NNN… handing off to /cbp-checkpoint-plan` and auto-trigger `/cbp-checkpoint-plan {NNN}`.
-- **RULE B — planned-but-pending**: has tasks (or non-empty `plan.steps[]`) **BUT** `status === "pending"` (not yet activated) → the checkpoint is planned but not started. Suppress the Step-1 command; surface `Now starting CHK-NNN… handing off to /cbp-checkpoint-start` and auto-trigger `/cbp-checkpoint-start {NNN}` (a planned checkpoint must be started + claimed before task work).
-- **Neither** (planned AND `active`) → fall through to Step 2 unchanged. No regression to the existing flow.
+Two ownership signals:
 
-Skip this gate when `get_next_action` returns no checkpoint (idle — see Step 3) or the command is `/cbp-session-start`.
+1. **Server-detected conflict** — `rows[0].state === "worktree_conflict"` (command `/codebyplan:release-or-switch`): the todo-worker already detected the lock conflict. The owner is in `rows[0].metadata.conflicting_worktree_name` / `.conflicting_worktree_id`. Surface the mismatch message below and **STOP**. Do NOT auto-trigger the release-or-switch command and do NOT call `release_assignment` — switch worktrees rather than reassigning a lock to the caller.
+2. **Checkpoint-ownership check** — take the target checkpoint's `worktree_id` (loaded above, keyed by `rows[0].checkpoint_id` / `metadata.checkpoint.id`) and compare with caller `WORKTREE_ID`:
+   - target `worktree_id` is `null` → **allow** (unassigned — any worktree may pick it up; covers the both-null main-repo case).
+   - target `worktree_id` === caller `WORKTREE_ID` → **allow**.
+   - target `worktree_id` non-null **AND** caller `WORKTREE_ID` is `null`/unresolved → **block** (deliberate safety: identity cannot be confirmed. This does not contradict Step 0 — reading the queue is fine, auto-triggering INTO assigned work is not. Run `npx codebyplan setup` to register this worktree).
+   - target `worktree_id` non-null and differs from a non-null caller → **block**.
+
+On block, resolve the owning worktree's `name` + `path` via MCP `get_worktrees({ repo_id })` (match by id), then emit and STOP:
+
+```
+⚠ Work mismatch: CHK-<NNN> TASK-<N> is assigned to worktree <name> (<short-uuid>), not this one (<this-name> / <this-short-uuid>).
+Options:
+  A) Switch to <owning-worktree-path> and resume there
+  B) Work on something else here — run /cbp-checkpoint-create or /cbp-task-create
+  C) /cbp-session-end
+```
+
+`<short-uuid>` = first 8 chars of the worktree UUID. Caller unresolved → render "this one" as `(unresolved / —)`. Name lookup miss → show the UUID alone. Wait for the user. NEVER propose reassigning the checkpoint to the caller worktree.
+
+### Step 1.6: Checkpoint Planning Gate
+
+Ownership passed (Step 1.5). Now gate on the checkpoint's planning + activation state — reusing the `plan` + `status` + task count loaded in Step 1.5 — so work never starts on a half-baked or un-activated checkpoint. Evaluate two rules in order (Rule A wins if both could match):
+
+- **RULE A — unplanned**: empty `plan.steps[]` **AND** zero tasks → not planned. Suppress the head command; surface `Now planning CHK-NNN… handing off to /cbp-checkpoint-plan` and auto-trigger `/cbp-checkpoint-plan {NNN}`.
+- **RULE B — planned-but-pending**: has tasks (or non-empty `plan.steps[]`) **BUT** `status === "pending"` (not yet activated) → planned, not started. Suppress the head command; surface `Now starting CHK-NNN… handing off to /cbp-checkpoint-start` and auto-trigger `/cbp-checkpoint-start {NNN}` (a planned checkpoint must be started + claimed before task work).
+- **Neither** (planned AND `active`) → fall through to Step 2.
+
+Skip this gate when the routing target has no checkpoint (idle — see Step 3) or the command is `/cbp-session-start`.
 
 ### Step 2: Load Context Based on Command
 
-Before triggering the command, load the context it needs. This ensures `/clear` + `/cbp-todo` reliably restores full working context.
+Once the gates pass, load the context the head command needs. This ensures `/clear` + `/cbp-todo` reliably restores full working context.
 
-**Use the context loading matrix below.** Match the `command` from the response to determine what to load.
+**Use the context loading matrix below.** Match the `command` (in its `/cbp-<name>` form) to determine what to load.
 
 | Command Pattern | Context to Load |
 |----------------|-----------------|
 | `/cbp-session-start` | None — `/cbp-session-start` handles its own loading |
-| `/cbp-checkpoint-create` | If checkpoint exists in response context: load checkpoint via MCP `get_checkpoints` (filter by number). Display checkpoint title, goal, ideas summary |
+| `/cbp-checkpoint-create` | If checkpoint exists in `rows[0].metadata`: load checkpoint via MCP `get_checkpoints` (filter by number). Display checkpoint title, goal, ideas summary |
 | `/cbp-checkpoint-plan` | Load checkpoint via MCP `get_checkpoints` (filter by number) + `get_tasks(checkpoint_id)`. Display checkpoint title, goal, ideas, existing task count |
 | `/cbp-checkpoint-start` | Load checkpoint via MCP `get_checkpoints` + `get_tasks(checkpoint_id)`. Display checkpoint title, status, claim state, first pending task |
 | `/cbp-task-start [N]` | Load via MCP `get_current_task`. Display checkpoint title + task title/requirements summary |
@@ -87,9 +135,13 @@ Display a brief context summary:
 [Brief: what was done, what passed/failed]
 ```
 
-### Step 3: Suggest Session End When Idle
+### Step 3: Empty Queue — Fallback, then Idle
+
+Reached when `get_todos` returns `[]` or `USER_ID` was unavailable.
 
-If `get_next_action` returns no actionable `command` (null, empty, or explicit idle/done signal) — i.e. no active checkpoint with pending work — **do not auto-trigger anything**. Instead, suggest ending the session:
+1. **Fallback discovery** (worktree-scoped): MCP `get_current_task({ repo_id, worktree_id })` and `get_checkpoints({ repo_id, worktree_id, status: 'active' })` to discover whether actionable work exists for this caller.
+2. **Actionable work found** → treat the discovered checkpoint as the routing target and apply BOTH the Step 1.5 ownership gate and the Step 1.6 planning gate to it, using the `worktree_id` + `plan` + `status` returned by `get_checkpoints` (the fallback has no `rows[0]` — substitute the discovered checkpoint). If both gates pass, route via Step 2 → Step 4.
+3. **Nothing actionable** → suggest ending the session:
 
 ```
 No work remaining in the current checkpoint.
@@ -98,14 +150,15 @@ Run `/cbp-session-end` to finalize the session log and close out.
 Or run `/cbp-checkpoint-create` to start new work.
 ```
 
-Wait for the user. Do not auto-trigger `/cbp-session-end` — session wrap-up is a user-driven decision.
+Wait for the user. Do not auto-trigger `/cbp-session-end` — session wrap-up is a user-driven decision. NEVER call `regenerate_todos_for_repo`; an empty queue is a legitimate "nothing scheduled" state (the todo-worker has not regenerated yet, or there is no actionable work).
 
 ### Step 4: Display and Auto-trigger
 
-If Step 3 found actionable work, show `instructions` from the get_next_action response (gives user a chance to see what's happening), then auto-trigger the `command`.
+Reached only when the Step 1.5 ownership gate allowed routing to continue and the Step 1.6 planning gate fell through (no hand-off). Show `rows[0].instructions` (so the user sees what is happening), then auto-trigger `rows[0].command` (its `/cbp-<name>` form).
 
 ## Integration
 
 - **Called by**: `/cbp-session-start`, `/cbp-task-complete`, `/cbp-checkpoint-complete`, manual, after `/clear`
-- **Reads**: MCP `get_next_action`, `get_current_task`, `get_rounds`, `get_checkpoints`, `get_tasks`
-- **Triggers**: `command` from response (auto); Step 1.5 gate overrides to `/cbp-checkpoint-plan` (unplanned) or `/cbp-checkpoint-start` (planned-but-pending)
+- **Resolves**: `npx codebyplan resolve-worktree --json` (worktree id + distress signal), `npx codebyplan whoami --json` (user id)
+- **Reads**: MCP `get_todos`, `get_current_task`, `get_rounds`, `get_checkpoints`, `get_tasks`, `get_worktrees`
+- **Triggers**: `rows[0].command` (auto, after the Step 1.5 ownership gate); Step 1.6 overrides to `/cbp-checkpoint-plan` (unplanned) or `/cbp-checkpoint-start` (planned-but-pending)

package/templates/skills/cbp-todo/qa-regression.md

@@ -0,0 +1,45 @@
+---
+scope: org-shared
+name: cbp-todo-qa-regression
+description: Manual regression procedure for the cbp-todo worktree-ownership gate + get_todos switch (CHK-137 TASK-2)
+---
+
+# cbp-todo — Worktree-Ownership Regression
+
+Manual procedure verifying that `/cbp-todo` reads the pure-read `get_todos` queue and refuses to auto-route into work locked to another worktree. No automated harness exists for markdown skills; run these by hand (or read the queue with the MCP tools) whenever Step 0/1/1.5 of `SKILL.md` changes.
+
+Repo under test: `2ff6d405-39c5-47b8-a6d1-59f998ac0537`. Resolve a real `user_id` with `npx codebyplan whoami --json`, or harvest a non-null `assigned_user_id` from `get_checkpoints`.
+
+## Preconditions
+
+- `get_todos` is the only Step 1 read — confirm no `get_next_action` / `regenerate_todos_for_repo` call remains (`grep -n 'get_next_action\|regenerate_todos_for_repo' SKILL.md` → no hits).
+- Step 0 uses `resolve-worktree --json` and `whoami --json`.
+
+## Scenario A — caller owns the work → auto-trigger
+
+1. From a worktree that owns the active checkpoint (caller `WORKTREE_ID` === target checkpoint `worktree_id`, or target `worktree_id` is `null`).
+2. `get_todos({ repo_id, user_id, worktree_id })` returns a head whose target checkpoint is owned by the caller (or unscoped).
+3. **Expected**: Step 1.5 ownership gate allows, Step 1.6 planning gate falls through, Step 4 auto-triggers `rows[0].command` (mapped to its `/cbp-<name>` form).
+
+## Scenario B1 — server-generated conflict head → halt
+
+1. Caller `codebyplan-claude-2` (`38cd7dfa`). Active work assigned to `codebyplan-cli` (`016bd7f2`).
+2. `get_todos` head is the server conflict todo: `state === "worktree_conflict"`, `command "/codebyplan:release-or-switch"`, `metadata.conflicting_worktree_name === "codebyplan-cli"`.
+3. **MCP calls expected**: `get_todos`; `get_worktrees` (to resolve `016bd7f2` path for the message). NO `get_checkpoints` needed — the server already resolved the conflict.
+4. **Expected**: Step 1.5 server-conflict branch blocks and STOPS. The "Work mismatch" message names `codebyplan-cli (016bd7f2)` vs `codebyplan-claude-2 (38cd7dfa)`, offers Switch (`/Users/merilyviks/codebyplan-cli`) / other-work / session-end. NO auto-trigger; NO `release_assignment` call (never reassign the lock to the caller).
+
+## Scenario B2 — normal head, mismatched checkpoint owner → halt
+
+1. Caller `codebyplan-claude-2` (`38cd7dfa`). `get_todos` head is a normal routing todo whose target checkpoint `worktree_id` is `016bd7f2`.
+2. **MCP calls expected**: `get_todos`; `get_checkpoints` (Step 1.5 load, reads the target `worktree_id`); `get_worktrees` (resolve `016bd7f2` name + path).
+3. **Expected**: Step 1.5 checkpoint-ownership branch blocks and STOPS with the same "Work mismatch" message. NO auto-trigger; the Step 1.6 planning gate never runs (ownership precedes it).
+
+## Scenario C — empty queue + cross-worktree current task → halt
+
+1. `get_todos` returns `[]` (or `whoami` returned `null`, so Step 1 was skipped).
+2. Step 3 fallback: `get_current_task({ repo_id, worktree_id })` / `get_checkpoints({ repo_id, worktree_id, status: 'active' })` surface a checkpoint whose `worktree_id` differs from the caller.
+3. **Expected**: the Step 1.5 ownership gate (applied to the fallback target) blocks the discovered work with the same "Work mismatch" message. NO auto-trigger. `regenerate_todos_for_repo` is never called.
+
+## Edge — both null
+
+Caller `WORKTREE_ID` empty AND target checkpoint `worktree_id` `null` → legitimate main-repo / unassigned work → auto-trigger allowed.