create-claude-cabinet 0.42.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` +
@@ -609,15 +612,8 @@ const MODULES = {
     templates: [
       'skills/collab-client',
       'skills/collab-consultant',
-      'skills/engagement',
-      'skills/engagement-progress',
       'skills/engagement-help',
-      'skills/engagement-message',
       'skills/engagement-create',
-      'skills/engagement-edit',
-      'skills/engagement-add',
-      'skills/engagement-status',
-      'skills/engagement-sync',
       'skills/setup-accounts',
       'skills/guide',
       'engagement',
@@ -635,7 +631,6 @@ const MODULES = {
       'scripts/watchtower-lib.mjs',
       'scripts/watchtower-queue.mjs',
       'skills/inbox',
-      'skills/decisions',
       'hooks/watchtower-session-start.sh',
       'scripts/watchtower-build-context.mjs',
       'scripts/watchtower-ring1.mjs',
@@ -657,6 +652,7 @@ const MODULES = {
       'scripts/watchtower-status.sh',
       'skills/briefing',
       'skills/threads',
+      'skills/qa-handoff',
     ],
   },
   mux: {
@@ -666,7 +662,7 @@ const MODULES = {
     default: false,
     lean: false,
     postInstall: 'mux-setup',
-    templates: ['skills/orient/phases/dx-captures.md'],
+    templates: ['skills/orient/phases/dx-captures.md', 'skills/dx-feedback'],
   },
   'engagement-server': {
     name: 'Engagement Server',

package/lib/engagement-setup.js

@@ -177,7 +177,7 @@ function setupEngagement({ dryRun, projectDir } = {}) {
           target_fid    TEXT,
           packet_id     TEXT,
           kind          TEXT NOT NULL
-                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent')),
+                          CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent','packet_opened')),
           author        TEXT NOT NULL,
           verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
           body          TEXT CHECK(body IS NULL OR length(body) <= 10000),

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.42.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/engagement/pib-db-patches/pib-db-schema.sql

@@ -114,7 +114,7 @@ CREATE TABLE IF NOT EXISTS engagement_events (
   target_fid    TEXT,
   packet_id     TEXT,
   kind          TEXT NOT NULL
-                  CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent')),
+                  CHECK(kind IN ('client_feedback','status_push','delegation','approval','note','packet_sent','packet_opened')),
   author        TEXT NOT NULL,
   verdict       TEXT CHECK(verdict IS NULL OR verdict IN ('approve','object','comment','none')),
   body          TEXT CHECK(body IS NULL OR length(body) <= 10000),

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
@@ -227,19 +234,37 @@ create_worktree() {
     }
   }
 
-  # Copy .claude/ into worktree so CC sees worktree-local paths in its
-  # system context. A symlink here causes CC to resolve through to the
-  # main repo path, leaking it into every Read/Edit/Write call.
-  git -C "$wt_path" ls-files .claude/ 2>/dev/null | while IFS= read -r f; do
-    git -C "$wt_path" update-index --assume-unchanged "$f" 2>/dev/null || true
-  done
+  # Copy .claude/ infra into the worktree so CC sees worktree-local paths in
+  # its system context (a symlink makes CC resolve through to the main repo
+  # path, leaking it into every Read/Edit/Write). EXCEPT the authored project
+  # record — .claude/plans/ and .claude/methodology/ — which is real work that
+  # must commit from the worktree. Those stay as normal git-tracked files,
+  # left exactly as `git worktree add` checked them out from HEAD. See
+  # .claude/rules/artifacts-of-thought.md.
+  git -C "$wt_path" ls-files .claude/ 2>/dev/null \
+    | grep -vE '^\.claude/(plans|methodology)/' \
+    | while IFS= read -r f; do
+        git -C "$wt_path" update-index --assume-unchanged "$f" 2>/dev/null || true
+      done
   if [[ -d "$proj_path/.claude" ]]; then
-    rm -rf "$wt_path/.claude"
-    cp -R "$proj_path/.claude" "$wt_path/.claude"
-    # Exclude copied .claude/ from worktree's git status (it's infra, not work)
+    # Refresh infra subdirs from main, one top-level entry at a time, never
+    # the authored-record dirs (leave the worktree's HEAD-checked-out copies).
+    local entry name
+    for entry in "$proj_path"/.claude/*; do
+      [[ -e "$entry" ]] || continue
+      name=$(basename "$entry")
+      [[ "$name" == "plans" || "$name" == "methodology" ]] && continue
+      rm -rf "$wt_path/.claude/$name"
+      cp -R "$entry" "$wt_path/.claude/$name"
+    done
+    # Hide infra from the worktree's git status, but keep authored records
+    # visible so new design docs created in a worktree show up and commit.
     local wt_gitdir
     wt_gitdir=$(git -C "$wt_path" rev-parse --git-dir 2>/dev/null)
-    [[ -n "$wt_gitdir" ]] && mkdir -p "$wt_gitdir/info" && echo '.claude/' >> "$wt_gitdir/info/exclude"
+    if [[ -n "$wt_gitdir" ]]; then
+      mkdir -p "$wt_gitdir/info"
+      { echo '.claude/*'; echo '!.claude/plans/'; echo '!.claude/methodology/'; } >> "$wt_gitdir/info/exclude"
+    fi
   fi
   for f in .mcp.json .claudeignore; do
     [[ -f "$proj_path/$f" ]] && ln -sf "$proj_path/$f" "$wt_path/$f"
@@ -408,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() {
@@ -503,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
@@ -529,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
 }
@@ -566,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
@@ -1023,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 ""
@@ -1306,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   │