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(watch-link): the visible capture reports no alternate-screen flag

review1e041577c830
diff --git a/src/core/pty-manager.capture-visible.test.ts b/src/core/pty-manager.capture-visible.test.ts
index ad89165df..c957b5105 100644
--- a/src/core/pty-manager.capture-visible.test.ts
+++ b/src/core/pty-manager.capture-visible.test.ts
@@ -79,7 +79,7 @@ beforeEach(() => {
calls.length = 0
ssh.path = '/usr/bin/ssh'
hostCapture.mockClear()
- script.answer = () => ({ stdout: 'hello\n\n2 0 0\n' })
+ script.answer = () => ({ stdout: 'hello\n\n2 0\n' })
// `findSsh` memoizes per module; a fresh module per test lets one test say "no ssh here".
vi.resetModules()
initPlatform(fakePlatform())
@@ -91,8 +91,7 @@ describe('captureVisible — local tmux', () => {
const m = await manager({})
expect(await m.captureVisible('sess-1')).toEqual({
screen: 'hello\n\n',
- cursor: { x: 2, y: 0 },
- altScreen: false
+ cursor: { x: 2, y: 0 }
})
expect(calls).toEqual([
{
@@ -166,8 +165,7 @@ describe('captureVisible — SSH project', () => {
const m = await manager({ sshRemote: SSH_REMOTE })
expect(await m.captureVisible('sess-1')).toEqual({
screen: 'hello\n\n',
- cursor: { x: 2, y: 0 },
- altScreen: false
+ cursor: { x: 2, y: 0 }
})
expect(calls).toHaveLength(1)
expect(calls[0].file).toBe('/usr/bin/ssh')
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 76905afb0..65c62a904 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -4417,11 +4417,12 @@ export class PtyManager {
}
/**
- * A live link's keyframe: the VISIBLE screen of a session, with the cursor and the alternate-screen
- * flag read in the same tmux invocation — never history. Which backends get one, the exact target
- * and the parse are `watch-link/capture-route.ts`. The session host (scrollback only), a direct
- * Windows pane and a plain shell get `unavailableCapture()`, as does any failure — a dead
- * ControlMaster, tmux's own "can't find session" for an exact-target miss.
+ * A live link's keyframe: the VISIBLE screen of a session, with the cursor read in the same tmux
+ * invocation — never history. The keyframe's `altScreen` is the caller's, from the join (a
+ * tmux-backed client paints on the alternate screen; see `VisibleCapture`). Which backends get
+ * one, the exact target and the parse are `watch-link/capture-route.ts`. The session host
+ * (scrollback only), a direct Windows pane and a plain shell get `unavailableCapture()`, as does
+ * any failure — a dead ControlMaster, tmux's own "can't find session" for an exact-target miss.
*/
async captureVisible(sessionId: string): Promise<VisibleCapture> {
const session = this.sessions.get(sessionId)
diff --git a/src/core/remote-ssh/capture-visible.realsh.test.ts b/src/core/remote-ssh/capture-visible.realsh.test.ts
index fe342cd7e..9d352a9d9 100644
--- a/src/core/remote-ssh/capture-visible.realsh.test.ts
+++ b/src/core/remote-ssh/capture-visible.realsh.test.ts
@@ -124,7 +124,7 @@ describe('remoteCaptureVisibleArgs (real /bin/sh)', () => {
const got = parseVisibleCapture(stdout)
expect(got.screen).toContain('REMOTE-12')
expect(got.cursor).toEqual({ x: 0, y: 1 })
- expect(got.altScreen).toBe(false)
+ expect(got.screen).not.toMatch(/(^|\n)\d+ \d+\n?$/)
})
it.skipIf(!REAL_TMUX)('an exact-target miss prints nothing and fails — never the longer-named session', () => {
diff --git a/src/core/watch-link/capture-route.realtmux.test.ts b/src/core/watch-link/capture-route.realtmux.test.ts
index 799779aff..f23a24ecd 100644
--- a/src/core/watch-link/capture-route.realtmux.test.ts
+++ b/src/core/watch-link/capture-route.realtmux.test.ts
@@ -1,4 +1,4 @@
-// A LIVE LINK'S KEYFRAME, CAPTURED FROM A REAL TMUX (R10 + R17).
+// A LIVE LINK'S KEYFRAME, CAPTURED FROM A REAL TMUX (R10 + R17, amended by R18: no alt-screen flag).
//
// What is measured here is a property of tmux, not of our code, so it cannot be unit-tested:
// - the one invocation `capture-pane … ; display-message …` really does print the visible screen
@@ -111,9 +111,8 @@ describe('visible capture against a real tmux', () => {
const got = captureVisible('nt-x-12')
expect(got.screen).toContain('SCREEN-OF-12')
expect(got.cursor).toEqual({ x: 0, y: 1 })
- expect(got.altScreen).toBe(false)
// The cursor line is not left in the screen.
- expect(got.screen).not.toMatch(/\d+ \d+ [01]\n?$/)
+ expect(got.screen).not.toMatch(/(^|\n)\d+ \d+\n?$/)
})
itTmux('only the visible rows — the history above them is never in the keyframe', () => {
@@ -124,11 +123,12 @@ describe('visible capture against a real tmux', () => {
expect(got.screen.split('\n').filter(Boolean)).toEqual(['L8', 'L9', 'L10'])
})
- itTmux('reads the alternate screen and its flag', () => {
+ itTmux('a pane on the alternate screen: the grid on screen, with its cursor — and no flag (R18)', () => {
const got = captureVisible('nt-alt')
expect(got.screen).toContain('ALT')
expect(got.screen).not.toContain('MAIN')
- expect(got.altScreen).toBe(true)
expect(got.cursor).toEqual({ x: 5, y: 1 })
+ // The keyframe's altScreen is the caller's, from the join — the capture reports none.
+ expect(Object.keys(got).sort()).toEqual(['cursor', 'screen'])
})
})
diff --git a/src/core/watch-link/capture-route.test.ts b/src/core/watch-link/capture-route.test.ts
index 2c710eea7..1ee480437 100644
--- a/src/core/watch-link/capture-route.test.ts
+++ b/src/core/watch-link/capture-route.test.ts
@@ -64,76 +64,66 @@ describe('localCaptureVisibleArgs', () => {
expect(args.filter((a) => a.includes('nt-abc'))).toEqual(['=nt-abc:', '=nt-abc:'])
})
- it('asks for the cursor and the alternate-screen flag', () => {
- expect(VISIBLE_CAPTURE_FORMAT).toBe('#{cursor_x} #{cursor_y} #{alternate_on}')
+ it('asks for the cursor and nothing else — no alternate-screen flag (R18)', () => {
+ // A keyframe's altScreen comes from the JOIN (tmux-backed client => true), never the capture:
+ // the pane's `#{alternate_on}` describes a different screen than the tmux client's stream.
+ expect(VISIBLE_CAPTURE_FORMAT).toBe('#{cursor_x} #{cursor_y}')
+ expect(args.join(' ')).not.toContain('alternate_on')
})
})
describe('parseVisibleCapture', () => {
it('splits the trailing cursor line off a real tmux 3.4 reply', () => {
// Measured: a 20x4 pane after 10 lines of output — only the visible rows, then the cursor line.
- expect(parseVisibleCapture('L8\nL9\nL10\n\n0 3 0\n')).toEqual({
+ expect(parseVisibleCapture('L8\nL9\nL10\n\n0 3\n')).toEqual({
screen: 'L8\nL9\nL10\n\n',
- cursor: { x: 0, y: 3 },
- altScreen: false
+ cursor: { x: 0, y: 3 }
})
})
- it('reads the alternate-screen flag', () => {
- expect(parseVisibleCapture('\n ALT\n\n\n5 1 1\n')).toEqual({
- screen: '\n ALT\n\n\n',
- cursor: { x: 5, y: 1 },
- altScreen: true
- })
+ it('carries no alternate-screen field at all', () => {
+ expect(Object.keys(parseVisibleCapture('\n ALT\n\n\n5 1\n')).sort()).toEqual(['cursor', 'screen'])
+ expect(Object.keys(parseVisibleCapture('no cursor line\n')).sort()).toEqual(['cursor', 'screen'])
})
it('keeps the screen byte-identical to what capture-pane printed on its own', () => {
const screen = '\u001b[1mbold\u001b[0m\nplain\n'
- expect(parseVisibleCapture(`${screen}12 1 0\n`).screen).toBe(screen)
+ expect(parseVisibleCapture(`${screen}12 1\n`).screen).toBe(screen)
})
it('an empty screen is an empty string, not the cursor line', () => {
- expect(parseVisibleCapture('0 0 0\n')).toEqual({
- screen: '',
- cursor: { x: 0, y: 0 },
- altScreen: false
- })
+ expect(parseVisibleCapture('0 0\n')).toEqual({ screen: '', cursor: { x: 0, y: 0 } })
})
it('a screen whose own last line looks like a cursor line keeps that line', () => {
// Only the LAST line is the cursor; a numeric-ish row above it is screen text.
- expect(parseVisibleCapture('10 20 1\n3 4 0\n')).toEqual({
- screen: '10 20 1\n',
- cursor: { x: 3, y: 4 },
- altScreen: false
- })
+ expect(parseVisibleCapture('10 20\n3 4\n')).toEqual({ screen: '10 20\n', cursor: { x: 3, y: 4 } })
})
it('reads CRLF line endings', () => {
- expect(parseVisibleCapture('a\r\nb\r\n7 1 1\r\n')).toEqual({
+ expect(parseVisibleCapture('a\r\nb\r\n7 1\r\n')).toEqual({
screen: 'a\r\nb\r\n',
- cursor: { x: 7, y: 1 },
- altScreen: true
+ cursor: { x: 7, y: 1 }
})
})
it('without a cursor line the whole output is the screen and the cursor is unknown', () => {
- for (const out of ['a\nb\n', 'a\nb', 'a\n3 4 5\n', 'a\n3 4\n', 'a\nx 1 0\n', 'a\n \n', '']) {
- expect(parseVisibleCapture(out)).toEqual({ screen: out, cursor: null, altScreen: null })
+ for (const out of ['a\nb\n', 'a\nb', 'a\n3 4 5\n', 'a\n3 4 0\n', 'a\n3\n', 'a\nx 1\n', 'a\n \n', '']) {
+ expect(parseVisibleCapture(out)).toEqual({ screen: out, cursor: null })
}
})
it('does not accept a padded or signed cursor line', () => {
- for (const line of [' 1 2 0', '1 2 0 ', '-1 2 0', '1 2 0', '1\t2\t0']) {
+ for (const line of [' 1 2', '1 2 ', '-1 2', '1 2', '1\t2']) {
const out = `s\n${line}\n`
- expect(parseVisibleCapture(out)).toEqual({ screen: out, cursor: null, altScreen: null })
+ expect(parseVisibleCapture(out)).toEqual({ screen: out, cursor: null })
}
})
})
describe('unavailableCapture', () => {
it('is an empty screen with nothing known', () => {
- expect(unavailableCapture()).toEqual({ screen: '', cursor: null, altScreen: null })
+ expect(unavailableCapture()).toEqual({ screen: '', cursor: null })
})
it('is a fresh object each time (a caller may mutate what it was handed)', () => {
diff --git a/src/core/watch-link/capture-route.ts b/src/core/watch-link/capture-route.ts
index 916dcdf7e..dd2b223a3 100644
--- a/src/core/watch-link/capture-route.ts
+++ b/src/core/watch-link/capture-route.ts
@@ -7,9 +7,9 @@
// scrollback and a direct Windows pane has no visible-only read, so both get NO keyframe (the viewer
// starts from the live stream) rather than history. A plain shell has no tmux to ask.
//
-// The screen, the cursor and the alternate-screen flag are read in ONE tmux invocation
-// (`capture-pane … ; display-message …`), so all three describe the same instant: a cursor read in a
-// second round trip could describe a screen that has since scrolled.
+// The screen and the cursor are read in ONE tmux invocation (`capture-pane … ; display-message …`), so
+// both describe the same instant: a cursor read in a second round trip could describe a screen that has
+// since scrolled.
//
// The target is EXACT (`exactPaneTarget`). Node ids end in a counter, so `nt-x-1` is a prefix of
// `nt-x-12`, and tmux resolves a bare target by fnmatch then PREFIX on a miss: a bare target would
@@ -24,19 +24,28 @@
// and the combined `capture-pane -t =nt-x-1: ; display-message …` stops at the failed capture: exit 1,
// nothing on stdout. So an exact miss is a failed command, which the caller reads as unavailable.
+/**
+ * What a visible-only capture returns: the screen and the cursor, read at one instant.
+ *
+ * Deliberately NO alternate-screen flag (controller ruling R18). A keyframe's `altScreen` is decided
+ * by the CALLER from the join (a tmux-backed client ⇒ `true`), not from the capture: a watcher
+ * co-attaches to the tmux CLIENT's output, and tmux paints its client on the alternate screen
+ * whatever the pane's application does, so every `tmux`/`ssh`-route join means `altScreen: true`.
+ * The pane's own `#{alternate_on}` (vim, a TUI) describes a different screen — a shell pane reads 0
+ * while the stream is on the alternate screen — and mapping it into the keyframe would scroll every
+ * tmux redraw into the viewer's history.
+ */
export interface VisibleCapture {
/** The visible screen with SGR, byte-identical to what `capture-pane -p -e` prints on its own
* (one `\n`-terminated line per row); '' when there is none. Never history. */
screen: string
/** The pane's cursor at capture time, 0-based (`#{cursor_x}`, `#{cursor_y}`); null when unread. */
cursor: { x: number; y: number } | null
- /** Whether the pane's application is on the alternate screen (`#{alternate_on}`); null when unread. */
- altScreen: boolean | null
}
/** A session with no visible-only capture, or one that failed: an empty screen, nothing known. */
export function unavailableCapture(): VisibleCapture {
- return { screen: '', cursor: null, altScreen: null }
+ return { screen: '', cursor: null }
}
export function visibleCaptureRoute(
@@ -48,8 +57,8 @@ export function visibleCaptureRoute(
return tmuxAvailable && s.tmuxBacked ? 'tmux' : 'none'
}
-/** The tmux format read beside the screen: cursor column, cursor row, alternate screen (0/1). */
-export const VISIBLE_CAPTURE_FORMAT = '#{cursor_x} #{cursor_y} #{alternate_on}'
+/** The tmux format read beside the screen: cursor column and cursor row, 0-based. */
+export const VISIBLE_CAPTURE_FORMAT = '#{cursor_x} #{cursor_y}'
/** "Exactly this session, its active pane" — the only spelling that is exact AND resolves for a
* target-pane command (see the measurement at the top of this file). */
@@ -81,7 +90,7 @@ export function localCaptureVisibleArgs(socket: string, sessionName: string): st
]
}
-const CURSOR_LINE = /^(\d+) (\d+) ([01])$/
+const CURSOR_LINE = /^(\d+) (\d+)$/
/**
* Split the combined reply: the LAST line is the cursor line when it has exactly the format's shape,
@@ -93,10 +102,9 @@ export function parseVisibleCapture(stdout: string): VisibleCapture {
const cut = body.lastIndexOf('\n')
const last = cut === -1 ? body : body.slice(cut + 1)
const m = CURSOR_LINE.exec(last)
- if (!m) return { screen: stdout, cursor: null, altScreen: null }
+ if (!m) return { screen: stdout, cursor: null }
return {
screen: cut === -1 ? '' : body.slice(0, cut + 1),
- cursor: { x: Number(m[1]), y: Number(m[2]) },
- altScreen: m[3] === '1'
+ cursor: { x: Number(m[1]), y: Number(m[2]) }
}
}