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.

chore: clear the leftovers the final review found

review414ee5d1dfcd
diff --git a/CLAUDE.md b/CLAUDE.md
index 0385a60a3..e252d0054 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -10314,7 +10314,12 @@ The invariants, each with its reason:
rewritten to `(null, null)`: a small window must not shrink everyone's terminal. `joinOnly`
asks the STRICT exact-target probe (`has-session -t =nt-<id>`), refuses when it cannot tell, and
reattaches without `-D`. The folded probe reads a tmux error as "exists", which is the safe answer
- for an owner and would let a viewer's `new-session -A` CREATE the session.
+ for an owner and would let a viewer's `new-session -A` CREATE the session. On the Windows session
+ host the join-only viewer rides a read-only `watch-attach` (`SESSION_HOST_WATCH`): no geometry
+ claim and no pause ticket, the host refuses its writes and resizes, it never spawns, and its
+ `Session` is `watcherClient` (never indexed as the node's session). A host without the
+ `watch-attach` feature REFUSES the viewer (`join-only`), never an ordinary attach; details:
+ `docs/windows-session-host.md`.
- **The host key is never silently regenerated** (`host-key.ts`). Its public key IS the team's
address (`hostId`), so a new key orphans every bookmark and sends every teammate back through
first-join approval. Unreadable ⇒ hosting stays off with `host-key-unreadable`; only
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 7e36b0a82..5d3a15110 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -662,7 +662,7 @@ anything else. Board-level fields survive every transform — `pullLinks` is one
pty produces no next chunk, so a resume that waits for one never comes: that froze the phone's
terminal for good after a single >8 MB burst. `host-service.ts` arms a 250 ms sweep while a stream
is paused, then repaints with a snapshot before it resumes — the same drain-sweep pattern as
- `core/ui-sink-registry.ts` (whose self-paced sinks never drop). A new paused path needs the same
+ `core/ui-sink-registry.ts`. A new paused path needs the same
trigger. CLAUDE.md, "Remote access".
- **An SSH project's node runs on the project's host — ask the project, not the node.** Node
diff --git a/docs/windows-session-host.md b/docs/windows-session-host.md
index 8f3ab3b40..99ca37d9a 100644
--- a/docs/windows-session-host.md
+++ b/docs/windows-session-host.md
@@ -894,11 +894,6 @@ via `scripts/patch-node-pty.mjs` is worth doing only if a device shows ≥ ~8 MB
by default (no OSC 7 / 9;9), so a plain Windows shell's relative file links still resolve against
the launch cwd only; agent CLIs and shell integrations that emit OSC 7 / 9;9 / 633 work. No prompt
hook is installed for them (it would rewrite the user's prompt); an opt-in one is a follow-up.
-- **Control typing into a session-host node needs the node open when the viewer joins**: a viewer
- of a node nobody holds rides a read-only `watch-attach` attachment, which has no typing path (the
- host refuses its writes, and keys must not be retyped as a framed `sendKeys` paste). The input
- route is decided at join, so that viewer stays read-only after the owner opens the node, until it
- rejoins.
- **No equivalent of `paneOwner` / `bracketPasteRequested` / a standalone `paneCursor` query** —
see the protocol table's "Not implemented" note. Nothing in this app currently calls these for a
session-host-backed node (they are gated behind `this.tmuxPath` being set), so nothing is
diff --git a/src/core/capture-route.realtmux.test.ts b/src/core/capture-route.realtmux.test.ts
index 63fb4b8e7..2ac91f799 100644
--- a/src/core/capture-route.realtmux.test.ts
+++ b/src/core/capture-route.realtmux.test.ts
@@ -115,7 +115,7 @@ describe('visible capture against a real tmux', () => {
expect(got.screen).not.toMatch(/(^|\n)\d+ \d+\n?$/)
})
- itTmux('only the visible rows — the history above them is never in the keyframe', () => {
+ itTmux('only the visible rows — the history above them is never in the visible capture', () => {
const got = captureVisible('nt-hist')
expect(got.screen).toContain('L10')
expect(got.screen).not.toMatch(/^L1$/m)
@@ -128,7 +128,7 @@ describe('visible capture against a real tmux', () => {
expect(got.screen).toContain('ALT')
expect(got.screen).not.toContain('MAIN')
expect(got.cursor).toEqual({ x: 5, y: 1 })
- // The keyframe's altScreen is the caller's, from the join — the capture reports none.
+ // The visible capture'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/capture-route.test.ts b/src/core/capture-route.test.ts
index e6dd48b1f..9d1867c20 100644
--- a/src/core/capture-route.test.ts
+++ b/src/core/capture-route.test.ts
@@ -71,7 +71,7 @@ describe('localCaptureVisibleArgs', () => {
})
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:
+ // A visible capture'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')
diff --git a/src/core/pty-manager.capture-visible.test.ts b/src/core/pty-manager.capture-visible.test.ts
index 4d9ac575a..4f2aaa203 100644
--- a/src/core/pty-manager.capture-visible.test.ts
+++ b/src/core/pty-manager.capture-visible.test.ts
@@ -129,13 +129,13 @@ describe('captureVisible — local tmux', () => {
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
})
- it('a plain shell (not tmux-backed) gets no keyframe and runs nothing', async () => {
+ it('a plain shell (not tmux-backed) gets no visible capture and runs nothing', async () => {
const m = await manager({ tmuxBacked: false })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(calls).toEqual([])
})
- it('no tmux binary: no keyframe, nothing run', async () => {
+ it('no tmux binary: no visible capture, nothing run', async () => {
const m = await manager({}, null)
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
expect(calls).toEqual([])
@@ -149,7 +149,7 @@ describe('captureVisible — local tmux', () => {
})
describe('captureVisible — never history', () => {
- it("a session-host session's keyframe is the host's visible-only read, with its own altScreen", async () => {
+ it("a session-host session's visible capture is the host's visible-only read, with its own altScreen", async () => {
hostCaptureVisible.mockResolvedValueOnce({ screen: 'vis\n', cursor: { x: 3, y: 0 }, altScreen: false })
const m = await manager({ sessionHost: true })
expect(await m.captureVisible('sess-1')).toEqual({ screen: 'vis\n', cursor: { x: 3, y: 0 }, altScreen: false })
@@ -158,7 +158,7 @@ describe('captureVisible — never history', () => {
expect(calls).toEqual([])
})
- it('a session host without the read (older build) gets NO keyframe — never its scrollback capture', async () => {
+ it('a session host without the read (older build) gets NO visible capture — never its scrollback capture', async () => {
hostCaptureVisible.mockResolvedValueOnce(null)
const m = await manager({ sessionHost: true })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
@@ -166,7 +166,7 @@ describe('captureVisible — never history', () => {
expect(calls).toEqual([])
})
- it('a direct Windows pane gets no keyframe either', async () => {
+ it('a direct Windows pane gets no visible capture either', async () => {
const capture = vi.fn(() => 'HISTORY')
const m = await manager({ nativeWindowsPane: { capture } })
expect(await m.captureVisible('sess-1')).toEqual(unavailableCapture())
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 55bbf7681..ac5f70093 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -99,7 +99,6 @@ import {
type VisibleCapture
} from './capture-route'
import { controlInputPlan, remoteControlInputPlan } from './pane-input'
-import { sanitizePasteText } from './paste-injection'
import {
recordFreshSpawnOwner,
forgetPaneOwner,
@@ -411,24 +410,6 @@ function runTypedScript(args: readonly string[], input: string, env: NodeJS.Proc
})
}
-/** `p`'s answer, or false once `ms` passed (the timer never holds the process). A rejection is false. */
-function settleWithin(p: Promise<boolean>, ms: number): Promise<boolean> {
- return new Promise<boolean>((resolve) => {
- const timer = setTimeout(() => resolve(false), ms)
- timer.unref?.()
- p.then(
- (v) => {
- clearTimeout(timer)
- resolve(v)
- },
- () => {
- clearTimeout(timer)
- resolve(false)
- }
- )
- })
-}
-
// Minimal tmux config so the user's ~/.tmux.conf never interferes. The tmux server
// (under our socket) keeps sessions alive while no client is attached, which is what
// gives us continuity across node remounts and full app restarts.
@@ -3365,7 +3346,6 @@ export class PtyManager {
}
})
-
/** Find the live session registered under a node id (persistKey), if any. */
private sessionByPersistKey(persistKey: string): Session | undefined {
for (const session of this.sessions.values()) {
@@ -5912,7 +5892,7 @@ export class PtyManager {
try {
if (route === 'sessionHost') {
// The host's own emulator answers (a negotiated `captureVisible`); an older host, a gone
- // session or any failure is null ⇒ no keyframe. Never the scrollback `capture` in its place.
+ // session or any failure is null ⇒ no visible capture. Never the scrollback `capture` in its place.
// `altScreen` comes from the emulator's ACTIVE buffer: no tmux client sits between the pane
// and the stream here, so the pane's own buffer IS the stream's.
const cap = await sessionHostCaptureVisible(target)
diff --git a/src/core/pty-session-host-watch.test.ts b/src/core/pty-session-host-watch.test.ts
index ebd73fabf..a83d7a672 100644
--- a/src/core/pty-session-host-watch.test.ts
+++ b/src/core/pty-session-host-watch.test.ts
@@ -175,7 +175,7 @@ describe('PtyManager: join-only creates on the session host', () => {
})
})
-describe('PtyManager: session-host keyframe and pane cwd', () => {
+describe('PtyManager: session-host visible capture and pane cwd', () => {
let manager: import('./pty-manager').PtyManager | undefined
let host: FakePlatform
diff --git a/src/core/session-host-client.ts b/src/core/session-host-client.ts
index 30749dd29..2a6e004d4 100644
--- a/src/core/session-host-client.ts
+++ b/src/core/session-host-client.ts
@@ -1487,11 +1487,6 @@ export class SessionHostClient {
return this.hostFeatures.has(feature)
}
- /** The negotiated answer for `feature` WITHOUT connecting: undefined while there is no connection. */
- connectedFeature(feature: SessionHostFeature): boolean | undefined {
- return this.socket ? this.hostFeatures.has(feature) : undefined
- }
-
private async attachSubscriber(
name: string,
sub: SessionSubscriber,
diff --git a/src/session-host/terminal-emulator.ts b/src/session-host/terminal-emulator.ts
index c4828b0e4..4d16fee87 100644
--- a/src/session-host/terminal-emulator.ts
+++ b/src/session-host/terminal-emulator.ts
@@ -95,12 +95,12 @@ export class TerminalEmulator {
* Built from `SerializeAddon` with `scrollback: 0` rather than by hand, so attributes, wide cells
* and soft wraps encode exactly as the warm-attach replay does. Adjustments:
* - the ALTERNATE buffer: `serialize` always writes the normal buffer first and the alternate one
- * after `CSI ?1049h CSI H`; a keyframe is the active screen only (the viewer switches buffers
+ * after `CSI ?1049h CSI H`; the capture is the active screen only (the viewer switches buffers
* itself from `altScreen` BEFORE painting), so only the part after that marker is kept;
- * - row separators: the addon joins rows with `\r\n`; a keyframe's contract is `\n`.
+ * - row separators: the addon joins rows with `\r\n`; the capture's contract is `\n`.
* The private-mode tail (bracketed paste, application cursor keys, mouse) IS kept, after the last
* row: unlike a tmux client, a viewer joining a session-host stream mid-way never saw the app
- * request them, and a Control viewer's keys encode by them. It is pure DECSET, so the viewer's
+ * request them, and a viewer that types encodes its keys by them. It is pure DECSET, so the viewer's
* reset + clear paint is unaffected. The addon's trailing relative cursor restore is dropped (the
* viewer places the cursor absolutely from `cursor`).
*/
@@ -117,7 +117,7 @@ export class TerminalEmulator {
const body = screenPart
.replace(/\r\n/g, '\n')
// The addon's trailing RELATIVE cursor restore (CUU/CUD/CUF/CUB after the last row) is dropped:
- // the keyframe carries the cursor absolutely, and a relative move followed by the row's `\n`
+ // the capture carries the cursor absolutely, and a relative move followed by the row's `\n`
// could scroll the viewer. A row itself never ends in one (a gap is only emitted before a
// following character), so only the tail matches. The pen-style SGR after it is kept.
// eslint-disable-next-line no-control-regex