@overdeck/desktop 0.45.24 → 0.47.0

package/sync-sources/dev-skills/pan-dashboard-restart/SKILL.md

@@ -16,10 +16,12 @@ allowed-tools:
   - Read
 ---
 
-# Overdeck Dashboard Restart (production-safe, detached)
+# Overdeck Dashboard Restart (production-safe)
 
 The dashboard the browser talks to is the **pre-built `dist/dashboard/server.js` running under Node 22**, started from the **primary repo checkout** (NOT a `workspaces/feature-*` copy). It serves both the built frontend and the API on one port. **Never** run the production server via `npm run dev`, `tsx`, `vite`, or Bun — that violates the dashboard-node22-only rule (node-pty native addon + circular ESM). `pan dev` is the *development* path (vite HMR for the frontend + Node server); `pan up` is the *production* path.
 
+The **supervisor sidecar** (`overdeck-supervisor.service`, port 3012) owns the dashboard lifecycle: it health-checks the server and respawns it as a systemd unit with the full env from `config.yaml`. Restart **through** it (`POST :3012/restart-dashboard`) — a manually spawned server is a duplicate it will replace, and racing it costs minutes of churn. The manual detached start below is the fallback for when the supervisor itself is down, and it must carry the Traefik env block (gotcha 7).
+
 ## When to use this skill
 
 `pan up` / `pan restart` is the normal path. Reach for this manual procedure **only** when:
@@ -35,33 +37,53 @@ The dashboard the browser talks to is the **pre-built `dist/dashboard/server.js`
 3. **Exactly ONE server.** Two servers = two deacons racing the same `~/.overdeck` state (the duel), and the PAN-1625 janitor reaps/churns extras. A single port-owner is left alone.
 4. **Work-agent tmux sessions survive a dashboard restart** — they are separate processes on the `overdeck` socket. Restarting the dashboard does NOT kill agents; the new deacon reconciles them as running.
 5. **Run from the primary repo**, not a workspace. If `readlink /proc/<pid>/cwd` is a `workspaces/feature-*` path, a workspace dashboard hijacked the port — kill it and restart from the primary checkout.
+6. **The supervisor sidecar owns the dashboard lifecycle.** `overdeck-supervisor.service` (port 3012) health-checks the dashboard and respawns it as a systemd unit with the full env from `config.yaml`. A manual server you spawn yourself is a duplicate it will replace — so restart THROUGH the supervisor (below) instead of racing it, and never kill a systemd-parented server that carries `OVERDECK_TRAEFIK_*` env: that is the supervisor's correctly-configured replacement, not a stray.
+7. **A bare `node dist/dashboard/server.js` launch 403s the domain on dists without the config fallback.** `getTrustedOrigins()` reads the launch env; no `OVERDECK_TRAEFIK_*` → only loopback is trusted → `/ws/*` 403s `https://overdeck.localhost` → the dashboard hangs on "Reconnecting to the dashboard…" while `localhost:3011` works. `/api/health` returns 200 the whole time because it does no origin validation. Newer dists fall back to `config.yaml` (commit `e86d125071`), but always launch WITH the env block below — it costs nothing and works on every dist.
 
 ## Procedure
 
 ```bash
 cd ~/Projects/overdeck   # the PRIMARY checkout
 
+# 0. Domain comes from config.yaml — the same source pan up / the supervisor use
+DOMAIN=$(awk '/^traefik:/{f=1} f && /^  domain:/{print $2; exit}' ~/.overdeck/config.yaml)
+DOMAIN=${DOMAIN:-overdeck.localhost}
+
 # 1. Rebuild ONLY if you changed server/lib source (the Node 22 dist is what runs)
 npm run build
 
-# 2. Find the live dashboard port + PID, kill by EXPLICIT PID (never pkill -f self-matching)
-PORT_LINE=$(ss -ltnp 2>/dev/null | grep -E ':(3010|3011|3012)\b' | grep node | head -1)
-OLD=$(echo "$PORT_LINE" | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
-echo "current server: pid=$OLD"
+# 2. PREFERRED: restart through the supervisor (it owns the lifecycle, sets the
+#    correct env from config.yaml, and systemd-manages the result). Skip to step 3
+#    only when port 3012 refuses connections.
+curl -s -X POST http://127.0.0.1:3012/restart-dashboard   # → 202 Accepted
+
+# 3. Supervisor down? Manual detached start — WITH the Traefik env block (gotcha 7).
+#    Kill the old server by EXPLICIT PID (never pkill -f self-matching).
+OLD=$(ss -ltnp 2>/dev/null | grep -E ':3011\b' | grep node | grep -oE 'pid=[0-9]+' | head -1 | cut -d= -f2)
 [ -n "$OLD" ] && kill -TERM "$OLD"
 for i in $(seq 1 15); do { [ -n "$OLD" ] && kill -0 "$OLD" 2>/dev/null; } && sleep 1 || break; done
 { [ -n "$OLD" ] && kill -0 "$OLD" 2>/dev/null; } && kill -9 "$OLD"
 
-# 3. Start ONE fully-detached server (survives the shell; not a child of any wrapper).
-#    PORT is inherited from the environment; set it explicitly if you need a specific port.
-setsid bash -c 'exec node dist/dashboard/server.js' > /tmp/pan-dash.log 2>&1 < /dev/null &
+setsid env \
+  DASHBOARD_URL="https://${DOMAIN}" OVERDECK_TRAEFIK_ENABLED=1 \
+  OVERDECK_TRAEFIK_DOMAIN="${DOMAIN}" OVERDECK_TRUSTED_ORIGINS="https://${DOMAIN}" \
+  DASHBOARD_PORT=3010 API_PORT=3011 PORT=3011 OVERDECK_MODE=production \
+  bash -c 'exec node dist/dashboard/server.js' > /tmp/pan-dash.log 2>&1 < /dev/null &
 
-# 4. Verify health (Traefik routes overdeck.localhost -> the API port)
+# 4. Verify health AND the WebSocket origin path. /api/health does no origin
+#    validation — it returns 200 even while /ws/* 403s the domain (gotcha 7).
+#    The WS check is the only one that proves the browser can actually connect.
 for i in $(seq 1 40); do
-  code=$(curl -sk -o /dev/null -w '%{http_code}' --max-time 3 https://overdeck.localhost/api/health 2>/dev/null)
+  code=$(curl -sk -o /dev/null -w '%{http_code}' --max-time 3 "https://${DOMAIN}/api/health" 2>/dev/null)
   [ "$code" = 200 ] && { echo "healthy after ${i}s"; break; }
   sleep 1
 done
+ws=$(curl -sk -o /dev/null -w '%{http_code}' --http1.1 --max-time 5 \
+  -H "Origin: https://${DOMAIN}" -H "Connection: Upgrade" -H "Upgrade: websocket" \
+  -H "Sec-WebSocket-Version: 13" -H "Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==" \
+  "https://${DOMAIN}/ws/rpc")
+[ "$ws" = 101 ] && echo "WS origin OK" \
+  || echo "WS origin FAILED (got $ws) — server does not trust the domain; relaunch with the env block (or a dist with the config fallback)"
 
 # 5. Confirm SINGLE instance, correct dist path (primary repo, not a workspace)
 ss -ltnp 2>/dev/null | grep -E ':(3010|3011)\b'
@@ -79,6 +101,7 @@ readlink -f /proc/$NEW/cwd      # must be the primary repo path
 ## Verify success
 
 - `overdeck.localhost/api/health` returns `{"status":"ok"}` and `curl http://localhost:<port>/api/health` returns 200.
+- **The WebSocket origin check returns 101** (procedure step 4). Health alone is not success — a server missing its Traefik env is healthy on `/api/health` and dead to the browser at the same time.
 - Exactly one **host-level** `node dist/dashboard/server.js` process; its `/proc/<pid>/cwd` is the primary repo.
   **Do not count workspace-container servers.** Each running workspace devcontainer has its own `server` service whose `dist/dashboard/server.js` process is visible in host `ps` — those are legitimate read/UI peers (cwd `/workspaces/overdeck`, parent `containerd-shim`, `OVERDECK_DISABLE_DEACON=1`), NOT duplicate dashboards and NOT a single-deacon hazard. Seeing N+1 server processes with N containers up is the healthy state. Container-aware census:
   ```bash
@@ -89,6 +112,7 @@ readlink -f /proc/$NEW/cwd      # must be the primary repo path
   done
   ```
   Exactly one `HOST` line, with cwd = the primary repo, is success. Multiple `HOST` lines = a real orphan (the deacon's orphan-server reaper, PAN-1625, will also catch it).
+- **Do not kill the supervisor's server.** If a HOST server is parented to systemd and its env contains `OVERDECK_TRAEFIK_DOMAIN`, it is the supervisor's correctly-configured managed instance (gotcha 6). If you spawned a manual server and then see a second one appear, kill YOURS (the one without the Traefik env), never the supervisor's.
 - Agent tmux sessions (`tmux -L overdeck list-sessions`) are intact.
 - The deacon log (`/tmp/pan-dash.log` or the dashboard log) shows a single `Deacon started` and patrols advancing — no `received SIGTERM` loop.
 

package/sync-sources/hooks/linear-mcp-auth-hook

@@ -0,0 +1,97 @@
+#!/bin/bash
+# PostToolUse + PostToolUseFailure hook for structured Linear MCP OAuth
+# intervention events (PAN-2997). Registered with matcher mcp__linear__.* for
+# both hook events: PostToolUse fires after a tool call SUCCEEDS, while a
+# failed MCP call — the motivating OAuth-expired case — fires
+# PostToolUseFailure with a top-level `error` field and no tool_response.
+#
+# Never breaks Claude Code: every failure exits 0 silently.
+
+set +e
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+command -v jq >/dev/null 2>&1 || exit 0
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+[[ "$TOOL_NAME" == mcp__linear__* ]] || exit 0
+
+EVENT_NAME=$(printf '%s' "$INPUT" | jq -r '.hook_event_name // "PostToolUse"' 2>/dev/null)
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=pan-hook-lib.sh
+. "$SCRIPT_DIR/pan-hook-lib.sh" 2>/dev/null || exit 0
+declare -f pan_resolve_agent_id >/dev/null 2>&1 || exit 0
+pan_resolve_agent_id || exit 0
+declare -f pan_emit_event >/dev/null 2>&1 || exit 0
+
+MARKER_DIR="${OVERDECK_HOME:-$HOME/.overdeck}/agents/$AGENT_ID"
+MARKER="$MARKER_DIR/linear-mcp-auth-pending"
+
+# Auth-failure classifier. The 401 alternative requires a non-identifier
+# boundary on both sides so ordinary Linear data (MIN-401, "AUR-4015") can
+# never match; prose phrases are matched as words.
+is_auth_error_text() {
+  printf '%s' "$1" | grep -Eiq 'requires authentication|not authenticated|unauthorized|(^|[^0-9A-Za-z-])401([^0-9]|$)'
+}
+
+emit_required() {
+  local auth_url="$1"
+  local body
+  body=$(jq -n --arg authUrl "$auth_url" '{
+    kind: "linear_mcp_auth_required",
+    authUrl: (if $authUrl == "" then null else $authUrl end)
+  }' 2>/dev/null) || return 0
+  pan_emit_event "$AGENT_ID" "$body" >/dev/null 2>&1 || true
+  mkdir -p "$MARKER_DIR" 2>/dev/null || true
+  : > "$MARKER" 2>/dev/null || true
+}
+
+emit_healthy_if_pending() {
+  [ -f "$MARKER" ] || return 0
+  local body
+  body=$(jq -n '{kind: "linear_mcp_auth_healthy"}' 2>/dev/null) || return 0
+  pan_emit_event "$AGENT_ID" "$body" >/dev/null 2>&1 || true
+  rm -f "$MARKER" 2>/dev/null || true
+}
+
+if [ "$EVENT_NAME" = "PostToolUseFailure" ]; then
+  # Documented failure-event shape: top-level `error`, no tool_response.
+  ERROR_TEXT=$(printf '%s' "$INPUT" | jq -r '.error // ""' 2>/dev/null)
+  if is_auth_error_text "$ERROR_TEXT"; then
+    emit_required ''
+  fi
+  exit 0
+fi
+
+# PostToolUse — successful tool call.
+RESPONSE=$(printf '%s' "$INPUT" | jq -r '
+  (.tool_response // .tool_result // "")
+  | if type == "string" then . else tojson end
+' 2>/dev/null)
+[ -n "$RESPONSE" ] || RESPONSE=''
+
+if [ "$TOOL_NAME" = 'mcp__linear__authenticate' ]; then
+  AUTH_URL=$(printf '%s\n' "$RESPONSE" \
+    | grep -Eo 'https://linear\.app/oauth/authorize[^"[:space:]<>]*' 2>/dev/null \
+    | sed -n '1p')
+  emit_required "$AUTH_URL"
+  exit 0
+fi
+
+# An MCP server can report a failure inside a successful hook event as an
+# error-shaped payload (isError: true, or an `error` member). Only those
+# payloads are auth-classified — ordinary successful result data (issue
+# identifiers like MIN-401, titles mentioning 401s or "unauthorized") never
+# reaches this check and simply clears any pending intervention below.
+ERROR_SHAPED=$(printf '%s' "$INPUT" | jq -r '
+  (.tool_response // .tool_result // {})
+  | if type == "object" and ((.isError == true) or (.error != null)) then "yes" else "" end
+' 2>/dev/null)
+
+if [ -n "$ERROR_SHAPED" ] && is_auth_error_text "$RESPONSE"; then
+  emit_required ''
+  exit 0
+fi
+
+emit_healthy_if_pending
+exit 0

package/sync-sources/rules/ask-user-question-self-contained.md

@@ -0,0 +1,9 @@
+---
+scope: universal
+---
+### Make every AskUserQuestion prompt self-contained
+
+Every AskUserQuestion must stand alone because the operator may answer from a
+dashboard dialog without the preceding transcript. State the situation in one
+or two sentences, ask for the decision in plain language, and describe each
+option by the consequence of choosing it rather than by a label alone.

package/sync-sources/skills/pan-close/SKILL.md

@@ -35,15 +35,17 @@ Each overridable row has one explicit acceptance flag:
 ```text
 --accept-review       Row 1: review passed
 --accept-tests        Row 2: tests passed
---accept-verification Row 3: branch verification passed at lastVerifiedCommit
+--accept-verification Row 3: branch verification passed
 --accept-merged       Row 4: PR merged on the forge
 --accept-post-merge   Row 5: post-merge lifecycle completed
 --accept-main-verify  Row 6: merge commit verified on main
 --accept-deploy       Row 7: live dashboard build includes the merge
 ```
 
-An acceptance records the flag, operator/agent identity, and timestamp in the
-issue close-out record. Use it only when the missing evidence is understood:
+An acceptance records the flag, operator identity, and timestamp in the issue
+close-out record. The autonomous flywheel may run a clean close-out, but it cannot
+use `--accept-*`; an operator must apply every override after reviewing the miss.
+Use an override only when the missing evidence is understood:
 
 ```bash
 pan close PAN-1234 --force

package/sync-sources/skills/pan-merge/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: pan-merge
-description: "pan merge — cancel pending Flywheel auto-merges during the cooldown window"
+description: "pan merge — cancel actionable Flywheel auto-merge rows"
 triggers:
   - pan merge
   - cancel auto-merge
@@ -12,7 +12,7 @@ allowed-tools:
 
 # pan merge
 
-Use this skill when cancelling a pending Flywheel auto-merge before its cooldown expires.
+Use this skill when cancelling a pending, blocked, or failed Flywheel auto-merge row.
 
 ## Commands
 
@@ -26,12 +26,14 @@ pan merge cancel <id>
 pan merge cancel PAN-123
 ```
 
-Cancels a pending Flywheel auto-merge for the issue id. The command calls the dashboard `DELETE /api/flywheel/auto-merge/:id` endpoint, removes the entry from the active pending list, and announces `auto-merge cancelled for <issueId>`.
+Cancels one actionable Flywheel auto-merge row for the issue id. The command calls the dashboard `DELETE /api/flywheel/auto-merge/:id` endpoint, removes that row from the active or problems list, and announces `auto-merge cancelled for <issueId>`.
 
-If the cooldown has already expired and the executor transitioned the entry to `merging`, the command exits non-zero and reports that the merge is already in progress. If there is no active pending auto-merge for the issue, it exits non-zero with `No pending auto-merge for <id>`.
+An issue can hold duplicate rows from separate scheduling attempts. When more actionable rows remain, the success message reports the count and tells you to re-run `pan merge cancel <id>` to clear the next row; repeat until the normal success message contains no remaining-row notice.
+
+If the cooldown has already expired and the selected row transitioned to `merging`, the command exits non-zero and reports that the merge is already in progress. If there is no actionable auto-merge row for the issue, it exits non-zero with `No pending auto-merge for <id>`.
 
 ## Guardrails
 
-- Use this only during the five-minute auto-merge cooldown window.
+- A pending row is cancellable during the five-minute cooldown; blocked and failed rows remain cancellable afterward.
 - Do not use raw HTTP when the CLI is available; the CLI supplies the dashboard internal token.
 - A `merging` entry cannot be cancelled safely; let the merge pipeline finish or fail visibly.

package/sync-sources/skills/pan-peer-review/SKILL.md

@@ -0,0 +1,195 @@
+---
+name: pan-peer-review
+description: "Workflow: spawn an independent adversarial reviewer on a different model to verify or refute your own findings. EXPENSIVE — invoke only when the operator explicitly asks for a peer/second-opinion review."
+triggers:
+  - peer review my findings
+  - get independent feedback
+  - second opinion from another model
+  - have another model review this
+  - adversarial review of my analysis
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+---
+
+# pan peer-review — independent second opinion from another model
+
+Spawn a conversation on a **different model family** to adversarially verify or
+refute an analysis you produced, then read its findings back. Use it when a
+conclusion is expensive to get wrong: a root-cause diagnosis about to become a
+PRD, a refactor plan, a security claim, a "this is safe to merge" call.
+
+## ⚠️ Operator-invoked only — never launch this on your own initiative
+
+**Do not start a peer review because you think your work would benefit from
+one.** A peer review spawns a second full agent that reads source, burns a
+frontier-model context, and runs for many minutes. That cost is the operator's
+call, not yours.
+
+Launch only when the operator explicitly asks — "get a second opinion", "run
+this by another model", "have K3 review it", "peer review this". If you believe
+a review is warranted and they have not asked, say so in one sentence and let
+them decide.
+
+Corollary: never chain reviews. One reviewer, one pass. If the reviewer
+disagrees with you, bring the disagreement back to the operator rather than
+spawning a third model to break the tie.
+
+## Why a different model, and what "independent" buys you
+
+A reviewer on the same model as the author tends to agree — it reconstructs the
+same reasoning from the same priors. The value comes from a different family
+reading the same source: Opus/Fable reviewing GPT work, K3 reviewing Claude
+work, GPT reviewing Claude work.
+
+Pick the reviewer by contrast with whoever produced the analysis:
+
+| Author | Good reviewer |
+| --- | --- |
+| Claude (Opus/Fable/Sonnet) | `k3` (Kimi), `gpt-5.6-sol` |
+| GPT | `claude-opus-5`, `k3` |
+| Kimi | `claude-opus-5`, `gpt-5.6-sol` |
+
+Never pass `--harness`. Harness routing is config-owned and the operator sets it
+deliberately; `--model` is the only routing flag this workflow uses, and only
+because the operator asked for a specific reviewer.
+
+Leave reasoning effort alone. It inherits `high`, which is the right tier —
+never raise it to `xhigh`/`max` for a review.
+
+## The workflow
+
+### 1. Write the brief to a file — never into the focus
+
+The `pan handoff` focus is hard-capped at 500 characters. A real review brief is
+thousands. Write it to a file in the reviewer's future cwd and let the focus
+point at it.
+
+A brief that produces a useful review has these parts:
+
+- **Adversarial framing, stated first.** "Assume each claim may be wrong. A
+  claim that survives refutation is worth more than agreement. Do not soften
+  findings to be agreeable." Without this you get a politeness echo.
+- **Read-only rules.** No edits to source, no commits, no `pan` commands, no
+  POST/DELETE. The reviewer writes exactly one file: its findings.
+- **A glossary** of every term of art before you use it — the reviewer has none
+  of your conversation's context.
+- **Absolute paths for evidence outside the worktree** — live workspaces, logs,
+  config, API endpoints. The reviewer cannot find them otherwise.
+- **Each claim stated separately**, with the exact file:line it rests on, the
+  evidence you used, and the fix you propose.
+- **Per-claim questions that invite refutation** — "does the fix actually
+  terminate the loop?", "what is the blast radius?", "would this regress the
+  monorepo path?". Generic "please review" produces generic output.
+- **Cross-cutting questions**, including at least one that asks for things you
+  did *not* find: "search for every other site with this pattern and report any
+  beyond the ones named here."
+- **An explicit output contract** — a verdict vocabulary (CONFIRMED /
+  PARTIALLY CONFIRMED / REFUTED / CANNOT VERIFY), where to write findings, and
+  a request to also summarize in-conversation.
+
+### 2. Create a detached worktree
+
+The reviewer needs the source, isolated from your working tree. Spawned agents
+must never get the primary worktree as their cwd.
+
+```bash
+git worktree add --detach /home/eltmon/Projects/hoff-<slug> main
+```
+
+`--detach` is required: a plain `git worktree add <path> main` fails with
+`fatal: 'main' is already used by worktree at ...` whenever main is checked out
+somewhere, which on a dev machine is always. Detached HEAD is correct here —
+the reviewer never commits.
+
+Then write the brief into that worktree.
+
+### 3. Launch the handoff
+
+```bash
+pan handoff --model <reviewer-model> --cwd /home/eltmon/Projects/hoff-<slug> self \
+  "Read REVIEW-BRIEF.md in your cwd FIRST and follow it exactly. You are an INDEPENDENT ADVERSARIAL reviewer — verify or refute each claim against real source and critique each proposed fix. Read-only. Write findings to FEEDBACK-<model>.md."
+```
+
+`self` must come before the focus text. Omitting it makes the CLI read your
+focus as a conversation name and fail with `Conversation not found`.
+
+**The command can exceed a two-minute tool timeout while the handoff document is
+authored — that is normal and does not mean it failed.** Either run it with
+`run_in_background: true`, or let it time out and verify the spawn afterwards:
+
+```bash
+tmux -L overdeck list-sessions | grep conv-
+```
+
+### 4. Correct the frame — the step everyone skips
+
+`pan handoff` seeds the new conversation with an **authored handoff document
+describing your session's state and open work**. It does not deliver your focus
+as an instruction. The reviewer therefore wakes up believing it is *you,
+continuing your work* — and if your open-work list said "launch a peer review",
+it will try to launch one, recursively.
+
+Check what it actually received before assuming it is reviewing:
+
+```bash
+tmux -L overdeck capture-pane -t <conv-id> -p -S -30
+```
+
+If it is acting as a continuation rather than as a reviewer, correct it with
+`pan tell` (never raw tmux keystroke injection):
+
+```bash
+pan tell <conv-id> "STOP. You are NOT continuing that conversation's work. You ARE the independent reviewer it wanted to spawn. Read <brief path> and follow it exactly. Read-only. Begin now."
+```
+
+Budget for this step every time. Treat the handoff document as context the
+reviewer happens to have, and your `pan tell` as the actual task assignment.
+
+### 5. Wait on the artifact, not the pane
+
+Poll for the findings file rather than watching output scroll:
+
+```bash
+until [ -s /home/eltmon/Projects/hoff-<slug>/FEEDBACK-<model>.md ]; do sleep 20; done
+```
+
+Run that in the background so you can keep working.
+
+### 6. Read the findings critically, then report
+
+The reviewer is not an oracle. Treat REFUTED verdicts as claims to check, the
+same way you asked it to treat yours — a reviewer that misreads a call site can
+be confidently wrong. Verify anything that would change what you do next.
+
+Report back to the operator with: what the reviewer confirmed, what it refuted
+and whether you agree, what it found that you missed, and where you still
+disagree after checking. Never launder its output as consensus.
+
+### 7. Clean up
+
+```bash
+git worktree remove /home/eltmon/Projects/hoff-<slug>
+```
+
+Keep the findings file if it is going into an issue or PRD — copy it out before
+removing the worktree.
+
+## Failure modes and what they mean
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| `fatal: 'main' is already used by worktree at ...` | `git worktree add` without `--detach` | Add `--detach` |
+| `Conversation not found` | Focus text passed without `self` first | `pan handoff ... self "<focus>"` |
+| `Focus is N characters — the limit is 500`, no conversation created | Brief crammed into the focus | Put the brief in a file, point the focus at it |
+| Handoff command times out at 2 minutes | Handoff document authoring is slow | Normal — verify the spawn with `tmux -L overdeck list-sessions` |
+| Reviewer starts doing your open-work list, or tries to spawn its own review | It received the handoff doc, not your focus | `pan tell` it the real task (step 4) |
+| Reviewer agrees with everything | Brief lacked adversarial framing, or reviewer shares the author's model family | Rewrite the framing; pick a different family |
+| `state.json has no issueId` on `pan tell` | Informational — conversations have no issue | Ignore; the message still delivers |
+
+## Related
+
+- `/pan-handoff` — the underlying command and its full semantics
+- `/pan-code-review` — reviewing a *diff*; this skill reviews an *analysis*
+- `/pan-tell` — the sanctioned way to message a running conversation

package/sync-sources/skills/pan-release/SKILL.md

@@ -88,6 +88,63 @@ First-time setup for a brand-new package (npm org creation, the one-time
 bootstrap publish, configuring the Trusted Publisher) and full publish
 troubleshooting live in `docs/RELEASING.md`.
 
+## Releasing as an agent (guards you will hit)
+
+An agent cutting a release trips guards a human operator never sees. All three
+have sanctioned levers — **never reach for `--no-verify`**, which is a one-way
+door.
+
+**1. The commit path guard.** `scripts/guard-flywheel-orchestrator-commit.sh`
+(via `.husky/pre-commit`) refuses a `flywheel-orchestrator` commit that touches
+anything outside `docs/FLYWHEEL-STATE.md` and the state paths — and a release
+commit necessarily touches three `package.json` files. The guard's own
+operator-directed escape hatch is:
+
+```bash
+OVERDECK_OPERATOR_COMMIT=1 pan release stable --version X.Y.Z
+```
+
+It mirrors `OVERDECK_OPERATOR_PUSH=1` for the push guard. Use it only when the
+operator has actually directed the release.
+
+**2. The push guard.** `scripts/guard-agent-main-push.sh` exempts `conv-`
+prefixed agent ids but not pipeline roles, so pushing `main` and the tag needs:
+
+```bash
+OVERDECK_OPERATOR_PUSH=1 git push origin main
+OVERDECK_OPERATOR_PUSH=1 git push origin vX.Y.Z
+```
+
+**3. Preflight tests failing for the wrong reason (PAN-3081 / PAN-3189).** The
+per-agent `~/.overdeck/agents/<id>/git-guard` shim used to intercept
+`git reset --hard` and `git rebase` *inside test fixtures that legitimately run
+them against their own temp repos*, so preflight reported failures that did not
+exist — **10 failures with the shim on `PATH`, 0 without.**
+
+PAN-3189 fixed both halves at the source: the guard now fires only for git
+commands targeting the agent's own worktree, and each launcher strips any
+inherited guard directory from `PATH` before installing its own. A session
+spawned since that landed needs no workaround.
+
+A session started *before* it — or any shell that inherited an old shim — can
+still see the artifact. Check first, and only reach for the workaround if the
+shim is actually there:
+
+```bash
+echo $PATH | tr ':' '\n' | grep git-guard    # expect: your own agent's dir, or nothing
+CLEAN=$(echo $PATH | tr ':' '\n' | grep -v git-guard | paste -sd:)
+PATH="$CLEAN" npm test          # must be genuinely green
+pan release stable --version X.Y.Z --skip-tests
+```
+
+`--skip-tests` is legitimate **only** when you have run the suite clean and seen
+it pass. It skips a corrupted measurement, not the verification itself.
+
+**Ordering note.** If `git push origin main` is rejected because the remote moved
+ahead, merge rather than rebase (`git rebase` is blocked by the agent git guard)
+and push again. Push the tag even if `main` is momentarily behind — the tag is
+its own ref and triggers the publish workflow independently.
+
 ## Notes
 
 - Stable is for “ship this to normal users now.”

package/sync-sources/skills/pan-reload/SKILL.md

@@ -11,17 +11,17 @@ Use this after code changes that should run in the local Overdeck dashboard.
 
 ```bash
 pan reload
-pan reload --force   # explicitly bypass the agent deploy-window gate
+pan reload --force   # explicit operator bypass of the deploy-window gate
 ```
 
-`pan reload` runs `bun install` and then `npm run build` first. If either fails, it leaves the current dashboard running and exits non-zero. If both succeed, it restarts the dashboard and waits for `http://127.0.0.1:3011/api/health`.
+`pan reload` fetches `origin/main`, creates a temporary detached worktree at that commit, and runs `bun install` followed by `npm run build` there — never in the primary working tree. If the primary tree has uncommitted changes or its `HEAD` differs from `origin/main`, the command notes that those changes are excluded and continues with the canonical build. If installation or build fails, it leaves the current dashboard running and exits non-zero; after a successful build, it keeps the detached worktree as the active deployment root and launches its `dist/dashboard/server.js` with its canonical runtime dependencies and workspace packages intact, leaves the primary checkout's `node_modules/` untouched, refreshes the primary `dist/` CLI mirror with a dependency link back to that deployment root, then restarts the dashboard and waits for `http://127.0.0.1:3011/api/health`. Deployments alternate between two fixed generation worktrees. A failure before the new process is left running restores the prior marker and primary `dist/` and removes the failed generation. A health timeout keeps the new deployment active because the dashboard is deliberately left running so a slow boot can finish or a failed boot can be inspected. Retries still reuse one of the two fixed slots, so failures cannot accumulate unbounded dependency trees.
 
 `npm run build` already rebuilds the dashboard **server** bundle (via `build-post-cli.mjs` → `build:dashboard:server:bundle`), so `pan reload` picks up server/deacon code changes — you do **not** need a separate `npm run build:dashboard:server`. The `bun install` step runs first so a merge/rebase that added a runtime dependency (e.g. `chokidar`) can't produce a freshly-built server that boot-crashes with `ERR_MODULE_NOT_FOUND`.
 
 ## Options
 
 - `--skip-build` — restart the current bundle without running `bun install` or `npm run build`.
-- `--force` — bypass the deploy-window gate for an agent-issued reload. Without it, active verification, merge, post-merge, flywheel, restart, or `pan dev` ownership refuses the reload because it would disconnect live conversations and terminals.
+- `--force` — explicitly bypass the deploy-window gate. Without it, a refused agent-issued reload queues the deploy, reports its age and distinct verification blockers, and self-fires at the next safe verification boundary. Do not retry-loop or use `--force` to interrupt healthy verification; reserve the bypass for exceptional operator recovery.
 - `--health-timeout <ms>` — set the dashboard health-check budget. The default is `30000`.
 - `--no-deacon` — restart without Cloister/Deacon auto-start.
 

package/sync-sources/skills/pan-restart/SKILL.md

@@ -34,7 +34,7 @@ pan restart --traefik
 pan restart --full       # nuclear — stops & restarts everything
 
 # Explicit force cases
-pan restart --force              # bypass the agent deploy-window gate
+pan restart --force              # explicit operator bypass of the deploy-window gate
 pan restart --cliproxy --force   # redownload the pinned CLIProxy binary
 ```
 
@@ -61,9 +61,10 @@ server is a failure, not a successful restart.
 - `pan restart --dashboard` NEVER touches CLIProxy, Traefik, or TLDR — that
   scope contract is enforced by tests.
 - Agent-issued dashboard and full restarts consult the deploy-window gate before
-  acquiring the restart lock. Active verification, merge, post-merge, flywheel,
-  restart, or `pan dev` ownership refuses the restart because it would disconnect
-  live conversations and terminals; `--force` explicitly bypasses this gate.
+  acquiring the restart lock. A refusal queues the deploy, reports its age and
+  distinct verification blockers, and self-fires at the next safe verification
+  boundary. Do not retry in a loop or use `--force` to interrupt healthy verification;
+  `--force` remains the explicit operator bypass for exceptional recovery.
 - For `--cliproxy`, `--force` has a separate meaning: it redownloads the binary at
   the pinned version before restarting it.
 - If the dashboard restart fails, shared sidecars are left running so recovery

package/sync-sources/skills/pan-review/SKILL.md

@@ -1,12 +1,13 @@
 ---
 name: pan-review
-description: "pan review <subcommand> — manage the code review lifecycle: list pending work, set quick/full mode, re-request review, reset/abort/restart review cycles"
+description: "pan review <subcommand> — manage the code review lifecycle: list pending work, re-request review, heal status drift, reset/abort/restart review cycles"
 triggers:
   - pan review
   - review pending
   - request review
   - review mode
   - reset review
+  - resync review
   - restart review
   - abort review
   - code review lifecycle
@@ -30,6 +31,7 @@ pan review pending --blocked                       # List blocked review/test/me
 pan review request <id>                            # Re-request review after fixing feedback
 pan review mode <id> <quick|full>                  # Set this issue's review mode override
 pan review reset <id> [--session]                  # Reset review/test/merge cycles (human override)
+pan review resync <id>                             # Re-emit canonical status to heal dashboard drift
 pan review abort <id>                              # Kill all running reviewers, leave worker idle
 pan review restart <id> [--model <m>] [--role <r>] # Kill reviewers and dispatch a fresh review pipeline
 ```
@@ -54,6 +56,9 @@ pan review restart <id> [--model <m>] [--role <r>] # Kill reviewers and dispatch
   pipeline can be re-dispatched from scratch. Use when the saved state is
   inconsistent or corrupt. `--session` additionally clears the saved Claude
   session for each reviewer so they restart with a clean conversation.
+- **`resync <id>`** — Reads the canonical review status and re-emits it without
+  changing any verdict. Use when an issue passed review but is missing from
+  Awaiting Merge or its actions are wrongly gated by stale dashboard state.
 - **`abort <id>`** — Kills any currently running reviewer sessions but
   leaves the work agent alone. Use when reviewers are stuck or running
   against the wrong commit and you want to halt without resetting state.
@@ -77,6 +82,7 @@ pan review restart <id> [--model <m>] [--role <r>] # Kill reviewers and dispatch
 | This issue needs the full review convoy | `pan review mode <id> full` |
 | Return an issue to default quick review | `pan review mode <id> quick` |
 | Pipeline state is inconsistent, need a clean slate | `pan review reset <id>` |
+| Issue passed but is missing from Awaiting Merge or actions are wrongly gated | `pan review resync <id>` |
 | Same as above plus reviewer Claude sessions are bad | `pan review reset <id> --session` |
 | Reviewer is hung, just kill it | `pan review abort <id>` |
 | Reviewer crashed, want a fresh convoy with a different model | `pan review restart <id> --model gpt-5.4` |