Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

feat(terminal): raise default park window 5 -> 10 min (#886)

reviewf9980d5fa7b7
diff --git a/CLAUDE.md b/CLAUDE.md
index 81b4bd1be..7c96e12c1 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -580,7 +580,7 @@ Lifecycle, by intent:
carry over; do NOT "optimize" this into a respawn+redraw — a fresh xterm on a reused client
misses the attach-time mode sequences and breaks scrolling). The park timer then runs the real
teardown: `kill()` detaches the PTY client; the tmux session keeps running. **Window and cap
- are settings (issue #886)**: `settings.terminalParkMinutes` (default 5; **0 = until app quit** —
+ are settings (issue #886)**: `settings.terminalParkMinutes` (default **10**, raised from 5; **0 = until app quit** —
`parkWindowMs` returns `null` and NO timer is armed, never `Infinity`, which `setTimeout` clamps
to ~1 ms and would dispose every park at once) and `settings.terminalParkMax` (default **20**, raised from 12), both
re-validated at park time. The LRU cap evicts **local parks before remote ones**
diff --git a/src/core/pty-coattach.test.ts b/src/core/pty-coattach.test.ts
index 8ccab3295..a1bb890fa 100644
--- a/src/core/pty-coattach.test.ts
+++ b/src/core/pty-coattach.test.ts
@@ -702,7 +702,7 @@ describe('size negotiation: smallest subscriber wins', () => {
})
// ── A PARKED terminal is subscribed but not looking ──────────────────────────────────────
- // The renderer keeps a node's xterm+PTY alive for 5 minutes after unmount (TERM_PARK_MS), so a
+ // The renderer keeps a node's xterm+PTY alive for the park window after unmount (`settings.terminalParkMinutes`), so a
// parked client stays a subscriber. Its (possibly tiny) last fit must NOT shrink the terminal
// for the people still watching — it reports a null size instead: "listening, not viewing".
it('a parked subscriber (null size) stops constraining the shared pty but keeps its output', async () => {
diff --git a/src/core/pty-idle-reap.test.ts b/src/core/pty-idle-reap.test.ts
index 002520b4b..f68380f27 100644
--- a/src/core/pty-idle-reap.test.ts
+++ b/src/core/pty-idle-reap.test.ts
@@ -178,11 +178,11 @@ describe('idle reap of unwatched client PTYs', () => {
expect(spawned[0].killed).toBe(false)
})
- it('never reaps before the threshold — it must not race the renderer 5-minute park', async () => {
+ it('never reaps before the threshold', async () => {
await tmuxManager()
await create(ALICE)
- idle(6 * 60 * 1000) // one minute past TERM_PARK_MS
+ idle(6 * 60 * 1000) // well inside REAP_IDLE_MS
expect(spawned[0].killed).toBe(false)
})
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 2fe0dabd6..88dc890a7 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -807,7 +807,7 @@ export const SHADOW_CMD_TIMEOUT_MS = 5_000
* It exists so a BURST — an agent pushing a multi-line prompt, a run of slash commands — costs one
* `tmux -C` child instead of one per keystroke batch, and nothing more. Ten seconds is past any
* plausible gap inside one such burst and far short of every lifecycle it must not interfere with:
- * the renderer's 5-minute park (`TERM_PARK_MS`), the 10-minute offscreen dispose
+ * the renderer's park (10 min by default), the 10-minute offscreen dispose
* (`offscreen-policy.ts`) and the 10-minute idle reap (`REAP_IDLE_MS`). That ordering is the point
* of picking a number this small: an idle client is a real tmux client on some session, and the
* shorter it lives the smaller the window in which anything has to reason about it at all.
diff --git a/src/core/pty-reap.test.ts b/src/core/pty-reap.test.ts
index 380a16d6e..936948a52 100644
--- a/src/core/pty-reap.test.ts
+++ b/src/core/pty-reap.test.ts
@@ -41,11 +41,10 @@ describe('shouldReap', () => {
expect(shouldReap(candidate({ unwatchedSince: null }), REAP_IDLE_MS * 100)).toBe(false)
})
- it('leaves comfortable room above the renderer park window', () => {
- // TerminalNode parks an unmounted terminal (with its PTY subscription intact) for 5 minutes
- // before detaching it. A parked terminal is still a SUBSCRIBER, so the sweep would skip it
- // anyway — but the threshold must never be close enough for that to be the only reason.
- const TERM_PARK_MS = 5 * 60 * 1000
- expect(REAP_IDLE_MS).toBeGreaterThanOrEqual(2 * TERM_PARK_MS)
+ it('never reaps a parked terminal, however long the park window is', () => {
+ // TerminalNode parks an unmounted terminal WITH its PTY subscription intact, for a
+ // user-configurable window (default 10 min, up to "until quit" — issue #886). No timing margin
+ // can cover that range, so the guarantee is the subscriber test: a parked client is `watched`.
+ expect(shouldReap(candidate({ watched: true, unwatchedSince: 0 }), 365 * 86_400_000)).toBe(false)
})
})
diff --git a/src/core/pty-reap.ts b/src/core/pty-reap.ts
index 2f0984cdf..a17a55838 100644
--- a/src/core/pty-reap.ts
+++ b/src/core/pty-reap.ts
@@ -6,7 +6,7 @@
* ssh children. Every terminal after that spawned black (see pty-devices.ts, which now says so).
*
* The normal release paths — the last subscriber's `pty:kill`, `dropClient` when a window/tab
- * vanishes, the renderer's 5-minute park expiry — already return the pty client for anything the
+ * vanishes, the renderer's park expiry (`settings.terminalParkMinutes`) — already return the pty client for anything the
* user actually closed. This sweep is the SAFETY NET underneath them: every one of those paths is a
* hook that has to be wired (window 'closed', 'render-process-gone', the relay's socket teardown,
* the peer registry's gone-hook), and a hook that is missed leaves a session subscribed to a client
@@ -31,10 +31,10 @@
/**
* How long a session must have been unwatched before its client pty is released.
*
- * Comfortably longer than the renderer's park window (`TERM_PARK_MS`, 5 minutes in
- * renderer/nodes/TerminalNode.tsx), and deliberately not just longer: a parked terminal keeps its
- * subscription, so the sweep already skips it on the `watched` test — the margin is so that the two
- * mechanisms cannot come to depend on each other's timing. Ten minutes with nobody attached is also
+ * Independent of the renderer's park window (`settings.terminalParkMinutes`: default 10 minutes,
+ * user-tunable up to 24 h or "until quit", issue #886). A parked terminal keeps its subscription,
+ * so the sweep skips it on the `watched` test whatever the two durations are — that test, not a
+ * timing margin, is what keeps the reaper off a parked client. Ten minutes with nobody attached is also
* far past any human "I'll be right back": the cost of reaping is one tmux redraw on return, the
* cost of not reaping is a pty device held forever.
*/
diff --git a/src/core/pty-shadow.test.ts b/src/core/pty-shadow.test.ts
index 30c47b617..d03910a35 100644
--- a/src/core/pty-shadow.test.ts
+++ b/src/core/pty-shadow.test.ts
@@ -26,7 +26,7 @@ import {
* Two invariants carry the whole design, and most of what follows asserts one of them:
* - a node never has a live painter AND a live shadow at the same time;
* - a shadow is INVISIBLE to everything that asks "is somebody watching" — the reap sweep (which
- * decides against `platform().clientIds()`), the renderer's 5-minute park and the 10-minute
+ * decides against `platform().clientIds()`), the renderer's park and the 10-minute
* offscreen dispose. It is not a subscriber, not a `Session`, and not a renderer client id.
*/
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 6e925826f..273004a6f 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -516,7 +516,7 @@ interface ParkedTerminal {
remote: boolean
}
const parkedTerminals = new Map<string, ParkedTerminal>()
-// The park window is `settings.terminalParkMinutes` (default 5 = the historical TERM_PARK_MS; 0 =
+// The park window is `settings.terminalParkMinutes` (default 10 — the old TERM_PARK_MS was 5; 0 =
// until the app quits) and the count cap `settings.terminalParkMax` (default PARK_MAX = 20), both
// read at PARK time through their validators (`parkWindowMs` / `parkCap`), so a change applies to
// the next switch-away without touching entries already parked. Issue #886.
diff --git a/src/renderer/terminal/park-budget.test.ts b/src/renderer/terminal/park-budget.test.ts
index 41bc4a668..3a89bd87b 100644
--- a/src/renderer/terminal/park-budget.test.ts
+++ b/src/renderer/terminal/park-budget.test.ts
@@ -271,16 +271,17 @@ describe('planParkEviction — remote parks go last (issue #886)', () => {
})
describe('parkWindowMs', () => {
- it('defaults to the historical 5 minutes', () => {
- expect(parkWindowMs(PARK_MINUTES_DEFAULT)).toBe(5 * 60_000)
- expect(parkWindowMs(undefined)).toBe(5 * 60_000)
+ it('defaults to 10 minutes', () => {
+ expect(PARK_MINUTES_DEFAULT).toBe(10)
+ expect(parkWindowMs(PARK_MINUTES_DEFAULT)).toBe(10 * 60_000)
+ expect(parkWindowMs(undefined)).toBe(10 * 60_000)
})
it('0 = no window at all (null), never Infinity', () => {
// setTimeout clamps a delay above 2^31-1 ms to ~1 ms: an Infinity window would dispose at once.
expect(parkWindowMs(0)).toBeNull()
})
it('a broken hand-edit falls back to the default, never to "keep forever"', () => {
- for (const bad of [NaN, -1, Infinity, '30', null]) expect(parkWindowMs(bad)).toBe(5 * 60_000)
+ for (const bad of [NaN, -1, Infinity, '30', null]) expect(parkWindowMs(bad)).toBe(10 * 60_000)
})
it('clamps to the ceiling, which stays under the setTimeout overflow', () => {
expect(parkWindowMs(1e9)).toBe(PARK_MINUTES_MAX * 60_000)
diff --git a/src/renderer/terminal/park-budget.ts b/src/renderer/terminal/park-budget.ts
index 02de8a4c4..52a38f487 100644
--- a/src/renderer/terminal/park-budget.ts
+++ b/src/renderer/terminal/park-budget.ts
@@ -24,8 +24,10 @@ import type { AgentState } from '@shared/agents/normalize'
export const PARK_MAX = 20
/** Default park window in minutes (`settings.terminalParkMinutes`) — the historical
- * `TERM_PARK_MS` of 5 minutes, unchanged for everyone who never touches the setting. */
-export const PARK_MINUTES_DEFAULT = 5
+ * `TERM_PARK_MS` was 5 minutes; raised to 10 (issue #886) so a short detour through other
+ * projects no longer lands an SSH project on the seconds-long reattach path. The memory it holds
+ * is bounded by the count cap (`PARK_MAX`), not by the window. */
+export const PARK_MINUTES_DEFAULT = 10
/** Settings UI ceilings. The window's `0` means "until the app quits", so the ceiling only
* bounds a typed number; the cap's is a sanity bound for a hand-edited settings.json. */
export const PARK_MINUTES_MAX = 24 * 60
diff --git a/src/shared/types.ts b/src/shared/types.ts
index e23431008..2ad264c9a 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1612,7 +1612,7 @@ export interface Settings {
offscreenTerminalMinutes: number
/** Minutes a terminal stays PARKED after its project is switched away — xterm + PTY client kept
* alive off-DOM so switching back is instant and exact (no reattach). 0 = until the app quits.
- * Default 5. Hand-editable; re-validated at the use site (`parkWindowMs`). Issue #886. */
+ * Default 10. Hand-editable; re-validated at the use site (`parkWindowMs`). Issue #886. */
terminalParkMinutes: number
/** Max parked terminals across all projects before the oldest (local first, then remote) are
* released early. Default 20. Re-validated at the use site (`parkCap`). Issue #886. */
@@ -1890,7 +1890,7 @@ export const DEFAULT_SETTINGS: Settings = {
tmuxScrollback: 50000,
tmuxLeadPaneWidth: 0,
offscreenTerminalMinutes: 10,
- terminalParkMinutes: 5,
+ terminalParkMinutes: 10,
terminalParkMax: 20,
commitAgent: 'claude',
commitAgentCommand: '',