create-claude-cabinet 0.43.0 → 0.44.0

package/lib/cli.js

@@ -397,9 +397,12 @@ function generateAgentWrappers(projectDir) {
     if (/websearch/.test(toolSignal)) tools.push('WebSearch');
     if (/webfetch|fetch_docs/.test(toolSignal)) tools.push('WebFetch');
 
-    // model: none of the cabinet skills declare one today; default to sonnet,
-    // but honor an explicit declaration if a member ever sets one.
-    const model = (typeof fm.model === 'string' && fm.model.trim()) || 'sonnet';
+    // model: none of the cabinet skills declare one today; default to inherit
+    // (follow the session model — a family alias like 'sonnet' goes stale when
+    // the frontier moves families), but honor an explicit declaration if a
+    // member ever sets one. Background watchtower rings pin their own model
+    // separately and are unaffected.
+    const model = (typeof fm.model === 'string' && fm.model.trim()) || 'inherit';
 
     const wrapper =
       `---\n` +

package/lib/mux-setup.js

@@ -57,6 +57,7 @@ const DATA_DIRS = [
   path.join(os.homedir(), '.config', 'mux', 'dx'),
   path.join(os.homedir(), '.config', 'mux', 'pending-prompts'),
   path.join(os.homedir(), '.local', 'share', 'mux', 'wt-health'),
+  path.join(os.homedir(), '.local', 'share', 'mux', 'qa-handoff'),
 ];
 
 function sha256(content) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-claude-cabinet",
-  "version": "0.43.0",
+  "version": "0.44.0",
   "description": "Claude Cabinet — opinionated process scaffolding for Claude Code projects",
   "bin": {
     "create-claude-cabinet": "bin/create-claude-cabinet.js"

package/templates/mux/bin/mux

@@ -162,10 +162,17 @@ setup_session_hooks() {
     "run-shell '${HOME}/.config/mux/worktree-cleanup.sh \"${project}\" \"#{window_name}\" 2>/dev/null || true'" 2>/dev/null || true
 
   # Window format: ·wt suffix colored by health (green=healthy, red=issues)
+  # on worktree windows; ·N amber QA-handoff badge on the main window (the
+  # two are mutually exclusive — @mux_qa is only ever set on the non-worktree
+  # window). See the QA handoff dispatch helpers.
   tmux set-option -t "$project" window-status-format \
-    '#[fg=#888888] #I:#W#{?@mux_worktree,#{?@wt_healthy,#[fg=#66bbaa],#[fg=#ff6666]}·wt#[default],} ' 2>/dev/null || true
+    '#[fg=#888888] #I:#W#{?@mux_worktree,#{?@wt_healthy,#[fg=#66bbaa],#[fg=#ff6666]}·wt#[default],}#{?@mux_qa,#[fg=#e0af68]·#{@mux_qa}#[default],} ' 2>/dev/null || true
   tmux set-option -t "$project" window-status-current-format \
-    '#[fg=#ffffff,bg=#4a4a8a,bold] #I:#W#{?@mux_worktree,#{?@wt_healthy,#[fg=#88ddcc],#[fg=#ff6666]}·wt#[default],} ' 2>/dev/null || true
+    '#[fg=#ffffff,bg=#4a4a8a,bold] #I:#W#{?@mux_worktree,#{?@wt_healthy,#[fg=#88ddcc],#[fg=#ff6666]}·wt#[default],}#{?@mux_qa,#[fg=#e0af68]·#{@mux_qa}#[default],} ' 2>/dev/null || true
+
+  # Restore the ·N QA badge from the durable queue on desk open (the tmux
+  # window option is ephemeral; the queue dir is the source of truth).
+  qa_refresh_indicator "$project" 2>/dev/null || true
 
   # Global bindings live in mux.tmux.conf (single source of truth), which
   # ~/.tmux.conf sources at server start. Re-sourcing here applies upgrades
@@ -426,6 +433,179 @@ queue_claude_resume() {
   tmux send-keys -t "$stable" "cd '${win_path}' && claude --resume ${session_id}" Enter
 }
 
+# --- QA handoff dispatch (qa-handoff-protocol.md, stage 2) ---
+#
+# The push model. /qa-handoff packages a just-merged worktree into an inbox
+# item, then calls `mux qa dispatch <descriptor>`. We route that handoff to
+# the desk's MAIN window (window 1 — the permanent main session that owns
+# post-merge QA / publish / deploy):
+#
+#   verified-idle Claude  → inject the pickup prompt (send-keys)
+#   bare shell (no Claude) → launch a fresh Claude with the prompt
+#   busy / other / closed  → queue on disk + light the ·N tab badge
+#
+# Window 1 drains the queue one at a time with `mux qa drain`. mux stays
+# DUMB: it routes an opaque, self-contained prompt and never parses handoff
+# content — so it's decoupled from the watchtower inbox schema and degrades
+# to inbox-only when not installed. The on-disk queue is the durable source
+# of truth; the ·N badge is a pure projection of it, recomputed at every
+# mutation and on desk open, so a tmux restart can't desync the two.
+
+MUX_QA_DIR="${HOME}/.local/share/mux/qa-handoff"
+
+# A descriptor is the small JSON /qa-handoff writes per merge:
+#   { project, project_path, item_id, merged_commit, what, pickup_prompt }
+# mux only reads project / pickup_prompt / item_id / what / merged_commit.
+
+qa_count() {
+  find "${MUX_QA_DIR}/${1}" -maxdepth 1 -name '*.json' 2>/dev/null | wc -l | tr -d ' '
+}
+
+# Resolve a project's MAIN STATION window — where post-merge QA lands.
+# Worktree windows (@mux_worktree=1) are never the station. Among the
+# non-worktree windows it PREFERS the lowest-index one running a live Claude
+# (@mux_claude=1), and otherwise falls back to the lowest-index non-worktree
+# window (a bare shell we can launch into). That fallback is the hardening:
+# if window 1's Claude died and the live main session moved to another
+# non-worktree window, the handoff still finds it. Echoes "<session>:<idx>",
+# or fails if the desk isn't open. list-windows is index-ordered.
+qa_main_window() {
+  local project="$1" idx wt claude fallback=""
+  while IFS='|' read -r idx wt claude; do
+    [[ "$wt" == "1" ]] && continue
+    [[ -z "$fallback" ]] && fallback="${project}:${idx}"
+    if [[ "$claude" == "1" ]]; then
+      echo "${project}:${idx}"
+      return 0
+    fi
+  done < <(tmux list-windows -t "=$project" -F '#{window_index}|#{@mux_worktree}|#{@mux_claude}' 2>/dev/null)
+  [[ -n "$fallback" ]] && { echo "$fallback"; return 0; }
+  return 1
+}
+
+# Classify the main window's pane:
+#   claude-idle | claude-busy | shell | other | no-window
+# Conservative by design: anything ambiguous resolves to claude-busy, so we
+# queue instead of injecting (better dark than wrong — the indicator and the
+# inject path only fire on a positively verified state). The idle/busy
+# markers track Claude Code's footer and may need tuning across CC versions;
+# `mux qa status` surfaces the detected state so any drift is debuggable, not
+# silent.
+qa_pane_state() {
+  local project="$1" win cmd is_claude snap
+  win=$(qa_main_window "$project") || { echo "no-window"; return; }
+  cmd=$(tmux display-message -t "=$win" -p '#{pane_current_command}' 2>/dev/null)
+  is_claude=$(tmux show-window-option -t "=$win" -v @mux_claude 2>/dev/null)
+
+  if [[ "$is_claude" != "1" ]]; then
+    case "$cmd" in
+      zsh|bash|sh|fish|login|-zsh|-bash|-sh) echo "shell" ;;
+      *) echo "other" ;;
+    esac
+    return
+  fi
+
+  snap=$(tmux capture-pane -t "=$win" -p -S -30 2>/dev/null)
+  if printf '%s' "$snap" | grep -qiE 'esc to interrupt|· *[0-9]+ tokens|Running…|Compacting|Thinking…'; then
+    echo "claude-busy"
+  elif printf '%s' "$snap" | grep -qiE '\? for shortcuts|\? for help'; then
+    echo "claude-idle"
+  else
+    echo "claude-busy"
+  fi
+}
+
+# Recompute the ·N badge from the durable queue and set/clear it on the main
+# window. Called after every mutation and from setup_session_hooks (desk
+# open), keeping the badge a faithful projection of the queue dir.
+qa_refresh_indicator() {
+  local project="$1" win count
+  win=$(qa_main_window "$project") || return 0
+  count=$(qa_count "$project")
+  if [[ "$count" -gt 0 ]]; then
+    tmux set-window-option -t "=$win" @mux_qa "$count" 2>/dev/null || true
+  else
+    tmux set-window-option -t "=$win" -u @mux_qa 2>/dev/null || true
+  fi
+}
+
+qa_enqueue() {
+  local project="$1" descriptor="$2" item_id
+  mkdir -p "${MUX_QA_DIR}/${project}"
+  item_id=$(python3 -c 'import json,sys,re; v=str(json.load(open(sys.argv[1])).get("item_id") or "handoff"); print(re.sub(r"[^A-Za-z0-9._-]","-",v))' "$descriptor" 2>/dev/null)
+  [[ -n "$item_id" ]] || item_id="handoff-$(date +%s)"
+  cp "$descriptor" "${MUX_QA_DIR}/${project}/${item_id}.json"
+  qa_refresh_indicator "$project"
+}
+
+# Inject into an idle Claude composer. C-u clears any half-typed input first
+# so we never prepend to whatever was sitting in the box.
+qa_inject() {
+  local win="$1" prompt="$2"
+  tmux send-keys -t "=$win" C-u 2>/dev/null || true
+  tmux send-keys -t "=$win" -l "$prompt"
+  tmux send-keys -t "=$win" Enter
+}
+
+# Launch a fresh Claude in a bare-shell main window with the handoff as its
+# opening prompt. Reuses queue_claude_start (the same cd→claude→/orient-quick
+# →prompt sequence mux uses everywhere) — single source of truth for "start a
+# Claude session with a prompt". C-u clears the shell line first.
+qa_launch_fresh() {
+  local win="$1" prompt="$2" project="$3" path
+  path=$(project_path "$project" 2>/dev/null) || path="$PWD"
+  tmux send-keys -t "=$win" C-u 2>/dev/null || true
+  queue_claude_start "=$win" "$prompt" "$path"
+}
+
+# Ensure the desk has a live MAIN STATION (window 1 — a Claude on the main
+# checkout that receives post-merge QA handoffs). Idempotent, and the keystone
+# of the standing-station model: because a clean station is guaranteed, every
+# `mux … "prompt"` can safely route its work to a worktree and let the merge
+# hand back to the station. Three cases, in order:
+#   - a live non-worktree Claude already exists → reuse it (no-op)
+#   - the main window is a bare shell (window 1's Claude died) → relaunch there
+#   - no non-worktree window at all (defensive) → create window 1, launch there
+# Never touches worktree windows. Reuses qa_main_window (live-station-preferring
+# resolution) and qa_launch_fresh (the single launch path) — no forked logic.
+ensure_main_station() {
+  local project="$1" path="$2" station claude
+  station=$(qa_main_window "$project" 2>/dev/null || true)
+  if [[ -n "$station" ]]; then
+    claude=$(tmux show-window-option -t "=$station" -v @mux_claude 2>/dev/null)
+    [[ "$claude" == "1" ]] && return 0
+    qa_launch_fresh "$station" "" "$project"
+    return 0
+  fi
+  tmux new-window -t "=$project" -c "$path" 2>/dev/null || true
+  station=$(qa_main_window "$project" 2>/dev/null || true)
+  [[ -n "$station" ]] && qa_launch_fresh "$station" "" "$project"
+  return 0
+}
+
+# Create a worktree for WORK, and never silently fall back to the main
+# checkout — dumping work onto the clean station is the exact silent failure
+# the standing-station model exists to prevent. On a slug collision with an
+# existing worktree, uniquify (slug-2, slug-3, …) so the work always gets its
+# own isolated worktree, and surface the rename. Echoes the final slug; fails
+# (caller refuses to run on main) only on a genuine, non-collision error.
+create_work_worktree() {
+  local project="$1" base="$2" slug="$2" n=1
+  while (( n <= 20 )); do
+    if create_worktree "$project" "$slug" >/dev/null 2>&1; then
+      [[ "$slug" != "$base" ]] && \
+        printf "worktree '%s' already existed — created '%s' instead\n" "$base" "$slug" >&2
+      printf '%s\n' "$slug"
+      return 0
+    fi
+    # A pre-existing dir means a slug collision → uniquify and retry. Anything
+    # else is a real failure (bad git state) → don't mask it as main.
+    [[ -d "${MUX_WORKTREES_DIR}/${project}-${slug}" ]] || return 1
+    (( n++ )); slug="${base}-${n}"
+  done
+  return 1
+}
+
 # --- Subcommands ---
 
 cmd_picker() {
@@ -521,17 +701,17 @@ cmd_open() {
       local win_name win_path
       win_name=$(slugify "$prompt")
 
-      if has_active_claude "$project"; then
-        win_path=$(create_worktree "$project" "$win_name") || win_path="$path"
-      else
-        win_path="$path"
-      fi
+      # Standing-station model: keep window 1 a clean main station and run the
+      # work in an isolated worktree, so the merge produces a real handoff.
+      ensure_main_station "$project" "$path"
+      # Never fall back to main — that would dump work onto the clean station.
+      win_name=$(create_work_worktree "$project" "$win_name") \
+        || die "Couldn't create a worktree for '${win_name}' — refusing to run work on the main checkout. Try: mux worktree ls"
+      win_path="${MUX_WORKTREES_DIR}/${project}-${win_name}"
 
       tmux new-window -t "=$project" -n "$win_name" -c "$win_path"
-      if [[ "$win_path" == "$MUX_WORKTREES_DIR/"* ]]; then
-        tmux set-window-option -t "=${project}:${win_name}" @mux_worktree 1 2>/dev/null || true
-        tmux set-window-option -t "=${project}:${win_name}" @wt_healthy 1 2>/dev/null || true
-      fi
+      tmux set-window-option -t "=${project}:${win_name}" @mux_worktree 1 2>/dev/null || true
+      tmux set-window-option -t "=${project}:${win_name}" @wt_healthy 1 2>/dev/null || true
       queue_claude_start "=${project}:${win_name}" "$prompt" "$win_path"
 
       if in_tmux; then
@@ -547,23 +727,38 @@ cmd_open() {
       fi
     fi
   else
-    if [[ -n "$prompt" ]]; then
-      local win_name
-      win_name=$(slugify "$prompt")
-      tmux new-session -d -s "$project" -n "$win_name" -c "$path"
-      queue_claude_start "=${project}:${win_name}" "$prompt" "$path"
-    else
-      tmux new-session -d -s "$project" -c "$path"
-    fi
-
-    # Store project path and set up session hooks
+    # New desk: window 1 is the main checkout. Create it + wire hooks first so
+    # the station and any worktree windows inherit the right format/env.
+    tmux new-session -d -s "$project" -c "$path"
     tmux set-environment -t "$project" MUX_PROJECT_PATH "$path" 2>/dev/null || true
     setup_session_hooks "$project" "$path"
 
-    if in_tmux; then
-      tmux switch-client -t "=$project"
+    if [[ -n "$prompt" ]]; then
+      # Work on a fresh desk: window 1 becomes the main station, the work runs
+      # in a worktree (window 2). Land the operator on the work.
+      local win_name win_path
+      win_name=$(slugify "$prompt")
+      ensure_main_station "$project" "$path"
+      # Never fall back to main — that would dump work onto the clean station.
+      win_name=$(create_work_worktree "$project" "$win_name") \
+        || die "Couldn't create a worktree for '${win_name}' — refusing to run work on the main checkout. Try: mux worktree ls"
+      win_path="${MUX_WORKTREES_DIR}/${project}-${win_name}"
+      tmux new-window -t "=$project" -n "$win_name" -c "$win_path"
+      tmux set-window-option -t "=${project}:${win_name}" @mux_worktree 1 2>/dev/null || true
+      tmux set-window-option -t "=${project}:${win_name}" @wt_healthy 1 2>/dev/null || true
+      queue_claude_start "=${project}:${win_name}" "$prompt" "$win_path"
+      if in_tmux; then
+        tmux switch-client -t "=${project}:${win_name}"
+      else
+        tmux attach-session -t "=${project}:${win_name}"
+      fi
     else
-      tmux attach-session -t "=$project"
+      # No prompt — the lightweight "just drop me into main" escape hatch.
+      if in_tmux; then
+        tmux switch-client -t "=$project"
+      else
+        tmux attach-session -t "=$project"
+      fi
     fi
   fi
 }
@@ -584,17 +779,17 @@ cmd_new() {
     local win_name win_path
     win_name=$(slugify "$prompt")
 
-    if has_active_claude "$session"; then
-      win_path=$(create_worktree "$session" "$win_name") || win_path="$path"
-    else
-      win_path="$path"
-    fi
+    # Standing-station model: ensure window 1 is a main station, run the work
+    # in an isolated worktree so its merge hands back to the station.
+    ensure_main_station "$session" "$path"
+    # Never fall back to main — that would dump work onto the clean station.
+    win_name=$(create_work_worktree "$session" "$win_name") \
+      || die "Couldn't create a worktree for '${win_name}' — refusing to run work on the main checkout. Try: mux worktree ls"
+    win_path="${MUX_WORKTREES_DIR}/${session}-${win_name}"
 
     tmux new-window -n "$win_name" -c "$win_path"
-    if [[ "$win_path" == "$MUX_WORKTREES_DIR/"* ]]; then
-      tmux set-window-option -t "=${session}:${win_name}" @mux_worktree 1 2>/dev/null || true
-      tmux set-window-option -t "=${session}:${win_name}" @wt_healthy 1 2>/dev/null || true
-    fi
+    tmux set-window-option -t "=${session}:${win_name}" @mux_worktree 1 2>/dev/null || true
+    tmux set-window-option -t "=${session}:${win_name}" @wt_healthy 1 2>/dev/null || true
     queue_claude_start "=${session}:${win_name}" "$prompt" "$win_path"
   else
     if has_active_claude "$session"; then
@@ -1041,6 +1236,146 @@ cmd_worktree() {
   esac
 }
 
+cmd_qa() {
+  local action="${1:-list}"
+  shift || true
+  case "$action" in
+    dispatch) qa_cmd_dispatch "$@" ;;
+    list)     qa_cmd_list "$@" ;;
+    drain)    qa_cmd_drain "$@" ;;
+    status)   qa_cmd_status "$@" ;;
+    clear)    qa_cmd_clear "$@" ;;
+    *) die "Usage: mux qa {dispatch <file>|list|drain|status|clear} [project]" ;;
+  esac
+}
+
+# Route one packaged handoff to window 1. Called by /qa-handoff after it
+# files the inbox item. Never dies on a closed/absent desk — it queues, so
+# the handoff is never lost (it also lives in the inbox regardless).
+qa_cmd_dispatch() {
+  require_python
+  local descriptor="${1:-}"
+  [[ -f "$descriptor" ]] || die "mux qa dispatch: descriptor file not found: ${descriptor}"
+
+  local project prompt
+  project=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("project",""))' "$descriptor" 2>/dev/null)
+  prompt=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("pickup_prompt",""))' "$descriptor" 2>/dev/null)
+  [[ -n "$project" ]] || die "mux qa dispatch: descriptor missing 'project'"
+  [[ -n "$prompt" ]]  || die "mux qa dispatch: descriptor missing 'pickup_prompt'"
+
+  # `project` should be the mux DESK (tmux session). Desk short-names often
+  # differ from the repo dir name (desk `cabinet`, repo `claude-cabinet`), so
+  # if it isn't a live session but the descriptor's project_path matches a
+  # desk's MUX_PROJECT_PATH, remap to that desk — otherwise a repo-name
+  # descriptor would queue to a dead desk and never light the badge.
+  if ! tmux has-session -t "=$project" 2>/dev/null; then
+    local ppath desk mp
+    ppath=$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("project_path",""))' "$descriptor" 2>/dev/null)
+    if [[ -n "$ppath" ]]; then
+      while IFS= read -r desk; do
+        mp=$(tmux show-environment -t "$desk" MUX_PROJECT_PATH 2>/dev/null | sed 's/^MUX_PROJECT_PATH=//')
+        if [[ "$mp" == "$ppath" ]]; then project="$desk"; break; fi
+      done < <(tmux list-sessions -F '#{session_name}' 2>/dev/null)
+    fi
+  fi
+
+  local state win
+  state=$(qa_pane_state "$project")
+  win=$(qa_main_window "$project" 2>/dev/null || true)
+
+  # Self-dispatch guard: if dispatch is invoked FROM the main-station window
+  # itself, the work was done on main (no worktree to hand off from) and there
+  # is no second window to route to. No-op cleanly instead of queuing a handoff
+  # to the very window that wrote it. This is the deliberate work-on-main
+  # escape hatch; the standing-station default makes it rare.
+  if [[ -n "${TMUX_PANE:-}" && -n "$win" ]]; then
+    local here
+    here=$(tmux display-message -t "$TMUX_PANE" -p '#{session_name}:#{window_index}' 2>/dev/null)
+    if [[ -n "$here" && "$here" == "$win" ]]; then
+      echo "• Already on the main station (work was on main, not a worktree) — the handoff is filed in the inbox; act on it here or it ages. No dispatch needed."
+      return 0
+    fi
+  fi
+
+  case "$state" in
+    claude-idle)
+      qa_inject "$win" "$prompt"
+      echo "✓ Handoff pushed to window 1 (injected into the idle main session)."
+      ;;
+    shell)
+      qa_launch_fresh "$win" "$prompt" "$project"
+      echo "✓ Handoff pushed to window 1 (launched a fresh main session with it)."
+      ;;
+    claude-busy|other|no-window)
+      qa_enqueue "$project" "$descriptor"
+      local n; n=$(qa_count "$project")
+      local why; case "$state" in
+        claude-busy) why="window 1 is busy" ;;
+        other)       why="window 1 is running another program" ;;
+        no-window)   why="the ${project} desk isn't open" ;;
+      esac
+      echo "• Queued — ${why}. ${n} handoff(s) pending; the ·${n} badge is lit. Window 1 drains with: mux qa drain"
+      ;;
+  esac
+}
+
+qa_cmd_list() {
+  local project="${1:-$(tmux display-message -p '#{session_name}' 2>/dev/null)}"
+  [[ -n "$project" ]] || die "mux qa list: no project (run inside a desk or pass a name)"
+  local n; n=$(qa_count "$project")
+  if [[ "$n" -eq 0 ]]; then
+    echo "No QA handoffs queued for ${project}."
+    return 0
+  fi
+  echo "${n} QA handoff(s) queued for ${project} (oldest first):"
+  local f
+  while IFS= read -r f; do
+    [[ -n "$f" ]] || continue
+    python3 -c 'import json,sys
+d=json.load(open(sys.argv[1]))
+what=d.get("what","(no summary)")
+sha=str(d.get("merged_commit","?"))[:8]
+iid=d.get("item_id","?")
+print(f"  - {what}  [merged {sha}]  {iid}")' "$f" 2>/dev/null
+  done < <(ls -1tr "${MUX_QA_DIR}/${project}"/*.json 2>/dev/null)
+  echo ""
+  echo "Drain the oldest into this session: mux qa drain"
+}
+
+# Pop the oldest queued handoff and print its pickup prompt to stdout. The
+# window-1 Claude session runs this (via the Bash tool) and acts on the
+# prompt it gets back — the prompt IS the instruction. Removing the
+# descriptor decrements the badge.
+qa_cmd_drain() {
+  local project="${1:-$(tmux display-message -p '#{session_name}' 2>/dev/null)}"
+  [[ -n "$project" ]] || die "mux qa drain: no project (run inside a desk or pass a name)"
+  local oldest
+  oldest=$(ls -1tr "${MUX_QA_DIR}/${project}"/*.json 2>/dev/null | head -1)
+  if [[ -z "$oldest" ]]; then
+    echo "No QA handoffs queued for ${project}."
+    return 0
+  fi
+  python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("pickup_prompt",""))' "$oldest" 2>/dev/null
+  rm -f "$oldest"
+  qa_refresh_indicator "$project"
+}
+
+qa_cmd_status() {
+  local project="${1:-$(tmux display-message -p '#{session_name}' 2>/dev/null)}"
+  [[ -n "$project" ]] || die "mux qa status: no project (run inside a desk or pass a name)"
+  printf 'QA handoff — %s\n' "$project"
+  printf '  window 1 pane: %s\n' "$(qa_pane_state "$project")"
+  printf '  queued:        %s\n' "$(qa_count "$project")"
+}
+
+qa_cmd_clear() {
+  local project="${1:-$(tmux display-message -p '#{session_name}' 2>/dev/null)}"
+  [[ -n "$project" ]] || die "mux qa clear: no project (run inside a desk or pass a name)"
+  rm -f "${MUX_QA_DIR}/${project}"/*.json 2>/dev/null || true
+  qa_refresh_indicator "$project"
+  echo "Cleared queued QA handoffs for ${project}."
+}
+
 cmd_setup() {
   echo "=== mux setup ==="
   echo ""
@@ -1324,6 +1659,7 @@ main() {
     dx)        shift; cmd_dx "$@" ;;
     portal)    shift; cmd_portal "${1:-}" ;;
     worktree)  shift; cmd_worktree "$@" ;;
+    qa)        shift; cmd_qa "$@" ;;
     setup)     cmd_setup ;;
     help)      cmd_help ;;
     -h|--help) cmd_help ;;

package/templates/mux/config/help.txt

@@ -19,6 +19,7 @@
 │  mux portal on/off    Toggle voice     │
 │  mux worktree ls      List worktrees   │
 │  mux worktree health  Check health     │
+│  mux qa list/drain    QA handoff queue │
 │  mux setup            First-time setup │
 │  mux help             This screen      │
 │                                        │
@@ -32,6 +33,7 @@
 │                                        │
 │  ·wt tab marker = worktree window      │
 │  green = healthy, red = issues         │
+│  ·N tab marker = QA handoffs queued    │
 │                                        │
 │  Terminal text (scroll + copy):        │
 │  wheel or Ctrl-Space [   scroll back   │

package/templates/skills/audit/SKILL.md

@@ -1,5 +1,4 @@
 ---
-model: opus
 name: audit
 description: |
   Convene the full cabinet for a quality review. Each cabinet member examines

package/templates/skills/cabinet-record-keeper/SKILL.md

@@ -23,7 +23,12 @@ directives:
     (2) Additions — check if this session built, changed, or published
     anything that should be recorded in those files but isn't yet
     (new capabilities, version bumps, count changes, new conventions).
-    Fix what you find — don't create findings.
+    Verification guard — before you write or update ANY claim, grep the
+    named file, symbol, command, path, or count in the working tree and
+    confirm it matches reality. Never extrapolate what a change does from
+    its stated intent; read the actual diff or code. If a claim can't be
+    verified against the tree, do not record it as fact — mark it
+    unverified instead. Fix what you find — don't create findings.
 files:
   - CLAUDE.md
   - "**/CLAUDE.md"

package/templates/skills/cc-upgrade/SKILL.md

@@ -1,5 +1,4 @@
 ---
-model: opus
 name: cc-upgrade
 description: |
   Conversational upgrade when Claude Cabinet updates. Runs the installer to

package/templates/skills/execute/SKILL.md

@@ -1,5 +1,4 @@
 ---
-model: opus
 name: execute
 description: |
   Execute a plan with cabinet member checkpoints. Reads the plan, activates

package/templates/skills/investigate/SKILL.md

@@ -1,5 +1,4 @@
 ---
-model: opus
 name: investigate
 description: |
   Structured codebase exploration before planning. Four phases: observe
@@ -17,7 +16,6 @@ related:
   - type: file
     path: cabinet/_briefing.md
     role: "System briefing for investigation scope"
-model: opus
 argument-hint: "what to investigate — e.g., 'why orient fails on fresh installs'"
 ---
 

package/templates/skills/plan/SKILL.md

@@ -1,5 +1,4 @@
 ---
-model: opus
 name: plan
 description: |
   Structured planning with cabinet critique. The relevant cabinet members

package/templates/skills/qa-handoff/SKILL.md

@@ -6,8 +6,8 @@ description: |
   happen on main (e2e tests against a live server, npm publish, deploy).
   Writes an operator-level handoff (what merged, what the worktree could
   NOT verify, what hangs on the next step) to the watchtower inbox so it
-  surfaces and ages until QA happens. Stage 1 of the QA-handoff protocol:
-  this PACKAGES the handoff; it does not yet dispatch it to window 1.
+  surfaces and ages until QA happens, then pushes it to the desk's main
+  window (mux dispatch) so QA starts without hand-carrying it.
   Use when: "qa-handoff", "/qa-handoff", "hand off to QA", "package the
   handoff", or right after merging a worktree branch into main.
 argument-hint: "optional branch — e.g., (none = most recent merge), 'mux/my-branch'"
@@ -22,11 +22,12 @@ main. These are all **post-merge** activities, and there's no bridge
 between "the worktree work is merged" and "QA / publish / deploy runs on
 main." This skill builds the handoff that crosses that gap.
 
-Full design: `.claude/plans/qa-handoff-protocol.md`. This skill is
-**stage 1** — it packages a merge into a durable, surfaced handoff. The
-dispatch half (mux poking window 1, pane-state detection, the on-disk
-queue) is a later stage; for now the handoff lands in the inbox and is
-surfaced by `/briefing` until the operator runs QA.
+Full design: `.claude/plans/qa-handoff-protocol.md`. This skill packages
+a merge into a durable, surfaced handoff (stage 1) and then pushes it to
+the desk's main window via `mux qa dispatch` (stage 2) — injecting into
+an idle window-1 Claude, launching a fresh one, or queuing behind a `·N`
+tab badge when window 1 is busy. The handoff lands in the inbox either
+way, so `/briefing` resurfaces it until QA happens.
 
 ## The verification contract this enforces
 
@@ -145,21 +146,27 @@ reserve `urgent` for a handoff that genuinely blocks (a publish the
 operator is waiting on). Better dark than wrong: a wall of urgent
 handoffs trains the operator to ignore them.
 
-Write the payload to a temp file, then file via the installed queue API:
+Write the payload to a **run-scoped** temp file, then file via the installed
+queue API. Handoffs accumulate — never reuse one fixed filename (a second
+handoff collides, and the Write tool refuses to overwrite an unread leftover
+from a prior run). Key the temp file by the merged short SHA and `rm -f` it
+first:
 
 ```bash
 WT="${WATCHTOWER_DIR:-$HOME/.claude-cabinet/watchtower}"
-# 1. Write the createItem args to /tmp/qa-handoff-item.json:
+ITEM="/tmp/qa-handoff-item-<short-sha>.json"   # run-scoped — never a fixed name
+rm -f "$ITEM"
+# Write the createItem args to "$ITEM" (here `project` is the WATCHTOWER
+# project/repo name — the inbox keys on it):
 #    { project, project_path, category: "qa-handoff", urgency,
 #      title, summary, context_anchor, evidence: <the payload above>,
-#      thread_ids: [<linked thread slugs, if known>],
-#      filed_by: "manual" }
+#      thread_ids: [<linked thread slugs, if known>], filed_by: "manual" }
 node --input-type=module -e '
 import { readFileSync } from "fs";
 import { createItem } from "'"$WT"'/scripts/watchtower-queue.mjs";
 const args = JSON.parse(readFileSync(process.argv[1], "utf8"));
 console.log("Filed qa-handoff item:", createItem(args));
-' /tmp/qa-handoff-item.json
+' "$ITEM"
 ```
 
 - `title`: `QA handoff: <what>, merged <short-sha>`
@@ -170,11 +177,84 @@ console.log("Filed qa-handoff item:", createItem(args));
   Ring 3 mints threads at session close, so a fresh thread may not exist
   yet; leave `[]` rather than guessing.
 
-## Step 6: Report to the operator
+## Step 6: Dispatch to window 1 (push model)
+
+Stage 1 stops at the inbox. Stage 2 pushes the handoff to the desk's
+**main window** (window 1 — the permanent main session that owns
+post-merge QA / publish / deploy) so QA starts without the operator
+hand-carrying it. mux owns the routing; this skill just hands it an
+opaque, self-contained prompt and lets mux decide where it lands:
+
+- verified-idle Claude in window 1 → injected immediately
+- bare-shell window 1 (no Claude) → a fresh session launches with it
+- window 1 busy / desk closed → queued on disk + a `·N` tab badge lights;
+  window 1 drains it with `mux qa drain`
+
+mux never parses the handoff — it routes the prompt — so the inbox item
+filed in Step 5 stays the single canonical record. The `pickup_prompt`
+is a pointer to that item plus the one thing QA must not miss; do not
+inline the whole payload (that would fork the source of truth).
+
+Write the dispatch descriptor to a **run-scoped** path, then call mux. Two
+fields are load-bearing:
+
+- **`project` here is the mux DESK** — the tmux session name, NOT the
+  repo/project name. mux resolves window 1 with `tmux -t "=<project>"`, so
+  when the desk's short name differs from the repo name (desk `cabinet`,
+  repo `claude-cabinet`) a repo-name descriptor silently queues to a
+  non-existent desk and never lights the badge. Get the desk from
+  `tmux display-message -p '#{session_name}'` and use that literal value.
+  (mux now also self-corrects by `project_path` if you get this wrong, but
+  pass the desk name — don't rely on the fallback.)
+- The temp path is run-scoped (keyed by the merged short SHA) — same
+  accumulate-don't-collide reason as Step 5.
+
+Use the `item_id` that Step 5's `createItem` returned:
+
+```bash
+tmux display-message -p '#{session_name}'        # the mux desk — use as "project" below
+DISPATCH="/tmp/qa-handoff-dispatch-<short-sha>.json"
+cat > "$DISPATCH" <<'JSON'
+{
+  "project": "<mux desk name from the command above — NOT the repo name>",
+  "project_path": "<repo root>",
+  "item_id": "<id from Step 5>",
+  "merged_commit": "<sha on main>",
+  "what": "<the one-line what>",
+  "pickup_prompt": "Post-merge QA: <branch> merged to main at <short-sha>. Read qa-handoff inbox item <item_id> (run /inbox) for the full handoff, then run the runtime-needed checks it names — <e2e/publish/deploy, one phrase> — and stamp the verdict citing the named checks and the commit tested (<short-sha>). Do not publish or deploy without operator go."
+}
+JSON
+
+if command -v mux >/dev/null 2>&1; then
+  mux qa dispatch "$DISPATCH"
+else
+  echo "mux not installed — handoff is in the inbox; /briefing and /inbox surface it."
+fi
+```
+
+Graceful degradation, no silent failure: if mux is absent (the project
+doesn't use it), the handoff still lives in the inbox from Step 5 — the
+command says so rather than failing quietly. mux's own output reports
+which path it took (injected / launched / queued).
+
+### Without mux (the universal path)
+
+mux is optional. The substantive part of this skill — the honest handoff
+filed to the inbox — depends only on the **watchtower** module, not mux.
+Without mux, the dispatch above is skipped and the handoff simply waits in
+the inbox: open Claude on the main checkout (any terminal or editor tab),
+pull it with `/inbox` or `/briefing`, and run the QA there. Same handoff,
+same verification contract — *pull* instead of *push*. Everything above
+the dispatch step (the honest packaging) is identical either way; the mux
+routing is purely an accelerant for desks that run it.
+
+## Step 7: Report to the operator
 
 Tell the operator, plainly:
 - What was handed off (the `what` + merged commit).
 - What QA on main needs to do — the `runtime_needed` list, named.
+- How it dispatched — pushed to window 1 now, or queued behind a `·N`
+  badge for window 1 to drain (echo mux's result).
 - Whether a publish/deploy is staged and waiting on their go.
 - That it's in the inbox and `/briefing` will resurface it until acted
   on.
@@ -183,10 +263,21 @@ Do **not** run the publish or deploy. This skill prepares and stops;
 promotion is an explicit operator decision (and, later, a dispatched
 window-1 step).
 
-## Scope boundary (stage 1)
+## Scope boundary (stages 1–2)
+
+This skill now packages the handoff (stage 1) AND pushes it to window 1
+(stage 2, via `mux qa dispatch`). What it still does NOT do:
+
+- **Inject into a *busy* window-1 session.** Dispatch only injects into a
+  verified-idle Claude or launches a fresh one; a running session is left
+  alone and the handoff queues. Reaching into a live session needs the
+  unbuilt session-messages layer (ex-Plan 8) — deferred by design.
+- **Auto-run the QA or flip `runtime-needed` → `runtime-verified`.** That
+  is the window-1 session's job after it drains the handoff and the named
+  checks pass; the flip lands when the operator resolves the inbox item.
+- **Publish or deploy.** Always prepared, never auto-fired (operator go).
 
-This skill does NOT poke window 1, detect pane state, or auto-run QA.
-Those are the dispatch stages in `.claude/plans/qa-handoff-protocol.md`.
-What it guarantees today: every merge can be packaged into one honest,
-surfaced, ageable handoff that names what could not be verified from the
-worktree — so nothing silently ships unverified.
+What it guarantees: every merge becomes one honest, surfaced, ageable
+handoff that names what the worktree could not verify — and that handoff
+is actively routed to the QA station, not left for the operator to find.
+See `.claude/plans/qa-handoff-protocol.md` for the full protocol.