dsh-coding-sidebar 1.0.7 → 1.0.9

package/src/fs-operations.ts

@@ -1,5 +1,6 @@
 /**
- * Workspace-safe file mutations for the sidebar (the upload route today).
+ * Workspace-safe file mutations for the sidebar: the upload route plus the
+ * file tree's rename and delete.
  *
  * Every write is confined to the real session workspace: the upload
  * directory is resolved absolute and its target is checked through existing
@@ -9,14 +10,21 @@
  * to a uniquely named temp sibling
  * and are renamed into place, so a failed, aborted, or oversized upload never
  * leaves a partial file at the target path.
+ *
+ * The tree's rename/delete (below) are link-aware: existence and containment
+ * are verified against the fully resolved target (a symlink pointing outside
+ * the workspace is refused), but the operation itself addresses the lexical
+ * row path — renaming or deleting a symlink row renames/unlinks the LINK,
+ * never its target, matching what the tree row visually names (VS Code
+ * semantics). Containment is always enforced (no fence toggle on this fork).
  */
 import { randomUUID } from 'node:crypto'
 import { once } from 'node:events'
 import { createWriteStream } from 'node:fs'
-import { mkdir, rename, rm, stat } from 'node:fs/promises'
-import { basename, dirname, join } from 'node:path'
+import { access, lstat, mkdir, realpath, rename, rm, stat, unlink } from 'node:fs/promises'
+import { basename, dirname, isAbsolute, join } from 'node:path'
 import type { SidebarHttpRequest } from './context-types.ts'
-import { requireAbsolute } from './fs-tree.ts'
+import { isWithin, requireAbsolute } from './fs-tree.ts'
 import { ensureWorkspacePath, ensureWorkspaceWritePath } from './path-security.ts'
 import { SidebarError } from './wire.ts'
 
@@ -93,3 +101,117 @@ export async function writeWorkspaceUpload(input: WorkspaceUploadInput): Promise
     throw error
   }
 }
+
+/** Resolve a tree-row path against the session workspace (absolute rows pass through). */
+function resolveRowPath(cwd: string, target: string): string {
+  return isAbsolute(target) ? target : join(cwd, target)
+}
+
+/** Resolve one existing entry for a link-aware mutation: the lexical row path
+ * plus its fully resolved real target (containment-checked). Resolution
+ * failures become fs-errors, mirroring path-security's semantics. */
+async function resolveEntry(
+  cwd: string,
+  target: string,
+): Promise<{ absolute: string; real: string; realCwd: string }> {
+  const absolute = requireAbsolute(resolveRowPath(cwd, target))
+  let real: string
+  let realCwd: string
+  try {
+    ;[realCwd, real] = await Promise.all([realpath(cwd), realpath(absolute)])
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot resolve "${target}": ${error instanceof Error ? error.message : String(error)}`, 400)
+  }
+  if (!isWithin(realCwd, real)) {
+    throw new SidebarError('forbidden', `path "${target}" is outside workspace`, 403)
+  }
+  return { absolute, real, realCwd }
+}
+
+/** Whether a path exists (ENOENT → false; other failures propagate). */
+async function pathExists(target: string): Promise<boolean> {
+  try {
+    await access(target)
+    return true
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return false
+    throw error
+  }
+}
+
+/** Inputs of one tree-row rename. */
+export interface WorkspaceRenameInput {
+  /** The session workspace root; the renamed entry must stay inside it. */
+  cwd: string
+  /** Absolute path of the row as the tree displays it (may be a symlink). */
+  path: string
+  /** The new base name (single segment — rename never moves across directories). */
+  name: string
+}
+
+/**
+ * Rename one tree row within its directory: `path` → `<parent>/<name>`.
+ * The new name must be a single path segment (this is rename, not move);
+ * an existing destination is refused (POSIX rename would clobber it
+ * silently); the workspace root itself is never renamable; a symlink row
+ * renames the link, not its target. A no-op rename (same name) succeeds
+ * without touching the filesystem.
+ *
+ * @throws SidebarError with a wire code for shape, containment, existence
+ * and root failures.
+ */
+export async function renameWorkspaceEntry(input: WorkspaceRenameInput): Promise<{ path: string }> {
+  const { cwd, path, name } = input
+  if (name === '' || name === '.' || name === '..' || name.includes('/') || name.includes('\\')) {
+    throw new SidebarError('bad-request', 'name must be a single path segment', 400)
+  }
+  const { absolute, real, realCwd } = await resolveEntry(cwd, path)
+  if (real === realCwd) {
+    throw new SidebarError('fs-error', 'cannot rename the workspace root', 400)
+  }
+  if (basename(absolute) === name) return { path: absolute }
+  const destination = join(dirname(absolute), name)
+  const safeDestination = await ensureWorkspaceWritePath(cwd, destination)
+  if (await pathExists(safeDestination)) {
+    throw new SidebarError('fs-error', `"${name}" already exists`, 409)
+  }
+  try {
+    await rename(absolute, safeDestination)
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot rename "${path}" to "${name}": ${error instanceof Error ? error.message : String(error)}`, 400)
+  }
+  return { path: safeDestination }
+}
+
+/** Inputs of one tree-row delete. */
+export interface WorkspaceRemoveInput {
+  /** The session workspace root; the removed entry must stay inside it. */
+  cwd: string
+  /** Absolute path of the row as the tree displays it (may be a symlink). */
+  path: string
+}
+
+/**
+ * Delete one tree row permanently (there is no trash on the host): files are
+ * unlinked, directories removed recursively, a symlink row unlinks the LINK
+ * only (lstat decides, so a link to a directory does not recurse into its
+ * target). The workspace root itself is never removable.
+ *
+ * @throws SidebarError with a wire code for containment, existence and
+ * root failures.
+ */
+export async function removeWorkspaceEntry(input: WorkspaceRemoveInput): Promise<{ path: string }> {
+  const { cwd, path } = input
+  const { absolute, real, realCwd } = await resolveEntry(cwd, path)
+  if (real === realCwd) {
+    throw new SidebarError('fs-error', 'cannot remove the workspace root', 400)
+  }
+  try {
+    const info = await lstat(absolute)
+    if (info.isDirectory()) await rm(absolute, { recursive: true })
+    else await unlink(absolute)
+  } catch (error) {
+    throw new SidebarError('fs-error', `cannot remove "${path}": ${error instanceof Error ? error.message : String(error)}`, 400)
+  }
+  return { path: absolute }
+}

package/src/git.ts

@@ -9,8 +9,8 @@
  * Commits use the user's git global identity untouched (never sets
  * user.name/user.email).
  */
-import { readdir } from 'node:fs/promises'
-import { join } from 'node:path'
+import { readdir, readFile } from 'node:fs/promises'
+import { isAbsolute, join } from 'node:path'
 import { spawn } from 'node:child_process'
 import { resolve } from 'node:path'
 
@@ -323,11 +323,27 @@ function pathIdentity(path: string): string {
   return process.platform === 'win32' ? absolute.toLowerCase() : absolute
 }
 
+/** Whether the current Git binary supports NUL-framed `worktree list` output.
+ * Git < 2.36 rejects `-z`; cache the capability after the first attempt so
+ * the SCM panel's polling does not repeatedly spawn a command known to fail. */
+let worktreeListSupportsZ: boolean | undefined
+
 /** Raw usable checkout records, shared by inventory and target validation.
  * Prunable records point at missing paths and are deliberately excluded from
  * both the selector and the command-target allowlist. */
 async function listedWorktrees(cwd: string): Promise<GitWorktreeRecord[]> {
-  const raw = await runGit(cwd, ['worktree', 'list', '--porcelain', '-z'])
+  let raw: string
+  if (worktreeListSupportsZ === false) {
+    raw = await runGit(cwd, ['worktree', 'list', '--porcelain'])
+  } else {
+    try {
+      raw = await runGit(cwd, ['worktree', 'list', '--porcelain', '-z'])
+      worktreeListSupportsZ = true
+    } catch {
+      worktreeListSupportsZ = false
+      raw = await runGit(cwd, ['worktree', 'list', '--porcelain'])
+    }
+  }
   return parseWorktreeList(raw).filter(entry => !entry.prunable)
 }
 
@@ -423,6 +439,43 @@ export async function show(cwd: string, rev: string, path: string, selected?: st
   }
 }
 
+/**
+ * Both sides' full file contents for a diff-fold expansion. `path` is
+ * repo-relative. The sides resolve per diff kind: a commit reads
+ * `<hash>^` vs `<hash>`; a staged change reads HEAD vs the index (`:`);
+ * an unstaged change reads HEAD vs the working tree file on disk (a side
+ * that does not exist — untracked, deleted, binary-refused — comes back
+ * null and the client degrades the fold to a static marker).
+ */
+export async function foldContents(
+  cwd: string,
+  path: string,
+  opts: { staged?: boolean; hash?: string } = {},
+  selected?: string,
+): Promise<{ old: string | null; new: string | null }> {
+  const root = await repoRoot(cwd, selected)
+  if (opts.hash !== undefined) {
+    const [old, neu] = await Promise.all([
+      show(root, `${opts.hash}^`, path, selected),
+      show(root, opts.hash, path, selected),
+    ])
+    return { old, new: neu }
+  }
+  if (opts.staged === true) {
+    // `git show :<path>` reads the index (stage 0) — the staged side.
+    const [old, neu] = await Promise.all([
+      show(root, 'HEAD', path, selected),
+      show(root, ':', path, selected),
+    ])
+    return { old, new: neu }
+  }
+  const [old, neu] = await Promise.all([
+    show(root, 'HEAD', path, selected),
+    readFile(isAbsolute(path) ? path : join(root, path), 'utf8').catch(() => null),
+  ])
+  return { old, new: neu }
+}
+
 /** Full patch text of one commit (`git show` with the commit header suppressed).
  *  Merge commits show their diff against the first parent (`-m --first-parent`
  *  is a no-op for regular commits), so a history click always has content. */

package/src/index.ts

@@ -30,7 +30,7 @@ import {
   type SidebarPrefs,
 } from './config.ts'
 import { parentOf, requireAbsolute, listDirectory, rootLabel } from './fs-tree.ts'
-import { writeWorkspaceUpload } from './fs-operations.ts'
+import { removeWorkspaceEntry, renameWorkspaceEntry, writeWorkspaceUpload } from './fs-operations.ts'
 import { ensureWorkspacePath, ensureWorkspaceWritePath } from './path-security.ts'
 import { searchFiles } from './fs-search.ts'
 import { extractFrameAncestors } from './browser-probe.ts'
@@ -40,7 +40,7 @@ import { launchExternal } from './open-external.ts'
 import * as git from './git.ts'
 import { SettingsConflictError, type SettingsNamespace } from '@deepseek-ai/dsh-settings'
 import { defaultShell, ensureSpawnHelper, PtyManager, shellDisplayName } from './pty-manager.ts'
-import { AgentPtyRegistry, clampDims, type AgentTerminalHandle } from './agent-pty.ts'
+import { AgentPtyRegistry, armPtyResizeGate, tryResizePty, type AgentTerminalHandle } from './agent-pty.ts'
 import {
   DSH_NODE_PTY_RANGE,
   depsStatus,
@@ -351,6 +351,26 @@ function buildApi(
       }
       return { ok: true }
     },
+    // The tree row's rename: single-segment name, destination-existence and
+    // workspace-root refusals, link-aware (renames the row, not its target).
+    // fs-operations.ts owns the containment and shape rules.
+    'fs.rename': async (payload) => {
+      const { cwd } = await cwdOf(payload)
+      return renameWorkspaceEntry({
+        cwd,
+        path: requireString(payload, 'path'),
+        name: requireString(payload, 'name'),
+      })
+    },
+    // The tree row's delete (permanent — the host has no trash): recursive
+    // for directories, unlinks a symlink row without touching its target.
+    'fs.remove': async (payload) => {
+      const { cwd } = await cwdOf(payload)
+      return removeWorkspaceEntry({
+        cwd,
+        path: requireString(payload, 'path'),
+      })
+    },
     'git.worktrees': async (payload) => {
       const { cwd } = await gitCwdOf(payload)
       const selected = selectedRepoOf(payload)
@@ -438,6 +458,19 @@ function buildApi(
       const rev = requireString(payload, 'rev')
       return { content: await git.show(cwd, rev, path, repoRoot) }
     },
+    // Diff-fold expansion data: both sides' full file contents so the client
+    // can materialize the hidden context rows a -U3 hunk gap omitted. The
+    // sides resolve per diff kind (commit hash / staged / unstaged) inside
+    // git.foldContents; a missing side is null and the client degrades.
+    'git.fold-contents': async (payload) => {
+      const { cwd } = await gitCwdOf(payload)
+      const repoRoot = selectedRepoOf(payload)
+      const record = payload as { path?: unknown; staged?: unknown; hash?: unknown }
+      const path = await resolveGitPath(cwd, requireString(record, 'path'), repoRoot)
+      const staged = record.staged === true
+      const hash = typeof record.hash === 'string' ? record.hash : undefined
+      return await git.foldContents(cwd, path, { staged, hash }, repoRoot)
+    },
     // Release a terminal immediately. The WebSocket close frame already does
     // this while the socket is open; this route covers the tab-close that
     // happens while the socket is down (reconnect loop), so a closed tab can
@@ -459,6 +492,15 @@ function buildApi(
       agentPtyRegistry?.close(uuid)
       return { ok: true }
     },
+    // The sidebar wait banner's skip button: abort every active
+    // terminal_wait_for on one agent terminal. Idempotent — 0 when nothing
+    // is waiting (a stale banner racing a wait that already resolved).
+    // Degraded mode (node-pty unavailable) has no registry and no waits: an
+    // honest ok.
+    'agent-pty.skip-wait': (payload) => {
+      const uuid = requireString(payload, 'uuid')
+      return { ok: true, skipped: agentPtyRegistry?.skipWait(uuid) ?? 0 }
+    },
     // Terminal dependency status (issue #140): after a WS close 1011 with
     // reason `pty-deps-missing` the client fetches the full repair details
     // here — the close reason itself is capped at 123 bytes, too small for
@@ -1036,6 +1078,38 @@ async function attachAgentList(
   }
 }
 
+/**
+ * The WS close reason for a failed terminal attach. A missing configured
+ * shell gets a SHORT machine-readable marker (`shell-not-found:<name>`,
+ * capped by BYTES — a WS close reason allows at most 123 bytes, which `ws`
+ * validates with `Buffer.byteLength`) that the client maps to a localized,
+ * actionable banner; every other failure keeps the raw message (the
+ * model-side tool errors read it verbatim).
+ */
+export function wsCloseReasonOf(error: unknown): string {
+  if (error instanceof SidebarError && error.code === 'shell-not-found') {
+    const name = truncateUtf8Bytes(shellDisplayName(String(error.meta?.shell ?? '')), 100)
+    return `shell-not-found:${name}`
+  }
+  return error instanceof Error ? error.message : String(error)
+}
+
+/**
+ * Truncate to at most `maxBytes` UTF-8 bytes without splitting a code point.
+ * A character-count `slice` does not bound the WS close reason: `ws` measures
+ * `Buffer.byteLength` against its 123-byte cap, and the resulting throw would
+ * replace the very error the reason describes.
+ */
+function truncateUtf8Bytes(value: string, maxBytes: number): string {
+  if (Buffer.byteLength(value) <= maxBytes) return value
+  let truncated = ''
+  for (const character of value) {
+    if (Buffer.byteLength(truncated + character) > maxBytes) break
+    truncated += character
+  }
+  return truncated
+}
+
 /**
  * Wire one terminal socket to its pty: replay transcript, pump both ways.
  * Two attach modes share the wire protocol:
@@ -1097,6 +1171,9 @@ async function attachTerminal(
     // terminals opened from now on (existing pty handles keep their shell).
     const overrides = shellOverridesOf(getSettings)
     const handle = ptyManager.open(sessionId, tabId, cwd, 80, 24, overrides.shell, overrides.shellArgs)
+    // Windows pre-ready gate for the resize frames this socket may deliver
+    // (see armPtyResizeGate; inert on POSIX).
+    armPtyResizeGate(handle.pty)
     // Replay the transcript, then follow live output.
     if (handle.transcript !== '') ws.send(handle.transcript)
     const onData = (data: string): void => {
@@ -1143,8 +1220,7 @@ async function attachTerminal(
         && control.type === 'resize'
         && typeof control.cols === 'number' && typeof control.rows === 'number'
       ) {
-        const dims = clampDims(control.cols, control.rows)
-        handle.pty.resize(dims.cols, dims.rows)
+        tryResizePty(handle.pty, control.cols, control.rows)
       } else {
         handle.pty.write(text)
       }
@@ -1162,7 +1238,7 @@ async function attachTerminal(
       }
     })
   } catch (error) {
-    ws.close(1011, error instanceof Error ? error.message : String(error))
+    ws.close(1011, wsCloseReasonOf(error))
   }
 }
 
@@ -1212,8 +1288,7 @@ function pumpAgentTerminal(
       && control.type === 'resize'
       && typeof control.cols === 'number' && typeof control.rows === 'number'
     ) {
-      const dims = clampDims(control.cols, control.rows)
-      handle.pty.resize(dims.cols, dims.rows)
+      tryResizePty(handle.pty, control.cols, control.rows)
     } else if (control === null) {
       // Raw text input (a JSON-looking string the pty would have received
       // verbatim is reachable in theory but is exotic for an agent terminal;

package/src/open-external.ts

@@ -28,11 +28,10 @@ export function revealCommand(path: string, platform: NodeJS.Platform = process.
   switch (platform) {
     case 'darwin':
       return { command: 'open', args: ['-R', path] }
-    // `explorer /select,<path>` — the classic "show in folder" incantation.
-    // Passed as separate argv entries (no shell); verify on Windows, with
-    // `cmd /c start "" explorer.exe "/select,<path>"` as the fallback.
+    // Explorer expects `/select,<path>` as one argument. Keep the spawn
+    // shell-free: a command shell would reinterpret valid path characters.
     case 'win32':
-      return { command: 'explorer.exe', args: ['/select,', path] }
+      return { command: 'explorer.exe', args: [`/select,${path}`] }
     default: {
       const parent = parentOf(path)
       return { command: 'xdg-open', args: [parent ?? path] }

package/src/prefs-shared.ts

@@ -16,14 +16,16 @@ export interface SidebarPrefs {
   /** Default panel width as a percent of the window width (20–60). */
   defaultWidthPercent: number
   /**
-   * Whether the sidebar auto-activates (opens the panel) and expands the
-   * Subagent page when the current conversation spawns a new subagent.
+   * Whether the sidebar auto-activates the Subagent page when the current
+   * conversation spawns a new subagent. Wide viewports also open the panel;
+   * narrow viewports prepare the tab without opening the full-screen drawer.
    */
   autoOpenSubagent: boolean
   /**
-   * Whether the sidebar auto-activates (opens the panel) and expands the
-   * Jobs page when a NEW background job appears for the current
-   * conversation (any new job id, not just the first one).
+   * Whether the sidebar auto-activates the Jobs page when a NEW background
+   * job appears for the current conversation (any new job id, not just the
+   * first one). Wide viewports also open the panel; narrow viewports prepare
+   * the tab without opening the full-screen drawer.
    */
   autoOpenJobs: boolean
   /**

package/src/pty-manager.ts

@@ -7,7 +7,7 @@
  * tab is closed or the plugin tears down.
  */
 import { chmodSync, existsSync } from 'node:fs'
-import { dirname, join } from 'node:path'
+import { dirname, join, win32 as win32Path } from 'node:path'
 import { createRequire } from 'node:module'
 import { userInfo } from 'node:os'
 import type { IPty } from 'node-pty'
@@ -153,7 +153,7 @@ export class PtyManager {
       sessionId,
       tabId,
       cwd,
-      pty: this.nodePty.spawn(shell ?? this.shell, shellSpawnArgs(shellArgs ?? this.shellArgs), {
+      pty: this.nodePty.spawn(resolveShellExecutable(shell ?? this.shell), shellSpawnArgs(shellArgs ?? this.shellArgs), {
         name: 'xterm-256color',
         cols: Math.max(2, Math.floor(cols)),
         rows: Math.max(2, Math.floor(rows)),
@@ -270,6 +270,32 @@ export interface ShellResolutionOptions {
   exists?: (path: string) => boolean
 }
 
+/** Inputs for resolving one configured shell into the executable path passed
+ * to node-pty. Injectable so the Windows-only search semantics stay covered
+ * on POSIX CI runners. */
+export interface ShellExecutableResolutionOptions {
+  /** Platform override (defaults to `process.platform`). */
+  platform?: NodeJS.Platform
+  /** Environment override; Windows reads PATH/PATHEXT/SystemRoot plus the
+   * PowerShell well-known-location variables. */
+  env?: NodeJS.ProcessEnv
+  /** File-existence probe override (defaults to `existsSync`). */
+  exists?: (path: string) => boolean
+}
+
+/** Read one Windows environment value case-insensitively. Real
+ * `process.env` has case-insensitive lookup on Windows, but injected objects
+ * and some embedders do not preserve that behavior. */
+function windowsEnv(env: NodeJS.ProcessEnv, name: string): string | undefined {
+  const direct = env[name]
+  if (direct !== undefined) return direct
+  const lowered = name.toLowerCase()
+  for (const [key, value] of Object.entries(env)) {
+    if (key.toLowerCase() === lowered) return value
+  }
+  return undefined
+}
+
 /**
  * Candidate directories that may contain a `pwsh.exe` on Windows: PATH
  * entries first, then the well-known machine/user install locations
@@ -281,7 +307,7 @@ export interface ShellResolutionOptions {
  */
 function windowsPwshCandidateDirs(env: NodeJS.ProcessEnv): string[] {
   const dirs: string[] = []
-  const pathEntries = env.PATH
+  const pathEntries = windowsEnv(env, 'PATH')
   if (pathEntries !== undefined) {
     // The win32 branch always uses the Windows PATH separator; hardcoding it
     // keeps the function testable from POSIX runners without a delimiter
@@ -291,12 +317,12 @@ function windowsPwshCandidateDirs(env: NodeJS.ProcessEnv): string[] {
       if (trimmed !== '') dirs.push(trimmed)
     }
   }
-  for (const programFiles of [env.ProgramW6432, env.ProgramFiles]) {
+  for (const programFiles of [windowsEnv(env, 'ProgramW6432'), windowsEnv(env, 'ProgramFiles')]) {
     if (programFiles === undefined || programFiles.trim() === '') continue
     dirs.push(join(programFiles, 'PowerShell', '7'))
     dirs.push(join(programFiles, 'PowerShell', '7-preview'))
   }
-  const localAppData = env.LOCALAPPDATA
+  const localAppData = windowsEnv(env, 'LOCALAPPDATA')
   if (localAppData !== undefined && localAppData.trim() !== '') {
     dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7'))
     dirs.push(join(localAppData, 'Microsoft', 'PowerShell', '7-preview'))
@@ -306,6 +332,95 @@ function windowsPwshCandidateDirs(env: NodeJS.ProcessEnv): string[] {
   return [...new Set(dirs)]
 }
 
+/**
+ * Resolve the configured shell executable before handing it to node-pty.
+ *
+ * Windows' native backend does not consistently apply the shell's PATHEXT
+ * lookup to a bare value (`pwsh` / `cmd` can fail with the opaque
+ * `File not found:` error), so perform the lookup ourselves: an explicit
+ * path is accepted as-is when it exists (or with a PATHEXT suffix when the
+ * user omitted `.exe`), and a bare name is searched through PATH, System32,
+ * and PowerShell's known install directories.
+ *
+ * POSIX node-pty uses `execvp`, so a bare name would already follow PATH —
+ * but a wrong name made the pty die with a bare
+ * `[process exited with code N]`, so probe like Windows anyway: a path with
+ * a separator must exist; a bare name is searched along PATH (the colon
+ * form is fixed by the platform). A miss is a clear, actionable
+ * `shell-not-found` error instead of a cryptic exit code.
+ *
+ * @param shell - the configured shell (settings page or yaml `config.shell`).
+ * @param options - platform/env/exists injection points for tests.
+ * @returns the executable path passed to node-pty.
+ * @throws {SidebarError} `shell-not-found` when no candidate exists.
+ */
+export function resolveShellExecutable(
+  shell: string,
+  options: ShellExecutableResolutionOptions = {},
+): string {
+  const configured = unquotePath(shell.trim())
+  if (configured === '') return configured
+
+  const platform = options.platform ?? process.platform
+  const env = options.env ?? process.env
+  const exists = options.exists ?? existsSync
+  const notFound = (): SidebarError =>
+    new SidebarError('shell-not-found', `shell executable not found: "${configured}"`, 400, { shell: configured })
+
+  if (platform === 'win32') {
+    const rawPathext = windowsEnv(env, 'PATHEXT')
+    const executableExts = (rawPathext ?? '.COM;.EXE')
+      .split(';')
+      .map(extension => extension.trim())
+      // node-pty ultimately calls CreateProcess; batch files need an
+      // intermediate cmd.exe and therefore are not valid shell executables.
+      .filter(extension => /^\.(?:com|exe)$/i.test(extension))
+    if (executableExts.length === 0) executableExts.push('.EXE', '.COM')
+
+    const hasExtension = win32Path.extname(configured) !== ''
+    const names = hasExtension
+      ? [configured]
+      : executableExts.map(extension => configured + extension.toLowerCase())
+    const hasPath = win32Path.isAbsolute(configured) || /[\\/]/.test(configured)
+    const candidates: string[] = []
+    if (hasPath) {
+      candidates.push(...names)
+    } else {
+      const path = windowsEnv(env, 'PATH')
+      if (path !== undefined) {
+        for (const dir of path.split(';').map(entry => entry.trim()).filter(Boolean)) {
+          for (const name of names) candidates.push(win32Path.join(dir, name))
+        }
+      }
+      const systemRoot = windowsEnv(env, 'SystemRoot')
+      if (systemRoot !== undefined && systemRoot.trim() !== '') {
+        for (const name of names) candidates.push(win32Path.join(systemRoot, 'System32', name))
+      }
+      if (/^pwsh(?:\.exe)?$/i.test(configured)) {
+        for (const dir of windowsPwshCandidateDirs(env)) {
+          candidates.push(win32Path.join(dir, 'pwsh.exe'))
+        }
+      }
+    }
+
+    for (const candidate of [...new Set(candidates)]) {
+      if (exists(candidate)) return candidate
+    }
+    throw notFound()
+  }
+
+  if (configured.includes('/')) {
+    if (!exists(configured)) throw notFound()
+    return configured
+  }
+  const path = env.PATH ?? '/usr/bin:/bin'
+  for (const dir of path.split(':').map(entry => entry.trim()).filter(Boolean)) {
+    const candidate = join(dir, configured)
+    if (exists(candidate)) return candidate
+  }
+  throw notFound()
+}
+
 /**
  * The interactive shell for this platform, resolved like a terminal
  * emulator: an explicitly configured shell (the `shell` config field) wins,
@@ -374,3 +489,59 @@ export function shellSpawnArgs(configured: string[] = []): string[] {
   if (configured.length > 0) return [...configured]
   return process.platform === 'win32' ? [] : ['-l']
 }
+
+/**
+ * Strip ONE pair of surrounding quotes from a configured shell path. Users
+ * paste Windows paths with spaces pre-quoted (`"C:\Program Files\…"`); the
+ * quotes are shell-input syntax, not part of the path. Unpaired quotes and
+ * shorter values stay verbatim.
+ */
+export function unquotePath(value: string): string {
+  if (value.length >= 2) {
+    const first = value[0]
+    const last = value[value.length - 1]
+    if ((first === '"' && last === '"') || (first === "'" && last === "'")) return value.slice(1, -1)
+  }
+  return value
+}
+
+/**
+ * Split a settings-page shell-arguments string into argv with quote-aware
+ * grouping: `'…'` / `"…"` group whitespace, and characters inside quotes are
+ * LITERAL — a backslash is never an escape, so Windows paths survive intact
+ * (`-File "C:\my init\init.ps1"` → three tokens, the last containing spaces).
+ * The price is that an argument containing a literal quote character cannot
+ * be expressed; shell startup arguments never need one. An unclosed quote
+ * folds the remainder into the current token (settings input stays
+ * forgiving); an empty quote pair yields no argument.
+ */
+export function splitShellArgs(input: string): string[] {
+  const args: string[] = []
+  let current = ''
+  let quote: '"' | "'" | null = null
+  let started = false
+  for (const ch of input) {
+    if (quote !== null) {
+      if (ch === quote) quote = null
+      else current += ch
+      continue
+    }
+    if (ch === '"' || ch === "'") {
+      quote = ch
+      started = true
+      continue
+    }
+    if (/\s/.test(ch)) {
+      if (started) {
+        args.push(current)
+        current = ''
+        started = false
+      }
+      continue
+    }
+    current += ch
+    started = true
+  }
+  if (started) args.push(current)
+  return args.filter(arg => arg !== '')
+}