feat(sessions): surface tmux sessions the server does not track
A `web_*` tmux session that outlives the process which created it was unreachable
from the UI, permanently. Nothing enumerated tmux — src/session/tmux.ts had
hasSession but no list — so recovery only worked if a client still had the id in
localStorage. list() walks the in-memory table, and so does reapIdle, so such a
session could not be listed, previewed, joined or killed, and never aged out.
On this host that was 69 tmux sessions with 5 clients: 64 unreachable, the oldest
from 26 Jun, one of them still running a Claude Code session with 7 agents.
This is the "catalogue" approach: make them visible and actionable WITHOUT
adopting them. Nothing is attached, because attaching makes tmux resize the window
to the new client's dimensions and SIGWINCH whatever is running inside — doing
that to dozens of live TUIs at startup is exactly the outcome to avoid. Adoption
stays an explicit user action: opening an orphan re-attaches by id through the
existing re-attach path, and it becomes an ordinary live session.
src/session/tmux.ts listSessions() + parseSessionList() (pure, so the filter
rules are unit-testable) and capturePane(), which reads a
session's current screen via `capture-pane -p -e` — no
client, no resize, colour preserved.
src/session/manager.ts listOrphans/captureOrphan/killOrphan/killOrphansIdleSince
src/server.ts GET /orphan-sessions, GET /orphan-sessions/:id/preview,
DELETE /orphan-sessions/:id, DELETE /orphan-sessions
?idleDays=N
public/ a "Recoverable" section under the home grid, reusing the
existing card/thumbnail machinery via orphanAsLive()
Guards, all enforced in the manager so no route can forget one:
- the tmux name must be `web_` + a UUID v4 (SESSION_ID_RE, the same gate the
attach protocol applies). This is what stops a hostile or malformed name from
reaching `tmux -t` — a literal `-t`, or path traversal — and it means a tmux
session the user created for their own work is never enumerated, never
previewed and never offered for deletion.
- an id the table already owns is refused everywhere: killing it via tmux would
end the shell behind a live PTY's back and leave a zombie table entry. Those go
through killById.
- every function is inert when cfg.useTmux is off, so the non-tmux deployment is
byte-for-byte unchanged.
- bulk cleanup skips ATTACHED sessions and requires idleDays >= 1: there is no
"delete everything" form of the route. "This server does not track it" is not
evidence that it is abandoned — a plain `tmux attach` and a second server
process both report as attached.
- reads carry no Origin guard (same threat model as /live-sessions); both DELETEs
do. Preview gets its own rate-limit bucket since each call spawns a process.
Two things the live run exposed and this fixes: previews were loading
sequentially (69 tmux spawns per 5 s refresh) — now once per card, fire-and-forget
— and the grid is capped at 24 cards because each thumbnail is an xterm instance.
The remainder is stated in the UI with the tmux command to reach it, never
silently truncated.
Separate wire type from LiveSessionInfo on purpose: an orphan supports none of the
live-session operations, and the Android/iOS clients decode /live-sessions, so a
variant shape there would break them.
Tests: 2203 unit (+42: parse/filter rules, all four manager guards, tmux-off
inertness) and 8 integration against real tmux — create a throwaway session,
list it, capture it while asserting it stays unattached, reject non-UUID ids,
reject a foreign Origin, kill it, 404 the second time. The integration file never
issues the bulk DELETE: it runs against the host's real tmux server and would end
the developer's own sessions. Verified live against all 69 with none harmed.
This commit is contained in:
@@ -10,6 +10,38 @@
|
||||
*/
|
||||
|
||||
import { execFileSync } from 'node:child_process'
|
||||
import { SESSION_ID_RE } from '../protocol.js'
|
||||
|
||||
/** Upper bound on one `capture-pane` payload. A pane is one screen, so this is
|
||||
* generous; it exists so a wedged tmux can never hand us unbounded output. */
|
||||
const CAPTURE_MAX_BUFFER = 512 * 1024
|
||||
|
||||
/** Tab-separated, machine-readable. tmux reports the two clocks in unix SECONDS. */
|
||||
const LIST_FORMAT = [
|
||||
'#{session_name}',
|
||||
'#{session_created}',
|
||||
'#{session_activity}',
|
||||
'#{session_attached}',
|
||||
'#{window_width}',
|
||||
'#{window_height}',
|
||||
].join('\t')
|
||||
|
||||
/**
|
||||
* One `web_*` tmux session as tmux itself describes it (A).
|
||||
*
|
||||
* `attached` is tmux's own client count, NOT "this server is streaming it": a
|
||||
* session can be attached from a plain terminal, or by a second web-terminal
|
||||
* process. So "we do not track it" and "nobody is using it" are different
|
||||
* questions, and the UI must not conflate them.
|
||||
*/
|
||||
export interface TmuxSessionSummary {
|
||||
readonly id: string
|
||||
readonly createdAtMs: number
|
||||
readonly lastActivityAtMs: number
|
||||
readonly attached: boolean
|
||||
readonly cols: number
|
||||
readonly rows: number
|
||||
}
|
||||
|
||||
/** Is the tmux binary available on PATH? */
|
||||
export function tmuxAvailable(): boolean {
|
||||
@@ -44,3 +76,94 @@ export function killSession(name: string): void {
|
||||
// already gone — fine
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* Parse `tmux list-sessions -F LIST_FORMAT` output. Pure, so the parsing rules are
|
||||
* testable without a tmux binary.
|
||||
*
|
||||
* Two filters, both load-bearing:
|
||||
* - the name must start with `web_`, so we never enumerate (and therefore never
|
||||
* offer to kill) a tmux session the user created for their own work;
|
||||
* - the remainder must be a UUID v4 per SESSION_ID_RE — the same gate the attach
|
||||
* protocol applies (M7). Anything else cannot have been created by this app, and
|
||||
* refusing it here is also what keeps a hostile name from reaching `tmux -t`
|
||||
* (e.g. a literal `-t`, or a name full of path traversal).
|
||||
*/
|
||||
export function parseSessionList(stdout: string): TmuxSessionSummary[] {
|
||||
const rows: TmuxSessionSummary[] = []
|
||||
for (const line of stdout.split('\n')) {
|
||||
if (line === '') continue
|
||||
const parts = line.split('\t')
|
||||
if (parts.length < 6) continue
|
||||
|
||||
const [name, created, activity, attached, width, height] = parts as [
|
||||
string,
|
||||
string,
|
||||
string,
|
||||
string,
|
||||
string,
|
||||
string,
|
||||
]
|
||||
if (!name.startsWith('web_')) continue
|
||||
const id = name.slice('web_'.length)
|
||||
if (!SESSION_ID_RE.test(id)) continue
|
||||
|
||||
const createdSec = Number(created)
|
||||
const activitySec = Number(activity)
|
||||
const cols = Number(width)
|
||||
const rows_ = Number(height)
|
||||
if (
|
||||
!Number.isFinite(createdSec) ||
|
||||
!Number.isFinite(activitySec) ||
|
||||
!Number.isFinite(cols) ||
|
||||
!Number.isFinite(rows_)
|
||||
) {
|
||||
continue
|
||||
}
|
||||
|
||||
rows.push({
|
||||
id,
|
||||
createdAtMs: createdSec * 1000,
|
||||
lastActivityAtMs: activitySec * 1000,
|
||||
attached: attached !== '0' && attached !== '',
|
||||
cols,
|
||||
rows: rows_,
|
||||
})
|
||||
}
|
||||
return rows.sort((a, b) => b.lastActivityAtMs - a.lastActivityAtMs)
|
||||
}
|
||||
|
||||
/** Every `web_*` tmux session on the host, most recently active first. Never
|
||||
* throws; [] when tmux is missing or no tmux server is running. */
|
||||
export function listSessions(): TmuxSessionSummary[] {
|
||||
try {
|
||||
const out = execFileSync('tmux', ['list-sessions', '-F', LIST_FORMAT], {
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'ignore'],
|
||||
maxBuffer: CAPTURE_MAX_BUFFER,
|
||||
})
|
||||
return parseSessionList(out)
|
||||
} catch {
|
||||
return []
|
||||
}
|
||||
}
|
||||
|
||||
/**
|
||||
* The session's CURRENT screen, without attaching. Returns null if it is gone.
|
||||
*
|
||||
* `-p` prints to stdout and `-e` keeps the escape sequences, so the bytes can go
|
||||
* straight into a read-only xterm and keep their colour. Deliberately NOT
|
||||
* `attach-session`: attaching would make tmux resize the window to the new
|
||||
* client's dimensions and SIGWINCH whatever is running inside it.
|
||||
*/
|
||||
export function capturePane(name: string): string | null {
|
||||
try {
|
||||
return execFileSync('tmux', ['capture-pane', '-p', '-e', '-t', name], {
|
||||
encoding: 'utf8',
|
||||
stdio: ['ignore', 'pipe', 'ignore'],
|
||||
maxBuffer: CAPTURE_MAX_BUFFER,
|
||||
})
|
||||
} catch {
|
||||
return null
|
||||
}
|
||||
}
|
||||
|
||||
Reference in New Issue
Block a user