unsnooze 1.15.0 → 1.16.1

package/CHANGELOG.md

@@ -1,5 +1,85 @@
 # Changelog
 
+## 1.16.1 — 2026-08-16
+
+- **`unsnooze status` no longer offers an attach command for headless sessions.**
+  A headless "pane" is a detached pid, but the attach hint fell through to the
+  default `tmux attach -t <session>` — a command that at best does nothing and
+  at worst attaches to an unrelated tmux session that happens to share the name.
+  Headless output lives in `~/.unsnooze/headless/<session>.log`, and status now
+  says nothing rather than something wrong. Found while building the capability
+  table for the new **[Supported terminals](https://unsnooze.dev/docs/#terminals)**
+  docs section, which sets out exactly what each of tmux, Zellij, herdr, cmux
+  and headless does and does not do.
+
+## 1.16.0 — 2026-08-16
+
+- **Claude Design, and native Windows along the way.** ([#13](https://github.com/saaranshM/unsnooze/issues/13))
+  Claude Design shares your 5-hour and weekly limits with everything else, so a
+  long design run stops exactly like any other session — the obstacle was never
+  the stop, it was that Design's canvas is a web app with no pane to watch, and
+  that the reporter was on Windows, where unsnooze watched nothing at all.
+  `unsnooze design setup` wires up the official `claude-design` MCP server so
+  the work runs inside Claude Code, where it is watched like anything else;
+  `unsnooze design` reports whether it is registered and signed in, keeping
+  those two apart because an expired `/design-login` is *not* a usage limit and
+  waiting will never clear it. unsnooze does not automate the web canvas and
+  will not: Anthropic's Consumer Terms bar automated access to claude.ai, and
+  accounts have been terminated over it.
+
+- **Watching without a multiplexer (`headless`).** A pane was only one of three
+  detection channels — the StopFailure hook and the transcript watcher never
+  needed one. What was missing was somewhere to put a revived agent, so there
+  is now a backend where a "pane" is a pid and a revive is a detached process
+  logging to `~/.unsnooze/headless/`. That makes native Windows, bare servers
+  and CI work. It is picked only when no multiplexer is installed, never ahead
+  of one, and it is honestly weaker: no limit-menu answering, no busy
+  detection, no live pane to attach to.
+
+- **Native Windows is supported.** Previously unsnooze printed *"native Windows
+  is not supported; run inside WSL"* and ran your CLI unwatched. Two things
+  were broken beneath that: the StopFailure hook command was POSIX
+  (`test -f …`), which cmd.exe has no `test` for, so the hook failed on every
+  turn; and the shell wrapper only ever reached `~/.zshrc` and `~/.bashrc`,
+  files a PowerShell user does not have — so nothing routed through unsnooze in
+  the first place. Both are fixed, the daemon autostarts from a logon-triggered
+  Scheduled Task, and `unsnooze doctor` stops reporting wrappers as missing
+  when they are installed. WSL remains the richer option.
+
+- **A server throttle is no longer mistaken for your usage limit.** Claude Code
+  says *"API Error: Server is temporarily limiting requests (not your usage
+  limit)"* — and `usage limit` matched the parenthetical. Since the TUI never
+  clears old banners from scrollback, any stale *"resets 3pm"* nearby was enough
+  to turn a throttle that clears in seconds into an hours-long scheduled wait.
+  It is now read as what it is and handled on the transient overload ladder.
+
+- **Non-resetting Claude stops are notified, not scheduled.** The claude adapter
+  gained the `terminalPatterns` every other adapter already had. An expired
+  Claude Design credential and an exhausted credit balance are stops no amount
+  of waiting clears, so unsnooze says so once instead of booking a wake and
+  burning the attempt cap. This matters most for unattended runs: a revived
+  headless session has no interactive terminal, so `/design-login` cannot even
+  be offered there. All patterns are anchored to the CLI's real error phrasings
+  rather than to the bare command name, so an agent explaining `/design-login`
+  is not a stop.
+
+- **Claude's own auto-continue is recognised, not raced.** Claude Code shipped
+  in-process auto-continue on 2026-08-14 (desktop; the CLI carries it behind a
+  gate that currently defaults off). unsnooze was already guarded — every resume
+  path checks whether the session moved on its own, and the 60s reset margin
+  means Claude gets there first — but a session that woke itself was recorded
+  identically to one unsnooze woke, so the deliberate stand-aside was invisible.
+  Records now carry who resumed them and `unsnooze status` says *"resumed itself
+  (unsnooze stood aside)"*. Note the native feature covers only the 5-hour
+  limit: weekly stops, closed apps, headless boxes and every non-Claude CLI
+  remain unsnooze's job.
+
+- **`launchExtraArgs.<agent>`.** The launch-side twin of `resumeExtraArgs`, for
+  flags that must hold for a whole session rather than just a revival —
+  `unsnooze config set launchExtraArgs.claude "--autocompact 400000"` keeps a
+  context-heavy run compacting instead of stalling. Revivals inherit them, so
+  the flag survives the wake.
+
 ## 1.15.0 — 2026-08-15
 
 - **Two new multiplexer backends: herdr and cmux.** unsnooze now watches and

package/README.md

@@ -16,7 +16,9 @@
 **Claude Code · Codex CLI · Grok · Qwen · Kimi · OpenCode · Antigravity** — when they hit the 5-hour or weekly usage limit
 ("You've hit your usage limit"), your session just… stops.<br/>
 unsnooze auto-resumes them: it tracks **every** limit-stopped session across all
-your projects and **wakes each one up in tmux, Zellij, or herdr the moment the usage limit resets.**
+your projects and **wakes each one up the moment the usage limit resets** — in
+tmux, Zellij, herdr or cmux, and on **macOS, Linux and Windows**, with or
+without a terminal multiplexer.
 
 ```sh
 npm install -g unsnooze && unsnooze setup
@@ -162,6 +164,45 @@ explicit setup is:
 headroom install apply --scope provider --providers manual --target claude --target codex
 ```
 
+## Claude Design
+
+Claude Design shares your usual 5-hour and weekly limits with chat, Cowork and
+Claude Code — so a long design run stops the same way everything else does, and
+unsnooze resumes it the same way. What it needs first is a terminal to run in.
+
+Claude Design has three surfaces. The canvas at `claude.ai/design` and the
+Claude Desktop sidebar are web apps. The third is an official MCP server that
+Claude Code drives from your terminal, and that is the one unsnooze supports:
+
+```sh
+unsnooze design setup     # registers the claude-design MCP server
+# then, inside Claude Code:
+/design-login
+unsnooze design           # confirms it is registered and signed in
+```
+
+For long design runs, give the session room to compact rather than stall:
+
+```sh
+unsnooze config set launchExtraArgs.claude "--autocompact 400000"
+```
+
+**unsnooze does not automate the web canvas, and will not.** Anthropic's
+Consumer Terms bar accessing Claude "through automated or non-human means,
+whether through a bot, script, or otherwise", and accounts have been terminated
+for it. Claude Code is the documented exemption — which is exactly what
+unsnooze drives. A browser-driving "Design adapter" is not a missing feature
+here; it is one this project declines.
+
+Two things worth knowing:
+
+- A signed-out `/design-login` is **not** a usage limit. Waiting will never
+  clear it, so unsnooze reports it separately instead of letting it look like a
+  stop that will resolve itself.
+- Design used to have its own weekly allowance. It does not now — everything
+  draws from one shared pool, which is why `unsnooze usage` already accounts
+  for design work without knowing it is design work.
+
 ## GUI surfaces (VS Code extension, desktop apps)
 
 Terminal sessions are watched through the shell wrapper + tmux, Zellij, or herdr. Sessions in
@@ -509,7 +550,7 @@ password hosts on Windows; a plain `ssh <host>` prompt works with native
 
 | key | default | meaning |
 |---|---|---|
-| `multiplexer` | `auto` | Backend to use: `auto`, `tmux`, `zellij`, `herdr`, or `cmux`. `auto` prefers the current multiplexer (tmux/zellij ambient env, then `CMUX_SOCKET_PATH`); with no ambient env it falls back to whichever of tmux/zellij is installed, tmux as the tie-breaker — cmux is only selected via its ambient env or an explicit setting, never by this installed-backend fallback, since it has no attach-from-outside path to wrap into. cmux support covers resume-in-place (detect, capture, send); it has no joinable named-session model, so idle-session reaping (`unsnooze reap`) does not cover cmux panes, and no attach hint is shown for cmux sessions. |
+| `multiplexer` | `auto` | Backend to use: `auto`, `tmux`, `zellij`, `herdr`, `cmux`, or `headless`. `auto` prefers the current multiplexer (tmux/zellij ambient env, then `CMUX_SOCKET_PATH`); with no ambient env it falls back to whichever of tmux/zellij is installed, tmux as the tie-breaker — cmux is only selected via its ambient env or an explicit setting, never by this installed-backend fallback, since it has no attach-from-outside path to wrap into. cmux support covers resume-in-place (detect, capture, send); it has no joinable named-session model, so idle-session reaping (`unsnooze reap`) does not cover cmux panes, and no attach hint is shown for cmux sessions. `headless` is the no-multiplexer mode (see [Watching without a multiplexer](#watching-without-a-multiplexer)) — `auto` falls back to it only when no multiplexer is installed at all, never ahead of one. |
 | `autoResume` | `true` | Master switch. Off = stops are still tracked, but nothing is resumed until you run `unsnooze resume-now` or turn it back on. |
 | `menuAutoAnswer` | `true` | May unsnooze answer Claude's limit menu (send keys in your pane)? Off = watch-only. |
 | `notifications` | `true` | Master switch for all notifications (limit detected / session resumed / gave up). Off = silence every channel. |
@@ -518,6 +559,7 @@ password hosts on Windows; a plain `ssh <host>` prompt works with native
 | `resumeMessage` | *"Continue where you left off…"* | The message sent to wake a session. Override it for a single session with `unsnooze message <id> "…"` — visible in `unsnooze status`. |
 | `resumeMessages.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Per-agent override of `resumeMessage`. Empty = use the global message; clear one with `unsnooze config set resumeMessages.claude ""`. |
 | `resumeExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Extra flags for launches unsnooze performs itself. A revival spawns the agent binary directly, so flags you normally get from a shell alias or wrapper (`--dangerously-skip-permissions`, `--model …`) do not apply unless you put them here. Quoting is respected: `--append-system-prompt "stay in this repo"` is two arguments, not five. `config.json` may also hold an array (`["--append-system-prompt", "stay in this repo"]`), which skips parsing entirely. |
+| `launchExtraArgs.claude` / `.codex` / `.grok` / `.qwen` / `.kimi` / `.opencode` / `.agy` | `""` | Extra flags for the sessions **you** start through the shell wrapper — the launch-side twin of `resumeExtraArgs`. Use it for flags that have to hold for the whole session: `unsnooze config set launchExtraArgs.claude "--autocompact 400000"` keeps a long, context-heavy run compacting instead of stalling. Flags are placed before your own arguments, since `claude "do the thing"` puts a positional prompt there. Revivals inherit them too, so a flag survives the wake. |
 | `agents.claude` / `agents.codex` | `true` | Which CLIs are guarded. |
 | `agents.grok` / `agents.qwen` / `agents.kimi` / `agents.opencode` / `agents.agy` | `false` | Experimental adapters — off by default; enable in `unsnooze setup` or `unsnooze config set agents.qwen on`. |
 | `workspaceGuard` | `inform` | Repo changed while a session slept? `inform` wakes it with a heads-up in the message; `pause` holds it (desktop notification, diff shown on `resume-now`); `off` disables. |
@@ -615,15 +657,82 @@ watcher stops (no pane context) always use native.
 
 ## Requirements
 
-- Node ≥ 20.12 and tmux ≥ 3.2, Zellij, **or** herdr ≥ 0.8.0
-- macOS, Linux, or **Windows via WSL** (see below)
-- zsh or bash (the wrappers are installed into `~/.zshrc` / `~/.bashrc`)
+- Node ≥ 20.12
+- macOS, Linux, or Windows — natively on all three (see
+  [Watching without a multiplexer](#watching-without-a-multiplexer))
+- tmux ≥ 3.2, Zellij, **or** herdr ≥ 0.8.0 for pane-level watching. Optional:
+  without one, unsnooze runs `headless` and still catches and resumes stops.
+- zsh or bash (wrappers go into `~/.zshrc` / `~/.bashrc`), or PowerShell
+  (wrappers go into `$PROFILE.CurrentUserAllHosts`)
+
+### Supported terminals
+
+unsnooze drives four terminal multiplexers, and works without one.
+
+| | [tmux](https://github.com/tmux/tmux) ≥ 3.2 | [Zellij](https://zellij.dev) | [herdr](https://herdr.dev) ≥ 0.8.0 | [cmux](https://cmux.dev) | `headless` |
+|---|:---:|:---:|:---:|:---:|:---:|
+| Detect a limit stop | pane + hook + transcript | pane + hook + transcript | pane + hook + transcript | pane + hook + transcript | hook + transcript |
+| Resume a live session in place | ✅ | ✅ | ✅ | ✅ | — |
+| Answer Claude's limit menu | ✅ | ✅ | ✅ | ✅ | — |
+| Revive a session whose pane died | ✅ | ✅ | ✅¹ | ✅² | ✅³ |
+| Wrap a bare `claude` into a managed session | ✅ | ✅ | ✅ | — | n/a⁴ |
+| `unsnooze reap` idle sessions | ✅ | ✅ | ✅ | — | — |
+| `attach:` hint in `unsnooze status` | ✅ | ✅ | ✅ | — | — |
+| OSC notifications to your terminal | ✅ | — | — | — | — |
+
+¹ Into a fresh session name (`unsnooze-2`), never by restarting the stopped one —
+herdr restores saved agent panes itself, so a revival on top would resume the
+same conversation twice.
+² Into a fresh workspace; cmux has no joinable named-session model.
+³ As a detached process. Its output goes to `~/.unsnooze/headless/<session>.log`,
+since there is no scrollback to read it out of later.
+⁴ Nothing to wrap into — your own terminal is the session.
+
+Pick one explicitly with `unsnooze config set multiplexer tmux|zellij|herdr|cmux|headless`.
+On `auto`, unsnooze uses the multiplexer you are currently inside; failing that,
+the only one installed (tmux breaks ties); failing that, `headless`.
+
+**Install:** `brew install tmux` or `brew install zellij` on macOS,
+`sudo apt install tmux` on Linux/WSL. herdr comes from
+[herdr.dev](https://herdr.dev) — Homebrew still ships 0.7.3, which `available()`
+refuses, so take the release binary.
+
+### Watching without a multiplexer
+
+A terminal pane is only one of unsnooze's three detection channels. The Claude
+Code **StopFailure hook** and the **session transcript watcher** need no pane at
+all — which is what makes native Windows, bare servers and CI work.
+
+When no multiplexer is installed, `multiplexer: auto` resolves to `headless`:
+
+| | with tmux/Zellij/herdr | `headless` |
+|---|---|---|
+| detects limit stops | pane scrape + hook + transcript | hook + transcript |
+| resumes at reset | yes | yes |
+| answers Claude's limit menu | yes | no |
+| waits out a busy pane | yes | no |
+| revived session | live pane you can attach to | detached process, output in `~/.unsnooze/headless/` |
+
+`headless` is never chosen ahead of a real multiplexer — only when none is
+installed, or when you ask for it with
+`unsnooze config set multiplexer headless`. If you want the full behaviour on
+Windows, WSL is still the better home.
+
+### Windows
+
+Native Windows works: PowerShell wrappers, a cmd-safe StopFailure hook, and a
+logon-triggered Scheduled Task for the daemon. Install as usual and run
+`unsnooze doctor` to confirm.
 
-### Windows / WSL
+Two honest caveats. The daemon is started at logon but not restarted if it
+dies — Task Scheduler is not a supervisor the way launchd and systemd are — so
+after upgrading unsnooze, log out and back in (or run `unsnooze daemon`
+yourself). And stored-password fleet hosts still need Git-for-Windows or WSL
+`ssh`; native `ssh.exe` requires an `.exe` askpass helper unsnooze does not yet
+ship.
 
-tmux, Zellij, and herdr are Unix tools, so on Windows unsnooze runs inside
-[WSL](https://learn.microsoft.com/windows/wsl/install) — which is where the
-agent CLIs live on Windows anyway:
+WSL remains the richer option, because that is where the Unix multiplexers live
+— and where the agent CLIs often already are:
 
 ```sh
 # inside your WSL distro (Ubuntu etc.)
@@ -665,9 +774,7 @@ herdr differs from tmux and Zellij in three ways that are visible in use:
 
 Everything works as on Linux, including desktop notifications: inside WSL,
 unsnooze raises **native Windows toasts** through `powershell.exe` (no
-`notify-send` or X server needed). Native Windows (PowerShell/cmd, no WSL) is
-not supported — without tmux or Zellij there is no terminal pane to watch; unsnooze will tell you
-so and run your CLI unwatched instead of breaking it.
+`notify-send` or X server needed).
 
 ## FAQ
 

package/bin/unsnooze.js

@@ -48,7 +48,7 @@ function runAgentFallback(agentId, args) {
 
 // Only human-facing commands may print update notices — never the wrapper
 // passthrough, hooks, or daemons (their output lands in agent panes/logs).
-const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'sessions', 'reap', 'doctor', 'preview', 'usage', 'dashboard', 'hosts', 'fleet', 'prompt', 'help', '-h', '--help', '--help-unsnooze']);
+const USER_FACING = new Set(['status', 'resume-now', 'cancel', 'message', 'config', 'logs', 'report', 'sessions', 'reap', 'doctor', 'preview', 'usage', 'dashboard', 'hosts', 'fleet', 'prompt', 'design', 'help', '-h', '--help', '--help-unsnooze']);
 
 // Every named subcommand; anything else (or no args) is an agent launch.
 const NAMED_COMMANDS = new Set([
@@ -142,6 +142,10 @@ async function main() {
       const { cmdDoctor } = await import('../src/doctor.js');
       return cmdDoctor(rest);
     }
+    case 'design': {
+      const { cmdDesign } = await import('../src/design.js');
+      return cmdDesign(rest);
+    }
     case 'preview': {
       const { cmdPreview } = await import('../src/cli.js');
       return cmdPreview(rest);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "unsnooze",
-  "version": "1.15.0",
-  "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, and Antigravity sessions when 5-hour or weekly usage limits reset—across tmux, Zellij, herdr, VS Code, and desktop apps.",
+  "version": "1.16.1",
+  "description": "Automatically resume Claude Code, Codex CLI, Grok, Qwen Code, Kimi CLI, OpenCode, and Antigravity sessions when 5-hour or weekly usage limits reset—on macOS, Linux and Windows, with or without a terminal multiplexer.",
   "keywords": [
     "claude",
     "claude-code",
@@ -39,7 +39,14 @@
     "ai-agents",
     "agentic-coding",
     "cli",
-    "developer-tools"
+    "developer-tools",
+    "windows",
+    "powershell",
+    "claude-design",
+    "mcp",
+    "headless",
+    "wsl",
+    "cmux"
   ],
   "author": "Saaransh Menon <saaransh.dev2811@gmail.com>",
   "license": "MIT",

package/src/agents/claude.js

@@ -52,8 +52,29 @@ export const patterns = {
     /API Error:?\s*\(?5\d\d/i,
     /overloaded_error/i,
     /API Error:?\s*\(?429/i,
+    // "API Error: Server is temporarily limiting requests (not your usage
+    // limit)" — a server-side throttle. It clears in seconds, so it belongs on
+    // this ladder; patterns.js separately refuses to read its parenthetical as
+    // a usage limit.
+    /temporarily limiting requests/i,
   ],
   transientPatterns: [],   // claude's transient errors are the overload set
+  // Stops that waiting cannot clear: notify once, never enter the ledger
+  // (monitor.js). Scheduling a wake for these would burn the attempt cap on a
+  // condition only a human can fix.
+  //
+  // All verbatim from the shipped 2.1.233 bundle. The Claude Design ones matter
+  // most for headless/unattended runs: a revived session has no interactive
+  // terminal, so an expired design credential produces a stop that can never
+  // self-resolve. Anchored to the error phrasings rather than to the bare
+  // command name, so an agent explaining "/design-login" is not a stop.
+  terminalPatterns: [
+    /rejected your \/design-login credential/i,
+    /could not refresh the design access token/i,
+    /could not save the design credential/i,
+    /\/design-login requires an interactive terminal/i,
+    /credit balance is too low/i,
+  ],
 };
 
 // --- Interactive /rate-limit-options menu (Claude Code only) ---
@@ -94,10 +115,21 @@ export default {
   experimental: false,
   patterns,
   menu: { isPrompt: isRateLimitOptionsPrompt, stepsToWait: menuStepsToWaitOption },
-  // How to reopen a dead session. messageViaPane: the resume prompt is typed
-  // into the TUI once it's ready (claude has no resume-with-prompt argv form).
-  resumeArgs(sessionId) {
-    return { args: sessionId ? ['--resume', sessionId] : ['-c'], messageViaPane: true };
+  // How to reopen a dead session.
+  //
+  // Default (a real pane): the prompt is typed into the TUI once it's ready.
+  // That path is load-bearing on tmux/zellij/herdr and stays exactly as it was.
+  //
+  // canType: false (headless — no pane to type into): the prompt rides in argv.
+  // `claude --resume <id> "<prompt>"` resumes that session id and acts on the
+  // prompt, verified against claude 2.1.233 on 2026-08-16. Without a TTY it
+  // runs to completion non-interactively, which is what an unattended overnight
+  // resume wants anyway.
+  resumeArgs(sessionId, message, { canType = true } = {}) {
+    const args = sessionId ? ['--resume', sessionId] : ['-c'];
+    if (canType) return { args, messageViaPane: true };
+    if (message) args.push(message);
+    return { args, messageViaPane: false };
   },
   // v1: every agent launches the bare TUI and gets the prompt typed once idle.
   launchArgs(message) { return { args: [], messageViaPane: true }; },

package/src/cli.js

@@ -94,6 +94,11 @@ export async function cmdStatus(args = []) {
         mux: s.mux ?? null, pane: s.pane ?? null, muxSession: s.muxSession ?? null,
         attempts: s.attempts ?? 0, lastError: s.lastError ?? null,
         workspaceHold: !!s.workspaceHold,
+        // 'unsnooze' | 'native' | null. Since 2026-08-14 Claude Code can resume
+        // a five_hour stop by itself, so "resumed" alone no longer says who did
+        // it — and standing aside for the provider is a deliberate outcome, not
+        // a missing one.
+        resumedBy: s.resumedBy ?? null,
       })),
       promptQueue: queueList(),
     }, null, 2));
@@ -175,8 +180,13 @@ export async function cmdStatus(args = []) {
     let attach = '';
     const hint = await attachHintFor(s);
     if (hint) attach = ` · attach: ${hint}`;
+    // Claude Code can now resume a five_hour stop itself. When it did, say so:
+    // otherwise standing aside (the correct outcome, and the reason nothing was
+    // double-resumed) is indistinguishable from unsnooze having done the work.
+    const by = s.status === 'resumed' && s.resumedBy === 'native'
+      ? ' · resumed itself (unsnooze stood aside)' : '';
     console.log(`  [${s.status.toUpperCase().padEnd(9)}] ${id}  ${(s.agent || 'claude').padEnd(6)} ${s.limitType?.padEnd(7) ?? 'unknown'} ${s.cwd}`);
-    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}${attach}`);
+    console.log(`              mux ${s.mux ?? '-'} · pane ${pane} · session ${s.muxSession ?? '-'} · via ${origin} · resets ${reset} · attempts ${s.attempts ?? 0}/${MAX_RESUME_ATTEMPTS}${s.lastError ? ` · last error: ${s.lastError}` : ''}${msg}${ctx}${hold}${attach}${by}`);
   }
   printPromptQueueSection(pendingPromptEntries());
   return 0;

package/src/config.js

@@ -77,7 +77,14 @@ export const LEASE_GRACE_MS = envInt('UNSNOOZE_LEASE_GRACE_MS', 60_000);
 // it in either one puts the other in a temporal dead zone at import time.
 // cmux is last: an agent can run tmux inside a cmux surface, so tmux/zellij
 // must win detection when both are signalled (see multiplexer.js: detect()).
-export const MUX_NAMES = ['tmux', 'zellij', 'herdr', 'cmux'];
+// headless is last of all and never auto-detected from the environment: it is
+// the no-multiplexer fallback (native Windows, servers, CI), and a real pane
+// must always beat it.
+export const MUX_NAMES = ['tmux', 'zellij', 'herdr', 'cmux', 'headless'];
+
+// Where a headless revive tees the agent's output. There is no pane to scroll
+// back through, so the log is the only record of what an unattended run did.
+export const HEADLESS_LOG_DIR = join(STATE_DIR, 'headless');
 
 // Pane scanning
 export const PANE_SCAN_LINES = envInt('UNSNOOZE_PANE_SCAN_LINES', 12);

package/src/design.js

@@ -0,0 +1,209 @@
+// Claude Design support (issue #13).
+//
+// Claude Design has three surfaces: the canvas at claude.ai/design, the Claude
+// Desktop sidebar, and — the one that matters here — an official MCP server
+// that Claude Code drives from the terminal:
+//
+//   claude mcp add --scope user --transport http claude-design \
+//     https://api.anthropic.com/v1/design/mcp
+//   /design-login
+//
+// unsnooze deliberately supports only that third surface. The canvas is a web
+// app, and Anthropic's Consumer ToS bars accessing Claude "through automated or
+// non-human means, whether through a bot, script, or otherwise" — driving it
+// with a headless browser risks the user's account, and Claude Code is the
+// documented exemption. There is no version of this file that opens a browser.
+//
+// Design draws from the same 5-hour and weekly pool as chat, Cowork and Claude
+// Code (it had its own weekly allowance once; it does not now), so a design
+// session that stops is an ordinary limit stop and the existing machinery
+// already handles it. What was missing was setup and visibility, which is all
+// this module adds.
+
+import { spawnSync } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+export const DESIGN_MCP_NAME = 'claude-design';
+export const DESIGN_MCP_URL = 'https://api.anthropic.com/v1/design/mcp';
+
+export function designMcpAddArgs() {
+  return ['mcp', 'add', '--scope', 'user', '--transport', 'http',
+    DESIGN_MCP_NAME, DESIGN_MCP_URL];
+}
+
+function defaultRunner(args) {
+  const bin = process.env.UNSNOOZE_CLAUDE_BIN || 'claude';
+  const r = spawnSync(bin, args, { encoding: 'utf-8' });
+  if (r.error) throw r.error;
+  return `${r.stdout || ''}${r.stderr || ''}`;
+}
+
+// One row per configured MCP server, from `claude mcp list`. Real output:
+//
+//   Checking MCP server health…
+//   [mcp-sdk] SEP-2352: stored OAuth credential has no 'issuer' stamp (…)
+//   claude.ai Notion: https://mcp.notion.com/mcp - ! Needs authentication
+//   plugin:context7:context7: https://mcp.context7.com/mcp (HTTP) - ✔ Connected
+//
+// Two shapes make this fussier than a split(': '): names carry both colons
+// (plugin:context7:context7) and spaces (claude.ai Notion), and the SDK prints
+// unrelated diagnostics that look like rows. So the row separator is the LAST
+// ' - ' on the line, and the name is everything before the first COLON-SPACE —
+// which no name contains, because a bare colon inside a name is never followed
+// by a space.
+export function parseMcpList(stdout) {
+  if (typeof stdout !== 'string' || stdout === '') return [];
+  const rows = [];
+  for (const raw of stdout.split('\n')) {
+    const line = raw.trim();
+    if (!line || line.startsWith('[')) continue;   // sdk diagnostics
+    const sep = line.lastIndexOf(' - ');
+    if (sep === -1) continue;
+    const head = line.slice(0, sep);
+    const status = line.slice(sep + 3).trim();
+    const colon = head.indexOf(': ');
+    if (colon === -1) continue;
+    const name = head.slice(0, colon).trim();
+    if (!name) continue;
+    const target = head.slice(colon + 2).trim();
+    const needsAuth = /needs? authentication/i.test(status);
+    rows.push({
+      name,
+      target,
+      status,
+      connected: /connected/i.test(status) && !needsAuth,
+      needsAuth,
+    });
+  }
+  return rows;
+}
+
+// Registration, answered from disk instead of over the wire.
+//
+// `claude mcp list` health-checks every configured server, which takes seconds
+// — fine for an explicit `unsnooze design`, far too slow for `unsnooze doctor`,
+// which people run casually. `--scope user` writes the TOP-LEVEL mcpServers map
+// in ~/.claude.json; the per-project maps under .projects are a different scope
+// and must not be mistaken for it.
+export function designRegisteredOffline({
+  readConfig = () => readFileSync(join(homedir(), '.claude.json'), 'utf-8'),
+} = {}) {
+  try {
+    const parsed = JSON.parse(readConfig());
+    return Boolean(parsed?.mcpServers?.[DESIGN_MCP_NAME]);
+  } catch {
+    return false;   // missing, unreadable or corrupt — treat as not set up
+  }
+}
+
+// Is this machine ready to run Claude Design work from the terminal?
+//
+// Three distinguishable states, because the remedies differ completely:
+//   - claude missing/broken  -> nothing to do with Design at all
+//   - not registered         -> `unsnooze design setup`
+//   - registered, logged out -> `/design-login`, and note that this one is
+//     NOT a usage limit: no amount of waiting clears it.
+export function designStatus({ runner = defaultRunner } = {}) {
+  let out;
+  try {
+    out = runner(['mcp', 'list']);
+  } catch (err) {
+    return {
+      available: false, registered: false, connected: false, needsAuth: false,
+      hint: `could not run \`claude mcp list\` (${err.message}) — is the claude CLI installed?`,
+    };
+  }
+  const row = parseMcpList(out).find(r => r.name === DESIGN_MCP_NAME);
+  if (!row) {
+    return {
+      available: true, registered: false, connected: false, needsAuth: false,
+      hint: 'Claude Design is not wired into Claude Code — run `unsnooze design setup`',
+    };
+  }
+  if (row.needsAuth || !row.connected) {
+    return {
+      available: true, registered: true, connected: false, needsAuth: true,
+      hint: 'Claude Design is registered but signed out — run `/design-login` inside Claude Code. '
+        + 'This is not a usage limit; waiting will not clear it.',
+    };
+  }
+  return {
+    available: true, registered: true, connected: true, needsAuth: false,
+    hint: 'Claude Design is connected — design sessions are watched like any other Claude Code session',
+  };
+}
+
+// Register the MCP server. Editing the user's Claude config is not something to
+// do quietly, so this is only ever reached from an explicit `unsnooze design
+// setup`, and it prints exactly what it ran.
+export function installDesignMcp({ runner = defaultRunner } = {}) {
+  const args = designMcpAddArgs();
+  try {
+    return { ok: true, output: runner(args), args };
+  } catch (err) {
+    return { ok: false, output: err.message, args };
+  }
+}
+
+// --- command ---------------------------------------------------------------
+
+const USAGE = `unsnooze design — Claude Design from the terminal
+
+  unsnooze design            show whether Claude Design is wired up
+  unsnooze design setup      register the claude-design MCP server with Claude Code
+
+Claude Design's canvas (claude.ai/design, Claude Desktop) is a web surface and
+unsnooze does not automate it: Anthropic's Consumer Terms bar automated access
+to claude.ai, and doing it anyway risks your account. The supported route is the
+claude-design MCP server inside Claude Code, which unsnooze watches like any
+other Claude Code session.
+`;
+
+export function cmdDesign(rest = [], { runner = defaultRunner, log = console.log } = {}) {
+  const sub = rest[0];
+
+  if (sub === 'help' || sub === '--help' || sub === '-h') {
+    log(USAGE);
+    return 0;
+  }
+
+  if (sub === 'setup') {
+    const before = designStatus({ runner });
+    if (!before.available) {
+      log(`unsnooze: ${before.hint}`);
+      return 1;
+    }
+    if (before.registered) {
+      log(`unsnooze: ${DESIGN_MCP_NAME} is already registered.`);
+      log(`unsnooze: ${before.hint}`);
+      return 0;
+    }
+    log(`unsnooze: running \`claude ${designMcpAddArgs().join(' ')}\``);
+    const result = installDesignMcp({ runner });
+    if (!result.ok) {
+      log(`unsnooze: registration failed — ${result.output}`);
+      return 1;
+    }
+    log('unsnooze: registered. Now run `/design-login` inside Claude Code to sign in.');
+    log('unsnooze: design work shares your usual 5-hour and weekly limits, so a');
+    log('unsnooze: design session that stops is resumed like any other.');
+    return 0;
+  }
+
+  if (sub && sub !== 'status') {
+    log(`unsnooze: unknown design subcommand "${sub}"`);
+    log(USAGE);
+    return 1;
+  }
+
+  const status = designStatus({ runner });
+  log(`unsnooze: ${status.hint}`);
+  if (status.connected) {
+    log('unsnooze: tip — long design runs burn context fast; set');
+    log('unsnooze:   unsnooze config set launchExtraArgs.claude "--autocompact 400000"');
+    log('unsnooze: so a context-heavy session compacts instead of stalling.');
+  }
+  return status.connected ? 0 : 1;
+}