@overdeck/desktop 0.45.24 → 0.46.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-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-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` |

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

@@ -30,12 +30,12 @@ curl -X POST http://localhost:3011/api/issues/PAN-XXX/sync-main
 ## What It Does
 
 1. Checks for uncommitted changes (blocks if any — must commit, explicitly discard, or surface to the operator first; agents never `git stash`)
-2. Cleans up any stale git locks
-3. Runs `git fetch origin main`
-4. Runs `git merge origin/main`
-5. If clean merge: reports commit count and changed files
-6. If conflicts: wakes the merge-agent specialist to resolve them
-7. After conflict resolution: scans for leftover markers, then reports result
+2. Resolves the workspace's required git repos; monorepos produce one repo root
+3. Cleans up stale git locks in each repo
+4. Fetches and merges each repo's configured target branch sequentially in config order
+5. Stops at the first failed or conflicted repo and marks later repos skipped
+6. If clean: reports aggregate commit/file totals plus one result per repo
+7. If conflicts remain: aborts that repo's merge and reports its conflict files
 
 ## Outcomes
 
@@ -44,14 +44,15 @@ curl -X POST http://localhost:3011/api/issues/PAN-XXX/sync-main
 | Already up to date | Main has no new commits since last sync |
 | Success (N commits) | Clean merge or agent-resolved conflicts |
 | Uncommitted changes | Commit or discard workspace changes first |
-| Conflict (unresolvable) | Agent could not resolve — merge aborted, workspace unchanged |
+| Conflict (unresolvable) | The failing repo's merge is aborted and its conflict files are reported |
+| Per-repo / skipped | Polyrepo output shows each repo's result; repos after the first failure are skipped |
 
 ## Design Decisions
 
 - **Merge, not rebase** — Rebase rewrites SHAs and requires force-push. Merge commits serve as audit markers.
 - **No tests/builds** — Feature branch is WIP. Running tests after sync would fail on pre-existing issues.
 - **No push to remote** — This is a local workspace operation only.
-- **All-or-nothing for polyrepo** — If any repo fails, all are aborted (not implemented yet; sync is per-workspace).
+- **Sequential polyrepo sync** — Required repos sync in config order. The first failure stops iteration; earlier merges remain, later repos are skipped, and output reports every repo's result.
 
 ## Examples
 

package/sync-sources/skills/pipeline-status/SKILL.md

@@ -86,7 +86,11 @@ don't appear via `/api/issues` filtering.
 ### 1. Generate the table
 
 Run this script. It gets the row universe from `GET /api/pipeline/membership`,
-then joins issue titles, review status, tmux, and agent state as annotations.
+then joins issue titles, review status, tmux, and agent state as annotations. A
+bare array is a successful answer. An HTTP 200 object with
+`status: "unavailable"` is a typed blind spot; show its `projectKey`, `reason`,
+and `message`, then stop instead of deriving membership from another source.
+HTTP 503 means the first snapshot is still loading and may be retried later.
 
 ```bash
 python3 - <<'PY'
@@ -100,6 +104,11 @@ issues_data = json.loads(subprocess.check_output(['curl','-s','http://localhost:
 membership = json.loads(subprocess.check_output([
     'curl','-s','http://localhost:3011/api/pipeline/membership?project=overdeck'
 ]))
+if isinstance(membership, dict) and membership.get('status') == 'unavailable':
+    raise SystemExit(
+        'PIPELINE MEMBERSHIP UNAVAILABLE: '
+        f"{membership.get('projectKey')} — {membership.get('reason')}: {membership.get('message')}"
+    )
 issues_by_id = {(i.get('identifier') or '').upper(): i for i in issues_data}
 panissues = []
 for member in membership:

package/sync-sources/skills/workspace-add-repo/SKILL.md

@@ -14,6 +14,7 @@ Run from the workspace root:
 ```bash
 pan workspace add-repo <workspace-id> <repo-name> [repo-name...]
 pan workspace add-repo <workspace-id> --group <group-name>
+pan workspace add-repo <workspace-id> --new <git-url>
 ```
 
 Examples:
@@ -25,8 +26,11 @@ pan workspace add-repo int-123 int-provider-a int-canonical-to-hs
 # Add a named group
 pan workspace add-repo int-123 --group simphony
 
-# Add all repos
+# Add all configured repos
 pan workspace add-repo int-123 --group all
+
+# Register a repo created as part of this issue
+pan workspace add-repo int-123 --new git@github.com:acme/new-service.git
 ```
 
 ## How to decide which repos you need
@@ -40,7 +44,18 @@ pan workspace add-repo int-123 --group all
 The new repos appear as subdirectories in the workspace with feature branches ready.
 Run git commands inside each repo subdirectory.
 
+## New deliverable repositories
+
+Run `--new <git-url>` before cloning or committing in a repository created during the issue. Overdeck clones the project-level source repo, creates the issue feature worktree, and registers it so review, inspection, and merge include it.
+
+If the repo name inferred from the URL is not suitable, pass the workspace directory name before `--new`:
+
+```bash
+pan workspace add-repo int-123 service --new git@github.com:acme/new-service.git
+```
+
 ## Notes
 
+- An unknown repo name without `--new` fails instead of silently reporting success
 - Meta repos (symlinked) are readonly — do NOT commit changes to them
 - Use `--dry-run` first to see what would be added without making changes

package/server/activity-logger-OEUBdfZ8.js

@@ -1,3 +0,0 @@
-import { a as init_activity_logger, n as emitActivityEntrySync, r as emitActivityTtsSync } from "./activity-logger-DDlOIAML.js";
-init_activity_logger();
-export { emitActivityEntrySync, emitActivityTtsSync };

package/server/agent-state-Bc3tzUC8.js

@@ -1,3 +0,0 @@
-import { Bn as clearAgentPausedSync, Hn as clearAgentTroubledSync, Xn as init_agent_state, Yn as getAgentStateSync, dr as setAgentPausedSync } from "./queries-CjNIf-Ub.js";
-init_agent_state();
-export { clearAgentPausedSync, clearAgentTroubledSync, getAgentStateSync, setAgentPausedSync };

package/server/agents-wi9NWzs2.js

@@ -1,3 +0,0 @@
-import { $ as appendActivity, $n as isRole, $t as OHMYPI_AGENT_READY_TIMEOUT_SECONDS, An as buildDefaultResumeContinueMessage, Ar as saveAgentRuntimeState, At as deliverAgentPermissionDecision, B as detectCrashedAgents, Bn as clearAgentPausedSync, Bt as assertWorkspaceStackHealthyForSpawn, C as replayCrashedStandingAgent, Cn as getProviderEnvForModel, Cr as normalizeAgentId, Dr as getAgentRuntimeState, Er as waitForReadySignal, Fn as writeChannelsBridgeMcpConfig, G as resumeAgent, Gn as getAgentDir, Gt as transitionIssueToInProgress, H as restartAgent, Hn as clearAgentTroubledSync, In as GOVERNOR_SLOT_PAUSE_REASON_PREFIX, Jn as getAgentStateFilePath, Kt as transitionIssueToInReview, Ln as SESSION_EXITED_BEFORE_KICKOFF, Mn as decideChannelsForWorkAgent, Mt as deliverResumeMessageWithTranscriptConfirmation, Nn as decideSupervisorForWorkAgent, Nt as setAgentDeliveryMethod, Or as getAgentRuntimeStateSync, Pn as dismissDevChannelsDialog, Qn as isAgentTroubled, Rn as __testInternals, S as contextWindowForModel, Sn as determineModel, Sr as isQualifiedAgentId, T as shouldReplayCompactAtTierRunBoundary, Tn as getProviderTmuxFlags, Tr as waitForAgentIdle, U as buildCompactRecoverySeed, Un as clearYieldForResumeSync, V as recoverAgent, Vn as clearAgentTroubled, Vt as buildAgentLaunchConfig, Wt as retrieveSpawnTimeMemoryContext, X as messageAgent, Yn as getAgentStateSync, Zn as isAgentPaused, a as listRunningAgentsSync, an as getProviderAuthMode, ar as recordAgentFailureSync, at as saveSessionId, b as init_agents, bn as buildCavemanExports, cn as injectPiConversationMemory, cr as saveAgentState, dn as waitForPromptReady, dr as setAgentPausedSync, en as describeOhmypiSpawnFailure, et as getActivity, fr as setAgentYieldedSync, ft as stopAgent, i as listRunningAgents, ir as recordAgentFailure, jn as buildResumeContinueMessage, jt as deliverInitialPromptWithRetry, kt as deliverAgentMessage, ln as roleAgentDefinitionPath, lr as saveAgentStateSync, lt as spawnAgent, mr as writeAgentStateJsonSync, nn as getAgentRuntimeBaseCommand, nr as markAgentStoppedState, nt as getLatestSessionIdSync, o as warnOnBareNumericIssueIds, on as getRoleRuntimeBaseCommand, pr as wipeAgentStateDirs, pt as stopAgentSync, qn as getAgentState, r as listAgentStates, rr as markAgentTroubled, rt as getSessionId, sr as resetAgentFailureCount, t as dropLegacyAgentStatesMissingRoleAsync, tr as markAgentRunningState, tt as getLatestSessionId, ur as setAgentPaused, ut as spawnRun, w as replayStandingAgent, wn as getProviderExportsForModel, wr as resolveAgentTargetSync, x as compactAtTierRunBoundary, xn as buildSpawnEnvForModel, xr as clearReadySignal, z as autoRecoverAgents, zn as clearAgentPaused } from "./queries-CjNIf-Ub.js";
-init_agents();
-export { GOVERNOR_SLOT_PAUSE_REASON_PREFIX, OHMYPI_AGENT_READY_TIMEOUT_SECONDS, SESSION_EXITED_BEFORE_KICKOFF, __testInternals, appendActivity, assertWorkspaceStackHealthyForSpawn, autoRecoverAgents, buildAgentLaunchConfig, buildCavemanExports, buildCompactRecoverySeed, buildDefaultResumeContinueMessage, buildResumeContinueMessage, buildSpawnEnvForModel, clearAgentPaused, clearAgentPausedSync, clearAgentTroubled, clearAgentTroubledSync, clearReadySignal, clearYieldForResumeSync, compactAtTierRunBoundary, contextWindowForModel, decideChannelsForWorkAgent, decideSupervisorForWorkAgent, deliverAgentMessage, deliverAgentPermissionDecision, deliverInitialPromptWithRetry, deliverResumeMessageWithTranscriptConfirmation, describeOhmypiSpawnFailure, detectCrashedAgents, determineModel, dismissDevChannelsDialog, dropLegacyAgentStatesMissingRoleAsync, getActivity, getAgentDir, getAgentRuntimeBaseCommand, getAgentRuntimeState, getAgentRuntimeStateSync, getAgentState, getAgentStateFilePath, getAgentStateSync, getLatestSessionId, getLatestSessionIdSync, getProviderAuthMode, getProviderEnvForModel, getProviderExportsForModel, getProviderTmuxFlags, getRoleRuntimeBaseCommand, getSessionId, injectPiConversationMemory, isAgentPaused, isAgentTroubled, isQualifiedAgentId, isRole, listAgentStates, listRunningAgents, listRunningAgentsSync, markAgentRunningState, markAgentStoppedState, markAgentTroubled, messageAgent, normalizeAgentId, recordAgentFailure, recordAgentFailureSync, recoverAgent, replayCrashedStandingAgent, replayStandingAgent, resetAgentFailureCount, resolveAgentTargetSync, restartAgent, resumeAgent, retrieveSpawnTimeMemoryContext, roleAgentDefinitionPath, saveAgentRuntimeState, saveAgentState, saveAgentStateSync, saveSessionId, setAgentDeliveryMethod, setAgentPaused, setAgentPausedSync, setAgentYieldedSync, shouldReplayCompactAtTierRunBoundary, spawnAgent, spawnRun, stopAgent, stopAgentSync, transitionIssueToInProgress, transitionIssueToInReview, waitForAgentIdle, waitForPromptReady, waitForReadySignal, warnOnBareNumericIssueIds, wipeAgentStateDirs, writeAgentStateJsonSync, writeChannelsBridgeMcpConfig };