From 7b2b2d787a40a93157f3bf6166d135d4c2dc3ce3 Mon Sep 17 00:00:00 2001
From: Lexus2016 <Lexus2016@users.noreply.github.com>
Date: Wed, 11 Nov 2026 10:27:51 +0000
Subject: [PATCH 1/2] settings: give the Configuration dialog the available
 screen (#136)

The Configuration dialog kept a fixed 740px width and an 86vh cap, so on a
large screen most of the window stayed empty while the form, its tabs and the
search bar were squeezed together. It now uses min(1180px, 96vw) by 88dvh.

Refs #136
---
 public/index.html          | 1 +
 test/responsive-ui.test.js | 5 +++++
 2 files changed, 6 insertions(+)

diff --git a/public/index.html b/public/index.html
index 638be38..809b414 100644
--- a/public/index.html
+++ b/public/index.html
@@ -3961,6 +3961,7 @@ <h2 id="gwTitle" style="font-size:14px;display:flex;align-items:center;gap:7px">
 
 <!-- Settings-only layout and keyboard affordances. -->
 <style>
+#cfgModal .modal { width:min(1180px,96vw);max-width:96vw;height:88vh;height:88dvh;max-height:88dvh }
 #cfgModal .settings-note { padding:10px 20px;color:var(--muted);font-size:12px;line-height:1.5 }
 #cfgModal #cfgTabs { overflow-x:auto;flex-shrink:0 }
 #cfgModal #cfgTabs button { white-space:nowrap;font:inherit }
diff --git a/test/responsive-ui.test.js b/test/responsive-ui.test.js
index 7dd5d03..0afafd8 100644
--- a/test/responsive-ui.test.js
+++ b/test/responsive-ui.test.js
@@ -52,5 +52,10 @@ check('kanban.html mobile media query forces card-actions display on touch scree
   assert.ok(/\.card-actions\s*\{[^}]*display:\s*flex\s*!important/.test(media800), 'missing display: flex !important for card-actions in mobile query');
 });
 
+check('configuration modal uses the available screen (#136)', () => {
+  assert.ok(idxSrc.includes('width:min(1180px,96vw)'), 'configuration modal should use the available width');
+  assert.ok(idxSrc.includes('height:88dvh'), 'configuration modal should use the available height');
+});
+
 if (failed) { console.log(`\n${failed} test(s) failed`); process.exit(1); }
 console.log('\nAll responsive-ui tests passed');

From d08361fcc210bf1a0f029155e7c34104a13d54cb Mon Sep 17 00:00:00 2001
From: "Chief (agent)" <25110505+Lexus2016@users.noreply.github.com>
Date: Thu, 12 Nov 2026 18:10:33 +0000
Subject: [PATCH 2/2] engine: opt-in idle reaper for subscription tmux sessions
 (#141)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

A chat on the subscription engine keeps `ccs-<id>` — and every MCP server that
pane spawned, ~1.2 GB on a typical set — alive after its turn ends. Nothing
reaped it: CLAUDE_IDLE_TIMEOUT_MS only bounds a single turn, so memory grew
with every chat opened since the last restart.

CCS_ENGINE_IDLE_KILL_MS (unset or 0 = today's behaviour) kills a pane that has
had no turn and no attached viewer for that long; the next message respawns it
with `--resume <cid>`, the path the config-change respawn already uses, so no
history is lost.

Never reaped: a running turn (answered from server.js's activeTasks /
activeChatSessions / in_progress-task registries, which also cover the autoSkill
window), an attached viewer (and while attached it refreshes the clock, so a
viewer that leaves does not leave an expired timer behind), a pending prompt or
a spinner still animating (#20), and a pane of unknown age — its clock is
started instead of trusted.

test/engine-idle-reaper.test.js pins the decision table through injected seams
and drives a real tmux pane, where a control-mode client must count as a
viewer. Refs #141
---
 .env.example                    |   8 ++
 CLAUDE.md                       |   2 +-
 README.md                       |   1 +
 README_RU.md                    |   1 +
 README_UA.md                    |   1 +
 claude-interactive.js           | 131 +++++++++++++++++++++-
 package.json                    |   2 +-
 server.js                       |   8 +-
 test/engine-idle-reaper.test.js | 192 ++++++++++++++++++++++++++++++++
 9 files changed, 342 insertions(+), 4 deletions(-)
 create mode 100644 test/engine-idle-reaper.test.js

diff --git a/.env.example b/.env.example
index fef2ec8..5c50f2f 100644
--- a/.env.example
+++ b/.env.example
@@ -50,6 +50,14 @@ CLAUDE_IDLE_TIMEOUT_MS=1800000
 # so a task keeps running to the end even with no browser connected.
 # TASK_DISCONNECT_TIMEOUT_MS=1800000
 
+# Reap an idle subscription-engine pane, and every MCP server it spawned.
+# Unset or 0 (default) keeps the old behaviour: `ccs-<id>` lives as long as the
+# studio process. Set it to a window (e.g. 900000 = 15 min) and a chat with no
+# running turn and no attached viewer for that long has its tmux session killed;
+# the next message respawns it with `--resume`, so no history is lost. Measured
+# ~1.2 GB per open session (claude ~300 MB + MCP servers ~900 MB).
+# CCS_ENGINE_IDLE_KILL_MS=0
+
 # Ceiling on turns per sub-agent in multi-agent mode (default 200, matching the
 # UI's "Turns" field). A sub-agent that exhausts its turns auto-continues up to
 # 3 times, so worst case per agent is 4x this number. Lower it to cap spend.
diff --git a/CLAUDE.md b/CLAUDE.md
index 4a5019d..06c7755 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -31,7 +31,7 @@ npm run release <patch|minor|major|x.y.z>  # bump, commit, tag, push → GitHub
 npm run release:mac                         # on the Mac with the cert: build, notarize, verify, upload, bump the cask
 ```
 
-No linting and no build step configured. `npm test` chains 108 test files under `test/`: 20 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 88 plain-`node` suites in `test/` covering the focused workspace and its Back/Forward history (`focused-workspace.test.js`, `secondary-navigation.test.js` — see "Focused workspace navigation" below), the form workflows of every section (`settings-ux`, `team-forms-ux`, `section-controls-ux`, `page-forms-ux` — see docs/SECTION-CONTROLS-REVIEW.md), the sidebar rows and chat delete (`sidebar-ux.test.js` runs the real `delSess`/`delSelectedHist` in a `vm`: a 409 `UNMERGED_WORK` is asked about and resent with force, never swallowed — both doors used to close the tab and reload, so the chat came straight back; and it pins that hover-only row actions take no width on a mouse), the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), session expiry (`session-expiry.test.js` boots a real server TWICE against one `APP_DIR`, ages sessions in SQLite between the boots, and pins that expiry removes the worktree, branch and queued messages of a clean session while keeping one with uncommitted work, its Kanban cards, and an orphan tree younger than an hour), the external agents' model/effort catalogs (`agent-catalog.test.js` — #123: the Settings form and `POST /api/external-agents` both carry them, and the browser's comma parser is RUN against the server sanitiser so the two cannot drift), the Kanban group form (`kanban-group-button.test.js` RUNS the real `buildChainForm` in a `vm` context so a stray free variable in its template throws there instead of silently killing the modal — see #115 — and parses every inline `<script>` of the board), the on-screen terminal keys (`terminal-keys.test.js` runs the real #117 block from `index.html` in a `vm`: the Esc/Tab/arrow bytes including SS3 under DECCKM, a ONE-SHOT Ctrl that applies to the next key from either the row or the phone keyboard, and that a tap never takes focus — a focused button closes Gboard on every key), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, authentication-failure classification (`auth-errors.test.js`, which pins that the detector runs BEFORE the auto-continue in all three agent loops — a reorder there silently restores #86), 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 subscription engine's spawn command (`engine-spawn-cmd.test.js` starts a real tmux session with a 40 KB system prompt and asserts the child's argv byte-identical — the tmux command may never carry the prompt inline, see #96), the interactive TUI's first-run screens (`claude-firstrun.test.js` reads the theme picker, trust question and Bypass Permissions warning CAPTURED from CLI 2.1.288 in `test/fixtures/claude-tui/`, pins the config seed, and drives `runInteractiveSingle` against a fake `claude` drawing the trust screen to prove nothing is pasted into it), the cross-project global workspace aggregation, the add-project-from-Git-URL endpoint (`git-clone.test.js` boots a server whose `PATH` holds a fake `git` and pins the transport allowlist, the `--` argv shape and the failure cleanup — see #94), the rule that an SSH credential never leaves the server process, the macOS release config (`mac-signing.test.js` — the Apple Events entitlement, arm64-only targets, and that CI never builds macOS) and the local mac release (`release-mac.test.js` — nothing is uploaded until spctl says `Notarized Developer ID` about the app and the app inside the dmg), 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), and `engine-default.test.mjs` pins three ways the UI and the chat disagreed about the engine: the mobile sheet's engine chips (the API chip ships `on`, so a sync that skips the group blanks both), `send()` waiting for `/api/version` to supply the configured default before it reads `curEngine`, and `checkVersion()` applying that default even when the last script block (home of `loadTerminalCapability`) has not been parsed yet. The third is the cause of the other two looking like they did nothing: that call threw a `ReferenceError` into `checkVersion`'s own `catch {}` and skipped the configured engine, the chat defaults and `loadBots()`. Three rules on the wait, each found by an independent review of the first version: it is bounded by `VERSION_WAIT_MS`, never indefinite; it never applies to a user who already clicked an engine chip (`_engineUserPicked` — set by `setOpt`/`setMobOpt`, cleared by `resolveEngineForView()`), whose pick neither the wait nor `checkVersion()`'s resolve may overwrite; and it waits on the LOCAL version reply only — the GitHub release lookup is `_checkLatestRelease`, deliberately not awaited, or a firewall that drops packets to GitHub would add the full bound to every send. Keep literal `<script>` tags out of comments in `index.html` — `script-scope.test.mjs` counts them as block boundaries. `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 five tmux-dependent suites do not self-skip).
+No linting and no build step configured. `npm test` chains 108 test files under `test/`: 20 DOM-less render/UI-logic tests (`test/render/*.test.mjs`, run through `node --test`) plus 88 plain-`node` suites in `test/` covering the focused workspace and its Back/Forward history (`focused-workspace.test.js`, `secondary-navigation.test.js` — see "Focused workspace navigation" below), the form workflows of every section (`settings-ux`, `team-forms-ux`, `section-controls-ux`, `page-forms-ux` — see docs/SECTION-CONTROLS-REVIEW.md), the sidebar rows and chat delete (`sidebar-ux.test.js` runs the real `delSess`/`delSelectedHist` in a `vm`: a 409 `UNMERGED_WORK` is asked about and resent with force, never swallowed — both doors used to close the tab and reload, so the chat came straight back; and it pins that hover-only row actions take no width on a mouse), the overload detector, env load order, multi-agent results, terminals, bots, telegram, updates, kanban scheduling, the Kanban card's run-settings badges (`kanban-run-badges.test.js` pins the card's model/effort/engine chain against the one `startTask` actually resolves — the two live in different files and the card silently lies when they drift), the board-only `create_task` status (`task-backlog.test.js`), session expiry (`session-expiry.test.js` boots a real server TWICE against one `APP_DIR`, ages sessions in SQLite between the boots, and pins that expiry removes the worktree, branch and queued messages of a clean session while keeping one with uncommitted work, its Kanban cards, and an orphan tree younger than an hour), the external agents' model/effort catalogs (`agent-catalog.test.js` — #123: the Settings form and `POST /api/external-agents` both carry them, and the browser's comma parser is RUN against the server sanitiser so the two cannot drift), the Kanban group form (`kanban-group-button.test.js` RUNS the real `buildChainForm` in a `vm` context so a stray free variable in its template throws there instead of silently killing the modal — see #115 — and parses every inline `<script>` of the board), the on-screen terminal keys (`terminal-keys.test.js` runs the real #117 block from `index.html` in a `vm`: the Esc/Tab/arrow bytes including SS3 under DECCKM, a ONE-SHOT Ctrl that applies to the next key from either the row or the phone keyboard, and that a tap never takes focus — a focused button closes Gboard on every key), i18n completeness, the config precedence resolver plus its secret masking, usage-limit detection, authentication-failure classification (`auth-errors.test.js`, which pins that the detector runs BEFORE the auto-continue in all three agent loops — a reorder there silently restores #86), 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 subscription engine's spawn command (`engine-spawn-cmd.test.js` starts a real tmux session with a 40 KB system prompt and asserts the child's argv byte-identical — the tmux command may never carry the prompt inline, see #96), the opt-in idle reaper (`engine-idle-reaper.test.js` pins the decision table — a running turn, an attached viewer, a pending prompt and a spinner still animating all keep the pane, while a pane past `CCS_ENGINE_IDLE_KILL_MS` is killed, and an unknown clock is started instead of trusted — and drives a real tmux pane, where a control client must count as a viewer), the interactive TUI's first-run screens (`claude-firstrun.test.js` reads the theme picker, trust question and Bypass Permissions warning CAPTURED from CLI 2.1.288 in `test/fixtures/claude-tui/`, pins the config seed, and drives `runInteractiveSingle` against a fake `claude` drawing the trust screen to prove nothing is pasted into it), the cross-project global workspace aggregation, the add-project-from-Git-URL endpoint (`git-clone.test.js` boots a server whose `PATH` holds a fake `git` and pins the transport allowlist, the `--` argv shape and the failure cleanup — see #94), the rule that an SSH credential never leaves the server process, the macOS release config (`mac-signing.test.js` — the Apple Events entitlement, arm64-only targets, and that CI never builds macOS) and the local mac release (`release-mac.test.js` — nothing is uploaded until spctl says `Notarized Developer ID` about the app and the app inside the dmg), 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), and `engine-default.test.mjs` pins three ways the UI and the chat disagreed about the engine: the mobile sheet's engine chips (the API chip ships `on`, so a sync that skips the group blanks both), `send()` waiting for `/api/version` to supply the configured default before it reads `curEngine`, and `checkVersion()` applying that default even when the last script block (home of `loadTerminalCapability`) has not been parsed yet. The third is the cause of the other two looking like they did nothing: that call threw a `ReferenceError` into `checkVersion`'s own `catch {}` and skipped the configured engine, the chat defaults and `loadBots()`. Three rules on the wait, each found by an independent review of the first version: it is bounded by `VERSION_WAIT_MS`, never indefinite; it never applies to a user who already clicked an engine chip (`_engineUserPicked` — set by `setOpt`/`setMobOpt`, cleared by `resolveEngineForView()`), whose pick neither the wait nor `checkVersion()`'s resolve may overwrite; and it waits on the LOCAL version reply only — the GitHub release lookup is `_checkLatestRelease`, deliberately not awaited, or a firewall that drops packets to GitHub would add the full bound to every send. Keep literal `<script>` tags out of comments in `index.html` — `script-scope.test.mjs` counts them as block boundaries. `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 five tmux-dependent suites do not self-skip).
 
 ## Architecture
 
diff --git a/README.md b/README.md
index cf83057..741f6f6 100644
--- a/README.md
+++ b/README.md
@@ -547,6 +547,7 @@ WORKDIR=./workspace
 MAX_TASK_WORKERS=5
 CLAUDE_IDLE_TIMEOUT_MS=600000   # kill subprocess after this idle gap (no output); default 10 min, .env.example ships 30 min (legacy alias: CLAUDE_TIMEOUT_MS)
 CLAUDE_HARD_CAP_MS=0            # optional absolute timeout ceiling; 0 = disabled (default)
+CCS_ENGINE_IDLE_KILL_MS=0       # kill an idle subscription-engine tmux pane (and its MCP servers) after this long; 0 = never (default)
 TASK_DISCONNECT_TIMEOUT_MS=1800000  # abort a task this long after the browser tab detaches; 0 = never
 MULTI_AGENT_MAX_TURNS_CAP=200   # ceiling on turns per sub-agent; each may auto-continue 3x
 TRUST_PROXY=false
diff --git a/README_RU.md b/README_RU.md
index 17a6d65..dcd4912 100644
--- a/README_RU.md
+++ b/README_RU.md
@@ -547,6 +547,7 @@ WORKDIR=./workspace
 MAX_TASK_WORKERS=5
 CLAUDE_IDLE_TIMEOUT_MS=600000   # kill subprocess after this idle gap (no output); default 10 min, .env.example ships 30 min (legacy alias: CLAUDE_TIMEOUT_MS)
 CLAUDE_HARD_CAP_MS=0            # optional absolute timeout ceiling; 0 = disabled (default)
+CCS_ENGINE_IDLE_KILL_MS=0       # kill an idle subscription-engine tmux pane (and its MCP servers) after this long; 0 = never (default)
 TASK_DISCONNECT_TIMEOUT_MS=1800000  # abort a task this long after the browser tab detaches; 0 = never
 MULTI_AGENT_MAX_TURNS_CAP=200   # ceiling on turns per sub-agent; each may auto-continue 3x
 TRUST_PROXY=false
diff --git a/README_UA.md b/README_UA.md
index 38f7f8e..e700d7a 100644
--- a/README_UA.md
+++ b/README_UA.md
@@ -548,6 +548,7 @@ WORKDIR=./workspace
 MAX_TASK_WORKERS=5
 CLAUDE_IDLE_TIMEOUT_MS=600000   # kill subprocess after this idle gap (no output); default 10 min, .env.example ships 30 min (legacy alias: CLAUDE_TIMEOUT_MS)
 CLAUDE_HARD_CAP_MS=0            # optional absolute timeout ceiling; 0 = disabled (default)
+CCS_ENGINE_IDLE_KILL_MS=0       # kill an idle subscription-engine tmux pane (and its MCP servers) after this long; 0 = never (default)
 TASK_DISCONNECT_TIMEOUT_MS=1800000  # abort a task this long after the browser tab detaches; 0 = never
 MULTI_AGENT_MAX_TURNS_CAP=200   # ceiling on turns per sub-agent; each may auto-continue 3x
 TRUST_PROXY=false
diff --git a/claude-interactive.js b/claude-interactive.js
index c2bd996..1d582a1 100644
--- a/claude-interactive.js
+++ b/claude-interactive.js
@@ -55,6 +55,19 @@ const IDLE_TIMEOUT_MS = parseInt(process.env.CLAUDE_IDLE_TIMEOUT_MS || process.e
 // Optional absolute ceiling — backstop against a turn that stays "busy" forever. 0 = off.
 const HARD_CAP_MS = parseInt(process.env.CLAUDE_HARD_CAP_MS || '0', 10) || 0;
 
+// Opt-in idle reaper for the engine's tmux sessions (GitHub #141). A subscription
+// chat keeps `ccs-<id>` — and every MCP server that pane spawned, ~1.2 GB on a
+// typical set — alive after its turn ends; nothing else ever reaps it, so memory
+// grows with the number of chats opened since the last restart. Unset (or 0) keeps
+// exactly the old behaviour. When set, a session with no turn and no attached
+// viewer for this long is killed, and the next message respawns it with
+// `--resume <cid>` — the path a config-change respawn already uses, so no history
+// is lost.
+const ENGINE_IDLE_KILL_MS = parseInt(process.env.CCS_ENGINE_IDLE_KILL_MS || '0', 10) || 0;
+// Floor for the reaper tick: a `list-clients` + `capture-pane` per engine session
+// is cheap, but not free, and nothing here needs sub-15s precision.
+const ENGINE_REAPER_MIN_TICK_MS = 15000;
+
 // ─── Interactive-prompt watchdog (GitHub #20) ────────────────────────────────
 // How often the turn loop looks at the transcript and the pane.
 const POLL_MS = 1500;
@@ -416,6 +429,112 @@ function killInteractiveTmux(localSessionId) {
   } catch {}
 }
 
+// ─── Idle reaper (GitHub #141) ────────────────────────────────────────────────
+// Every helper below is READ-ONLY on tmux except the two touch/kill calls. The
+// reaper is deliberately dumb about WHO owns a turn: it asks the caller
+// (`isLive`), because only server.js knows the activeTasks / activeChatSessions /
+// in_progress-task registries. Everything else — a viewer, a pending prompt, a
+// spinner still animating — is visible in the pane itself, so it is checked here.
+function listEngineSessions() {
+  try {
+    const r = spawnSync('tmux', tmuxArgs(['list-sessions', '-F', '#{session_name}']), { encoding: 'utf8' });
+    if (r.error || r.status !== 0) return [];
+    return String(r.stdout || '').split('\n').map(s => s.trim()).filter(n => /^ccs-/.test(n));
+  } catch { return []; }
+}
+
+// `list-clients -t` targets a CLIENT, not a session, so the filter must read the
+// client's session name from its format instead. A failure here reports 1 (assume
+// somebody is watching): a skipped reap costs memory, a wrong one costs the chat.
+function engineSessionClients(name) {
+  try {
+    const r = spawnSync('tmux', tmuxArgs(['list-clients', '-F', '#{client_session}']), { encoding: 'utf8' });
+    if (r.error || r.status !== 0) return 1;
+    return String(r.stdout || '').split('\n').map(s => s.trim()).filter(s => s === name).length;
+  } catch { return 1; }
+}
+
+function engineSessionId(name) {
+  const raw = getTmuxEnv(name, 'CCS_SESSION');
+  if (raw) return raw;
+  const bare = String(name || '').replace(/^ccs-/, '');
+  return bare || null;
+}
+
+function touchEngineSession(name, now = Date.now()) {
+  setTmuxEnv(name, 'CCS_LAST_TURN', String(now));
+}
+
+// Kill `ccs-<id>` panes that have been idle for longer than `idleMs`. Returns the
+// local session ids it killed. Injected seams (all optional) exist so the decision
+// table can be tested without tmux.
+function reapIdleEngineSessions(opts = {}) {
+  const idleMs = Number.isFinite(opts.idleMs) ? opts.idleMs : ENGINE_IDLE_KILL_MS;
+  if (!(idleMs > 0)) return [];                       // opt-in only
+  const now = Number.isFinite(opts.now) ? opts.now : Date.now();
+  const isLive = typeof opts.isLive === 'function' ? opts.isLive : () => false;
+  const list = typeof opts.list === 'function' ? opts.list : listEngineSessions;
+  const clientsOf = typeof opts.clientsOf === 'function' ? opts.clientsOf : engineSessionClients;
+  const paneOf = typeof opts.paneOf === 'function' ? opts.paneOf : capturePane;
+  const idOf = typeof opts.sessionIdOf === 'function' ? opts.sessionIdOf : engineSessionId;
+  const lastTurnOf = typeof opts.lastTurnOf === 'function'
+    ? opts.lastTurnOf
+    : (name) => parseInt(getTmuxEnv(name, 'CCS_LAST_TURN') || '', 10);
+  const kill = typeof opts.kill === 'function' ? opts.kill : (id) => killInteractiveTmux(id);
+  const touch = typeof opts.touch === 'function' ? opts.touch : (name) => touchEngineSession(name, now);
+
+  const killed = [];
+  for (const name of list() || []) {
+    if (!/^ccs-/.test(String(name))) continue;        // never touch anything else on the socket
+    const id = idOf(name);
+    if (!id) continue;
+    // A turn is running. The caller's registries also cover the window before the
+    // subprocess exists (autoSkill classification), which a pane check cannot see.
+    if (isLive(id)) { touch(name); continue; }
+    // A viewer is attached (view=engine, or a human in `tmux attach`). Treat it as
+    // activity: otherwise a viewer that reads for an hour then detaches would leave
+    // an already-expired clock behind and the pane would die on the next tick.
+    if (clientsOf(name) > 0) { touch(name); continue; }
+    // A pending prompt is waiting on a human (#20). Its turn may already have ended
+    // (grace expiry), but the pane must survive until the widget is answered — a
+    // killed pane turns "waiting for you" into a lost conversation.
+    const pane = paneOf(name);
+    if (paneBusy(pane, null) || paneAwaitingInput(pane) || paneAwaitingSelection(pane)) { touch(name); continue; }
+    const last = Number(lastTurnOf(name));
+    // Unknown age: a pane from before this feature, or a studio restart that lost the
+    // tmux environment. Start the clock now rather than kill a conversation of
+    // unknown age — the next full window still reaps it.
+    if (!(last > 0) || last > now) { touch(name); continue; }
+    if (now - last >= idleMs) { kill(id); killed.push(id); }
+  }
+  return killed;
+}
+
+// Start the periodic reaper. Returns null when CCS_ENGINE_IDLE_KILL_MS is unset —
+// no timer, no tmux calls, nothing to opt out of later.
+function startEngineIdleReaper(opts = {}) {
+  const idleMs = Number.isFinite(opts.idleMs) ? opts.idleMs : ENGINE_IDLE_KILL_MS;
+  if (!(idleMs > 0)) return null;
+  const tickMs = Number.isFinite(opts.tickMs) && opts.tickMs > 0
+    ? opts.tickMs
+    : Math.max(ENGINE_REAPER_MIN_TICK_MS, Math.min(60000, Math.floor(idleMs / 4)));
+  const log = opts.log || console;
+  const timer = setInterval(() => {
+    try {
+      const killed = reapIdleEngineSessions({ ...opts, idleMs });
+      for (const id of killed) {
+        try { log.info('engine idle session reaped', { sessionId: id, idleMs }); } catch {}
+        try { if (typeof opts.onKill === 'function') opts.onKill(id); } catch {}
+      }
+    } catch (e) {
+      // A reaper bug must never take the studio down with it.
+      try { log.error('engine idle reaper failed', { error: e && e.message ? e.message : String(e) }); } catch {}
+    }
+  }, tickMs);
+  try { if (timer.unref) timer.unref(); } catch {}
+  return timer;
+}
+
 // Run one message through the persistent interactive tmux session.
 // Params: same object as server.js runCliSingle — uses prompt, systemPrompt, model,
 // mode, ws, sessionId, abortController, claudeSessionId, workdir, tabId; ignores the rest.
@@ -517,6 +636,13 @@ async function runInteractiveSingle(params) {
 
       setTmuxEnv(name, 'CCS_CFG', cfgHash);
 
+      // Identity and idle clock for the reaper (GitHub #141). CCS_SESSION keeps the
+      // exact local session id even when tmuxName() had to sanitize it (the reaper
+      // must kill by the same name the engine uses); CCS_LAST_TURN lives in tmux's
+      // session environment, so it survives a studio restart together with the pane.
+      setTmuxEnv(name, 'CCS_SESSION', String(sessionId));
+      setTmuxEnv(name, 'CCS_LAST_TURN', String(Date.now()));
+
       // Wait for the TUI to settle: two consecutive identical, non-empty captures
       let prev = null;
       const settleDeadline = Date.now() + 20000;
@@ -900,6 +1026,9 @@ async function runInteractiveSingle(params) {
   } finally {
     // The turn is over whichever way it ended; the banner must not outlive it.
     if (awaitAnnounced) { awaitAnnounced = false; wsSendAll({ type: 'input_resolved', sessionId }); }
+    // The idle clock starts when the turn ENDS, not when the pane was spawned — a
+    // long first turn must never count as idle time. Skipped if the pane died.
+    if (tmuxHasSession(name)) setTmuxEnv(name, 'CCS_LAST_TURN', String(Date.now()));
   }
 }
 
@@ -991,4 +1120,4 @@ function catchUpFromTranscript({ cid, startOffset = 0 } = {}) {
   return out;
 }
 
-module.exports = { runInteractiveSingle, killInteractiveTmux, tmuxAvailable, catchUpFromTranscript, transcriptSize, tmuxName, listOrphanedDefaultSocketSessions, paneAwaitingInput, paneAwaitingSelection, promptExcerpt, buildInteractiveCommand, tmuxLaunchCommand };
+module.exports = { runInteractiveSingle, killInteractiveTmux, tmuxAvailable, catchUpFromTranscript, transcriptSize, tmuxName, listOrphanedDefaultSocketSessions, paneAwaitingInput, paneAwaitingSelection, promptExcerpt, buildInteractiveCommand, tmuxLaunchCommand, ENGINE_IDLE_KILL_MS, listEngineSessions, engineSessionClients, engineSessionId, touchEngineSession, reapIdleEngineSessions, startEngineIdleReaper };
diff --git a/package.json b/package.json
index bfc9068..849f413 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/auth-errors.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/tmux-composite.test.js && node test/engine-spawn-cmd.test.js && node test/claude-firstrun.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/agent-catalog.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/kanban-run-badges.test.js && node test/task-backlog.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/run-continuation.test.js && node test/worktree-manager.test.js && node test/session-expiry.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 && node test/claude-cli-status.test.js && node test/asar-helpers.test.js && node test/mac-signing.test.js && node test/release-mac.test.js && node test/task-workers.test.js && node test/git-clone.test.js && node test/responsive-ui.test.js && node test/kanban-delegation.test.js && node test/kanban-group-button.test.js && node test/terminal-keys.test.js && node test/electron-navigation.test.js && node test/cli-runtime.test.js && node test/worktree-safety.test.js && node test/auth-boundary.test.js && node test/cli-process-tree.test.js && node test/schedule-actions.test.js && node test/install-hooks.test.js && node test/frontend-recovery.test.js && node test/db-revisions.test.js && node test/frontend-refresh-races.test.js && node test/release-gate.test.js && node test/focused-workspace.test.js && node test/secondary-navigation.test.js && node test/section-controls-ux.test.js && node test/settings-ux.test.js && node test/team-forms-ux.test.js && node test/page-forms-ux.test.js && node test/sidebar-ux.test.js && node test/task-text-limit.test.js && node test/terminal-clipboard.test.js && node test/terminal-addons.test.js && node test/file-preview-copy.test.js && node test/telegram-lang.test.js",
+    "test": "node --test test/render/*.test.mjs && node test/overload-detector.test.js && node test/usage-limit.test.js && node test/auth-errors.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/tmux-composite.test.js && node test/engine-spawn-cmd.test.js && node test/claude-firstrun.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/agent-catalog.test.js && node test/update-flow.test.js && node test/kanban-schedule.test.js && node test/kanban-run-badges.test.js && node test/task-backlog.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/run-continuation.test.js && node test/worktree-manager.test.js && node test/session-expiry.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/engine-idle-reaper.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 && node test/claude-cli-status.test.js && node test/asar-helpers.test.js && node test/mac-signing.test.js && node test/release-mac.test.js && node test/task-workers.test.js && node test/git-clone.test.js && node test/responsive-ui.test.js && node test/kanban-delegation.test.js && node test/kanban-group-button.test.js && node test/terminal-keys.test.js && node test/electron-navigation.test.js && node test/cli-runtime.test.js && node test/worktree-safety.test.js && node test/auth-boundary.test.js && node test/cli-process-tree.test.js && node test/schedule-actions.test.js && node test/install-hooks.test.js && node test/frontend-recovery.test.js && node test/db-revisions.test.js && node test/frontend-refresh-races.test.js && node test/release-gate.test.js && node test/focused-workspace.test.js && node test/secondary-navigation.test.js && node test/section-controls-ux.test.js && node test/settings-ux.test.js && node test/team-forms-ux.test.js && node test/page-forms-ux.test.js && node test/sidebar-ux.test.js && node test/task-text-limit.test.js && node test/terminal-clipboard.test.js && node test/terminal-addons.test.js && node test/file-preview-copy.test.js && node test/telegram-lang.test.js",
     "postinstall": "node scripts/install-hooks.js",
     "release": "node scripts/release.js",
     "release:mac": "node scripts/release-mac.js",
diff --git a/server.js b/server.js
index 44a046e..e725bbf 100644
--- a/server.js
+++ b/server.js
@@ -132,7 +132,7 @@ const botsLogic = require('./bots');
 // instruction at all. One line stands in for "you were addressed with nothing else
 // to go on".
 const BARE_MENTION_PROMPT = "You were addressed directly with no other text — greet them and ask what they need, or continue naturally if there is relevant prior context in this conversation.";
-const { runInteractiveSingle, killInteractiveTmux, tmuxAvailable, catchUpFromTranscript, transcriptSize, tmuxName: interactiveTmuxName, listOrphanedDefaultSocketSessions } = require('./claude-interactive');
+const { runInteractiveSingle, killInteractiveTmux, tmuxAvailable, catchUpFromTranscript, transcriptSize, tmuxName: interactiveTmuxName, listOrphanedDefaultSocketSessions, startEngineIdleReaper } = require('./claude-interactive');
 const WM = require('./worktree-manager');
 const ClaudeSSH = require('./claude-ssh');
 const { testSshConnection } = require('./claude-ssh');
@@ -9190,6 +9190,12 @@ setInterval(cleanOldUploads, 30 * 60 * 1000); // then every 30 min
 runDatabaseMaintenance();                                            // run once on startup
 setInterval(runDatabaseMaintenance, CLEANUP_INTERVAL_HOURS * 60 * 60 * 1000); // every N hours
 
+// Idle engine reaper (GitHub #141): opt-in via CCS_ENGINE_IDLE_KILL_MS. It runs from
+// here because this is the one place that knows which chats are live — a pane whose
+// turn is running (activeTasks / activeChatSessions / an in_progress Kanban task) is
+// never touched. Unset, this returns null and nothing is scheduled.
+startEngineIdleReaper({ isLive: isSessionLive, log });
+
 app.post('/api/upload', fileUpload.single('file'), (req, res) => {
   if (!req.file) return res.status(400).json({ error: 'No file provided' });
   try {
diff --git a/test/engine-idle-reaper.test.js b/test/engine-idle-reaper.test.js
new file mode 100644
index 0000000..1863341
--- /dev/null
+++ b/test/engine-idle-reaper.test.js
@@ -0,0 +1,192 @@
+// GitHub #141 — "Opt-in reaper for idle subscription-engine tmux sessions".
+//
+// A subscription chat keeps its `ccs-<id>` tmux pane (and every MCP server that pane
+// spawned) alive after the turn ends, so a host accumulates ~1.2 GB per chat opened
+// since the last restart. The answer is an opt-in reaper: CCS_ENGINE_IDLE_KILL_MS
+// unset means today's behaviour, and when set a pane with no turn and no attached
+// viewer for that long is killed; the next message respawns it with `--resume`.
+//
+// The decision table below is driven through the injected seams, so it runs with or
+// without tmux. The last block drives a REAL tmux pane and self-skips when tmux is
+// absent (same rule as the other tmux suites: name only sessions this file created,
+// never `kill-server`, never a prefix lookup on the shared socket).
+//
+// Run: node test/engine-idle-reaper.test.js
+const assert = require('assert');
+const { spawn, spawnSync } = require('child_process');
+
+const interactive = require('../claude-interactive');
+const { TMUX_SOCKET } = require('../terminal-bridge');
+
+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} \u2014 expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`); }
+}
+
+const sleep = ms => new Promise(r => setTimeout(r, ms));
+async function waitFor(predicate, timeoutMs = 5000, intervalMs = 50) {
+  const deadline = Date.now() + timeoutMs;
+  for (;;) {
+    let v = false;
+    try { v = predicate(); } catch { v = false; }
+    if (v) return v;
+    if (Date.now() >= deadline) return v;
+    await sleep(intervalMs);
+  }
+}
+
+const IDLE = 60000;
+const NOW = 1000000000000;
+
+// One fake pane per test. `id` defaults to the name minus the ccs- prefix, exactly
+// what engineSessionId() falls back to for a pane spawned before CCS_SESSION existed.
+function makeWorld(sessions) {
+  const byName = new Map(sessions.map(s => [s.name, s]));
+  const killed = [];
+  const touched = [];
+  const idOf = (name) => (byName.get(name).id || name.replace(/^ccs-/, ''));
+  const reap = (over = {}) => interactive.reapIdleEngineSessions({
+    idleMs: IDLE,
+    now: NOW,
+    list: () => sessions.map(s => s.name),
+    sessionIdOf: idOf,
+    isLive: (id) => sessions.some(s => idOf(s.name) === id && !!s.live),
+    clientsOf: (name) => byName.get(name).clients || 0,
+    paneOf: (name) => byName.get(name).pane || '',
+    lastTurnOf: (name) => byName.get(name).last,
+    kill: (id) => killed.push(id),
+    touch: (name) => touched.push(name),
+    ...over,
+  });
+  return { reap, killed, touched };
+}
+
+console.log('opt-in switch:');
+{
+  const w = makeWorld([{ name: 'ccs-a', last: NOW - IDLE * 10 }]);
+  check('unset (0) reaps nothing', w.reap({ idleMs: 0 }), []);
+  check('unset (0) kills nothing', w.killed, []);
+  check('unset (0) does not even touch', w.touched, []);
+  check('a negative window also disables', w.reap({ idleMs: -5 }), []);
+  check('startEngineIdleReaper is null when disabled', interactive.startEngineIdleReaper({ idleMs: 0 }), null);
+}
+
+console.log('\nthe decision table:');
+{
+  const w = makeWorld([{ name: 'ccs-old', last: NOW - IDLE - 1 }]);
+  check('past the window is killed', w.reap(), ['old']);
+  check('and the kill is by local session id', w.killed, ['old']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-edge', last: NOW - IDLE }]);
+  check('exactly at the window is killed', w.reap(), ['edge']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-fresh', last: NOW - IDLE + 1 }]);
+  check('inside the window survives', w.reap(), []);
+}
+{
+  const w = makeWorld([{ name: 'ccs-live', last: NOW - IDLE * 20, live: true }]);
+  check('a running turn survives however old the clock', w.reap(), []);
+  check('a running turn refreshes the clock', w.touched, ['ccs-live']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-watched', last: NOW - IDLE * 20, clients: 1 }]);
+  check('an attached viewer survives', w.reap(), []);
+  check('an attached viewer refreshes the clock', w.touched, ['ccs-watched']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-prompt', last: NOW - IDLE * 20, pane: '> 1. Yes\n  2. No' }]);
+  check('a pending prompt survives (#20)', w.reap(), []);
+  check('a pending prompt refreshes the clock', w.touched, ['ccs-prompt']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-busy', last: NOW - IDLE * 20, pane: '(8s \u00b7 esc to interrupt)' }]);
+  check('a spinner still animating survives', w.reap(), []);
+}
+{
+  const w = makeWorld([{ name: 'ccs-mystery', last: null }]);
+  check('a pane of unknown age is not killed', w.reap(), []);
+  check('its clock is started instead', w.touched, ['ccs-mystery']);
+}
+{
+  const w = makeWorld([{ name: 'ccs-skew', last: NOW + 30000 }]);
+  check('a clock from the future is not trusted', w.reap(), []);
+}
+{
+  const w = makeWorld([
+    { name: 'ccs-a', last: NOW - IDLE * 3 },
+    { name: 'ccs-b', last: NOW - 1000 },
+    { name: 'terminal-7', last: 0 },
+  ]);
+  check('mixed set: only the idle engine pane is reaped', w.reap(), ['a']);
+  check('a non-engine session on the socket is never killed', w.killed.includes('terminal-7'), false);
+}
+{
+  const w = makeWorld([{ name: 'ccs-x', last: NOW - IDLE * 2, id: 'real\u2014id\u2014with\u2014unicode' }]);
+  check('kills by CCS_SESSION, not by the sanitized name', w.reap(), ['real\u2014id\u2014with\u2014unicode']);
+}
+
+console.log('\nthe timer:');
+{
+  const timer = interactive.startEngineIdleReaper({
+    idleMs: 5000, tickMs: 50, isLive: () => false,
+    list: () => [], log: { info: () => {}, error: () => {} },
+  });
+  check('a timer exists once enabled', !!timer && typeof timer.ref === 'function', true);
+  try { clearInterval(timer); } catch {}
+  const off = interactive.startEngineIdleReaper({ idleMs: 0, tickMs: 10, list: () => [], log: { info() {}, error() {} } });
+  check('no timer when disabled', off, null);
+}
+
+(async () => {
+  console.log('\nreal tmux (skipped when tmux is not installed):');
+  if (!interactive.tmuxAvailable()) {
+    console.log('  skip tmux is not installed here');
+  } else {
+    const rawTmux = (...args) => spawnSync('tmux', ['-L', TMUX_SOCKET, ...args], { encoding: 'utf8' });
+    const mine = [];
+    const makePane = (name, lastTurn) => {
+      rawTmux('new-session', '-d', '-s', name, '-x', '120', '-y', '30', '-c', '/tmp', `sh -c 'echo IDLE-PANE; cat'`);
+      rawTmux('set-environment', '-t', name, 'CCS_SESSION', name.replace(/^ccs-/, ''));
+      if (lastTurn !== null) rawTmux('set-environment', '-t', name, 'CCS_LAST_TURN', String(lastTurn));
+      mine.push(name);
+    };
+    const has = (name) => rawTmux('has-session', '-t', name).status === 0;
+    let client = null;
+    try {
+      const stale = `ccs-reaper-stale-${process.pid}`;
+      const fresh = `ccs-reaper-fresh-${process.pid}`;
+      makePane(stale, Date.now() - IDLE * 5);
+      makePane(fresh, Date.now());
+      check('both test panes are up', [has(stale), has(fresh)], [true, true]);
+
+      // Only this file's panes: the real list would include a developer's live chats.
+      const killed = interactive.reapIdleEngineSessions({ idleMs: IDLE, list: () => [stale, fresh] });
+      check('reaper kills the stale pane', killed, [stale.replace(/^ccs-/, '')]);
+      check('stale pane is gone', has(stale), false);
+      check('fresh pane is untouched', has(fresh), true);
+
+      // The viewer rule against a real tmux client: engineSessionClients() reads the
+      // client's `#{client_session}`, and this proves the format and the comparison
+      // actually line up — a typo here would silently reap a watched pane.
+      client = spawn('tmux', ['-L', TMUX_SOCKET, '-C', 'attach-session', '-t', fresh], { stdio: ['pipe', 'pipe', 'pipe'] });
+      client.stdin.on('error', () => {});
+      const attached = await waitFor(() => interactive.engineSessionClients(fresh) > 0);
+      check('the control client counts as an attached viewer', attached, true);
+      rawTmux('set-environment', '-t', fresh, 'CCS_LAST_TURN', String(Date.now() - IDLE * 5));
+      const kept = interactive.reapIdleEngineSessions({ idleMs: IDLE, list: () => [fresh] });
+      check('an attached viewer keeps the pane alive', kept, []);
+      check('pane still up', has(fresh), true);
+    } catch (e) {
+      check('tmux block ran without throwing', String((e && e.message) || e), '');
+    } finally {
+      if (client) { try { client.kill(); } catch {} }
+      for (const n of mine) { try { rawTmux('kill-session', '-t', n); } catch {} }
+    }
+  }
+
+  console.log(`\n${pass} passed, ${fail} failed`);
+  process.exit(fail === 0 ? 0 : 1);
+})();