sisyphi 1.1.18 → 1.1.19

package/README.md

@@ -31,26 +31,26 @@ A tmux-integrated orchestration daemon for [Claude Code](https://docs.anthropic.
 
 ## What this is
 
-Sisyphus is a thin orchestration layer on top of Claude Code. It doesn't replace Claude Code or wrap it in some abstraction — it just runs multiple Claude Code instances in tmux panes and coordinates them. Every agent is a real `claude` process with full access to your codebase, your tools, your CLAUDE.md, your hooks. You keep all the steerability of Claude Code; sisyphus just handles the "run N of them in parallel and loop until done" part.
+Sisyphus runs multiple Claude Code instances in tmux panes and coordinates them. That's it. Every agent is a real `claude` process with full access to your codebase, your CLAUDE.md, your hooks. Sisyphus just handles the "run N of them in parallel and loop until done" part.
 
-If you're familiar with the [Ralph Wiggum loop](https://ghuntley.com/ralph/) — `while true; do claude --prompt task.md; done` — sisyphus is that idea taken further. Instead of one agent in a loop, you get an orchestrator that decomposes work into parallel agents, each looping independently, with structured state that persists across cycles. The orchestrator itself is in a Ralph loop: it plans, spawns agents, gets killed, and respawns fresh with all the results. Same principle, more leverage.
+If you know the [Ralph Wiggum loop](https://ghuntley.com/ralph/) (`while true; do claude --prompt task.md; done`), this is that idea taken further. Instead of one agent in a loop, an orchestrator decomposes work into parallel agents, each looping independently, with structured state that persists across cycles. The orchestrator itself is in a Ralph loop: plan, spawn agents, get killed, respawn fresh with all the results.
 
 ## How it works
 
-Most hard tasks aren't hard because any single piece is difficult — they're hard because there are many pieces and context gets lost between them. A developer working a 12-file refactor holds it all in their head until they don't, then makes a mistake three files from the end because they forgot a constraint from the beginning.
+Most hard tasks aren't hard because any single piece is difficult. They're hard because there are many pieces and context gets lost between them. You're working a 12-file refactor, you hold it all in your head until you don't, and you make a mistake three files from the end because you forgot a constraint from the beginning.
 
-Sisyphus solves this structurally. An **orchestrator** Claude instance reads the full task, breaks it into subtasks, and spawns parallel **agent** Claude instances — each in its own tmux pane with a focused instruction. Agents work simultaneously, submit reports when they're done, and the orchestrator respawns to review progress and plan the next round.
+The fix is structural. An orchestrator Claude instance reads the full task, breaks it into subtasks, and spawns parallel agent instances, each in its own tmux pane with a focused instruction. Agents work simultaneously and submit reports when done. Then the orchestrator respawns to review progress and plan the next round.
 
-The key mechanism: **the orchestrator is stateless**. After it spawns agents and yields, it gets killed. When all agents finish, the daemon respawns a fresh orchestrator with the complete session state — every agent report, every cycle's history, the running plan. This means the orchestrator never degrades. Cycle 1 and cycle 15 get the same quality of reasoning, because each cycle starts with a full context window and a clean slate. The boulder rolls back down; Sisyphus walks back down after it, picks it up, and pushes again — but this time he remembers everything from every previous push.
+The trick: the orchestrator is stateless. After it spawns agents and yields, it gets killed. When all agents finish, the daemon respawns a fresh orchestrator with the complete session state (every agent report, every cycle's history, the running plan). Cycle 1 and cycle 15 get the same quality of reasoning because each one starts with a full context window and a clean slate. The boulder rolls back down; Sisyphus walks back down after it, picks it up, and pushes again. But this time he remembers everything from every previous push.
 
-The daemon handles the lifecycle: spawning panes, detecting when agents finish, persisting state to disk, respawning the orchestrator. You just describe what you want built and watch it work.
+The daemon handles lifecycle: spawning panes, detecting when agents finish, persisting state to disk, respawning the orchestrator.
 
 ## Requirements
 
-- **Node.js** >= 22
-- **tmux** >= 3.2 (you must be inside a tmux session)
-- **Claude Code** CLI (`claude`) installed and authenticated
-- **Neovim** (optional — enables embedded editor in the dashboard)
+- Node.js >= 22
+- tmux >= 3.2 (you must be inside a tmux session)
+- Claude Code CLI (`claude`) installed and authenticated
+- Neovim (optional, enables embedded editor in the dashboard)
 
 ## Install
 
@@ -58,18 +58,18 @@ The daemon handles the lifecycle: spawning panes, detecting when agents finish,
 npm install -g sisyphi
 ```
 
-Then run one-time setup:
+Then run setup once:
 
 ```bash
-sisyphus setup
+sisyphus admin setup
 ```
 
 This installs the background daemon (macOS launchd), tmux keybindings (`M-s` to cycle sessions, `M-S` for dashboard), and checks your environment. The daemon auto-updates when new versions are published.
 
-Verify everything is working:
+Verify:
 
 ```bash
-sisyphus doctor
+sisyphus admin doctor
 ```
 
 ## Quick start
@@ -80,17 +80,17 @@ sisyphus dashboard                        # Open the TUI (auto-opens on start)
 sisyphus status                           # Check session state from the CLI
 ```
 
-Sisyphus is a CLI that Claude Code calls for you. You tell Claude to use it, and Claude handles the rest — calling `sisyphus start`, writing the task description, and kicking off the orchestration loop.
+Sisyphus is a CLI that Claude Code calls for you. Tell Claude to use it and it handles the rest.
 
-In Claude Code, just say something like:
+In Claude Code, say something like:
 
 > Use sisyphus to migrate our REST API from Express to Hono. The API lives in src/api/ with 14 route files...
 
-Claude will call `sisyphus start` with a detailed task description, and tmux panes will start appearing with parallel agents working on your codebase.
+Claude calls `sisyphus start` with a detailed task description, and tmux panes start appearing with parallel agents working on your codebase.
 
-### Setting up a slash command (recommended)
+### Slash command (recommended)
 
-Create a file at `.claude/commands/sisyphus-begin.md` in your project:
+Create `.claude/commands/sisyphus-begin.md` in your project:
 
 ~~~markdown
 Run `sisyphus start` with a detailed task description:
@@ -99,17 +99,17 @@ Run `sisyphus start` with a detailed task description:
 sisyphus start "your task description"
 ```
 
-**Write a thorough task description.** Include what needs to be built or fixed, where relevant code lives, what done looks like, constraints or preferences, and adjacent concerns (don't break X, keep Y working). More context produces better results — the orchestrator figures out how to break it down.
+Write a thorough task description. Include what needs to be built or fixed, where relevant code lives, what done looks like, constraints, and adjacent concerns (don't break X, keep Y working). More context produces better results. The orchestrator figures out how to break it down.
 
-**Example:**
+Example:
 ```bash
 sisyphus start "Rip out our hand-rolled RBAC system and replace it with a proper policy engine. Current implementation is scattered across 20+ middleware files in src/middleware/auth/ that each do their own role checks with hardcoded string comparisons. Replace with a centralized policy engine in src/auth/policies/ using a declarative permission model — define resources, actions, and role mappings in a single config, then write one middleware that evaluates policies. Migrate every route that currently calls requireRole() or checkPermission() to the new system. The admin panel (src/routes/admin/) has the most complex rules including org-scoped permissions and delegated access — those need to work exactly as before. Add integration tests that cover the full matrix: superadmin, org-admin, member, and guest across every protected endpoint. Don't break the public API routes in src/routes/v1/public/. The existing test suite (npm test) must pass when you're done."
 ```
 ~~~
 
-Then in Claude Code, type `/sisyphus-begin` followed by your task and Claude will use sisyphus to orchestrate it.
+Then type `/sisyphus-begin` followed by your task in Claude Code.
 
-Alternatively, add a note to your `CLAUDE.md`:
+Or just add a note to your `CLAUDE.md`:
 
 ```markdown
 ## Sisyphus
@@ -119,65 +119,75 @@ Run `sisyphus start "detailed task description"` inside tmux.
 
 ### Interactive tutorial
 
-If you're new to tmux or sisyphus, run the guided walkthrough:
+New to tmux or sisyphus? Run the guided walkthrough:
 
 ```bash
-sisyphus getting-started
+sisyphus admin getting-started
 ```
 
-Six steps covering tmux basics, neovim essentials, sisyphus concepts, and a live demo session.
+Covers tmux basics, neovim essentials, sisyphus concepts, and a live demo session.
 
 ## Dashboard
 
-The dashboard is a full-screen TUI for monitoring and controlling sessions in real time.
+Full-screen TUI for watching and controlling sessions.
 
 ```bash
 sisyphus dashboard    # or press M-S (Alt-Shift-S)
 ```
 
-It auto-opens when you `sisyphus start` a session.
+Auto-opens when you `sisyphus start`.
 
-**Layout:**
+Left panel is a session tree (sessions, cycles, agents, reports) with status indicators. Right panel shows detail for whatever's selected: roadmap, agent instructions, report content, live pane output. If neovim is available, files open in an embedded editor. Bottom bar has mode and keybinding hints.
 
-- **Left panel** — Session tree with collapsible hierarchy: sessions → cycles → agents → reports. Status indicators show active/completed/paused state at a glance.
-- **Right panel** — Context-sensitive detail view for the selected node: session roadmap, agent instructions, report content, or live pane output. Opens files in an embedded neovim instance when available.
-- **Bottom bar** — Current mode, keybinding hints, and transient notifications.
-
-**Key bindings:**
+Key bindings — navigate mode:
 
 | Key | Action |
 |-----|--------|
 | `j/k` or `↑/↓` | Navigate tree / scroll detail |
 | `h/l` or `←/→` | Collapse/expand nodes |
+| `Tab` | Cycle panel focus |
+| `Enter` | Open selection |
 | `n` | New session (compose mode) |
+| `m` | Message orchestrator |
 | `R` | Resume a paused/completed session |
-| `w` | Jump to session's tmux window |
-| `g` | Edit goal | 
+| `g` | Edit goal |
 | `p` | Open roadmap |
-| `m` | Message orchestrator |
 | `r` | Re-run agent |
 | `x` | Restart agent |
-| `Space` | Leader menu (copy, delete, spawn agent, shell, etc.) |
-| `Tab` | Cycle panel focus |
+| `b` | Jump to session's tmux window |
+| `w` | Go to session window |
+| `o` | Open (file manager) |
+| `e` | Edit context file |
+| `S` | Session info |
+| `F` | Filter / search |
+| `c` | Open companion overlay |
 | `/` | Search sessions |
+| `q` | Quit |
 | `?` | Help overlay |
 
-Compose mode opens a temp file in the embedded neovim for multi-line input (new sessions, messages, resume instructions). Falls back to tmux popups if neovim isn't available.
+Key bindings — leader mode (`Space` + key):
+
+| Key | Action |
+|-----|--------|
+| `Space c …` | Copy submenu: `p` path, `i` id, `c` context, `l` logs, `r` report, `a` agent-id |
+| `Space o …` | Open submenu: `g` goal, `r` roadmap, `s` strategy, `l` logs, `d` dir, `R` latest report, `c` scratch, `e` context file |
+| `Space a …` | Agent submenu: `s` spawn, `m` message, `r` restart, `R` re-run, `j` jump-pane, `o` claude, `t` tail, `k` kill, `e` quick-Explore, `d` quick-Debug |
+| `Space S …` | Session submenu: `n` new, `r` resume, `c` continue, `b` rollback, `k` kill, `d` delete, `e` export, `w` window, `C` clone, `i` history |
+| `Space g …` | Go submenu: `w` window, `p` pane-picker, `s` session-picker, `n` next session, `r` reconnect |
+
+Compose mode opens a temp file in neovim for multi-line input (new sessions, messages, resume instructions). Falls back to tmux popups without neovim.
 
 ## Agent types
 
-Agents can be spawned with role templates that define their model, behavior, and capabilities. The orchestrator discovers available types automatically and uses them to match the right agent to each subtask.
+Agents can be spawned with role templates that set their model, behavior, and capabilities. The orchestrator discovers available types and matches them to subtasks.
 
 ### Built-in types
 
-Sisyphus ships these agent types:
-
 | Type | Description |
 |------|-------------|
 | `sisyphus:worker` | Generic agent (default) |
-| `sisyphus:plan` | Plan lead — breaks work into phases |
-| `sisyphus:design` | Technical design and architecture |
-| `sisyphus:requirements` | EARS-based requirements analysis |
+| `sisyphus:plan` | Plan lead, breaks work into phases |
+| `sisyphus:spec` | Interactive design + requirements spec session |
 | `sisyphus:problem` | Problem exploration and assumption challenging |
 | `sisyphus:review` | Code review |
 | `sisyphus:review-plan` | Plan review with parallel sub-reviewers |
@@ -188,7 +198,7 @@ Sisyphus ships these agent types:
 
 ### Custom agent types
 
-Define your own by creating a markdown file with YAML frontmatter:
+Create a markdown file with YAML frontmatter:
 
 ```markdown
 ---
@@ -206,7 +216,7 @@ You are a security-focused code reviewer. Analyze the code for OWASP top 10
 vulnerabilities, injection risks, auth bypasses, and data exposure...
 ```
 
-**Resolution order** (first match wins):
+Resolution order (first match wins):
 1. `.claude/agents/{name}.md` (project-local)
 2. `~/.claude/agents/{name}.md` (user-global)
 3. Bundled `sisyphus:{name}`
@@ -223,46 +233,48 @@ vulnerabilities, injection risks, auth bypasses, and data exposure...
 | `skills` | Claude Code skills to enable |
 | `permissionMode` | Permission handling mode |
 
-Models prefixed with `gpt-` or `codex-` automatically route to the OpenAI provider (Codex CLI).
+`gpt-` and `codex-` prefixed models automatically route to the OpenAI provider (Codex CLI).
 
 ## Tmux integration
 
 ### Status bar
 
-The daemon renders a live status indicator into your tmux status bar showing all sessions scoped to the current working directory:
+The daemon puts a live status indicator in your tmux status bar, scoped to the current working directory:
 
-- **Yellow dot** — orchestrator processing
-- **Yellow diamond** — agents running
-- **Green dot** — session completed
-- **Red dot** — waiting for input
-- **Gray** — idle / between cycles
+- Yellow dot: orchestrator processing
+- Yellow diamond: agents running
+- Green dot: session completed
+- Red dot: waiting for input
+- Gray: idle / between cycles
 
-Session phases update every 5 seconds. The currently focused session is highlighted.
+Updates every 5 seconds. Focused session is highlighted.
 
 ### Keybindings
 
-Installed by `sisyphus setup` into `~/.sisyphus/tmux.conf`:
+Installed by `sisyphus admin setup` into `~/.sisyphus/tmux.conf`. Requires tmux ≥ 3.2.
 
 | Key | Action |
 |-----|--------|
 | `M-s` | Cycle through sisyphus sessions in current project |
 | `M-S` | Jump to dashboard window |
-| `prefix-x` | Smart kill — kills pane or session depending on context |
+| `Ctrl-S` | Open the which-key popup (anchored bottom-right) |
+| `prefix-x` | Smart kill: pane or session depending on context |
+
+The which-key popup shows direct actions and submenu prefixes. Press the mnemonic key to fire an action; press a submenu prefix (`c`, `o`, `a`, `S`, `g`) to enter that submenu. Submenus follow the same letter conventions as the dashboard `Space` leader, so muscle memory transfers.
+
+Press `Ctrl-S ?` to see the full reference.
 
 ### Native notifications (macOS)
 
-On macOS, sisyphus builds a native notification helper (`SisyphusNotify.app`) during install. Notifications fire on session completion, agent crashes, and other lifecycle events. Clicking a notification switches your terminal to the relevant session.
+Sisyphus builds a native notification helper (`SisyphusNotify.app`) during install. Notifications fire on session completion, agent crashes, and other lifecycle events. Clicking one switches your terminal to the relevant session.
 
 Falls back to `terminal-notifier` or `osascript` if the native app isn't available.
 
 ## Companion
 
-The companion is a persistent character that tracks your work across sessions. It earns XP, levels up (30 levels from *Boulder Intern* to *The Absurd Hero*), unlocks achievements, and shifts mood based on your usage patterns — time of day, session length, crash frequency, efficiency.
+A persistent character that tracks your work across sessions. Earns XP, levels up (30 levels from *Boulder Intern* to *The Absurd Hero*), unlocks achievements, and shifts mood based on usage patterns (time of day, session length, crash frequency, efficiency).
 
-It manifests as:
-- A mood-colored face in the tmux status bar (updates in real time)
-- Commentary on lifecycle events (session start, level-up, late-night coding) generated by Haiku
-- An achievement gallery with 66 unlockable badges across milestone, session, time, and behavioral categories
+Shows up as a mood-colored face in the tmux status bar, generates commentary on lifecycle events via Haiku, and has 66 unlockable badges.
 
 ```bash
 sisyphus companion              # View profile, stats, and achievements
@@ -270,11 +282,11 @@ sisyphus companion --badges     # Full achievement gallery
 sisyphus companion --name Bub   # Rename your companion
 ```
 
-In the dashboard, press `Space` → `c` to open the companion overlay.
+Press `c` in the dashboard (nav mode) to open the companion overlay.
 
 ## Configuration
 
-Project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`):
+Project `.sisyphus/config.json` overrides global `~/.sisyphus/config.json`:
 
 ```json
 {
@@ -301,22 +313,130 @@ Project (`.sisyphus/config.json`) overrides global (`~/.sisyphus/config.json`):
 | `notifications.enabled` | `true` | Desktop notifications on lifecycle events |
 | `notifications.sound` | macOS Hero | Notification sound file path |
 | `requiredPlugins` | `[devcore]` | Claude Code plugins to auto-install for agents |
+| `upload` | — | Worker-proxy upload target — see [Session upload](#session-upload-optional) below |
+
+### Session upload (optional)
+
+On session completion, sisyphus zips the session directory and uploads it to an operator-managed Cloudflare R2 bucket through a Worker proxy — asynchronously, never blocking completion. Use `sisyphus admin upload <id>` to re-run the upload on demand (retry or in-progress sessions). `sisyphus admin export` is unchanged; upload is purely additive.
+
+**Token workflow** — the operator mints a per-user token and shares a URL of the form:
+
+```
+https://<worker-host>/upload?token=sisyphus_pat_...
+```
+
+Run `configure-upload` with that URL to write credentials to `~/.sisyphus/config.json`:
+
+```bash
+# Safest — no argv leak:
+pbpaste | sisyphus admin configure-upload --stdin
+
+# Interactive prompt:
+sisyphus admin configure-upload
+
+# Direct argv (triggers a leak warning — token visible via `ps` and shell history):
+sisyphus admin configure-upload "https://<worker-host>/upload?token=sisyphus_pat_..."
+```
+
+**Config** — `configure-upload` always writes to `~/.sisyphus/config.json`. The `upload` block is only honored from the global config; a project-local `.sisyphus/config.json` with an `upload` block is ignored with a warning (security hardening — prevents project files from redirecting your uploads).
+
+```json
+{
+  "upload": {
+    "url": "https://<worker-host>",
+    "token": "sisyphus_pat_..."
+  }
+}
+```
+
+**Manifest** — the zip includes a `manifest.json` with session metadata. Fields sent on the wire (13 fields):
+
+- `sessionId`, `sisyphusVersion`, `hostname`, `platform`
+- `status` (`completed` / `failed` / `cancelled`), `completedAt`, `durationMs`, `wallClockMs`
+- `model`, `effortTier` (`low` / `medium` / `high` / `xhigh`)
+- `cycleCount`, `agentCount`, `goal`
+
+`userId` is **not sent by the client** — the Worker injects it from the token, so it is opaque to end-users and non-operators.
+
+**Privacy / consent** — presence of `Config.upload` is consent. No upload happens unless the block is configured. The manifest is content-free metadata; the full session zip lands in private R2 owned by the operator.
+
+**State fields** — the session JSON surfaces `uploadStatus` (`pending` / `uploaded` / `failed`), `uploadKey` (e.g. `users/{userId}/{sessionId}.zip`), `uploadError`, and `uploadCompletedAt`.
+
+**Manual retry:**
+
+```bash
+sisyphus admin upload <session-id>     # re-uploads any session (active or completed)
+sisyphus admin upload                  # uploads the active session in this cwd
+```
+
+**Disable** — omit the `upload` config block. Daemon skips silently.
+
+Operator setup (token minting, Worker deployment, R2 provisioning): see [`workers/upload-proxy/README.md`](workers/upload-proxy/README.md).
 
 ## CLI reference
 
-**Session lifecycle:**
-`start`, `kill`, `resume`, `continue`, `rollback`, `complete`
+Session lifecycle: `session kill`, `session resume`, `session continue`, `session rollback`, `session complete`
+
+Agent and orchestrator: `agent spawn`, `agent submit`, `agent report`, `orch yield`, `message`, `agent restart`, `session task`
+
+Monitoring: `status` (`--verbose`), `list` (`--all`), `dashboard`
+
+Setup: `admin setup`, `admin init`, `admin doctor`, `admin getting-started`, `companion`, `admin uninstall`
+
+### history
+
+Browse session history and metrics.
+
+```bash
+sisyphus admin history                        # List recent sessions
+sisyphus admin history <session-id>           # Inspect a specific session
+sisyphus admin history --stats                # Aggregate statistics
+sisyphus admin history --events               # Raw event timeline
+```
 
-**Agent & orchestrator interaction:**
-`spawn`, `submit`, `report`, `yield`, `message`, `restart-agent`, `update-task`
+| Option | Description |
+|--------|-------------|
+| `--cwd <path>` | Filter by project directory |
+| `--status <status>` | Filter by status (`completed`, `killed`) |
+| `--since <duration>` | Filter by recency (e.g. `7d`, `24h`, `2w`) |
+| `--search <query>` | Search task text and messages |
+| `--events` | Show raw event timeline |
+| `--stats` | Show aggregate statistics |
+| `--json` | Output as JSON |
+| `-n, --limit <n>` | Max sessions to show (default: 20) |
 
-**Monitoring:**
-`status` (`--verbose`), `list` (`--all`), `dashboard`
+### clone
 
-**Setup & utilities:**
-`setup`, `init`, `doctor`, `getting-started`, `companion`, `uninstall`
+Clone a session into a new independent session with a different goal.
+
+```bash
+sisyphus session clone "new goal"
+sisyphus session clone "new goal" --strategy    # carry over strategy.md from source
+sisyphus session clone "new goal" --name my-clone --context "extra context"
+```
+
+Useful for branching off a variant approach without starting from scratch.
+
+### reconnect
+
+Reconnect the daemon to an orphaned tmux session (e.g. after a daemon restart). Makes no state changes and does not spawn the orchestrator.
+
+```bash
+sisyphus session reconnect <session-id>
+```
+
+### delete
+
+Delete a session and all its data.
+
+```bash
+sisyphus session delete <session-id>
+sisyphus session delete <session-id> --cwd /path/to/project
+```
+
+---
 
-Run `sisyphus --help` or `sisyphus <command> --help` for full usage.
+`sisyphus --help` or `sisyphus <command> --help` for full usage.
 
 ## License