@overdeck/desktop 0.45.12 → 0.45.13

package/sync-sources/hooks/tldr-read-enforcer

@@ -0,0 +1,340 @@
+#!/bin/bash
+# ~/.overdeck/bin/tldr-read-enforcer
+# PreToolUse hook on Read — intercepts file reads and returns TLDR summaries
+# for large code files, saving 90-95% of context tokens.
+#
+# Bypasses (allows normal read):
+#   - Files < 3KB (small enough to read directly)
+#   - Reads with offset/limit (targeted reads for editing)
+#   - Non-code files (configs, docs, json, etc.)
+#   - No .venv available (TLDR not installed)
+#   - TLDR disabled via OVERDECK_TLDR_ENABLED=0 or agents.tldr.enabled: false
+#   - TLDR command fails (graceful degradation)
+#   - Summary too sparse to be useful (< 100 tokens for file > 5KB)
+#   - Recently edited files (in .tldr/dirty-files — agent needs to verify changes)
+
+# Don't use set -e — never break Claude Code execution
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# Only act on Read tool
+TOOL_NAME=$(echo "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+if [ "$TOOL_NAME" != "Read" ]; then
+  exit 0
+fi
+
+# Bypass: TLDR disabled via env override or config (read live, so the Settings
+# toggle takes effect on the very next Read — no agent restart required).
+# TLDR defaults ON: only an explicit falsy value (0/false/no/off/disabled)
+# disables it; an absent/empty value means "enabled".
+tldr_falsy() {
+  case "$(printf '%s' "$1" | tr '[:upper:]' '[:lower:]')" in
+    0|false|no|off|disabled) return 0 ;;
+    *) return 1 ;;
+  esac
+}
+tldr_read_config_enabled() {
+  local config_path="$1"
+  [ -z "$config_path" ] && return 0
+  [ ! -f "$config_path" ] && return 0
+  awk '
+    function trim(s) { sub(/^[ \t\r\n]+/, "", s); sub(/[ \t\r\n]+$/, "", s); return s }
+    BEGIN { in_agents = 0; in_tldr = 0; agents_indent = -1; tldr_indent = -1 }
+    {
+      line = $0
+      sub(/#.*/, "", line)
+      if (line ~ /^[[:space:]]*$/) next
+      match(line, /^[ ]*/)
+      indent = RLENGTH
+      key = line
+      sub(/^[[:space:]]*/, "", key)
+      if (key ~ /^agents:[[:space:]]*$/) { in_agents = 1; in_tldr = 0; agents_indent = indent; next }
+      if (in_agents && indent <= agents_indent) { in_agents = 0; in_tldr = 0 }
+      if (in_agents && key ~ /^tldr:[[:space:]]*$/) { in_tldr = 1; tldr_indent = indent; next }
+      if (in_tldr && indent <= tldr_indent) { in_tldr = 0 }
+      if (in_tldr && key ~ /^enabled:[[:space:]]*/) {
+        sub(/^enabled:[[:space:]]*/, "", key)
+        gsub(/"/, "", key); gsub(/\047/, "", key)
+        print trim(key); exit
+      }
+    }
+  ' "$config_path" 2>/dev/null
+}
+tldr_config_enabled_value() {
+  if [ -n "${OVERDECK_CONFIG:-}" ]; then
+    tldr_read_config_enabled "$OVERDECK_CONFIG"
+  else
+    tldr_read_config_enabled "$HOME/.overdeck/config.yaml"
+  fi
+}
+if [ -n "${OVERDECK_TLDR_ENABLED+x}" ]; then
+  tldr_falsy "$OVERDECK_TLDR_ENABLED" && exit 0
+else
+  tldr_falsy "$(tldr_config_enabled_value)" && exit 0
+fi
+
+# Extract Read parameters
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // ""' 2>/dev/null)
+OFFSET=$(echo "$INPUT" | jq -r '.tool_input.offset // empty' 2>/dev/null)
+LIMIT=$(echo "$INPUT" | jq -r '.tool_input.limit // empty' 2>/dev/null)
+
+# Bypass: targeted reads (offset or limit specified — agent is reading for editing)
+if [ -n "$OFFSET" ] || [ -n "$LIMIT" ]; then
+  exit 0
+fi
+
+# Bypass: file doesn't exist
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Bypass: small files (< 3KB)
+FILE_SIZE=$(stat -c%s "$FILE_PATH" 2>/dev/null || echo 0)
+if [ "$FILE_SIZE" -lt 3072 ]; then
+  exit 0
+fi
+
+# Bypass: non-code files
+EXT="${FILE_PATH##*.}"
+EXT_LOWER=$(echo "$EXT" | tr '[:upper:]' '[:lower:]')
+case "$EXT_LOWER" in
+  ts|tsx|js|jsx|py|java|go|rs|cpp|c|h|hpp|rb|php|kt|swift|cs|scala|lua|ex|exs)
+    # Code file — continue to TLDR
+    ;;
+  *)
+    # Non-code — allow normal read
+    exit 0
+    ;;
+esac
+
+# Find the .venv/bin/tldr binary
+# Check workspace first, then project root
+TLDR_BIN=""
+DIR="$(dirname "$FILE_PATH")"
+while [ "$DIR" != "/" ]; do
+  if [ -x "$DIR/.venv/bin/tldr" ]; then
+    TLDR_BIN="$DIR/.venv/bin/tldr"
+    PROJECT_DIR="$DIR"
+    break
+  fi
+  DIR=$(dirname "$DIR")
+done
+
+# Bypass: no TLDR binary found
+if [ -z "$TLDR_BIN" ]; then
+  exit 0
+fi
+
+# Get relative path from project root
+REL_PATH="${FILE_PATH#$PROJECT_DIR/}"
+
+# Bypass: recently edited files (agent needs to verify its own changes)
+# The post-edit hook tracks edits in .tldr/dirty-files
+DIRTY_FILE="$PROJECT_DIR/.tldr/dirty-files"
+if [ -f "$DIRTY_FILE" ] && grep -qxF "$REL_PATH" "$DIRTY_FILE" 2>/dev/null; then
+  exit 0
+fi
+
+# Detect language from extension for tldr --lang flag
+case "$EXT_LOWER" in
+  ts|tsx)      TLDR_LANG="typescript" ;;
+  js|jsx)      TLDR_LANG="javascript" ;;
+  py)          TLDR_LANG="python" ;;
+  go)          TLDR_LANG="go" ;;
+  rs)          TLDR_LANG="rust" ;;
+  java|kt)     TLDR_LANG="java" ;;
+  rb)          TLDR_LANG="ruby" ;;
+  *)           TLDR_LANG="python" ;;
+esac
+
+# Strip file extension — tldr context expects module paths without extension
+# e.g., "src/lib/agents" not "src/lib/agents.ts"
+MODULE_PATH="${REL_PATH%.*}"
+
+# Try to get TLDR context for this file (module path mode)
+TLDR_OUTPUT=$("$TLDR_BIN" context "$MODULE_PATH" --lang "$TLDR_LANG" 2>/dev/null)
+TLDR_EXIT=$?
+
+# Quality gate: check if context output is too sparse to be useful.
+# Pattern: "~XX tokens" where XX < 100 means the summary captured almost nothing.
+# This happens with test files (describe/it blocks) and type-only files.
+CONTEXT_SPARSE=false
+if [ $TLDR_EXIT -eq 0 ] && [ -n "$TLDR_OUTPUT" ]; then
+  CTX_TOKENS=$(echo "$TLDR_OUTPUT" | grep -oP '\~\K\d+(?= tokens)' || echo "0")
+  if [ "$CTX_TOKENS" -lt 100 ] && [ "$FILE_SIZE" -gt 5120 ]; then
+    CONTEXT_SPARSE=true
+  fi
+fi
+
+# Fallback: if context failed, was sparse, or empty — try extract command
+# extract works on actual file paths (including .tsx) and returns structured JSON
+if [ $TLDR_EXIT -ne 0 ] || [ -z "$TLDR_OUTPUT" ] || [ "$CONTEXT_SPARSE" = true ]; then
+  EXTRACT_JSON=$("$TLDR_BIN" extract "$REL_PATH" 2>/dev/null)
+  EXTRACT_EXIT=$?
+  if [ $EXTRACT_EXIT -eq 0 ] && [ -n "$EXTRACT_JSON" ]; then
+    # Check if extract found any real content
+    EXTRACT_COUNTS=$(echo "$EXTRACT_JSON" | python3 -c "
+import json, sys
+try:
+    d = json.load(sys.stdin)
+    nf = len(d.get('functions', []))
+    nc = len(d.get('classes', []))
+    print(f'{nf} {nc}')
+except:
+    print('0 0')
+" 2>/dev/null)
+    EXTRACT_FUNCS=$(echo "$EXTRACT_COUNTS" | cut -d' ' -f1)
+    EXTRACT_CLASSES=$(echo "$EXTRACT_COUNTS" | cut -d' ' -f2)
+
+    # If extract also found nothing useful, bypass entirely
+    if [ "${EXTRACT_FUNCS:-0}" -eq 0 ] && [ "${EXTRACT_CLASSES:-0}" -eq 0 ]; then
+      # Neither context nor extract found useful content — let the agent read the file
+      exit 0
+    fi
+
+    # Convert extract JSON to a readable summary with language-appropriate syntax
+    TLDR_OUTPUT=$(echo "$EXTRACT_JSON" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lang = '$TLDR_LANG'
+    lines = []
+    fname = data.get('file_path', '$REL_PATH')
+    short = fname.split('/')[-1]
+    lines.append(f'## Code Context: {fname}')
+    lines.append('')
+
+    # Language-appropriate function keyword
+    fn_kw = {'typescript': 'function', 'javascript': 'function', 'python': 'def',
+             'go': 'func', 'rust': 'fn', 'java': '', 'ruby': 'def'}.get(lang, 'function')
+
+    for func in data.get('functions', []):
+        name = func.get('name', '?')
+        params = ', '.join(
+            p.get('name','') + (': ' + p.get('type','') if p.get('type') else '')
+            for p in func.get('parameters', [])
+        )
+        ret = func.get('return_type', '')
+        doc = (func.get('docstring') or '')[:80]
+        line = func.get('start_line') or '?'
+        sig = f'{fn_kw} {name}({params})'.strip()
+        if ret:
+            if lang in ('typescript', 'javascript', 'go', 'rust'):
+                sig += f': {ret}'
+            else:
+                sig += f' -> {ret}'
+        lines.append(f'{name} ({short}:{line})')
+        lines.append(f'   {sig}')
+        if doc:
+            lines.append(f'   // {doc}')
+        lines.append('')
+
+    for cls in data.get('classes', []):
+        name = cls.get('name', '?')
+        line = cls.get('start_line') or '?'
+        lines.append(f'class {name} ({short}:{line})')
+        for m in cls.get('methods', []):
+            mname = m.get('name', '?')
+            lines.append(f'   .{mname}()')
+        lines.append('')
+
+    nfunc = len(data.get('functions', []))
+    ncls = len(data.get('classes', []))
+    lines.append(f'---')
+    lines.append(f'{nfunc} functions, {ncls} classes (via extract)')
+    print('\n'.join(lines))
+except:
+    pass
+" 2>/dev/null)
+  fi
+fi
+
+# Observability: if BOTH TLDR invocations exited non-zero, the binary itself
+# is broken (dead interpreter, bad shebang after a rename, etc.) — NOT a file
+# with nothing to summarize. The hook still bypasses (exit 0 below) so the
+# agent's Read succeeds, but record it so a broken TLDR install surfaces
+# instead of silently degrading every Read to full-file. A dead binary is
+# otherwise indistinguishable from "no content" (this is exactly how a stale
+# shebang after the panopticon-cli → overdeck rename went unnoticed).
+if [ "${TLDR_EXIT:-0}" -ne 0 ] && [ "${EXTRACT_EXIT:-0}" -ne 0 ]; then
+  FAIL_LOG="$PROJECT_DIR/.tldr/failures.log"
+  mkdir -p "$(dirname "$FAIL_LOG")" 2>/dev/null
+  printf '%s binary_fail context_exit=%s extract_exit=%s %s\n' \
+    "$(date +%s)" "$TLDR_EXIT" "$EXTRACT_EXIT" "$REL_PATH" >> "$FAIL_LOG" 2>/dev/null
+fi
+
+# Bypass: both context and extract failed or produced nothing useful
+if [ -z "$TLDR_OUTPUT" ]; then
+  exit 0
+fi
+
+# Also get the file's imports and format them
+TLDR_IMPORTS_RAW=$("$TLDR_BIN" imports "$REL_PATH" --lang "$TLDR_LANG" 2>/dev/null || true)
+TLDR_IMPORTS=""
+if [ -n "$TLDR_IMPORTS_RAW" ]; then
+  TLDR_IMPORTS=$(echo "$TLDR_IMPORTS_RAW" | python3 -c "
+import json, sys
+try:
+    data = json.load(sys.stdin)
+    lines = []
+    for imp in data:
+        mod = imp.get('module', '?')
+        names = imp.get('names', [])
+        default = imp.get('default')
+        parts = []
+        if default:
+            parts.append(default)
+        if names:
+            parts.append('{ ' + ', '.join(names) + ' }')
+        if parts:
+            lines.append(f'import {', '.join(parts)} from \"{mod}\"')
+        else:
+            lines.append(f'import \"{mod}\"')
+    print('\n'.join(lines))
+except:
+    # If JSON parsing fails, use raw output (may already be formatted)
+    sys.stdout.write(sys.stdin.read() if hasattr(sys, '_raw') else '')
+" 2>/dev/null)
+  # If Python formatting failed, fall back to raw
+  if [ -z "$TLDR_IMPORTS" ]; then
+    TLDR_IMPORTS="$TLDR_IMPORTS_RAW"
+  fi
+fi
+
+# Build the summary that Claude will see instead of the raw file
+SUMMARY="[TLDR Summary — ${FILE_SIZE} bytes saved from context]
+
+File: ${FILE_PATH}
+
+## Structure & Exports
+${TLDR_OUTPUT}"
+
+if [ -n "$TLDR_IMPORTS" ]; then
+  SUMMARY="${SUMMARY}
+
+## Imports
+${TLDR_IMPORTS}"
+fi
+
+SUMMARY="${SUMMARY}
+
+---
+To read the full file, use Read with offset/limit parameters for the specific section you need to edit."
+
+# Deny the read and provide TLDR context instead
+# Use a temp file for the JSON to handle multiline safely
+TEMP_JSON=$(mktemp /tmp/tldr-hook-XXXXXX.json)
+jq -n --arg reason "TLDR summary provided instead of full file read (${FILE_SIZE} bytes → ~1K tokens)" \
+      --arg context "$SUMMARY" \
+  '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      permissionDecision: "deny",
+      permissionDecisionReason: $reason,
+      additionalContext: $context
+    }
+  }' > "$TEMP_JSON" 2>/dev/null
+
+cat "$TEMP_JSON"
+rm -f "$TEMP_JSON"
+
+exit 0

package/sync-sources/hooks/tmux-send-keys-guard

@@ -0,0 +1,87 @@
+#!/bin/bash
+# ~/.overdeck/bin/tmux-send-keys-guard  (PAN-1084)
+#
+# PreToolUse hook on Bash — prevents work agents from self-approving permission
+# prompts (or any other input) in another agent's tmux session by blocking
+# `tmux send-keys` and `tmux paste-buffer` that target a session other than
+# their own.
+#
+# The work-agent prompt already forbids interacting with permission prompts via
+# tmux keystrokes. This hook is the mechanical enforcement: it rewrites the
+# Bash command to a failing no-op when it would write to a non-self session.
+#
+# Never breaks Claude Code: on any error the hook exits 0 silently and lets the
+# original command through.
+
+set +e
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+
+# Only enforce for work agents (agent-<prefix>-<number>). Planning, test, review,
+# inspect, strike, flywheel, conversation, and human sessions must keep normal
+# tmux behavior — this guard is not meant for them.
+case "${OVERDECK_AGENT_ID:-}" in
+  agent-*[0-9]) : ;;
+  *) exit 0 ;;
+esac
+
+if ! command -v jq >/dev/null 2>&1; then
+  # Without jq we cannot safely parse the payload. Allow the call.
+  exit 0
+fi
+
+TOOL_NAME=$(printf '%s' "$INPUT" | jq -r '.tool_name // ""' 2>/dev/null)
+if [ "$TOOL_NAME" != "Bash" ]; then
+  exit 0
+fi
+
+COMMAND=$(printf '%s' "$INPUT" | jq -r '.tool_input.command // ""' 2>/dev/null)
+if [ -z "$COMMAND" ]; then
+  exit 0
+fi
+
+# Only guard tmux subcommands that write keystrokes/buffers to a target pane.
+if ! printf '%s' "$COMMAND" | grep -qE '\btmux\b.*\b(send-keys|paste-buffer)\b'; then
+  exit 0
+fi
+
+# Determine this agent's own tmux session name.
+SELF_SESSION=""
+if [ -n "${OVERDECK_AGENT_ID:-}" ]; then
+  SELF_SESSION="$OVERDECK_AGENT_ID"
+elif [ -n "${TMUX:-}" ]; then
+  SELF_SESSION=$(tmux display-message -p '#S' 2>/dev/null)
+fi
+
+# Extract the explicit -t target, if any. `tmux send-keys` / `tmux paste-buffer`
+# without `-t` target the current pane (self), so those are allowed.
+TARGET=$(printf '%s' "$COMMAND" | grep -oE -- '-t[[:space:]]+[^[:space:]]+' | tail -n1 | sed -E 's/^-t[[:space:]]+//' 2>/dev/null)
+if [ -z "$TARGET" ]; then
+  exit 0
+fi
+
+# Normalize session names for comparison. tmux pane targets look like
+# "session:window.pane" or "session.window-pane"; the session is the prefix.
+TARGET_SESSION=$(printf '%s' "$TARGET" | sed -E 's/[:.].*$//' 2>/dev/null)
+
+if [ -n "$SELF_SESSION" ] && [ "$TARGET_SESSION" = "$SELF_SESSION" ]; then
+  exit 0
+fi
+
+# Target is explicitly another session (or we cannot determine self). Rewrite
+# to a failing command so the agent sees a clear error and cannot silently
+# drive another session.
+BLOCKED_REASON="BLOCKED: tmux send-keys/paste-buffer targeting another tmux session (${TARGET_SESSION}) is forbidden (PAN-1084). Capture the pane with tmux -L overdeck capture-pane -t <session> -p and surface the issue via pan tell instead."
+
+jq -n \
+  --arg reason "$BLOCKED_REASON" \
+  '{
+    hookSpecificOutput: {
+      hookEventName: "PreToolUse",
+      updatedInput: {
+        command: ("printf '\''%s\\n'\'' \"" + $reason + "\" >&2; false")
+      }
+    }
+  }'
+
+exit 0

package/sync-sources/hooks/tsdown.config.ts

@@ -0,0 +1,14 @@
+import { defineConfig } from 'tsdown';
+
+export default defineConfig({
+  entry: ['record-cost-event.ts', 'gh-issue-trailer-hook.ts'],
+  format: 'esm',
+  platform: 'node',
+  shims: true,
+  outDir: '.',
+  clean: false,
+  outExtensions: () => ({ js: '.js' }),
+  // Bundle all dependencies inline — this script runs standalone at ~/.overdeck/bin/
+  // with no node_modules, so imports like 'yaml' must be embedded.
+  noExternal: [/.*/],
+});

package/sync-sources/hooks/user-prompt-submit-hook

@@ -0,0 +1,57 @@
+#!/bin/bash
+# ~/.overdeck/bin/user-prompt-submit-hook
+#
+# Fires on Claude Code UserPromptSubmit. Emits three events:
+#   1. agent.waiting_cleared  — clears hasPendingQuestion / suspension
+#   2. agent.message_received — updates lastActivity + lastMessageAt
+#   3. agent.activity_changed(thinking) — Claude is processing the prompt now
+#
+# Previously emitted activity=idle "so the dashboard spinner restarts." That
+# was a UI hack that lied about runtime state: Claude is NOT idle right after
+# the user submits a prompt — it's about to start thinking and may take many
+# minutes before the first PreToolUse hook fires. The deacon's stale-active
+# check would then read state=idle + old lastActivity and nudge with a
+# "you appear to have stopped working" message, cancelling Claude mid-think
+# (PAN-1024 reproduced this loop). Emitting activity=thinking keeps the
+# runtime snapshot honest until pre-tool-hook takes over.
+
+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
+
+INPUT=$(cat 2>/dev/null || echo '{}')
+TS=$(date -Iseconds)
+
+pan_emit_event "$AGENT_ID" "{\"kind\":\"waiting_clear\",\"clearedBy\":\"user_response\",\"timestamp\":\"$TS\"}"
+pan_emit_event "$AGENT_ID" "{\"kind\":\"message_received\",\"direction\":\"to_agent\",\"source\":\"user\",\"timestamp\":\"$TS\"}"
+pan_emit_event "$AGENT_ID" "{\"kind\":\"thinking_start\",\"lastToolAt\":\"$TS\",\"timestamp\":\"$TS\"}"
+
+INTERNAL_TOKEN="${OVERDECK_INTERNAL_TOKEN:-}"
+if [ -z "$INTERNAL_TOKEN" ]; then
+  TOKEN_PATH="${OVERDECK_HOME:-$HOME/.overdeck}/internal-token"
+  if [ -f "$TOKEN_PATH" ]; then
+    INTERNAL_TOKEN=$(cat "$TOKEN_PATH" 2>/dev/null || true)
+  fi
+fi
+
+if command -v jq >/dev/null 2>&1; then
+  TITLE_BODY=$(printf '%s' "$INPUT" | jq -c '{session_id: (.session_id // ""), prompt: (.prompt // .message // .input // "")}' 2>/dev/null)
+  if [ -n "$TITLE_BODY" ]; then
+    curl -s -m 1 -X POST -H 'Content-Type: application/json' -H "x-overdeck-internal-token: $INTERNAL_TOKEN" --data "$TITLE_BODY" "$PAN_DASHBOARD_URL/api/hooks/user-prompt-submit" >/dev/null 2>&1 || true
+  fi
+
+  INJECT_BODY=$(printf '%s' "$INPUT" | jq -c --arg agentId "$AGENT_ID" '{prompt: (.prompt // .message // .input // ""), sessionId: (.session_id // ""), agentId: $agentId}' 2>/dev/null)
+  if [ -n "$INJECT_BODY" ]; then
+    INJECT_RESPONSE=$(curl -s -m 1 -X POST -H 'Content-Type: application/json' -H "x-overdeck-internal-token: $INTERNAL_TOKEN" --data "$INJECT_BODY" "$PAN_DASHBOARD_URL/api/memory/inject" 2>/dev/null || true)
+    INJECT_CONTEXT=$(printf '%s' "$INJECT_RESPONSE" | jq -r 'if .ok == true and (.context // "") != "" then .context else empty end' 2>/dev/null)
+    if [ -n "$INJECT_CONTEXT" ]; then
+      printf '%s\n' "$INJECT_CONTEXT"
+    fi
+  fi
+fi
+
+exit 0