@overdeck/desktop 0.45.12 → 0.45.13

package/sync-sources/hooks/gh-issue-trailer-hook.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+import { existsSync, mkdtempSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir, tmpdir } from 'node:os';
+import { basename, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+interface PreToolUseEvent {
+  tool_name?: string;
+  tool_input?: {
+    command?: string;
+    [key: string]: unknown;
+  };
+}
+
+interface Token {
+  text: string;
+  start: number;
+  end: number;
+}
+
+type HookEnv = Record<string, string | undefined>;
+
+const FLYWHEEL_RUN_ID_PATTERN = /^RUN-\d+$/;
+
+function shellQuote(value: string): string {
+  return `'${value.replace(/'/g, `'"'"'`)}'`;
+}
+
+function tokenize(command: string): Token[] {
+  const tokens: Token[] = [];
+  let text = '';
+  let start = -1;
+  let quote: 'single' | 'double' | null = null;
+  let escape = false;
+
+  const flush = (end: number): void => {
+    if (start !== -1) tokens.push({ text, start, end });
+    text = '';
+    start = -1;
+  };
+
+  for (let index = 0; index < command.length; index += 1) {
+    const char = command[index];
+    if (start === -1 && !/\s/.test(char)) start = index;
+
+    if (escape) {
+      text += char;
+      escape = false;
+      continue;
+    }
+
+    if (quote === 'single') {
+      if (char === "'") quote = null;
+      else text += char;
+      continue;
+    }
+
+    if (quote === 'double') {
+      if (char === '"') quote = null;
+      else if (char === '\\') escape = true;
+      else text += char;
+      continue;
+    }
+
+    if (/\s/.test(char)) {
+      flush(index);
+      continue;
+    }
+
+    if (char === "'") {
+      quote = 'single';
+      continue;
+    }
+
+    if (char === '"') {
+      quote = 'double';
+      continue;
+    }
+
+    if (char === '\\') {
+      escape = true;
+      continue;
+    }
+
+    text += char;
+  }
+
+  flush(command.length);
+  return tokens;
+}
+
+function findGhIssueCreate(tokens: Token[]): number {
+  for (let index = 0; index <= tokens.length - 3; index += 1) {
+    if (tokens[index].text === 'gh' && tokens[index + 1].text === 'issue' && tokens[index + 2].text === 'create') {
+      return index;
+    }
+  }
+  return -1;
+}
+
+function containsFlywheelRunId(body: string): boolean {
+  return /^Flywheel-Run-Id:/m.test(body);
+}
+
+function resolveDiscoveredIn(env: HookEnv): string | null {
+  const agentId = env.OVERDECK_AGENT_ID;
+  if (!agentId || basename(agentId) !== agentId) return null;
+
+  const overdeckHome = env.OVERDECK_HOME ?? join(env.HOME ?? homedir(), '.overdeck');
+  const statePath = join(overdeckHome, 'agents', agentId, 'state.json');
+  if (!existsSync(statePath)) return null;
+
+  try {
+    const parsed = JSON.parse(readFileSync(statePath, 'utf-8')) as { issueId?: unknown };
+    return typeof parsed.issueId === 'string' && parsed.issueId.trim() ? parsed.issueId.trim() : null;
+  } catch {
+    return null;
+  }
+}
+
+function buildTrailer(env: HookEnv): string | null {
+  const runId = env.OVERDECK_FLYWHEEL_RUN_ID?.trim();
+  if (!runId || !FLYWHEEL_RUN_ID_PATTERN.test(runId)) return null;
+
+  const filedBy = env.OVERDECK_FLYWHEEL_AGENT_ROLE === 'flywheel' ? 'agent' : 'operator';
+  const discoveredIn = resolveDiscoveredIn(env);
+  const lines = [
+    '---',
+    `Flywheel-Run-Id: ${runId}`,
+    `Flywheel-Filed-By: ${filedBy}`,
+    discoveredIn ? `Flywheel-Discovered-In: ${discoveredIn}` : undefined,
+  ].filter((line): line is string => line !== undefined);
+  return `\n\n${lines.join('\n')}\n`;
+}
+
+function replaceSpan(command: string, start: number, end: number, replacement: string): string {
+  return `${command.slice(0, start)}${replacement}${command.slice(end)}`;
+}
+
+function findFlag(tokens: Token[], ghIndex: number, flagName: '--body' | '--body-file'): { flag: Token; value?: Token; inline: boolean } | null {
+  for (let index = ghIndex + 3; index < tokens.length; index += 1) {
+    const token = tokens[index];
+    if (token.text === flagName) return { flag: token, value: tokens[index + 1], inline: false };
+    if (token.text.startsWith(`${flagName}=`)) return { flag: token, inline: true };
+  }
+  return null;
+}
+
+function inlineFlagValue(flag: Token): { value: string; valueStart: number; valueEnd: number } | null {
+  const equalsOffset = flag.text.indexOf('=');
+  if (equalsOffset === -1) return null;
+  const valueStart = flag.start + equalsOffset + 1;
+  return { value: flag.text.slice(equalsOffset + 1), valueStart, valueEnd: flag.end };
+}
+
+function appendBodyFlag(command: string, tokens: Token[], ghIndex: number, trailer: string): string | null {
+  const bodyFlag = findFlag(tokens, ghIndex, '--body');
+  if (!bodyFlag) return null;
+
+  const body = bodyFlag.inline ? inlineFlagValue(bodyFlag.flag) : bodyFlag.value;
+  if (!body) return null;
+  const bodyText = 'text' in body ? body.text : body.value;
+  if (containsFlywheelRunId(bodyText)) return command;
+
+  const appended = `${bodyText}${trailer}`;
+  if ('text' in body) return replaceSpan(command, body.start, body.end, shellQuote(appended));
+  return replaceSpan(command, body.valueStart, body.valueEnd, shellQuote(appended));
+}
+
+function writeTempBodyFile(body: string): string {
+  const dir = mkdtempSync(join(tmpdir(), 'pan-gh-issue-body-'));
+  const path = join(dir, 'body.md');
+  writeFileSync(path, body, 'utf-8');
+  return path;
+}
+
+function appendBodyFileFlag(command: string, tokens: Token[], ghIndex: number, trailer: string): string | null {
+  const bodyFileFlag = findFlag(tokens, ghIndex, '--body-file');
+  if (!bodyFileFlag) return null;
+
+  const pathValue = bodyFileFlag.inline ? inlineFlagValue(bodyFileFlag.flag) : bodyFileFlag.value;
+  if (!pathValue) return null;
+  const pathText = 'text' in pathValue ? pathValue.text : pathValue.value;
+
+  if (pathText === '-') return appendStdinBody(command, tokens[ghIndex].start, trailer);
+  if (!existsSync(pathText)) return null;
+
+  const body = readFileSync(pathText, 'utf-8');
+  if (containsFlywheelRunId(body)) return command;
+
+  const tempPath = writeTempBodyFile(`${body}${trailer}`);
+  if ('text' in pathValue) return replaceSpan(command, pathValue.start, pathValue.end, shellQuote(tempPath));
+  return replaceSpan(command, pathValue.valueStart, pathValue.valueEnd, shellQuote(tempPath));
+}
+
+function findPipeBefore(command: string, beforeIndex: number): number {
+  let quote: 'single' | 'double' | null = null;
+  let escape = false;
+  let pipeIndex = -1;
+
+  for (let index = 0; index < beforeIndex; index += 1) {
+    const char = command[index];
+    if (escape) {
+      escape = false;
+      continue;
+    }
+    if (quote === 'single') {
+      if (char === "'") quote = null;
+      continue;
+    }
+    if (quote === 'double') {
+      if (char === '"') quote = null;
+      else if (char === '\\') escape = true;
+      continue;
+    }
+    if (char === "'") quote = 'single';
+    else if (char === '"') quote = 'double';
+    else if (char === '\\') escape = true;
+    else if (char === '|' && command[index + 1] !== '|' && command[index - 1] !== '|') pipeIndex = index;
+  }
+
+  return pipeIndex;
+}
+
+function appendHereDoc(command: string, trailer: string): string | null {
+  const match = command.match(/(<<-?\s*['"]?([A-Za-z_][A-Za-z0-9_-]*)['"]?[^\n]*\n)([\s\S]*?)(\n\2\s*)$/);
+  if (!match || match.index === undefined) return null;
+  const body = match[3];
+  if (containsFlywheelRunId(body)) return command;
+  const bodyStart = match.index + match[1].length;
+  const bodyEnd = bodyStart + body.length;
+  return replaceSpan(command, bodyStart, bodyEnd, `${body}${trailer}`);
+}
+
+function appendStdinBody(command: string, ghStart: number, trailer: string): string | null {
+  if (command.includes('Flywheel-Run-Id:')) return command;
+
+  const hereDoc = appendHereDoc(command, trailer);
+  if (hereDoc) return hereDoc;
+
+  const pipeIndex = findPipeBefore(command, ghStart);
+  if (pipeIndex === -1) return null;
+
+  const producer = command.slice(0, pipeIndex).trim();
+  const consumer = command.slice(pipeIndex + 1).trimStart();
+  if (!producer || !consumer) return null;
+  return `{ ${producer}; printf %s ${shellQuote(trailer)}; } | ${consumer}`;
+}
+
+function buildUpdatedInput(command: string): Record<string, unknown> {
+  return {
+    hookSpecificOutput: {
+      hookEventName: 'PreToolUse',
+      permissionDecisionReason: 'Flywheel issue provenance trailers added',
+      updatedInput: { command },
+    },
+  };
+}
+
+export function rewriteGhIssueCreateCommand(command: string, env: HookEnv = process.env): string | null {
+  const trailer = buildTrailer(env);
+  if (!trailer) return null;
+
+  const tokens = tokenize(command);
+  const ghIndex = findGhIssueCreate(tokens);
+  if (ghIndex === -1) return null;
+
+  const bodyCommand = appendBodyFlag(command, tokens, ghIndex, trailer);
+  if (bodyCommand !== null) return bodyCommand === command ? null : bodyCommand;
+
+  const bodyFileCommand = appendBodyFileFlag(command, tokens, ghIndex, trailer);
+  if (bodyFileCommand !== null) return bodyFileCommand === command ? null : bodyFileCommand;
+
+  return null;
+}
+
+export function runGhIssueTrailerHook(input: string, env: HookEnv = process.env): string {
+  let event: PreToolUseEvent;
+  try {
+    event = JSON.parse(input) as PreToolUseEvent;
+  } catch {
+    return '{}';
+  }
+
+  const command = event.tool_name === 'Bash' ? event.tool_input?.command : undefined;
+  if (typeof command !== 'string') return '{}';
+
+  const updatedCommand = rewriteGhIssueCreateCommand(command, env);
+  if (!updatedCommand) return '{}';
+  return JSON.stringify(buildUpdatedInput(updatedCommand));
+}
+
+if (process.argv[1] && fileURLToPath(import.meta.url) === process.argv[1]) {
+  const input = readFileSync(0, 'utf-8');
+  process.stdout.write(runGhIssueTrailerHook(input));
+}

package/sync-sources/hooks/git-hooks/post-checkout

@@ -0,0 +1,109 @@
+#!/bin/bash
+#
+# Git post-checkout hook to guard main project directories
+# Prevents accidental checkouts away from main in the primary project directory
+#
+# Install: ln -sf /path/to/overdeck/scripts/git-hooks/post-checkout .git/hooks/post-checkout
+# Or: pan projects add /path/to/project (auto-installs hooks)
+#
+# This hook only activates in the MAIN project directory (not worktrees).
+# Worktrees can freely checkout any branch - that's their purpose.
+#
+# Auto-revert behavior:
+# - Agents (OVERDECK_AGENT=1): Always auto-revert (agents should never checkout in main)
+# - Manual (OVERDECK_AUTO_REVERT_CHECKOUT=1): Opt-in auto-revert for humans
+# - Default: Warn only, don't revert
+
+# Get the previous and new HEAD refs
+PREV_HEAD=$1
+NEW_HEAD=$2
+IS_BRANCH_CHECKOUT=$3  # 1 if branch checkout, 0 if file checkout
+
+# Only care about branch checkouts
+if [ "$IS_BRANCH_CHECKOUT" != "1" ]; then
+    exit 0
+fi
+
+# Check if we're in a worktree (worktrees have .git as a file, not directory)
+if [ -f ".git" ]; then
+    # This is a worktree - allow any checkout
+    exit 0
+fi
+
+# Check if .git is a directory (main repo)
+if [ ! -d ".git" ]; then
+    # Not a git repo at all
+    exit 0
+fi
+
+# Get current branch name
+CURRENT_BRANCH=$(git branch --show-current 2>/dev/null)
+
+# If we're on main or master, all good
+if [ "$CURRENT_BRANCH" = "main" ] || [ "$CURRENT_BRANCH" = "master" ]; then
+    exit 0
+fi
+
+# We're in the main project directory and NOT on main - this is bad!
+echo ""
+echo "╔══════════════════════════════════════════════════════════════════════════════╗"
+echo "║  ⚠️  WARNING: Main project directory is not on 'main' branch!               ║"
+echo "╠══════════════════════════════════════════════════════════════════════════════╣"
+echo "║                                                                              ║"
+echo "║  Current branch: $CURRENT_BRANCH"
+echo "║  Location: $(pwd)"
+echo "║                                                                              ║"
+echo "║  The main project directory should ALWAYS stay on 'main'.                   ║"
+echo "║  All feature work should happen in workspaces (git worktrees).              ║"
+echo "║                                                                              ║"
+echo "║  To fix this:                                                               ║"
+echo "║    git checkout main                                                        ║"
+echo "║                                                                              ║"
+echo "║  To work on a feature:                                                      ║"
+echo "║    pan workspace create ISSUE-ID                                            ║"
+echo "║                                                                              ║"
+echo "╚══════════════════════════════════════════════════════════════════════════════╝"
+echo ""
+
+# Auto-revert for agents and planning sessions
+# They should NEVER be checking out in main project
+IS_OVERDECK_SESSION=0
+
+# Check explicit environment variables
+if [ "$OVERDECK_AGENT" = "1" ] || [ -n "$OVERDECK_AGENT_ID" ]; then
+    IS_OVERDECK_SESSION=1
+fi
+
+# Check for planning session
+if [ "$OVERDECK_PLANNING" = "1" ] || [ -n "$OVERDECK_PLANNING_ISSUE" ]; then
+    IS_OVERDECK_SESSION=1
+fi
+
+# Check tmux session name pattern (agent-* or planning-* or specialist-*)
+if [ -n "$TMUX" ]; then
+    TMUX_SESSION=$(tmux display-message -p '#{session_name}' 2>/dev/null || true)
+    case "$TMUX_SESSION" in
+        agent-*|planning-*|specialist-*)
+            IS_OVERDECK_SESSION=1
+            ;;
+    esac
+fi
+
+if [ "$IS_OVERDECK_SESSION" = "1" ]; then
+    echo "🤖 Overdeck session detected - auto-reverting to main branch..."
+    git checkout main --quiet
+    echo "✓ Reverted to main branch. Agents/planning must use workspaces for feature branches."
+    exit 0
+fi
+
+# Check for manual auto-revert environment variable
+if [ "$OVERDECK_AUTO_REVERT_CHECKOUT" = "1" ]; then
+    echo "Auto-reverting to main branch (OVERDECK_AUTO_REVERT_CHECKOUT=1)..."
+    git checkout main --quiet
+    echo "Reverted to main branch."
+    exit 0
+fi
+
+# Return success but with warning - don't block the checkout
+# The warning is enough for humans to notice
+exit 0

package/sync-sources/hooks/heartbeat-hook

@@ -0,0 +1,113 @@
+#!/bin/bash
+# ~/.overdeck/bin/heartbeat-hook  (PAN-800)
+#
+# Fires on Claude Code PostToolUse. POSTs agent.activity_changed(working, tool)
+# to the dashboard, then records the cost event.
+#
+# Rewritten from the ~200-line jq read-modify-write version to a pure POST
+# emitter. runtime.json and heartbeats/<id>.json are no longer written —
+# AgentStateService's SubscriptionRef + projection_cache is canonical.
+# activity.jsonl is retained as a forensic grep-able artifact (cheap to keep).
+# The sessions.json append-only list is retained because it's a bookkeeping
+# record of Claude session UUIDs, not runtime state.
+# Cost-event recording stays on its own flock-serialized path.
+
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=pan-hook-lib.sh
+. "$SCRIPT_DIR/pan-hook-lib.sh" 2>/dev/null || exit 0
+
+pan_resolve_agent_id || exit 0
+
+TOOL_INFO=$(cat 2>/dev/null || echo '{}')
+
+HAVE_JQ=0
+if command -v jq >/dev/null 2>&1; then HAVE_JQ=1; fi
+
+TOOL_NAME="unknown"
+TOOL_INPUT=""
+CLAUDE_SESSION_ID=""
+if [ "$HAVE_JQ" = "1" ]; then
+  TOOL_NAME=$(echo "$TOOL_INFO" | jq -r '.tool_name // "unknown"' 2>/dev/null || echo "unknown")
+  TOOL_INPUT=$(echo "$TOOL_INFO" | jq -r '.tool_input | tostring | .[0:100] // ""' 2>/dev/null || echo "")
+  CLAUDE_SESSION_ID=$(echo "$TOOL_INFO" | jq -r '.session_id // ""' 2>/dev/null || echo "")
+fi
+
+TS=$(date -Iseconds)
+
+# ── Emit agent.activity_changed(working, tool) ─────────────────────────────
+if [ "$HAVE_JQ" = "1" ]; then
+  BODY=$(jq -n --arg tool "$TOOL_NAME" --arg ts "$TS" \
+    '{kind: "activity", activity: "working", tool: $tool, timestamp: $ts}')
+else
+  BODY="{\"kind\":\"activity\",\"activity\":\"working\",\"tool\":\"$TOOL_NAME\",\"timestamp\":\"$TS\"}"
+fi
+pan_emit_event "$AGENT_ID" "$BODY"
+
+# ── Activity log (retained for forensics) ─────────────────────────────────
+AGENT_DIR="$HOME/.overdeck/agents/$AGENT_ID"
+mkdir -p "$AGENT_DIR" 2>/dev/null
+if [ "$HAVE_JQ" = "1" ]; then
+  ENTRY=$(jq -n --arg ts "$TS" --arg tool "$TOOL_NAME" --arg action "$TOOL_INPUT" \
+    '{ts: $ts, tool: $tool, action: $action}' 2>/dev/null || echo "")
+  if [ -n "$ENTRY" ]; then
+    echo "$ENTRY" >> "$AGENT_DIR/activity.jsonl" 2>/dev/null || true
+    # Prune to last 100 entries.
+    if [ -f "$AGENT_DIR/activity.jsonl" ]; then
+      TMP="$AGENT_DIR/activity.jsonl.tmp"
+      tail -n 100 "$AGENT_DIR/activity.jsonl" > "$TMP" 2>/dev/null \
+        && mv "$TMP" "$AGENT_DIR/activity.jsonl" 2>/dev/null || true
+    fi
+  fi
+fi
+
+# ── Claude session history (append-only bookkeeping) ──────────────────────
+if [ "$HAVE_JQ" = "1" ] && [ -n "$CLAUDE_SESSION_ID" ]; then
+  SESSIONS_FILE="$AGENT_DIR/sessions.json"
+  if [ -f "$SESSIONS_FILE" ]; then
+    if ! jq -e --arg sid "$CLAUDE_SESSION_ID" 'any(.[]; . == $sid)' "$SESSIONS_FILE" >/dev/null 2>&1; then
+      TMP="$SESSIONS_FILE.tmp"
+      jq --arg sid "$CLAUDE_SESSION_ID" '. + [$sid]' "$SESSIONS_FILE" > "$TMP" 2>/dev/null \
+        && mv "$TMP" "$SESSIONS_FILE" 2>/dev/null || true
+    fi
+  else
+    echo "[\"$CLAUDE_SESSION_ID\"]" > "$SESSIONS_FILE" 2>/dev/null || true
+  fi
+fi
+
+# ── Cost-event recording (unchanged, its own flock-serialized path) ──────
+COST_SCRIPT=""
+if [ -f "$HOME/.overdeck/bin/record-cost-event.js" ]; then
+  COST_SCRIPT="$HOME/.overdeck/bin/record-cost-event.js"
+elif [ -f "$SCRIPT_DIR/record-cost-event.js" ]; then
+  COST_SCRIPT="$SCRIPT_DIR/record-cost-event.js"
+fi
+
+if [ -n "$COST_SCRIPT" ] && [ -n "$CLAUDE_SESSION_ID" ]; then
+  GIT_BRANCH=$(git branch --show-current 2>/dev/null || echo "")
+  WORKSPACE=$(pwd)
+
+  if [ -z "$OVERDECK_ISSUE_ID" ]; then
+    if [[ "$GIT_BRANCH" =~ (pan|min|aud|krux|cli|PAN|MIN|AUD|KRUX|CLI)[-]([0-9]+) ]]; then
+      OVERDECK_ISSUE_ID="${BASH_REMATCH[1]^^}-${BASH_REMATCH[2]}"
+    fi
+  fi
+  if [ -z "$OVERDECK_ISSUE_ID" ]; then
+    if [[ "$WORKSPACE" =~ (pan|min|aud|krux|cli|PAN|MIN|AUD|KRUX|CLI)[-]([0-9]+) ]]; then
+      OVERDECK_ISSUE_ID="${BASH_REMATCH[1]^^}-${BASH_REMATCH[2]}"
+    fi
+  fi
+  export OVERDECK_ISSUE_ID="${OVERDECK_ISSUE_ID:-UNKNOWN}"
+  export OVERDECK_SESSION_TYPE="${OVERDECK_SESSION_TYPE:-implementation}"
+
+  STATE_DIR="$HOME/.overdeck/costs/state"
+  mkdir -p "$STATE_DIR" 2>/dev/null
+  LOCK_FILE="$STATE_DIR/${CLAUDE_SESSION_ID}.lock"
+  {
+    flock -x -w 30 200
+    echo "$TOOL_INFO" | node "$COST_SCRIPT" 2>/dev/null || true
+  } 200>"$LOCK_FILE"
+fi
+
+exit 0

package/sync-sources/hooks/notification-hook

@@ -0,0 +1,70 @@
+#!/bin/bash
+# ~/.overdeck/bin/notification-hook  (PAN-800)
+#
+# Fires on Claude Code Notification events. If the notification looks like a
+# permission prompt or a request for human input, emits
+# agent.waiting_started(reason=...). Logs the raw payload for future analysis.
+#
+# PAN-709 note: the Notification event fires for system/desktop notifications
+# from Claude Code, NOT for in-terminal tool approval dialogs. In-terminal
+# prompts are detected separately by the deacon tmux-tail scanner (still
+# active during the PAN-800 migration; scheduled for replacement in Phase 5).
+
+set +e
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+# shellcheck source=pan-hook-lib.sh
+. "$SCRIPT_DIR/pan-hook-lib.sh" 2>/dev/null || exit 0
+
+pan_resolve_agent_id || exit 0
+
+NOTIF_INFO=$(cat 2>/dev/null || echo '{}')
+
+HAVE_JQ=0
+if command -v jq >/dev/null 2>&1; then HAVE_JQ=1; fi
+
+NOTIF_MSG=""
+if [ "$HAVE_JQ" = "1" ]; then
+  NOTIF_MSG=$(echo "$NOTIF_INFO" | jq -r '.message // ""' 2>/dev/null || echo "")
+fi
+
+TS=$(date -Iseconds)
+
+# Log the raw notification for forensics. Kept at 500 entries.
+LOG_DIR="$HOME/.overdeck/logs"
+mkdir -p "$LOG_DIR" 2>/dev/null
+LOG_FILE="$LOG_DIR/notifications.jsonl"
+if [ "$HAVE_JQ" = "1" ]; then
+  jq -n --arg ts "$TS" --arg agent "$AGENT_ID" --argjson payload "$NOTIF_INFO" \
+    '{ts: $ts, agent: $agent, payload: $payload}' >> "$LOG_FILE" 2>/dev/null || true
+  if [ -f "$LOG_FILE" ]; then
+    TMP="$LOG_FILE.tmp"
+    tail -n 500 "$LOG_FILE" > "$TMP" 2>/dev/null && mv "$TMP" "$LOG_FILE" 2>/dev/null || true
+  fi
+fi
+
+# Classify the notification. The message strings come from Claude Code's own
+# notification payloads; we're pattern-matching the keywords that indicate the
+# agent is stalled waiting for the human.
+REASON=""
+if echo "$NOTIF_MSG" | grep -qiE '(permission|approval|allow.*tool|confirm.*tool)'; then
+  REASON="tool_permission"
+elif echo "$NOTIF_MSG" | grep -qiE '(question|needs.*input|waiting.*for|needs your)'; then
+  REASON="user_question"
+elif echo "$NOTIF_MSG" | grep -qiE '(disambiguat|choose|select|which)'; then
+  REASON="disambiguation"
+fi
+
+if [ -n "$REASON" ]; then
+  if [ "$HAVE_JQ" = "1" ]; then
+    BODY=$(jq -n --arg reason "$REASON" --arg msg "$NOTIF_MSG" --arg ts "$TS" \
+      '{kind: "waiting_start", reason: $reason, message: $msg, timestamp: $ts}')
+  else
+    # Fallback: minimal body, no message field. Escaping arbitrary NOTIF_MSG
+    # into JSON by hand is error-prone.
+    BODY="{\"kind\":\"waiting_start\",\"reason\":\"$REASON\",\"timestamp\":\"$TS\"}"
+  fi
+  pan_emit_event "$AGENT_ID" "$BODY"
+fi
+
+exit 0

package/sync-sources/hooks/notify-complete

@@ -0,0 +1,79 @@
+#!/bin/bash
+# notify-complete: Send desktop notification when agent completes work
+# Part of Overdeck - works on WSL2/Windows, Linux, and macOS
+#
+# Usage: notify-complete <issue-id> <title> [mr-url]
+#
+# Examples:
+#   notify-complete MIN-665 "Fixed login button"
+#   notify-complete PAN-96 "Implemented templates" "https://gitlab.com/mr/123"
+
+ISSUE_ID="${1:-UNKNOWN}"
+TITLE="${2:-Agent completed work}"
+MR_URL="${3:-}"
+
+# Log to completion file
+COMPLETION_LOG="$HOME/.overdeck/agent-completed.log"
+mkdir -p "$(dirname "$COMPLETION_LOG")"
+echo "$(date '+%Y-%m-%d %H:%M:%S') | ${ISSUE_ID} | ${TITLE} | ${MR_URL}" >> "$COMPLETION_LOG"
+
+# Detect platform and send notification
+send_notification() {
+  local title="$1"
+  local message="$2"
+
+  # WSL2/Windows - use PowerShell toast notifications
+  if command -v powershell.exe &>/dev/null; then
+    powershell.exe -Command "
+\$xml = @\"
+<toast>
+  <visual>
+    <binding template=\"ToastText02\">
+      <text id=\"1\">${title}</text>
+      <text id=\"2\">${message}</text>
+    </binding>
+  </visual>
+  <audio src=\"ms-winsoundevent:Notification.Default\"/>
+</toast>
+\"@
+
+[Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType = WindowsRuntime] | Out-Null
+[Windows.Data.Xml.Dom.XmlDocument, Windows.Data.Xml.Dom.XmlDocument, ContentType = WindowsRuntime] | Out-Null
+
+\$template = New-Object Windows.Data.Xml.Dom.XmlDocument
+\$template.LoadXml(\$xml)
+\$toast = New-Object Windows.UI.Notifications.ToastNotification \$template
+[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier('Overdeck').Show(\$toast)
+" 2>/dev/null && return 0
+
+    # Fallback: MessageBox
+    powershell.exe -Command "[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('${message}', '${title}', 'OK', 'Information')" 2>/dev/null &
+    return 0
+  fi
+
+  # macOS - use osascript
+  if command -v osascript &>/dev/null; then
+    osascript -e "display notification \"${message}\" with title \"${title}\"" 2>/dev/null
+    return 0
+  fi
+
+  # Linux - use notify-send
+  if command -v notify-send &>/dev/null; then
+    notify-send "${title}" "${message}" 2>/dev/null
+    return 0
+  fi
+
+  # Fallback - just print to console
+  echo "[NOTIFICATION] ${title}: ${message}"
+}
+
+# Build notification message
+if [ -n "$MR_URL" ]; then
+  MESSAGE="${TITLE} - Ready for review"
+else
+  MESSAGE="${TITLE} - Work complete"
+fi
+
+send_notification "Overdeck: ${ISSUE_ID}" "$MESSAGE"
+
+echo "Notification sent for ${ISSUE_ID}"