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.

fix(pty): Zellij review round — unknown is warm, names with spaces, `--`, socket length

review941b841107bc
diff --git a/CLAUDE.md b/CLAUDE.md
index 6d898ccf0..f57b0a63e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -1133,9 +1133,26 @@ Rules a refactor must not undo:
that created it, so the painter's `env` (hook env, account scope, gateway/project/custom-agent
values, all merged in `spawnSession`) IS the session env — measured. There is no `-e` list to
maintain and nothing to leak; do not add one.
-- **Only an answer is absence.** `list-sessions -n` exits 1 both for "No active zellij sessions
- found" (absence) and for real failures; only the sentence counts, everything else is `unknown`,
- folded to "exists" like tmux's `probeSaysAbsent`.
+- **Only an answer is absence, and `unknown` is WARM whatever the setting.** `list-sessions -n`
+ exits 1 both for "No active zellij sessions found" (absence) and for real failures; only the
+ sentence counts. When Zellij cannot be asked, the create is never cold — even with tmux selected
+ — or a node still live in Zellij gets its snapshot replayed and its agent resumed a SECOND time
+ in a new tmux shell (the review blocker on #1067: the first version folded to warm only when
+ Zellij was selected). `sessionExists` is the opposite fold: it claims a Zellij session only from
+ a listing that PARSED and shows it live, or every node on the machine "exists" (the phone's End
+ session always said "still running"). Session names may contain SPACES (`my work [Created …]`),
+ and a space-intolerant parser turned ONE personal session into `unknown` for every probe.
+- **`--` before every positional text** (`paste`, `write-chars`): otherwise clap reads a leading
+ `-` as a flag — measured in review, a markdown bullet list was refused and `-h` printed help with
+ exit 0, delivering nothing while the caller then pressed Enter.
+- **Zellij is probed only when it is in play** (`zellijProbeRun`: selected, or `zellij.kdl`
+ exists — written only when a Zellij painter is created), so a tmux user with Zellij merely
+ installed runs exactly the old path: no `list-sessions` per cold create, no `kill-session` per
+ delete.
+- **Socket path length**: Zellij refuses a socket path over `sun_path` (107 bytes on Linux, 103 on
+ macOS). `zellijSocketPath` mirrors its dir rule; a create that would not fit falls back to tmux
+ and Settings says why. A stock Mac with no `XDG_RUNTIME_DIR` computes to ~104 bytes for a real
+ node id — calculated, not run; it is the first device-checklist item.
- **A zombie needs confirming before it is killed.** A shell that exits with no client attached
leaves the session listed with only the hidden plugin pane, and `attach --create` to it exits at
once, so `decideZellij` kills it first. But a session a moment old ALSO has no terminal pane yet
@@ -1151,14 +1168,16 @@ Rules a refactor must not undo:
session is not resurrected by the next `attach --create`.
- **`tmuxBacked` is also true for a Zellij session** (it means "releasing the client destroys
nothing"); every path that would talk to the tmux socket asks `isZellij` first. A delete kills
- `nt-<id>` in Zellij whenever a binary exists (exact-name match, a no-op for a tmux node), because a
- node deleted after a restart has no live session and no record.
+ `nt-<id>` in Zellij whenever Zellij is in play (exact-name match, a no-op for a tmux node), because a
+ node deleted after a restart has no live session and no record (only when Zellij is in play).
- **Explicit degrades, named in Settings** (`ZELLIJ_BACKEND_GAPS`, pinned to the doc by
`zellij-backend.test.ts`): messaging/triggers refused (`paneOwner` null), model switch refused
- (`terminateForeground` false), no session-memory panel / reaper, no pane cwd / stale-cwd banner,
- mobile direct-SSH sees only tmux. The pane foreground command IS provided, from one `ps` read
+ (`terminateForeground` false), the session-memory panel COUNTS Zellij sessions it did not measure
+ (`SessionMemoryReport.unmeasured` — never "No sessions are running here." over live ones) and the
+ reaper ignores them, pasted text rides argv (readable while the call runs), no pane cwd /
+ stale-cwd banner, mobile direct-SSH sees only tmux. The pane foreground command IS provided, from one `ps` read
(server → shell → the shell's `tpgid`); ambiguous (two pane shells) answers null.
-Surfaces: Desktop full; Server Edition the same core (row shown when its host reports Zellij);
+Surfaces: Desktop measured and tested on Linux only (macOS unverified — socket path first); Server Edition the same core (row shown when its host reports Zellij);
Mobile via relay joins the Zellij session (`listNodetermSessions` includes and remembers them),
the phone's direct SSH path does not — iOS follow-up. Real-binary suites: `*.realzellij.test.ts`
(`NODETERM_TEST_ZELLIJ` or `zellij` on PATH; skipped in CI, which has none).
diff --git a/docs/session-backends.md b/docs/session-backends.md
index 10532e9f4..a770ff6c6 100644
--- a/docs/session-backends.md
+++ b/docs/session-backends.md
@@ -68,17 +68,40 @@ foreground-process question and would be the model for that leg.
bash/zsh/fish, as tmux runs its default shell as a login shell.
- **Zombies:** a session listed with no terminal pane is only believed after five pane-less reads
300 ms apart (a just-created session looks the same for a moment); a confirmed zombie is killed
- before the node is created again. Zellij that cannot be asked folds to "exists", the same
- fail-safe direction as tmux.
-- **Delete** kills `nt-<id>` in Zellij (exact name) whenever a Zellij binary exists, so a node
- deleted after a restart, never mounted since, does not leave its session running.
+ before the node is created again.
+- **Unknown is warm, whatever the setting.** When Zellij cannot be asked about a node, the create
+ is never cold — even with tmux selected — because a node that may still run in Zellij must not
+ get its snapshot replayed and its agent `--resume`d a second time in a new tmux shell (found in
+ review: a first version folded to warm only when Zellij was selected). `sessionExists`, by
+ contrast, claims a Zellij session only from a listing that parsed and shows it live.
+- **Session names may contain spaces** (measured: `my work [Created 0s ago]`); the listing parser
+ takes everything before the last ` [Created `. The first version rejected such a line, and one
+ personal session made every probe `unknown`.
+- **`--` before every positional text** (`paste`, `write-chars`): measured, `- item one` was
+ refused as an unknown argument and `-h` printed help with exit 0 while delivering nothing.
+- **Only when Zellij is in play.** Probes of nodes we know nothing about (the per-create
+ `list-sessions`, the per-delete `kill-session`, the relay listing) run only when Zellij is
+ selected or has been used on this machine (our `zellij.kdl` exists; it is written only when a
+ Zellij terminal is created). A tmux user who merely has Zellij installed runs exactly the old
+ path.
+- **Socket path length.** Zellij refuses a socket path over the platform limit ("IPC socket path is
+ too long (108 bytes, max 107)", measured in review on Linux; macOS allows 103). With the setting on and a
+ path that would not fit, new terminals fall back to tmux and the Settings row says why. A stock
+ Mac (no `XDG_RUNTIME_DIR`, 49-character `$TMPDIR`) with a real node id computes to ~104 bytes —
+ over the limit — so on such a Mac the row is expected to say so until `XDG_RUNTIME_DIR` or
+ `ZELLIJ_SOCKET_DIR` is set short. Calculated, not run.
+- **Delete** kills `nt-<id>` in Zellij (exact name) whenever Zellij is in play, so a node deleted
+ after a restart, never mounted since, does not leave its session running.
- **Paste:** refused (not split) above 120,000 UTF-8 bytes.
+- **Session memory:** the sweep reads tmux; the panel reports how many Zellij sessions it did not
+ measure instead of "No sessions are running here.".
### Not available with Zellij (named in the Settings row)
- Agent-to-agent messaging and triggers into Zellij sessions are refused (no pane-owner or paste-mode probe).
- Model switch refuses: it cannot stop the foreground process of a Zellij pane.
-- The session-memory panel and the idle-session reaper do not see Zellij sessions.
+- The session-memory panel counts Zellij sessions but does not measure them; the idle-session reaper does not see them.
+- Pasted text reaches Zellij as a command-line argument (readable by other local users while the call runs); pastes over 120 KB are refused.
- The stale-folder banner and the live pane folder for file links are unavailable.
- SSH projects and Windows keep tmux / the session host.
- nodeterm mobile’s direct SSH attach only finds tmux sessions.
@@ -89,7 +112,8 @@ is SSH-only anyway; `paneCursor` is unknown, so a resync paint leaves the cursor
## Surfaces
-- **Desktop:** full, macOS and Linux.
+- **Desktop:** measured and tested on Linux only. macOS is untested: see the checklist, whose
+ first item decides whether Zellij can be used there at all without a short socket dir.
- **Server Edition:** the same core. The Settings row appears whenever the server host reports
Zellij discovery; sessions are created on the server host.
- **Mobile:** over the relay, the phone's `pty.attach` goes through the same core and joins the
@@ -99,14 +123,18 @@ is SSH-only anyway; `paneCursor` is unknown, so a resync paint leaves the cursor
## Device checklist (not run here)
-1. macOS: `ps -A -o pid=,ppid=,tpgid=,comm=,args=` shape and `tpgid` for the pane shell
+1. **macOS socket path**: on a stock Mac, does the Settings row report the socket path as too long
+ (expected, see above), and with `ZELLIJ_SOCKET_DIR` set short, do Zellij nodes open? Also run
+ the `*.realzellij.test.ts` suites on a Mac (their sandbox falls back to a short `/tmp` socket
+ dir when the sandbox path would not fit).
+2. macOS: `ps -A -o pid=,ppid=,tpgid=,comm=,args=` shape and `tpgid` for the pane shell
(Restart agent / Eco read the pane command from it).
-2. macOS: Zellij from Homebrew is found from a Finder-launched app (`/opt/homebrew/bin`).
-3. A canvas node in Zellij: typing, resize, wheel scroll, drag-copy (OSC 52 pill), Shift+Enter in
+3. macOS: Zellij from Homebrew is found from a Finder-launched app (`/opt/homebrew/bin`).
+4. A canvas node in Zellij: typing, resize, wheel scroll, drag-copy (OSC 52 pill), Shift+Enter in
an agent CLI, Ctrl-g reaching Claude Code.
-4. Attach from an outside terminal with `zellij attach nt-<id>`; both clients see the same pane;
+5. Attach from an outside terminal with `zellij attach nt-<id>`; both clients see the same pane;
the smaller one sizes it.
-5. App restart with a Zellij node: warm reattach, no cold restore, agent still running.
-6. Machine reboot: cold restore replays the scrollback snapshot and resumes the agent in a new
+6. App restart with a Zellij node: warm reattach, no cold restore, agent still running.
+7. Machine reboot: cold restore replays the scrollback snapshot and resumes the agent in a new
Zellij session.
-7. Server Edition on a Linux host with Zellij installed: create, reattach from a second tab.
+8. Server Edition on a Linux host with Zellij installed: create, reattach from a second tab.
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index ffdb864e9..71a9eda9f 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -89,6 +89,9 @@ import {
zellijSendText,
zellijSessionState,
zellijWriteChars,
+ zellijSocketFits,
+ zellijSocketPath,
+ TYPICAL_SESSION_NAME,
loginShellArgs,
parseZellijSessionList,
type ZellijRun,
@@ -1939,7 +1942,7 @@ export class PtyManager {
enabled: this.getSettings().tmuxEnabled,
backend:
// Zellij when it is selected AND found: that is where a new local terminal goes.
- this.zellijSelected() && this.zellijBin()
+ this.zellijSelected() && this.zellijBin() && this.zellijSocketFitsFor(TYPICAL_SESSION_NAME)
? 'zellij'
: this.runtimePlatform !== 'win32' && available
? 'tmux'
@@ -1949,7 +1952,8 @@ export class PtyManager {
? {
zellij: {
available: !!this.zellijBin(),
- selected: normalizeSessionBackend(this.getSettings().sessionBackend) === 'zellij'
+ selected: normalizeSessionBackend(this.getSettings().sessionBackend) === 'zellij',
+ ...(this.zellijSocketFitsFor(TYPICAL_SESSION_NAME) ? {} : { socketTooLong: true })
}
}
: {})
@@ -2093,7 +2097,8 @@ export class PtyManager {
persistentSpawnAvailable(): boolean {
if (this.tmuxPath && this.getSettings().tmuxEnabled) return true
// A machine with no tmux whose setting picks Zellij still creates a persistent session.
- if (this.zellijSelected() && this.zellijBin()) return true
+ if (this.zellijSelected() && this.zellijBin() && this.zellijSocketFitsFor(TYPICAL_SESSION_NAME))
+ return true
return this.hostBackendEligible()
}
@@ -2470,10 +2475,15 @@ export class PtyManager {
? await this.decideZellij(options.persistKey)
: undefined
if (zellijChoice?.use) fresh = zellijChoice.fresh
+ // Zellij could not be asked about this node: it may be live there, so never COLD in tmux.
+ else if (zellijChoice?.state === 'unknown') fresh = false
// A join-only create on Zellij needs a session we SAW live; anything else could create one.
const joinRefused = zellijChoice?.use
? zellijChoice.state !== 'live'
- : fresh || freshUnverified || joinOnlyLocalVerdict === 'unknown'
+ : fresh ||
+ freshUnverified ||
+ joinOnlyLocalVerdict === 'unknown' ||
+ zellijChoice?.state === 'unknown'
if (options.joinOnly && joinRefused)
return { sessionId: '', fresh: false, unavailable: 'join-only' }
// Ensure the login-shell PATH is resolved (prewarmed in init(); usually already settled)
@@ -2944,7 +2954,7 @@ export class PtyManager {
private async decideZellij(
persistKey: string
): Promise<{ use: boolean; fresh: boolean; state: ZellijSessionState }> {
- const run = this.zellijRun()
+ const run = this.zellijProbeRun()
if (!run) {
this.zellijKeys.delete(persistKey)
return { use: false, fresh: true, state: 'absent' }
@@ -2955,25 +2965,75 @@ export class PtyManager {
await zellijKillSession(run, name)
state = 'absent'
}
- const selected = this.zellijSelected()
+ // Creating needs a socket path Zellij will accept; over the limit it refuses with exit 1 and
+ // the node would open as an exited terminal. Fall back to tmux instead (Settings says so).
+ const canCreate = this.zellijSocketFitsFor(name)
+ const selected = this.zellijSelected() && canCreate
const use = state === 'live' || (selected && (state === 'absent' || state === 'unknown'))
if (use) this.zellijKeys.add(persistKey)
else this.zellijKeys.delete(persistKey)
+ // `unknown` is WARM whatever the setting says: a node that may be live in Zellij must never be
+ // cold-started — snapshot replayed, agent `--resume`d a second time — in a new tmux shell.
return { use, fresh: state === 'absent', state }
}
+ /** The Zellij runner for PROBES of nodes we know nothing about. Only when Zellij is in play on this
+ * machine — selected now, or used before (our `zellij.kdl` exists: it is written only when a
+ * Zellij painter is created) — so a tmux user who merely has Zellij installed pays nothing: no
+ * `list-sessions` per cold create, no `kill-session` per delete. */
+ private zellijProbeRun(): ZellijRun | null {
+ if (!this.getSettings().tmuxEnabled) return null
+ if (!this.zellijSelected()) {
+ try {
+ if (!fs.existsSync(path.join(platform().userDataDir, 'zellij.kdl'))) return null
+ } catch {
+ return null
+ }
+ }
+ return this.zellijRun()
+ }
+
+ /** Would Zellij accept the IPC socket for `name` in this environment (zellijSocketPath)? */
+ private zellijSocketFitsFor(name: string): boolean {
+ const env = process.env as Record<string, string | undefined>
+ return zellijSocketFits(
+ zellijSocketPath(env, os.tmpdir(), process.getuid?.() ?? 0, name),
+ this.runtimePlatform
+ )
+ }
+
+ /**
+ * Live `nt-*` Zellij sessions on this machine (null = could not tell / Zellij not in play). The
+ * session-memory panel measures tmux only, so it says how many it could NOT measure rather than
+ * "no sessions are running" over a machine full of Zellij ones.
+ */
+ async zellijSessionCount(): Promise<number | null> {
+ const run = this.zellijProbeRun()
+ if (!run) return 0
+ try {
+ const listing = parseZellijSessionList((await run(['list-sessions', '-n'])).stdout)
+ return listing.ok ? [...listing.live].filter((n) => isSessionName(n)).length : null
+ } catch (error) {
+ const text = error && typeof error === 'object' ? String((error as { stdout?: unknown }).stdout ?? '') : ''
+ return text.includes('No active zellij sessions found') ? 0 : null
+ }
+ }
+
async sessionExists(persistKey: string): Promise<boolean> {
if (this.liveSessionForPersistKey(persistKey)) return true
const probes: Promise<boolean>[] = []
// A Zellij session is a session: the relay host asks this before attaching a phone to a node,
// and a "no" there would CREATE a tmux session beside the running Zellij one. `unknown` folds
- // to "exists" like tmux's probe; a live answer records the id so the attach routes to Zellij.
- const zellij = this.getSettings().tmuxEnabled ? this.zellijRun() : null
+ // Only a PARSED listing that shows the session live answers "yes": an `unknown` here would say
+ // every node on the machine exists (the phone's End session then always reports "still
+ // running", and a relay attach never cold-restores). A live answer records the id so the
+ // attach routes to Zellij.
+ const zellij = this.zellijProbeRun()
if (zellij) {
probes.push(
zellijSessionState(zellij, sessionName(persistKey)).then((state) => {
if (state === 'live') this.zellijKeys.add(persistKey)
- return state === 'live' || state === 'unknown'
+ return state === 'live'
})
)
}
@@ -5294,7 +5354,7 @@ export class PtyManager {
const hostSessions = this.hostBackendEligible()
? sessionHostListSessions().catch(() => [] as string[])
: Promise.resolve([] as string[])
- const zellijRun = this.getSettings().tmuxEnabled ? this.zellijRun() : null
+ const zellijRun = this.zellijProbeRun()
const zellijSessions = zellijRun
? zellijRun(['list-sessions', '-n'])
.then(({ stdout }) => {
@@ -5975,13 +6035,13 @@ export class PtyManager {
}
}
}
- // Zellij too, by exact name, whenever a binary exists — not only for a node this process
+ // Zellij too, by exact name, whenever Zellij is in play here — not only for a node this process
// knows to be Zellij-backed: a delete after an app restart, for a node never mounted since,
// holds no live session and no record, and skipping it would leave the session running with
// nothing on screen. `kill-session` matches exactly and answers "no such session" for a tmux
// node, so the extra call ends nothing it should not. Remote nodes never have one.
- if (remoteEnd.kind === 'none' && this.getSettings().tmuxEnabled) {
- const run = this.zellijRun()
+ if (remoteEnd.kind === 'none') {
+ const run = this.isZellij(persistKey, dying) ? this.zellijRun() : this.zellijProbeRun()
if (run) await zellijKillSession(run, sessionName(persistKey))
}
}
diff --git a/src/core/pty-zellij-fold.test.ts b/src/core/pty-zellij-fold.test.ts
new file mode 100644
index 000000000..7fbe61016
--- /dev/null
+++ b/src/core/pty-zellij-fold.test.ts
@@ -0,0 +1,131 @@
+// PtyManager's Zellij DECISIONS with a stub `zellij` (a shell script), so they run everywhere —
+// no real binary needed. Review of #1067: a probe that answers "unknown" must never let a node be
+// cold-started in tmux (snapshot replayed + agent resumed a SECOND time while it may still run in
+// Zellij); `sessionExists` must not claim every node exists; a tmux user with Zellij merely
+// installed must pay nothing; a socket path Zellij would refuse must fall back to tmux.
+import fs from 'fs'
+import path from 'path'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { initPlatform, resetPlatformForTests } from './platform'
+import { fakePlatform } from './platform-fake'
+import { DEFAULT_SETTINGS, type Settings } from '../shared/types'
+import { testTmpDir } from './test-tmp'
+
+const h = vi.hoisted(() => ({ spawns: [] as Array<{ file: string; args: string[] }> }))
+
+vi.mock('./session-host-backend', async () =>
+ (await import('./__fixtures__/no-session-host')).noSessionHost()
+)
+vi.mock('./pty-devices', async (importOriginal) => ({
+ ...(await importOriginal<typeof import('./pty-devices')>()),
+ readPtyDevices: () => ({ ceiling: 511, inUse: 8 })
+}))
+vi.mock('node-pty', () => ({
+ spawn: (file: string, args: string[]) => {
+ h.spawns.push({ file, args })
+ return {
+ onData: () => ({ dispose() {} }),
+ onExit: () => ({ dispose() {} }),
+ write: () => {},
+ resize: () => {},
+ pause: () => {},
+ resume: () => {},
+ kill: () => {},
+ pid: 4321
+ }
+ }
+}))
+
+let dir: string
+let userData: string
+let log: string
+let savedSockDir: string | undefined
+
+/** A stub zellij: logs its argv, then `list-sessions` answers per `mode`. */
+function stub(mode: 'broken' | 'none'): string {
+ const file = path.join(dir, `zellij-${mode}`)
+ const body =
+ mode === 'broken'
+ ? 'echo "zellij: could not connect" >&2; exit 2'
+ : 'case "$1" in list-sessions) echo "No active zellij sessions found."; exit 1;; esac; exit 0'
+ fs.writeFileSync(file, `#!/bin/sh\necho "$@" >> '${log}'\n${body}\n`, { mode: 0o755 })
+ return file
+}
+const calls = (): string => (fs.existsSync(log) ? fs.readFileSync(log, 'utf8') : '')
+
+async function manager(bin: string, settings: Partial<Settings>, tmuxAbsent = true) {
+ const { PtyManager } = await import('./pty-manager')
+ const m = new PtyManager({ zellijBin: bin })
+ ;(m as unknown as { getSettings: () => Settings }).getSettings = () => ({
+ ...DEFAULT_SETTINGS,
+ ...settings
+ })
+ ;(m as unknown as { tmuxPath: string }).tmuxPath = '/usr/bin/tmux'
+ vi.spyOn(m as unknown as { tmuxSessionExists: () => Promise<boolean> }, 'tmuxSessionExists').mockResolvedValue(
+ !tmuxAbsent
+ )
+ vi.spyOn(m as unknown as { paneCwdStale: () => Promise<boolean> }, 'paneCwdStale').mockResolvedValue(false)
+ return m
+}
+const inPlay = (): void => fs.writeFileSync(path.join(userData, 'zellij.kdl'), '// used before\n')
+
+beforeEach(() => {
+ h.spawns.length = 0
+ dir = testTmpDir('zfold-')
+ userData = path.join(dir, 'ud')
+ fs.mkdirSync(userData)
+ log = path.join(dir, 'calls.log')
+ savedSockDir = process.env.ZELLIJ_SOCKET_DIR
+ process.env.ZELLIJ_SOCKET_DIR = path.join(dir, 's')
+ initPlatform(fakePlatform({ userDataDir: userData }))
+})
+afterEach(() => {
+ if (savedSockDir === undefined) delete process.env.ZELLIJ_SOCKET_DIR
+ else process.env.ZELLIJ_SOCKET_DIR = savedSockDir
+ resetPlatformForTests()
+})
+
+describe('an unknown Zellij answer is WARM whatever the setting (the #1067 blocker)', () => {
+ it('tmux selected, Zellij in play but unreadable: the tmux create is NOT cold', async () => {
+ inPlay()
+ const m = await manager(stub('broken'), { sessionBackend: 'tmux' })
+ const r = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n1' })
+ expect(r.fresh).toBe(false)
+ expect(h.spawns.at(-1)?.file).toBe('/usr/bin/tmux')
+ })
+ it('Zellij selected and unreadable: warm, in Zellij', async () => {
+ const bin = stub('broken')
+ const m = await manager(bin, { sessionBackend: 'zellij' })
+ const r = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n1' })
+ expect(r.fresh).toBe(false)
+ expect(h.spawns.at(-1)?.file).toBe(bin)
+ })
+ it('sessionExists does not claim a node Zellij could not be asked about', async () => {
+ inPlay()
+ const m = await manager(stub('broken'), { sessionBackend: 'tmux' })
+ ;(m as unknown as { tmuxPath: string | null }).tmuxPath = null
+ expect(await m.sessionExists('never-existed')).toBe(false)
+ })
+})
+
+describe('a tmux user with Zellij merely installed pays nothing', () => {
+ it('no zellij.kdl (never used) + tmux selected: zellij is never executed', async () => {
+ const m = await manager(stub('broken'), { sessionBackend: 'tmux' })
+ const r = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n2' })
+ expect(r.fresh).toBe(true)
+ await m.destroySession(null, 'n2')
+ expect(await m.sessionExists('n2')).toBe(false)
+ expect(calls()).toBe('')
+ })
+})
+
+describe('a socket path Zellij would refuse falls back to tmux', () => {
+ it('selected, absent, over the limit: tmux, cold', async () => {
+ process.env.ZELLIJ_SOCKET_DIR = `/${'d'.repeat(120)}`
+ const m = await manager(stub('none'), { sessionBackend: 'zellij' })
+ const r = await m.createHeadless({ cols: 80, rows: 24, persistKey: 'n3' })
+ expect(r.fresh).toBe(true)
+ expect(h.spawns.at(-1)?.file).toBe('/usr/bin/tmux')
+ expect(m.tmuxStatus().zellij).toMatchObject({ selected: true, socketTooLong: true })
+ })
+})
diff --git a/src/core/pty-zellij.realzellij.test.ts b/src/core/pty-zellij.realzellij.test.ts
index 82062f6b7..57246b7e6 100644
--- a/src/core/pty-zellij.realzellij.test.ts
+++ b/src/core/pty-zellij.realzellij.test.ts
@@ -120,11 +120,21 @@ describe.skipIf(!TEST_ZELLIJ)('PtyManager on the Zellij backend (real binary)',
it('after a restart the node reattaches its Zellij session warm — even with the setting back on tmux', async () => {
settings = { ...settings, sessionBackend: 'tmux' }
+ // The review repro: a personal session whose name has a SPACE used to make every listing
+ // unparseable → "unknown" → with tmux selected, fresh:true and a tmux spawn — the agent resumed
+ // a second time beside the live Zellij one.
+ execFileSync(TEST_ZELLIJ as string, ['attach', '--create-background', 'my work'], {
+ env: sb.env,
+ timeout: 10_000,
+ stdio: 'ignore'
+ })
const m = await manager() // a fresh manager = a fresh app run: no memory of the node
expect(await m.sessionExists(node)).toBe(true)
const r = await m.createHeadless({ cols: 100, rows: 30, persistKey: node, cwd: sb.root })
expect(r.fresh).toBe(false)
expect(h.spawns.at(-1)!.file).toBe(TEST_ZELLIJ)
+ // …and a node that never existed is not claimed to exist.
+ expect(await m.sessionExists('never-existed')).toBe(false)
}, 30_000)
it('with tmux selected and no Zellij session, the default path is untouched', async () => {
diff --git a/src/core/session-memory-service.test.ts b/src/core/session-memory-service.test.ts
index 4ede008f9..e479da37a 100644
--- a/src/core/session-memory-service.test.ts
+++ b/src/core/session-memory-service.test.ts
@@ -62,6 +62,26 @@ describe('startSessionMemoryService', () => {
expect(r.ok).toBe(false)
})
+ it('a LOCAL answer carries the count of sessions the tmux sweep could not measure (Zellij)', async () => {
+ startSessionMemoryService({ tmuxBin: () => null, unmeasuredSessions: async () => 2 })
+ expect((await read({ projectId: 'p1' })).unmeasured).toBe(2)
+ })
+
+ it('none unmeasured leaves the report exactly as the sweep made it; a failed count is null', async () => {
+ startSessionMemoryService({ tmuxBin: () => null, unmeasuredSessions: async () => 0 })
+ expect(await read({ projectId: 'p1' })).not.toHaveProperty('unmeasured')
+ resetPlatformForTests()
+ platform = fakePlatform()
+ initPlatform(platform)
+ startSessionMemoryService({
+ tmuxBin: () => null,
+ unmeasuredSessions: async () => {
+ throw new Error('boom')
+ }
+ })
+ expect((await read({ projectId: 'p1' })).unmeasured).toBeNull()
+ })
+
it('routes an SSH project to the remote runner', async () => {
const run = vi.fn(async () => OK_REPLY)
startSessionMemoryService({
diff --git a/src/core/session-memory-service.ts b/src/core/session-memory-service.ts
index 8736764f8..bd1fc5866 100644
--- a/src/core/session-memory-service.ts
+++ b/src/core/session-memory-service.ts
@@ -13,6 +13,8 @@ import { fetchRemoteSessionMemory, type RemoteSessionMemoryRunner } from './sess
export interface SessionMemoryServiceOptions {
/** Lazy tmux resolver (PtyManager resolves after init; null = tmux unavailable). */
tmuxBin: () => string | null
+ /** Live local sessions the tmux sweep cannot measure (Zellij-backed; PtyManager answers). */
+ unmeasuredSessions?: () => Promise<number | null>
/** Host RAM reader, injectable for tests. Defaults to the real `/proc/meminfo` read. */
readMem?: () => MemInfo | null
/**
@@ -110,7 +112,11 @@ export function startSessionMemoryService(opts: SessionMemoryServiceOptions): {
if (!run || !q.projectId) return EMPTY()
return readRemote(q.projectId, run)
}
- return collectSessionMemory({ tmuxBin: opts.tmuxBin, readMem: opts.readMem })
+ const [report, unmeasured] = await Promise.all([
+ collectSessionMemory({ tmuxBin: opts.tmuxBin, readMem: opts.readMem }),
+ opts.unmeasuredSessions ? opts.unmeasuredSessions().catch(() => null) : Promise.resolve(0)
+ ])
+ return unmeasured === 0 ? report : { ...report, unmeasured }
}
)
diff --git a/src/core/zellij-backend.realzellij.test.ts b/src/core/zellij-backend.realzellij.test.ts
index 72f92f855..9a5090e34 100644
--- a/src/core/zellij-backend.realzellij.test.ts
+++ b/src/core/zellij-backend.realzellij.test.ts
@@ -78,6 +78,19 @@ describe.skipIf(!TEST_ZELLIJ)('Zellij backend against the real binary', () => {
expect(await eventually(async () => (await screen('nt-paste1')).includes('^[[200~F1'))).toBe(true)
})
+ it('text that starts with "-" is delivered, not read as a flag', async () => {
+ await create('nt-dash1')
+ await zellijWriteChars(sb.run, 'nt-dash1', 'stty -echo; cat -v\r')
+ expect(await zellijSendText(sb.run, 'nt-dash1', '- item one\n- item two', true)).toBe(true)
+ expect(await zellijWriteChars(sb.run, 'nt-dash1', '-h\r')).toBe(true)
+ expect(
+ await eventually(async () => {
+ const text = await screen('nt-dash1')
+ return text.includes('- item two') && /^-h$/m.test(text)
+ })
+ ).toBe(true)
+ })
+
it('the foreground command is read off the process table', async () => {
await create('nt-fg1')
await zellijWriteChars(sb.run, 'nt-fg1', 'sleep 30\r')
diff --git a/src/core/zellij-backend.test.ts b/src/core/zellij-backend.test.ts
index 8f9b10065..ac617205b 100644
--- a/src/core/zellij-backend.test.ts
+++ b/src/core/zellij-backend.test.ts
@@ -14,6 +14,10 @@ import {
zellijForegroundCommand,
zellijSendText,
zellijSessionState,
+ zellijSocketFits,
+ zellijSocketPath,
+ zellijWriteChars,
+ TYPICAL_SESSION_NAME,
type ZellijRun
} from './zellij-backend'
import fs from 'fs'
@@ -63,6 +67,15 @@ describe('parseZellijSessionList', () => {
expect([...l.live]).toEqual(['nt-a3'])
expect([...l.exited]).toEqual(['nt-b1'])
})
+ it('a session name with SPACES parses (measured) — one personal "my work" must not blind every probe', () => {
+ const l = parseZellijSessionList(
+ 'my work [Created 1s ago] \nold stuff [Created 3d ago] (EXITED - attach to resurrect)\nnt-x [Created 2s ago]\n'
+ )
+ expect(l.ok).toBe(true)
+ if (!l.ok) return
+ expect([...l.live].sort()).toEqual(['my work', 'nt-x'])
+ expect([...l.exited]).toEqual(['old stuff'])
+ })
it('an unparseable line makes the whole listing unknown — never a silent drop', () => {
expect(parseZellijSessionList('nt-a3 [Created 1s ago]\n\u001b[32;1mnt-b\u001b[m [Created').ok).toBe(false)
})
@@ -140,10 +153,18 @@ describe('zellijSendText — one paste, then Enter, never a split', () => {
const run = live()
expect(await zellijSendText(run, 'nt-x', 'a\nb', true)).toBe(true)
expect(run.calls.slice(1)).toEqual([
- ['--session', 'nt-x', 'action', 'paste', '--pane-id', 'terminal_0', 'a\nb'],
+ ['--session', 'nt-x', 'action', 'paste', '--pane-id', 'terminal_0', '--', 'a\nb'],
['--session', 'nt-x', 'action', 'write', '--pane-id', 'terminal_0', '13']
])
})
+ it('text starting with "-" is a positional, never a flag (`--` before it)', async () => {
+ const run = live()
+ expect(await zellijSendText(run, 'nt-x', '- item one\n- item two', false)).toBe(true)
+ expect(run.calls.at(-1)?.slice(-2)).toEqual(['--', '- item one\n- item two'])
+ const w = fakeRun([{ when: isPanes, stdout: LIVE_PANES }, { when: (a) => a.includes('write-chars') }])
+ expect(await zellijWriteChars(w, 'nt-x', '-h')).toBe(true)
+ expect(w.calls.at(-1)?.slice(-2)).toEqual(['--', '-h'])
+ })
it('refuses a paste over the argv ceiling instead of splitting it', async () => {
const run = live()
expect(await zellijSendText(run, 'nt-x', 'x'.repeat(ZELLIJ_PASTE_MAX_BYTES + 1), true)).toBe(false)
@@ -234,3 +255,23 @@ describe('the gap list the Settings row prints is the list the docs state', () =
for (const gap of ZELLIJ_BACKEND_GAPS) expect(doc).toContain(`- ${gap}`)
})
})
+
+describe('zellijSocketPath — Zellij refuses a socket path over the platform limit', () => {
+ it('follows Zellij: ZELLIJ_SOCKET_DIR, else XDG_RUNTIME_DIR/zellij, else <tmp>/zellij-<uid>', () => {
+ expect(zellijSocketPath({ ZELLIJ_SOCKET_DIR: '/s/' }, '/t', 5, 'nt-a')).toBe('/s/contract_version_1/nt-a')
+ expect(zellijSocketPath({ XDG_RUNTIME_DIR: '/run/user/5' }, '/t', 5, 'nt-a')).toBe(
+ '/run/user/5/zellij/contract_version_1/nt-a'
+ )
+ expect(zellijSocketPath({}, '/t/', 5, 'nt-a')).toBe('/t/zellij-5/contract_version_1/nt-a')
+ })
+ it('a stock Mac temp dir plus a real node id does not fit macOS; Linux has 4 more bytes', () => {
+ const macTmp = '/var/folders/zz/zyxvpxvq6csfxvn_n0000000000000/T/' // 49 chars, the stock shape
+ const mac = zellijSocketPath({}, macTmp, 501, TYPICAL_SESSION_NAME)
+ expect(zellijSocketFits(mac, 'darwin')).toBe(false)
+ expect(zellijSocketFits(zellijSocketPath({ XDG_RUNTIME_DIR: '/run/user/1000' }, '/tmp', 1000, TYPICAL_SESSION_NAME), 'linux')).toBe(true)
+ expect(zellijSocketFits('x'.repeat(107), 'linux')).toBe(true)
+ expect(zellijSocketFits('x'.repeat(108), 'linux')).toBe(false)
+ expect(zellijSocketFits('x'.repeat(103), 'darwin')).toBe(true)
+ expect(zellijSocketFits('x'.repeat(104), 'darwin')).toBe(false)
+ })
+})
diff --git a/src/core/zellij-backend.ts b/src/core/zellij-backend.ts
index e9f323a14..e156f81f4 100644
--- a/src/core/zellij-backend.ts
+++ b/src/core/zellij-backend.ts
@@ -120,8 +120,12 @@ export type ZellijListing = { ok: true; live: Set<string>; exited: Set<string> }
/**
* Parse `zellij list-sessions -n`. A line is `<name> [Created <age> ago]`, plus
* ` (EXITED - attach to resurrect)` for a serialized dead session (possible for a session a USER
- * created under our name with their own config — ours never serialize). An unparseable line makes
- * the whole listing unknown rather than silently dropping a session we might be asked about.
+ * created under our name with their own config — ours never serialize). Session names may contain
+ * SPACES (measured: `zellij attach -b 'my work'` lists as `my work [Created 0s ago]`), so the name
+ * is everything before the LAST ` [Created `. A line that still does not parse makes the whole
+ * listing unknown rather than silently dropping a session we might be asked about — which is why a
+ * space-intolerant pattern was a blocker: ONE personal session named "my work" turned every answer
+ * into `unknown`, forever.
*/
export function parseZellijSessionList(stdout: string): ZellijListing {
const live = new Set<string>()
@@ -130,7 +134,7 @@ export function parseZellijSessionList(stdout: string): ZellijListing {
const line = raw.trimEnd()
if (!line) continue
if (line.startsWith(NO_SESSIONS)) continue
- const m = /^(\S+) \[Created [^\]]*\]( \(EXITED\b.*\))?$/.exec(line)
+ const m = /^(.+) \[Created [^\]]*\]( \(EXITED\b.*\))?$/.exec(line)
if (!m) return { ok: false }
;(m[2] ? exited : live).add(m[1])
}
@@ -301,7 +305,9 @@ export async function zellijSendText(
if (!pane) return false
if (text) {
try {
- await run(['--session', name, 'action', 'paste', '--pane-id', pane, text])
+ // `--` before the text: without it clap reads a leading `-` as a flag — measured, a markdown
+ // bullet list was refused and `-h` printed help with exit 0, delivering NOTHING.
+ await run(['--session', name, 'action', 'paste', '--pane-id', pane, '--', text])
} catch {
return false
}
@@ -322,7 +328,7 @@ export async function zellijWriteChars(run: ZellijRun, name: string, data: strin
const pane = await paneOf(run, name)
if (!pane) return false
try {
- await run(['--session', name, 'action', 'write-chars', '--pane-id', pane, data])
+ await run(['--session', name, 'action', 'write-chars', '--pane-id', pane, '--', data])
return true
} catch {
return false
@@ -396,3 +402,39 @@ function errorText(error: unknown): string {
const e = error as { stdout?: unknown; stderr?: unknown; message?: unknown }
return [e.stdout, e.stderr, e.message].filter((v) => typeof v === 'string').join('\n')
}
+
+/**
+ * Where Zellij will put a session's IPC socket, mirroring its own rule: `$ZELLIJ_SOCKET_DIR`, else
+ * `$XDG_RUNTIME_DIR/zellij`, else `<temp dir>/zellij-<uid>`; then `contract_version_1/<name>`.
+ * Zellij REFUSES a path over the platform's `sun_path` limit ("IPC socket path is too long (108
+ * bytes, max 107)", exit 1) — and on a stock Mac (no XDG_RUNTIME_DIR, a 49-character
+ * `/var/folders/…/T/`) a real node id lands at ~104 bytes against macOS's 103. Calculated, not run
+ * on a Mac: see the device checklist in docs/session-backends.md.
+ */
+export function zellijSocketPath(
+ env: Record<string, string | undefined>,
+ tmpDir: string,
+ uid: number,
+ name: string
+): string {
+ const trim = (d: string): string => d.replace(/\/+$/, '')
+ const dir = env.ZELLIJ_SOCKET_DIR
+ ? trim(env.ZELLIJ_SOCKET_DIR)
+ : env.XDG_RUNTIME_DIR
+ ? `${trim(env.XDG_RUNTIME_DIR)}/zellij`
+ : `${trim(tmpDir)}/zellij-${uid}`
+ return `${dir}/contract_version_1/${name}`
+}
+
+/** Largest usable unix-socket path in bytes: `sun_path` is 104 bytes on macOS/BSD, 108 on Linux,
+ * one of which is the terminating NUL. */
+export function socketPathMax(platform: NodeJS.Platform): number {
+ return platform === 'linux' ? 107 : 103
+}
+
+/** A node id as the app mints them (`term-<base36 ms>-<8 hex>`), for "would a typical node fit". */
+export const TYPICAL_SESSION_NAME = 'nt-term-mucjey8s-ca76ca3d'
+
+export function zellijSocketFits(path: string, platform: NodeJS.Platform): boolean {
+ return Buffer.byteLength(path, 'utf8') <= socketPathMax(platform)
+}
diff --git a/src/core/zellij-test-env.ts b/src/core/zellij-test-env.ts
index ac997b6f6..a4e959283 100644
--- a/src/core/zellij-test-env.ts
+++ b/src/core/zellij-test-env.ts
@@ -16,7 +16,7 @@ import { execFile } from 'child_process'
import { promisify } from 'util'
import { findInPathString } from './exec-path'
import { testTmpDir } from './test-tmp'
-import type { ZellijRun } from './zellij-backend'
+import { zellijSocketFits, zellijSocketPath, type ZellijRun } from './zellij-backend'
const run = promisify(execFile)
@@ -29,6 +29,8 @@ export interface ZellijSandbox {
root: string
env: Record<string, string>
run: ZellijRun
+ /** A short socket dir outside the sandbox (only when the sandbox path was too long). */
+ shortSock?: string
}
export function makeZellijSandbox(): ZellijSandbox {
@@ -41,6 +43,13 @@ export function makeZellijSandbox(): ZellijSandbox {
XDG_RUNTIME_DIR: path.join(root, 'r'),
ZELLIJ_SOCKET_DIR: path.join(root, 's')
}
+ // Zellij refuses a socket path over the platform limit (103 bytes on macOS); a Mac's sandboxed
+ // temp dir can be long enough to hit it. Then use a short dir under /tmp, removed at dispose.
+ let shortSock: string | undefined
+ if (!zellijSocketFits(zellijSocketPath(dirs, os.tmpdir(), 0, 'nt-zw-xxxxxxxx-t'), process.platform)) {
+ shortSock = fs.mkdtempSync('/tmp/zj-')
+ dirs.ZELLIJ_SOCKET_DIR = shortSock
+ }
for (const d of Object.values(dirs)) fs.mkdirSync(d, { recursive: true })
const env: Record<string, string> = { ...(process.env as Record<string, string>), ...dirs, SHELL: '/bin/sh' }
for (const k of ['ZELLIJ', 'ZELLIJ_SESSION_NAME', 'ZELLIJ_PANE_ID', 'TMUX', 'TMUX_PANE']) delete env[k]
@@ -52,7 +61,7 @@ export function makeZellijSandbox(): ZellijSandbox {
})
return { stdout, stderr }
}
- return { root, env, run: bound }
+ return { root, env, run: bound, shortSock }
}
/** Kill every session in the sandbox and remove Zellij's temp-dir log. Never throws. */
@@ -62,6 +71,7 @@ export async function disposeZellijSandbox(sb: ZellijSandbox): Promise<void> {
} catch {
// none left — the normal case
}
+ if (sb.shortSock) fs.rmSync(sb.shortSock, { recursive: true, force: true })
const uid = process.getuid?.() ?? 0
try {
fs.rmSync(path.join(os.tmpdir(), `zellij-${uid}`), { recursive: true, force: true })
diff --git a/src/main/index.ts b/src/main/index.ts
index de78adbea..971473e91 100644
--- a/src/main/index.ts
+++ b/src/main/index.ts
@@ -3121,6 +3121,8 @@ app.whenReady().then(async () => {
// run after a project has connected.
startSessionMemoryService({
tmuxBin: () => ptyManager.getTmuxBin(),
+ // Zellij-backed sessions are not in the tmux sweep; the panel says how many it did not measure.
+ unmeasuredSessions: () => ptyManager.zellijSessionCount(),
remote: {
// Identity, not liveness: a DISCONNECTED SSH project is still someone else's machine, and
// `connectedHosts()` alone would answer "local" for it — exactly the window the service's
diff --git a/src/renderer/components/SessionMemoryPanel.tsx b/src/renderer/components/SessionMemoryPanel.tsx
index 7cc73d1d3..20817f360 100644
--- a/src/renderer/components/SessionMemoryPanel.tsx
+++ b/src/renderer/components/SessionMemoryPanel.tsx
@@ -19,6 +19,7 @@ import { useSessionMemory } from '../state/sessionMemory'
import { resolveSessionRows, totalMb } from '../lib/sessionMemoryRows'
import { usageScopeKey } from '../lib/usageScope'
import type { SessionPauseOffer } from '../lib/sessionPause'
+import { unmeasuredNote } from '../lib/sessionMemoryNote'
export interface SessionMemoryPanelProps {
/** Travel to the node behind a row. Canvas passes `travelToNode`, so a CLOSED project's tab is
@@ -77,6 +78,7 @@ export function SessionMemoryPanel({
const [pausing, setPausing] = useState<string | null>(null)
const ok = useSessionMemory((s) => s.ok)
const rows = useSessionMemory((s) => s.rows)
+ const unmeasured = useSessionMemory((s) => s.unmeasured)
const loading = useSessionMemory((s) => s.loading)
const loadedScope = useSessionMemory((s) => s.loadedScope)
const refreshFull = useSessionMemory((s) => s.refreshFull)
@@ -141,6 +143,10 @@ export function SessionMemoryPanel({
body = <div className="sessmem-panel__note">Could not measure sessions on this machine.</div>
} else if (!measured) {
body = <div className="sessmem-panel__note">Measuring…</div>
+ } else if (views.length === 0 && unmeasured !== 0) {
+ // The sweep reads tmux; Zellij-backed sessions are alive and simply not in it. "No sessions"
+ // here would be the ok:true-with-no-rows lie this panel exists to avoid.
+ body = <div className="sessmem-panel__note">{unmeasuredNote(unmeasured)}</div>
} else if (views.length === 0) {
// We looked, and there really is nothing — a different sentence from the two above.
body = <div className="sessmem-panel__note">No sessions are running here.</div>
@@ -227,6 +233,13 @@ export function SessionMemoryPanel({
))}
</ul>
)
+ if (unmeasured !== 0)
+ body = (
+ <>
+ {body}
+ <div className="sessmem-panel__note">{unmeasuredNote(unmeasured)}</div>
+ </>
+ )
}
return (
diff --git a/src/renderer/components/sessionBackendNote.test.ts b/src/renderer/components/sessionBackendNote.test.ts
index 44afb9a23..249350a01 100644
--- a/src/renderer/components/sessionBackendNote.test.ts
+++ b/src/renderer/components/sessionBackendNote.test.ts
@@ -27,3 +27,18 @@ describe('Session backend row — the sentence says what a NEW terminal gets', (
expect(persistenceDescription(status)).toMatch(/^Zellij is available/)
})
})
+
+import { unmeasuredNote } from '../lib/sessionMemoryNote'
+
+describe('review of #1067 — sentences that must not over-claim', () => {
+ it('a socket path Zellij would refuse says new terminals use tmux, and why', () => {
+ expect(sessionBackendNote({ selected: true, available: true, socketTooLong: true })).toMatch(
+ /socket path.*longer than the system allows.*use tmux/
+ )
+ })
+ it('the memory panel names Zellij sessions it did not measure instead of "no sessions"', () => {
+ expect(unmeasuredNote(1)).toBe('1 Zellij session is running here and is not measured (the sweep reads tmux).')
+ expect(unmeasuredNote(3)).toMatch(/^3 Zellij sessions are running here/)
+ expect(unmeasuredNote(null)).toMatch(/could not be counted/)
+ })
+})
diff --git a/src/renderer/components/usePersistenceStatus.ts b/src/renderer/components/usePersistenceStatus.ts
index df719e87d..3ac7c12a2 100644
--- a/src/renderer/components/usePersistenceStatus.ts
+++ b/src/renderer/components/usePersistenceStatus.ts
@@ -6,6 +6,8 @@ import { useSettings } from '../state/settings'
/** Always the local core (the server in a browser), never the selected relay host. */
export function usePersistenceStatus(): TmuxStatus | null | undefined {
const enabled = useSettings((s) => s.settings.tmuxEnabled)
+ // The backend choice changes what the core reports; re-read at once rather than in up to 15 s.
+ const backend = useSettings((s) => s.settings.sessionBackend)
const [status, setStatus] = useState<TmuxStatus | null>()
useEffect(() => {
let cancelled = false
@@ -26,7 +28,7 @@ export function usePersistenceStatus(): TmuxStatus | null | undefined {
clearInterval(timer)
clearTimeout(settled)
}
- }, [enabled])
+ }, [enabled, backend])
return status
}
@@ -45,7 +47,13 @@ export function persistenceDescription(status: TmuxStatus | null | undefined): s
* created, so each branch says what actually happens next — including the fallback when Zellij is
* selected but no binary was found, which must not read as applied.
*/
-export function sessionBackendNote(z: { available: boolean; selected: boolean }): string {
+export function sessionBackendNote(z: {
+ available: boolean
+ selected: boolean
+ socketTooLong?: boolean
+}): string {
+ if (z.selected && z.available && z.socketTooLong)
+ return 'Zellij is selected, but its socket path on this machine is longer than the system allows (Zellij refuses to start there) — new local terminals use tmux. Setting a short XDG_RUNTIME_DIR or ZELLIJ_SOCKET_DIR for the app fixes it.'
if (z.selected && !z.available)
return 'Zellij is selected but was not found on this machine — new local terminals use tmux until it is installed.'
if (z.selected)
diff --git a/src/renderer/lib/sessionMemoryNote.ts b/src/renderer/lib/sessionMemoryNote.ts
new file mode 100644
index 000000000..a2d219bc2
--- /dev/null
+++ b/src/renderer/lib/sessionMemoryNote.ts
@@ -0,0 +1,7 @@
+/** The sentence for live sessions the tmux sweep could not measure (Zellij-backed). */
+export function unmeasuredNote(n: number | null): string {
+ if (n === null) return 'Zellij sessions could not be counted; only tmux sessions are measured here.'
+ return n === 1
+ ? '1 Zellij session is running here and is not measured (the sweep reads tmux).'
+ : `${n} Zellij sessions are running here and are not measured (the sweep reads tmux).`
+}
diff --git a/src/renderer/state/sessionMemory.ts b/src/renderer/state/sessionMemory.ts
index d6c5f8747..cf807a52a 100644
--- a/src/renderer/state/sessionMemory.ts
+++ b/src/renderer/state/sessionMemory.ts
@@ -19,6 +19,8 @@ export const HOST_POLL_MS = 30_000
interface SessionMemoryState {
ok: boolean
rows: SessionMemoryRow[]
+ /** Live sessions the sweep could not measure (Zellij); 0 = none, null = could not tell. */
+ unmeasured: number | null
mem: MemInfo | null
loading: boolean
/** Scope key the current rows belong to; null before the first successful load. */
@@ -59,6 +61,7 @@ const api = (projectId?: string): SessionMemoryApi =>
export const useSessionMemory = create<SessionMemoryState>((set, get) => ({
ok: true,
rows: [],
+ unmeasured: 0,
mem: null,
loading: false,
loadedScope: null,
@@ -83,12 +86,12 @@ export const useSessionMemory = create<SessionMemoryState>((set, get) => ({
if (scopeKey !== activeScope) return
// `ok:false` is carried through untouched: the panel renders "could not measure", never an
// empty session list.
- set({ ok: r.ok, rows: r.rows, mem: r.mem, loadedScope: scopeKey })
+ set({ ok: r.ok, rows: r.rows, mem: r.mem, unmeasured: r.unmeasured ?? 0, loadedScope: scopeKey })
} catch {
// A rejected call (dead WS bridge, no session yet) is the same fact as `ok:false` — the sweep
// could not run. It is emphatically not "there are no sessions".
if (scopeKey !== activeScope) return
- set({ ok: false, rows: [] })
+ set({ ok: false, rows: [], unmeasured: 0 })
} finally {
// A response for a scope we have left owns nothing here — `enterScope` already cleared the
// spinner when it switched.
@@ -130,5 +133,5 @@ function enterScope(scopeKey: string, set: SetState): void {
activeScope = scopeKey
// `loading:false` too: whatever was in flight now belongs to a scope we have left, so its
// `finally` will (correctly) not clear the spinner it set.
- set({ ok: true, rows: [], mem: null, loading: false, loadedScope: null })
+ set({ ok: true, rows: [], unmeasured: 0, mem: null, loading: false, loadedScope: null })
}
diff --git a/src/server/index.ts b/src/server/index.ts
index 4087c1443..1570f5ca1 100644
--- a/src/server/index.ts
+++ b/src/server/index.ts
@@ -864,6 +864,8 @@ export async function startServer(
// complete before the server serves — not that it precedes this line.
startSessionMemoryService({
tmuxBin: () => ptyManager.getTmuxBin(),
+ // Zellij-backed sessions are not in the tmux sweep; the panel says how many it did not measure.
+ unmeasuredSessions: () => ptyManager.zellijSessionCount(),
remote: {
isRemoteProject: sshScopePredicate({ sshProjectIds: () => workspaceStore.sshProjectIds() })
}
diff --git a/src/shared/session-backend.ts b/src/shared/session-backend.ts
index f49b23def..6cc78b03a 100644
--- a/src/shared/session-backend.ts
+++ b/src/shared/session-backend.ts
@@ -30,7 +30,8 @@ export function normalizeSessionBackend(value: unknown): SessionBackend {
export const ZELLIJ_BACKEND_GAPS: readonly string[] = [
'Agent-to-agent messaging and triggers into Zellij sessions are refused (no pane-owner or paste-mode probe).',
'Model switch refuses: it cannot stop the foreground process of a Zellij pane.',
- 'The session-memory panel and the idle-session reaper do not see Zellij sessions.',
+ 'The session-memory panel counts Zellij sessions but does not measure them; the idle-session reaper does not see them.',
+ 'Pasted text reaches Zellij as a command-line argument (readable by other local users while the call runs); pastes over 120 KB are refused.',
'The stale-folder banner and the live pane folder for file links are unavailable.',
'SSH projects and Windows keep tmux / the session host.',
'nodeterm mobile’s direct SSH attach only finds tmux sessions.'
diff --git a/src/shared/types.ts b/src/shared/types.ts
index b5533e708..6b05eb067 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -1180,7 +1180,7 @@ export interface TmuxStatus {
* Windows (no Zellij backend there). `selected && !available` means new terminals fall back to
* tmux — the Settings row says so rather than letting the choice look applied.
*/
- zellij?: { available: boolean; selected: boolean }
+ zellij?: { available: boolean; selected: boolean; socketTooLong?: boolean }
/** One-shot install command for a terminal node; null = no known installer (text-only banner). */
installCommand: string | null
/** Button caption for installCommand (e.g. "Install Homebrew + tmux" when brew must come first). */
@@ -2877,6 +2877,12 @@ export interface SessionMemoryReport {
ok: boolean
rows: SessionMemoryRow[]
mem: MemInfo | null
+ /**
+ * Live nodeterm sessions on this machine that the sweep could NOT measure — today, Zellij-backed
+ * ones (the sweep reads tmux). Absent/0 = none. `null` = could not tell. Local scope only. The
+ * panel must never say "no sessions are running" while this is non-zero or unknown.
+ */
+ unmeasured?: number | null
}
/**