@overdeck/desktop 0.49.1 → 0.50.0

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

@@ -48,6 +48,7 @@ state it is in to running work.
   from the existing xBRIEF and xBRIEF tasks.
 - **Already running** — `pan start` exits 0 with a no-op message naming `pan tell <id>` for
   messaging and the tmux attach command.
+- **Swarm active** — the bare parent agent is the foreman. `pan start` attaches to or restores that foreman instead of refusing because slot agents exist; it never creates a competing serial parent.
 
 Planning depth is controlled by `--plan`:
 
@@ -65,6 +66,8 @@ Start-time policy flags are persisted on the issue before planning or work begin
 sets the durable work-model override used by later respawns, `--swarm` accepts `off`, `auto`,
 or `always`, `--review-mode` accepts `quick`, `full`, or `none`, and `--review-model` pins the
 model used by the review convoy. Omitted flags leave existing and inherited policy untouched.
+Swarm mode controls automatic foreman creation, not Deacon slot dispatch. `off` keeps serial work,
+while `auto` and `always` allow a readiness-eligible foreman loop.
 When this start also kicks off planning (no plan exists yet), `--plan-model <model>` overrides
 the planning agent's model for that session only — it is a one-shot override, not persisted
 policy, and it never changes the work agent's model (`--model`).

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

@@ -1,77 +1,65 @@
 ---
 name: pan-swarm
-description: Start and recover Overdeck swarm slots for planned issues with `pan swarm`; use for parallel work dispatch or failed-slot recovery.
+description: Start or operate a foreman-driven Overdeck swarm with gated dispatch, merge, observation, and recovery commands.
 ---
 
 # Pan Swarm
 
-Use `pan swarm` when an issue has a finalized xBRIEF plan and the operator wants Deacon-managed parallel slot execution.
+Use `pan swarm` only for a finalized, swarm-eligible xBRIEF. The resident parent work agent is the foreman. It owns decisions and drives deterministic CLI gates; the Deacon only runs janitor, liveness, and event-reporting duties.
 
-## Start a Swarm
-
-Run:
+## Start or attach
 
 ```bash
 pan swarm PAN-2203
 ```
 
-If the plan is not swarm eligible, stop and report the printed reason. Do not manually spawn slot agents.
-
-When `pan swarm PAN-2203` succeeds, it ensures the issue workspace exists, then runs the same coordination pass the Deacon patrol runs — reconcile live slot state, merge ready slots, garbage-collect merged slots, and dispatch the next wave — and leaves ongoing coordination to Deacon.
-
-Re-running `pan swarm PAN-2203` is idempotent: the coordination pass reconciles already-dispatched work (live sessions, unmerged slot branches, recorded assignments) and spawns nothing new for it, so a second back-to-back run does not duplicate slots or race the Deacon. If the issue is under an operator hold (`pan swarm freeze` / `pan swarm stop`), the command dispatches nothing and points at `pan swarm resume`.
-
-## Inspect Swarm State
+This validates readiness, ensures the parent workspace, and spawns or messages `agent-pan-2203` as the foreman. It does not dispatch slots. Re-running it attaches to the live foreman instead of creating a duplicate.
 
-Run:
+## Foreman loop
 
-```bash
-pan swarm status PAN-2203
-```
+1. Read `.pan/continue.json`, then run `pan swarm status PAN-2203 --json`.
+2. Run `pan swarm dispatch PAN-2203 --json` for one safe wave.
+3. Run `pan swarm wait PAN-2203 --timeout 300 --json` until state changes.
+4. Run `pan swarm merge PAN-2203 <slot> --json` only for a completion-ready slot.
+5. Run the parent feature-branch integration checks.
+6. Recover failures through `pan swarm recover`; do not invent a direct state edit.
+7. Repeat. If resolved `autoAdvance` is false, get operator acknowledgement before the next dispatch.
 
-`pan swarm status` is read-only — it performs no writes, no git mutation, and no dispatch. It prints one row per reconciled slot (index, item, lifecycle, branch merged/unmerged, agent session alive/dead), the hold state (whether the Deacon is skipping the issue and how to resume), and capacity (tmux-alive slot sessions against the reserved swarm slot limit).
+`status` is read-only. `wait` returns a structured delta instead of requiring transcript polling. The dispatch gate enforces DAG blockers, file-scope isolation, holds, capacity, and duplicate-slot checks. The merge gate verifies work before it writes item completion and clears the slot marker.
 
-## Recover a Failed Slot
-
-Run:
+## Recovery
 
 ```bash
 pan swarm recover PAN-2203 1 --action retry
+pan swarm recover PAN-2203 1 --action drop
+pan swarm recover PAN-2203 1 --action handoff
+pan swarm recover PAN-2203 1 --action reclaim
 ```
 
-Use `--action retry` to unblock and redispatch the failed item, `--action drop` to mark the item done after operator review, or `--action handoff` to keep the failed slot blocked for manual resolution.
-
-## Reset a Swarm (Work-Preserving)
-
-Run:
-
-```bash
-pan swarm reset PAN-2203
-```
-
-Reset stops the swarm (hold first, so the Deacon cannot re-spawn slots mid-cleanup), pushes every unmerged local slot branch to origin BEFORE deleting anything, removes all slot worktrees and local slot branches, clears the recorded slot assignments and any failed-merge block, marks lingering live-status slot agent rows stopped, and retires dead slot agent records through the canonical agent removal door. Slot agents with live tmux sessions are reported and never removed. If pushing an unmerged branch fails, the reset aborts with nothing deleted — pass `--force` only when you accept losing the origin backup. Use `--reason <text>` to record why on the hold.
+- `retry` archives the attempt and returns the item to gated dispatch.
+- `drop` completes an item only after operator review confirms it is unnecessary.
+- `handoff` preserves the block for manual resolution.
+- `reclaim` archives and unblocks the slot, then assigns the item to the foreman for serial implementation.
 
-After a reset the hold remains set: run `pan swarm resume PAN-2203` to re-enable coordination, then `pan swarm PAN-2203` to dispatch a fresh wave. Re-running reset on an already-clean issue succeeds and does nothing.
+Every action increments a durable counter by slot and failure class. A fourth automatic intervention is refused; only an operator may override it with `--operator`.
 
-## Freeze and Resume Coordination
+When a `[swarm-event]` reports a stopped, completed, or stalled slot, run `status --json`, reconcile the evidence, and choose the next gate. A stall message is detection only. The Deacon writes no stall recovery block.
 
-Run:
+## Holds and cleanup
 
 ```bash
-pan swarm freeze PAN-2203 --reason "investigating slot churn"
+pan swarm freeze PAN-2203 --reason "investigating"
+pan swarm stop PAN-2203 --reason "stop running slots"
 pan swarm resume PAN-2203
+pan swarm reset PAN-2203 --reason "clean restart"
 ```
 
-`pan swarm freeze` places a per-issue operator hold: the Deacon skips all swarm coordination for the issue — no slot reconciliation, merging, garbage collection, or new dispatch — until the hold is lifted. Slot agents that are already running keep running. `--reason <text>` records why the hold was placed.
-
-`pan swarm resume` lifts the hold; coordination picks the issue back up on the next Deacon patrol cycle. Both commands are idempotent: freezing an already-frozen issue or resuming an unfrozen issue succeeds with an "already" notice.
+Freeze writes `swarm.hold`; stop writes the hold before stopping slot agents. Resume clears the hold. Reset pushes unmerged slot branches before local deletion and leaves the hold set. Do not continue the foreman loop while held.
 
-## Stop a Swarm
+## Completion
 
-Run:
+A slot finishes with `pan done <issue>`, which writes a durable completion marker. If the signal is missing, the configured completion classifier may nudge or infer completion from stable git evidence. The foreman still uses `pan swarm merge`; it never merges a live or unverified slot directly.
 
-```bash
-pan swarm stop PAN-2203 --reason "runaway slot dispatch"
-```
+## Context and handoff
 
-`pan swarm stop` sets the same per-issue hold as `pan swarm freeze` FIRST (so the Deacon cannot re-spawn slots mid-stop), then stops every live slot agent for the issue via the agent lifecycle (agents-table status is updated, not just tmux-killed). Slot branches and worktrees are preserved — stopping deletes no work. With zero live slots it still succeeds and sets the hold. Run `pan swarm resume` to re-enable coordination afterwards.
+Commit and push one item before advancing it. If context becomes unsafe, write current wave state and next actions to `.pan/continue.json`, then use the normal persistent-session handoff. The replacement foreman starts with `status --json` and resumes the same loop.

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

@@ -315,7 +315,7 @@ These names are reserved by Overdeck. Don't use them for custom skills:
 
 **Pan operations:** `pan-down`, `pan-help`, `pan-install`, `pan-issue`, `pan-plan`, `pan-quickstart`, `pan-setup`, `pan-status`, `pan-up`, `pan-config`, `pan-tracker`, `pan-projects`, `pan-sync`, `pan-docker`, `pan-network`, `pan-approve`, `pan-tell`, `pan-kill`, `pan-doctor`, `pan-diagnose`, `pan-logs`, `pan-rescue`
 
-**Workflow skills:** `pan-task`,  `bug-fix`, `code-review`, `code-review-performance`, `code-review-security`, `dependency-update`, `feature-work`, `incident-response`, `onboard-codebase`, `refactor`, `release`, `session-health`, `skill-creator`, `web-design-guidelines`, `work-complete`
+**Workflow skills:** `pan-task`, `bug-fix`, `claude-skill-creator`, `code-review`, `code-review-performance`, `code-review-security`, `dependency-update`, `feature-work`, `incident-response`, `onboard-codebase`, `refactor`, `release`, `session-health`, `web-design-guidelines`, `work-complete`
 
 ## Related Skills
 

package/server/activity-logger-BejO16Am.js

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

package/server/agent-state-DH_-Jkua.js

@@ -1,3 +0,0 @@
-import { A as setAgentPausedSync, C as recordAgentFailure, D as saveAgentState, E as resetAgentFailureCount, M as wipeAgentStateDirs, N as writeAgentStateJsonSync, O as saveAgentStateSync, P as isRole, S as recordAgentActivitySync, T as recordStartupSessionExit, _ as isAgentTroubled, a as clearAgentPausedSync, b as markAgentStoppedState, c as clearYieldForResumeSync, d as getAgentResumeGateBlockReason, f as getAgentState, g as isAgentPaused, h as init_agent_state, i as clearAgentPaused, j as setAgentYieldedSync, k as setAgentPaused, l as decideResumeGate, m as getAgentStateSync, n as SESSION_EXITED_BEFORE_KICKOFF, o as clearAgentTroubled, p as getAgentStateFilePath, r as __testInternals, s as clearAgentTroubledSync, t as GOVERNOR_SLOT_PAUSE_REASON_PREFIX, u as getAgentDir, v as markAgentRunning, w as recordAgentFailureSync, x as markAgentTroubled, y as markAgentRunningState } from "./agent-state-Bb3UUxQm.js";
-init_agent_state();
-export { GOVERNOR_SLOT_PAUSE_REASON_PREFIX, SESSION_EXITED_BEFORE_KICKOFF, __testInternals, clearAgentPaused, clearAgentPausedSync, clearAgentTroubled, clearAgentTroubledSync, clearYieldForResumeSync, decideResumeGate, getAgentDir, getAgentResumeGateBlockReason, getAgentState, getAgentStateFilePath, getAgentStateSync, isAgentPaused, isAgentTroubled, isRole, markAgentRunning, markAgentRunningState, markAgentStoppedState, markAgentTroubled, recordAgentActivitySync, recordAgentFailure, recordAgentFailureSync, recordStartupSessionExit, resetAgentFailureCount, saveAgentState, saveAgentStateSync, setAgentPaused, setAgentPausedSync, setAgentYieldedSync, wipeAgentStateDirs, writeAgentStateJsonSync };

package/server/agents-megfmQHM.js

@@ -1,3 +0,0 @@
-import { $n as deliverResumeMessageWithTranscriptConfirmation, $r as determineModel, $t as spawnAgent, A as setAgentPausedSync, B as waitForReadySignal, Br as roleAgentDefinitionPath, C as recordAgentFailure, D as saveAgentState, E as resetAgentFailureCount, F as clearReadySignal, Fr as getProviderAuthMode, G as init_agents, Gt as getLatestSessionIdSync, H as getAgentRuntimeStateSync, Hr as waitForPromptReady, Ht as appendActivity, I as isQualifiedAgentId, Ir as getRoleRuntimeBaseCommand, J as replayCrashedStandingAgent, Jt as saveSessionId, K as compactAtTierRunBoundary, Kt as getSessionId, L as normalizeAgentId, M as wipeAgentStateDirs, N as writeAgentStateJsonSync, Nt as resumeAgent, O as saveAgentStateSync, Or as OHMYPI_AGENT_READY_TIMEOUT_SECONDS, P as isRole, Qn as deliverInitialPromptWithRetry, Qr as buildSpawnEnvForModel, R as resolveAgentTargetSync, Rt as messageAgent, Ut as getActivity, V as getAgentRuntimeState, W as saveAgentRuntimeState, Wt as getLatestSessionId, X as shouldReplayCompactAtTierRunBoundary, Xn as deliverAgentMessage, Y as replayStandingAgent, Zn as deliverAgentPermissionDecision, Zr as buildCavemanExports, _ as isAgentTroubled, a as clearAgentPausedSync, an as stopAgentSync, b as markAgentStoppedState, br as transitionIssueToInProgress, c as clearYieldForResumeSync, ci as buildResumeContinueMessage, cn as listAgentStates, di as dismissDevChannelsDialog, dn as warnOnBareNumericIssueIds, dt as detectCrashedAgents, ei as getProviderEnvForModel, en as spawnRun, f as getAgentState, ft as recoverAgent, g as isAgentPaused, gr as buildAgentLaunchConfig, hr as assertWorkspaceStackHealthyForSpawn, i as clearAgentPaused, in as stopAgent, j as setAgentYieldedSync, jr as getAgentRuntimeBaseCommand, jt as buildCompactRecoverySeed, k as setAgentPaused, kr as describeOhmypiSpawnFailure, li as decideChannelsForWorkAgent, ln as listRunningAgents, m as getAgentStateSync, mi as writeChannelsBridgeMcpConfig, n as SESSION_EXITED_BEFORE_KICKOFF, ni as getProviderTmuxFlags, o as clearAgentTroubled, on as dropLegacyAgentStatesMissingRoleAsync, p as getAgentStateFilePath, pt as restartAgent, q as contextWindowForModel, r as __testInternals, rr as setAgentDeliveryMethod, s as clearAgentTroubledSync, si as buildDefaultResumeContinueMessage, t as GOVERNOR_SLOT_PAUSE_REASON_PREFIX, ti as getProviderExportsForModel, u as getAgentDir, ui as decideSupervisorForWorkAgent, un as listRunningAgentsSync, ut as autoRecoverAgents, w as recordAgentFailureSync, x as markAgentTroubled, xr as transitionIssueToInReview, y as markAgentRunningState, yr as retrieveSpawnTimeMemoryContext, z as waitForAgentIdle, zr as injectPiConversationMemory } from "./agent-state-Bb3UUxQm.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-C-H9cM_J.js

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

package/server/build-info-PQlh_Rhb.js

@@ -1,2 +0,0 @@
-import { t as getBuildInfo } from "./build-info-DTX8JwVP.js";
-export { getBuildInfo };

package/server/cli-TaZspPHS.js

@@ -1,2 +0,0 @@
-import { t as createResetMarker } from "./cli-Do8UpLoI.js";
-export { createResetMarker };

package/server/cliproxy-36ncAXlu.js

@@ -1,3 +0,0 @@
-import { v as init_cliproxy, x as isCliproxyRunning } from "./cliproxy-CX6jHRDP.js";
-init_cliproxy();
-export { isCliproxyRunning };

package/server/context-layers-CF6zHws4.js

@@ -1,4 +0,0 @@
-import { S as codexGlobalContextFile, k as piGlobalContextFile } from "./assemble-DyTp2gSB.js";
-import { t as init_context_layers } from "./context-layers-CSPGc2Hb.js";
-init_context_layers();
-export { codexGlobalContextFile, piGlobalContextFile };

package/server/conversations-AnGJ5rtX.js

@@ -1,3 +0,0 @@
-import { N as listConversations, k as init_conversations } from "./conversations-DhwxsOru.js";
-init_conversations();
-export { listConversations };

package/server/deacon-BEH-IY0v.js

@@ -1,5 +0,0 @@
-import "./config-yaml-BwOEANMr.js";
-import { E as handleAgentStoppedForOrphanReviewerSessions, T as handleAgentStoppedEvent, ot as handleReviewCoordinatorDied, st as handleWorkCompleted, w as handleAgentHeartbeatDeadEvent } from "./deacon-TPYssFYt.js";
-import "./deacon-merge-BOGFEV8_.js";
-import "./deacon-swarm-BiLfNm_v.js";
-export { handleAgentHeartbeatDeadEvent, handleAgentStoppedEvent, handleAgentStoppedForOrphanReviewerSessions, handleReviewCoordinatorDied, handleWorkCompleted };

package/server/deacon-swarm-BHX-kR1b.js

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