codebyplan 1.13.26 → 1.13.28

package/dist/cli.js

@@ -14,7 +14,7 @@ var VERSION, PACKAGE_NAME;
 var init_version = __esm({
   "src/lib/version.ts"() {
     "use strict";
-    VERSION = "1.13.26";
+    VERSION = "1.13.28";
     PACKAGE_NAME = "codebyplan";
   }
 });

package/package.json

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

package/templates/hooks/README.md

@@ -2,7 +2,7 @@
 
 The `codebyplan` npm package ships a small, portable set of Claude Code hooks. They run in your project, use only generic primitives (`git rev-parse`, `${CLAUDE_PROJECT_DIR}`, `${CLAUDE_PLUGIN_ROOT}`), and degrade gracefully (exit 0) when their preconditions aren't met.
 
-Hook registration lives in [`hooks/hooks.json`](./hooks.json) — SessionStart, PreToolUse, and PostToolUse events are wired. (`Notification`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
+Hook registration lives in [`hooks/hooks.json`](./hooks.json) — PreToolUse, PostToolUse, and UserPromptSubmit events are wired. (`Notification`, `SessionStart`, `SessionEnd`, `Stop`, and `SubagentStop` are also schema-permitted but unused here.)
 
 **`cbp-statusline.sh` is auto-wired via `settings.project.base.json`.** The `statusLine` block is shipped inside `templates/settings.project.base.json` and merged into the consumer's `.claude/settings.json` automatically by `codebyplan claude install` (and on every `codebyplan claude update`). No manual copy-paste is required.
 
@@ -224,13 +224,32 @@ After a `complete_round` MCP call succeeds, reconciles the round's `files_change
 
 ---
 
+### `cbp-context-window-notify.sh` — UserPromptSubmit
+
+Injects a one-time notice into Claude's context when the session's total token usage
+(input + cache-creation + cache-read tokens from the last assistant message) crosses
+`CBP_CONTEXT_WARN_TOKENS` (default: 200000). Reads the JSONL transcript directly — not the
+statusline payload — so the model itself, not just the status bar, is aware of a large window.
+
+**Blocks vs warns**: never blocks — exits 0 on every path. Advisory only.
+
+**Skips when**: `transcript_path` or `session_id` is absent from stdin, the transcript file does
+not exist, or usage cannot be parsed (degrades to 0, below threshold).
+
+**Re-arms**: the latch `${TMPDIR:-/tmp}/cbp-ctxwin-<session_id>.latched` is removed when usage
+drops below threshold (e.g. after `/compact` or `/clear`), so the notice re-fires on the next crossing.
+
+**Opt out**: set `CBP_CONTEXT_WARN_TOKENS` very high, or remove the `UserPromptSubmit` entry from settings.
+
+---
+
 ## Supporting (not registered)
 
 ### `test-hooks.sh` — invoked by `auto-test-hooks.sh`
 
 Test suite for the plugin's 9 registered hooks. Runs two passes:
 
-1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
+1. **Header check** — every registered hook (`lint-format-on-edit`, `test-coverage-gate`, `pre-commit-quality-gate`, `maestro-yaml-validate`, `auto-test-hooks`, `mcp-migration-guard`, `validate-git-stash-deny`, `cbp-mcp-round-sync`, `cbp-context-window-notify`) carries the required `# Hook:` and `# Purpose:` header comments. `statusline` uses its own `# Claude Code Status Line` marker.
 2. **Functional smoke tests** — each hook is invoked with synthetic stdin matching its fast-path / graceful-degrade input; all must exit 0.
 
 Not in `hooks.json` — invoked indirectly via `auto-test-hooks.sh` on hook edits, or directly via `bash ${CLAUDE_PLUGIN_ROOT}/hooks/test-hooks.sh`.

package/templates/hooks/cbp-context-window-notify.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# @scope: org-shared
+# Hook: UserPromptSubmit
+# Purpose: Emit a one-time notice into Claude's context when the session's total
+#          context-window usage crosses CBP_CONTEXT_WARN_TOKENS (default 200000).
+#          Reads the last assistant message.usage from the JSONL transcript
+#          (input + cache_creation + cache_read) — independent of the statusline,
+#          so the model itself, not just the status bar, knows the window is large.
+#          Latches per session so the notice fires once; re-arms after /clear or
+#          /compact drops usage below the threshold. Always exits 0 — never blocks.
+
+set -euo pipefail
+
+INPUT=$(cat)
+
+TRANSCRIPT=$(echo "$INPUT" | jq -r '.transcript_path // ""' 2>/dev/null)
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // ""' 2>/dev/null)
+
+[ -z "$TRANSCRIPT" ] && exit 0
+[ -z "$SESSION_ID" ] && exit 0
+[ ! -f "$TRANSCRIPT" ] && exit 0
+
+THRESHOLD="${CBP_CONTEXT_WARN_TOKENS:-200000}"
+LATCH="${TMPDIR:-/tmp}/cbp-ctxwin-${SESSION_ID}.latched"
+
+TOTAL=$(tail -n 400 "$TRANSCRIPT" \
+  | jq -rR 'fromjson? | select(.message.usage != null)
+      | (.message.usage
+         | ((.input_tokens // 0) + (.cache_creation_input_tokens // 0) + (.cache_read_input_tokens // 0)))' \
+  2>/dev/null | tail -1) || TOTAL=0
+
+TOTAL="${TOTAL:-0}"
+
+if [ "$TOTAL" -ge "$THRESHOLD" ] 2>/dev/null; then
+  [ -f "$LATCH" ] && exit 0
+  touch "$LATCH"
+  jq -n --argjson tokens "$TOTAL" --argjson threshold "$THRESHOLD" \
+    '{hookSpecificOutput:{hookEventName:"UserPromptSubmit",additionalContext:("Context-window notice: total token usage has reached \($tokens) (threshold \($threshold)). The window is large — consider /compact or /clear, and be deliberate about large new reads.")}}'
+  exit 0
+fi
+
+rm -f "$LATCH" 2>/dev/null || true
+exit 0

package/templates/hooks/cbp-test-hooks.sh

@@ -255,6 +255,125 @@ fi
 
 echo ""
 
+# ===== HOOK SMOKE TESTS — cbp-context-window-notify =====
+echo "## Hook Smoke Tests — cbp-context-window-notify"
+
+HOOK="$HOOKS_DIR/cbp-context-window-notify.sh"
+FIXTURES_CTX="$HOOKS_DIR/__test-fixtures__/cbp-context-window-notify"
+
+if [ ! -f "$HOOK" ]; then
+  test_result "cbp-context-window-notify.sh present" "passed" "missing"
+else
+
+  # Case 1: over-threshold → exit 0 AND stdout has .hookSpecificOutput.additionalContext
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "sid-over-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+    test_result "cbp-context-window-notify.sh over-threshold exits 0 + emits additionalContext JSON" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh over-threshold exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+  fi
+  rm -rf "$ISO"
+
+  # Case 2: under-threshold → exit 0 AND empty stdout
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/under-threshold.jsonl" --arg s "sid-under-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-context-window-notify.sh under-threshold exits 0 + empty stdout" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh under-threshold exits 0 + empty stdout" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 3: latch — fire once (over), second identical call (same session_id, same TMPDIR) → empty stdout
+  ISO=$(mktemp -d)
+  SID="sid-latch-$$"
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] && [ -z "$OUTPUT" ]; then
+    test_result "cbp-context-window-notify.sh latch suppresses second over-threshold call" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh latch suppresses second over-threshold call" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 4: re-arm — fire over (creates latch), then under → latch file removed
+  ISO=$(mktemp -d)
+  SID="sid-rearm-$$"
+  STDIN_OVER=$(jq -n --arg t "$FIXTURES_CTX/over-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  STDIN_UNDER=$(jq -n --arg t "$FIXTURES_CTX/under-threshold.jsonl" --arg s "$SID" \
+    '{transcript_path:$t,session_id:$s}')
+  echo "$STDIN_OVER" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  echo "$STDIN_UNDER" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" >/dev/null 2>&1
+  LATCH_FILE="$ISO/cbp-ctxwin-${SID}.latched"
+  if [ ! -f "$LATCH_FILE" ]; then
+    test_result "cbp-context-window-notify.sh re-arm removes latch on under-threshold" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh re-arm removes latch on under-threshold" "passed" "failed (latch still present)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 5: cache-expired → exit 0 AND emits additionalContext JSON
+  ISO=$(mktemp -d)
+  STDIN=$(jq -n --arg t "$FIXTURES_CTX/cache-expired.jsonl" --arg s "sid-cache-$$" \
+    '{transcript_path:$t,session_id:$s}')
+  OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+  EXIT_CODE=$?
+  if [ "$EXIT_CODE" = "0" ] \
+     && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+    test_result "cbp-context-window-notify.sh cache-expired exits 0 + emits additionalContext JSON" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh cache-expired exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 6: graceful-degrade — empty stdin → exit 0
+  ISO=$(mktemp -d)
+  EXIT_CODE=$(echo '' | TMPDIR="$ISO" bash "$HOOK" >/dev/null 2>&1; echo $?)
+  if [ "$EXIT_CODE" = "0" ]; then
+    test_result "cbp-context-window-notify.sh graceful-degrade empty stdin exits 0" "passed" "passed"
+  else
+    test_result "cbp-context-window-notify.sh graceful-degrade empty stdin exits 0" "passed" "failed (exit=$EXIT_CODE)"
+  fi
+  rm -rf "$ISO"
+
+  # Case 7: malformed-line tolerance — a malformed/partial transcript line must NOT
+  # abort the hook (D3 "always exit 0"); the valid over-threshold line is still parsed
+  # (jq -rR 'fromjson?') and the notice still fires. The fixture lives only under
+  # .claude/hooks/__test-fixtures__; guard on its presence so this case stays
+  # byte-identical with the templates copy (which ships no __test-fixtures__ tree).
+  if [ -f "$FIXTURES_CTX/malformed.jsonl" ]; then
+    ISO=$(mktemp -d)
+    STDIN=$(jq -n --arg t "$FIXTURES_CTX/malformed.jsonl" --arg s "sid-malformed-$$" \
+      '{transcript_path:$t,session_id:$s}')
+    OUTPUT=$(echo "$STDIN" | TMPDIR="$ISO" CBP_CONTEXT_WARN_TOKENS=200000 bash "$HOOK" 2>/dev/null)
+    EXIT_CODE=$?
+    if [ "$EXIT_CODE" = "0" ] \
+       && echo "$OUTPUT" | jq -e '.hookSpecificOutput.additionalContext' >/dev/null 2>&1; then
+      test_result "cbp-context-window-notify.sh malformed-line tolerance exits 0 + emits additionalContext JSON" "passed" "passed"
+    else
+      test_result "cbp-context-window-notify.sh malformed-line tolerance exits 0 + emits additionalContext JSON" "passed" "failed (exit=$EXIT_CODE output=$(echo "$OUTPUT" | head -c 80))"
+    fi
+    rm -rf "$ISO"
+  else
+    test_result "cbp-context-window-notify.sh malformed-line tolerance (fixture absent — templates runtime)" "passed" "passed"
+  fi
+
+fi
+
+echo ""
+
 # ===== SUMMARY =====
 echo "=== TEST SUMMARY ==="
 echo -e "Passed: ${GREEN}$PASSED${NC}"

package/templates/hooks/hooks.json

@@ -1,5 +1,15 @@
 {
   "hooks": {
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "bash ${CLAUDE_PLUGIN_ROOT}/hooks/cbp-context-window-notify.sh"
+          }
+        ]
+      }
+    ],
     "PreToolUse": [
       {
         "matcher": "Edit|Write|MultiEdit",

package/templates/rules/todo-backend.md

@@ -2,7 +2,7 @@
 scope: org-shared
 paths:
   - "apps/todo-worker/**"
-  - "apps/web/src/lib/mcp/**"
+  - "packages/mcp-tools/src/**"
   - "supabase/migrations/*todos*"
   - "supabase/migrations/*worktrees*"
 ---
@@ -31,7 +31,7 @@ The worker is a passive cross-checker (`apps/todo-worker/src/invariants/check.ts
 `todos_jobs` is the work queue drained by the worker.
 
 ```
-MCP write → enqueueTodoJob → todos_jobs (status='pending')
+MCP write → enqueueTodosJob → todos_jobs (status='pending')
                                   ↓
             worker claim_todos_job (SELECT … FOR UPDATE SKIP LOCKED)
                                   ↓
@@ -72,23 +72,36 @@ The queue head (`get_todos` `rows[0]`) maps to one of these slash commands. The
 
 ## 5. Heartbeat policy
 
-The worker's `node-cron` heartbeat runs at `0 0 * * *` (UTC midnight). It enumerates every `(repo, worktree, user)` tuple with an active checkpoint OR in-progress standalone task and enqueues a `HEARTBEAT_SWEEP` todos_jobs row for each. This catches drift from missed `enqueueTodoJob` calls in MCP writers.
+The worker's `node-cron` heartbeat runs at `0 0 * * *` (UTC midnight). It enumerates every `(repo, worktree, user)` tuple with an active checkpoint OR in-progress standalone task and enqueues a `HEARTBEAT_SWEEP` todos_jobs row for each. This catches drift from missed `enqueueTodosJob` calls in MCP writers.
 
 Backoff: a failed job retries at `now + 2^attempts minutes` (cap 60min). After 3 attempts, the job stays `failed` and the heartbeat picks it up again at the next sweep.
 
 ## 6. Writer obligations — every MCP write enqueues
 
-`apps/web/src/lib/mcp/enqueueTodoJob.ts` exposes:
+The shared enqueue helper lives at `packages/mcp-tools/src/tools/enqueue-todos.ts`:
 
 ```ts
-enqueueTodoJob(client, { repoId, worktreeId, userId, reason }): Promise<void>
+enqueueTodosJob(
+  client: SupabaseClient,
+  repoId: string,
+  callerWorktreeId: string | undefined,
+  userId: string | null,
+  reason: string
+): Promise<void>
 ```
 
-Every workflow mutator in `apps/web/src/lib/mcp/tools/write.ts` MUST call this after the mutation succeeds. The 11 writers as of CHK-122:
+Two write modules import this helper:
+
+- **`packages/mcp-tools/src/tools/write.ts`** — checkpoint-bound writers (11 tools)
+- **`packages/mcp-tools/src/tools/standalone-write.ts`** — standalone task writers
+
+Every workflow mutator MUST call `void enqueueTodosJob(...)` after the mutation succeeds. The 11 checkpoint-bound writers in `write.ts` (CHK-122 + CHK-189):
 
 `create_checkpoint, update_checkpoint, complete_checkpoint, create_task, update_task, complete_task, add_round, update_round, complete_round, create_session_log, update_session_log`
 
-Plus the 2 dedicated enqueue tools: `enqueue_todo_job`, `bind_worktree_user`.
+**Dead code note**: `apps/web/src/lib/mcp/enqueueTodoJob.ts` and its companion test are orphaned dead code — `apps/web` no longer registers any MCP write tools (they live in `packages/mcp-tools`). Do not add new callers there.
+
+**Removed tools**: `enqueue_todo_job` and `bind_worktree_user` no longer exist. Do not reference or recreate them.
 
 **Contract**: best-effort. The helper logs and swallows failures — the heartbeat catches anything that slips through. Atomic in-txn enqueue is NOT supported (supabase-js limitation); the worker's bounded staleness (next heartbeat ≤ 24h) is the safety net.