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(windows): scope the fresh-launch probe skip to the session host; one PATH key

reviewe5e920f85096
diff --git a/src/core/exec-path.test.ts b/src/core/exec-path.test.ts
index 39286e7ba..b78065edb 100644
--- a/src/core/exec-path.test.ts
+++ b/src/core/exec-path.test.ts
@@ -5,6 +5,7 @@ import path from 'path'
import { execFileSync } from 'child_process'
import {
directExecutableInvocation,
+ envPathKey,
executableCandidates,
findInPathString,
unquotePathEntry
@@ -256,3 +257,15 @@ describe('findInPathString (real filesystem)', () => {
})
})
})
+
+describe('envPathKey', () => {
+ it('uses the key the environment already has', () => {
+ expect(envPathKey({ PATH: '/bin' })).toBe('PATH')
+ expect(envPathKey({ Path: 'C:\\Windows' })).toBe('Path')
+ expect(envPathKey({ path: 'x' })).toBe('path')
+ })
+ it('prefers an exact PATH and defaults to PATH', () => {
+ expect(envPathKey({ Path: 'a', PATH: 'b' })).toBe('PATH')
+ expect(envPathKey({})).toBe('PATH')
+ })
+})
diff --git a/src/core/exec-path.ts b/src/core/exec-path.ts
index 7c7a2f14a..619272a6d 100644
--- a/src/core/exec-path.ts
+++ b/src/core/exec-path.ts
@@ -274,3 +274,15 @@ export function findExecutableSync(bin: string, fallbacks: string[] = []): strin
}
return null
}
+
+/**
+ * The key an environment object ALREADY holds its search path under. POSIX spells it `PATH`; a
+ * spread of Windows' `process.env` spells it `Path` (the OS is case-insensitive, a plain object is
+ * not). Writing `PATH` onto a Windows copy therefore does not update the path — it adds a second,
+ * case-insensitively equal variable beside it. An exact `PATH` wins when present; no key at all ⇒
+ * `PATH`.
+ */
+export function envPathKey(env: Record<string, string | undefined>): string {
+ if ('PATH' in env) return 'PATH'
+ return Object.keys(env).find((k) => k.toUpperCase() === 'PATH') ?? 'PATH'
+}
diff --git a/src/core/pty-manager.ts b/src/core/pty-manager.ts
index 3ededa0fa..caa9b6f1b 100644
--- a/src/core/pty-manager.ts
+++ b/src/core/pty-manager.ts
@@ -83,7 +83,7 @@ import { effectiveSize, type PtySize } from './pty-size'
import { machOArch, archMismatch } from './macho-arch'
import { writeScrollback, readScrollback, deleteScrollback } from './scrollback-store'
import { claudeConfigDirFor } from './claude-config-dir'
-import { findExecutableSync, findInPathString, resolveShellPath, shellPathNow } from './exec-path'
+import { envPathKey, findExecutableSync, findInPathString, resolveShellPath, shellPathNow } from './exec-path'
import {
AUTH_ENV_STRIP,
accountTmuxEnvArgs,
@@ -2379,6 +2379,7 @@ export class PtyManager {
// setting this on a confident `fresh:false` would spend a round trip per warm node.
...(freshUnverified && !fresh ? { freshUnverified: true as const } : {}),
...(accountFallback ? { accountFallback } : {}),
+ ...(spawned?.sessionHost ? { sessionHost: true as const } : {}),
...(staleCwd ? { staleCwd: true as const } : {}),
...(screen ? { screen } : {})
}
@@ -2903,7 +2904,11 @@ export class PtyManager {
if (options.agentId && hasSharedIdentity(options.agentId as AgentId) && !options.sshRemote) {
// Windows exposes the inherited variable as `Path`; reading only the POSIX spelling
// silently drops the user's PATH and leaves the managed launcher unable to find `codex`.
- env.PATH = `${codexLauncherDir()}${path.delimiter}${env.PATH ?? env.Path ?? ''}`
+ // Prepend onto the key the environment ALREADY uses: a spread of Windows' `process.env` spells
+ // it `Path`, and adding a second `PATH` beside it hands the child two case-insensitively equal
+ // variables — which one it reads is up to the child's runtime.
+ const pathKey = envPathKey(env)
+ env[pathKey] = `${codexLauncherDir()}${path.delimiter}${env[pathKey] ?? ''}`
}
// Managed Claude account: the whole session runs under the account's private config
diff --git a/src/core/windows-session-persistence.test.ts b/src/core/windows-session-persistence.test.ts
index 62d6dcb04..c5742ec64 100644
--- a/src/core/windows-session-persistence.test.ts
+++ b/src/core/windows-session-persistence.test.ts
@@ -13,14 +13,8 @@ describe('Windows persistent-session integration', () => {
expect(manager).toContain("sessionHostSupported() ? 'session-host' : null")
})
- it('preserves the inherited Windows Path when prepending the Codex launcher', () => {
- expect(manager).toContain("env.PATH ?? env.Path ?? ''")
- })
-
- it('delivers a fresh launch without probing a session-host pane first', () => {
- expect(terminal).toContain(
- '(!manual && fresh) || isLaunchShell(await queryPaneWithin(() => api.pty.paneCommand(id), RESTART_EXIT_TIMEOUT_MS))'
- )
- expect(terminal).not.toContain('fresh && !sessionPersistent) || isLaunchShell(')
+ it('prepends the Codex launcher onto the PATH key the environment already uses', () => {
+ expect(manager).toContain('const pathKey = envPathKey(env)')
+ expect(manager).not.toContain("env.PATH ?? env.Path")
})
})
diff --git a/src/renderer/nodes/TerminalNode.tsx b/src/renderer/nodes/TerminalNode.tsx
index 0387a59bc..8529c21c1 100644
--- a/src/renderer/nodes/TerminalNode.tsx
+++ b/src/renderer/nodes/TerminalNode.tsx
@@ -8,7 +8,7 @@ import { installGlassCellBackgrounds, scheduleGlassCellAlpha, setGlassCellAlpha
import { deliverRelayInitialLaunch } from '../terminal/relay-initial-launch'
import { commitLaunch } from '../terminal/launch-attempt'
import { isLaunchShell } from '@shared/agents/pane'
-import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter } from '../terminal/launch-command'
+import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter, trustsFreshShell } from '../terminal/launch-command'
import { Suspense, lazy, useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
import { NODE_MIN_SIZES } from '../lib/nodeSizing'
import {
@@ -3152,6 +3152,7 @@ export function TerminalNode({
cursor,
coAttachMouse,
persistent,
+ sessionHost,
unavailable
}) => {
// The spawn answered: whatever it says, we are no longer waiting on the host.
@@ -3460,7 +3461,7 @@ export function TerminalNode({
io: { write: (d: string) => transport.write(sid, d), onData: (cb: (data: string) => void) => transport.onData(sid, cb) },
// A fresh shell is known at spawn; subsequent/manual deliveries must recheck the pane.
shellReady: async (manual: boolean) =>
- (!manual && fresh) || isLaunchShell(await queryPaneWithin(() => api.pty.paneCommand(id), RESTART_EXIT_TIMEOUT_MS)),
+ trustsFreshShell({ manual, fresh, persistent: sessionPersistent, sessionHost }) || isLaunchShell(await queryPaneWithin(() => api.pty.paneCommand(id), RESTART_EXIT_TIMEOUT_MS)),
killLine: getTerminalKillLine(),
cleanup: (cancel: () => void) => { cleanups.push(cancel) }
}
diff --git a/src/renderer/terminal/launch-command.test.ts b/src/renderer/terminal/launch-command.test.ts
index e3dc98aee..07354bbdc 100644
--- a/src/renderer/terminal/launch-command.test.ts
+++ b/src/renderer/terminal/launch-command.test.ts
@@ -1,7 +1,7 @@
import { commitLaunchAttempt } from './launch-attempt'
import type { PendingLaunch } from '@shared/types'
import { afterEach, describe, expect, it, vi } from 'vitest'
-import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter } from './launch-command'
+import { createLaunchWriter, deliverInitialLaunch, launchCommand, registerLaunchWriter, trustsFreshShell } from './launch-command'
import { KILL_LINE, WINDOWS_KILL_LINE, VERIFY_TIMEOUT_MS, DELIVERY_ATTEMPTS } from './command-delivery'
function fixture(attempted = false, killLine = KILL_LINE) {
@@ -238,3 +238,21 @@ it('a pre-input deferred claim preserves UI intent and the same parked writer ca
expect(await writer('claude brief', false)).toBe('submitted')
expect(write.mock.calls).toEqual([['claude brief'], ['\r']])
})
+
+describe('trustsFreshShell', () => {
+ const auto = { manual: false, fresh: true }
+ it('trusts a fresh plain shell and a fresh session-host shell', () => {
+ expect(trustsFreshShell({ ...auto, persistent: false })).toBe(true)
+ expect(trustsFreshShell({ ...auto, persistent: true, sessionHost: true })).toBe(true)
+ })
+ it('still probes a fresh tmux pane, and an older core that does not say', () => {
+ expect(trustsFreshShell({ ...auto, persistent: true })).toBe(false)
+ expect(trustsFreshShell({ ...auto })).toBe(false)
+ })
+ it('never trusts a manual delivery or a warm attach', () => {
+ expect(trustsFreshShell({ manual: true, fresh: true, persistent: false })).toBe(false)
+ expect(trustsFreshShell({ manual: true, fresh: true, sessionHost: true })).toBe(false)
+ expect(trustsFreshShell({ manual: false, fresh: false, persistent: false })).toBe(false)
+ expect(trustsFreshShell({ manual: false, fresh: false, sessionHost: true })).toBe(false)
+ })
+})
diff --git a/src/renderer/terminal/launch-command.ts b/src/renderer/terminal/launch-command.ts
index e5e99cd20..7ec00d914 100644
--- a/src/renderer/terminal/launch-command.ts
+++ b/src/renderer/terminal/launch-command.ts
@@ -14,6 +14,26 @@ function writersFor(scope: object): Map<string, Writer> {
if (!writers) { writers = new Map(); scopedWriters.set(scope, writers) }
return writers
}
+/**
+ * May an AUTOMATIC launch skip the pane probe and trust that a shell owns the pane? Only for a
+ * fresh session whose probe is either unneeded or unreliable:
+ * - a plain shell (`persistent:false`) — the pty IS the shell we just spawned;
+ * - a session-host session — its probe is a process-tree walk that reads a prompt helper (a `git`
+ * or `starship` child) as "not a shell", which stalled every fresh Windows launch (#916).
+ * A fresh TMUX pane is still probed: tmux answers exactly, and the probe covers the
+ * `new-session -A` race where another client created (and may already be running in) the session.
+ * `persistent` absent = an older core, treated as tmux, like everywhere else.
+ */
+export function trustsFreshShell(opts: {
+ manual: boolean
+ fresh: boolean
+ persistent?: boolean
+ sessionHost?: boolean
+}): boolean {
+ if (opts.manual || !opts.fresh) return false
+ return opts.persistent === false || opts.sessionHost === true
+}
+
export function registerLaunchWriter(id: string, writer: Writer, scope: object = defaultScope): () => void {
const writers = writersFor(scope)
writers.set(id, writer)
diff --git a/src/shared/types.ts b/src/shared/types.ts
index 77a8c18f6..7b3863b0b 100644
--- a/src/shared/types.ts
+++ b/src/shared/types.ts
@@ -285,6 +285,17 @@ export interface PtyCreateResult {
* the historical behavior (persistent), never protect on a guess.
*/
persistent?: boolean
+ /**
+ * This session is owned by the session-host backend (Windows, or POSIX with no tmux), not tmux.
+ * Set only on a SPAWN answer; absent everywhere else (tmux, plain shell, a join, an older core).
+ *
+ * The renderer's launch writer reads it for one decision: a FRESH session-host shell is trusted
+ * without a pane probe, because that backend's probe is a process-tree walk that cannot tell a
+ * shell from its prompt's helpers (a `git`/`starship` child reads as "not a shell") — issue
+ * #916. A fresh tmux pane keeps its probe: tmux's answer is exact, and it still covers the rare
+ * `new-session -A` race where another client created the session first.
+ */
+ sessionHost?: boolean
/**
* REFUSED: this node's session was permanently destroyed by ANOTHER client, so nothing was
* spawned (`sessionId` is empty) — the terminal shows the "closed by <name>" state instead.