@overdeck/desktop 0.47.0 → 0.48.0

package/sync-sources/hooks/notification-hook

@@ -46,8 +46,19 @@ 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.
+#
+# Exact-match exclusion first: "Claude is waiting for your input" is Claude
+# Code's idle-timeout heartbeat, fired for ANY agent idle >60s — after a
+# completed turn, between items, or when work is done. It carries no question,
+# and classifying it as user_question surfaced every long-idle agent as a
+# blocking "Question for you" decision with no content (seen on PAN-3253).
+# Real questions are detected by the JSONL AskUserQuestion scan and the pane
+# detector; this heartbeat must stay a non-event. Anchored exactly so a future
+# message that appends actual question text still classifies below.
 REASON=""
-if echo "$NOTIF_MSG" | grep -qiE '(permission|approval|allow.*tool|confirm.*tool)'; then
+if echo "$NOTIF_MSG" | grep -qixE 'claude is waiting for your input'; then
+  REASON=""
+elif 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"

package/sync-sources/hooks/pan-hook-lib.sh

@@ -14,6 +14,232 @@
 PAN_DASHBOARD_URL="${OVERDECK_DASHBOARD_URL:-http://localhost:3011}"
 PAN_CURL_TIMEOUT="${OVERDECK_HOOK_TIMEOUT:-0.5}"
 
+# Acquire a portable single-flight lock. A tiny Python helper holds the kernel
+# advisory lock for the caller's lifetime; the directory is ownership metadata,
+# not the synchronization primitive. Publishing the kernel lock before creating
+# the metadata closes the mkdir-to-PID initialization race (PAN-3294).
+pan_acquire_singleflight_lock() {
+  local lock_dir="$1"
+  local guard_file="${lock_dir}.flock"
+  local ready_file="${guard_file}.ready.$$.$RANDOM"
+  local lock_parent
+  lock_parent=$(dirname "$lock_dir")
+  mkdir -p "$lock_parent" 2>/dev/null || return 1
+
+  python3 - "$guard_file" "$ready_file" "$$" >/dev/null 2>&1 <<'PY' &
+import fcntl
+import os
+import sys
+import time
+
+guard_file, ready_file, parent_pid_text = sys.argv[1:]
+parent_pid = int(parent_pid_text)
+fd = os.open(guard_file, os.O_CREAT | os.O_RDWR, 0o600)
+try:
+    fcntl.flock(fd, fcntl.LOCK_EX | fcntl.LOCK_NB)
+except BlockingIOError:
+    with open(ready_file, "w", encoding="utf-8") as ready:
+        ready.write("busy\n")
+    raise SystemExit(0)
+
+with open(ready_file, "w", encoding="utf-8") as ready:
+    ready.write("acquired\n")
+
+while True:
+    try:
+        os.kill(parent_pid, 0)
+    except OSError:
+        break
+    if os.getppid() == 1:
+        break
+    time.sleep(0.1)
+PY
+  local helper_pid=$!
+
+  local attempts=0
+  while [ ! -s "$ready_file" ] && kill -0 "$helper_pid" 2>/dev/null && [ "$attempts" -lt 100 ]; do
+    /bin/sleep 0.01
+    attempts=$((attempts + 1))
+  done
+
+  local lock_status
+  lock_status=$(cat "$ready_file" 2>/dev/null || true)
+  rm -f "$ready_file" 2>/dev/null || true
+  if [ "$lock_status" != "acquired" ]; then
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+    return 1
+  fi
+
+  # The kernel lock is already held, so stale metadata can be replaced without
+  # exposing an unowned interval to contenders.
+  rm -rf "$lock_dir" 2>/dev/null || {
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+    return 1
+  }
+  mkdir "$lock_dir" 2>/dev/null || {
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+    return 1
+  }
+  printf '%s\n' "$$" > "$lock_dir/pid" || {
+    rm -rf "$lock_dir" 2>/dev/null || true
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+    return 1
+  }
+  printf '%s\n' "$helper_pid" > "$lock_dir/helper-pid" || {
+    rm -rf "$lock_dir" 2>/dev/null || true
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+    return 1
+  }
+  return 0
+}
+
+pan_release_singleflight_lock() {
+  local lock_dir="$1"
+  local owner_pid helper_pid
+  owner_pid=$(cat "$lock_dir/pid" 2>/dev/null || true)
+  helper_pid=$(cat "$lock_dir/helper-pid" 2>/dev/null || true)
+
+  # A caller may release only metadata it owns. Remove that metadata before
+  # dropping the kernel lock; a successor cannot acquire until the helper exits,
+  # and this owner performs no destructive filesystem action after that point.
+  [ "$owner_pid" = "$$" ] || return 0
+  rm -rf "$lock_dir" 2>/dev/null || return 0
+  if [[ "$helper_pid" =~ ^[1-9][0-9]*$ ]]; then
+    kill "$helper_pid" 2>/dev/null || true
+    wait "$helper_pid" 2>/dev/null || true
+  fi
+  return 0
+}
+
+# Run a command with a hard deadline while preserving its stdin, stdout, and
+# ordinary exit code. GNU timeout is preferred when installed; stock macOS uses
+# the pure-bash watchdog fallback. Expiry is always reported as 124.
+pan_run_with_timeout() {
+  local timeout_seconds="$1"
+  shift
+
+  if command -v timeout >/dev/null 2>&1; then
+    if timeout -k 5 "$timeout_seconds" "$@"; then
+      return 0
+    else
+      return $?
+    fi
+  fi
+  if command -v gtimeout >/dev/null 2>&1; then
+    if gtimeout -k 5 "$timeout_seconds" "$@"; then
+      return 0
+    else
+      return $?
+    fi
+  fi
+
+  local expired_file="${TMPDIR:-/tmp}/pan-hook-timeout.$$.$RANDOM"
+  "$@" &
+  local command_pid=$!
+  (
+    local sleep_pid=""
+    trap '[ -n "$sleep_pid" ] && kill "$sleep_pid" 2>/dev/null; exit 0' TERM INT
+
+    /bin/sleep "$timeout_seconds" &
+    sleep_pid=$!
+    wait "$sleep_pid" 2>/dev/null || exit 0
+    sleep_pid=""
+
+    if kill -0 "$command_pid" 2>/dev/null; then
+      : > "$expired_file"
+      kill -TERM "$command_pid" 2>/dev/null || true
+      /bin/sleep 5 &
+      sleep_pid=$!
+      wait "$sleep_pid" 2>/dev/null || exit 0
+      sleep_pid=""
+      kill -KILL "$command_pid" 2>/dev/null || true
+    fi
+  ) &
+  local watchdog_pid=$!
+
+  local command_rc
+  if wait "$command_pid"; then
+    command_rc=0
+  else
+    command_rc=$?
+  fi
+
+  kill "$watchdog_pid" 2>/dev/null || true
+  wait "$watchdog_pid" 2>/dev/null || true
+
+  if [ -f "$expired_file" ]; then
+    /bin/rm -f "$expired_file" 2>/dev/null || true
+    return 124
+  fi
+
+  return "$command_rc"
+}
+
+# Admit at most OVERDECK_HOOK_LLM_RATE_LIMIT hook-initiated LLM calls in a
+# rolling 60-second machine-wide window. Returns 0 after recording an allowed
+# call and 1 when the bucket is full or cannot be locked safely.
+pan_llm_rate_check() {
+  local overdeck_home="${OVERDECK_HOME:-$HOME/.overdeck}"
+  local bucket_file="$overdeck_home/hook-llm-calls.log"
+  local lock_dir="$overdeck_home/hook-llm-calls.lock.d"
+  local limit="${OVERDECK_HOOK_LLM_RATE_LIMIT:-6}"
+  [[ "$limit" =~ ^[0-9]+$ ]] || limit=6
+
+  mkdir -p "$overdeck_home" 2>/dev/null || return 1
+
+  local attempt=0
+  local acquired=0
+  while [ "$attempt" -lt 10 ]; do
+    if pan_acquire_singleflight_lock "$lock_dir"; then
+      acquired=1
+      break
+    fi
+    attempt=$((attempt + 1))
+    [ "$attempt" -lt 10 ] && /bin/sleep 0.1
+  done
+  [ "$acquired" = "1" ] || return 1
+
+  local now cutoff timestamp count=0
+  now=$(date +%s 2>/dev/null) || {
+    pan_release_singleflight_lock "$lock_dir"
+    return 1
+  }
+  cutoff=$((now - 60))
+
+  local bucket_tmp="${bucket_file}.tmp.$$"
+  : > "$bucket_tmp" 2>/dev/null || {
+    pan_release_singleflight_lock "$lock_dir"
+    return 1
+  }
+
+  if [ -f "$bucket_file" ]; then
+    while IFS= read -r timestamp; do
+      if [[ "$timestamp" =~ ^[0-9]+$ ]] && [ "$timestamp" -ge "$cutoff" ]; then
+        printf '%s\n' "$timestamp" >> "$bucket_tmp"
+        count=$((count + 1))
+      fi
+    done < "$bucket_file"
+  fi
+
+  local allowed=1
+  if [ "$count" -lt "$limit" ]; then
+    printf '%s\n' "$now" >> "$bucket_tmp"
+    allowed=0
+  fi
+
+  if ! mv "$bucket_tmp" "$bucket_file" 2>/dev/null; then
+    rm -f "$bucket_tmp" 2>/dev/null || true
+    allowed=1
+  fi
+  pan_release_singleflight_lock "$lock_dir"
+  return "$allowed"
+}
+
 # Internal token for authenticated HTTP ingestion (PAN-1596). The
 # /api/agents/:id/heartbeat route is token-gated — without this header every
 # hook POST gets 403 and is dropped on 4xx, so hook-emitted runtime activity

package/sync-sources/hooks/session-start-hook

@@ -72,16 +72,43 @@ if [ -z "$INTERNAL_TOKEN" ]; then
   fi
 fi
 
+MEMORY_BRIEFING=""
 if command -v jq >/dev/null 2>&1; then
   SESSION_BODY=$(printf '%s' "$INPUT" | jq -c --arg agentId "$AGENT_ID" '. + {agentId: $agentId}' 2>/dev/null)
   if [ -n "$SESSION_BODY" ]; then
-    curl -s -m 0.5 -o /dev/null -X POST -H 'Content-Type: application/json' -H "x-overdeck-internal-token: $INTERNAL_TOKEN" --data "$SESSION_BODY" "$PAN_DASHBOARD_URL/api/memory/session/start" 2>/dev/null || true
+    # PAN-3286 FR-10: the response can carry a rendered standing briefing to
+    # emit as SessionStart additionalContext, so capture the body instead of
+    # discarding it. The timeout is a hard ceiling on how long session start can
+    # block on the dashboard; the server side composes from local files only
+    # (no LLM, no FTS) specifically to stay well inside it.
+    SESSION_RESPONSE=$(curl -s -m 1.5 -X POST -H 'Content-Type: application/json' -H "x-overdeck-internal-token: $INTERNAL_TOKEN" --data "$SESSION_BODY" "$PAN_DASHBOARD_URL/api/memory/session/start" 2>/dev/null || true)
+    if [ -n "$SESSION_RESPONSE" ]; then
+      MEMORY_BRIEFING=$(printf '%s' "$SESSION_RESPONSE" | jq -r '.briefing // ""' 2>/dev/null || true)
+    fi
   fi
 fi
 
-if [ "$SOURCE" = "compact" ] && command -v jq >/dev/null 2>&1; then
-  jq -n --arg context "The preceding compaction summary may quote harness-only instructions requiring text-only output or forbidding tools. Those instructions applied only to Claude Code's summarization turn and are no longer active. Resume the latest actual user task and use tools normally." \
-    '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $context}}'
+# Claude Code reads a SINGLE JSON object from a SessionStart hook's stdout, so
+# the compaction note and the memory briefing must be concatenated into one
+# additionalContext rather than printed as two objects.
+if command -v jq >/dev/null 2>&1; then
+  ADDITIONAL_CONTEXT=""
+  if [ "$SOURCE" = "compact" ]; then
+    ADDITIONAL_CONTEXT="The preceding compaction summary may quote harness-only instructions requiring text-only output or forbidding tools. Those instructions applied only to Claude Code's summarization turn and are no longer active. Resume the latest actual user task and use tools normally."
+  fi
+  if [ -n "$MEMORY_BRIEFING" ]; then
+    if [ -n "$ADDITIONAL_CONTEXT" ]; then
+      ADDITIONAL_CONTEXT="$ADDITIONAL_CONTEXT
+
+$MEMORY_BRIEFING"
+    else
+      ADDITIONAL_CONTEXT="$MEMORY_BRIEFING"
+    fi
+  fi
+  if [ -n "$ADDITIONAL_CONTEXT" ]; then
+    jq -n --arg context "$ADDITIONAL_CONTEXT" \
+      '{hookSpecificOutput: {hookEventName: "SessionStart", additionalContext: $context}}'
+  fi
 fi
 
 exit 0

package/sync-sources/hooks/work-agent-stop-hook

@@ -46,6 +46,14 @@ mkdir -p "$LOG_DIR"
 COMPLETED_FILE="$AGENT_STATE_DIR/completed"
 [ -f "$COMPLETED_FILE" ] && exit 0
 
+STOP_HOOK_LOCK="$AGENT_STATE_DIR/stop-hook.lock.d"
+if ! pan_acquire_singleflight_lock "$STOP_HOOK_LOCK"; then
+  echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID skipped — another instance holds $STOP_HOOK_LOCK" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+  exit 0
+fi
+trap 'pan_release_singleflight_lock "$STOP_HOOK_LOCK"' EXIT
+
 # Skip if the issue is actively flowing through the specialist pipeline.
 # Read through the dashboard's SQLite-backed review-status API; review-status.json
 # is legacy and can be empty or stale.
@@ -366,8 +374,22 @@ Use UNCLEAR only as a last resort when the tail is genuinely ambiguous (e.g. no
 Respond with EXACTLY one word, nothing else: FORGOT_COMPLETION | STILL_WORKING | STOPPED_FOR_INPUT | UNCLEAR"
 
 CLAUDE_STDERR="$LOG_DIR/work-agent-stop-hook.claude-stderr.log"
-RESULT=$(echo "$ANALYSIS_PROMPT" | claude -p --model "$COMPLETION_MODEL" 2>>"$CLAUDE_STDERR")
+if ! pan_llm_rate_check; then
+  echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID rate-limited — skipping completion-check LLM" \
+    >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+  exit 0
+fi
+
+RESULT=$(echo "$ANALYSIS_PROMPT" | pan_run_with_timeout "${OVERDECK_HOOK_LLM_TIMEOUT:-60}" \
+  claude -p --model "$COMPLETION_MODEL" 2>>"$CLAUDE_STDERR")
 CLAUDE_RC=$?
+case "$CLAUDE_RC" in
+  124|137|143)
+    echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID completion-check LLM timed out rc=$CLAUDE_RC — no resolution emitted" \
+      >> "$LOG_DIR/hooks.log" 2>/dev/null || true
+    exit 0
+    ;;
+esac
 if [ $CLAUDE_RC -ne 0 ] || [ -z "$RESULT" ]; then
   echo "[$(date -Iseconds)] work-agent-stop-hook: $AGENT_ID claude -p failed rc=$CLAUDE_RC (see $CLAUDE_STDERR), fallback to UNCLEAR" \
     >> "$LOG_DIR/hooks.log" 2>/dev/null || true

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

@@ -5,6 +5,7 @@ triggers:
   - pan memory
   - memory search
   - memory status
+  - memory --target
 allowed-tools:
   - Bash
   - Read
@@ -17,16 +18,31 @@ Use `pan memory` to inspect the durable memory substrate for a project or issue.
 ## Commands
 
 ```bash
-pan memory search <query> [--project <id>] [--workspace <id>] [--issue <id>] [--tag <tag>] [--sibling] [--include-archived] [--limit <n>] [--json]
-pan memory status <issue> [--project <id>] [--json]
+pan memory search <query> [--project <id>] [--workspace <id|name>] [--issue <id>] [--tag <tag>] [--sibling] [--global] [--target [path]] [--include-archived] [--limit <n>] [--json]
+pan memory status [issue] [--project <id>] [--workspace <id|name>] [--history <n>] [--json]
+pan memory timeline [--workspace <id|name>] [--days <n>] [--limit <n>] [--json]
+pan memory read <path> [--workspace <id|name>] [--from <n>] [--lines <n>]
 pan memory reset <scope> <scopeId> --reason <text> [--project <id>] [--from <iso>] [--json]
-pan memory summary <issue> [--project <id>] [--date <yyyy-mm-dd>] [--json]
+pan memory summary [issue] [--project <id>] [--workspace <id|name>] [--date <yyyy-mm-dd>] [--json]
 pan memory doctor [--project <id>] [--json]
+pan memory backfill [--workspace <id>] [--project <id>] [--dry-run] [--json]
+pan memory pin <doc-path> [--project <id> | --workspace <id>] [--json]
+pan memory unpin <doc-path> [--project <id> | --workspace <id>] [--json]
+pan memory pins [--project <id> | --workspace <id>] [--json]
 pan memory config [--json]
 ```
 
 ## Notes
 
 - `search --sibling --issue <id>` searches same-project sibling issues instead of the selected issue.
+- `search --global` merges results across every registered project instead of just the selected/default one.
+- `search --workspace` accepts either a workspace id or a workspace name; a name matching more than one workspace across projects errors instead of guessing.
+- `search --target [path]` (Subspace `target-search` parity) finds every non-archived workspace whose `path` targets a directory — bare `--target` defaults to the current working directory. Mutually exclusive with `--workspace`/`--issue`/`--global`. Fans out per matched workspace (which may span several projects) and merges by rank score, same as `--global`'s per-project merge. When no workspace targets the directory, prints a friendly "No workspaces target `<dir>`." note and exits 0.
+- `status` and `summary` address a workspace three ways, in precedence order: `--workspace <id|name>`, an issue positional, then the workspace that owns the current directory. With none of the three resolvable the command exits non-zero and names all three modes. A workspace with no issue (main/scratch) is titled by its workspace name in `summary` output.
+- `status --history <n>` prints the current status first, then up to N archived statuses newest-first with their archive timestamp, phase, and headline. N is capped at 50; the rollup writer prunes the on-disk archive to its three most recent entries, so N above 3 returns whatever is still retained. `--history` with `--json` emits `{current, history}` where each history entry is `{archivedAt, path, status}`.
+- `timeline` prints one row per observation — timestamp, the action status or summary, and the files touched — oldest first, for the workspace named by `--workspace` or the one owning the current directory. `--days` counts today as day 1 and defaults to 7; `--limit` caps the row count at the 50 most recent by default; `--json` emits the observation rows.
+- `read` prints a file from the workspace's memory home; `<path>` is relative to that home and `--from`/`--lines` slice it by 1-based line number. It refuses, with a non-zero exit, any absolute path, any `../` traversal, and any symlink whose real target is outside the home — so Claude Code JSONL session files under `~/.claude` are unreachable by construction.
 - `reset` creates a reset marker; it does not delete historical memory records.
 - `doctor` exits non-zero when an active agent has no successful extraction in the last hour.
+- `backfill` reads historical Claude Code JSONL transcripts under `~/.claude/projects/` and extracts observations for sessions whose first-message cwd maps to a registered workspace; unmatched sessions are skipped. Read-only on the JSONL files — `--dry-run` reports matches without extracting or writing anything.
+- `pin`/`unpin`/`pins` manage docs injected under the knowledge budget at prompt time. `--workspace` overrides `--project`; paths are stored project-relative regardless of scope.

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

@@ -85,6 +85,15 @@ pan project remove myapp
 
 **Note:** This only removes the project from Overdeck's registry. It does NOT delete the actual project files.
 
+### Add a Secondary Target Path (PAN-1990)
+
+```bash
+pan project add-target myproject --path /path/to/secondary/checkout
+pan project add-target myproject --path /path/to/primary/checkout --primary
+```
+
+A project can have multiple target paths (e.g. a secondary worktree or mirror). `--primary` marks the given path as the primary target, demoting any previously-primary target — exactly one target is primary at a time.
+
 ## Project Requirements
 
 For a project to work well with Overdeck:

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

@@ -38,9 +38,9 @@ pan restart --force              # explicit operator bypass of the deploy-window
 pan restart --cliproxy --force   # redownload the pinned CLIProxy binary
 ```
 
-Each stage is health-gated: the command waits for `GET /api/health` (dashboard)
-or port binding (CLIProxy) to succeed before reporting `✓`, and exits non-zero
-with a `[stage] reason` message on timeout.
+Each stage is health-gated: the command waits for `GET /api/health` from the
+newly spawned dashboard process, or port binding for CLIProxy, before reporting
+`✓`. It exits non-zero with a `[stage] reason` message on timeout.
 
 ## Identity guard
 
@@ -49,10 +49,29 @@ non-primary checkout: either a workspace worktree or any linked Git worktree,
 including a handoff worktree. It exits with code 2 and names the primary
 checkout where the command must run.
 
-The post-boot health gate verifies both `repoRoot` and `mode` from
-`GET /api/health`. If another server holds the port, the command reports
-`port held by non-primary server (cwd=…, mode=…)`; a 200 response from the wrong
-server is a failure, not a successful restart.
+The post-boot health gate verifies `repoRoot`, `mode`, and the serving process
+PID from `GET /api/health`. A 200 response succeeds only when its PID matches the
+process this restart spawned. A different checkout reports
+`port held by non-primary server (cwd=…, mode=…)`; an old process from the same
+checkout reports `port answered by pid X — not the freshly spawned server (pid
+Y)`. Either response is a failure, not a successful restart.
+
+## Ownership-mismatch recovery
+
+When restart names PID X as the existing port owner, inspect that exact process
+before acting:
+
+```bash
+ps -p X -o pid=,ppid=,etime=,cmd=
+lsof -nP -iTCP:3011 -sTCP:LISTEN
+```
+
+If it is the stale dashboard named by the failure, terminate it with `kill X`,
+verify that the PID and listener are gone, then rerun `pan restart`. Do not use a
+broad `pkill` pattern: it can terminate the supervisor, agents, or unrelated Node
+processes. A fresh `EADDRINUSE` line fails restart immediately and names the same
+owner, while a health timeout leaves the newly spawned process running for
+inspection.
 
 ## Important Notes
 

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

@@ -0,0 +1,77 @@
+---
+name: pan-workspace
+description: "pan workspace new/main/get/activate/archive/relocate — the PAN-1990 projects/workspaces domain: kinds, doors, memory homes"
+triggers:
+  - pan workspace new
+  - pan workspace main
+  - pan workspace relocate
+  - scratch workspace
+  - workspace kind
+allowed-tools:
+  - Bash
+  - Read
+---
+
+# Pan Workspace (PAN-1990 domain)
+
+`pan workspace` is overloaded — it also carries the older PAN-428 issue/git-worktree
+lifecycle (`create`, `migrate`, `ssh`, `destroy`, …), which this skill does **not**
+cover. This skill wraps only the newer projects/workspaces domain: every registered
+project has exactly one `main` workspace plus any number of `issue` (one per tracked
+issue) and `scratch` (ad-hoc, unattached to an issue) workspaces, all rows in the
+`workspaces` table read through `src/lib/workspaces/resolver.ts` and written through
+`src/lib/workspaces/writer.ts` — see `docs/WORKSPACES-AND-PROJECTS.md` for the full
+model.
+
+## Commands
+
+```bash
+pan workspace new <name> [--project <key>] [--isolated] [--parent-branch <branch>] [--target-path <dir>] [--dry-run]
+pan workspace main [--project <key>]
+pan workspace get <ws>
+pan workspace activate <ws>
+pan workspace archive <ws>
+pan workspace relocate <ws> --path <dir> [--force]
+pan workspace list [--kind <main|issue|scratch>] [--archived] [--json] [--all]
+```
+
+## Notes
+
+- `new <name>` creates a **scratch** workspace. By default it shares the project's
+  primary directory (same worktree, no new branch); pass `--isolated` to create a
+  separate git worktree instead, with `--parent-branch` overriding the inferred
+  parent (defaults to the project's current branch).
+- `--target-path <dir>` points the scratch workspace at any existing directory
+  instead of the project's primary path — this is how a workspace becomes a
+  long-lived lens onto an arbitrary repo, independent of `--isolated`'s
+  worktree-per-branch model. Mutually exclusive with `--isolated`; the path must
+  already exist. `is_git_repository` is detected from `<dir>/.git`. If the
+  resolved directory isn't the project's primary path or a path registered via
+  `pan project add-target`, the command still creates the row but prints an
+  informational note suggesting `pan project add-target`.
+- `--dry-run` prints the resolved intent (`projectId`, `kind`, `name`, `path`,
+  `branchName`, `parentBranch`, `parentBranchGuessed`, `isGitRepository`,
+  `wouldCreateWorktree`) as JSON and returns before any worktree is created or
+  workspace row is written — no DB row, no worktree, no memory home.
+- `main [--project <key>]` resolves the project's singleton main workspace, creating
+  it if it doesn't exist yet. There is exactly one `main` workspace per project —
+  `archive` refuses to touch it.
+- `--project <key>` on `new`/`main` defaults to the sole registered project, or the
+  one resolved from the current working directory, when omitted.
+- `get <ws>` prints the full row (id, kind, project, path, branch, issue, archived,
+  favorite, lastAccess) plus `memoryHome` — the workspace's memory-home directory
+  (`resolveWorkspaceMemoryRoot`), keyed by workspace id and stable across relocation.
+- `activate <ws>` bumps `lastAccessedAt` (drives most-recent-first ordering in the
+  Sidebar and Cmd-K switcher) and prints a hint to restore `layoutConfig` if the
+  workspace has a saved dashboard pane arrangement.
+- `archive <ws>` is reversible and refuses `kind=main`.
+- `relocate <ws> --path <dir>` (Subspace `workspaces update --relocate` parity) points
+  an existing workspace at a new path: updates the `path` column, re-detects
+  `is_git_repository` from `<dir>/.git`, touches `lastAccessedAt`, and re-writes the
+  memory-home `metadata.json` recovery hint — the memory home itself never moves,
+  since it's keyed by workspace id, not path. `<ws>` accepts an id or a name
+  (ambiguous names across projects error out asking for the id). Refuses
+  `kind=issue` (pipeline-owned) and archived workspaces; `kind=main` requires
+  `--force` since it diverges the row from projects.yaml's primary path.
+- `list --kind <kind>` reads through the resolver the same way the dashboard does;
+  add `--archived` to include archived rows (only meaningful together with `--kind`).

package/server/activity-logger-CMthG6Vd.js

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

package/server/agent-state-CYXJVG72.js

@@ -1,3 +0,0 @@
-import { Jn as clearAgentPausedSync, Xn as clearAgentTroubledSync, ir as init_agent_state, rr as getAgentStateSync, yr as setAgentPausedSync } from "./queries-C-MUZaIy.js";
-init_agent_state();
-export { clearAgentPausedSync, clearAgentTroubledSync, getAgentStateSync, setAgentPausedSync };

package/server/agents-ePFVoZbu.js

@@ -1,3 +0,0 @@
-import { $n as getAgentDir, An as getProviderExportsForModel, B as detectCrashedAgents, Bn as dismissDevChannelsDialog, Br as saveAgentRuntimeState, C as replayCrashedStandingAgent, Dn as buildSpawnEnvForModel, En as buildCavemanExports, Fr as waitForAgentIdle, Ft as deliverResumeMessageWithTranscriptConfirmation, G as resumeAgent, Gn as SESSION_EXITED_BEFORE_KICKOFF, Gt as assertWorkspaceStackHealthyForSpawn, H as restartAgent, In as buildDefaultResumeContinueMessage, Ir as waitForReadySignal, Jn as clearAgentPausedSync, Kn as __testInternals, Kt as buildAgentLaunchConfig, Ln as buildResumeContinueMessage, Lr as getAgentRuntimeState, Mr as isQualifiedAgentId, Mt as deliverAgentMessage, Nr as normalizeAgentId, Nt as deliverAgentPermissionDecision, On as determineModel, Pr as resolveAgentTargetSync, Pt as deliverInitialPromptWithRetry, Rn as decideChannelsForWorkAgent, Rr as getAgentRuntimeStateSync, Rt as setAgentDeliveryMethod, S as contextWindowForModel, Sr as writeAgentStateJsonSync, T as shouldReplayCompactAtTierRunBoundary, U as buildCompactRecoverySeed, Un as writeChannelsBridgeMcpConfig, V as recoverAgent, Wn as GOVERNOR_SLOT_PAUSE_REASON_PREFIX, X as messageAgent, Xn as clearAgentTroubledSync, Xt as transitionIssueToInProgress, Yn as clearAgentTroubled, Yt as retrieveSpawnTimeMemoryContext, Zn as clearYieldForResumeSync, Zt as transitionIssueToInReview, _n as waitForPromptReady, _r as saveAgentStateSync, a as listRunningAgentsSync, an as OHMYPI_AGENT_READY_TIMEOUT_SECONDS, ar as isAgentPaused, b as init_agents, br as setAgentYieldedSync, cn as getAgentRuntimeBaseCommand, dn as getProviderAuthMode, dr as markAgentTroubled, dt as spawnRun, et as appendActivity, fn as getRoleRuntimeBaseCommand, fr as recordAgentFailure, gr as saveAgentState, hn as roleAgentDefinitionPath, hr as resetAgentFailureCount, i as listRunningAgents, it as getSessionId, jn as getProviderTmuxFlags, jr as clearReadySignal, kn as getProviderEnvForModel, lr as markAgentRunningState, mn as injectPiConversationMemory, mt as stopAgentSync, nr as getAgentStateFilePath, nt as getLatestSessionId, o as warnOnBareNumericIssueIds, on as describeOhmypiSpawnFailure, or as isAgentTroubled, ot as saveSessionId, pr as recordAgentFailureSync, pt as stopAgent, qn as clearAgentPaused, r as listAgentStates, rr as getAgentStateSync, rt as getLatestSessionIdSync, sr as isRole, t as dropLegacyAgentStatesMissingRoleAsync, tr as getAgentState, tt as getActivity, ur as markAgentStoppedState, ut as spawnAgent, vr as setAgentPaused, w as replayStandingAgent, x as compactAtTierRunBoundary, xr as wipeAgentStateDirs, yr as setAgentPausedSync, z as autoRecoverAgents, zn as decideSupervisorForWorkAgent } from "./queries-C-MUZaIy.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 };

package/server/archive-planning-B2XplFzT.js

@@ -1,2 +0,0 @@
-import { i as findWorkspacePath } from "./archive-planning-BwhxeP7C.js";
-export { findWorkspacePath };

package/server/cli-CjOCSnfj.js

@@ -1,3 +0,0 @@
-import { r as init_cli, t as createResetMarker } from "./cli-Cte9ZFGn.js";
-init_cli();
-export { createResetMarker };

package/server/deacon-swarm-B1XkIvfr.js

@@ -1,2 +0,0 @@
-import { r as coordinateSwarmSlots } from "./deacon-swarm-v5PMun-m.js";
-export { coordinateSwarmSlots };

package/server/delivery-BX9HR4wQ.js

@@ -1,3 +0,0 @@
-import { It as init_delivery, Mt as deliverAgentMessage } from "./queries-C-MUZaIy.js";
-init_delivery();
-export { deliverAgentMessage };

package/server/dist-B3YPQa5A.js

@@ -1,3 +0,0 @@
-import { t as require_dist } from "./dist-C3A8B8wM.js";
-export default require_dist();
-export {};

package/server/event-store-5UKzh9Jf.js

@@ -1,3 +0,0 @@
-import { a as init_event_store, i as initEventStore, n as getEventStore, o as openEventDb, r as getSharedDb, t as createEventStore } from "./event-store-CrHcVC5_.js";
-init_event_store();
-export { createEventStore, getEventStore, getSharedDb, initEventStore, openEventDb };

package/server/forge-B5o319qI.js

@@ -1,3 +0,0 @@
-import { n as getForgeAdapter, r as init_forge } from "./forge-BaKGCya6.js";
-init_forge();
-export { getForgeAdapter };