unsnooze 1.16.0 → 1.16.2

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # Changelog
 
+## 1.16.2 — 2026-08-22
+
+- **A herdr revival now opens a tab in your project's workspace, not a new
+  workspace of its own.** ([#15](https://github.com/saaranshM/unsnooze/issues/15))
+  `newWindow` means "one more terminal for this work" — a window in tmux, a tab
+  in Zellij — and it was mapped to `herdr workspace create`. But a herdr
+  workspace is the *project*: it is per repo, the way a tmux session is. So
+  every reset left another top-level workspace for the same repo, and a week of
+  them was a sidebar full of duplicates. unsnooze now asks herdr which
+  workspace is already open on that directory and adds a tab there, creating a
+  workspace only when there is genuinely none — a session it just started, or a
+  directory herdr has nothing open on. A tab rather than a split, because a
+  revived agent draws a full-screen TUI and halving the pane you are looking at
+  would leave two terminals too narrow to use; neither takes focus away from
+  what you are doing.
+
+## 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))

package/README.md

@@ -665,6 +665,38 @@ watcher stops (no pane context) always use native.
 - 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
@@ -719,7 +751,7 @@ explicitly with `unsnooze config set multiplexer tmux`, `zellij`, or `herdr`.
 
 #### herdr specifics
 
-herdr differs from tmux and Zellij in three ways that are visible in use:
+herdr differs from tmux and Zellij in four ways that are visible in use:
 
 - **unsnooze never restarts a stopped herdr session.** herdr restores saved
   agent panes when a session restarts (`resume_agents_on_restore` is on by
@@ -729,10 +761,17 @@ herdr differs from tmux and Zellij in three ways that are visible in use:
   reusing the name. If you restart a stopped session yourself and herdr brings
   the agent back, unsnooze may still open a fresh pane for it; that case is not
   yet detected.
+- **A revived session opens a tab, not a workspace.** A herdr workspace is the
+  project — per repo, the way a tmux *session* is — while a tab is what tmux
+  calls a window. So a revival opens a new tab in whichever workspace herdr
+  already has open on that directory, and only creates a workspace when there
+  is none. (A tab rather than a split: a revived agent draws a full-screen TUI,
+  and halving the pane you are looking at would leave two terminals too narrow
+  to use. Neither steals focus.)
 - **Multi-line resume messages are carried, not typed.** herdr starts a pane
   command by typing it into the pane's shell, where a newline would submit half
   a command and a tab would be a completion request. Any such argument is passed
-  through the workspace environment instead and referenced by the typed line, so
+  through the new tab's environment instead and referenced by the typed line, so
   a multi-paragraph `resumeMessage` reaches the agent as one argument, byte for
   byte. (A NUL byte is still refused — an environment value cannot hold one.)
 - **A custom `HERDR_SOCKET_PATH` that does not match the session being

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "unsnooze",
-  "version": "1.16.0",
+  "version": "1.16.2",
   "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",

package/src/multiplexers/herdr.js

@@ -2,7 +2,7 @@
 // remains alive with its shell prompt. The resumer must therefore verify
 // agent ownership before injecting, and revival can reuse a surviving pane
 // only when Task 3 wires that path deliberately.
-// Launch env is delivered via workspace create --env. Keep this narrow because
+// Launch env is delivered via tab/workspace create --env. Keep this narrow because
 // pane run types argv into the pane shell, but preserve the two Claude config
 // roots: desktop/isolated Claude sessions cannot be resumed without them.
 
@@ -276,6 +276,66 @@ export function createHerdr({ spawner = defaultSpawner, env = process.env } = {}
       return syncOutput(result);
     };
 
+    const listPaneRows = async session => {
+      const result = parseResult(await inSession(session, 'pane', 'list'));
+      return Array.isArray(result?.panes) ? result.panes : [];
+    };
+
+    const samePath = (a, b) => {
+      if (typeof a !== 'string' || typeof b !== 'string' || !a || !b) return false;
+      const trim = value => (value.length > 1 ? value.replace(/\/+$/, '') : value);
+      return trim(a) === trim(b);
+    };
+
+    // The workspace herdr already has open on this project, if any.
+    //
+    // A herdr workspace is the project, not the window: it is where a repo
+    // lives, the way a tmux SESSION is, and creating one per revival left a
+    // user with N top-level workspaces for one repo (#15). herdr reports no cwd
+    // on a workspace, so the project is read off its panes instead — `pane
+    // list` walks workspaces in order, so the first match is the oldest
+    // workspace on this path, which is the user's own rather than one of ours.
+    const workspaceOnProject = async (session, cwd) => {
+      try {
+        const match = (await listPaneRows(session)).find(pane =>
+          samePath(pane?.cwd, cwd) || samePath(pane?.foreground_cwd, cwd));
+        return match?.workspace_id ? String(match.workspace_id) : null;
+      } catch {
+        return null;
+      }
+    };
+
+    const rootPaneId = (created, what) => {
+      const pane = created?.root_pane?.pane_id;
+      if (!pane) throw new Error(`unsnooze: unexpected herdr ${what} shape: no root_pane`);
+      return String(pane);
+    };
+
+    // One more full-size terminal for `cwd`, in the workspace that project
+    // already occupies. A TAB, not a pane split: `newWindow` means the same
+    // thing on every backend — a tmux window, a zellij tab — and a revived
+    // agent draws a full-screen TUI, so halving the pane the user is looking at
+    // would leave two terminals too narrow to use. Only when herdr has no
+    // workspace on this project (a session we just started has none at all)
+    // does a new workspace get created.
+    const openTerminal = async (session, cwd, envArgs) => {
+      const workspace = await workspaceOnProject(session, cwd);
+      if (workspace) {
+        try {
+          return rootPaneId(parseResult(await inSession(
+            session, 'tab', 'create', '--workspace', workspace,
+            '--cwd', cwd, '--label', 'unsnooze', ...envArgs,
+          )), 'tab');
+        } catch {
+          // The workspace can close between the listing and the create. A
+          // revival into a fresh workspace still revives; failing does not.
+        }
+      }
+      return rootPaneId(parseResult(await inSession(
+        session, 'workspace', 'create', '--cwd', cwd, '--label', 'unsnooze', ...envArgs,
+      )), 'workspace');
+    };
+
     const backend = {
       name: 'herdr',
       owner,
@@ -477,9 +537,8 @@ export function createHerdr({ spawner = defaultSpawner, env = process.env } = {}
 
       async listSessionPanes(sessionName) {
         try {
-          const result = parseResult(await inSession(sessionName, 'pane', 'list'));
-          const panes = Array.isArray(result?.panes) ? result.panes : [];
-          return panes.map(entry => String(entry.pane_id)).filter(Boolean);
+          return (await listPaneRows(sessionName))
+            .map(entry => String(entry.pane_id)).filter(Boolean);
         } catch {
           return [];
         }
@@ -515,14 +574,11 @@ export function createHerdr({ spawner = defaultSpawner, env = process.env } = {}
         }
         // Build the command first: an argument that cannot be typed (a
         // multi-line resume message) travels as environment instead, and that
-        // environment has to be on the workspace before the pane exists.
+        // environment has to be on the tab before its pane exists.
         const { line, env: argEnv } = shellCommand(launchSpec.file, launchSpec.args || []);
-        const workspace = parseResult(await inSession(
-          target, 'workspace', 'create', '--cwd', cwd, '--label', 'unsnooze',
-          ...envFlags({ ...launchSpec?.env, ...argEnv }),
-        ));
-        const pane = workspace?.root_pane?.pane_id;
-        if (!pane) throw new Error('unsnooze: unexpected herdr workspace shape: no root_pane');
+        const pane = await openTerminal(
+          target, cwd, envFlags({ ...launchSpec?.env, ...argEnv }),
+        );
         // One argument, already quoted: `pane run` joins its operands with
         // spaces and types them into the pane's shell, so the quoting has to be
         // ours. It also submits the line itself (PaneSendInput carries

package/src/multiplexers/session-name.js

@@ -52,6 +52,11 @@ export function attachHint(muxName, sessionName) {
   // is no command that attaches to a surface from outside cmux, so omit the
   // hint rather than print a `tmux attach` that would silently do nothing.
   if (muxName === 'cmux') return null;
+  // headless has no session at all — its "pane" is a detached pid. The default
+  // below would print `tmux attach -t <name>`, which at best does nothing and
+  // at worst attaches to an unrelated tmux session that happens to share the
+  // name. Its output lives in ~/.unsnooze/headless/<session>.log instead.
+  if (muxName === 'headless') return null;
   if (muxName === 'herdr') return `herdr session attach ${sessionName}`;
   if (muxName === 'zellij') return `zellij attach ${sessionName}`;
   return `tmux attach -t ${sessionName}`;