@overdeck/desktop 0.49.2 → 0.50.1

package/sync-sources/rules/agent-message-delivery.md

@@ -1,19 +1,26 @@
 ---
 scope: universal
 ---
-### Message running agents with `pan tell` — never raw tmux keystroke injection
+### Message Overdeck-managed agents with `pan tell`, not raw tmux keystrokes
 
-To send a message to a running agent, conversation, or the flywheel, use
-`pan tell <agent-or-session> "<message>"`. It routes through the delivery door
-(`deliverAgentMessage`: PTY supervisor → channels → tmux fallback), echoes into
-the transcript, and works regardless of harness. If it reports the target is
-not running, verify with `tmux -L overdeck list-sessions` and check your
-`OVERDECK_HOME` (a polluted shell env is the usual cause — prefix
-`OVERDECK_HOME=~/.overdeck` if in doubt).
+To send a message to a running **Overdeck-managed** agent, conversation, or
+the flywheel, use `pan tell <agent-or-session> "<message>"`. It routes through
+the delivery door (`deliverAgentMessage`: PTY supervisor → channels → tmux
+fallback), echoes into the transcript, and works regardless of harness. If it
+reports the target is not running, verify with `tmux -L overdeck list-sessions`
+and check your `OVERDECK_HOME` (a polluted shell env is the usual cause —
+prefix `OVERDECK_HOME=~/.overdeck` if in doubt).
 
-Do NOT drive another session's terminal directly with `tmux paste-buffer` or
-`tmux send-keys` — keystroke injection is deny-listed in permission settings
-and will be refused. That deny-list is intentional; `pan tell` is the
-sanctioned path. (The `load-buffer`/`paste-buffer` pattern remains correct
-*inside Overdeck source code* implementing the delivery fallback — see the dev
-async-tmux rule.)
+Do not drive another **Overdeck-managed** session with raw `tmux send-keys` /
+`tmux paste-buffer` when `pan tell` can reach it — raw keystrokes bypass the
+transcript echo and the PTY supervisor, so the message leaves no trace and can
+interleave with the harness's own input handling. Scope of the mechanical
+enforcement (PAN-1084): pipeline **work agents** are hook-blocked from
+injecting keystrokes into any session other than their own (this exists to
+stop self-approval of another agent's permission prompts). Conversations and
+human-directed sessions are NOT blocked.
+
+Driving a session that Overdeck does not manage (e.g. the operator's own tmux
+session on the default socket, at their direction) with `send-keys` /
+`paste-buffer` is legitimate — use the async `load-buffer` + `paste-buffer` +
+delayed Enter pattern from the async-tmux rule so the text lands reliably.

package/sync-sources/rules/pan-handoff-focus-limit.md

@@ -7,7 +7,9 @@ The `pan handoff` **focus** (the trailing text after `self`/`<conv>`) is a steer
 statement, not the brief. Since PAN-3737 the hard cap is **10,000 characters**
 (multi-line focus is allowed), so accidental rejection is effectively gone — but a
 short focus still works better: it becomes the conversation title and steers the
-handoff author, while detail belongs in the transcript or a brief file.
+handoff author, while detail belongs in the transcript or a brief file. Pass
+`--title "<title>"` to name the successor explicitly instead (PAN-3768) — useful
+when the focus is a file pointer.
 
 For a full brief, write it to a file in the target cwd and point the focus at it:
 

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

@@ -13,17 +13,6 @@ triggers:
   - run the gauntlet
   - gauntlet
   - AAA quality pass
-  - at the level of
-  - utterly perfect
-  - fan out sub-agents
-allowed-tools:
-  - Bash
-  - Read
-  - Write
-  - Edit
-  - WebFetch
-  - WebSearch
-  - Task
 ---
 
 # Gauntlet Loop
@@ -34,15 +23,22 @@ builder sub-agent per area, judge each area with a **separate** harsh critic
 back, and loop until every area is WOWED. A live progress page tracks every
 area, screenshot, verdict, and defect list.
 
-Origin: Matt Shumer's gauntlet prompt; hardened by run #1 lessons
-(`references/lessons.md` — read it before the first fan-out).
+Origin: Matt Shumer's gauntlet prompt; hardened by the operational lessons of
+runs #1–#2 (folded into the phases below — every rule exists because its
+absence cost an iteration).
 
 ## Phase 0 — Intake: fill the slots, ask about the gaps
 
-Extract these slots from the user's request. For every slot that is missing or
-vague, ask via AskUserQuestion — batch up to 4 questions per call, each
-self-contained (the operator may answer from a dashboard dialog without the
-transcript: state the situation, then ask). Never guess the mission.
+**Run-file shortcut:** a run file (e.g. `gauntlet/RUN-<CODENAME>.md`) may
+pre-fill every slot and carry the operator's approval in writing. When one
+exists and the operator pointed you at it, the run file IS the contract —
+skip intake questions and the Phase-1 approval gate, and follow the run
+file wherever it is more specific than this skill.
+
+Otherwise, extract these slots from the user's request. For every slot that is
+missing or vague, ask via AskUserQuestion — batch up to 4 questions per call,
+each self-contained (the operator may answer from a dashboard dialog without
+the transcript: state the situation, then ask). Never guess the mission.
 
 | Slot | Meaning | If missing |
 |---|---|---|
@@ -85,12 +81,18 @@ REFERENCE is the load-bearing slot. Before accepting it, verify it is:
      automatic failures, scoring dimensions, verdict JSON format.
    - `refs/press/` — the fetched reference evidence (screenshots, transcripts,
      docs). Gitignore third-party media.
-4. **Serve the progress page:** from `gauntlet/`, run
+4. **Build seed/test hooks NOW, not mid-loop.** Seedable state is
+   load-bearing for critique: if reaching a state takes hours of wall-clock
+   (filled stockpiles, advanced time, specific data), the loop can't be
+   photographed. Add the hook during setup. Never restart a shared dev
+   server mid-run — hot-reload kills other agents' verification sessions.
+5. **Serve the progress page:** from `gauntlet/`, run
    `python3 -m http.server <port>` in the background and report the URL.
    (Browsers block `fetch()` from `file://` — the page needs HTTP.)
-5. **Operator approval gate.** Show the filled `gauntlet/PROMPT.md` to the
+6. **Operator approval gate.** Show the filled `gauntlet/PROMPT.md` to the
    operator and get an explicit go before the first fan-out. The gauntlet
    burns real tokens; the mission it burns them on is the operator's call.
+   (Skipped when a run file already carries the approval — see Phase 0.)
 
 ### status.json schema
 
@@ -119,27 +121,58 @@ REFERENCE is the load-bearing slot. Before accepting it, verify it is:
 
 ## Phase 2 — The loop (per area, areas in waves)
 
-1. **Wave plan.** Assign each area a file-ownership map. Areas that share
-   files run in the same wave **serially**; disjoint areas may run in
-   parallel. Concurrent agents in one worktree WILL clobber shared files.
+1. **Wave plan — parallelize to the file-ownership limit.** Assign each area
+   an exact file-ownership map, restated in every agent prompt. Concurrent
+   agents in one worktree WILL clobber shared files, so areas that share
+   files run in the same wave **serially** — but that constraint is
+   per-file, not global: prefer SPLITTING areas until their maps are
+   disjoint, and run everything disjoint **concurrently**. Films and
+   critics for different areas are read-only-ish and parallelize freely.
+   Keep the orchestrator thin; the fan-out does the work.
 2. **Build.** Spawn a builder sub-agent for the area with its ownership map,
    the mission prompt, and the current defect list as its work order.
-   Builders never commit; the orchestrator reviews and commits per area with
-   path-scoped `git add` (in-flight agents keep the tree dirty).
-3. **Capture evidence.** Launch the real thing and drive it — Playwright for
-   UI (1920×1080, realistic data, dev chrome hidden), the CLI at its command,
-   the benchmark at its load. Save the canonical shot to
-   `gauntlet/shots/<area-key>.png` (or transcript/benchmark to notes/).
+   Builders never commit and never judge their own work; the orchestrator
+   reviews and commits per area with path-scoped `git add` — `git add -A`
+   would scoop another in-flight agent's half-done work.
+3. **Capture evidence at presentation quality.** Launch the real thing and
+   drive it — Playwright for UI, the CLI at its command, the benchmark at
+   its load. Screenshots at 1920×1080 with realistic in-fiction data (a
+   visible test username in a shot is a defect); keep dev tooling out of
+   frame. Save the canonical shot to `gauntlet/shots/<area-key>.png` (or
+   transcript/benchmark to notes/). Headless gotchas: black frames in
+   headless Chromium are a renderer-context issue, not scene code — try
+   default launch flags before forcing software rasterization; canvas/WebGL
+   code must survive a React StrictMode double-mount; software-rasterized
+   FPS is CPU numbers — NEVER the real perf verdict. Perf claims need a
+   headed capture.
 4. **Critique.** Spawn the critic — ALWAYS a separate sub-agent from the
-   builder, fresh context, frontier-tier model, evidence + refs/ only. It
-   judges blind per `refs/REFERENCE-BAR.md` and returns the verdict JSON.
-   Save it to `gauntlet/notes/critique-<area>-iter<n>.json`.
+   builder, fresh context, high-tier model (see routing below). The critic
+   is blind to the builder's effort, reasoning, and transcript — but it is
+   NOT tool-poor: it gets the evidence + `refs/`, and it MAY run its own
+   probes and instruments against the running app, the repo, or the
+   benchmark to verify or refute any claim (run-#2 precedent: critic-built
+   instruments caught deploy-saving defects the builder's own numbers
+   missed). It judges blind per `refs/REFERENCE-BAR.md` — literally side by
+   side, which one looks better — and returns the verdict JSON. Verdicts
+   are binary (WOWED / NOT_YET + every failing element with a concrete
+   fix), never a score out of 10. The critic tags each defect with the
+   owning area so cross-area defects merge into the right queue. Save to
+   `gauntlet/notes/critique-<area>-iter<n>.json`.
 5. **Update the dashboard at every transition** — agent launched / landed /
-   awaiting critique / verdict — not just after critiques. A stale dashboard
-   is a bug.
+   filming / awaiting critique / verdict — not just after critiques. A
+   stale dashboard is a bug. The page mutates cards in place; regenerated
+   media needs cache-busting or browsers replay stale files.
 6. **NOT_YET → the defect list becomes the next iteration's work order** for
-   the same area. WOWED → area done. **No fixed round count**: the exit is
+   the same area. WOWED → area done, and prior WOWED quality is a FLOOR no
+   later iteration may regress. **No fixed round count**: the exit is
    winning, or the operator stopping the run.
+7. **Test reconciliation is its own queued item.** Big visual/structural
+   changes break existing test selectors; don't let a builder burn its run
+   fixing them. Wave gates are: build passes, evidence captured, critique
+   filed. Broken-suite repair gets its own area or follow-up.
+8. **Cadence artifacts.** Commit critique JSONs and status.json to the
+   branch — the pass history is reviewable. Gitignore large third-party
+   reference media and regenerable sources (keep shipped assets committed).
 
 ## Phase 3 — Stop conditions
 
@@ -151,31 +184,46 @@ REFERENCE is the load-bearing slot. Before accepting it, verify it is:
 ## The four ways the loop silently fails
 
 1. **Vague bar** — the critic invents a comparison and approves everything.
-2. **Builder judging its own work** — the critic must be a fresh agent with no
-   knowledge of the builder's effort or reasoning.
-3. **Soft critic** — the verdict is binary (WOWED / NOT_YET + concrete fixes),
-   never a score out of 10.
-4. **Fixed round count** — "3 iterations" ships a prototype. Loop until WOWED.
+   The bar must be named, fetchable, comparable.
+2. **Builder judging its own work** — the critic must be a fresh agent with
+   zero knowledge of the builder's effort or reasoning trail.
+3. **Soft critic** — scores out of 10 drift upward and everything passes.
+   Binary verdict + concrete fixes only.
+4. **Fixed round count** — "3 iterations" ships a prototype. The exit is
+   WOWED, or the operator stopping the run.
+
+Restate all four in every agent prompt — they are the whole game.
 
-## Sub-agents and model routing
+## Sub-agents, model routing, and tools
 
 - Fan out with the Agent tool inside this conversation. Gauntlet builders and
   critics are ephemeral conversation sub-agents — the "work agents run through
   `pan`" rule governs managed pipeline issues, not this loop. If the gauntlet
   uncovers work that belongs in the managed pipeline, file an issue and route
   it through `pan start`.
-- Route deliberately: frontier-tier model for design-heavy areas and for ALL
-  critics; workhorse-tier for mechanical implementation, tests, and asset
-  runs. Critics are where model quality pays — never cheap out on the judge.
+- **Model ladder — cheapest that clears the bar, escalate on evidence:**
+  **Sonnet** is the default for as much as possible — builders, films,
+  mechanical implementation, asset processing, test runs. **Opus** when
+  necessary — every critic by default, design-heavy build areas, and
+  problems a Sonnet attempt just fumbled. **Fable** for the really tricky
+  stuff only — areas that keep failing across iterations, deep root-cause
+  mysteries, and the final full-frame composition judgment. Escalate a
+  LANE's tier after failures, not preemptively; de-escalate when the hard
+  part is done. Critics are where model quality pays — never cheap out on
+  the judge.
+- **Distribute and parallelize as much as possible.** Many cheap agents in
+  flight beat one expensive agent in series; the wave plan's file-ownership
+  maps are the only serialization constraint.
+- **No tool restrictions.** Every gauntlet agent may use whatever tools the
+  session has — browsers/Playwright, WebSearch/WebFetch, image tooling,
+  profilers, DB clients. "Blind critic" restricts what the critic is TOLD
+  (nothing from the builder), never what it may DO.
 - Sub-agent fan-out requires a harness with the Agent tool. GPT-routed
   claude-code sessions cannot spawn sub-agents — run the gauntlet from a
   Claude session.
 
 ## References
 
-- `references/lessons.md` — run-#1 operational lessons (file ownership,
-  headless rendering, evidence capture, critic protocol, dashboard contract).
-  Read before the first fan-out; fold applicable lines into agent prompts.
 - `references/domains.md` — per-domain CHECK (evidence capture), sample area
   splits, automatic-failure lists, and storefront-test phrasing.
 - `assets/` — `gauntlet-index.html` (progress page), `PROMPT.template.md`,

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

@@ -1,6 +1,6 @@
 ---
 name: pan-handoff
-description: "pan handoff <conv> — agent-authored conversation handoff that spawns a new conversation. Keep the focus short and steering; the hard cap is 10000 characters (PAN-3737)."
+description: "pan handoff <conv> — agent-authored conversation handoff that spawns a new conversation. Keep the focus short and steering; the hard cap is 10000 characters (PAN-3737). Pass --title to name the successor."
 triggers:
   - pan handoff
   - hand off conversation
@@ -74,6 +74,7 @@ pan handoff source-conv --model claude-opus-4-7 wire the Stripe webhook into che
 pan handoff source-conv --author external --author-model claude-haiku-4-5 cheap clean handoff
 pan handoff source-conv --author source uses-source-agent-and-pollutes-its-context
 pan handoff source-conv --issue PAN-1234 continue the API wiring
+pan handoff source-conv --title "Checkout webhook repair" continue the API wiring
 ```
 
 ## Project and issue association
@@ -94,7 +95,17 @@ Use a normal summary fork when a quick passive summary is enough. Use a plain fo
 
 The positional text after `<conv>` is the focus — a short statement of what the successor should concentrate on. Quotes are optional; everything after the conversation reference (excluding flags) is joined with spaces. Keep it short and task-oriented; the focus is injected into the handoff-authoring prompt, not used as the new conversation's user request.
 
-**Hard ceiling: 10,000 characters** (PAN-3737; multi-line focus is allowed). Don't pack the backstory into the focus even so; the detail belongs in the transcript the author reads or in a brief file in the successor cwd. The focus only steers what the author emphasizes, and its first ~70 characters become the new conversation's title.
+**Hard ceiling: 10,000 characters** (PAN-3737; multi-line focus is allowed). Don't pack the backstory into the focus even so; the detail belongs in the transcript the author reads or in a brief file in the successor cwd. The focus only steers what the author emphasizes.
+
+## Title
+
+Without `--title`, the new conversation is titled `Handoff: <first ~70 chars of focus>` (or `Handoff: <source title>` when there is no focus). Pass `--title "<title>"` to name it explicitly — useful when the focus is a file pointer like "Read .pan/handoff-brief.md FIRST" and would otherwise become the title verbatim:
+
+```bash
+pan handoff self --title "Checkout webhook repair" Read .pan/handoff-brief.md FIRST and follow it exactly.
+```
+
+A blank `--title` falls back to the default naming above.
 
 ## Authoring modes
 

package/server/archive-planning-BW4MKNI7.js

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

package/server/build-info-Bj2vQEMh.js

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

package/server/cli-BRuzUT_I.js

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

package/server/dead-end-trip-6V_CwveT.js

@@ -1,2 +0,0 @@
-import { t as recordDeadEndNeedsYou } from "./dead-end-trip-CnVmjnya.js";
-export { recordDeadEndNeedsYou };

package/server/deploy-queue-CjLErpgw.js

@@ -1,2 +0,0 @@
-import { i as recordDeployIntent } from "./deploy-queue-r96ojDI3.js";
-export { recordDeployIntent };

package/server/dist-fCA6y2bH.js

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

package/server/forge-bvak6vXJ.js

@@ -1,2 +0,0 @@
-import { n as getForgeAdapter } from "./forge-RVTCK_5X.js";
-export { getForgeAdapter };

package/server/hume-TYTb6fDU.js

@@ -1,3 +0,0 @@
-import { i as init_hume, r as deleteHumeConfig } from "./hume-BP9YbxaE.js";
-init_hume();
-export { deleteHumeConfig };

package/server/inspect-agent-JFEaYTRa.js

@@ -1,2 +0,0 @@
-import { n as onInspectComplete } from "./inspect-agent-sV_19NxZ.js";
-export { onInspectComplete };

package/server/merge-ops-DabXHp2i.js

@@ -1,2 +0,0 @@
-import { l as triggerMerge } from "./workspaces-BJdPqx_J.js";
-export { triggerMerge };

package/server/merge-rebase-CXq0qsgR.js

@@ -1,2 +0,0 @@
-import { t as rebaseFeatureBranch } from "./merge-rebase-qq40s91P.js";
-export { rebaseFeatureBranch };