From 076f937248b15ea1c8f72835095beaa810765fda Mon Sep 17 00:00:00 2001
From: Lexus2016 <lexus@cdzv.com>
Date: Tue, 25 Aug 2026 01:28:07 +0200
Subject: [PATCH 1/2] fix: a remote SSH chat must never become permanently
 unusable (#67)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Reported: after a remote run exhausts its auto-continues the chat stops
responding, and "Restart Session" does not recover it.

Root cause is a missed termination, not the auto-continue budget.
`runSshSingle()` awaits a promise that resolves ONLY from `onDone`, and
four paths in `ClaudeSSH.send()` ended a run without reaching it:

  1. a socket closing with no 'error' and no channel open (sshd's
     ClientAlive/LoginGraceTime drop, a NAT idle-reap) — there was no
     `conn.on('close')` handler at all
  2. the idle watchdog and the hard cap, which called `conn.end()` and
     nothing else; that settles a run only if a channel exists to be torn
     down with it
  3. an abort arriving before `conn.exec` — the listener lived INSIDE the
     exec callback, so Stop during the handshake was silently ignored
  4. `conn.on('error')` calling `h.onDone` directly, bypassing the
     `finished` guard, so the socket close behind it fired onDone twice

A pending await keeps the session's `activeTasks` entry alive, and nothing
reaps it: the 15s orphan sweeper opens with `if (activeTasks.has(sid))
continue`. The chat then refuses every new message AND `restart_session`
answered "Task is still running" — no way out but a server restart.

Every ending now goes through `finish()`, and the abort listener is
registered at `send()` entry.

Restart Session becomes a recovery action instead of a refusal: it aborts
the live turn, waits up to 5s for that turn's own `finally` to release the
session (which also flushes partial output to SQLite), identity-compares
before reaping so a NEW turn's entry is never removed, and drops
`activeChatSessions` + `_tabBusy` with it. It is also now reachable from
the session bar — the in-message button only renders when the server got a
`session_restart_available` frame out, and the run that needs recovering is
precisely the one that never sends one.

Failure notices name the root cause (`describeStopReason`), so "hit the
turn limit three times" is distinguishable from "the link died three
times", and the session-reset path no longer ends on a bare `break` with
no word that it gave up.

Tests: `ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake
ssh2 Client and asserts onDone fires exactly once on eight endings (the
first scenario hangs on the pre-fix code); `session-restart.test.js` boots
a real server against a `claude` that never exits and pins that a restart
aborts and releases the session (3 assertions fail pre-fix).

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 CLAUDE.md                    |  47 ++++++-
 claude-ssh.js                |  72 ++++++++---
 package.json                 |   2 +-
 public/index.html            |  43 ++++++-
 server.js                    |  74 ++++++++++-
 test/session-restart.test.js | 191 ++++++++++++++++++++++++++++
 test/ssh-termination.test.js | 232 +++++++++++++++++++++++++++++++++++
 7 files changed, 631 insertions(+), 30 deletions(-)
 create mode 100644 test/session-restart.test.js
 create mode 100644 test/ssh-termination.test.js

diff --git a/CLAUDE.md b/CLAUDE.md
index 827ef7fc..a2e410df 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -20,7 +20,7 @@ docker compose up -d
 docker compose logs -f claude-chat
 ```
 
-No linting and no build step configured. `npm test` chains 66 test files under `test/`: 18 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 48 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the cross-project global workspace aggregation, the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the four tmux-dependent suites do not self-skip).
+No linting and no build step configured. `npm test` chains 68 test files under `test/`: 18 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 50 plain-`node` suites in `test/` covering the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, the filesystem path guard (including the SVG sandbox header and the symlink rule on the `@`-mention search endpoints) plus the tunnel-blocks-terminal rule, WS session re-subscription, the SSH remote CLI-session import, the live engine pane / interactive-prompt watchdog, the cross-project global workspace aggregation, the rule that an SSH credential never leaves the server process, the Windows command-quoting oracle, the auth token lifecycle, the multi-agent dependency scheduler (waves, plan sanitising, and the rule that a failure warning must survive dep-context truncation), the SSH stream parser's three guards, the SSH run's termination guarantee (`ssh-termination.test.js` drives `ClaudeSSH.send()` through a fake ssh2 `Client` in `require.cache` and asserts `onDone` fires EXACTLY once on every ending — a missed one hangs the chat forever, a doubled one re-emits stderr) and the recovery contract of "Restart Session" (`session-restart.test.js` boots a real server against a fake `claude` that never exits, then pins that a restart ABORTS that turn and releases the session instead of refusing), the remote non-interactive shell environment (`remote-env.test.js`, which runs the generated prelude through real `bash -lc`: it must parse, print nothing on stdout, and never end on a false test — the caller chains `&& claude …` behind it), the remote CLI-list framing parser, the bot inbox's SQL seam (`bot-inbox.test.js` pins that `from_bot AS "from"` keeps the exact key `planInboxDelivery` reads — rename one without the other and every letter is silently retired as malformed), the one-time config/.env migration onto CCS_CONFIG_PATH and the mid-task clarification delivery contract on the subscription engine (`interrupt-delivery.test.js` — pins that the tmux injection block sits BEFORE the poll loop's completion `break`, that draining does not imply delivery, that a failed paste is re-queued and warns non-terminally, and that the task runner passes the same callbacks the chat path does), the CLAUDE.md / AGENTS.md discovery rules (`agents-md.test.js`, which also pins that AGENTS.md reaches the subprocess as `--append-system-prompt` and never as `--system-prompt`), and the remote file browser's three guard layers (`remote-files.test.js` runs the generated POSIX script through a real `/bin/sh` against a temp tree that contains symlinks OUT of the project; `remote-files-api.test.js` boots a server against a fake remote via `CCS_REMOTE_EXEC_HOOK` and drives `/api/files` the way the SPA does), the editor deep links (`editor-links.test.js` pins the two URI shapes literally — the browser link puts `vscode-remote` in the AUTHORITY and the CLI argument puts it in the SCHEME, and collapsing the two silently breaks one path; `editor-open-api.test.js` boots a real server with `PATH` pointed at an EMPTY directory, which both makes the `opened:'client'` fallback deterministic and guarantees the suite never launches an editor window on a developer's desktop), and the new-chat defaults chain (`chat-defaults.test.js` pins the pure resolver — the built-ins are asserted to be exactly what the SPA hardcoded before #58, and the choice lists to be exactly the toolbar's `data-v` sets and `MODEL_MAP`'s aliases; `chat-defaults-api.test.js` boots a real server in a throwaway `APP_DIR` and pins that a project writes back a SPARSE override object — a five-key snapshot passes every other assertion in that file and still breaks the feature). On the render side, `tables.test.mjs` also pins the ReDoS bound in renderMd step 3.4, `xss.test.mjs` runs 24 adversarial payloads end-to-end, and `forged-tokens.test.mjs` covers the case where user text contains the renderer's own placeholder control bytes, and `pane-font.test.mjs` pins the clamp DIRECTION of `_fitEnginePaneFont` (a wide engine pane may only shrink; a narrow split pane must be allowed to grow). `script-scope.test.mjs` pins which `<script>` block a helper is declared in — declarations hoist only within their own block, so a helper used by `loadSess()` must not live in the terminal block at the bottom of the file. Note the glob: a file under `test/render/` whose name does not end in `.test.mjs` is NEVER run — `_load.selftest.mjs` sat there unexecuted until it was renamed to `loader.test.mjs`. It runs serially and aborts on the first failing file. `.github/workflows/ci.yml` runs it on every push and PR to `main` (tmux installed, so the four tmux-dependent suites do not self-skip).
 
 ## Architecture
 
@@ -460,6 +460,49 @@ Four reports that all reduce to "the UI moved or stopped listening". Pinned by
   key, and the text and the CR go in ONE frame so a prompt that echoes and submits on
   the same tick cannot split them.
 
+### A remote run must always end (issue #67)
+
+`runSshSingle()` awaits a promise that resolves **only** from `onDone`. `ClaudeSSH.send()`
+therefore has one hard rule: every way a run can end goes through `finish()`. Four paths
+did not, and each one hung the caller forever.
+
+The consequence is out of proportion to the cause, which is why this is written down.
+A pending await keeps the session's `activeTasks` entry alive, and **nothing reaps that
+entry** — the 15s orphan sweeper opens with `if (activeTasks.has(sid)) continue`. So one
+missed `onDone` means: the chat refuses every new message, the spinner never stops, and
+"Restart Session" answers *"Task is still running"*. Only a server restart clears it.
+
+- **`conn.on('close')` is the backstop, and it is not redundant.** A cleanly closed socket
+  emits **no** `'error'`: sshd's `ClientAliveCountMax`/`LoginGraceTime` drop, a NAT idle-reap
+  and our own `conn.end()` from the watchdogs all land there only. With a channel open ssh2
+  closes it too and `stream 'close'` calls `finish()` first — on the nextTick queue, so it
+  wins the `setImmediate` and the run still reports its real exit code. With no channel open
+  (still handshaking, or between `'ready'` and `exec`) this is the only thing left.
+- **`conn.end()` is not a way to end a run.** It settles one only when a channel exists for
+  ssh2 to tear down with it. Both watchdogs call `finish()` after it, for that reason.
+- **The abort listener is registered at `send()` entry, not inside the `conn.exec` callback.**
+  There, a Stop pressed during the handshake had no listener at all — it neither stopped the
+  run nor settled the promise. `sshStream` is handed to it once the channel opens.
+- **`conn.on('error')` goes through `finish()` too.** A bare `h.onDone()` left `finished`
+  false, so the socket close behind the error re-emitted the stderr block and fired `onDone`
+  a second time.
+
+**"Restart Session" is a recovery action, so it aborts rather than refuses.** It used to
+open by returning *"Task is still running"* whenever the session had an `activeTasks`
+entry — useless in the one situation the button exists for. It now aborts the turn (the
+same signal Stop sends), waits up to 5s for that turn's own `finally` to release the
+session (that path also flushes partial output to SQLite, which a forced delete skips),
+identity-compares before reaping so a NEW turn's entry is never the one removed, and drops
+`activeChatSessions` + every socket's `_tabBusy` with it — otherwise the next message is
+queued instead of run and the chat still looks dead after a restart that worked.
+
+**The button has to be reachable without a working turn.** The in-message restart button
+only renders when the server got a `session_restart_available` frame out, and the run that
+needs recovering is precisely the one that never sends one. Hence `#sessBarRestartBtn` in
+the session bar, shown whenever the session has a `claude_session_id`. Clearing that id is
+the whole fix: `shouldReplaySessionHistory` is `!!existSess && !localClaudeId`, so the next
+message replays the chat's history into a fresh Claude session rather than losing it.
+
 ### Markdown Rendering in SPA
 - During streaming: `renderStreaming()` handles unclosed code fences
 - On `done` event: re-render with full `renderMd()` for proper final formatting
@@ -469,7 +512,7 @@ Four reports that all reduce to "the UI moved or stopped listening". Pinned by
 
 ## How to Verify Changes
 
-`npm test` runs 66 test files under `test/` (18 `test/render/*.test.mjs` + 48 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
+`npm test` runs 68 test files under `test/` (18 `test/render/*.test.mjs` + 50 `test/*.test.js`), and `.github/workflows/ci.yml` runs the same command on every push and PR to `main`. Nothing covers the live browser/WebSocket path, so also verify that manually:
 
 ```bash
 # 1. Start server
diff --git a/claude-ssh.js b/claude-ssh.js
index b2dd5f32..2938c9c3 100644
--- a/claude-ssh.js
+++ b/claude-ssh.js
@@ -259,18 +259,56 @@ class ClaudeSSH {
         }
       }
 
-      // Report stderr errors (filter known noise)
-      if (code !== 0 && stderrBuf.trim() && h.onError) {
+      // Report stderr errors (filter known noise). Skipped on abort for the same
+      // reason stream 'error' is: the user pressed Stop, the teardown noise is not
+      // a failure worth showing.
+      if (code !== 0 && !aborted && stderrBuf.trim() && h.onError) {
         const realErrors = stderrBuf.trim().split('\n')
           .filter(l => l.trim() && !l.includes('Loaded MCP') && !l.includes('Starting MCP'))
           .join('\n').trim();
         if (realErrors) try { h.onError(realErrors.substring(0, 1000)); } catch {}
       }
 
+      try { abortController?.signal?.removeEventListener('abort', onAbort); } catch {}
       if (h.onDone) h.onDone(detectedSid);
       try { conn.end(); } catch {}
     };
 
+    // ── Termination guarantee (issue #67) ───────────────────────────────────
+    // runSshSingle() awaits a promise that ONLY resolves from onDone. Every path
+    // that ends this run must therefore go through finish(); one that does not
+    // leaves the caller awaiting forever, which keeps the session's activeTasks
+    // entry alive — and that entry is what makes the chat refuse new messages and
+    // makes "Restart Session" answer "Task is still running". There is no reaper
+    // for activeTasks (the 15s sweeper skips any session that has one), so a
+    // single missed onDone locks the chat until the server is restarted.
+    //
+    // Abort is registered HERE, not inside the conn.exec callback where it used to
+    // live: a Stop pressed while the handshake is still in flight had no listener
+    // at all, so it neither tore the connection down nor settled the promise.
+    let sshStream = null;
+    const onAbort = () => {
+      aborted = true;
+      try { sshStream?.close(); } catch {}
+      try { conn.end(); } catch {}
+      // A connection with no channel open has nothing left that would ever emit.
+      finish(1);
+    };
+    if (abortController?.signal) {
+      // Already aborted before we even connected. Deferred, never immediate: the
+      // caller attaches .onDone() synchronously AFTER send() returns, so a finish()
+      // running now would find h.onDone still null and settle nothing.
+      if (abortController.signal.aborted) setImmediate(onAbort);
+      else abortController.signal.addEventListener('abort', onAbort, { once: true });
+    }
+
+    // A cleanly closed socket emits NO 'error': sshd's ClientAlive/LoginGraceTime
+    // drop, a NAT idle-reap and our own conn.end() from the watchdogs all land here
+    // only. With a channel open ssh2 closes it too and stream 'close' calls finish()
+    // first — on the nextTick queue, so it wins this setImmediate and the run still
+    // reports its real exit code. With no channel open, this is the only thing left.
+    conn.on('close', () => { setImmediate(() => finish(1)); });
+
     conn.on('ready', () => {
       (async () => {
         let remoteTempDir = null;
@@ -341,20 +379,17 @@ class ClaudeSSH {
           conn.exec(remoteCmd, { pty: false }, (err, stream) => {
             if (err) {
               try { if (h.onError) h.onError(`SSH exec failed: ${err.message}`); } catch {}
-              if (h.onDone) h.onDone(detectedSid);
-              try { conn.end(); } catch {}
+              finish(1);
               return;
             }
 
             try { stream.stdin.end(); } catch {}
 
-            if (abortController) {
-              abortController.signal.addEventListener('abort', () => {
-                aborted = true;
-                try { stream.close(); } catch {}
-                try { conn.end(); } catch {}
-              }, { once: true });
-            }
+            // Hand the channel to the abort listener registered above. A Stop that
+            // arrived before this point already tore the connection down, so the
+            // channel we just opened has to be closed here rather than left running.
+            sshStream = stream;
+            if (aborted) { try { stream.close(); } catch {} try { conn.end(); } catch {} return; }
 
             stream.stdout.on('data', (chunk) => {
               armIdleTimer(); // remote output = alive — reset the idle clock
@@ -407,15 +442,12 @@ class ClaudeSSH {
           });
         } catch (err) {
           try { if (h.onError) h.onError(`SSH attachment setup failed: ${err.message}`); } catch {}
-          if (h.onDone) h.onDone(detectedSid);
-          try { conn.end(); } catch {}
+          finish(1);
         }
       })();
     });
 
     conn.on('error', (err) => {
-      if (idleTimer) { clearTimeout(idleTimer); idleTimer = null; }
-      if (hardCapTimer) { clearTimeout(hardCapTimer); hardCapTimer = null; }
       const msg = this._hostVerifier?.state?.rejected
         ? hostKeyMismatchError(this._hostVerifier, this.hostname, this.port).message
         : err.code === 'ECONNREFUSED' ? `SSH connection refused — is sshd running on port ${this.port}?`
@@ -424,7 +456,10 @@ class ClaudeSSH {
         : err.level === 'client-authentication' ? `SSH auth failed — check password/key for ${this.username}@${this.hostname}`
         : `SSH error: ${err.message}`;
       try { if (h.onError) h.onError(msg); } catch {}
-      if (h.onDone) h.onDone(detectedSid);
+      // Through finish(), not a bare onDone: the timers are cleared there, and the
+      // `finished` guard is what stops the socket close that follows this error from
+      // re-emitting the stderr block and calling onDone a second time.
+      finish(1);
     });
 
     // Idle watchdog — armed now and reset on every chunk of remote output (the
@@ -437,6 +472,10 @@ class ClaudeSSH {
         const mins = Math.round(IDLE_TIMEOUT_MS / 60000);
         try { if (h.onError) h.onError(`SSH subprocess timed out — no output for ${mins} min (idle). Raise CLAUDE_IDLE_TIMEOUT_MS to allow longer silences.`); } catch {}
         try { conn.end(); } catch {}
+        // conn.end() alone only settles the run when a channel is open to be closed
+        // with it. Fire while still handshaking (or between 'ready' and exec) and
+        // nothing else would ever emit — the exact silent lock-up of issue #67.
+        finish(1);
       }, IDLE_TIMEOUT_MS);
     };
     armIdleTimer();
@@ -448,6 +487,7 @@ class ClaudeSSH {
         const mins = Math.round(HARD_CAP_MS / 60000);
         try { if (h.onError) h.onError(`SSH subprocess timed out — exceeded hard cap of ${mins} min (CLAUDE_HARD_CAP_MS).`); } catch {}
         try { conn.end(); } catch {}
+        finish(1); // same reason as the idle watchdog above
       }, HARD_CAP_MS);
     }
 
diff --git a/package.json b/package.json
index e32aa490..efa97e70 100644
--- a/package.json
+++ b/package.json
@@ -8,7 +8,7 @@
   "scripts": {
     "start": "node server.js",
     "dev": "node --watch server.js",
-    "test": "node --test test/render/*.test.mjs && node test/overload-detector.test.js && node test/usage-limit.test.js && node test/env-load-order.test.js && node test/multi-agent-result.test.js && node test/terminal-session.test.js && node test/terminal-schema.test.js && node test/bots.test.js && node test/bot-inbox.test.js && node test/bots-api.test.js && node test/running-sessions.test.js && node test/session-liveness.test.js && node test/terminal-bridge.integration.test.js && node test/telegram-format.test.js && node test/telegram-behaviour.test.js && node test/ask-user-question.test.js && node test/delegate-terminal.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/i18n-completeness.test.js && node test/config-resolve.test.js && node test/chat-defaults.test.js && node test/chat-defaults-api.test.js && node test/setup-gate.test.js && node test/path-guard.test.js && node test/subscribe-nocatchup.test.js && node test/cli-import-remote.test.js && node test/remote-list-parse.test.js && node test/config-migrate.test.js && node test/engine-pane.test.js && node test/global-workspace.test.js && node test/ssh-secret.test.js && node test/agent-dag.test.js && node test/ssh-parser.test.js && node test/remote-env.test.js && node test/remote-files.test.js && node test/remote-files-api.test.js && node test/auth-token.test.js && node test/cmd-model.test.js && node test/origin-guard.test.js && node test/interrupted-recovery.test.js && node test/queue-persistence.test.js && node test/interrupt-idle-config.test.js && node test/agents-md.test.js && node test/editor-links.test.js && node test/editor-open-api.test.js && node test/interrupt-delivery.test.js && node test/terminal-pane-guard.integration.test.js && node test/composer-terminal.test.js",
+    "test": "node --test test/render/*.test.mjs && node test/overload-detector.test.js && node test/usage-limit.test.js && node test/env-load-order.test.js && node test/multi-agent-result.test.js && node test/terminal-session.test.js && node test/terminal-schema.test.js && node test/bots.test.js && node test/bot-inbox.test.js && node test/bots-api.test.js && node test/running-sessions.test.js && node test/session-liveness.test.js && node test/terminal-bridge.integration.test.js && node test/telegram-format.test.js && node test/telegram-behaviour.test.js && node test/ask-user-question.test.js && node test/delegate-terminal.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/i18n-completeness.test.js && node test/config-resolve.test.js && node test/chat-defaults.test.js && node test/chat-defaults-api.test.js && node test/setup-gate.test.js && node test/path-guard.test.js && node test/subscribe-nocatchup.test.js && node test/cli-import-remote.test.js && node test/remote-list-parse.test.js && node test/config-migrate.test.js && node test/engine-pane.test.js && node test/global-workspace.test.js && node test/ssh-secret.test.js && node test/agent-dag.test.js && node test/ssh-parser.test.js && node test/ssh-termination.test.js && node test/session-restart.test.js && node test/remote-env.test.js && node test/remote-files.test.js && node test/remote-files-api.test.js && node test/auth-token.test.js && node test/cmd-model.test.js && node test/origin-guard.test.js && node test/interrupted-recovery.test.js && node test/queue-persistence.test.js && node test/interrupt-idle-config.test.js && node test/agents-md.test.js && node test/editor-links.test.js && node test/editor-open-api.test.js && node test/interrupt-delivery.test.js && node test/terminal-pane-guard.integration.test.js && node test/composer-terminal.test.js",
     "postinstall": "node scripts/install-hooks.js",
     "release": "node scripts/release.js",
     "electron:dev": "electron .",
diff --git a/public/index.html b/public/index.html
index 429d4afc..0c1824c5 100644
--- a/public/index.html
+++ b/public/index.html
@@ -3448,6 +3448,7 @@ <h3 data-i18n="mob.tabs">Sessions</h3>
     <a id="sessBarOpenBtn" style="display:none;font-size:11px;color:var(--accent2);text-decoration:none;padding:1px 7px;border-radius:4px;border:1px solid rgba(124,106,239,.25);flex-shrink:0;cursor:pointer;" onclick="openInClaude()">⚡ Claude Code</a>
     <button id="sessBarPaneBtn" style="display:none;font-size:11px;color:var(--accent2);background:transparent;padding:1px 7px;border-radius:4px;border:1px solid rgba(124,106,239,.25);flex-shrink:0;cursor:pointer;" onclick="openEnginePane()">▣ <span data-i18n="term.pane.btn">Live pane</span></button>
     <button id="sessBarCatchupBtn" style="display:none;font-size:11px;color:var(--accent2);background:transparent;padding:1px 7px;border-radius:4px;border:1px solid rgba(124,106,239,.25);flex-shrink:0;cursor:pointer;" onclick="catchUpFromTerminal()" data-i18n-title="catchup.title" title="Дочитати у чат повідомлення, набрані напряму в терміналі (claude --resume)" data-i18n="catchup.btn">⤵ Дочитати</button>
+    <button id="sessBarRestartBtn" style="display:none;font-size:11px;color:var(--warn,#f59e0b);background:transparent;padding:1px 7px;border-radius:4px;border:1px solid rgba(245,158,11,.3);flex-shrink:0;cursor:pointer;" onclick="restartSessionFromBar()" data-i18n-title="restart.title" title="">🔄 <span data-i18n="restart.short">Перезапуск</span></button>
     <button id="sessBarCompactBtn" class="sess-compact-btn" style="display:none;" onclick="compactSession()" data-i18n-title="compact.title" title="Compact chat and start new session">📋 <span data-i18n="compact.btn">Compact & New</span></button>
     <button id="sessBarDelegateBtn" class="sess-compact-btn" style="display:none;" onclick="openDelegateModal()" data-i18n-title="dlg.btn.title" title="Делегувати зовнішньому агенту">⇗ <span data-i18n="dlg.btn">Делегувати</span></button>
     <div id="sessBarExportWrap" class="sess-export-wrap" style="display:none;">
@@ -5020,7 +5021,7 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     'mcp.import.formats':'Підтримується формат <strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>) та будь-який JSON вигляду <code style=\'font-size:11px\'>{"mcpServers":{...}}</code>',
     'me.id':'ID сервера',
     'dir.pick_host':'— оберіть хост —',
-    'restart.btn':'🔄 Перезапустити сесію','restart.ing':'Перезапуск...','restart.done':'✅ Сесію перезапущено — можна продовжувати',
+    'restart.btn':'🔄 Перезапустити сесію','restart.ing':'Перезапуск...','restart.done':'✅ Сесію перезапущено — можна продовжувати','restart.short':'Перезапуск','restart.title':'Скинути зависле віддалене підключення та почати нову сесію Claude — історію чату буде відтворено в наступному повідомленні','restart.confirm':'Перезапустити сесію? Поточний хід буде зупинено, а наступне повідомлення почне нову сесію Claude з відтвореною історією цього чату.',
     'retry.title':'Повторів: {n}','intr.title':'Хід було перервано','intr.body':'Цей запит не завершився. Він не буде виконаний сам — вирішіть, чи запускати його ще раз.','intr.body.n':'Цей запит не завершився. Спроб уже було: {n}. Він не буде виконаний сам.','intr.resume':'Відновити','intr.discard':'Відхилити','pend.run':'Хід завершився, але агент позначив роботу як незавершену. Сам він не продовжить.','pend.wait':'Агент чекає на вашу відповідь, але запитання не поставив. Хід уже завершено.','pend.blocked':'Агент повідомив, що заблокований. Хід завершено — без вашої дії нічого не зміниться.','pend.btn.continue':'Продовжити','pend.btn.ask':'Що далі?',
     'plan.exec.btn':'▶️ Виконати план','plan.exec.title':'Перемкнути в режим Auto і виконати цей план',
     'tmux.required':'Потрібен tmux на сервері (macOS/Linux/Docker/WSL). Тут недоступно.',
@@ -5408,7 +5409,7 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     'mcp.import.formats':'Supported: the <strong>Claude Desktop</strong> format (<code>claude_desktop_config.json</code>) and any JSON shaped like <code style=\'font-size:11px\'>{"mcpServers":{...}}</code>',
     'me.id':'Server ID',
     'dir.pick_host':'— pick a host —',
-    'restart.btn':'🔄 Restart Session','restart.ing':'Restarting...','restart.done':'✅ Session restarted — you can continue chatting',
+    'restart.btn':'🔄 Restart Session','restart.ing':'Restarting...','restart.done':'✅ Session restarted — you can continue chatting','restart.short':'Restart','restart.title':'Clear a stuck or broken run and start a fresh Claude session — this chat’s history is replayed on your next message','restart.confirm':'Restart this session? The current turn is stopped, and your next message starts a fresh Claude session with this chat’s history replayed.',
     'retry.title':'Retried {n} time(s)','intr.title':'This turn was interrupted','intr.body':'The request never finished. It will not run on its own — decide whether to run it again.','intr.body.n':'The request never finished. It has already been attempted {n} time(s). It will not run on its own.','intr.resume':'Resume','intr.discard':'Discard','pend.run':'The turn ended, but the agent marked its own work unfinished. It will not resume on its own.','pend.wait':'The agent is waiting on you but never asked a question. The turn is already over.','pend.blocked':'The agent reported it is blocked. The turn has ended — nothing moves without you.','pend.btn.continue':'Continue','pend.btn.ask':'What next?',
     'plan.exec.btn':'▶️ Execute Plan','plan.exec.title':'Switch to Auto mode and execute this plan',
     'tmux.required':'tmux is required on the server (macOS/Linux/Docker/WSL). Unavailable here.',
@@ -5796,7 +5797,7 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     'mcp.import.formats':'Поддерживается формат <strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>) и любой JSON вида <code style=\'font-size:11px\'>{"mcpServers":{...}}</code>',
     'me.id':'ID сервера',
     'dir.pick_host':'— выберите хост —',
-    'restart.btn':'🔄 Перезапустить сессию','restart.ing':'Перезапуск...','restart.done':'✅ Сессия перезапущена — можно продолжать',
+    'restart.btn':'🔄 Перезапустить сессию','restart.ing':'Перезапуск...','restart.done':'✅ Сессия перезапущена — можно продолжать','restart.short':'Перезапуск','restart.title':'Сбросить зависшее удалённое подключение и начать новую сессию Claude — история чата будет воспроизведена в следующем сообщении','restart.confirm':'Перезапустить сессию? Текущий ход будет остановлен, а следующее сообщение начнёт новую сессию Claude с воспроизведённой историей этого чата.',
     'retry.title':'Повторов: {n}','intr.title':'Ход был прерван','intr.body':'Этот запрос не завершился. Сам он не выполнится — решите, запускать ли его снова.','intr.body.n':'Этот запрос не завершился. Попыток уже было: {n}. Сам он не выполнится.','intr.resume':'Возобновить','intr.discard':'Отклонить','pend.run':'Ход завершён, но агент отметил работу как незаконченную. Сам он не продолжит.','pend.wait':'Агент ждёт вашего ответа, но вопрос не задал. Ход уже завершён.','pend.blocked':'Агент сообщил, что заблокирован. Ход завершён — без вашего действия ничего не изменится.','pend.btn.continue':'Продолжить','pend.btn.ask':'Что дальше?',
     'plan.exec.btn':'▶️ Выполнить план','plan.exec.title':'Переключиться в режим Auto и выполнить этот план',
     'tmux.required':'Нужен tmux на сервере (macOS/Linux/Docker/WSL). Здесь недоступно.',
@@ -6085,7 +6086,7 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     'mcp.import.formats':'Formats pris en charge : celui de <strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>) et tout JSON de la forme <code style=\'font-size:11px\'>{"mcpServers":{...}}</code>',
     "me.id":"ID du serveur",
     "dir.pick_host":"— choisir un hôte —",
-    "restart.btn":"🔄 Redémarrer la session","restart.ing":"Redémarrage…","restart.done":"✅ Session redémarrée — vous pouvez continuer à discuter",
+    "restart.btn":"🔄 Redémarrer la session","restart.ing":"Redémarrage…","restart.done":"✅ Session redémarrée — vous pouvez continuer à discuter","restart.short":"Redémarrer","restart.title":"Réinitialiser une exécution bloquée ou interrompue et démarrer une nouvelle session Claude — l'historique de cette discussion est rejoué à votre prochain message","restart.confirm":"Redémarrer cette session ? Le tour en cours sera arrêté, et votre prochain message démarrera une nouvelle session Claude avec l'historique de cette discussion rejoué.",
     "retry.title":"Tentatives : {n}","intr.title":"Ce tour a été interrompu","intr.body":"La requête ne s'est jamais terminée. Elle ne repartira pas toute seule — à vous de décider s'il faut la relancer.","intr.body.n":"La requête ne s'est jamais terminée. Elle a déjà été tentée {n} fois. Elle ne repartira pas toute seule.","intr.resume":"Reprendre","intr.discard":"Ignorer","pend.run":"Le tour est terminé, mais l'agent a marqué son propre travail comme inachevé. Il ne repartira pas tout seul.","pend.wait":"L'agent vous attend mais n'a posé aucune question. Le tour est déjà terminé.","pend.blocked":"L'agent signale qu'il est bloqué. Le tour est terminé — rien n'avancera sans vous.","pend.btn.continue":"Continuer","pend.btn.ask":"Et ensuite ?",
     "plan.exec.btn":"▶️ Exécuter le plan","plan.exec.title":"Passer en mode Auto et exécuter ce plan",
     "tmux.required":"tmux est requis sur le serveur (macOS/Linux/Docker/WSL). Indisponible ici.",
@@ -6346,7 +6347,7 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     'mcp.import.formats':'נתמך הפורמט של <strong>Claude Desktop</strong> (<code>claude_desktop_config.json</code>) וכל JSON במבנה <code style=\'font-size:11px\'>{"mcpServers":{...}}</code>',
     "me.id":"מזהה שרת",
     "dir.pick_host":"— בחרו מארח —",
-    "restart.btn":"🔄 הפעלה מחדש של הסשן","restart.ing":"מפעיל מחדש...","restart.done":"✅ הסשן הופעל מחדש — אפשר להמשיך לשוחח",
+    "restart.btn":"🔄 הפעלה מחדש של הסשן","restart.ing":"מפעיל מחדש...","restart.done":"✅ הסשן הופעל מחדש — אפשר להמשיך לשוחח","restart.short":"הפעלה מחדש","restart.title":"איפוס הרצה תקועה או שבורה והתחלת סשן Claude חדש — היסטוריית השיחה תשוחזר בהודעה הבאה","restart.confirm":"להפעיל מחדש את הסשן? התור הנוכחי ייעצר, וההודעה הבאה תתחיל סשן Claude חדש עם היסטוריית השיחה המשוחזרת.",
     "retry.title":"ניסיונות חוזרים: {n}","intr.title":"התור הופסק","intr.body":"הבקשה מעולם לא הסתיימה. היא לא תרוץ מעצמה — החליטו אם להריץ אותה שוב.","intr.body.n":"הבקשה מעולם לא הסתיימה. כבר בוצעו {n} ניסיונות. היא לא תרוץ מעצמה.","intr.resume":"לחדש","intr.discard":"לבטל","pend.run":"התור הסתיים, אבל ה-agent סימן שהעבודה שלו לא הושלמה. הוא לא ימשיך מעצמו.","pend.wait":"ה-agent ממתין לתשובה שלכם אבל לא שאל שאלה. התור כבר הסתיים.","pend.blocked":"ה-agent דיווח שהוא חסום. התור הסתיים — בלי פעולה שלכם שום דבר לא יזוז.","pend.btn.continue":"להמשיך","pend.btn.ask":"מה הלאה?",
     "plan.exec.btn":"▶️ להריץ את התוכנית","plan.exec.title":"מעבר למצב Auto והרצת התוכנית הזו",
     "tmux.required":"נדרש tmux בשרת (macOS/Linux/Docker/WSL). לא זמין כאן.",
@@ -7791,12 +7792,20 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
       }
       { const openBtn = $i('sessBarOpenBtn'); if (openBtn) openBtn.style.display = 'none'; }
       { const catchupBtn = $i('sessBarCatchupBtn'); if (catchupBtn) catchupBtn.style.display = 'none'; }
+      { const rsBtn = $i('sessBarRestartBtn'); if (rsBtn) { delete rsBtn.dataset.busy; rsBtn.style.opacity = ''; rsBtn.style.display = 'none'; } }
       toast(t('restart.done'), false, 3000);
       // Reset streaming state for fresh start
       streaming.el = null; streaming.txt = '';
       streaming.toolCounts = {}; streaming.toolLog = [];
       isGen = false;
       setSendStop(false);
+      // Clear the per-tab busy state too, the same way `done` does. Restart is reached
+      // precisely when a turn ended without one (issue #67) — leaving `generating` set
+      // kept the tab's busy dot on and the toolbar in Stop after a restart that had
+      // in fact succeeded.
+      if (found?.tab) { found.tab.generating = false; found.tab.done = true; }
+      if (tabId === activeTabId || tabId === generatingTabId) generatingTabId = null;
+      renderTabs();
       if (tabId === activeTabId) updateSessBar();
       break;
 
@@ -10457,6 +10466,12 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
     }
     if (openBtn) { openBtn.style.display = hasClaudeId ? '' : 'none'; }
     { const catchupBtn = $i('sessBarCatchupBtn'); if (catchupBtn) catchupBtn.style.display = hasClaudeId ? '' : 'none'; }
+    // Recovery has to be reachable without a working turn (issue #67). The in-message
+    // button only appears when the server managed to send a `session_restart_available`
+    // frame — a run that never ends never sends one, which is precisely the case the
+    // user needs to escape. Tied to hasClaudeId: with no Claude session there is
+    // nothing to reset.
+    { const restartBtn = $i('sessBarRestartBtn'); if (restartBtn) restartBtn.style.display = hasClaudeId ? '' : 'none'; }
     updateSessBarSkills();
     const tab = findTabAcrossProjects(sessionId)?.tab || openTabs.find(t => t.id === sessionId);
     // Show compact button when session has messages and is not actively generating
@@ -10522,6 +10537,24 @@ <h2 id="dlgModalTitle" data-i18n="dlg.title">Делегувати агенту</
   } catch {}
 }
 
+// Manual recovery, always reachable from the session bar — unlike the in-message
+// button, which only exists if the server got a `session_restart_available` frame out
+// (issue #67: the run that needs recovering is the one that never sends one). The
+// server aborts whatever the session still has running, then clears claude_session_id;
+// the next message replays this chat's history into a fresh Claude session.
+function restartSessionFromBar() {
+  if (!currentSessionId) return;
+  if (!confirm(t('restart.confirm'))) return;
+  const btn = $i('sessBarRestartBtn');
+  if (btn) { if (btn.dataset.busy) return; btn.dataset.busy = '1'; btn.style.opacity = '.5'; }
+  // The timer is a floor, not the primary clear: session_restart_done releases it as
+  // soon as the server answers, and this only stops a server that never does from
+  // latching the button off for good.
+  setTimeout(() => { if (btn) { delete btn.dataset.busy; btn.style.opacity = ''; } }, 8000);
+  try { ws.send(JSON.stringify({ type: 'restart_session', sessionId: currentSessionId })); }
+  catch { if (btn) { delete btn.dataset.busy; btn.style.opacity = ''; } }
+}
+
 // Pull conversation typed directly in an opened `claude --resume` terminal into the
 // web chat (complements openInClaude). Server reads new <cid>.jsonl bytes, persists
 // them, returns a count; we re-render the session history on success.
diff --git a/server.js b/server.js
index dd8412b6..7e3c6d9d 100644
--- a/server.js
+++ b/server.js
@@ -3428,6 +3428,21 @@ function _sleepAbortable(ms, signal) {
   });
 }
 
+// Turn the CLI's stop `subtype` (plus whatever landed on stderr) into a sentence a
+// user can act on. Kept next to isResettableClaudeSessionError because both read the
+// same two fields, and both are the only places that interpret them.
+function describeStopReason(subtype, errorText = '') {
+  const err = (errorText || '').trim();
+  if (subtype === 'error_max_turns') return 'it kept hitting the per-run turn limit (raise "Max turns" for this chat)';
+  if (subtype === 'error_during_execution') return 'the agent errored mid-run';
+  if (/SSH (error|connection|stream|exec)|timed out|ECONNRESET|Host not found|auth failed/i.test(err)) {
+    return `the SSH connection to the remote host kept failing (${err.split('\n')[0].substring(0, 160)})`;
+  }
+  if (err) return `last error: ${err.split('\n')[0].substring(0, 160)}`;
+  if (subtype) return `the run kept ending as "${subtype}"`;
+  return 'the run kept ending before the agent finished';
+}
+
 function isResettableClaudeSessionError(errorText = '') {
   return /Invalid signature in thinking block|invalid session|session .* not found|could not find .*session|no conversation found|resume .*failed|failed to resume|conversation .* not found/i.test(errorText || '');
 }
@@ -3680,7 +3695,16 @@ async function runCliSingle(p) {
         : prompt;
       currentContentBlocks = replayContent || (Array.isArray(userContent) ? userContent : null);
       continueCount++;
-      if (continueCount >= MAX_AUTO_CONTINUES) break;
+      if (continueCount >= MAX_AUTO_CONTINUES) {
+        // Was a bare `break`: the turn ended on the "starting a fresh session" line
+        // above with no word that it had in fact given up, and without the restart
+        // affordance every other exhausted path offers.
+        const notice = `\n\n⚠️ **Could not re-establish the Claude session** after ${MAX_AUTO_CONTINUES} attempts.\n\n`;
+        fullText += notice;
+        { const _cb = (chatBuffers.get(sessionId) || '') + notice; chatBuffers.set(sessionId, _cb.length > MAX_CHAT_BUFFER ? _cb.slice(-MAX_CHAT_BUFFER) : _cb); }
+        try { ws.send(JSON.stringify({ type:'text', text: notice, session_restart_available: true, sessionId, ...(tabId ? { tabId } : {}) })); } catch {}
+        break;
+      }
       continue;
     }
 
@@ -3698,7 +3722,9 @@ async function runCliSingle(p) {
 
     // 🔄 Auto-continue budget exhausted
     if (continueCount >= MAX_AUTO_CONTINUES) {
-      const notice = `\n\n⚠️ **Agent did not complete** after ${MAX_AUTO_CONTINUES} auto-continues. Continue manually if needed.\n\n`;
+      // Same reason as the SSH loop's copy below: "gave up" without "why" is not
+      // actionable — raising Max turns and fixing a crashing tool are different fixes.
+      const notice = `\n\n⚠️ **Agent did not complete** after ${MAX_AUTO_CONTINUES} auto-continues — ${describeStopReason(resultData?.subtype, errorText)}. Send another message to continue, or use **Restart Session** to start fresh with this chat's history replayed.\n\n`;
       fullText += notice;
       { const _cb = (chatBuffers.get(sessionId) || '') + notice; chatBuffers.set(sessionId, _cb.length > MAX_CHAT_BUFFER ? _cb.slice(-MAX_CHAT_BUFFER) : _cb); }
       try { ws.send(JSON.stringify({ type:'text', text: notice, session_restart_available: true, sessionId, ...(tabId ? { tabId } : {}) })); } catch {}
@@ -3945,7 +3971,16 @@ async function runSshSingle(p) {
         : prompt;
       currentContentBlocks = replayContent || (Array.isArray(userContent) ? userContent : null);
       continueCount++;
-      if (continueCount >= MAX_AUTO_CONTINUES) break;
+      if (continueCount >= MAX_AUTO_CONTINUES) {
+        // Was a bare `break`: the turn ended on the "starting a fresh session" line
+        // above with no word that it had in fact given up, and without the restart
+        // affordance every other exhausted path offers.
+        const notice = `\n\n⚠️ **Could not re-establish the Claude session** after ${MAX_AUTO_CONTINUES} attempts.\n\n`;
+        fullText += notice;
+        { const _cb = (chatBuffers.get(sessionId) || '') + notice; chatBuffers.set(sessionId, _cb.length > MAX_CHAT_BUFFER ? _cb.slice(-MAX_CHAT_BUFFER) : _cb); }
+        try { ws.send(JSON.stringify({ type:'text', text: notice, session_restart_available: true, sessionId, ...(tabId ? { tabId } : {}) })); } catch {}
+        break;
+      }
       continue;
     }
     if (resultData?.subtype === 'error_max_budget_usd') {
@@ -3957,7 +3992,11 @@ async function runSshSingle(p) {
     }
     if (abortController?.signal?.aborted) break;
     if (continueCount >= MAX_AUTO_CONTINUES) {
-      const notice = `\n\n⚠️ **Agent did not complete** after ${MAX_AUTO_CONTINUES} auto-continues.\n\n`;
+      // Name why it kept stopping. Without this the message said only that it gave
+      // up, so "hit the turn limit three times" (raise maxTurns) was indistinguishable
+      // from "the remote link died three times" (fix the connection) — issue #67.
+      const _why = describeStopReason(resultData?.subtype, errorText);
+      const notice = `\n\n⚠️ **Agent did not complete** after ${MAX_AUTO_CONTINUES} auto-continues — ${_why}. The chat is still usable: send another message to continue, or use **Restart Session** to start a fresh remote session with this chat's history replayed.\n\n`;
       fullText += notice;
       { const _cb = (chatBuffers.get(sessionId) || '') + notice; chatBuffers.set(sessionId, _cb.length > MAX_CHAT_BUFFER ? _cb.slice(-MAX_CHAT_BUFFER) : _cb); }
       try { ws.send(JSON.stringify({ type:'text', text: notice, session_restart_available: true, sessionId, ...(tabId ? { tabId } : {}) })); } catch {}
@@ -11324,11 +11363,34 @@ wss.on('connection', (ws) => {
         return;
       }
 
+      // Recovery IS this button's job, so a live turn is aborted rather than used as
+      // a reason to refuse (issue #67). The turn this is clicked on is by definition
+      // one the user has given up on: a remote run whose SSH link died leaves an
+      // activeTasks entry that nothing reaps — the 15s orphan sweeper explicitly skips
+      // any session that has one — so refusing here left the chat locked until the
+      // server was restarted, which is exactly what "Restart Session does not recover"
+      // meant. Aborting is safe for a healthy turn too: it is the same signal Stop sends.
       const task = activeTasks.get(sessionId);
       if (task && !task.abortController?.signal?.aborted) {
-        ws.send(JSON.stringify({ type: 'error', error: 'Task is still running', tabId: sessionId }));
-        return;
+        log.warn('session restart aborting live turn', { sessionId, source: task.source, ageMs: Date.now() - (task.startedAt || 0) });
+        try { task.abortController.abort(); } catch {}
       }
+      if (task) {
+        // Give the aborted turn its own finally block a moment to release the session —
+        // that path also flushes partial output to SQLite, which a forced delete skips.
+        for (let i = 0; i < 50 && activeTasks.get(sessionId) === task; i++) await _sleepAbortable(100);
+        // Backstop: a run wedged below the abort signal never returns. Identity-compare
+        // so a NEW turn's entry is never the one removed.
+        if (activeTasks.get(sessionId) === task) {
+          activeTasks.delete(sessionId);
+          log.warn('session restart reaped an unresponsive turn', { sessionId });
+        }
+      }
+      // The cross-connection lock is released with it — otherwise the next message is
+      // queued instead of run and the chat still looks dead after a "successful" restart.
+      activeChatSessions.delete(sessionId);
+      for (const client of wss.clients) { try { if (client._tabBusy) delete client._tabBusy[sessionId]; } catch {} }
+      markActivityDirty();
 
       // Get user messages from the session to transfer context
       const userMessages = stmts.getMsgsLite.all(sessionId).filter(m => m.role === 'user');
diff --git a/test/session-restart.test.js b/test/session-restart.test.js
new file mode 100644
index 00000000..469c75dc
--- /dev/null
+++ b/test/session-restart.test.js
@@ -0,0 +1,191 @@
+// "Restart Session" as a RECOVERY action — issue #67.
+//
+// The handler used to open with:
+//     if (task && !task.abortController?.signal?.aborted)
+//       → { type:'error', error:'Task is still running' }
+// which made the button useless in the one situation it exists for. A remote turn whose
+// SSH link dies leaves an activeTasks entry that nothing reaps — the 15s orphan sweeper
+// skips any session that has one (`if (activeTasks.has(sid)) continue`) — so the chat
+// refuses new messages AND refuses to be restarted, with no way out but a server
+// restart. That is the reported "Restart Session does not recover the conversation".
+//
+// It now aborts the live turn, waits for the turn's own finally to release the session,
+// reaps the entry if it never does, and drops the cross-connection lock with it.
+//
+// This drives the LOCAL cli engine — the handler is engine-agnostic, and a fake `claude`
+// that just sleeps reproduces "a turn that will not end on its own" without needing a
+// remote host. Boots a real server against a THROWAWAY data directory.
+//
+// Run: node test/session-restart.test.js   (TEST_PORT=<n> to move off the default port)
+'use strict';
+const assert = require('assert');
+const fs = require('fs');
+const net = require('net');
+const os = require('os');
+const path = require('path');
+const { spawn } = require('child_process');
+const WebSocket = require('ws');
+
+let pass = 0, fail = 0;
+function check(label, actual, expected) {
+  try { assert.deepStrictEqual(actual, expected); pass++; console.log(`  ok   ${label}`); }
+  catch { fail++; console.error(`  FAIL ${label} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); }
+}
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+
+const PORT = Number(process.env.TEST_PORT || 3994);
+const BASE = `http://127.0.0.1:${PORT}`;
+const APP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-restart-'));
+const HOME_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-restart-home-'));
+process.on('exit', () => { for (const d of [APP_DIR, HOME_DIR]) { try { fs.rmSync(d, { recursive: true, force: true }); } catch {} } });
+fs.mkdirSync(path.join(APP_DIR, 'data'), { recursive: true });
+
+// A fake `claude` that announces a session id, emits one line, then sleeps far longer
+// than this test runs — i.e. a turn that will not end on its own. `--model haiku`
+// (title generation) exits at once so it is never the turn under test.
+const binDir = path.join(HOME_DIR, '.local', 'bin');
+fs.mkdirSync(binDir, { recursive: true });
+fs.writeFileSync(path.join(binDir, 'claude'), `#!/bin/sh
+case " $* " in *" haiku "*) exit 0 ;; esac
+printf '%s\\n' '{"type":"system","subtype":"init","session_id":"ccs-restart-fake"}'
+printf '%s\\n' '{"type":"assistant","message":{"content":[{"type":"text","text":"WEDGED"}]}}'
+sleep 600
+`);
+fs.chmodSync(path.join(binDir, 'claude'), 0o755);
+
+let srv = null, srvExited = false, srvLog = '';
+function startServer() {
+  srv = spawn(process.execPath, [path.join(__dirname, '..', 'server.js')], {
+    env: { ...process.env, PORT: String(PORT), CCS_DESKTOP: '1', APP_DIR, WORKDIR: APP_DIR, HOME: HOME_DIR },
+    stdio: ['ignore', 'pipe', 'pipe'],
+  });
+  srv.on('exit', () => { srvExited = true; });
+  srv.stdout.on('data', d => { srvLog += d; });
+  srv.stderr.on('data', d => { srvLog += d; });
+}
+let cleanedUp = false;
+function cleanup() {
+  if (cleanedUp) return;
+  cleanedUp = true;
+  if (srv && !srvExited) { try { srv.kill('SIGTERM'); } catch {} }
+  for (const d of [APP_DIR, HOME_DIR]) { try { fs.rmSync(d, { recursive: true, force: true }); } catch {} }
+}
+process.on('exit', cleanup);
+for (const sig of ['SIGINT', 'SIGTERM', 'SIGHUP']) process.on(sig, () => { cleanup(); process.exit(1); });
+function die(msg) { console.error(msg); if (srvLog) console.error(srvLog.slice(-2000)); cleanup(); process.exit(1); }
+
+async function api(method, url, body) {
+  const res = await fetch(BASE + url, {
+    method,
+    headers: body ? { 'content-type': 'application/json' } : undefined,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+  return { status: res.status, json: await res.json().catch(() => null) };
+}
+// /api/activity derives `live` from activeTasks itself — the exact map that stayed
+// populated forever and locked the chat.
+async function activityLive() {
+  const r = await api('GET', '/api/activity');
+  return (r.json && Array.isArray(r.json.live)) ? r.json.live.map(x => x.session_id) : [];
+}
+function openWs() {
+  const ws = new WebSocket(`ws://127.0.0.1:${PORT}`);
+  ws._frames = [];
+  ws.on('message', raw => { try { ws._frames.push(JSON.parse(raw)); } catch {} });
+  return new Promise((resolve, reject) => {
+    ws.on('open', () => resolve(ws));
+    ws.on('error', reject);
+    setTimeout(() => reject(new Error('ws open timeout')), 10000);
+  });
+}
+async function waitFor(predicate, timeoutMs = 15000) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) { if (await predicate()) return true; await sleep(150); }
+  return false;
+}
+function probePort(port) {
+  return new Promise(resolve => {
+    const probe = net.createServer();
+    probe.once('error', err => resolve(err.code || String(err)));
+    probe.once('listening', () => probe.close(() => resolve(null)));
+    probe.listen(port, '127.0.0.1');
+  });
+}
+
+(async () => {
+  // Without this the test's own server dies with EADDRINUSE and every assertion runs
+  // against a foreign instance — creating sessions in a database this test did not make.
+  const busy = await probePort(PORT);
+  if (busy) die(`Port ${PORT} is already in use (${busy}). Re-run with TEST_PORT=<free port>.`);
+
+  startServer();
+  if (!await waitFor(async () => { try { return (await fetch(BASE + '/api/health')).ok; } catch { return false; } }, 20000)) {
+    die('server never came up');
+  }
+
+  const created = await api('POST', '/api/sessions', { title: 'restart-test', workdir: APP_DIR });
+  const sid = created.json && created.json.id;
+  if (!sid) die('could not create a session');
+
+  const ws = await openWs().catch(e => die(e.message));
+  ws.send(JSON.stringify({ type: 'chat', text: 'hi', tabId: sid, sessionId: sid, model: 'sonnet', mode: 'auto' }));
+
+  if (!await waitFor(async () => ws._frames.some(d => d.type === 'text' && String(d.text).includes('WEDGED')), 25000)) {
+    die('the fake claude never streamed — the scenario would be vacuous');
+  }
+  if (!await waitFor(async () => (await activityLive()).includes(sid), 10000)) die('turn never became live');
+
+  console.log('\n— a live turn is the reason to restart, not a reason to refuse —');
+  check('the session is live in activeTasks before the restart', (await activityLive()).includes(sid), true);
+
+  const before = ws._frames.length;
+  ws.send(JSON.stringify({ type: 'restart_session', sessionId: sid }));
+
+  const answered = await waitFor(async () =>
+    ws._frames.slice(before).some(d => d.type === 'session_restart_done'), 20000);
+  const newFrames = ws._frames.slice(before);
+  check('the server answered session_restart_done', answered, true);
+  check('it did NOT refuse with "Task is still running"',
+    newFrames.some(d => d.type === 'error' && /Task is still running/.test(d.error || '')), false);
+
+  console.log('\n— and the session is actually released —');
+  const released = await waitFor(async () => !(await activityLive()).includes(sid), 20000);
+  check('the session left activeTasks, so the chat accepts messages again', released, true);
+
+  const sess = await api('GET', `/api/sessions/${sid}`);
+  check('claude_session_id was cleared, so the next turn starts fresh',
+    sess.json && (sess.json.claude_session_id || null), null);
+
+  // The whole point of clearing it: shouldReplaySessionHistory in processChat is
+  // `!!existSess && !localClaudeId`, so the next message replays this chat's history
+  // into the fresh session rather than starting from nothing.
+  const src = fs.readFileSync(path.join(__dirname, '..', 'server.js'), 'utf8');
+  check('a session with no claude id replays its history on the next turn',
+    /shouldReplaySessionHistory\s*=\s*!!existSess\s*&&\s*!localClaudeId/.test(src), true);
+
+  console.log('\n— a session that never had a turn still restarts —');
+  {
+    const idle = await api('POST', '/api/sessions', { title: 'idle-restart', workdir: APP_DIR });
+    const isid = idle.json && idle.json.id;
+    const n = ws._frames.length;
+    ws.send(JSON.stringify({ type: 'restart_session', sessionId: isid }));
+    const ok = await waitFor(async () => ws._frames.slice(n).some(d => d.type === 'session_restart_done'), 10000);
+    check('session_restart_done on an idle session', ok, true);
+  }
+
+  console.log('\n— an unknown session is still refused —');
+  {
+    const n = ws._frames.length;
+    ws.send(JSON.stringify({ type: 'restart_session', sessionId: 'no-such-session-id' }));
+    const refused = await waitFor(async () =>
+      ws._frames.slice(n).some(d => d.type === 'error' && /Session not found/.test(d.error || '')), 10000);
+    check('unknown session id answers "Session not found"', refused, true);
+  }
+
+  try { ws.close(); } catch {}
+  console.log(`\n${pass} passed, ${fail} failed`);
+  if (srv && !srvExited) { try { srv.kill('SIGTERM'); } catch {} }
+  for (let i = 0; i < 60 && !srvExited; i++) await sleep(50);
+  cleanup();
+  process.exit(fail ? 1 : 0);
+})().catch(e => { console.error('FAIL', e && e.message); cleanup(); process.exit(1); });
diff --git a/test/ssh-termination.test.js b/test/ssh-termination.test.js
new file mode 100644
index 00000000..28924112
--- /dev/null
+++ b/test/ssh-termination.test.js
@@ -0,0 +1,232 @@
+// The termination guarantee of ClaudeSSH.send() — issue #67.
+//
+// runSshSingle() in server.js awaits a promise that resolves ONLY from onDone. A path
+// that ends the run without reaching onDone therefore leaves that await pending forever,
+// and the session's activeTasks entry with it. Nothing reaps that entry — the 15s orphan
+// sweeper explicitly skips any session that has one — so the chat refuses every new
+// message and "Restart Session" answers "Task is still running". That is the reported
+// symptom: after a remote run breaks, the conversation is permanently stuck.
+//
+// Four paths used to end a run without calling onDone:
+//   1. a socket that closes with no 'error' and no channel open (sshd's ClientAlive /
+//      LoginGraceTime drop, a NAT idle-reap) — there was no conn.on('close') at all
+//   2. the idle watchdog and the hard cap, which called conn.end() and nothing else
+//   3. an abort arriving before conn.exec ran — the listener was registered INSIDE the
+//      exec callback, so a Stop during the handshake was silently ignored
+//   4. conn.on('error') called h.onDone directly, bypassing the `finished` guard, so the
+//      socket close behind it re-emitted the stderr block and fired onDone a second time
+//
+// Every scenario below asserts onDone fired EXACTLY once. Driven through a fake ssh2
+// Client injected into require.cache, so no network and no remote host is involved.
+//
+// Run: node test/ssh-termination.test.js
+'use strict';
+
+// Read at module load in claude-ssh.js — must be set before the require below. Low
+// enough that the watchdog scenario finishes fast, high enough that the other
+// scenarios (all sub-millisecond) never trip it.
+process.env.CLAUDE_IDLE_TIMEOUT_MS = '400';
+
+const assert = require('assert');
+const path = require('path');
+const fs = require('fs');
+const { EventEmitter } = require('events');
+
+let pass = 0, fail = 0;
+function check(label, actual, expected) {
+  try { assert.deepStrictEqual(actual, expected); pass++; console.log(`  ok   ${label}`); }
+  catch { fail++; console.error(`  FAIL ${label} — expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); }
+}
+
+// ── fake ssh2 ────────────────────────────────────────────────────────────────
+// Only the surface claude-ssh.js touches: connect/end/exec, plus an exec stream with
+// stdout/stderr/stdin. The test drives every event by hand.
+class FakeStream extends EventEmitter {
+  constructor() {
+    super();
+    this.stdout = new EventEmitter();
+    this.stderr = new EventEmitter();
+    this.stdin = { end() {} };
+    this.closed = false;
+  }
+  close() { this.closed = true; }
+}
+
+let lastClient = null;
+class FakeClient extends EventEmitter {
+  constructor() {
+    super();
+    this.ended = false;
+    this.execCalls = 0;
+    this.stream = null;
+    this._execMode = 'ok'; // 'ok' | 'error' | 'never'
+    lastClient = this;
+  }
+  connect() { /* the test emits 'ready'/'error'/'close' itself */ }
+  end() {
+    if (this.ended) return;
+    this.ended = true;
+    // A real ssh2 Client emits 'close' after end(); that is exactly the event the fix
+    // hangs the last-resort finish() on, so the fake has to produce it too.
+    setImmediate(() => this.emit('close'));
+  }
+  exec(cmd, opts, cb) {
+    this.execCalls++;
+    if (this._execMode === 'never') return;
+    if (this._execMode === 'error') return void setImmediate(() => cb(new Error('open failed')));
+    this.stream = new FakeStream();
+    setImmediate(() => cb(null, this.stream));
+  }
+}
+
+const ssh2Path = require.resolve('ssh2');
+require.cache[ssh2Path] = { id: ssh2Path, filename: ssh2Path, loaded: true, exports: { Client: FakeClient } };
+
+const ClaudeSSH = require('../claude-ssh');
+
+// ── harness ──────────────────────────────────────────────────────────────────
+// Returns { doneCount, sid, errors } once onDone has fired, or rejects on timeout —
+// a timeout here IS the bug this file exists to catch.
+function runScenario(drive, { timeoutMs = 3000 } = {}) {
+  return new Promise((resolve, reject) => {
+    const ssh = new ClaudeSSH({ host: 'user@example.invalid', workdir: '/srv/app', password: 'x' });
+    const state = { doneCount: 0, sid: undefined, errors: [], text: '' };
+    const ac = new AbortController();
+    const timer = setTimeout(
+      () => reject(new Error('onDone never fired — the run would hang the chat forever')),
+      timeoutMs);
+
+    ssh.send({ prompt: 'hi', sessionId: null, model: 'sonnet', maxTurns: 5, abortController: ac })
+      .onText(t => { state.text += t; })
+      // onDone only carries a sid the OUTER scope detected (the stderr regex fallbacks);
+      // a session_id read out of a stream-json frame arrives here instead, which is why
+      // server.js wires both. Mirror that so this measures the real contract.
+      .onSessionId(sid => { state.sid = sid; })
+      .onError(e => { state.errors.push(e); })
+      .onDone(sid => {
+        state.doneCount++;
+        if (sid) state.sid = sid;
+        // Do NOT resolve immediately: a second onDone is the regression in path 4, and
+        // it can only be observed by waiting past the first.
+        setTimeout(() => { clearTimeout(timer); resolve(state); }, 120);
+      });
+
+    // The chained handlers above are attached synchronously; the connection is only
+    // driven after that, the same order the real event loop produces.
+    setImmediate(() => { try { drive(lastClient, ac); } catch (e) { reject(e); } });
+  });
+}
+
+(async () => {
+  console.log('\n— a socket that closes with no error and no channel open must still finish —');
+  {
+    // The #67 hang, exactly: sshd drops the connection during/just after the handshake.
+    // ssh2 emits 'close' and nothing else. Before the fix there was no listener for it.
+    const r = await runScenario(conn => { conn.emit('close'); });
+    check('onDone fired exactly once', r.doneCount, 1);
+  }
+
+  console.log('\n— a connection error must finish once, not twice —');
+  {
+    const r = await runScenario(conn => {
+      const err = new Error('All configured authentication methods failed');
+      err.level = 'client-authentication';
+      conn.emit('error', err);
+      // The socket close that always follows an ssh2 error. Before the fix conn.on('error')
+      // called h.onDone directly, leaving `finished` false, so this re-fired it.
+      setImmediate(() => conn.emit('close'));
+    });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('the auth failure was reported to the caller',
+      r.errors.some(e => /SSH auth failed/.test(e)), true);
+  }
+
+  console.log('\n— Stop pressed before the channel exists must finish —');
+  {
+    // The abort listener used to live inside the conn.exec callback. Abort here reached
+    // nothing at all: the run neither stopped nor settled.
+    const r = await runScenario((conn, ac) => {
+      conn._execMode = 'never';
+      conn.emit('ready');
+      setTimeout(() => ac.abort(), 30);
+    });
+    check('onDone fired exactly once', r.doneCount, 1);
+  }
+
+  console.log('\n— Stop pressed with a live channel must close it and finish —');
+  {
+    let streamClosed = null;
+    const r = await runScenario((conn, ac) => {
+      conn.emit('ready');
+      setTimeout(() => { ac.abort(); streamClosed = conn.stream?.closed ?? null; }, 60);
+    });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('the exec channel was closed', streamClosed, true);
+  }
+
+  console.log('\n— a failed channel open must finish —');
+  {
+    const r = await runScenario(conn => { conn._execMode = 'error'; conn.emit('ready'); });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('the exec failure was reported', r.errors.some(e => /SSH exec failed/.test(e)), true);
+  }
+
+  console.log('\n— the idle watchdog must finish even with no channel to close —');
+  {
+    // conn.end() alone settles the run only when there is an open channel for ssh2 to
+    // tear down with it. Firing between 'ready' and exec, there is none.
+    const r = await runScenario(conn => { conn._execMode = 'never'; conn.emit('ready'); },
+      { timeoutMs: 3000 });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('the timeout was reported to the caller',
+      r.errors.some(e => /no output for .* min \(idle\)/.test(e)), true);
+  }
+
+  console.log('\n— a normal run still reports its own result, unchanged —');
+  {
+    const r = await runScenario(conn => {
+      conn.emit('ready');
+      setTimeout(() => {
+        const s = conn.stream;
+        s.stdout.emit('data', Buffer.from(
+          JSON.stringify({ type: 'system', subtype: 'init', session_id: 'abc-123' }) + '\n' +
+          JSON.stringify({ type: 'assistant', message: { content: [{ type: 'text', text: 'hello' }] } }) + '\n'));
+        // The channel's own close wins the race against the socket close behind it, so
+        // the real exit code is what reaches finish().
+        s.emit('close', 0);
+      }, 40);
+    });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('the remote session id came back', r.sid, 'abc-123');
+    check('the assistant text came back', r.text, 'hello');
+    check('a clean run reports no error', r.errors, []);
+  }
+
+  console.log('\n— stderr noise is not reported as a failure on abort —');
+  {
+    const r = await runScenario((conn, ac) => {
+      conn.emit('ready');
+      setTimeout(() => {
+        conn.stream.stderr.emit('data', Buffer.from('some teardown noise\n'));
+        ac.abort();
+      }, 40);
+    });
+    check('onDone fired exactly once', r.doneCount, 1);
+    check('no stderr block was pushed into the chat', r.errors, []);
+  }
+
+  // ── source-shape guards, so the paths cannot silently regress ──────────────
+  console.log('\n— the shape of the guarantee —');
+  const src = fs.readFileSync(path.join(__dirname, '..', 'claude-ssh.js'), 'utf8');
+  check("send() listens for the connection's own close", /conn\.on\('close',[\s\S]{0,80}finish\(/.test(src), true);
+  check('no path ends the run on a bare h.onDone any more',
+    /if \(h\.onDone\) h\.onDone\(detectedSid\);/g.test(src) &&
+      (src.match(/if \(h\.onDone\) h\.onDone\(detectedSid\);/g) || []).length, 1); // the one inside finish()
+  // `conn.exec(remoteCmd` and not `conn.exec(` — _execText() has its own exec call
+  // earlier in the file, and matching that one makes this assertion meaningless.
+  check('the abort listener is registered before send() opens its channel',
+    src.indexOf("addEventListener('abort', onAbort") < src.indexOf('conn.exec(remoteCmd'), true);
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail ? 1 : 0);
+})().catch(e => { console.error('FAIL', e.message); process.exit(1); });

From 644067dd8974197c65a9c8f50fbabfa5aef35118 Mon Sep 17 00:00:00 2001
From: Lexus2016 <lexus@cdzv.com>
Date: Tue, 25 Aug 2026 01:32:04 +0200
Subject: [PATCH 2/2] test: move session-restart onto a port no other suite
 books
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

3994 was already session-liveness.test.js's. They never run at the same
time (npm test is serial), but a server that has not released the port
yet fails THIS file's preflight rather than its own — a flake with a
misleading name.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
---
 test/session-restart.test.js | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/test/session-restart.test.js b/test/session-restart.test.js
index 469c75dc..0943b193 100644
--- a/test/session-restart.test.js
+++ b/test/session-restart.test.js
@@ -33,7 +33,10 @@ function check(label, actual, expected) {
 }
 const sleep = ms => new Promise(r => setTimeout(r, ms));
 
-const PORT = Number(process.env.TEST_PORT || 3994);
+// 3992: unused elsewhere in test/. Sharing a port with another server-booting suite
+// works only because npm test runs them serially — one that has not released the port
+// yet fails this file's preflight instead of its own.
+const PORT = Number(process.env.TEST_PORT || 3992);
 const BASE = `http://127.0.0.1:${PORT}`;
 const APP_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-restart-'));
 const HOME_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'ccs-restart-home-'));