Skip to content

The ultimate harness for coding agents and beyond. All your agents. All your machines. One command center. Start with code, then follow your curiosity and build across disciplines: CAD, circuits, robots, games and music.

107 KB
Raw Blame
import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, symlinkSync, utimesSync, writeFileSync } from 'node:fs'
import { execFileSync } from 'node:child_process'
import { constants, tmpdir } from 'node:os'
import { join } from 'node:path'
import { env } from '../config/env.js'
import {
  AGENT_NAME_RE,
  BYPASS_PERMISSION_FLAGS,
  FIRST_PROMPT_ARGS,
  FirstPromptUnsupportedError,
  LAUNCH_RESUME_FLAG,
  NAMED_AGENT_ARGS,
  NamedAgentUnsupportedError,
  HARNESS_WORDMARK_LINES,
  MAX_FIRST_PROMPT_CHARS,
  PERMISSION_MODES,
  terminalHintLines,
  buildEngineCommandArgv,
  buildEngineLaunchArgv,
  shellAgentArgv,
  buildTerminalLaunchArgv,
  interactiveEngineShell,
  isPosixShell,
  commandAvailableInInteractiveShell,
  commandSupportsFlagInInteractiveShell,
  dropPermissionFlagIfUnsupported,
  permissionFlagToVerify,
  permissionModeFlags,
  refusePermissionFlagIfUnsupported,
  engineUpdateCommand,
  unsupportedLaunchModelFlag,
  resetCommandFlagSupportCache,
  engineFallbackPrelude,
  ENGINE_INPUT_DRAIN_SH,
  firstPromptArgs,
  gridPanePrelude,
  harnessNodePrelude,
  noDevtoolsPrelude,
  namedAgentArgs,
  supportsFirstPrompt,
  supportsNamedAgent,
  unreadableCwdGuard,
  ZSH_GUARD_ZSHENV,
  zshNewUserGuard,
  engineLaunchEnv,
  buildEngineInstallationArgv,
} from './engineLaunch.js'
import { isHeldStartCommand, NATIVE_LAUNCH_MARKER } from './nativePaneHold.js'
import { WindowsStartupUnverified } from './windows/engineStart.js'
import { defaultWindowsShell } from './windows/shell.js'
import type { NativeLaunch } from '../engines/nativeLaunch.js'
import { ENGINES, type AgentEngine } from '../engines/types.js'
import { engineBin } from './engineBin.js'
import { engineInstallRecipe, type EngineInstallRecipe } from './engineInstall.js'
import { MIN_OPEN_FILES, RAISE_OPEN_FILES_SH } from './openFiles.js'
import { browserPrelude } from './browserShim.js'
import { DSH_SESSION_ENV, harnessEnvToClear } from '../dsh/launch.js'
import { launchScriptOf } from '../testing/launchScript.js'
import { buildGridEngineLaunch, gridConflictingEnvToClear } from './gridLaunch.js'
import { TmuxBackend } from './tmuxBackend.js'
import { resumeSessionId } from './processTable.js'

// What these cases test is what real shells make of the scripts this module writes: sh, dash, bash and
// zsh run each one, and nothing here could be faked without faking the subject. Each run carries its own
// bound (a probe's 5 s in engineLaunch.ts, the 10 s of the runs below), and vitest's 5 s default sat under
// them: a slow shell timed the case out instead of answering as its bound says. Under a full run at load
// 36 (six workers), 11 cases here hit it, one of them on a single probe; under 8 busy and 8 spawning loops
// the four-probe case took 4.9 s. Room for four probes at their limit, and a margin.
vi.setConfig({ testTimeout: 30_000 })

// The launch script names the `grid` the daemon resolved, and a developer's own HARNESS_GRID_BIN
// would resolve to THEIR grid. The suite's runtime dir is already a throwaway (vitest.setup.ts), so
// with the override gone every case below resolves to the bare name.
const developersOwnGridBin = process.env.HARNESS_GRID_BIN
beforeEach(() => { delete process.env.HARNESS_GRID_BIN })
afterAll(() => { if (developersOwnGridBin !== undefined) process.env.HARNESS_GRID_BIN = developersOwnGridBin })

// A zsh user as most are: with a startup file of their own, so the zsh launches below are the plain
// ones. vitest.setup.ts points ZDOTDIR at an empty folder, which is the new-user case `zshNewUserGuard`
// handles; that case has its own tests at the end of this file.
const suiteZdotdir = process.env.ZDOTDIR
const zshUserHome = mkdtempSync(join(tmpdir(), 'launch-zdotdir-'))
writeFileSync(join(zshUserHome, '.zshrc'), '')
beforeEach(() => { process.env.ZDOTDIR = zshUserHome })
afterAll(() => {
  if (suiteZdotdir === undefined) delete process.env.ZDOTDIR
  else process.env.ZDOTDIR = suiteZdotdir
  rmSync(zshUserHome, { recursive: true, force: true })
})

/** The prelude every case below gets by default: no managed grid on this machine, so PATH is left
 *  alone and only grid's update check is turned off. */
const GRID_PRELUDE = gridPanePrelude('grid')
const NO_DEVTOOLS = noDevtoolsPrelude()
// Every pane's BROWSER is the daemon's script (lib/browserShim.ts): a page a program opens can go to the phone typing there.
const BROWSER = browserPrelude()
/** The engine-in-a-shell wrapper every launch carries, for the shell each case names — see
 *  `engineFallbackPrelude`. `null` tmux: the suite must not depend on what this machine has. */
const FALLBACK = (engine: AgentEngine, shell: string) => engineFallbackPrelude(engine, shell, null)
const NO_TMUX = null
/** The screen Harness runs Codex on (facets/launch.ts `ScreenContract`), ahead of the launch's extra arguments. */
const CODEX_SCREEN = ['-c', 'tui.fullscreen_transcript=false']
/** How a plain launch ends: job control on, the binary its command names run at the script's top
 *  level, where a stop is resumed, then the exit handling (`engineRunScript`). */
const RUN = 'if [ -n "${ZSH_VERSION:-}" ]; then setopt monitor 2>/dev/null || :; else set -m 2>/dev/null || :; fi\n'
  + 'trap : INT QUIT\n'
  + 'harness_engine_bin=$1\nshift\nharness_status=0\n"$harness_engine_bin" "$@" || harness_status=$?\nharness_resume\nharness_after'
/** The engine's own run, in every launch. */
const RUN_LINE = '"$harness_engine_bin" "$@" || harness_status=$?'
/** What a POSIX login shell's `-c` is: its launch script, sourced from a one-time file. */
const SOURCED = /^\. '.+\.sh'$/

describe('buildEngineLaunchArgv', () => {
  it('runs the exact native command in the current shell environment after a missing-agent install', () => {
    const dir = mkdtempSync(join(tmpdir(),'hn-shell-install-'))
    const binary = join(dir,'fake-agent'), source = join(dir,'template'), marker = join(dir,'installed')
    try {
      writeFileSync(source,'#!/bin/sh\nprintf "%s\\n" "$@"\nexit 17\n',{mode:0o700})
      const recipe: EngineInstallRecipe = {command:`cp '${source}' '${binary}'; touch '${marker}'`,source:'test fixture',executable:{names:[binary]}}
      const argv = shellAgentArgv(binary,['task; $(literal)','--model','mine'],recipe,'/missing-node')
      try { execFileSync(argv[0],argv.slice(1),{encoding:'utf8'}); throw new Error('expected native exit 17') }
      catch (error) {
        expect((error as {status:number}).status).toBe(17)
        expect(String((error as {stdout:string}).stdout)).toContain('task; $(literal)\n--model\nmine\n')
      }
      expect(existsSync(marker)).toBe(true)
      rmSync(marker)
      try { execFileSync(argv[0],argv.slice(1),{encoding:'utf8'}) } catch (error) { expect((error as {status:number}).status).toBe(17) }
      expect(existsSync(marker)).toBe(false)
    } finally { rmSync(dir,{recursive:true,force:true}) }
  })
  it.each(['claude', 'terminal'] as const)('clears inherited harness context before a plain %s session runs', (engine) => {
    const argv = buildEngineLaunchArgv(engine, { clearEnv: harnessEnvToClear() }, '/bin/sh', undefined, undefined, NO_TMUX)
    const probe = 'for name in HARNESS_DSH HARNESS_DSH_DIR HARNESS_WORKSPACE HARNESS_CONTEXT_FILE HARNESS_SKILLS_DIR HARNESS_PRIVATE_GRID; do printenv "$name" && exit 9; done; printf "%s" "$KEEP_ME"'
    const args = engine === 'terminal' ? ['harness-terminal', ''] : ['harness-engine']
    const out = execFileSync(argv[0], [argv[1], argv[2], ...args, '/bin/sh', '-c', probe], {
      encoding: 'utf8',
      env: { ...process.env, ...Object.fromEntries(DSH_SESSION_ENV.map((name) => [name, 'stale-harness'])), KEEP_ME: 'retained' },
      stdio: ['ignore', 'pipe', 'pipe'],
    })
    expect(out).toBe('retained')
  })

  it('wraps zsh in its interactive login form and execs the resolved binary', () => {
    const argv = buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, undefined, NO_TMUX)
    expect(argv).toEqual([
      '/usr/bin/env', 'DISABLE_AUTO_UPDATE=true', '/bin/zsh', '-lic', expect.stringMatching(SOURCED), 'harness-engine', engineBin('claude'),
    ])
    expect(launchScriptOf(argv)).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/zsh')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}${RUN}`)
  })

  it('uses Ubuntu bash interactive startup files without making it a login shell', () => {
    const argv = buildEngineLaunchArgv('claude', {}, '/bin/bash', undefined, undefined, NO_TMUX)
    expect(argv).toEqual(['/bin/bash', '-ic', expect.stringMatching(SOURCED), 'harness-engine', engineBin('claude')])
    expect(launchScriptOf(argv)).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/bash')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}${RUN}`)
  })

  it('hands the shell its script in a one-time file that removes itself, private to this user', () => {
    // On the command line the script was most of a launch, and tmux takes the launch as one command of
    // at most 16KiB: see `launchFile`.
    const argv = buildEngineLaunchArgv('claude', { cwd: '/work' }, '/bin/zsh', undefined, undefined, NO_TMUX)
    const file = SOURCED.test(argv[4]) ? argv[4].slice(3, -1) : ''
    expect(file.startsWith(join(env.ADAPTER_DATA_DIR, 'launch'))).toBe(true)
    expect(statSync(file).mode & 0o777).toBe(0o600)
    expect(readFileSync(file, 'utf8').startsWith(`rm -f -- '${file}'\n`)).toBe(true)
    const run = execFileSync('/bin/sh', ['-c', argv[4], 'harness-engine', '/', '/bin/sh', '-c', 'printf "%s|" "$PWD" "$@"', 'engine', 'a b'], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
    expect(run).toBe('/|a b|')
    expect(existsSync(file)).toBe(false)
  })

  it('runs Codex under dash, where there is one, when no login shell resolves', () => {
    // macOS's /bin/sh is bash 3.2, which never sees the engine stop: the engine would wait, stopped, for
    // good (STOP_PROOF_FUNCTIONS). dash resumes it like the rest.
    const argv = buildEngineLaunchArgv('codex', {}, 'relative-shell', undefined, undefined, NO_TMUX)
    expect(argv.slice(0, 2)).toEqual([existsSync('/bin/dash') ? '/bin/dash' : '/bin/sh', '-c'])
    expect(argv[2]).toMatch(SOURCED)
    expect(launchScriptOf(argv)).toContain('harness_resume')
  })

  it('sweeps a launch file that never ran once it is an hour old, and only then', () => {
    const directory = join(env.ADAPTER_DATA_DIR, 'launch')
    mkdirSync(directory, { recursive: true })
    const stale = join(directory, 'never-ran.sh')
    const fresh = join(directory, 'about-to-run.sh')
    writeFileSync(stale, 'exit 0\n')
    writeFileSync(fresh, 'exit 0\n')
    utimesSync(stale, new Date(Date.now() - 2 * 3600_000), new Date(Date.now() - 2 * 3600_000))
    buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, undefined, NO_TMUX)
    expect(existsSync(stale)).toBe(false)
    expect(existsSync(fresh)).toBe(true)
  })

  it('puts the script on the command line when there is no data folder to write it in', () => {
    const saved = env.ADAPTER_DATA_DIR
    env.ADAPTER_DATA_DIR = '/dev/null/no-data-folder'
    try {
      const argv = buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, undefined, NO_TMUX)
      // The browser script is the one the data folder would hold: read under the folder the launch was built in.
      expect(argv[4]).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/zsh')}${GRID_PRELUDE}${browserPrelude()}${NO_DEVTOOLS}${RUN}`)
    } finally { env.ADAPTER_DATA_DIR = saved }
  })

  it('keeps the longest launch, as the whole tmux command, well inside what tmux takes', async () => {
    // `tmux new-session` takes a launch as one command, its environment and options included, and
    // refuses one over 16KiB with "command too long" (measured, tmux 3.7c). The longest a launch gets:
    // Codex or Claude Code on a grid with its web tools, looked for first, taking over a terminal's
    // conversation, resuming it, with Harness's Node, and the longest first prompt in three-byte
    // characters. With the script on the command line Codex's came to 17.9KB; it goes in a file now.
    const dir = mkdtempSync(join(tmpdir(), 'harness-launch-size-'))
    const savedPath = process.env.PATH
    try {
      writeFileSync(join(dir, 'tmux'), `#!/bin/sh\nfor arg in "$@"; do printf '%s\\000' "$arg"; done > "$(mktemp ${dir}/call.XXXXXX)"\nprintf '%%42\\n'\n`, { mode: 0o755 })
      process.env.PATH = `${dir}:${savedPath}`
      const grid = { networkId: 'grid-3378218621364f16', networkName: 'autonomous.ai', baseUrl: 'https://grid.autonomous.ai/grid-3378218621364f16/relay/v1', apiKey: 'gridkey-abc123', model: 'GLM-4.7-Flash', mcpUrl: 'https://api-grid.autonomous.ai/v1/grid/web-mcp/' }
      for (const engine of ['claude', 'codex'] as const) {
        for (const call of readdirSync(dir).filter((name) => name.startsWith('call.'))) rmSync(join(dir, call))
        const built = buildGridEngineLaunch(engine, grid, { hermesSystemManaged: false })
        if (!built.ok) throw new Error(built.detail)
        const cwd = '/Users/demo/projects/a project with a fairly long name'
        const command = buildEngineLaunchArgv(engine, {
          cwd, firstPrompt: '漢'.repeat(MAX_FIRST_PROMPT_CHARS), resumeSessionId: '019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b',
          installIfMissing: engineInstallRecipe(engine), waitForPid: { pid: 4242, name: 'Codex' }, bypassPermission: true,
          extraArgs: built.launch.args, clearEnv: gridConflictingEnvToClear(built.launch), harnessNode: true,
        }, '/bin/zsh', '/opt/harness/runtime/node/bin/node', '/opt/harness/runtime/grid/grid', '/opt/homebrew/bin/tmux')
        const created = await new TmuxBackend(undefined, () => 'daemon-0000').create({ cwd, label: `harness-${engine}-1791200000000`, env: built.launch.env, command })
        expect(created.state, engine).toBe('succeeded')
        const sizes = readdirSync(dir).filter((name) => name.startsWith('call.')).map((name) => statSync(join(dir, name)).size)
        expect(Math.max(...sizes), engine).toBeLessThan(15 * 1024)
      }
    } finally {
      process.env.PATH = savedPath
      rmSync(dir, { recursive: true, force: true })
    }
  })

  it('enters the workspace only after interactive startup has completed', () => {
    const argv = buildEngineLaunchArgv('claude', { cwd: '/work/project' }, '/bin/zsh', undefined, undefined, NO_TMUX)
    expect(argv).toEqual([
      '/usr/bin/env', 'DISABLE_AUTO_UPDATE=true', '/bin/zsh', '-lic', expect.stringMatching(SOURCED),
      'harness-engine', '/work/project', engineBin('claude'),
    ])
    expect(launchScriptOf(argv)).toBe(
      `${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/zsh')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; exit 1; fi\n${unreadableCwdGuard(process.platform)}shift\n${RUN}`,
    )
  })

  describe('the engine runs INSIDE the pane shell (`engineRunScript`), never exec\'d over it', () => {
    const run = (argv: string[]) => {
      try {
        return { status: 0, out: execFileSync(argv[0], argv.slice(1), { stdio: ['ignore', 'pipe', 'pipe'] }).toString() }
      } catch (error) {
        const failed = error as { status: number | null; stdout: Buffer; stderr: Buffer }
        return { status: failed.status, out: `${failed.stdout}${failed.stderr}` }
      }
    }
    it('hands the engine its argv untouched, and without a terminal on stdin reports its exit status', () => {
      const argv = buildEngineLaunchArgv('claude', {}, '/bin/sh', undefined, undefined, NO_TMUX)
      // The launcher's own argv, then the "engine": `sh -c 'echo …; exit 3'` stands in for one.
      const script = [argv[0], argv[1], argv[2], 'harness-engine', '/bin/sh', '-c', 'printf "%s\\n" "args:$*"; exit 3', 'engine', 'a b', '--flag']
      const result = run(script)
      expect(result.out).toContain('args:a b --flag')
      expect(result.status).toBe(3)
      // No shell was handed over and no "this pane is a shell now" line was printed: no tty.
      expect(result.out).not.toContain('This pane is a shell now')
    })
    it('a take-over that waits says so, and starts the engine only once the other process is gone', () => {
      const folder = mkdtempSync(join(tmpdir(), 'harness-wait-engine-'))
      const binary = join(folder, 'codex')
      // /bin/sh --help succeeds on macOS but fails with Ubuntu's dash. A
      // simulated CLI needs its own help contract for the real startup probe.
      writeFileSync(binary, '#!/bin/sh\nif [ "$1" = "--help" ]; then echo "fixture CLI"; exit 0; fi\necho "engine ran"\n', { mode: 0o755 })
      // Not a child of this process, as the terminal's is not: an unreaped child never looks gone.
      const pid = Number(execFileSync('/bin/sh', ['-c', 'sleep 1 >/dev/null 2>&1 & echo $!']).toString().trim())
      try {
        const argv = buildEngineLaunchArgv('codex', { waitForPid: { pid, name: 'Codex' } }, '/bin/sh', undefined, undefined, NO_TMUX)
        const started = Date.now()
        const result = run([argv[0], argv[1], argv[2], 'harness-engine', binary])
        expect(Date.now() - started).toBeGreaterThanOrEqual(800)
        expect(result.out).toContain('Waiting for the Codex in your terminal to finish its turn.')
        expect(result.out.indexOf('Waiting for')).toBeLessThan(result.out.indexOf('engine ran'))
        expect(result.status).toBe(0)
        // Nothing to wait for: it starts at once.
        const immediate = buildEngineLaunchArgv('codex', { waitForPid: { pid: 2 ** 22 + 7, name: 'Codex' } }, '/bin/sh', undefined, undefined, NO_TMUX)
        const immediateStarted = Date.now()
        expect(run([immediate[0], immediate[1], immediate[2], 'harness-engine', binary]).out).toContain('engine ran')
        expect(Date.now() - immediateStarted).toBeLessThan(800)
      } finally {
        try { process.kill(pid) } catch { /* gone */ }
        rmSync(folder, { recursive: true, force: true })
      }
    })
    it('a command that does not exist still ends the pane with 127, so "not installed" stays a launch failure', () => {
      const argv = buildEngineLaunchArgv('claude', {}, '/bin/sh', undefined, undefined, NO_TMUX)
      expect(run([argv[0], argv[1], argv[2], 'harness-engine', '/nowhere/claude-that-is-not-here']).status).toBe(127)
    })
    it.each([
      ['with pane options (3.0 and later)', '', 'set-option -p -t %5 @harness_engine_exit 3'],
      // tmux 2.x answers `-p` with its usage text: the mark goes on the pane's window instead.
      ['before pane options (tmux 2.x)', 'if [ "$2" = -p ]; then echo "set-option: illegal option -- p" >&2; exit 1; fi\n',
        'set-option -w -t %5 @harness_engine_exit 3'],
    ])('marks the pane with the engine\'s exit status on a tmux %s', (_tmux, refuse, mark) => {
      const folder = mkdtempSync(join(tmpdir(), 'harness-exit-mark-'))
      try {
        const tmux = join(folder, 'tmux')
        const calls = join(folder, 'calls')
        writeFileSync(tmux, `#!/bin/sh\n${refuse}printf '%s\\n' "$*" >> '${calls}'\n`, { mode: 0o755 })
        const argv = buildEngineLaunchArgv('claude', {}, '/bin/sh', undefined, undefined, tmux)
        execFileSync(argv[0], [argv[1], argv[2], 'harness-engine', '/bin/sh', '-c', 'exit 3'], {
          stdio: ['ignore', 'pipe', 'pipe'], env: { ...process.env, TMUX_PANE: '%5' },
        }).toString()
      } catch (error) {
        expect((error as { status: number }).status).toBe(3)
      } finally {
        expect(readFileSync(join(folder, 'calls'), 'utf8').trim()).toBe(mark)
        rmSync(folder, { recursive: true, force: true })
      }
    })
    it('marks the pane with the exit status through the daemon\'s own tmux, and only then hands over a shell', () => {
      const prelude = engineFallbackPrelude('codex', '/bin/bash', '/opt/homebrew/bin/tmux')
      expect(prelude).toContain(`[ -n "\${TMUX_PANE:-}" ] && { '/opt/homebrew/bin/tmux' set-option -p -t "$TMUX_PANE" @harness_engine_exit "$harness_status"`)
      expect(prelude.indexOf('set-option')).toBeLessThan(prelude.indexOf("exec '/bin/bash'"))
      // What reached the terminal for the engine is dropped after the mark and before any shell reads it.
      expect(prelude.indexOf('set-option')).toBeLessThan(prelude.indexOf(ENGINE_INPUT_DRAIN_SH))
      expect(prelude.indexOf(ENGINE_INPUT_DRAIN_SH)).toBeLessThan(prelude.indexOf("exec '/bin/bash'"))
      expect(prelude).toContain('if [ "$harness_status" -eq 127 ]; then exit 127; fi')
      // zsh is a login shell; bash keeps its interactive rc (same rule as a terminal).
      expect(engineFallbackPrelude('codex', '/bin/zsh', null)).toContain("exec '/bin/zsh' -l\n")
      expect(engineFallbackPrelude('codex', '/bin/bash', null)).toContain("exec '/bin/bash'\n")
      expect(engineFallbackPrelude('codex', '/bin/bash', null)).not.toContain('set-option')
    })
  })

  describe('a stop is not an exit: a stopped engine is continued, never left behind', () => {
    const SHELLS = ['/bin/sh', '/bin/bash', '/bin/zsh', '/bin/dash'].filter(existsSync)
    const npmRecipe: EngineInstallRecipe = { command: 'npm install -g fixture', source: 'test fixture', executable: { names: ['fixture'], npmGlobal: true } }
    const launches: Array<[string, () => string[]]> = [
      ['claude', () => buildEngineLaunchArgv('claude', { cwd: '/work' }, '/bin/zsh', undefined, undefined, '/opt/homebrew/bin/tmux')],
      ['codex, run again after a failed startup', () => buildEngineLaunchArgv('codex', { cwd: '/work' }, '/bin/bash', undefined, undefined, '/opt/homebrew/bin/tmux')],
      ['codex without tmux', () => buildEngineLaunchArgv('codex', {}, '/bin/zsh', undefined, undefined, NO_TMUX)],
      ['an engine installed when missing', () => buildEngineLaunchArgv('claude', { installIfMissing: npmRecipe }, '/bin/zsh', undefined, undefined, '/opt/homebrew/bin/tmux')],
      ['codex installed when missing, after a take-over', () => buildEngineLaunchArgv('codex', { installIfMissing: { ...npmRecipe, executable: { names: ['codex'] } }, waitForPid: { pid: 2 ** 22 + 7, name: 'Codex' } }, '/bin/zsh', undefined, undefined, '/opt/homebrew/bin/tmux')],
      ['an engine installed first', () => buildEngineLaunchArgv('opencode', { installFirst: "curl -fsSL 'https://example.invalid/install' | bash" }, '/bin/bash', undefined, undefined, NO_TMUX)],
    ]
    const scriptOf = launchScriptOf

    it.each(launches)('%s: parses in every POSIX shell a pane may run it in', (_name, launch) => {
      const script = scriptOf(launch())
      for (const shell of SHELLS) expect(() => execFileSync(shell, ['-n', '-c', script], { stdio: ['ignore', 'pipe', 'pipe'] }), shell).not.toThrow()
    })

    it.each(launches)('%s: runs the engine, and an install, only at the top level of the script', (name, launch) => {
      // zsh gives up the whole script when a job stops inside a function, an `if`, a loop or an
      // `eval`, and bash leaves every loop around one: only a top-level run can be resumed. Every
      // block in these scripts indents its body, so a run in one would not start the line.
      const lines = scriptOf(launch()).split('\n')
      const runs = lines.filter((line) => /"\$harness_engine_bin"(?: \$\{harness_codex_no_daemon:\+--no-daemon\})? "\$@" \|\| harness_status=\$\?$/.test(line.trim()))
      expect(runs.length).toBe(name.startsWith('codex, run again') || name.startsWith('codex installed') ? 4 : 1)
      for (const run of runs) expect(run).toMatch(/^(?:\[ "\$harness_codex_go" != 1 \] \|\| )?"\$harness_engine_bin"/)
      // The friendly install (its progress on screen, the installer's output in a log) is the same
      // install in a pipeline inside one more top-level subshell, behind the same guards.
      for (const install of lines.filter((line) => line.includes('eval '))) expect(install).toMatch(/^(?:\[ -n "\$harness_engine_bin" \] \|\| )?(?:\[ "\$harness_quiet" -eq [01] \] \|\| )?(?:\( \( )?\((?:export npm_config_prefix=.*; )?eval /)
      // What follows each run is the resume, at the top level too.
      for (const run of runs) expect(lines[lines.indexOf(run) + 1]).toBe('harness_resume')
    })

    // The stop signals' numbers differ between macOS and Linux; dash's `kill -l` takes no names, so
    // these come from Node's table for this platform.
    const tstp = constants.signals.SIGTSTP
    const stop = constants.signals.SIGSTOP
    // `fg` and `jobs` need a terminal; these stand-ins count the stops and report each like the
    // shell's own would: 128 + TSTP while the engine keeps stopping, then its exit status.
    const ttou = constants.signals.SIGTTOU
    const resume = (shell: string, status: number, stops: number, job = true, { again = tstp, before = '' } = {}) => execFileSync(shell, ['-c', `${engineFallbackPrelude('claude', shell, null)}
stops=${stops}; resumed=0
jobs() { ${job ? 'return 0' : 'return 1'}; }
fg() { resumed=$((resumed + 1)); stops=$((stops - 1)); if [ "$stops" -gt 0 ]; then return ${128 + again}; fi; return 7; }
${before}
harness_status=${status}
harness_resume
printf '%s %s' "$harness_status" "$resumed"`], { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })

    it.each(SHELLS)('%s: continues a stopped engine as often as it stops, and keeps its real exit status', (shell) => {
      expect(resume(shell, 128 + tstp, 1)).toBe('7 1')
      expect(resume(shell, 128 + tstp, 3)).toBe('7 3')
      expect(resume(shell, 128 + stop, 2)).toBe('7 2')
    })

    it.each(SHELLS)('%s: leaves an engine that exited alone, and a job it did not start', (shell) => {
      expect(resume(shell, 0, 1)).toBe('0 0')
      expect(resume(shell, 3, 1)).toBe('3 0')
      // An engine killed by a signal, or one that exits with a stop's number: not a stop.
      expect(resume(shell, 128 + 15, 1)).toBe(`${128 + 15} 0`)
      expect(resume(shell, tstp, 1)).toBe(`${tstp} 0`)
      // A stop's status with no job to continue (a rc file's job is not the engine): nothing to resume.
      expect(resume(shell, 128 + tstp, 1, false)).toBe(`${128 + tstp} 0`)
    })

    it.each(SHELLS)('%s: lets an engine that stops again at once wait a second between resumes, so nothing spins', (shell) => {
      // Six stops, each within a second of its resume: three resumed at once, the rest after a pause.
      const started = Date.now()
      expect(resume(shell, 128 + tstp, 6)).toBe('7 6')
      expect(Date.now() - started).toBeGreaterThanOrEqual(2_000)
    }, 20_000)

    it.each(SHELLS)('%s: ends an engine that cannot keep the terminal after five quick tries', (shell) => {
      // TTOU over and over: the job is never let have the terminal (as when `fg` could not hand it over).
      expect(resume(shell, 128 + ttou, 50, true, { again: ttou })).toBe('137 5')
    }, 20_000)

    it.each(SHELLS)('%s: ends an engine at its thousandth stop where the resume calls itself, and only there', (shell) => {
      // bash and dash recurse once a stop, and overflow some ten thousand deep; zsh loops.
      const atTheEnd = { before: 'harness_resumes=998' }
      expect(resume(shell, 128 + tstp, 5, true, atTheEnd)).toBe(shell === '/bin/zsh' ? '7 5' : '137 1')
    })
  })

  describe('Codex writer ownership', () => {
    it.each(['supported', 'older', 'failed'] as const)('probes %s startup options without changing prompt arguments', mode => {
      const folder = mkdtempSync(join(tmpdir(), 'harness-codex-launch-'))
      try {
        const binary = join(folder, 'codex fixture')
        writeFileSync(binary, '#!/bin/sh\nif [ "$1" = "--help" ]; then\n'
          + (mode === 'failed' ? 'exit 2\n' : `printf '%s\\n' '${mode === 'supported' ? '  --no-daemon  Run locally' : '  --model  Choose a model'}'\nexit 0\n`)
          + 'fi\nprintf "<%s>\\n" "$@"\n', { mode: 0o755 })
        const script = buildEngineLaunchArgv('codex', {}, '/bin/sh', undefined, undefined, NO_TMUX)[2]
        const args = ['-c', script, 'harness-engine', binary, 'resume', 'same-conversation', 'literal $(nothing) `nothing` and spaces']
        if (mode === 'failed') {
          try { execFileSync('/bin/sh', args, { stdio: ['ignore', 'pipe', 'pipe'] }); expect.fail('launch must refuse an unknown startup mode') }
          catch (error) {
            expect((error as any).status).toBe(1)
            expect(String((error as any).stderr)).toContain('could not verify Codex startup options')
            expect(String((error as any).stdout)).not.toContain('same-conversation')
          }
        } else {
          const output = execFileSync('/bin/sh', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] })
          expect(output).toBe(`${mode === 'supported' ? '<--no-daemon>\n' : ''}<resume>\n<same-conversation>\n<literal $(nothing) \`nothing\` and spaces>\n`)
        }
      } finally { rmSync(folder, { recursive: true, force: true }) }
    })
  })

  describe('a terminal (engine `terminal`)', () => {
    it('is the login shell itself behind a non-interactive wrapper that only raises the limit and enters the folder', () => {
      expect(buildEngineLaunchArgv('terminal', { cwd: '/work/project' }, '/bin/zsh')).toEqual([
        '/bin/zsh', '-c',
        `${RAISE_OPEN_FILES_SH}${BROWSER}if ! cd -- "$1"; then printf '%s\\n' 'harness: the selected working directory is unavailable.' >&2; fi\nshift\nexec "$@"`,
        'harness-terminal', '/work/project', '/bin/zsh', '-l',
      ])
    })

    it('gives bash no login flag (its rc file is where Ubuntu keeps PATH edits), and no folder means no cd', () => {
      expect(buildEngineLaunchArgv('terminal', {}, '/bin/bash')).toEqual([
        '/bin/bash', '-c', `${RAISE_OPEN_FILES_SH}${BROWSER}shift\nexec "$@"`, 'harness-terminal', '', '/bin/bash',
      ])
    })

    it('falls back to /bin/sh rather than to an engine command when no shell resolves', () => {
      expect(buildEngineLaunchArgv('terminal', {}, 'relative-shell')).toEqual([
        '/bin/sh', '-c', `${RAISE_OPEN_FILES_SH}${BROWSER}shift\nexec "$@"`, 'harness-terminal', '', '/bin/sh',
      ])
    })

    it('ignores every engine option: nothing to bypass, resume, prompt or install', () => {
      const argv = buildEngineLaunchArgv('terminal', {
        cwd: '/w', bypassPermission: true, resumeSessionId: 'abc', firstPrompt: 'hi', extraArgs: ['--x'],
      }, '/bin/zsh')
      expect(argv.slice(-2)).toEqual(['/bin/zsh', '-l'])
      expect(argv.join(' ')).not.toContain('abc')
      expect(argv.join(' ')).not.toContain('--x')
    })

    it('is a script a real shell accepts and that keeps a cd failure from ending the terminal', () => {
      const script = buildEngineLaunchArgv('terminal', { cwd: '/nowhere/at/all' }, '/bin/sh')[2]
      expect(() => execFileSync('/bin/sh', ['-n', '-c', script])).not.toThrow()
      // The wrapper's `exec "$@"` runs the shell handed in argv; `true` in its place proves the
      // wrapper reaches the exec even when the cd failed (the terminal still opens, at $HOME).
      const out = execFileSync('/bin/sh', ['-c', script, 'harness-terminal', '/nowhere/at/all', '/bin/sh', '-c', 'echo reached'], { stdio: ['ignore', 'pipe', 'pipe'] })
      expect(out.toString()).toContain('reached')
    })

    it('greets every new tile with the banner — wordmark, where it is, agents, `harness remote` — before its prompt', () => {
      const argv = buildEngineLaunchArgv('terminal', { terminalHint: { machineName: 'MacbookPro.local' } }, '/bin/sh')
      expect(argv.slice(3)).toEqual(['harness-terminal', '', '/bin/sh'])
      expect(() => execFileSync('/bin/sh', ['-n', '-c', argv[2]])).not.toThrow()
      const run = (): string => execFileSync('/bin/sh', ['-c', argv[2], 'harness-terminal', '', '/bin/sh', '-c', 'echo prompt'], { stdio: ['ignore', 'pipe', 'pipe'] }).toString()
      // Every time, not once per machine: a new tile is a new person at a new prompt.
      for (const out of [run(), run()]) {
        // Every line as drawn — the wordmark's backslashes and backtick included.
        expect(out).toContain(terminalHintLines('MacbookPro.local').join('\n'))
        expect(out).toContain('  Terminal on MacbookPro.local')
        expect(out).toContain('harness remote')
        expect(out.trim().endsWith('prompt')).toBe(true)
      }
    })

    it('opens OS terminals directly at the shell prompt', () => {
      vi.stubEnv('HARNESS_OS', '1')
      try {
        const argv = buildEngineLaunchArgv('terminal', { terminalHint: { machineName: 'programmer-os' } }, '/bin/sh')
        const out = execFileSync('/bin/sh', ['-c', argv[2], 'harness-terminal', '', '/bin/sh', '-c', 'echo prompt']).toString()
        expect(out).toBe('prompt\n')
      } finally { vi.unstubAllEnvs() }
    })

    it('the banner names the machine, falls back to "this machine", and fits an 80-column pane unwrapped', () => {
      expect(terminalHintLines('  ')).toContain('  Terminal on this machine')
      for (const line of terminalHintLines('office-imac')) expect(line.length).toBeLessThanOrEqual(78)
      // A hostname longer than the line has room for is cut, never wrapped.
      const long = terminalHintLines('a'.repeat(120))
      for (const line of long) expect(line.length).toBeLessThanOrEqual(78)
      expect(long.find((line) => line.startsWith('  Terminal on'))).toMatch(/^  Terminal on a{61}…$/)
      // A blank line first and last: the wordmark does not sit on the pane's top edge, nor the prompt on the guide.
      const lines = terminalHintLines('office-imac')
      expect([lines[0], lines[lines.length - 1]]).toEqual(['', ''])
    })

    it('the wordmark is the one the installer prints, line for line', () => {
      // install.sh's print_logo, run for real: what a person sees at the end of an install is what a
      // tile shows them next — two copies, held to one drawing.
      const installer = readFileSync(join(process.cwd(), 'scripts', 'install.sh'), 'utf8')
      const printLogo = installer.slice(installer.indexOf('print_logo() {'), installer.indexOf('\n}\n', installer.indexOf('print_logo() {')) + 3)
      const printed = execFileSync('/bin/sh', ['-c', `${printLogo}\nprint_logo`], { encoding: 'utf8' }).split('\n').filter((line) => line.trim() !== '')
      expect(printed).toEqual([...HARNESS_WORDMARK_LINES])
    })

    it('with no guide asked for (restore, restart, a test) the pane says nothing before its prompt', () => {
      const script = buildEngineLaunchArgv('terminal', {}, '/bin/sh')[2]
      expect(script).not.toContain('harness remote')
      expect(script).not.toContain('Terminal on')
    })
  })

  it('hands the engine a soft open-files limit fit for it, however low the pane started', async () => {
    // A tmux server started by the desktop app passes launchd's 256 to every pane; Claude Code will
    // not start under that. The pane's own shell lifts it before exec, so the server never has to.
    const [shell, flag, paneScript] = buildEngineLaunchArgv('claude', {}, '/bin/sh')
    const { execFile } = await import('node:child_process')
    const seenByEngine = await new Promise<string>((resolve, reject) => {
      execFile(
        '/bin/sh',
        ['-c', 'ulimit -S -n 256 || exit 99; exec "$@"', 'pane', shell, flag, paneScript, 'harness-engine', '/bin/sh', '-c', 'ulimit -S -n'],
        { timeout: 10_000 },
        (error, stdout, stderr) => (error ? reject(new Error(`${error.message}\n${stderr}`)) : resolve(stdout.trim())),
      )
    })
    expect(seenByEngine).not.toBe('256')
    expect(seenByEngine === 'unlimited' || Number(seenByEngine) >= Math.min(MIN_OPEN_FILES, 4096)).toBe(true)
  })

  describe('an unreadable workspace', () => {
    // Under /bin/sh, with the engine replaced by printf so its run leaves a marker.
    async function launchInto(dir: string): Promise<{ code: number; stdout: string; stderr: string }> {
      const [, , paneScript] = buildEngineLaunchArgv('claude', { cwd: dir }, '/bin/sh')
      const { execFile } = await import('node:child_process')
      return await new Promise((resolve) => {
        execFile(
          '/bin/sh',
          ['-c', paneScript, 'harness-engine', dir, '/usr/bin/printf', 'ENGINE_RAN\n'],
          { timeout: 10_000 },
          (error, stdout, stderr) => {
            const code = error && typeof (error as { code?: unknown }).code === 'number'
              ? (error as unknown as { code: number }).code
              : 0
            resolve({ code, stdout, stderr })
          },
        )
      })
    }

    // root reads everything, so the guard has nothing to catch there.
    const notRoot = process.getuid?.() !== 0

    it.skipIf(!notRoot)('says why and stops instead of letting the engine fail on its first read', async () => {
      // Enterable but not readable: what macOS privacy settings (TCC) produce for a folder the
      // responsible app was not granted — `cd` works, the first readdir does not.
      const dir = mkdtempSync(join(tmpdir(), 'harness-unreadable-'))
      try {
        chmodSync(dir, 0o300)
        const result = await launchInto(dir)
        expect(result.code).toBe(1)
        expect(result.stdout).not.toContain('ENGINE_RAN')
        expect(result.stderr).toContain(`harness: cannot read ${dir}`)
      } finally {
        chmodSync(dir, 0o700)
        rmSync(dir, { recursive: true, force: true })
      }
    })

    it('launches the engine when the workspace is readable', async () => {
      const dir = mkdtempSync(join(tmpdir(), 'harness-readable-'))
      try {
        const result = await launchInto(dir)
        expect(result.code).toBe(0)
        expect(result.stdout).toContain('ENGINE_RAN')
      } finally {
        rmSync(dir, { recursive: true, force: true })
      }
    })

    // Both hints are pushed through a real /bin/sh, whatever platform runs the suite: the quoting
    // of the macOS text (a backtick-free command, `›`, `—`) is what a Linux runner would otherwise
    // never exercise.
    async function guardOutput(platform: NodeJS.Platform, dir: string): Promise<string> {
      const { execFile } = await import('node:child_process')
      return await new Promise((resolve) => {
        execFile(
          '/bin/sh',
          ['-c', `cd -- "$1" || exit 9\n${unreadableCwdGuard(platform)}echo ENGINE_RAN`, 'guard', dir],
          { timeout: 10_000 },
          (_error, stdout, stderr) => resolve(stdout + stderr),
        )
      })
    }

    it.skipIf(!notRoot)('points at the privacy settings on macOS and at permissions elsewhere', async () => {
      const dir = mkdtempSync(join(tmpdir(), 'harness-unreadable-hint-'))
      try {
        chmodSync(dir, 0o300)
        const darwin = await guardOutput('darwin', dir)
        expect(darwin).toContain('Full Disk Access')
        expect(darwin).toContain('tmux kill-server')
        expect(darwin).toContain('Privacy & Security')
        expect(darwin).not.toContain('ENGINE_RAN')
        const linux = await guardOutput('linux', dir)
        expect(linux).toContain('permissions')
        expect(linux).not.toContain('Privacy & Security')
        expect(linux).not.toContain('ENGINE_RAN')
      } finally {
        chmodSync(dir, 0o700)
        rmSync(dir, { recursive: true, force: true })
      }
    })

    it('keeps the action inside what a relayed pane summary can show', () => {
      // First hint line: what to do. It has to survive next to a folder path in a ~180-char summary.
      const firstHint = unreadableCwdGuard('darwin').match(/'(harness: on macOS[^']*)'/)?.[1] ?? ''
      expect(firstHint.length).toBeGreaterThan(0)
      expect(firstHint.length).toBeLessThanOrEqual(120)
    })
  })

  it('a DSH agent gets Harness\'s Node at the end of a PATH that has none; a plain launch is unchanged', () => {
    const argv = buildEngineLaunchArgv('claude', { harnessNode: true }, '/bin/zsh', '/opt/harness runtime/bin/node', undefined, NO_TMUX)
    // On this branch every pane script opens with the open-files raise, the engine-in-a-shell
    // wrapper and the grid prelude; the Node line lands after them, and a launch without
    // `harnessNode` is exactly the baseline above.
    expect(launchScriptOf(argv)).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/zsh')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}${harnessNodePrelude('/opt/harness runtime/bin/node')}${RUN}`)
    expect(harnessNodePrelude('/opt/harness runtime/bin/node')).toBe(
      'if ! command -v node >/dev/null 2>&1; then PATH="${PATH:+$PATH:}"\'/opt/harness runtime/bin\'; export PATH; fi\n')
    expect(launchScriptOf(buildEngineLaunchArgv('claude', { harnessNode: false }, '/bin/zsh', undefined, undefined, NO_TMUX))).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('claude', '/bin/zsh')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}${RUN}`)
  })

  it('the DSH prelude, run by a real shell, reaches the engine\'s PATH only when node is missing', () => {
    const home = mkdtempSync(join(tmpdir(), 'harness-node-prelude-'))
    try {
      const runtimeBin = join(home, 'runtime', 'bin')
      mkdirSync(runtimeBin, { recursive: true })
      writeFileSync(join(runtimeBin, 'node'), '#!/bin/sh\n', { mode: 0o755 })
      const run = (path: string) => {
        const argv = buildEngineLaunchArgv('claude', { harnessNode: true }, '/bin/sh', join(runtimeBin, 'node'))
        const script = argv[2]
        return execFileSync('/bin/sh', ['-c', script, 'harness-engine', '/bin/sh', '-c', 'echo "$PATH"; command -v node'], {
          env: { HOME: home, PATH: path }, encoding: 'utf8',
        }).trim().split('\n')
      }
      expect(run('/usr/bin:/bin')).toEqual([`/usr/bin:/bin:${runtimeBin}`, join(runtimeBin, 'node')])
      const own = join(home, 'own')
      mkdirSync(own)
      writeFileSync(join(own, 'node'), '#!/bin/sh\n', { mode: 0o755 })
      expect(run(`${own}:/usr/bin:/bin`)).toEqual([`${own}:/usr/bin:/bin`, join(own, 'node')])
    } finally {
      rmSync(home, { recursive: true, force: true })
    }
  })

  it('falls back to direct execution when no absolute shell is available', () => {
    expect(buildEngineLaunchArgv('claude', {}, '')).toEqual([engineBin('claude')])
    expect(buildEngineLaunchArgv('claude', {}, 'zsh')).toEqual([engineBin('claude')])
  })

  // Windows 11's default execution policy refuses npm's codex.ps1, which PowerShell would pick for a bare `codex`, and
  // cmd.exe would re-read the first message if the .cmd shim ran it (lib/windows/launch.ts): node runs the script.
  it('runs an npm engine on Windows as node on its script, never its .ps1 or .cmd', () => {
    const npm = mkdtempSync(join(tmpdir(), 'engine-launch-npm-'))
    const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
    try {
      for (const name of ['codex', 'codex.ps1', 'node.exe']) writeFileSync(join(npm, name), '')
      writeFileSync(join(npm, 'codex.cmd'), readFileSync(join(import.meta.dirname, 'windows', 'fixtures', 'npm-codex.cmd')))
      const script = join(npm, 'node_modules', '@openai', 'codex', 'bin', 'codex.js')
      mkdirSync(join(script, '..'), { recursive: true })
      writeFileSync(script, '')
      vi.stubEnv('PATH', npm)
      vi.stubEnv('CODEX_PATH', '')
      Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
      // The owned-process flag Codex's help listed (nativeLaunch.ts `startupArgs`) goes first, after the script.
      const native = { startupArgs: ['--no-daemon'] } as unknown as NativeLaunch
      expect(buildEngineCommandArgv('codex', { native, bypassPermission: true, firstPrompt: 'fix&calc "%PATH%"\n\nnext' }))
        .toEqual([join(npm, 'node.exe'), script, '--no-daemon', '--approve-for-me', ...CODEX_SCREEN, ...firstPromptArgs('codex', 'fix&calc "%PATH%"\n\nnext')])
    } finally {
      Object.defineProperty(process, 'platform', platform)
      vi.unstubAllEnvs()
      rmSync(npm, { recursive: true, force: true })
    }
  })

  // Windows has no /usr/bin/env: the variables it carried ride in the pane's env (engineLaunchEnv).
  it('never puts /usr/bin/env in front of a Windows launch, and gives its variables as env instead', () => {
    const native = { token: 'native-token' } as NativeLaunch
    const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
    let windows: string[][]
    try {
      Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
      windows = [buildEngineLaunchArgv('claude', {}, ''), buildEngineLaunchArgv('claude', { native }, '')]
    } finally { Object.defineProperty(process, 'platform', platform) }
    // The engine itself first: its name here, its resolved exe on a real Windows (windows/launch.ts).
    expect(windows[0][0]).toMatch(/(?:^|[\\/])claude(?:\.exe)?$/)
    for (const argv of windows) expect(argv).not.toContain('/usr/bin/env')
    expect(engineLaunchEnv('claude', native, 'win32')).toEqual({ [NATIVE_LAUNCH_MARKER]: 'native-token' })
    expect(engineLaunchEnv('codex', undefined, 'win32')).toBeUndefined()
    // Elsewhere the prefix stays in the argv, as before, and there is no env to add.
    if (process.platform !== 'win32') expect(buildEngineLaunchArgv('claude', { native }, '').slice(0, 2)).toEqual(['/usr/bin/env', `${NATIVE_LAUNCH_MARKER}=native-token`])
    expect(engineLaunchEnv('claude', native, 'darwin')).toBeUndefined()
  })

  describe('on Windows, which has no POSIX shell (lib/windows/engineStart.ts)', () => {
    const POSIX_ONLY = /^(?:\/bin\/(?:sh|dash|bash|zsh)|\/usr\/bin\/env)$/
    const platform = Object.getOwnPropertyDescriptor(process, 'platform')!
    const onWindows = <T>(run: () => T): T => {
      Object.defineProperty(process, 'platform', { ...platform, value: 'win32' })
      try { return run() } finally { Object.defineProperty(process, 'platform', platform) }
    }
    const executable = (current = true) => ({ command: '/fixture/codex', identity: 'fixture', current: () => current })
    const native = (overrides: Partial<NativeLaunch> = {}): NativeLaunch => ({
      token: '0f0e0d0c-0b0a-4908-8706-050403020100', executable: executable(), opencodeMajor: null, environment: {}, proofs: [],
      ready: () => true, current: () => true, prepareHooks: async () => true, permission: async () => 'supported',
      startupArgs: ['--no-daemon'], ...overrides,
    })

    it('has no interactive shell, whatever SHELL says (OpenSSH sets cmd.exe)', () => {
      for (const shell of ['c:\\windows\\system32\\cmd.exe', '/bin/zsh', '/usr/bin/bash', undefined]) {
        expect(onWindows(() => interactiveEngineShell(shell))).toBeNull()
      }
    })

    it('starts a plain engine as itself: no script, no POSIX program', () => {
      for (const shell of ['/bin/zsh', 'c:\\windows\\system32\\cmd.exe', '']) {
        const argv = onWindows(() => buildEngineLaunchArgv('claude', { cwd: '/work', installIfMissing: engineInstallRecipe('claude'), clearEnv: ['A'] }, shell))
        expect(argv).toEqual(onWindows(() => buildEngineCommandArgv('claude', {})))
        expect(argv.filter((arg) => POSIX_ONLY.test(arg))).toEqual([])
      }
    })

    it('starts Codex, whose startup contract needs a script elsewhere, with the flag its help listed', () => {
      const withFlag = onWindows(() => buildEngineLaunchArgv('codex', { native: native(), resumeSessionId: 'abc' }, '/bin/zsh'))
      expect(withFlag).toEqual(['/fixture/codex', '--no-daemon', 'resume', 'abc', ...CODEX_SCREEN])
      // An older Codex, whose help has no --no-daemon: none.
      expect(onWindows(() => buildEngineLaunchArgv('codex', { native: native({ startupArgs: [] }) }, '')))
        .toEqual(['/fixture/codex', ...CODEX_SCREEN])
      for (const argv of [withFlag]) expect(argv.filter((arg) => POSIX_ONLY.test(arg))).toEqual([])
    })

    it('refuses a Codex launch nobody probed, as the script ends one whose probe could not answer', () => {
      for (const opts of [{}, { native: native({ startupArgs: undefined }) }]) {
        expect(() => onWindows(() => buildEngineLaunchArgv('codex', opts, ''))).toThrow(WindowsStartupUnverified)
        expect(() => onWindows(() => buildEngineCommandArgv('codex', opts))).toThrow('Could not verify Codex startup options. Please try opening this session again.')
      }
      // An engine with no startup probe needs none.
      expect(onWindows(() => buildEngineCommandArgv('opencode', {}))).toHaveLength(1)
      // Elsewhere the script probes, and the command carries no flag of its own.
      if (process.platform !== 'win32') expect(buildEngineCommandArgv('codex', {})).toEqual([engineBin('codex'), ...CODEX_SCREEN])
    })

    it('runs a confirmed native launch as its engine, and holds one whose evidence changed', () => {
      const confirmed = onWindows(() => buildEngineLaunchArgv('codex', { native: native() }, ''))
      expect(confirmed).toEqual(['/fixture/codex', '--no-daemon', ...CODEX_SCREEN])
      const token = native().token!
      for (const changed of [
        native({ executable: executable(false) }),
        native({ ready: () => false }),
        native({ proofs: [{ files: [], current: () => false }] as unknown as NativeLaunch['proofs'] }),
      ]) {
        const held = onWindows(() => buildEngineLaunchArgv('codex', { native: changed }, ''))
        expect(held.slice(1, 2)).toEqual(['-e'])
        expect(held.slice(3)).toEqual(['harness-held', 'Waiting for native launch preparation to be confirmed.', token])
        expect(isHeldStartCommand(held.join(' '), token)).toBe(true)
        expect(held.filter((arg) => POSIX_ONLY.test(arg))).toEqual([])
      }
      // A native launch with no executable (a terminal's) has nothing to guard.
      expect(onWindows(() => buildEngineLaunchArgv('claude', { native: native({ executable: undefined }) }, '')))
        .toEqual(onWindows(() => buildEngineCommandArgv('claude', {})))
    })

    it('opens a terminal as the default Windows shell, and installs nothing through a POSIX shell', () => {
      expect(onWindows(() => buildEngineLaunchArgv('terminal', { cwd: '/work', terminalHint: { machineName: 'box' } }, '/bin/zsh')))
        .toEqual(defaultWindowsShell())
      expect(() => onWindows(() => buildEngineInstallationArgv('codex', engineInstallRecipe('codex')!, { HOME: '/h' })))
        .toThrow('The POSIX installer of codex does not run on Windows')
    })
  })

  it('appends the confirmed flag for engines with a known bypass flag', () => {
    expect(buildEngineCommandArgv('claude', { bypassPermission: true }))
      .toEqual([engineBin('claude'), '--permission-mode', 'auto'])
    expect(buildEngineCommandArgv('codex', { bypassPermission: true }))
      .toEqual([engineBin('codex'), '--approve-for-me', ...CODEX_SCREEN])
    expect(buildEngineCommandArgv('cursor', { bypassPermission: true }))
      .toEqual([engineBin('cursor'), '--force'])
    expect(buildEngineCommandArgv('opencode', { bypassPermission: true }))
      .toEqual([engineBin('opencode'), '--auto'])
  })

  it('launches each permission mode with its own flags, and a mode outranks bypassPermission', () => {
    expect(buildEngineCommandArgv('claude', { permissionMode: 'plan' }))
      .toEqual([engineBin('claude'), '--permission-mode', 'plan'])
    expect(buildEngineCommandArgv('claude', { permissionMode: 'acceptEdits', bypassPermission: true }))
      .toEqual([engineBin('claude'), '--permission-mode', 'acceptEdits'])
    // Claude Code's Ask names its mode: given no flag, 2.1.296 started in auto (2026-10-12).
    expect(buildEngineCommandArgv('claude', { permissionMode: 'ask', bypassPermission: true }))
      .toEqual([engineBin('claude'), '--permission-mode', 'default'])
    expect(buildEngineCommandArgv('codex', { permissionMode: 'ask', bypassPermission: true }))
      .toEqual([engineBin('codex'), ...CODEX_SCREEN])
    expect(buildEngineCommandArgv('claude', { permissionMode: 'full' }))
      .toEqual([engineBin('claude'), '--dangerously-skip-permissions'])
    expect(buildEngineCommandArgv('codex', { permissionMode: 'readOnly' }))
      .toEqual([engineBin('codex'), '--sandbox', 'read-only', ...CODEX_SCREEN])
    // Team-written work reads none of the branch's own settings, `settings.local.json` included (audit H2), and since v3 runs
    // as its owner on their own computer, so it skips no permission check and no sandbox (review of #3485).
    expect(buildEngineCommandArgv('claude', { permissionMode: 'teamWritten', bypassPermission: true }))
      .toEqual([engineBin('claude'), '--setting-sources', 'user', '--strict-mcp-config'])
    expect(buildEngineCommandArgv('codex', { permissionMode: 'teamWritten', bypassPermission: true }))
      .toEqual([engineBin('codex'), ...CODEX_SCREEN])
    // An older Buddy's saved mode is no mode: the registry clears it on load (task #4215).
    expect(permissionModeFlags('claude', 'buddy')).toBeNull()
    expect(permissionModeFlags('codex', 'readOnlyAsk')).toBeNull()
    expect(buildEngineCommandArgv('codex', { permissionMode: 'full' }))
      .toEqual([engineBin('codex'), '--dangerously-bypass-approvals-and-sandbox', ...CODEX_SCREEN])
    // A mode the engine lacks falls back to the yes/no.
    expect(buildEngineCommandArgv('opencode', { permissionMode: 'plan', bypassPermission: true }))
      .toEqual([engineBin('opencode'), '--auto'])
    expect(buildEngineCommandArgv('pi', { permissionMode: 'auto' })).toEqual([engineBin('pi')])
  })

  it('makes auto the same flags as bypassPermission, for every engine with modes', () => {
    for (const [engine, modes] of Object.entries(PERMISSION_MODES)) {
      expect(modes?.auto, engine).toEqual(BYPASS_PERMISSION_FLAGS[engine as keyof typeof BYPASS_PERMISSION_FLAGS])
      expect(modes?.ask, engine).toEqual(engine === 'claude' ? ['--permission-mode', 'default'] : [])
    }
  })

  it('is a no-op for engines with no confirmed flag, even when bypass is requested', () => {
    expect(buildEngineCommandArgv('pi', { bypassPermission: true })).toEqual([engineBin('pi')])
    expect(buildEngineCommandArgv('hermes', { bypassPermission: true })).toEqual([engineBin('hermes')])
  })

  it('has an entry (possibly null) for every known engine — no engine silently falls through', () => {
    for (const engine of ENGINES) {
      expect(Object.prototype.hasOwnProperty.call(BYPASS_PERMISSION_FLAGS, engine)).toBe(true)
    }
  })

  it('appends a flag-style resume argument after the binary', () => {
    expect(buildEngineCommandArgv('claude', { resumeSessionId: 'abc-123' }))
      .toEqual([engineBin('claude'), '--resume', 'abc-123'])
    expect(buildEngineCommandArgv('opencode', { resumeSessionId: 'ses_1' }))
      .toEqual([engineBin('opencode'), '--session', 'ses_1'])
  })

  it('reopens a Pi by its exact id, which Pi creates when nothing was written to it yet', () => {
    // `pi --session <id>` exits with "No session found matching" until the first reply writes the file.
    const id = '019a2b3c-4d5e-7f60-8a9b-0c1d2e3f4a5b'
    expect(buildEngineCommandArgv('pi', { resumeSessionId: id })).toEqual([engineBin('pi'), '--session-id', id])
    expect(resumeSessionId('pi', `pi --session-id ${id}`)).toBe(id)
  })

  it('puts a subcommand-style resume FIRST, ahead of any other flag', () => {
    expect(buildEngineCommandArgv('codex', { resumeSessionId: 'abc-123' }))
      .toEqual([engineBin('codex'), 'resume', 'abc-123', ...CODEX_SCREEN])
    expect(buildEngineCommandArgv('codex', { resumeSessionId: 'abc-123', bypassPermission: true }))
      .toEqual([engineBin('codex'), 'resume', 'abc-123', '--approve-for-me', ...CODEX_SCREEN])
    expect(buildEngineCommandArgv('amp', { resumeSessionId: 'T-1' }))
      .toEqual([engineBin('amp'), 'threads', 'continue', 'T-1'])
  })

  it('still applies bypassPermission with no resume requested (regression)', () => {
    expect(buildEngineCommandArgv('claude', { bypassPermission: true }))
      .toEqual([engineBin('claude'), '--permission-mode', 'auto'])
  })

  it('resumes devin by its session slug (docs.devin.ai/cli, since 2026.4.17)', () => {
    expect(buildEngineCommandArgv('devin', { resumeSessionId: 'brisk-otter' })).toEqual([engineBin('devin'), '--resume', 'brisk-otter'])
  })

  it('has a launch resume flag for every engine RESUME_ARGS also covers, plus claude/codex', () => {
    for (const engine of ['claude', 'codex', 'cursor', 'opencode', 'kilo', 'pi', 'hermes', 'commandcode',
      'muse', 'amp', 'grok', 'agy', 'copilot', 'devin'] as const) {
      expect(LAUNCH_RESUME_FLAG[engine]?.length).toBeGreaterThan(0)
    }
  })
})

describe('a login shell that is not POSIX', () => {
  let dataDir = ''
  let savedDataDir = ''
  beforeEach(() => { dataDir = mkdtempSync(join(tmpdir(), 'launch-shell-')); savedDataDir = env.ADAPTER_DATA_DIR; env.ADAPTER_DATA_DIR = dataDir })
  afterEach(() => { env.ADAPTER_DATA_DIR = savedDataDir; rmSync(dataDir, { recursive: true, force: true }) })

  it('tells the POSIX shells from the rest by name', () => {
    for (const shell of ['/bin/sh', '/bin/bash', '/bin/zsh', '/usr/bin/dash', '/bin/ksh', '/usr/local/bin/mksh', '/bin/ash', '/usr/bin/yash']) expect(isPosixShell(shell), shell).toBe(true)
    for (const shell of ['/usr/local/bin/fish', '/bin/tcsh', '/bin/csh', '/opt/homebrew/bin/nu', '/usr/bin/xonsh', '/usr/bin/elvish']) expect(isPosixShell(shell), shell).toBe(false)
  })

  it('asks each its own way for the person\'s interactive startup files', () => {
    expect(interactiveEngineShell('/bin/zsh')?.args).toEqual(['-lic'])
    expect(interactiveEngineShell('/bin/bash')?.args).toEqual(['-ic'])
    expect(interactiveEngineShell('/usr/bin/dash')?.args).toEqual(['-ic'])
    expect(interactiveEngineShell('/usr/local/bin/fish')).toMatchObject({ args: ['-i', '-c'], label: 'fish shell' })
    expect(interactiveEngineShell('/bin/tcsh')?.args).toEqual(['-i', '-c'])
    expect(interactiveEngineShell('/opt/homebrew/bin/nu')?.args).toEqual(['-c'])
  })

  it('launches an engine through the shell, which hands a one-time POSIX script to dash, or else /bin/sh', () => {
    const argv = buildEngineLaunchArgv('claude', { cwd: "/work/it's here" }, '/usr/local/bin/fish', '/opt/node/bin/node', '/opt/grid/bin/grid', '/usr/bin/tmux')
    expect(argv.slice(0, 3)).toEqual(['/usr/local/bin/fish', '-i', '-c'])
    expect(argv).toHaveLength(4)
    // dash, where there is one: run like this it still resumes an engine that stopped (bash as sh does not).
    expect(argv[3].startsWith(`exec ${existsSync('/bin/dash') ? '/bin/dash' : '/bin/sh'} '`)).toBe(true)
    const file = /^exec \/bin\/(?:da)?sh '(.+)'$/.exec(argv[3])?.[1]
    expect(file && file.startsWith(join(dataDir, 'launch'))).toBe(true)
    const script = readFileSync(file!, 'utf8')
    // It removes itself first, then takes the arguments a POSIX shell would have been given.
    expect(script.startsWith(`rm -f -- '${file}'\nset -- '/work/it'"'"'s here' '${engineBin('claude')}'`)).toBe(true)
    expect(script).toContain(RUN_LINE)
    // zsh runs its own: it sources the file itself, with the arguments on its command line.
    const zsh = buildEngineLaunchArgv('claude', { cwd: '/work' }, '/bin/zsh', '/opt/node/bin/node', '/opt/grid/bin/grid', '/usr/bin/tmux')
    expect(zsh.slice(0, 4)).toEqual(['/usr/bin/env', 'DISABLE_AUTO_UPDATE=true', '/bin/zsh', '-lic'])
    expect(zsh[4]).toMatch(SOURCED)
  })

  it.skipIf(!existsSync('/bin/tcsh'))('runs that script for real under tcsh, with its arguments intact and the file gone', () => {
    const argv = buildEngineLaunchArgv('claude', { cwd: dataDir, installFirst: undefined }, '/bin/tcsh', '/opt/node/bin/node', '/opt/grid/bin/grid', null)
    const file = /^exec \/bin\/(?:da)?sh '(.+)'$/.exec(argv[argv.length - 1])![1]
    // Run the file the way tcsh would hand it over, with the engine replaced by printf.
    writeFileSync(file, readFileSync(file, 'utf8').replace(RUN_LINE, 'printf "%s|" "$PWD" "$harness_engine_bin" "$@"'))
    const out = execFileSync('/bin/tcsh', ['-i', '-c', argv[argv.length - 1]], { encoding: 'utf8', env: { ...process.env, HOME: dataDir }, stdio: ['ignore', 'pipe', 'ignore'] })
    expect(out).toContain(`${dataDir}|${engineBin('claude')}|`)
    expect(existsSync(file)).toBe(false)
  })

  it('opens a terminal tile with /bin/sh entering the folder, then the person\'s own shell', () => {
    expect(buildTerminalLaunchArgv({ cwd: '/work' }, '/usr/local/bin/fish')).toEqual(['/bin/sh', '-c', expect.stringContaining('exec "$@"'), 'harness-terminal', '/work', '/usr/local/bin/fish'])
    expect(buildTerminalLaunchArgv({ cwd: '/work' }, '/bin/zsh').slice(0, 2)).toEqual(['/bin/zsh', '-c'])
  })
})

describe('a model and effort on launch', () => {
  it('gives Claude Code its model and effort as flags of that session, ahead of the first prompt', () => {
    expect(buildEngineCommandArgv('claude', { launchModel: { model: 'opus', effort: 'high' }, extraArgs: ['--x'], firstPrompt: 'go' }))
      .toEqual([engineBin('claude'), '--x', '--model', 'opus', '--effort', 'high', 'go'])
    expect(buildEngineCommandArgv('claude', { launchModel: { model: 'default', effort: 'default' } })).toEqual([engineBin('claude')])
  })

  it('keeps a model with shell characters one argv item, never part of a shell string', () => {
    const argv = buildEngineCommandArgv('claude', { launchModel: { model: 'a$(id)', effort: null } })
    expect(argv).toEqual([engineBin('claude'), '--model', 'a$(id)'])
  })

  it('leaves an engine without the flags as it was', () => {
    expect(buildEngineCommandArgv('codex', { launchModel: { model: 'gpt-5', effort: 'high' } })).toEqual(buildEngineCommandArgv('codex'))
  })
})

describe('the owner\'s own launch words', () => {
  it('go last: after the extra arguments, the model and the first prompt, so a trailing flag cannot swallow Harness\'s own', () => {
    const argv = buildEngineCommandArgv('claude', {
      extraArgs: ['--append-system-prompt', 'be brief'], launchModel: { model: 'opus', effort: null }, firstPrompt: 'go', ownerArgs: ['--chrome', '--add-dir'],
    })
    expect(argv).toEqual([engineBin('claude'), '--append-system-prompt', 'be brief', '--model', 'opus', 'go', '--chrome', '--add-dir'])
    expect(buildEngineCommandArgv('claude', { ownerArgs: [] })).toEqual([engineBin('claude')])
  })

  it('reach the pane\'s command line through the shell wrapper as separate items', () => {
    const argv = buildEngineLaunchArgv('claude', { cwd: '/work', ownerArgs: ['--add-dir', 'a b'] })
    expect(argv.slice(-2)).toEqual(['--add-dir', 'a b'])
  })
})

describe('a first prompt on launch', () => {
  const PROMPT = 'Start a local model on this machine'

  it('hands opencode the text through its TUI flag', () => {
    expect(buildEngineCommandArgv('opencode', { firstPrompt: PROMPT }))
      .toEqual([engineBin('opencode'), '--prompt', PROMPT])
  })

  it('hands claude and codex the text positionally', () => {
    expect(buildEngineCommandArgv('claude', { firstPrompt: PROMPT })).toEqual([engineBin('claude'), PROMPT])
    expect(buildEngineCommandArgv('codex', { firstPrompt: PROMPT })).toEqual([engineBin('codex'), ...CODEX_SCREEN, PROMPT])
  })

  it('hands hermes the text as the first turn of an interactive chat, after a resume', () => {
    // `hermes chat -q` on a TTY seeds the session and keeps the TUI open (measured on a live pane).
    expect(buildEngineCommandArgv('hermes', { firstPrompt: PROMPT }))
      .toEqual([engineBin('hermes'), 'chat', '-q', PROMPT])
    // Global flags stay ahead of the subcommand, where hermes's parser reads them.
    expect(buildEngineCommandArgv('hermes', { resumeSessionId: 'abc', firstPrompt: PROMPT }))
      .toEqual([engineBin('hermes'), '--resume', 'abc', 'chat', '-q', PROMPT])
  })

  it('puts the text LAST, after every flag, so a positional is never read as an option value', () => {
    expect(buildEngineCommandArgv('claude', { firstPrompt: PROMPT, bypassPermission: true, extraArgs: ['--allowedTools=WebSearch'] }))
      .toEqual([engineBin('claude'), '--permission-mode', 'auto', '--allowedTools=WebSearch', PROMPT])
    expect(buildEngineCommandArgv('opencode', { firstPrompt: PROMPT, bypassPermission: true, extraArgs: ['-m', 'local/qwen'] }))
      .toEqual([engineBin('opencode'), '--auto', '-m', 'local/qwen', '--prompt', PROMPT])
  })

  it('refuses an engine with no documented mechanism, naming the engine, rather than dropping the text', () => {
    expect(supportsFirstPrompt('cursor')).toBe(false)
    expect(() => firstPromptArgs('cursor', PROMPT)).toThrow(FirstPromptUnsupportedError)
    let refusal: unknown
    try { buildEngineCommandArgv('cursor', { firstPrompt: PROMPT }) } catch (error) { refusal = error }
    expect(refusal).toBeInstanceOf(FirstPromptUnsupportedError)
    expect((refusal as FirstPromptUnsupportedError).code).toBe('PROMPT_UNSUPPORTED')
    expect((refusal as FirstPromptUnsupportedError).message).toContain('Cursor')
  })

  // prompt_unsupported, 4 in the Oct 21–27 report: the refusal named the engine but not what to do instead.
  it('says what to do instead: leave the first message out, or use an agent that takes one', () => {
    expect(new FirstPromptUnsupportedError('cursor').message).toBe('Cursor cannot start with a first message. Start it without one '
      + 'and type the message once it opens, or choose Claude, Codex, OpenCode, Oh My Pi or Hermes to start with one.')
  })

  it('leaves the argv unchanged with no prompt, or an empty one', () => {
    expect(buildEngineCommandArgv('opencode', {})).toEqual([engineBin('opencode')])
    expect(buildEngineCommandArgv('opencode', { firstPrompt: '' })).toEqual([engineBin('opencode')])
    expect(buildEngineCommandArgv('cursor', { firstPrompt: '' })).toEqual([engineBin('cursor')])
  })

  it('reaches the engine as ONE positional argument through the pane shell, however it is spelled', async () => {
    // The pane script execs "$@": the prompt must arrive as a single argv entry, spaces, quotes and
    // all, rather than being re-split by the shell.
    const spelled = `Start a local model on "this" machine; it's $HOME`
    const [, , paneScript, marker, ...command] = buildEngineLaunchArgv('claude', { firstPrompt: spelled }, '/bin/sh')
    expect(marker).toBe('harness-engine')
    expect(command).toEqual([engineBin('claude'), spelled])
    const { execFile } = await import('node:child_process')
    const seen = await new Promise<string>((resolve, reject) => {
      execFile('/bin/sh', ['-c', paneScript, 'harness-engine', '/bin/sh', '-c', 'printf "%s" "$1"', 'engine', spelled],
        { timeout: 10_000 }, (error, stdout) => (error ? reject(error) : resolve(stdout)))
    })
    expect(seen).toBe(spelled)
  })

  it('has an entry (possibly null) for every known engine — no engine silently falls through', () => {
    for (const engine of ENGINES) {
      expect(Object.prototype.hasOwnProperty.call(FIRST_PROMPT_ARGS, engine)).toBe(true)
    }
    expect(supportsFirstPrompt('opencode')).toBe(true)
    expect(supportsFirstPrompt('claude')).toBe(true)
    expect(supportsFirstPrompt('codex')).toBe(true)
  })
})

describe('opening as a named agent', () => {
  it('hands opencode the name through --agent, in the extraArgs slot a relaunch also uses', () => {
    expect(namedAgentArgs('opencode', 'harness-compute')).toEqual(['--agent', 'harness-compute'])
    expect(buildEngineCommandArgv('opencode', { bypassPermission: true, extraArgs: ['-m', 'local/qwen', ...namedAgentArgs('opencode', 'harness-compute')] }))
      .toEqual([engineBin('opencode'), '--auto', '-m', 'local/qwen', '--agent', 'harness-compute'])
    // Resume keeps it too — the flag rides `extraArgs`, which every relaunch rebuilds from the row.
    expect(buildEngineCommandArgv('opencode', { resumeSessionId: 'ses_1', extraArgs: namedAgentArgs('opencode', 'harness-compute') }))
      .toEqual([engineBin('opencode'), '--session', 'ses_1', '--agent', 'harness-compute'])
  })

  it('refuses opencode v2, whose TUI has no --agent (only `opencode run` does)', () => {
    expect(supportsNamedAgent('opencode', 2)).toBe(false)
    expect(() => namedAgentArgs('opencode', 'harness-compute', 2)).toThrow(NamedAgentUnsupportedError)
    // v1, or a version not read, keeps the flag it always had.
    expect(supportsNamedAgent('opencode', 1)).toBe(true)
    expect(supportsNamedAgent('opencode', null)).toBe(true)
  })

  it('refuses every other engine, naming it, rather than dropping the name', () => {
    for (const engine of ENGINES) {
      if (engine === 'opencode') continue
      expect(supportsNamedAgent(engine)).toBe(false)
      let refusal: unknown
      try { namedAgentArgs(engine, 'harness-compute') } catch (error) { refusal = error }
      expect(refusal).toBeInstanceOf(NamedAgentUnsupportedError)
      expect((refusal as NamedAgentUnsupportedError).code).toBe('AGENT_UNSUPPORTED')
      expect((refusal as NamedAgentUnsupportedError).message).toContain(engine)
    }
  })

  it('has an entry (possibly null) for every known engine — no engine silently falls through', () => {
    for (const engine of ENGINES) {
      expect(Object.prototype.hasOwnProperty.call(NAMED_AGENT_ARGS, engine)).toBe(true)
    }
    expect(supportsNamedAgent('opencode')).toBe(true)
  })

  it('accepts an identifier and nothing that could be a path or prose', () => {
    for (const ok of ['harness-compute', 'build', 'A_b-1', 'x'.repeat(64)]) expect(AGENT_NAME_RE.test(ok)).toBe(true)
    for (const bad of ['', ' harness-compute', 'local model', '../etc', 'a/b', 'name.md', 'x'.repeat(65), 'nämn']) {
      expect(AGENT_NAME_RE.test(bad)).toBe(false)
    }
  })
})

const dirs: string[] = []
const originalProbePath = process.env.HARNESS_ENGINE_TEST_PATH

afterEach(() => {
  if (originalProbePath === undefined) delete process.env.HARNESS_ENGINE_TEST_PATH
  else process.env.HARNESS_ENGINE_TEST_PATH = originalProbePath
  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true })
})

function executable(dir: string, name: string): string {
  const path = join(dir, name)
  writeFileSync(path, '#!/bin/sh\nexit 0\n')
  chmodSync(path, 0o700)
  return path
}

function bashProbeShell(): string {
  const dir = mkdtempSync(join(tmpdir(), 'harness-engine-shell-'))
  dirs.push(dir)
  const shell = join(dir, 'bash')
  writeFileSync(shell, `#!/bin/sh
[ "$1" = '-ic' ] || exit 97
shift
script="$1"
shift
PATH="$HARNESS_ENGINE_TEST_PATH"
export PATH
exec /bin/sh -c "$script" "$@"
`)
  chmodSync(shell, 0o700)
  return shell
}

/** The real zsh, if this machine has one. macOS always does; a Linux CI box may not. */
const ZSH = ['/bin/zsh', '/usr/bin/zsh'].find((path) => existsSync(path)) ?? null

/**
 * A probe shell that hands the script to the REAL zsh. `bashProbeShell` runs everything through
 * `/bin/sh` and so cannot see a zsh-only parse rule — and zsh is what macOS defaults $SHELL to,
 * i.e. the shell the capability probe actually runs under for most users. Plain `-c` rather than
 * zsh's interactive form keeps the case hermetic: no developer's rc file gets a say in the result.
 */
function zshProbeShell(): string {
  const dir = mkdtempSync(join(tmpdir(), 'harness-engine-zsh-shell-'))
  dirs.push(dir)
  // Named `zsh` so interactiveEngineShell hands it zsh's own `-lic`, exactly as it would $SHELL.
  const shell = join(dir, 'zsh')
  writeFileSync(shell, `#!/bin/sh
[ "$1" = '-lic' ] || exit 97
shift
script="$1"
shift
PATH="$HARNESS_ENGINE_TEST_PATH"
export PATH
exec ${ZSH} -c "$script" "$@"
`)
  chmodSync(shell, 0o700)
  return shell
}

describe('commandAvailableInInteractiveShell', () => {
  it('reports a shell failure as unverified rather than a missing command', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'harness-failed-probe-'))
    dirs.push(dir)
    const shell = join(dir, 'bash')
    writeFileSync(shell, '#!/bin/sh\nexit 9\n')
    chmodSync(shell, 0o700)
    const result = await commandAvailableInInteractiveShell('git', shell, undefined, true)
    expect(result).toMatchObject({ status: 'unverified', detail: expect.stringContaining('9') })
  })
  it('bounds a hung shell probe and reports a timeout as unverified', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'harness-slow-probe-'))
    dirs.push(dir)
    const shell = join(dir, 'bash')
    writeFileSync(shell, '#!/bin/sh\nexec /bin/sleep 30\n')
    chmodSync(shell, 0o700)
    const started = Date.now()
    const result = await commandAvailableInInteractiveShell('git', shell, undefined, true)
    expect(result).toEqual({ status: 'unverified', detail: 'Interactive shell tool probe timed out after 5 seconds.' })
    expect(Date.now() - started).toBeLessThan(7_000)
  }, 8_000)
  it('uses the same bash interactive PATH that launches a new engine', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-bin-'))
    dirs.push(binDir)
    executable(binDir, 'kilo')
    process.env.HARNESS_ENGINE_TEST_PATH = binDir

    const shell = bashProbeShell()
    await expect(commandAvailableInInteractiveShell('kilo', shell)).resolves.toBe(true)
    await expect(commandAvailableInInteractiveShell('missing-engine', shell)).resolves.toBe(false)
    await expect(commandAvailableInInteractiveShell('kilo', shell, undefined, true)).resolves.toEqual({ status: 'available' })
    await expect(commandAvailableInInteractiveShell('missing-engine', shell, undefined, true)).resolves.toEqual({ status: 'missing' })
  })

  it('recognizes an installed vendor path before the shell profile has it on PATH', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-vendor-bin-'))
    dirs.push(binDir)
    const installed = executable(binDir, 'cursor-agent')
    process.env.HARNESS_ENGINE_TEST_PATH = '/usr/bin:/bin'
    const recipe: EngineInstallRecipe = {
      command: 'false',
      source: 'test fixture',
      executable: { names: ['cursor-agent'], absolutePaths: [installed] },
    }

    await expect(
      commandAvailableInInteractiveShell('cursor-agent', bashProbeShell(), recipe),
    ).resolves.toBe(true)
  })
})

/** A fake engine whose `--help` prints exactly `help`, and nothing else. */
function fakeEngine(dir: string, name: string, help: string): void {
  writeFileSync(join(dir, name), `#!/bin/sh\nif [ "$1" = "--help" ]; then printf "%s\\n" '${help}'; exit 0; fi\nexit 2\n`)
  chmodSync(join(dir, name), 0o700)
}

describe('the permission gates', () => {
  /** A fake opencode on the probe shell's PATH, and the shell that will find it. */
  function withFakeOpencode(help: string): string {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-gate-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    fakeEngine(binDir, 'opencode', help)
    return bashProbeShell()
  }

  it('refuses a create whose engine does not take the flag, naming the engine and the flag', async () => {
    const shell = withFakeOpencode('--auto-update')
    const refusal = await refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'auto' }, shell)
    expect(refusal?.error).toBe('CODEX_CLI_TOO_OLD')
    expect(refusal?.detail).toContain('opencode')
    expect(refusal?.detail).toContain('--auto')
  })

  // The install lines are POSIX shell: on Windows only an npm line runs as written (in PowerShell too).
  it('names an update command only where it runs as written', () => {
    expect(engineUpdateCommand('opencode', 'darwin')).toBe('curl -fsSL https://opencode.ai/install | bash')
    expect(engineUpdateCommand('opencode', 'win32')).toBeNull()
    expect(engineUpdateCommand('codex', 'win32')).toBe('npm install -g @openai/codex')
    expect(engineUpdateCommand('terminal', 'darwin')).toBeNull()
  })

  // codex_cli_too_old, 2–4 a day: "Update opencode" did not say how.
  it('gives the command that updates the engine', async () => {
    const shell = withFakeOpencode('--auto-update')
    const refusal = await refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'auto' }, shell)
    expect(refusal?.detail).toBe('The opencode CLI on this machine does not support --auto, which Harness uses for this permission mode. '
      + 'Update opencode by running curl -fsSL https://opencode.ai/install | bash, then try again, or choose Ask permissions for this harness.')
  })

  it('lets a create through when the flag is there, and when there is no flag to check', async () => {
    const shell = withFakeOpencode('--auto')
    await expect(refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'auto' }, shell)).resolves.toBeNull()
    await expect(refusePermissionFlagIfUnsupported('opencode', { permissionMode: 'ask' }, shell)).resolves.toBeNull()
  })

  it('drops the flag for a relaunch instead of refusing it, leaving the launch in Ask', async () => {
    const shell = withFakeOpencode('--auto-update')
    const dropped = await dropPermissionFlagIfUnsupported('opencode', { permissionMode: 'auto', bypassPermission: true }, shell)
    expect(dropped).toEqual({ choice: { permissionMode: 'ask', bypassPermission: false }, droppedFlag: '--auto' })
  })

  it('drops Claude Code\'s mode for a relaunch to no flag at all, since its Ask names a mode with that flag', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-gate-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    fakeEngine(binDir, 'claude', '--resume')
    const shell = bashProbeShell()
    for (const permissionMode of ['auto', 'ask']) {
      const dropped = await dropPermissionFlagIfUnsupported('claude', { permissionMode, bypassPermission: permissionMode === 'auto' }, shell)
      expect(dropped).toEqual({ choice: { permissionMode: null, bypassPermission: false }, droppedFlag: '--permission-mode' })
      expect(buildEngineCommandArgv('claude', { ...dropped.choice, permissionMode: dropped.choice.permissionMode ?? undefined })).toEqual([engineBin('claude')])
    }
    // A create in Ask is told to update, never to choose the Ask it chose.
    const refusal = await refusePermissionFlagIfUnsupported('claude', { permissionMode: 'ask' }, shell)
    expect(refusal?.detail).toContain('Update claude by running npm install -g @anthropic-ai/claude-code, then try again.')
    expect(refusal?.detail).not.toContain('choose Ask')
  })

  it('leaves a relaunch alone when the flag is supported', async () => {
    const shell = withFakeOpencode('--auto')
    const kept = await dropPermissionFlagIfUnsupported('opencode', { permissionMode: 'auto', bypassPermission: true }, shell)
    expect(kept).toEqual({ choice: { permissionMode: 'auto', bypassPermission: true }, droppedFlag: null })
  })
})

describe('the launch model gate', () => {
  function withFakeClaude(help: string): string {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-gate-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    fakeEngine(binDir, 'claude', help)
    return bashProbeShell()
  }

  it('names the first flag a build of the engine lacks', async () => {
    const shell = withFakeClaude('--model <model>')
    await expect(unsupportedLaunchModelFlag('claude', { model: 'opus', effort: 'high' }, shell)).resolves.toBe('--effort')
    await expect(unsupportedLaunchModelFlag('claude', { model: 'opus', effort: null }, shell)).resolves.toBeNull()
  })

  it('does not read a longer flag as the one it needs', async () => {
    const shell = withFakeClaude('--model <model>\n--effort-hint')
    await expect(unsupportedLaunchModelFlag('claude', { model: null, effort: 'high' }, shell)).resolves.toBe('--effort')
  })

  it('lets a build that has both flags through, and asks nothing for default or an engine without flags', async () => {
    const shell = withFakeClaude('--model <model>\n--effort <level>')
    await expect(unsupportedLaunchModelFlag('claude', { model: 'opus', effort: 'high' }, shell)).resolves.toBeNull()
    await expect(unsupportedLaunchModelFlag('claude', { model: 'default', effort: 'default' }, shell)).resolves.toBeNull()
    await expect(unsupportedLaunchModelFlag('codex', { model: 'x', effort: 'high' }, shell)).resolves.toBeNull()
  })
})

describe('permissionFlagToVerify', () => {
  it('names the single token a mode adds', () => {
    expect(permissionFlagToVerify('opencode', { permissionMode: 'auto' })).toBe('--auto')
    expect(permissionFlagToVerify('cursor', { permissionMode: 'auto' })).toBe('--force')
    expect(permissionFlagToVerify('codex', { permissionMode: 'auto' })).toBe('--approve-for-me')
  })

  it('reads the bypass table when no mode was recorded', () => {
    expect(permissionFlagToVerify('opencode', { bypassPermission: true })).toBe('--auto')
    expect(permissionFlagToVerify('opencode', { bypassPermission: false })).toBeNull()
  })

  // The documented limit: help never prints the pair, so only the token can be asked about, and a
  // build that lists `--permission-mode` while having dropped the `auto` VALUE is not caught here.
  it('takes the flag token of a pair, never its value', () => {
    expect(permissionModeFlags('claude', 'auto')).toEqual(['--permission-mode', 'auto'])
    expect(permissionFlagToVerify('claude', { permissionMode: 'auto' })).toBe('--permission-mode')
    expect(permissionFlagToVerify('codex', { permissionMode: 'readOnly' })).toBe('--sandbox')
  })

  it('has nothing to verify for an Ask with no flag, an engine with no table, or a terminal', () => {
    expect(permissionFlagToVerify('codex', { permissionMode: 'ask' })).toBeNull()
    // Claude Code's Ask passes its mode, verified like any other.
    expect(permissionFlagToVerify('claude', { permissionMode: 'ask' })).toBe('--permission-mode')
    expect(permissionFlagToVerify('muse', { bypassPermission: true })).toBeNull()
    expect(permissionFlagToVerify('terminal', { bypassPermission: true })).toBeNull()
  })
})

describe('commandSupportsFlagInInteractiveShell', () => {
  it('distinguishes an older CLI help surface from a supported flag', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-capability-'))
    dirs.push(binDir)
    const codex = join(binDir, 'codex')
    writeFileSync(
      codex,
      '#!/bin/sh\nif [ "$1" = "--help" ]; then printf "%s\\n" "--sandbox"; exit 0; fi\nexit 2\n',
    )
    chmodSync(codex, 0o700)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir

    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', bashProbeShell()),
    ).resolves.toBe('unsupported')

    writeFileSync(
      codex,
      '#!/bin/sh\nif [ "$1" = "--help" ]; then printf "%s\\n" "--approve-for-me"; exit 0; fi\nexit 2\n',
    )
    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', bashProbeShell()),
    ).resolves.toBe('supported')
  })

  // openharness#285: opencode 1.14.51 has no `--auto`, prints its help and exits, and the wrapper
  // hands the pane to a shell. A substring match reads `--auto-update` in a newer help as support
  // for `--auto` and launches that very pane.
  it('does not read a longer flag as the one it was asked about', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-boundary-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir

    fakeEngine(binDir, 'opencode', '--auto-update   keep opencode current')
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', bashProbeShell()))
      .resolves.toBe('unsupported')

    fakeEngine(binDir, 'opencode', '--auto   approve automatically')
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', bashProbeShell()))
      .resolves.toBe('supported')
  })

  it('answers a flag that ends the help text', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-tail-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    fakeEngine(binDir, 'cursor-agent', '--force')
    await expect(commandSupportsFlagInInteractiveShell('cursor-agent', '--force', bashProbeShell()))
      .resolves.toBe('supported')
  })

  // Every relaunch asks, and a restore asks once per agent. Only the working answer is remembered:
  // the cure for the other two is to change the engine on disk, and a remembered refusal would
  // outlive the upgrade that fixed it — which is how openharness#285's reporter resolved theirs.
  it('remembers that a flag IS supported, and keeps asking when it is not', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-cache-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    const shell = bashProbeShell()

    fakeEngine(binDir, 'opencode', '--auto')
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
    // Downgraded underneath us where the daemon cannot see the file (only the probe shell's PATH has
    // it): remembered by name alone, the yes stands until the cache is reset.
    fakeEngine(binDir, 'opencode', '--auto-update')
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
    resetCommandFlagSupportCache()
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('unsupported')
    // A refusal is never remembered, so the upgrade is seen at once.
    fakeEngine(binDir, 'opencode', '--auto')
    await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
  })

  // e2e/updates.e2e.ts: remembered by name alone, a yes outlived the update that dropped the flag,
  // and the engine was launched with a flag it refused at once. A yes is kept for the file it was read from.
  it('answers an unchanged engine from memory, and asks again once an update has changed its file', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-update-'))
    dirs.push(binDir)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir
    const savedPath = process.env.PATH
    process.env.PATH = `${binDir}:${savedPath ?? ''}`
    try {
      const shell = bashProbeShell()
      const runs = join(binDir, 'runs')
      const build = (path: string, help: string) => {
        writeFileSync(path, `#!/bin/sh\necho run >> '${runs}'\nif [ "$1" = "--help" ]; then printf "%s\\n" '${help}'; exit 0; fi\nexit 2\n`)
        chmodSync(path, 0o700)
      }
      const asked = () => existsSync(runs) ? readFileSync(runs, 'utf8').split('\n').filter(Boolean).length : 0
      const opencode = join(binDir, 'opencode')

      build(opencode, '--auto')
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
      expect(asked()).toBe(1)
      // Rewritten in place by an update that dropped the flag: asked again, and refused.
      build(opencode, '--auto-update')
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('unsupported')
      expect(asked()).toBe(2)

      // Installed as versions and linked, the way Homebrew and native installs update: the same size,
      // and only the link moves.
      mkdirSync(join(binDir, 'v1')); mkdirSync(join(binDir, 'v2'))
      build(join(binDir, 'v1', 'opencode'), '--auto')
      build(join(binDir, 'v2', 'opencode'), '--nope')
      rmSync(opencode)
      symlinkSync(join(binDir, 'v1', 'opencode'), opencode)
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('supported')
      expect(asked()).toBe(3)
      rmSync(opencode)
      symlinkSync(join(binDir, 'v2', 'opencode'), opencode)
      await expect(commandSupportsFlagInInteractiveShell('opencode', '--auto', shell)).resolves.toBe('unsupported')
      expect(asked()).toBe(4)
    } finally {
      process.env.PATH = savedPath
    }
  })

  // A shell's own failure exits 1 — as zsh's read-only `status` did — and must not read as a missing
  // flag: only the probe's own "not in the help" exit refuses an engine.
  it('does not read a shell failure as a missing flag', async () => {
    const shellDir = mkdtempSync(join(tmpdir(), 'harness-engine-shell-'))
    dirs.push(shellDir)
    const shell = join(shellDir, 'bash')
    writeFileSync(shell, '#!/bin/sh\nexit 1\n')
    chmodSync(shell, 0o700)

    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', shell),
    ).resolves.toBe('unknown')
  })

  it('does not reject a CLI when its help command cannot be inspected', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-capability-'))
    dirs.push(binDir)
    const codex = join(binDir, 'codex')
    writeFileSync(codex, '#!/bin/sh\nexit 2\n')
    chmodSync(codex, 0o700)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir

    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', bashProbeShell()),
    ).resolves.toBe('unknown')
  })

  // zsh makes `status` a read-only alias of `$?`, so a bare `status=$?` in the probe script is a
  // fatal error there: the shell dies with exit 1, which this function reads as `unsupported`.
  // macOS defaults $SHELL to zsh, so that one name turned every Codex Auto launch on a Mac into
  // "your installed Codex CLI does not support --approve-for-me" whatever version was installed.
  it.skipIf(!ZSH)('answers from zsh too, where `status` is a read-only parameter', async () => {
    const binDir = mkdtempSync(join(tmpdir(), 'harness-engine-capability-zsh-'))
    dirs.push(binDir)
    const codex = join(binDir, 'codex')
    writeFileSync(
      codex,
      '#!/bin/sh\nif [ "$1" = "--help" ]; then printf "%s\\n" "--approve-for-me"; exit 0; fi\nexit 2\n',
    )
    chmodSync(codex, 0o700)
    process.env.HARNESS_ENGINE_TEST_PATH = binDir

    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', zshProbeShell()),
    ).resolves.toBe('supported')

    writeFileSync(
      codex,
      '#!/bin/sh\nif [ "$1" = "--help" ]; then printf "%s\\n" "--sandbox"; exit 0; fi\nexit 2\n',
    )
    await expect(
      commandSupportsFlagInInteractiveShell('codex', '--approve-for-me', zshProbeShell()),
    ).resolves.toBe('unsupported')
  })
})

describe('buildEngineLaunchArgv — the grid the pane finds', () => {
  /** A runnable `grid` at `dir/grid`. Which one the pane's shell resolves is the assertion. */
  function gridAt(dir: string): string {
    mkdirSync(dir, { recursive: true })
    return executable(dir, 'grid')
  }

  it('puts the resolved grid first on PATH and turns its update check off, before the engine', () => {
    const managed = '/opt/harness/runtime/grid-0.3.47-darwin-arm64/grid'
    const script = launchScriptOf(buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, managed))

    expect(script).toContain(`PATH='/opt/harness/runtime/grid-0.3.47-darwin-arm64'"\${PATH:+:$PATH}"\nexport PATH\n`)
    expect(script).toContain('GRID_NO_UPDATE_CHECK=1\nexport GRID_NO_UPDATE_CHECK\n')
    expect(script.indexOf('export GRID_NO_UPDATE_CHECK')).toBeLessThan(script.indexOf(RUN_LINE))
  })

  it('leaves PATH alone when grid is only a name on it, but still turns the update check off', () => {
    const script = launchScriptOf(buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, 'grid'))

    expect(script).not.toContain('export PATH')
    expect(script).toContain('GRID_NO_UPDATE_CHECK=1')
  })

  /** What the engine's own `command -v grid` answers, and what it sees in GRID_NO_UPDATE_CHECK.
   *
   *  The pane is the user's login shell, and a `.zshrc` that puts `~/.local/bin` first is ordinary —
   *  which is where grid's own installer (uv, on a Mac) leaves a `grid`. The prelude runs AFTER the
   *  startup files, so that one cannot get ahead of the grid the daemon resolved. `bashProbeShell()`
   *  plays the startup file: it resets PATH to HARNESS_ENGINE_TEST_PATH before the script runs. */
  async function gridSeenByEngine(gridBinary: string): Promise<{ which: string; updateCheck: string }> {
    const [shell, flag, script] = buildEngineLaunchArgv('claude', {}, bashProbeShell(), undefined, gridBinary)
    const { execFile } = await import('node:child_process')
    const out = await new Promise<string>((resolve, reject) => {
      execFile(
        shell,
        [flag, script, 'harness-engine', '/bin/sh', '-c', 'command -v grid; printf "%s" "$GRID_NO_UPDATE_CHECK"'],
        { timeout: 10_000 },
        (error, stdout, stderr) => (error ? reject(new Error(`${error.message}\n${stderr}`)) : resolve(stdout)),
      )
    })
    const [which, updateCheck] = out.split('\n')
    return { which, updateCheck }
  }

  it('wins over a grid the shell\'s own startup files put first on PATH', async () => {
    const root = mkdtempSync(join(tmpdir(), 'harness-pane-grid-'))
    dirs.push(root)
    gridAt(join(root, 'users-own'))
    const managed = gridAt(join(root, 'runtime', 'grid-0.3.47-darwin-arm64'))
    process.env.HARNESS_ENGINE_TEST_PATH = `${join(root, 'users-own')}:/usr/bin:/bin`

    await expect(gridSeenByEngine(managed)).resolves.toEqual({ which: managed, updateCheck: '1' })
  })

  it('leaves the user\'s own grid in charge when the daemon resolved nothing better', async () => {
    const root = mkdtempSync(join(tmpdir(), 'harness-pane-grid-'))
    dirs.push(root)
    const own = gridAt(join(root, 'users-own'))
    process.env.HARNESS_ENGINE_TEST_PATH = `${join(root, 'users-own')}:/usr/bin:/bin`

    await expect(gridSeenByEngine('grid')).resolves.toEqual({ which: own, updateCheck: '1' })
  })
})

describe('buildEngineLaunchArgv with installFirst', () => {
  // Everything here is about ONE rule: the engine must not be exec'd after an install that failed.
  // Doing so reproduces the `command not found` this feature exists to replace, with a screenful of
  // installer output above it to bury the cause.
  const script = (install: string): string =>
    buildEngineLaunchArgv('opencode', { installFirst: install }, '/bin/zsh')[4]

  it('leaves the plain launch alone when nothing has to be installed', () => {
    expect(launchScriptOf(buildEngineLaunchArgv('opencode', {}, '/bin/zsh', undefined, undefined, NO_TMUX))).toBe(`${RAISE_OPEN_FILES_SH}${FALLBACK('opencode', '/bin/zsh')}${GRID_PRELUDE}${BROWSER}${NO_DEVTOOLS}${RUN}`)
  })

  it('keeps the engine argv positional, so the shell never re-parses a path or a flag', () => {
    const argv = buildEngineLaunchArgv('opencode', {
      installFirst: 'npm install -g opencode-ai',
      bypassPermission: true,
    }, '/bin/zsh')
    expect(argv.slice(0, 4)).toEqual(['/usr/bin/env', 'DISABLE_AUTO_UPDATE=true', '/bin/zsh', '-lic'])
    expect(argv.slice(5)).toEqual(['harness-engine', ...buildEngineCommandArgv('opencode', { bypassPermission: true })])
    expect(launchScriptOf(argv)).toContain(RUN_LINE)
  })

  it('runs the engine only when the install succeeded', async () => {
    await expect(runPaneScript(script('true'))).resolves.toMatchObject({ code: 0, ranEngine: true })
  })

  it('does not run the engine when the install returns a failure', async () => {
    const result = await runPaneScript(script('false'))
    expect(result.ranEngine).toBe(false)
    expect(result.code).toBe(1)
    expect(result.stdout).toContain('the install failed')
  })

  it('does not run the engine when the install command is not there at all', async () => {
    const result = await runPaneScript(script('harness-no-such-installer --please'))
    expect(result.ranEngine).toBe(false)
    expect(result.code).toBe(1)
  })

  it('prints the command before running it, so a long install is not a hung pane', () => {
    expect(launchScriptOf(['-c', script('npm install -g opencode-ai')])).toContain('npm install -g opencode-ai')
  })

  it("survives an install line carrying a quote, rather than ending the shell's string", async () => {
    // `curl … | bash` is already in the table; a quoted argument is the next shape to arrive, and an
    // install line is a constant in our own source — so the failure mode is a broken pane, not an
    // injection. It still must not break.
    const result = await runPaneScript(script(`sh -c 'exit 3'`))
    expect(result.ranEngine).toBe(false)
    expect(result.code).toBe(1)
  })
})

describe('buildEngineLaunchArgv with installIfMissing', () => {
  const recipe = (
    command: string,
    executable: EngineInstallRecipe['executable'] = { names: ['harness-no-such-engine'] },
  ): EngineInstallRecipe => ({ command, source: 'test fixture', executable })
  // No Harness Node unless a test names one: these check the plain install, which shows the installer
  // itself. The friendly one, which needs Node for its progress, has its own tests below.
  const script = (install: EngineInstallRecipe, runtimeNode = '/nonexistent/harness-node'): string =>
    buildEngineLaunchArgv('opencode', { installIfMissing: install }, '/bin/zsh', runtimeNode)[4]

  describe('the friendly install: plain lines and a bar on screen, the installer in a log', () => {
    let home = ''
    beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'harness-friendly-install-')); dirs.push(home) })
    const friendly = (install: EngineInstallRecipe, firstPrompt?: string): string =>
      buildEngineLaunchArgv('opencode', { installIfMissing: install, ...(firstPrompt ? { firstPrompt } : {}) }, '/bin/zsh', process.execPath)[4]
    const run = (paneScript: string) => runPaneScript(paneScript, 'harness-no-such-engine', { ...process.env, HOME: home })
    const log = () => readFileSync(join(home, '.harness', 'logs', 'install-opencode.log'), 'utf8')

    it('shows what is happening without the installer, and keeps the installer\'s output in the log', async () => {
      const result = await run(friendly(recipe("printf 'npm notice New major version of npm available!\\n'")))
      expect(result.stdout).toContain('Installing OpenCode…')
      expect(result.stdout).toMatch(/[█░]{24}/)
      expect(result.stdout).not.toContain('npm notice')
      expect(result.stdout).not.toContain('engine is missing')
      expect(result.stdout).not.toContain('Your message goes as soon as it starts.')
      expect(log()).toContain('npm notice New major version of npm available!')
    })

    it('says the first message is waiting when there is one', async () => {
      const result = await run(friendly(recipe('true'), 'make a web page'))
      expect(result.stdout).toContain('Your message goes as soon as it starts.')
    })

    it('a failed install says so, with the last of the log and where the rest is', async () => {
      const result = await run(friendly(recipe("printf 'E404 not found: fixture\\n'; exit 3")))
      expect(result).toMatchObject({ code: 1, ranEngine: false })
      expect(result.stdout).toContain('OpenCode could not be installed.')
      expect(result.stdout).toContain('E404 not found: fixture')
      expect(result.stdout).toContain(`Full details: ${join(home, '.harness', 'logs', 'install-opencode.log')}`)
      expect(result.stdout).not.toContain('The command is above')
    })

    it('runs the engine after an install that put it in place', async () => {
      const dir = mkdtempSync(join(tmpdir(), 'harness-friendly-engine-'))
      dirs.push(dir)
      const source = join(dir, 'source-engine')
      const installed = join(dir, 'new-engine')
      writeFileSync(source, '#!/bin/sh\n/usr/bin/printf "%s" "$1"\n')
      chmodSync(source, 0o700)
      const result = await run(friendly(recipe(`cp ${JSON.stringify(source)} ${JSON.stringify(installed)}`, { names: ['harness-no-such-engine'], absolutePaths: [installed] })))
      expect(result).toMatchObject({ code: 0, ranEngine: true })
      expect(result.stdout).toContain('Installing OpenCode…')
    })
  })

  it('execs an installed engine without running the installer', async () => {
    await expect(runPaneScript(script(recipe('false')))).resolves.toMatchObject({ code: 0, ranEngine: true })
  })

  it('runs the installer inside the pane when the engine is absent', async () => {
    const result = await runPaneScript(script(recipe('false')), 'harness-no-such-engine')
    expect(result.ranEngine).toBe(false)
    expect(result.code).toBe(1)
    expect(result.stdout).toContain('engine is missing')
  })

  it('execs a vendor path after install even when the current PATH did not reload', async () => {
    const dir = mkdtempSync(join(tmpdir(), 'harness-engine-installed-'))
    dirs.push(dir)
    const source = join(dir, 'source-engine')
    const installed = join(dir, 'new-engine')
    writeFileSync(source, '#!/bin/sh\n/usr/bin/printf "%s" "$1"\n')
    chmodSync(source, 0o700)
    const install = `cp ${JSON.stringify(source)} ${JSON.stringify(installed)}`
    const result = await runPaneScript(
      script(recipe(install, { names: ['harness-no-such-engine'], absolutePaths: [installed] })),
      'harness-no-such-engine',
    )
    expect(result).toMatchObject({ code: 0, ranEngine: true })
  })

  it('reports a successful install that did not provide an executable', async () => {
    const result = await runPaneScript(script(recipe('true')), 'harness-no-such-engine')
    expect(result).toMatchObject({ code: 1, ranEngine: false })
    expect(result.stdout).toContain('install completed, but its executable could not be found')
  })

  it('enables npm from the managed Node runtime when the pane PATH has no npm', async () => {
    const runtimeBin = mkdtempSync(join(tmpdir(), 'harness-managed-node-bin-'))
    const emptyPath = mkdtempSync(join(tmpdir(), 'harness-empty-path-'))
    dirs.push(runtimeBin, emptyPath)
    const runtimeNode = executable(runtimeBin, 'node')
    const engineSource = join(runtimeBin, 'engine-source')
    writeFileSync(engineSource, '#!/bin/sh\n/usr/bin/printf "HARNESS-TEST-ENGINE-RAN\\n"\n')
    chmodSync(engineSource, 0o700)
    const installed = join(runtimeBin, 'installed-engine')
    const npm = join(runtimeBin, 'npm')
    writeFileSync(npm, `#!/bin/sh
if [ "$1" = prefix ]; then exit 0; fi
/bin/cp ${JSON.stringify(engineSource)} ${JSON.stringify(installed)}
/bin/chmod 700 ${JSON.stringify(installed)}
`)
    chmodSync(npm, 0o700)

    const result = await runPaneScript(
      script(recipe('npm install -g fixture', {
        names: ['harness-no-such-engine'],
        absolutePaths: [installed],
        npmGlobal: true,
      }), runtimeNode),
      'harness-no-such-engine',
      { PATH: emptyPath },
    )

    expect(result).toMatchObject({ code: 0, ranEngine: true })
    expect(result.stdout).toContain('installing for this user')
  })

  it('does not add the npm bootstrap to non-npm installers', () => {
    expect(launchScriptOf(['-c', script(recipe('true'))])).toContain('engine is missing')
    expect(launchScriptOf(['-c', script(recipe('true'))])).not.toContain('managed Node.js/npm')
  })
})

/** Run one generated pane script under /bin/sh and report what it did. */
async function runPaneScript(
  paneScript: string,
  command = '/usr/bin/printf',
  env: NodeJS.ProcessEnv = process.env,
): Promise<{ code: number; stdout: string; ranEngine: boolean }> {
  const { execFile } = await import('node:child_process')
  const marker = 'HARNESS-TEST-ENGINE-RAN'
  return await new Promise((resolve) => {
    execFile(
      '/bin/sh',
      ['-c', paneScript, 'harness-engine', command, `${marker}\n`],
      { timeout: 10_000, env },
      (error, stdout) => {
        const code = error && typeof (error as { code?: unknown }).code === 'number'
          ? (error as unknown as { code: number }).code
          : 0
        resolve({ code, stdout, ranEngine: stdout.includes(marker) })
      },
    )
  })
}

describe('zsh\'s new-user menu, kept out of an agent\'s pane', () => {
  // Debian, Ubuntu, Fedora and Arch build zsh with its zsh/newuser module: on a terminal, for a person
  // with no .zshenv, .zprofile, .zshrc or .zlogin, it runs a full-screen setup menu before anything else.
  // On the end-to-end suite's first Linux run every zsh agent's pane showed it, and no engine started.
  let root = ''
  let savedDataDir = ''
  beforeEach(() => {
    root = mkdtempSync(join(tmpdir(), 'launch-newuser-'))
    savedDataDir = env.ADAPTER_DATA_DIR
    env.ADAPTER_DATA_DIR = join(root, 'data')
  })
  afterEach(() => {
    env.ADAPTER_DATA_DIR = savedDataDir
    rmSync(root, { recursive: true, force: true })
  })
  const folder = () => join(root, 'data', 'zsh-startup')

  it('points a person with no zsh startup files at a .zshenv of Harness\'s that puts their ZDOTDIR back', () => {
    const home = join(root, 'home')
    mkdirSync(home)
    expect(zshNewUserGuard({ HOME: home })).toEqual([`ZDOTDIR=${folder()}`])
    expect(zshNewUserGuard({ HOME: home, ZDOTDIR: home })).toEqual([`ZDOTDIR=${folder()}`, `HARNESS_ZDOTDIR=${home}`])
    expect(readFileSync(join(folder(), '.zshenv'), 'utf8')).toBe(ZSH_GUARD_ZSHENV)
    expect(statSync(join(folder(), '.zshenv')).mode & 0o777).toBe(0o600)
    // In the launch itself, before the shell and its flags.
    process.env.ZDOTDIR = home
    expect(buildEngineLaunchArgv('claude', {}, '/bin/zsh', undefined, undefined, NO_TMUX).slice(0, 6)).toEqual([
      '/usr/bin/env', 'DISABLE_AUTO_UPDATE=true', `ZDOTDIR=${folder()}`, `HARNESS_ZDOTDIR=${home}`, '/bin/zsh', '-lic',
    ])
  })

  it.each(['.zshenv', '.zprofile', '.zshrc', '.zlogin'])('leaves anyone with a %s exactly as they were', (name) => {
    const home = join(root, 'home')
    mkdirSync(home)
    writeFileSync(join(home, name), '')
    expect(zshNewUserGuard({ HOME: home })).toEqual([])
    expect(zshNewUserGuard({ HOME: join(root, 'elsewhere'), ZDOTDIR: home })).toEqual([])
    expect(existsSync(folder())).toBe(false)
  })

  it('launches as before when it cannot write its .zshenv, or there is no home to look in', () => {
    writeFileSync(join(root, 'data'), 'a file where the data folder should be')
    expect(zshNewUserGuard({ HOME: root })).toEqual([])
    expect(zshNewUserGuard({})).toEqual([])
  })

  // What the .zshenv does, in a real zsh: a person's ZDOTDIR, set or unset, is theirs again before any
  // of their own files is read, and a startup file of theirs that appears later is read from it.
  it.skipIf(!existsSync('/bin/zsh'))('gives a real zsh back the person\'s ZDOTDIR, set or unset, and reads their files from it', () => {
    const home = join(root, 'home')
    mkdirSync(home)
    const run = (environment: NodeJS.ProcessEnv) => {
      const guard = zshNewUserGuard(environment)
      expect(guard).not.toEqual([])
      const out = execFileSync('/usr/bin/env', [...guard, '/bin/zsh', '-lic', 'print -r -- "${ZDOTDIR-unset}|${+HARNESS_ZDOTDIR}|${HARNESS_PROFILE-}"'], {
        encoding: 'utf8', env: { PATH: process.env.PATH, ...environment }, stdio: ['ignore', 'pipe', 'ignore'],
      })
      return out.trim().split('\n').at(-1)
    }
    expect(run({ HOME: home })).toBe('unset|0|')
    expect(run({ HOME: join(root, 'not-here'), ZDOTDIR: home })).toBe(`${home}|0|`)
    // A .zshenv only at the guard's decision: one written after it is still the person's to run.
    const later = join(root, 'later')
    mkdirSync(later)
    const guard = zshNewUserGuard({ HOME: later })
    writeFileSync(join(later, '.zshenv'), 'export HARNESS_PROFILE=theirs\n')
    const out = execFileSync('/usr/bin/env', [...guard, '/bin/zsh', '-lic', 'print -r -- "${ZDOTDIR-unset}|${HARNESS_PROFILE-}"'], {
      encoding: 'utf8', env: { PATH: process.env.PATH, HOME: later }, stdio: ['ignore', 'pipe', 'ignore'],
    })
    expect(out.trim().split('\n').at(-1)).toBe('unset|theirs')
  })

  // The menu itself needs zsh's newuser script (not on macOS) and a terminal, which a pseudo-terminal
  // from python's pty module provides. Without the guard the menu waits for a key and the marker never
  // comes; with it the shell runs the command at once.
  const newuserScript = ['/usr/share/zsh', '/usr/local/share/zsh'].flatMap((base) => {
    try { return readdirSync(base).map((version) => join(base, version, 'scripts', 'newuser')) } catch { return [] }
  }).find((file) => existsSync(file))
  it.skipIf(!existsSync('/bin/zsh') || !newuserScript || !existsSync('/usr/bin/python3'))('runs a new user\'s pane straight to its command, with no setup menu', () => {
    const home = join(root, 'home')
    mkdirSync(home)
    const argv = ['/usr/bin/env', ...zshNewUserGuard({ HOME: home }), '/bin/zsh', '-lic', 'print HARNESS-MARKER; exit']
    const pty = `import os, pty, sys, select, time\npid, fd = pty.fork()\nif pid == 0:\n    os.execvpe(sys.argv[1], sys.argv[1:], os.environ)\nout = b''\nend = time.time() + 8\nwhile time.time() < end and b'HARNESS-MARKER' not in out:\n    r, _, _ = select.select([fd], [], [], 0.2)\n    if r:\n        try: out += os.read(fd, 4096)\n        except OSError: break\nos.kill(pid, 9)\nsys.stdout.write(out.decode('utf8', 'replace'))\n`
    const out = execFileSync('/usr/bin/python3', ['-c', pty, ...argv], {
      encoding: 'utf8', env: { PATH: process.env.PATH, HOME: home, TERM: 'xterm', LINES: '40', COLUMNS: '120' }, timeout: 20_000,
    })
    expect(out).not.toContain('zsh-newuser-install')
    expect(out).toContain('HARNESS-MARKER')
  })
})